


bspfront(1)               User Commands               bspfront(1)



NAME
     bspfront - The Oxford BSP  Toolset  compilation  driver  for
     BSPlib


SYNOPSIS
     bspfront [ _o_p_t_i_o_n_s | _f_i_l_e_n_a_m_e_s ]...
     bspf77 [ _o_p_t_i_o_n_s | _f_i_l_e_n_a_m_e_s ]...
     bspcc [ _o_p_t_i_o_n_s | _f_i_l_e_n_a_m_e_s ]...
     bspc++ [ _o_p_t_i_o_n_s | _f_i_l_e_n_a_m_e_s ]...

DESCRIPTION
     Programs written  for  the  bsplib(3)  parallel  programming
     library  should  be  compiled  with  the  compilation driver
     bspfront. The compilation  driver  guides  each  input  file
     through  some  of  the  possible  phases  of  a compilation:
     extracting code from a literate program (see litToPgm(1) and
     litToTex(1) ), compilation, assembly, and linking.

     For each input file, the phase to start with  is  determined
     by the file's suffix:

     .c     C source; preprocess, compile, assemble
     .f     Fortran 77 source; compile, assemble
     .cc    C++ source; preprocess, compile, assemble
     .c++   C++ source; preprocess, compile, assemble
     .lc    Literate C source; unlit, preprocess, compile, assemble
     .lf    Literate  Fortran 77 source; unlit, compile, assemble
     .lcc   Literate  C++ source; unlit, preprocess, compile, assemble
     .lc++  Literate  C++ source; unlit, preprocess, compile, assemble

     Files with other suffixes are passed to the linker.   Common
     cases include:

     .o      Object file
     .a      Archive file

     Linking is always the last stage unless  you  use  the   - c
     option  to  avoid  it (or unless compilation errors stop the
     whole  process).   For  the  link  stage,   all   .o   files
     corresponding  to  source  files, -l libraries, unrecognized
     filenames (including named .o object files and .a  archives)
     are passed to the linker in command-line order.

     bspcc is just an alias  for  bspfront,  whereas  bspc++  and
     bspf77  have the same operational behaviour as bspfront -f77
     and bspfront -c++ respectively.


OPTIONS
     Options must be separate: `-dr' is quite different from `- d
     - r  '.   Any  option  not  recognised by bspfront is passed



Oxford BSP Toolset  Last change: 1.4 25/9/98                    1






bspfront(1)               User Commands               bspfront(1)



     straight through to the underlying compiler.  Here is a sum-
     mary  of  all the options, grouped by type. Explanations can
     be found in the appropriate sections below:


     Overall Options
          -v -c -o _f_i_l_e -cflags _o_p_t_i_o_n_s -f77flags _o_p_t_i_o_n_s -
          c++flags _o_p_t_i_o_n_s -overridecc _c_o_m_m_a_n_d -overridef77
          _c_o_m_m_a_n_d -overridec++ _c_o_m_m_a_n_d -overrideld _c_o_m_m_a_n_d -keep
          -showlog

     Preprocessor Options
          -E -I_d_i_r -D_m_a_c_r_o[=_d_e_f_n] -U_m_a_c_r_o

     Debugging Options
          -g -debug -f[no]check-syncs

     Profiling Options
          -stat -prof -cgprof -nof77munging -f[no]throttle-procs

     General Optimisation Options
          -O -O2 -O3 -flibrary-level _l_e_v_e_l -fcombine-puts-buffer
          _n_u_m_b_e_r,[_n_u_m_b_e_r,[_n_u_m_b_e_r]] -fcontention-resolve _l_e_v_e_l -
          f[no]combine-puts -fcombine-puts-buffer _n_u_m_b_e_r -
          ffixed-bsmp-buffers _n_u_m_b_e_r -finfinite-bsmp-buffers -
          bspbuffer _n_u_m_b_e_r -bspfifo _n_u_m_b_e_r

     Shared Memory Optimisation Options
          -bspbufferstalls _n_u_m_b_e_r -bspnobuffers _n_u_m_b_e_r


     Network Of Workstations (NOW) Optimisation Options
          -bspnobuffers _n_u_m_b_e_r -bspslotsize _n_u_m_b_e_r -bspnoslots
          _n_u_m_b_e_r -bsproundtrip _n_u_m_b_e_r -bspsendlatency _n_u_m_b_e_r


     Process Migration and Fault Tolerance Options
          -f[no]processmigration -fprocessmigration _n_u_m_b_e_r -
          f[no]checkpointing -fcheckpointing _n_u_m_b_e_r

     Linker Options
          -c++ -f77 -mpi -udpip -tcpip -shmemsysv -shmemwin32 -
          l_l_i_b_r_a_r_y -ldflags _f_l_a_g_s -device _d_e_v_i_c_e

     Directory Options
          -L_d_i_r_e_c_t_o_r_y


