GUPC

NAME

gupc - UPC compiler for parallel computers.

SYNOPSIS

gupc [ option | filename]... 

DESCRIPTION

GUPC 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 GUPC compiler is integrated with the GCC compiler. The GUPC compiler processes input files through one or more of four stages: pre-processing, compilation, assembly, and linking.

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

.upc		UPC source; pre-process, compile, assemble
.upci		Preprocessed UPC; compile, assemble
.h		Pre-processor file; not usually named on command line
.c		Files will be compiled as UPC source, unless preceded by "-x c"
.i,.s		Preprocessed C, and assembler source files 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 filenames (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
-fupc-instrument
-fupc-instrument-functions
-x upc

Debugging Options

-g

-dwarf-2-upc
-fupc-debug

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 upcswitch 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

-dwarf-2-upc

Generate UPC-specific symbolic DWARF-2 debugging information. This debugging information is processed by GDB-UPC, a variant of the GDB debugger that is UPC-aware, and the commercially available Totalview debugger, among others.

-fupc-debug

Generate calls to the UPC runtime library that include source filename and line number information that is used to print more informative error messages when errors are detected at runtime.

INSTRUMENTATION OPTIONS

-fupc-instrument

Instrument UPC shared accesses and library calls, using GASP tool support (implies -fno-upc-inline-lib)

-fupc-instrument-functions

Instrument functions calls, using GASP tool support (implies -fupc-instrument and -fno-upc-inline-lib)

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 trade off 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.

[[-fupc-threads-|-n]] [[-fupc-heap-|-heap ][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- or -n command line switch, which establishes the number of parallel execution threads given by the value `'. Generally, `' should not exceed the number of physical central processing units (or cores).

The size of the heap used by the UPC program is established with the specification of the -fupc-heap- command line switch. The value of `' is the size of the heap available to each thread, specified in bytes. A suffix of `K', indicates that the value `' is expressed in kilobytes (2^10 bytes); a suffix of `M' indicates that `' is expressed in megabytes (2^20 bytes); and `G' indicates the value is given in gigabytes (2^30 bytes). If the -fupc-heap- 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, the upc run-time supports the specification of execution and memory affinity for UPC threads. The following options control how threads are scheduled:

-sched-policy [cpu,strict,node,auto]

Controls the scheduling policy for threads. cpuspecifies 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-cpu-avoid n1,n2,..

Controls the availability of CPUs for UPC scheduling. The UPC run-time will not schedule any thread on CPUs specified with this option.

-mem-policy [node,strict,auto]

Controls the memory allocation policy if a NUMA aware kernel is available. node allocates memory first from the node on which a thread is scheduled to run. strict allocates memory only from the node on which a thread is scheduled to run. auto lets the 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             UPC source file (unless preceded by the "-x c" switch)
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 gupc -v
TMPDIR The temporary directory location is given by the environment variable TMPDIR (default /usr/tmp if available, else /tmp).

SEE ALSO

gcc(1), cpp(1), as(1), ld(1), gdb(1).

Introduction to UPC and Language Specification
(http://upc.lbl.gov/publications/UPC-TR-Original99.pdf) William W. Carlson et al., LLNL, CCS-TR-99-157, May 13, 1999

UPC Language Specifications
(http://www.gwu.edu/~upc/docs/upc_specs_1.2.pdf) Tarek A. El-Ghazawi et al, February 25, 2001

GASP Tool Interface
(http://gasp.hcs.ufl.edu/) University of Florida, GASP Tool Interface

The GNU UPC web site
(http://www.gccupc.org)

The GNU UPC Mailing List
(http://www.gwu.edu/~upc/software/gnu-upc-ml.html) is an electronic forum for discussing news announcements, bug reports, planned developments, and other topics of interest to GNU UPC developers and users.

 

BUGS

Report bugs to http://gccupc.org/bugs.

 

AUTHORS

Current developers and maintainers are Gary Funck < This e-mail address is being protected from spambots. You need JavaScript enabled to view it > and Nenad Vukicevic < This e-mail address is being protected from spambots. You need JavaScript enabled to view it >.
Original Implementation by Jesse M. Draper < This e-mail address is being protected from spambots. You need JavaScript enabled to view it > and William W. Carlson < This e-mail address is being protected from spambots. You need JavaScript enabled to view it >.