GCC UPC Compiler, man page

Posted on Mon, 2006-03-20 16:40

NAME

upc - UPC compiler for parallel computers.

SYNOPSIS

upc [ option | filename ]...

DESCRIPTION

UPC is an extension to the GNU C compiler from the Free Software Foundation. In addition to the options specified here, all of the normal GCC options listed in the man pages for gcc(1) are available. The UPC compiler is integrated with the GCC compiler. UPC processes input files through one or more of four stages: preprocessing, compilation, assembly, and linking.

Suffixes of source file names indicate the language and kind of processing to be done:

.upc	UPC source; preprocess, compile, assemble
.upci	Preprocessed UPC; compile, assemble
.h	Preprocessor file; not usually named on command line
.c,.i,.s	C, preprocessed C, and assembler source files, and are processed by the C compiler and assembler. The resulting object files can be linked with UPC source code.

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 one of the -c, -S, or -E options to avoid linking (or unless compilation errors stop the whole process). For the link stage, all .o files corresponding to source files, -l libraries, unrecognized file names (including named .o object files and .a archives) are passed to the linker in command-line order.

OPTIONS

Here is a summary of all the UPC-specific options.

Information Options: -v

Language Options: -fupc-threads-n
-fupc-pthreads-model-tls
-fupc-inline-lib
-x upc

Debugging Options: -g

Optimization Options: -O1, -O2, -O3

INFORMATION OPTIONS

-v: Identifies the version of UPC currently in use, with a path name to a specification file that is in the same directory as include directories and other version-specific directories and files. Can be invoked without a source file name. When invoked with files, gives include and library directory paths in the order that they are searched.

LANGUAGE OPTIONS

All source files ending in .upc or .upci will be compiled by the UPC compiler. The -x upc switch tells the compiler to process all of the following file names as UPC source code, ignoring the default language typically associated with filename extensions.

-fupc-threads-n: Compile for n threads. The special symbol THREADS will be set to n and can be used both in data declarations (as a constant for array dimensions) and in expressions. On each thread the special symbol MYTHREAD refers to the thread number.
-fupc-pthreads-model-tls: Compile for POSIX threads (pthreads) environment. Each UPC thread is directly mapped to one pthread.
-fupc-inline-lib: Inline UPC run-time library calls. This option is turned on by default and -fno-upc-inline-lib option must be specified to turn it off. In general, inlining of the run-time library calls produces larger code and needs to be turned off if more condensed code is required.

DEBUGGING OPTIONS

-g: Produce symbolic debugging information

OPTIMIZATION OPTIONS

-O2: This optimization level is one of GCC's standard options. It is especially important for UPC because it enables instruction scheduling, which increases performance dramatically for distributed data access. Nearly all supported optimizations that do not involve a space-speed tradeoff are performed. Loop unrolling and function inlining are not done, for example.

EXECUTION (RUNTIME) OPTIONS

The number of THREADS in an UPC application can be specified statically at compile-time, or dynamically at execution time. In the static compilation environment THREADS is a constant, and can be used freely in contexts where a constant is required by the C language specification (for example in an array declaration). In a dynamic compilation environment, the value of THREADS is given at runtime, and THREADS can be used in array declarations only if the array is qualified as shared and in contexts where one and only one of the shared array's dimensions is specified as an integral multiple of THREADS.

<UPC_program> [[-fupc-threads-|-n]<nthreads>] [[-fupc-heap-|-heap ]<heapsize>[K|M|G]] [upc affinity options] [program-specific-arguments and switches]

If the UPC program was not compiled with the -fupc-threads- option, then the number of THREADS must be specified explicitly on the command line when the program is executed. The UPC runtime recognizes the -fupc-threads-<nthreads> or -n<nthreads> command line switch, and establishes the number of parallel execution threads given by the value `<nthreads>'. Generally, `<nthreads>' should not exceed the number of physical central processing units.

The size of the heap used by the UPC program is established with the specificaion of the -fupc-heap-<heapsize> command line switch. The value of `<heapsize>' is the size of the heap available to each thread, specified in bytes. A suffix of `K', indicates that the value `<heapsize>' is expressed in kilobytes (2^10 bytes); a suffix of `M' indicates that `<heapsize>' is expressed in megabytes (2^20 bytes); and `G' indicates the value is given in gigabytes (2^30 bytes). If the -fupc-heap-<heapsize> switch is not supplied, then the runtime system will choose a default heap size of 16 megabytes per thread.

As of version 4.2.3, upc run-time supports execution and memory affinity of UPC threads. The following options control how threads are scheduled:

sched-policy [cpu,strict,node,auto]: Controls the scheduling policy for threads. cpu specifies that threads are evenly scheduled over available CPUs (single processor or a core unit in multicore processor). strict is similar to cpu scheduling except that one to one mapping of threads and CPUs is required. node specifies that threads are scheduled on nodes if NUMA aware kernel is available. auto specifies that UPC run-time should not manage scheduling of UPC threads.
sched-policy [cpu,strict,node,auto]: Controls the availability of CPUs for UPC scheduling. UPC run-time will not schedule any thread on CPUs specified with this option.
mem-policy [node,strict,auto]: Controls the threads' memory allocation policy if NUMA aware kernel is available. -I node allocates memory first from the node on which thread is scheduled to run. -I strict allocates memory only from the node on which thread is scheduled to run. -I auto lets kernel decide the best memory allocation policy.

The UPC runtime will remove all switches that begin with the prefix -fupc- and that immediately follow the UPC program name on the command line, before calling the UPC program's `main()' routine.

FILES

file.upc	UPC source file
file.upci	preprocessed UPC source file
file.c	C source file
file.h	C header (preprocessor) file
file.i	preprocessed C source file
file.s	assembly language file
file.o	object file
a.out	link edited output
TMPDIR/cc*	temporary files
LIBDIR/cpp	preprocessor
LIBDIR/cc1upc	compiler for UPC
LIBDIR/cc1	compiler for C
LIBDIR/collect2	linker front end needed on some machines
LIBDIR/libupc.a	UPC runtime library
LIBDIR/libgcc.a	GCC subroutine library
/lib/crt[01n].o	start-up routine
/lib/libc.a	standard C library, see intro(3)
/usr/include	standard directory for #include files
LIBDIR/include	standard gcc directory for #include files

LIBDIR should be found by using upc -v
TMPDIR comes from the environment variable TMPDIR (default /usr/tmp if available, else /tmp).

BUGS

Report bugs to upc@intrepid.com .

AUTHORS

Original Implementation by Jesse M. Draper and William W. Carlson.
Ported to SGI Irix 6.5 and the gcc 2.95.2 baseline by Gary Funck <g a r y a t i n t r e p i d d o t c o m> and Nenad Vukicevic <n e n a d a t i n t r e p i d d o t c o m>.

intrepid.com

upc documentation

upc resources