OVERALL OPTIONS
     -v    Print (on standard error output) the commands executed
          to  run the stages of compilation.  Also print the ver-
          sion number of the compiler  driver  and  the  standard



Oxford BSP Toolset  Last change: 1.4 25/9/98                    2






bspfront(1)               User Commands               bspfront(1)



          compilation options that are set for your platform.

     -c    Suppress the loading  phase  of  the  compilation  and
          force  an  object  file to be produced even if only one
          program is compiled.

     -o _f_i_l_e
          Place output in _f_i_l_e.  This applies regardless to what-
          ever  sort  of output bspfront is producing, whether it
          be an executable or an object file.

     -cflags _o_p_t_i_o_n_s
          Pass _o_p_t_i_o_n_s straight through to the underlying C  com-
          piler.  This  option  is  useful  when an option in the
          underlying C compiler is required, but it clashes  with
          one  of  bspfront's  options.  For example, -_v turns on
          bspfront's verbose mode. If the underlying C  compilers
          verbose  mode is required (which also uses the flag -_v)
          then use -cflags '-v'.

     -f77flags _o_p_t_i_o_n_s
          Pass _o_p_t_i_o_n_s straight through to the underlying Fortran
          77 compiler

     -c++flags _o_p_t_i_o_n_s
          Pass _o_p_t_i_o_n_s straight through  to  the  underlying  C++
          compiler

     -overridecc _c_o_m_m_a_n_d
          Use _c_o_m_m_a_n_d as an alternative C compiler.

     -overridef77 _c_o_m_m_a_n_d
          Use _c_o_m_m_a_n_d as an alternative Fortran 77 compiler.

     -overridec++ _c_o_m_m_a_n_d
          Use _c_o_m_m_a_n_d as an alternative C++ compiler.

     -overrideld _c_o_m_m_a_n_d
          Use _c_o_m_m_a_n_d as an alternative linker.

     -keep
          Any temporary files created by the  compilation  driver
          in _T_M_P_D_I_R are not removed at the end of compilation

     -showlog
          Display a list of users who have been using the  compi-
          lation  driver.  This option is only valid if  bspfront
          has been installed to log usage.

PREPROCESSOR OPTIONS
     -E    Preprocess only the named C files and send the  result
          to  the  standard  output.   The  output  will  contain



Oxford BSP Toolset  Last change: 1.4 25/9/98                    3






