Chapter 4. Compiling System Environment Variables

This chapter details environment variables which are used by the MIPSpro compiling environment. The following sections are included in this chapter:

4.1. OpenMP Environment Variables

OMP_SCHEDULE 

Sets the schedule type and (optionally) the chunk size for DO and PARALLEL DO loops declared with a schedule of RUNTIME. For these loops, the schedule is set at run time when the system reads the value of this environment variable. Valid values for this environment variable are STATIC, DYNAMIC, and GUIDED. The default value for this environment variable is STATIC.

For DO and PARALLEL DO directives that have a schedule type other than RUNTIME, this environment variable is ignored.

If the optional chunk size is not set, a chunk size of 1 is assumed, except in the case of a STATIC schedule. For a STATIC schedule, the default chunk size is set to the loop iteration space divided by the number of threads applied to the loop.

OMP_NUM_THREADS 

Sets the number of threads to use during execution, unless that number is explicitly changed by calling the OMP_SET_NUM_THREADS(3) subroutine.

When dynamic adjustment of the number of threads is enabled, the value of this environment variable is the maximum number of threads to use. The default value is the minimum of 8 and the number of CPUs on the system.

OMP_DYNAMIC 

Enables or disables dynamic adjustment of the number of threads available for execution of parallel regions.

If set to TRUE, the number of threads that are used for executing parallel regions can be adjusted by the runtime environment to best utilize system resources. The default value is TRUE. If set to FALSE, dynamic adjustment is disabled.

OMP_NESTED 

Enables or disables nested parallelism. If set to TRUE, nested parallelism is enabled. If set to FALSE, it is disabled (default).

4.2. Origin Series Variables

The following environment variables are recognized on Origin 2000 and Origin 200 systems.

_DSM_BARRIER 

Controls the barrier implementation within the MP run-time system. This environment variable accepts one of the following values:

  • FOP: Uses the uncached operations available on Origin series systems. FOP achieves the best performance. This requires kernel patch #1856.

  • LLSC: Uses load-linked (LL), store-conditional (SC) operations on shared memory.

  • SHM: Uses regular shared memory. Default

_DSM_MIGRATION 

Specifies aspects of automatic page migration. Values can be OFF (disables migration), ON (enables migration for all but explicitly placed data using PAGE_PLACE or a data distribution directive), or ALL_ON (enables migration for all data).

Default: OFF.

_DSM_MIGRATION_LEVEL 

Controls the aggressiveness level of automatic page migration. This environment variable must be set to an integer value between 0 (most conservative setting) and 100 (most aggressive). Specifying 0 disables this feature.

Default: 100.

_DSM_MUSTRUN 

Locks each thread to the corresponding CPU. This environment variable is not set by default.

_DSM_OFF 

When set to OFF, disables nonuniform memory access (NUMA) calls. This can be used, for example, to allocate pages from a particular memory.

On Origin series systems, _DSM_OFF is set to ON by default.

_DSM_PLACEMENT 

Allocates memory for all stack, data, and text segments. Values can be FIRST_TOUCH (specifies first-touch data placement) or ROUND_ROBIN (specifies round-robin data allocation.)

Default: ROUND_ROBIN.

_DSM_PPM 

Specifies the number of processors to use per memory module. Must be set to an integer value. To use only one processor per memory module, set this environment variable to 1.

_DSM_ROUND_ROBIN 

Specifies round-robin data allocation across memories rather than first-touch, for all of stack, data, and text segments.

_DSM_VERBOSE 

When set, writes messages to stdout about parameters used during execution to stdout.

_DSM_WAIT 

Controls how a thread waits for a synchronization event, such as a lock or a barrier. Values can be SPIN (specifies that a thread wait in a loop until the synchronization event succeeds) or YIELD (specifies that a waiting thread should spin for a while and invokes sginap(2), which surrenders the CPU to another waiting process, if any).

Default: YIELD.

4.3. Multiprocessing Variables

The multiprocessing environment variables allow you to set up your multiprocessing environment. Some of the settings that these environment variables control can also be set through library routines. For more information on the multiprocessing library routines, see MP(3f).


Note: Many of the environment variables in the following list are outmoded. The descriptions for each one indicate the preferred alternative, if one exists.


MP_SCHEDTYPE and CHUNK
 

Specifies the type of scheduling to use on PARALLEL DO loops with scheduling specified as RUNTIME.

