Next: , Previous: ppwmpicc, Up: Command Reference


B.9 ppwupcc

ppwupcc is a simple wrapper that takes care of invoking your underlying UPC compiler with all options and flags needed by the PPW performance tool. ppwupcc is meant to be used in place of your regular UPC compiler (such as upcc) such that you can instrument your program for use with PPW with as little effort as possible.

ppwupcc’ will pass any options it does not understand to your underlying UPC compiler.

B.9.1 Invoking ppwupcc

To invoke ppwupcc, use the following syntax:

     
     ppwupcc [--inst|--inst-local|--inst-functions|--noinst]
             [-v|-V|--version|--ppw-verbose|--ppw-showcommand]
             [--ppw-overschedule]
             file.upc...
     

B.9.2 ppwupcc Command Options

ppwupcc gives special meaning to the following options:

--inst
Instrument any source files given to the compiler for recording performance data. This option is on by default unless the --noinst option is given.
--inst-local
Instrument source files to record performance data bout both shared-remote and shared-local memory accesses. By default, only shared-remote accesses will be tracked (accesses to the shared data space to remote data located on other threads) unless this option is given.
--inst-functions
Track all function entry and exits. This allows PPW to record information about how much time was spent in each function, which allows you to localize performance bottlenecks to individual functions. If you make a large number of function calls in a short period of time in your application, be sure to read the PPW manual section `Managing Measurement Overhead'.
--noinst
Do not instrument the source files to record performance data. Conflicts with any of the --inst options.
-V
--version
Print version information to stdout before invoking the underlying UPC compiler.
--ppw-verbose
Print all commands to stdout prefixed by a `+' before invoking them. This option is not passed along to the backend UPC compiler. Not useful for most users.
--ppw-showcommand
Print all commands out as in --ppw-verbose, except do not run them. Useful for debugging the PPW wrapper script or for poking into the internals of PPW. This option is not passed along to the backend UPC compiler. Not useful for most users.
--ppw-overschedule
Forces PPW to use polite synchronization methods when collecting performance data into a PAR file at the end of the run, such as calling sched_yield(2) while inside synchronization spinlocks. This is only useful if you are severely overscheduling threads to CPUs, such as using -pthreads=32 on a uniprocessor cluster with Berkeley UPC.
-v
Same as --version --ppw-verbose.

B.9.3 ppwupcc Notes

If you decide to compile parts of your application using a regular compiler such as gcc, you may experience warnings like this:

     $ gcc -c file.c
     $ ppwcc -o myapp file.o file2.c
     PPW warning: Can't find file.o.ppw.compopts
     PPW warning: missing some compilation info
     PPW warning: Can't find file.o.ppw.src
     PPW warning: missing some source info

In short, you may ignore this warning but read the rest of this section for caveats.

PPW keeps metadata about each file that you compile, including compilation arguments and a snapshot of the source code that was compiled. This metadata is stored in files with extensions matching .ppw.*, such as .ppw.compopts and .ppw.src.

During the linking phase, PPW's wrapper scripts assemble all compilation metadata information (along with other data) into a single .ppw.sar file. If you pass in a .o object file that does not have appropriate .ppw.* files, you will get warnings similar to those mentioned above. You may safely ignore such warnings, although when you view performance data for your application later this metadata will not be available.

If you have a complicated build process that moves object files around from the location in which they were originally compiled, remember to keep the .ppw.* files in the same directory if you wish to preserve this metadata.

Please be sure to use either ppwupcc, ppwshmemcc, or ppwcc when linking your application, as these scripts will pass in the necessary arguments to link your application against all libraries that PPW requires.

For UPC programs, PPW does not currently support noncollective UPC exits, such as an exit on one thread that causes a SIGKILL signal to be sent to other threads. As an example, consider the following UPC program:

     ...
     int main() {
       if (MYTHREAD) {
         upc_barrier;
       } else {
         exit(0);
       }
       return 0;
     }

In this program, depending on the UPC compiler and runtime system used, PPW may not write out valid performance data for all threads. A future version of PPW may add “dump” functionality where complete profile data is flushed to disk every N minutes, which will allow you to collect partial performance data from a long-running program that happens to crash a few minutes before it is completed. However, for technical reasons PPW will generally not be able to recover from situations like these, so please do try to debug any crashes in your program before analyzing it with PPW.