bspfront(1)               User Commands               bspfront(1)



          preprocessing directives for use by the  next  pass  of
          the compilation system.

     -I_d_i_r
          Append  directory  _d_i_r  to  the  list  of   directories
          searched for include files.

     -D_m_a_c_r_o
          Define macro _m_a_c_r_o with the string `1' as  its  defini-
          tion.

     -D_m_a_c_r_o=_d_e_f_n
          Define macro _m_a_c_r_o as _d_e_f_n.

     -U_m_a_c_r_o
          Cause any definition of _m_a_c_r_o to be undefined, as if by
          a  #undef  preprocessing directive. If the same name is
          specified for both -D and - U, _m_a_c_r_o  is  not  defined,
          regardless of the order of the options.

DEBUGGING OPTIONS
     -g    Turn on standard Unix debugging.

     -debug
          Turn on the runtime debugging information  in  the  li-
          brary (this will probably be meaningless to people oth-
          er than implementors).

     -f[no]check-syncs
          Check that each superstep encountered during  execution
          is delimited by a bsp_sync(3) at the same textual posi-
          tion in the users code (default is -fcheck-syncs).

PROFILING OPTIONS
     -stat
          Report statistics on the performance of a BSP  program,
          and  the theoretical costs of the collective communica-
          tions. The file _S_T_A_T._b_s_p will be written to the current
          working directory.

     -prof
          Generate BSP profiling  information  suitable  for  the
          analysis  program bspprof(1). The file _P_R_O_F._b_s_p will be
          written to the current working directory.

     -cgprof
          Generate BSP call graph profiling information  suitable
          for   the   analysis  program  bspcgprof(1).  The  file
          _P_R_O_F._b_s_p will  be written to the current working direc-
          tory.  This  option must be used during compilation and
          linking.




Oxford BSP Toolset  Last change: 1.4 25/9/98                    4






bspfront(1)               User Commands               bspfront(1)



     -nof77munging
          Turn off the inlining of filename and line numbers into
          Fortran  77  code.  The information is used by the pro-
          filer, and helps to give useful error messages when us-
          ing the -flibrary-level 0 or -flibrary-level 1 versions
          of the library.

     -f[no]throttle-procs
          When this flag is on, then the number of processes that
          can  concurrently execute the local computation part of
          a superstep is limited to 1, or the number specified by
          the environment variable BSP_THROTTLE_PROCS.

GENERAL OPTIMISATION OPTIONS
     -O -O2 or -O3
          Turn on the appropriate optimisation  packages  in  the
          underlying C, C++, or Fortran 77 compilers.

     -flibrary-level _l_e_v_e_l
          Request the level of sanity checking to be performed by
          the library. The default level is 0.

          0    performs checks  on  registration,  out  of  bound
               DRMA,  and consistent arguments to collective com-
               munications. The communication primitives at  this
               level  of optimisation may not be optimal, but are
               guaranteed  to  be  resource  friendly  (see     -
               flibrary-level _1 below).

          1    is a resource friendly  version  of  the  library.
               This means that if more processes (including other
               users processes) are running on the  machine  than
               processors,  then  the  performance of the library
               doesn't deteriorate.

          2    is an optimised version of the  library  that  has
               been  tuned in such a way that it assumes no other
               major  processes  are  running  on  the   parallel
               machine. When benchmarking, or collecting results,
               use this optimisation level.

     -f[no]combine-puts
          Where possible, combine multiple puts to the same  pro-
          cessor into a single put.

     -fcombine-puts-buffer _n_u_m_b_e_r[,_m_a_x,_m_i_n]
          Each process has buffers of total  size  2*_n_u_m_b_e_r*(P-1)
          for combining puts; where P is the number of processes.
          If the option _m_a_x is specified, then the total size  of
          the  combine buffers across all processors will be _m_a_x;
          and _m_i_n the threashold buffer size where the  optimisa-
          tion is turned off as _m_a_x/_P is smaller than _m_i_n.



Oxford BSP Toolset  Last change: 1.4 25/9/98                    5






bspfront(1)               User Commands               bspfront(1)



     -fcontention-resolve _l_e_v_e_l
          Apply optimisations to automatically eliminate  message
          contention  within  an  algorithm. There are three dif-
          ferent optimisation levels (default level is 1):

          0    no contention elimination

          1    always apply contention elimination.

          2    only  apply  contention  elimination  to  buffered
               transfers.  i.e., don't use contention elimination
               for high-performance puts (bsp_hpput(3))  so  that
               the put can occur asynchronously with computation

     -ffixed-bsmp-buffers _n_u_m_b_e_r
          Use fixed sized system buffers for the Bulk Synchronous
          Message  passing  operations. On some systems (particu-
          larly the Cray T3D),  having  arbitrary  sized  buffers
          denoted  by the -finfinite-bsmp-buffers option incurs a
          large penalty in  barrier synchronisation latency.

     -finfinite-bsmp-buffers
          Use BSMP buffers which dynamically change  in  size  as
          described in the BSPlib proposal.

     -bspbuffer _n_u_m_b_e_r
          Sets the packet size for outgoing messages.  If  _n_u_m_b_e_r
          ends in a 'K', then the size is in kilobytes; otherwise
          the size is assumed to be bytes (see the  results  from
          the  -prof option for optimal buffer sizes for particu-
          lar codes). On some systems, this value is fixed by the
          implementation.

     -bspfifo _n_u_m_b_e_r
          In this implementation of BSPlib, all puts and gets are
          delayed  until  the  end  of the superstep. This option
          sets the initial size of an internal  FIFO  queue  that
          holds  all delayed communications. If more puts are is-
          sued during a superstep, then the FIFO is  extended  in
          _n_u_m_b_e_r  sized  increments.  On some systems, a seperate
          FIFO is used to hold all the gets, and this can not  be
          extended  during  runtime. This queue will only need to
          be increased if a runtime overflow is raised.

SHARED MEMORY OPTIMISATION OPTIONS
     -bspnobuffers _n_u_m_b_e_r
          Each process has a number of incoming buffers associat-
          ed  with  it. The BSPlib communication occurs in a mes-
          sage passing style through these shared memory buffers.
          The  more  buffers there are, then there is more chance
          that the sending process will be able to send a message
          to  the  destination  prcocess.  However,  if  too many



Oxford BSP Toolset  Last change: 1.4 25/9/98                    6






bspfront(1)               User Commands               bspfront(1)



          buffers are allocated, then the receiving  process  may
          spend  too long servicing buffers which are empty. This
          option sets the number of incoming  buffers  associated
          with each process.

     -bspbufferstalls _n_u_m_b_e_r
          The number of incoming  buffers  specified  by  the   -
          _b_s_p_n_o_b_u_f_f_e_r_s  option  are  serviced  in  a  round-robin
          fashion. After _n_u_m_b_e_r stalls (i.e., nothing  came  in),
          then  data  is  attempted  to  be sent out in a similar
          manner. i.e., _n_u_m_b_e_r attempts are made to send packets.

NETWORK OF WORKSTATIONS (NOW) OPTIMISATION OPTIONS
     -bspslotsize _v_a_r_e_p_s_i_l_o_n
          In BSPlib, the mechanism of pacing the transport  layer
          is  achieved  by  using  a  form  of  statistical time-
          division multiplexing that works as follows. The  frame
          size   (-_b_s_p_b_u_f_f_e_r)   and   the  number  of  processors
          (_b_s_p__n_p_r_o_c_s()) involved in the communication are known.
          As the processors' clocks are not necessarily synchron-
          ised, it is not possible to allow the processors access
          in  accordance  with  some permutation, a technique ap-
          plied successfully in  more  tightly-coupled  architec-
          tures.  Thus the processors choose a slot, _q, uniformly
          at random in the interval [_0..._Q-_1]  (where  _Q  is  the
          number of processors communicating at the end of a par-
          ticular superstep), and schedule their transmission for
          this  slot. The choice of a random slot is important if
          the clocks are not synchronised as it ensures that  the
          processors do not repeatedly choose a bad communication
          schedule.  Each processor waits for time _q * _v_a_r_e_p_s_i_l_o_n
          microseconds after the start of the cycle, where _v_a_r_e_p_-
          _s_i_l_o_n _i_s _a _s_l_o_t time, before passing another packet  to
          the  transport  layer. The length of the slot, _v_a_r_e_p_s_i_-
          _l_o_n, is chosen based on the maximum time that the  slot
          can  occupy the physical medium, and takes into account
          collisions that might occur when good throughput is be-
          ing  achieved.  The  mechanism is designed to allow the
          medium to operate at the steady state that  achieves  a
          high  throughput. Since the burstiness of communication
          has been smoothed by this slotting protocol, the errat-
          ic  behaviour of the low-level protocol is avoided, and
          a high utilisation of the medium is ensured.


     -bspnoslots _n_u_m_b_e_r
          This option specifies the number of time slots required
          for  _b_s_p__n_p_r_o_c_s()  processors to simultaneiously send a
          message to another process. For a  shared  bus  or  re-
          peater then _n_u_m_b_e_r should be equal to _b_s_p__n_p_r_o_c_s(). For
          a switch with full duplex links and a back plane  capa-
          city  that  is the sum of the capacities of each of the



Oxford BSP Toolset  Last change: 1.4 25/9/98                    7






bspfront(1)               User Commands               bspfront(1)



          links, then _n_u_m_b_e_r should be set to one.


     -bsproundtrip _n_u_m_b_e_r
          _n_u_m_b_e_r is the round trip delay time,  in  microseconds,
          of a message that contains no payload.


     -bspsendlatency _n_u_m_b_e_r
          In the steady state where a process emits a  stream  of
          empty  packets  into  the  network,  then _n_u_m_b_e_r is the
          time, in microseconds, at which packets can be emitted.
          As  it  is  usually faster to emit packets than receive
          them, then this time will probably equate to the upload
          rate  of  a  packet,  as  a  steady  state  can only be
          achieved when processes are sending and receiving pack-
          ets  at  the same rate. The parameter should be used to
          throttle a fast sender so that it emits  packets  at  a
          rate at which the receiver can safely upload them.

PROCESS MIGRATION AND FAULT TOLERANCE OPTIONS
     -fcheckpointing _n_u_m_b_e_r
          In the NOW implementation of the library, all processes
          checkpoint  themselves  every _n_u_m_b_e_r seconds. After the
          process has checkpointed itself, it continues to run on
          the  same  processor  (see  -_f_p_r_o_c_e_s_s_m_i_g_r_a_t_i_o_n). If the
          process is interupted, then the program can be restart-
          ed  at  the last checkpoint by passing the -_r_e_s_t_a_r_t op-
          tion to _b_s_p_r_u_n(_1), when the program is re-run.


     -fnocheckpointing
          Turn off checkpointing. This is equivalent to - _f_c_h_e_c_k_-
          _p_o_i_n_t_i_n_g _0 .


     -fprocessmigration _n_u_m_b_e_r
          This option is similar to -_f_c_h_e_c_k_p_o_i_n_t_i_n_g. On entry  to
          a  _b_s_p__s_y_n_c(_3)  if _n_u_m_b_e_r seconds has elapsed since the
          last time process migration occured, then all  the  BSP
          processes determine if process migration is applicable.
          This is done by contacting the load  daemon  _b_s_p_l_o_a_d(_3)
          to  see  if  there are any processors with a load lower
          than any processor that has a bsp job  running  on  it,
          minus  one.  If  a  less  loaded  process is found, all
          processes checkpoint themselves, stop, and then restart
          on the _p least loaded processors.

LINKER OPTIONS
     These options come into play when the compiler links  object
     files  into an executable output file.  They are meaningless
     if the compiler is not doing a link step.



Oxford BSP Toolset  Last change: 1.4 25/9/98                    8






bspfront(1)               User Commands               bspfront(1)



     _o_b_j_e_c_t-_f_i_l_e-_n_a_m_e
          A file name that does not end in a  special  recognized
          suffix is considered to name an object file or library.
          (Object files are distinguished from libraries  by  the
          linker  according to the file contents.)  If GCC does a
          link step, these object files are used as input to  the
          linker.


     -device _d_e_v_i_c_e
          Determine which communication device should be used for
          BSPlib programs. The default device is speficied by the
          command bsparch -device .  The _d_e_v_i_c_e option has to  be
          a  valid  BSPlib  device (see the help bsparch -help ),
          and that device has to be installed.


     -_m_p_i Shorthand for the option -device _M_P_A_S_S__M_P_I.


     -_u_d_p_i_p
          Shorthand for the option -device _M_P_A_S_S__U_D_P_I_P.


     -_t_c_p_i_p
          Shorthand for the option -device _M_P_A_S_S__T_C_P_I_P.


     -_s_h_m_e_m_s_y_s_v
          Shorthand for the option -device _S_H_M_E_M__S_Y_S_V.



     -l_l_i_b_r_a_r_y
          Use the library named _l_i_b_r_a_r_y when linking.

          The linker searches a standard list of directories  for
          the   library,   which   is   actually   a  file  named
          `lib_l_i_b_r_a_r_y.a'.  The linker then uses this file  as  if
          it had been specified precisely by name.

          The directories searched include several standard  sys-
          tem directories plus any that you specify with `-L'.

          Normally the files found this way are  library  files -
          archive  files  whose  members  are  object files.  The
          linker handles an archive file by scanning  through  it
          for  members which define symbols that have so far been
          referenced but not defined.   However,  if  the  linker
          finds  an  ordinary  object file rather than a library,
          the object file is linked in the  usual  fashion.   The
          only difference between using an `-l' option and speci-