The defaults are the same as those for the DOACROSS directive clauses. If neither environment variable is set, SIMPLE scheduling is assumed. If MP_SCHEDTYPE is set and CHUNK is not set, a CHUNK of 1 is assumed. If CHUNK is set, but MP_SCHEDTYPE is not set, DYNAMIC scheduling is assumed.


Note: The MP_SCHEDTYPE and CHUNK environment variables are outmoded. The preferred alternative is the OMP_SCHEDULE environment variable.


MP_SET_NUMTHREADS, MP_BLOCKTIME, MP_SETUP, and NUM_THREADS
 

Acts as an implicit call to MP_SET_NUMTHREADS(3f), MP_BLOCKTIME(3f), and MP_SETUP(3f) (respectively).

The MP_SET_NUMTHREADS environment variable determines the number of processors across which an array is distributed during program execution, regardless of the number of processors physically present on the machine. MP_BLOCKTIME accepts an integer value. MP_SETUP accepts no values.


Note: The MP_SET_NUMTHREADS and NUM_THREADS environment variables are outmoded. The preferred alternative is the OMP_NUM_THREADS environment variable.


MP_SIMPLE_SCHED
 

Controls simple scheduling of parallel loops. Values can be EQUAL or BLOCK. If you are using distributed arrays, the default is BLOCK. For all other cases, the default is EQUAL. The critical path (that is, the largest piece of the iteration space) is the same in either case.

MP_SLAVE_STACKSIZE
 

Controls the stack size of slave processes. As its value, it accepts an integer number that indicates the desired stack size, in bytes. The default is 16 Mbytes (4 Mbytes for greater than 64 threads). Slave processes allocate their local data only onto their stacks. Shared data, even if allocated on the master's stack, is not counted.

MP_STACK_OVERFLOW
 

Controls stack overflow checking. In a multi-threaded program (for example, one using OpenMP constructs) the MP runtime system automatically detects and reports stack overflow errors at runtime. When stack overflow errors are encountered, you can use the MP_SLAVE_STACKSIZE environment variable or the MP_SET_SLAVE_STACKSIZE library routine to request larger stacks for the parallel threads.

The MP_SLAVE_STACKSIZE environment variable and the MP_SET_SLAVE_STACKSIZE library routine affect the allocation of stack space for parallel threads. If this effect is not desired, it can be be disabled by setting the MP_STACK_OVERFLOW environment variable to OFF. By default, this environment variable is set to ON.

MP_SUGNUMTHD and MPC_SUGNUMTHD
 

Enables an additional, asynchronous process that monitors the system load. This environment variable may be useful on a system with long-running jobs and varying workloads.

The process that is enabled allows you to vary the number of threads during execution of some jobs. When idle processors exist, the number of threads is increased, up to the maximum specified by MP_SET_NUMTHREADS. When the system load increases, the number of threads is decreased, possibly to as few as one. Note that the number of threads being used is adjusted only at the start of a parallel region (for example, at a DOACROSS directive); it is not adjusted within a parallel region. Using this environment variable can improve overall system throughput. By avoiding excessive concurrency, this feature can reduce delays at synchronization points within a single application.

These environment variables are on by default.


Note: The MP_SUGNUMTHD and MPC_SUGNUMTHD environment variables are outmoded. The preferred alternative is the OMP_DYNAMIC environment variable.


MP_SUGNUMTHD_MIN and MP_SUGNUMTHD_MAX
 

Limits the effect of MP_SUGNUMTHD. These environment variables accept an integer value between 1 and the value of MP_SET_NUMTHREADS. When these environment variables are set, the number of processors is not lowered below the MP_SUGNUMTHD_MIN setting and it is not increased beyond the MP_SUGNUMTHD_MAX setting.


Note: These environment variables are outmoded.


MP_SUGNUMTHD_VERBOSE
 

Determines whether or not the system writes informational messages to stderr whenever the process changes the number of threads in use.

The compiler interprets library calls to MP_NUMTHREADS(3f) and MP_SET_NUMTHREADS(3f) as a sign that the application depends on the number of threads in use, and the number is frozen upon encountering either of these calls. If MP_SUGNUMTHD_VERBOSE is set, a message to that effect is written to stderr. By default, this environment variable is not set.


Note: The MP_SUGNUMTHD_VERBOSE environment variable is outmoded. The preferred alternative is the _DSM_VERBOSE environment variable.


MPC_GANG
 

Controls the use of gang scheduling, which is enabled by default. To disable gang scheduling, set this environment variable to OFF. By default, this environment variable is not set.


Note: The MPC_GANG environment variable is outmoded.


