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 sum-
mary 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 -f[no]check-syncs
Profiling Options
-stat -prof -cgprof -nof77munging -f[no]throttle-procs
General Optimisation Options
-O -O2 -O3 -flibrary-level level -fcombine-puts-buffer
number,[number,[number]] -fcontention-resolve level -
f[no]combine-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
-f[no]processmigration -fprocessmigration number -
f[no]checkpointing -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 ver-
sion 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 what-
ever 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 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 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 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
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 defini-
tion.
-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 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 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 direc-
tory. 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 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 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 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 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 optimisa-
tion 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 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 number
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 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 particu-
lar 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 is-
sued 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 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
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 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 * varepsilon
microseconds after the start of the cycle, where varep-
silon is a slot time, before passing another packet to
the transport layer. The length of the slot, varepsi-
lon, 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 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 re-
peater then number should be equal to bsp_nprocs(). For
a switch with full duplex links and a back plane capa-
city 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 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 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 restart-
ed at the last checkpoint by passing the -restart op-
tion to bsprun(1), when the program is re-run.
-fnocheckpointing
Turn off checkpointing. This is equivalent to - fcheck-
pointing 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
`liblibrary.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-
fying 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
Man(1) output converted with
man2html