Oxford BSP Toolset  Last change: 1.4 25/9/98                    9






bspfront(1)               User Commands               bspfront(1)



          fying a file name is that `-l' surrounds  _l_i_b_r_a_r_y  with
          `lib' and `.a' and searches several directories.

     -c++  The C compiler is  the  default  linker.  This  option
          changes the linker to the C++ compiler.

     -f77  Use the Fortran 77 compiler as the linker.   - ldflags
          _f_l_a_g_s Pass _f_l_a_g_s straight through to the linker.

DIRECTORY OPTIONS
     These options  specify  directories  to  search  for  header
     files, for libraries and for parts of the compiler:

     -I_d_i_r
          Append  directory  _d_i_r  to  the  list  of   directories
          searched for include files.

FILES
     file.c                         C source file
     file.h                         C header (preprocessor) file
     file.f                         Fortran 77 file
     file.cc                        C++ source file
     file.lc++                      Literate C++ source file
     file.lc                        Literate C source file
     file.lh                        Literate C header (preprocessor) file
     file.lf                        Literate Fortran 77 file
     file.lcc                       Literate C++ source file
     file.lc++                      Literate C++ source file
     file.s                         assembly language file
     file.o                         object file
     a.out                          link edited output
     _T_M_P_D_I_R/bspfront*               temporary files
     _T_M_P_D_I_R/bspfront_*_preload.c    start-up routine
     _P_R_E_F_I_X/lib/_m_a_c_h/libbspcore*.a  BSPlib subroutine library
     _P_R_E_F_I_X/include                 BSPlib include files

     _P_R_E_F_I_X is  the  installation  prefix  set  when  configuring
     BSPlib.
     _T_M_P_D_I_R comes from the environment variable  TMPDIR  (default
     /usr/tmp if available, else /tmp).