PAGESIZE_STACK, PAGESIZE_DATA, and PAGESIZE_TEX
 

Specifies the desired page size for each of the stack, data, and text segments. The default page size is 16 Kbytes on IRIX 6.4 and later systems; the default is 4 Kbytes on systems running previous IRIX revisions. These environment variables accept an integer value that represents the desired size in Kbytes. Typical values for this environment variable are 4, 16, or 64. Your operating system may not be able to accommodate larger values. If unsuitable values are specified, the system may adjust your page size to be lower than requested.

4.4. I/O Environment Variables

The following environment variables are used by the I/O libraries.

FF_IO_AIO_LOCKS, FF_IO_AIO_NUMUSERS, FF_IO_AIO_THREADS
 

Specifies aspects of the aioinit structure. This structure contains the following fields: aio_locks, aio_numusers, and aio_threads. These environment variables alter the values used for these fields. For more information on using these environment variables, see AIO_SGI_INIT(3) man page.

FF_IO_LOGFILE
 

Names a file to which statistics are written by the event FFIO layer.

FILENV
 

Specifies the location of the assign environment information. Use FILENV to assign a file name to store the assign information or to specify that it be stored in the process environment.

4.5. Miscellaneous Compiler Environment Variables

The following miscellaneous environment variables also affect compiling.

COMPILER_DEFAULTS_PATH
 

Specifies the a path or a colon-separated list of paths designating where the compiler is to look for the compiler.defaults file.

F2CFLAGS
 

Controls the Fortran-to-C interface. As a value for this environment variable, specify options to the mkf2c(1) command.

FORMAT_TYPE_CHECKING
 

Determines restrictions for various data types.

F90_BOUNDS_CHECK_ABORT
 

Controls whether the compiler aborts execution if a bounds check fails.

The f90 -C option performs array bounds checking. By default, execution continues even if the bounds check fails. To cause the compiler to abort on a failed bounds check, set the F90_BOUNDS_CHECK_ABORT environment variable to YES.

LD_LIBRARY_PATH, LD_LIBRARY64_PATH, and LD_LIBRARYN32_PATH
 

Specifies the default library search path. This differs depending on the ABI being used. For more information on these environment variables, see rld(5).

LISTIO_PRECISION
 

Controls the number of digits of precision printed by list-directed output.

NLSPATH
 

Affects interactions with the message system. For more information, see catopen(3c).

SGI_ABI
 

Specifies the Application Binary Interface (ABI) used during compilation. This environment variable can be used to change the default ABI. Specify -o32, -n32, or -64 as values.

SGI_CC
 

Specifies the default C compile mode. This environment variable can be set to any one of ansi, cckr (cc only), or xansi, and is interpreted as an option before any other options specified on the command line.

TMPDIR
 

Specifies a path for temporary files. When set, the value used is the directory in which the system places temporary files, rather than the default, /tmp.

TRAP_FPE
 

Controls the handling and classifying of floating-point exceptions and substitutes new values. It also provides a mechanism to count, trace, exit, or abort on enabled exceptions. The -TENV:check_div option on the command line inserts checks for divide by zero and for overflow. See FSIGFPE(3f) for information on HANDLE_FSIGFPES, which performs a function similar to that of this environment variable.

_XPG
 

Specifies that compilation should proceed according to X/Open XPG4 specifications. If set, cc or f77 (c89 or fort77, as they are known under XPG4, respectively) operates in conformance with the X/Open XPG4 specifications. The options and the command line behavior may differ in accordance to the XPG4 standards.

ZERO_WIDTH_PRECISION
 

Sets the default size of the fractional field using real formating specifications.

You can also set an environment variable to specify the compilation mode:

setenv SGI_ABI -n32
 

Sets the environment for new 32-bit compilation.

setenv SGI_ABI -64
 

Sets the environment for 64-bit compilation.

setenv SGI_ABI -o32
 

Sets the environment for old 32-bit compilation.

4.6. SpeedShop Environment Variables

SpeedShop is a tool used to help you analyze compiler performance on IRIX systems.

4.6.1. General Environment Variables

_SPEEDSHOP_VERBOSE
 

Causes a log of each program's operation to be written to stderr. If this variable is set to an empty string, only major events are logged; if it is set to a non-empty string, more detailed events are logged.

_SPEEDSHOP_SILENT
 

Suppresses all SpeedShop output other than fatal error messages. If both _SPEEDSHOP_VERBOSE and _SPEEDSHOP_SILENT are set, _SPEEDSHOP_VERBOSE is ignored.

