Gupc - GNU project UPC compiler
1.1 Introduction to gupc
gupc is an extension to the GNU Compiler Collection from the Free Software Foundation. In addition to the options specified here, all of the normal options listed in the man pages for gcc 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:
- file
.upc - UPC source; pre-process, compile, assemble
- file
.upci - Pre-processed UPC source; compile, assemble
- file
.h - Pre-processor header file; not usually named on command line
- file
.c - Files will be compiled as UPC source, unless preceded by -x c
- file
.i - Pre-processed source code; compile, assemble
- file
.s - Assembler source files; assemble
Files with other suffixes are passed to the linker. Common cases include:
- file
.o - Object file
- file
.a - Archive file
Linking is always the last stage unless you use one of the -c, -S, or -E options to avoid linking. Compilation errors also stop the process, and the linker is not invoked. For the link stage, all .o files correspond to source files, and all -l options correspond to libraries. Named .o object files, .a archives, and any file names unrecognized by gupc are passed to the linker in command-line order.
1.2 Number of Threads
Within a UPC program, the special symbol THREADS refers to the number of parallel execution threads. On each thread, the special symbol MYTHREAD refers to the thread number. The number of threads in a UPC application can be specified statically at compile-time or dynamically at execution time. Generally, the number of threads should not exceed the number of physical central processing units or cores.
If the number of threads is specified statically at compile-time, the special symbol THREADS is a constant and can be used freely in any context where a constant is required by the C language specification (for example, in array dimensions in an array declaration). See the -fupc-threads-N compilation option.
If the number of threads is specified dynamically at execution time, the special symbol THREADS is assigned at run-time, and THREADS can be used in array declarations only if the array is qualified as sharedand only if one and only one of the shared array's dimensions is specified as an integral multiple of THREADS. See the -fupc-threads-N execution option.
1.3 Invoking gupc
gupc [ options ] files
1.4 gupc Options
gupc accepts the following UPC-specific options:
1.4.1 Information Options
-v- Print (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver program and of the preprocessor and the compiler proper.
1.4.2 Language Options
-x upc- All source files ending in .upc, .c, or .upci will be compiled by the gupc compiler. The -x upc option tells the compiler to process all of the following file names as UPC source code, ignoring the default language typically associated with filename extensions.
-n N-fupc-threads-N- Specify the number of threads at compile-time as N . See the Number of Threads section, above.
-fupc-pthreads-model-tls- Compile for the 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 when compiled with optimization and the -fno-upc-inline-lib option must be specified to turn it off. In general, inlining of run-time library calls produces larger code. Turn it off if more condensed code is required.
1.4.3 Debugging Options
-g- Produce symbolic debugging information
-dwarf-2-upc- Generate UPC-specific symbolic DWARF-2 debugging information. This debugging information is processed by UPC-aware debuggers including GDB-UPC, a variant of the GDB debugger, and the commercially available Totalview debugger.
-fupc-debug- Generate calls to the UPC run-time library that include source filename and line number information that is used to print more informative error messages when errors are detected at run-time.
1.4.4 Instrumentation Options
--inst-fupc-instrument- Instrument UPC shared accesses and library calls using GASP tool support. This option implies -fno-upc-inline-lib.
--inst-functions-fupc-instrument-functions- Instrument functions calls using GASP tool support. This option implies -fupc-instrument and -fno-upc-inline-lib.
1.4.5 Optimization Options
-O0, -O1, -O2, -O3- Specify the optimization level. Nearly all GCC supported optimizations are performed.
1.4.6 Execution (Run-time) Options
This section describes options that are specified on the command line when you invoke a UPC program. These options are recognized by the UPC run-time. Before calling the main() function of a UPC program, the UPC run-time removes all options that begin with the prefix -fupc- and that immediately follow the UPC program name on the command line.
UPC_program [ number of threads ] [ heap size ] [ affinity options ] [ program arguments ]
-n N-fupc-threads-N- Specifies, at run-time, the number of parallel execution threads as N. If the UPC program was not compiled with the -fupc-threads-N option, either the -fupc-threads-N or -n N command-line option is required when you invoke the UPC program. See the Number of Threads section, above.
-fupc-heap-HEAPSIZE- Specifies the size of the heap available to each thread as HEAPSIZE . A suffix of K indicates that HEAPSIZE is expressed in kilobytes (2^10 bytes). A suffix of M indicates that HEAPSIZE is expressed in megabytes (2^20 bytes). A suffix of G indicates that HEAPSIZE is expressed in gigabytes (2^30 bytes). If a suffix is not present, HEAPSIZE is expressed in bytes. If the -fupc-heap-HEAPSIZE option is not supplied, the run-time system will use a default heap size of 16 megabytes per thread.
The following options specify thread scheduling and NUMA policies:
-sched-policy[cpu|strict|node|auto]- Specifies the scheduling policy for threads.
cpu- specifies that threads are evenly scheduled over available CPUs. (A CPU is a processor with a single core or a core unit in a 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 a NUMA-aware kernel is available.
auto- specifies that the UPC run-time should not manage scheduling of UPC threads.
-sched-cpu-avoid n1,n2,..
-mem-policy [ node,strict,auto ]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 memory allocation policy.
1.5 Referencies
gcc(1), cpp(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1).
http://upc.lbl.gov/publications/UPC-TR-Original99.pdf Introduction to UPC and Language Specification, William W. Carlson et al., LLNL, CCS-TR-99-157, May 13, 1999
http://www.gwu.edu/~upc/docs/upc_specs_1.2.pdf UPC Language Specification, Tarek A. El-Ghazawi et al, February 25, 2001
http://gasp.hcs.ufl.edu/ GASP Tool Interface, University of Florida
http://www.gccupc.org GNU UPC web site
http://www.gwu.edu/~upc/software/gnu-upc-ml.html GNU UPC Mailing List is an electronic forum for discussing news announcements, bug reports, planned developments, and other topics of interest to GNU UPC developers and users.
1.6 Report Gupc Problems
Report bugs at http://gccupc.org/bugs.
1.7 Contributors to GUPC
The current developers and maintainers of GUPC 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 .
GUPC was originally implemented by Jesse M. Draper and William W. Carlson.
See the Info entry for gupc , or http://gcc.gnu.org/onlinedocs/gcc/Contributors.html for contributors to GCC and GUPC.