SEE ALSO
     bsplib(3), bspprof(1), bsparch(1)

     ``_B_S_P_l_i_b: _T_h_e _B_S_P _P_r_o_g_r_a_m_m_i_n_g _L_i_b_r_a_r_y'' Jonathan M. D. Hill,
     Bill  McColl,  Dan  C.  Stefanescu,  Mark W. Goudreau, Kevin
     Lang, Satish B. Rao, , Torsten Suel, Thanasis Tsantilas, and
     Rob  Bisseling.  Parallel  Computing,  to  appear  1998. See
     _h_t_t_p://_w_w_w._b_s_p-_w_o_r_l_d_w_i_d_e._o_r_g for more details.





Oxford BSP Toolset  Last change: 1.4 25/9/98                   10






bspfront(1)               User Commands               bspfront(1)



     The Oxford BSP toolset web pages can be found  at:
     _h_t_t_p://_w_w_w._b_s_p-_w_o_r_l_d_w_i_d_e._o_r_g/_i_m_p_l_m_n_t_s/_o_x_t_o_o_l/


BUGS
     Problems  and  bug  reports  should  be  mailed  to  _b_s_p_l_i_b-
     _b_u_g_s@_c_o_m_l_a_b._o_x._a_c._u_k


COPYING
     Copyright 1995,1996,1997,1998 University of Oxford

     Permission  to  use,  copy,  modify,  and  distribute   this
     software,  and  to incorporate it, in whole or in part, into
     other software, is  hereby  granted  without  fee,  provided
     that:

     i    the above copyright notice and this  permission  notice
          appear  in all copies of the source code, and the above
          copyright notice appear in clearly visible form on  all
          supporting documentation   and distribution media;

     ii    modified versions of this software be accompanied by a
          complete  change  history  describing author, date, and
          modifications made;


     iii   and any redistribution of the software, in original or
          modified form, be without fee and subject to these same
          conditions.

AUTHORS
     Jonathan.Hill@comlab.ox.ac.uk

     http://www.comlab.ox.ac.uk/oucl/people/jonathan.hill.html




















Oxford BSP Toolset  Last change: 1.4 25/9/98                   11



