intrepid.com

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

Create library cals instead of in-line access for shared data.

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> [UPC options] [program-specific-arguments and switches]

The following UPC options are available:

-fupc-threads-N
-n N

Number of UPC threads (N) for execution
If the UPC program was not compiled with the -fupc-threads-N 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-N command line switch, and establishes the number of parallel execution threads given by the value `N'. Generally, `N' should not exceed the number of physical central processing units. The implementation-imposed maximum value of `N' is 256.

-fupc-heap-N[K|M|G]
-heap N[K|M|G]

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

--

Last UPC switch divider. Use this switch if any of the program's switches is the same as the above defined UPC switches

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).  

SEE ALSO

gcc(1), cpp(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1).

Introduction to UPC and Language Specification, William W. Carlson et al., LLNL, CCS-TR-99-157, May 13, 1999

UPC Language Specifications Tarek A. El-Ghazawi et al, February 25, 2001

The GCC UPC Mailing List is an electronic forum for discussing news announcements, bug reports, planned developments, and other topics of interest to GCC UPC developers and users.  

BUGS

Report bugs to gcc-upc@hermes.gwu.edu.  

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 and Nenad Vukicevic of Intrepid Technology.