bspfront(1)

NAME
bspfront - The Oxford BSP Toolset compilation driver for BSPlib

SYNOPSIS
bspfront [ options | filenames ]...
bspf77 [ options | filenames ]...
bspcc [ options | filenames ]...
bspc++ [ options | filenames ]...

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 straight through to the underlying compiler. Here is a summary of all the options, grouped by type. Explanations can be found in the appropriate sections below:

Overall Options
    -v -c -o file -cflags options -f77flags options -c++flags options -overridecc command -overridef77 command -overridec++ command -overrideld command -keep -showlog

Preprocessor Options
    -E -Idir -Dmacro[=defn] -Umacro

Debugging Options
    -g -debug -fcheck-syncs

Profiling Options
    -stat -prof -cgprof -nof77munging -fthrottle-procs

General Optimisation Options
    -O -O2 -O3 -flibrary-level level -fcombine-puts-buffer number,[number,[number]] -fcontention-resolve level -fcombine-puts -fcombine-puts-buffer number -ffixed-bsmp-buffers number -finfinite-bsmp-buffers -bspbuffer number -bspfifo number

Shared Memory Optimisation Options
    -bspbufferstalls number -bspnobuffers number

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

Process Migration and Fault Tolerance Options
    -fprocessmigration -fprocessmigration number -fcheckpointing -fcheckpointing number

Linker Options
    -c++ -f77 -mpi -udpip -tcpip -shmemsysv -shmemwin32 -llibrary -ldflags flags -device device

Directory Options
    -Ldirectory

OVERALL OPTIONS

-v  Print (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver and the standard 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 file
    Place output in file . This applies regardless to whatever sort of output bspfront is producing, whether it be an executable or an object file.

-cflags options
    Pass options straight through to the underlying C compiler. 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 options
    Pass options straight through to the underlying Fortran 77 compiler

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

-overridecc command
    Use command as an alternative C compiler.

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

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

-overrideld command
    Use command as an alternative linker.

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

-showlog
    Display a list of users who have been using the compilation 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 preprocessing directives for use by the next pass of the compilation system.

-Idir
    Append directory dir to the list of directories searched for include files.

-Dmacro
    Define macro macro with the string `1 ' as its definition.

-Dmacro=defn
    Define macro macro as defn .

-Umacro
    Cause any definition of macro to be undefined, as if by a #undef preprocessing directive. If the same name is specified for both -D and - U, macro 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 library (this will probably be meaningless to people other than implementors).

-fcheck-syncs
    Check that each superstep encountered during execution is delimited by a bsp_sync(3) at the same textual position 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 communications. The file STAT.bsp will be written to the current working directory.

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

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

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

-fthrottle-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 level
    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 communications. 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.

-fcombine-puts
    Where possible, combine multiple puts to the same processor into a single put.

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

-fcontention-resolve level
    Apply optimisations to automatically eliminate message contention within an algorithm. There are three different 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 number
    Use fixed sized system buffers for the Bulk Synchronous Message passing operations. On some systems (particularly 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 number
    Sets the packet size for outgoing messages. If number 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 particular codes). On some systems, this value is fixed by the implementation.

-bspfifo number
    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 issued during a superstep, then the FIFO is extended in number 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 number
    Each process has a number of incoming buffers associated with it. The BSPlib communication occurs in a message 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 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 number
    The number of incoming buffers specified by the -bspnobuffers option are serviced in a round-robin fashion. After number stalls (i.e., nothing came in), then data is attempted to be sent out in a similar manner. i.e., number attempts are made to send packets.

NETWORK OF WORKSTATIONS (NOW) OPTIMISATION OPTIONS

-bspslotsize varepsilon
    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 (-bspbuffer ) and the number of processors (bsp_nprocs() ) involved in the communication are known. As the processors' clocks are not necessarily synchronised, it is not possible to allow the processors access in accordance with some permutation, a technique applied successfully in more tightly-coupled architectures. 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 particular 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 * varepsilon microseconds after the start of the cycle, where varepsilon is a slot time, before passing another packet to the transport layer. The length of the slot, varepsilon , 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 being 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 erratic behaviour of the low-level protocol is avoided, and a high utilisation of the medium is ensured.

-bspnoslots number
    This option specifies the number of time slots required for bsp_nprocs() processors to simultaneiously send a message to another process. For a shared bus or repeater then number should be equal to bsp_nprocs() . For a switch with full duplex links and a back plane capacity that is the sum of the capacities of each of the links, then number should be set to one.

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

-bspsendlatency number
    In the steady state where a process emits a stream of empty packets into the network, then number 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 packets 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 number
    In the NOW implementation of the library, all processes checkpoint themselves every number seconds. After the process has checkpointed itself, it continues to run on the same processor (see -fprocessmigration ). If the process is interupted, then the program can be restarted at the last checkpoint by passing the -restart option to bsprun(1) , when the program is re-run.

-fnocheckpointing
    Turn off checkpointing. This is equivalent to -fcheckpointing 0 .

-fprocessmigration number
    This option is similar to -fcheckpointing . On entry to a bsp_sync(3) if number 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 bspload(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.

object-file-name
    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 device
    Determine which communication device should be used for BSPlib programs. The default device is speficied by the command bsparch -device . The device option has to be a valid BSPlib device (see the help bsparch -help ), and that device has to be installed.

-mpi
    Shorthand for the option -device MPASS_MPI .

-udpip
    Shorthand for the option -device MPASS_UDPIP .

-tcpip
    Shorthand for the option -device MPASS_TCPIP .

-shmemsysv
    Shorthand for the option -device SHMEM_SYSV .

-llibrary
    Use the library named library when linking.

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

    The directories searched include several standard system 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 specifying a file name is that `-l ' surrounds library 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 flags Pass flags straight through to the linker.

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

-Idir
    Append directory dir to the list of directories searched for include files.

-Ldir
    Append directory dir to the list of directories searched for libraries.

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
TMPDIR/bspfront*	temporary files
TMPDIR/bspfront_*_preload.c	start-up routine
PREFIX/lib/mach/libbspcore*.a	BSPlib subroutine library
PREFIX/include	BSPlib include files

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

SEE ALSO
bsplib(3), bspprof(1), bsparch(1) ``BSPlib: The BSP Programming Library'' 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 http://www.bsp-worldwide.org for more details. The Oxford BSP toolset web pages can be found at:
http://www.bsp-worldwide.org/implmnts/oxtool/

BUGS
Problems and bug reports should be mailed to bsplib-bugs@comlab.ox.ac.uk

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