diff --git a/doc/manual/HPCToolkit-users-manual.pdf b/doc/manual/HPCToolkit-users-manual.pdf index 0e256a16e6..135099567c 100644 Binary files a/doc/manual/HPCToolkit-users-manual.pdf and b/doc/manual/HPCToolkit-users-manual.pdf differ diff --git a/doc/manual/environ.tex b/doc/manual/environ.tex index 8ec7a1ddaf..fb8eda1028 100644 --- a/doc/manual/environ.tex +++ b/doc/manual/environ.tex @@ -3,22 +3,26 @@ \chapter{Environment Variables} \HPCToolkit{}'s measurement subsystem decides what and how to measure -using information it obtains from environment variables. When using +using information it obtains from environment variables. +This chapter describes all of the environment variables that control +\HPCToolkit's measurement subsystem. + +When using \HPCToolkit{}'s \hpcrun{} script to measure the performance of dynamically-linked executables, \hpcrun{} takes information passed to it in command-line arguments and communicates it to \HPCToolkit{}'s measurement subsystem by appropriately setting environment variables. To measure statically-linked executables, one first adds \HPCToolkit's measurement subsystem to a binary as it is linked by using \HPCToolkit's -\hpclink script. Prior to launching a statically-linked binary that -includes \HPCToolkit's measurement subsystem, environment variables -must be set manually by the user prior to launching an application. -This section describes all of the environment variables that control -\HPCToolkit's measurement subsystem. Section~\ref{user-env} describes +\hpclink{} script. Prior to launching a statically-linked binary that +includes \HPCToolkit's measurement subsystem, a user +must manually set environment variables. + +Section~\ref{user-env} describes environment variables of interest to users. Section~\ref{system-env} describes environment variables designed for use by \HPCToolkit{} developers. In some cases, \HPCToolkit's developers will ask a user -to set some of these environment variables to generate a detailed error +to set some of the environment variables described in Section~\ref{system-env} to generate a detailed error report when problems arise. \section{Environment Variables for Users} @@ -26,13 +30,13 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_EVENT\_LIST.} -This environment variable is used provide -HPCToolkit's measurement library with a set of sample (event, period) -pairs that will be used for sample-based measurement. HPCRUN\_EVENT\_LIST -must be set otherwise HPCToolkit's measurement facility will terminate +This environment variable is used provide a set of (event, period) +pairs that will be used to configure \HPCToolkit's measurement subsystem to perform +asynchronous sampling. The HPCRUN\_EVENT\_LIST environment variable +must be set otherwise HPCToolkit's measurement subsystem will terminate execution. If an application should run with sampling disabled, HPCRUN\_EVENT\_LIST should be set to NONE. Otherwise, HPCToolkit's -measurement library expects an event list of the form shown below. +measurement subsystem expects an event list of the form shown below. $$event1[@period1];...;eventN[@periodN]$$ As denoted by the square brackets, periods are optional. The default period is 1 million. @@ -46,7 +50,7 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_TRACE.} If this environment variable is set, HPCToolkit's measurement -facility will collect a trace of sample events as part of a measurement +subsystem will collect a trace of sample events as part of a measurement database in addition to a profile. HPCToolkit's hpctraceviewer utility can be used to view the trace after the measurement database are processed with either HPCToolkit's hpcprof or hpcprofmpi @@ -57,7 +61,7 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_OUT\_PATH} -If this environment variable is set, HPCToolkit's measurement library +If this environment variable is set, HPCToolkit's measurement subsystem will use the value specified as the name of the directory where output data will be recorded. The default directory for a command $command$ running under control of a job launcher with as job ID @@ -71,15 +75,15 @@ \section{Environment Variables for Users} Flags to set output path with \hpcrun: \verb|-o/--output| $directoryName$ \paragraph{HPCRUN\_PROCESS\_FRACTION} - +\sloppy If this environment variable is set, \HPCToolkit's measurement -library will measure only a fraction of an execution’s processes. +subsystem will measure only a fraction of an execution’s processes. The value of HPCRUN\_PROCESS\_FRACTION may be written as a a floating point number or as a fraction. So, '0.10' and '1/10' are equivalent. If HPCRUN\_PROCESS\_FRACTION is set to a value with an unrecognized -format, \HPCToolkit's measurement library will use the default +format, \HPCToolkit's measurement subsystem will use the default probability of 0.1. For each process, \HPCToolkit's measurement -library will generate a pseudo-random value in the range [0.0, 1.0). +subsystem will generate a pseudo-random value in the range [0.0, 1.0). If the generated random number is less than the value of HPCRUN\_PROCESS\_FRACTION, then \HPCToolkit{} will collect performance measurements for that process. @@ -90,16 +94,16 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_MEMLEAK\_PROB} If this environment variable is set, \HPCToolkit's measurement -library will measure only a fraction of an execution’s memory +subsystem will measure only a fraction of an execution’s memory allocations, e.g., calls to \verb|malloc|, \verb|calloc|, \verb|realloc|, \verb|posix_memalign|, \verb|memalign|, and valloc. All allocations monitored will have their corresponding calls to free monitored as well. The value of HPCRUN\_MEMLEAK\_PROB may be written as a a floating point number or as a fraction. So, '0.10' and '1/10' are equivalent. If HPCRUN\_MEMLEAK\_PROB is set to a value with an -unrecognized format, \HPCToolkit's measurement library will use the +unrecognized format, \HPCToolkit's measurement subsystem will use the default probability of 0.1. For each memory allocation, \HPCToolkit's -measurement library will generate a pseudo-random value in the range +measurement subsystem will generate a pseudo-random value in the range [0.0, 1.0). If the generated random number is less than the value of HPCRUN\_MEMLEAK\_PROB, then \HPCToolkit{} will monitor that allocation. @@ -110,7 +114,7 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_DELAY\_SAMPLING} \sloppy -If this environment variable is set, HPCToolkit's measurement library +If this environment variable is set, HPCToolkit's measurement subsystem will initialize itself but not begin measurement using sampling until the program turns on sampling by calling \verb|hpctoolkit_sampling_start()|. To measure only a part of a @@ -124,7 +128,7 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_RETAIN\_RECURSION} Unless this environment variable is set, by default HPCToolkit's -measurement library will summarize call chains from recursive calls +measurement subsystem will summarize call chains from recursive calls at a depth of two. Typically, application developers have no need to see performance attribution at all recursion depths when an application calls recursive procedures such as quicksort. Setting @@ -137,7 +141,7 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_MEMSIZE} -If this environment variable is set, HPCToolkit's measurement library +If this environment variable is set, HPCToolkit's measurement subsystem will allocate memory for measurement data in segments using the value specified for HPCRUN\_MEMSIZE (rounded up to the nearest enclosing multiple of system page size) as the segment size. The @@ -148,7 +152,7 @@ \section{Environment Variables for Users} \paragraph{HPCRUN\_LOW\_MEMSIZE} -If this environment variable is set, HPCToolkit's measurement library +If this environment variable is set, HPCToolkit's measurement subsystem will allocate another segment of measurement data when the amount of free space available in the current segment is less than the value specified by HPCRUN\_LOW\_MEMSIZE. The default for low memory @@ -163,10 +167,10 @@ \section{Environment Variables for Developers} \paragraph{HPCRUN\_WAIT} -If this environment variable is set, HPCToolkit's measurement library +If this environment variable is set, HPCToolkit's measurement subsystem will spin wait for a user to attach a debugger. After attaching a debugger, a user can set breakpoints or watchpoints in the user -program or HPCToolkit's measurement library before continuing +program or HPCToolkit's measurement subsystem before continuing execution. To continue after attaching a debugger, use the debugger to set the program variable DEBUGGER\_WAIT=0 and then continue. Note: Setting HPCRUN\_WAIT can only be cleared by a debugger @@ -177,12 +181,12 @@ \section{Environment Variables for Developers} \paragraph{HPCRUN\_DEBUG\_FLAGS} \HPCToolkit{} supports a multitude of debugging flags that enable a -developer to log information about HPCToolkit's measurement facility +developer to log information about HPCToolkit's measurement subsystem as it records sample events. If HPCRUN\_DEBUG\_FLAGS is set, this environment variable is expected to contain a list of tokens separated by a space, comma, or semicolon. If a token is the name of a debugging flag, the flag will be enabled, it will cause HPCToolkit's measurement -facility to log messages guarded with that flag as an application +subsystem to log messages guarded with that flag as an application executes. The complete list of dynamic debugging flags can be found in HPCToolkit's source code in the file src/tool/hpcrun/messages/messages.flag-defns. A special flag value @@ -203,11 +207,11 @@ \section{Environment Variables for Developers} \paragraph{HPCRUN\_ABORT\_TIMEOUT} If an execution hangs when profiled with HPCToolkit's measurement -facility, the environment variable HPCRUN\_ABORT\_TIMEOUT can be +subsystem, the environment variable HPCRUN\_ABORT\_TIMEOUT can be used to specify the number of seconds that an application should be allowed to execute. After executing for the number of seconds specified in HPCRUN\_ABORT\_TIMEOUT, HPCToolkit's measurement -facility will forcibly terminate the execution and record a core +subsystem will forcibly terminate the execution and record a core dump (assuming that core dumps are enabled) to aid in debugging. \parg @@ -218,10 +222,10 @@ \section{Environment Variables for Developers} \paragraph{HPCRUN\_QUIET} If this unfortunately-named environment variable is set, HPCToolkit's -measurement facility will turn on a default set of dynamic debugging +measurement subsystem will turn on a default set of dynamic debugging variables to log information about HPCToolkit's stack unwinding based on on-the-fly binary analysis. If set, HPCToolkit's measurement -facility log information associated with the following debug flags: +subsystem log information associated with the following debug flags: TROLL (when a return address was not found algorithmically and \HPCToolkit{} begins looking for possible return address values on the call stack), SUSPICIOUS\_INTERVAL (when an x86 unwind recipe