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
-fupc-instrument
-fupc-instrument-functions - -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 file name 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
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-
The size of the heap used by the UPC program is established with the specification of the -fupc-heap-
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 run-time 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 run-time 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
(http://projects.seas.gwu.edu/~hpcl/upcdev/upctr.pdf) William W. Carlson et al., LLNL, CCS-TR-99-157, May 13, 1999
UPC Language Specifications
(ftp://ftp.seas.gwu.edu/pub/upc/downloads/upc_specs.pdf) Tarek A. El-Ghazawi et al, February 25, 2001
The GCC 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 GCC UPC developers and users.
BUGS
Report bugs to This e-mail address is being protected from spambots. You need JavaScript enabled to view it .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