_SPEEDSHOP_CALIPER_POINT_SIG sig_num
 

Causes the specified signal number to be used for recording a caliper point in the experiment.

_SPEEDSHOP_REUSE_FILE_DESCRIPTOR
 

Opens and closes the file descriptors for the output files every time performance data is to be written

_SPEEDSHOP_HWC_COUNTER_NUMBER
 

Specifies the counter to be used for prof_hwc experiments. Counters are numbered between 0 and 31, Counter 0 counters are numbered 0-15, and counter 1 counters are numbered 16-31.

_SPEEDSHOP_HWC_COUNTER_OVERFLOW
 

Specifies the overflow value for the counter to be used in prof_hwc experiments. The value chosen can be any number greater than 0. Some choices may produce data that is not statistically random but reflects a correlation between the overflow interval and a cyclic behavior in the application. Users may want to do two or more runs with different overflow values.

_SPEEDSHOP_OUTPUT_NOCOMPRESS
 

Disables the compression of performance data.

_SPEEDSHOP_OUTPUT_DIRECTORY
 

Causes the output data files to be placed in the specified directory rather than the current working directory

_SPEEDSHOP_OUTPUT_FILENAME
 

Causes the output file to be saved under the specified name. If set to myfile, the experiment file is named myfile.suffix (for example, myfile.m12345).

If _SPEEDSHOP_OUTPUT_DIRECTORY is also specified, the directory is prepended to the file name you specify.

4.6.2. Process Tracking Environment Variables

_SPEEDSHOP_TRACE_FORK
 

If True, specifies that processes spawned by calls to fork() will be monitored if they do not call exec(). If they do call exec() and _SPEEDSHOP_TRACE_FORK_TO_EXEC is not set to True, the data covering the time between the fork() and exec() will be discarded.

Default: true.

_SPEEDSHOP_TRACE_FORK_TO_EXEC
 

If True, specifies that a process spawned by calls to fork() will be monitored, even if they also call exec().

Default: false.

_SPEEDSHOP_TRACE_EXE
 

If True, specifies that a process spawned by calls to any of the various flavors of exec() will be monitored.

Default: true.

_SPEEDSHOP_TRACE_SPROC
 

If True, specifies that a process spawned by calls to sproc() will be monitored.

Default: true.

_SPEEDSHOP_TRACE_SYSTEM
 

If True, specifies that system() calls will be monitored.

Default: true.

4.6.3. Expert-Mode Environment Variables

A number of variables may be used for debugging and finer control of the operation of SpeedShop:

_SPEEDSHOP_SAMPLING_MODE
 

Used for PC sampling and hardware counter profiling. If set to 1, generates data for the base executable only. If not set or set to a value other than 1, data is generated for the executable and all the DSOs it uses.

_SPEEDSHOP_INIT_DEFERRED_SIG
 

If specified, initialization of the experiment is not performed when the target process starts. Initialization is delayed until the specified signal is sent to the process. A handler for the given signal is installed when the process starts. It is the user's responsibility to ensure that it is not overridden by the target code.

_SPEEDSHOP_SHUTDOWN_SIG
 

If specified, termination of the experiment is not performed when the target process exits. Termination happens when the specified signal is sent to the process. A handler for the given signal is installed when the process starts, and it is the user's responsibility to ensure that it is not overridden by the target code.

_SPEEDSHOP_EXPERIMENT_TYPE
 

Passes the name of the experiment to the run-time DSO. It is normally set by ssrun but can be overwritten.

_SPEEDSHOP_MARCHING_ORDERS
 

Passes the marching orders of the experiment to the run-time DSO. The marching orders are usually set by ssrun from the experiment type, but they can be overwritten.

_SPEEDSHOP_SBRK_BUFFER_LENGTH
 

Defines the maximum size of the internal malloc (memory allocation) area used. This area is completely separate from the user's area and has a default size of 0x100000.

_SPEEDSHOP_FILE_BUFFER_LENGTH
 

Defines the size of the buffer used for writing the experiment files. The default length is 8 KB. The buffer is used only for writing small records to the file; large records are written directly to avoid the buffering overhead.

_SPEEDSHOP_DEBUG_NO_SIG_TRAPS
 

Disables the normal setting of signal handlers for all fatal and exit signals.

_SPEEDSHOP_DEBUG_NO_STACK_UNWIND
 

Suppresses the stack unwind, as in usertime experiments and at caliper samples, for all experiments. The option is used as a workaround for various unwind bugs in libexc.