• 2019 Update 3
  • 03/07/2019
  • Public Content
  • Download as PDF
Contents

Source locations can be specified and recorded in two different contexts:
  • State changes, associating a source location with the state change. This is useful to record where a function has been called, or where a code region begins and ends.
  • Communication events, associating a source location with calls to MPI functions, for example, calls to the send/receive or collective communication and I/O functions.
To minimize instrumentation overhead, locations for the state changes and communication events are referred to by integer location handles that can be defined by calling the API function
VT_scldef()
, which will automatically assign a handle. A source location is a pair of a filename and a line number within that file.
VT_scldef
int VT_scldef (const char * file, int line_nr, int * sclhandle)
Description
Allocates a handle for a source code location (SCL).
Fortran
VTSCLDEF(file, line_nr, sclhandle, ierr)
Parameters
file
file name
line_nr
line number in this file, counting from 1
Return values
sclhandle
the integer it points to is set by Intel® Trace Collector
Returns error code
Some functions require a location handle, but they all accept
VT_NOSCL
instead of a real handle:
#define VT_NOSCL
Special SCL handle — no location available.
VT_sclstack
int VT_sclstack (void * pc, void * stackframe, int skip, int trace, int * sclhandle)
Description
Allocates a handle for a source code location (SCL) handle which refers to the current call stack.
This SCL can then be used in several API calls without having to repeat the stack unwinding each time. Which stack frames are preserved and which are skipped is determined by the
PCTRACE
configuration option, but can be overridden with function parameters.
Special support is available for recording source code locations from inside signal handlers by calling this function with the
pc
and
stackframe
parameters different from
NULL
. Other usages of these special parameters include:
  • Remembering the stack frame in those API calls of a library that are invoked directly by the application, then at arbitrary points in the library do stack unwinding based on that stack frame to catch just the application code
  • Defining a source code location ID for a specific program counter value
Here is a usage example of this call inside a library that implements a message send:
void MySend(struct *msg) { int sclhandle; VT_sclstack( NULL, NULL, // we use the default stack unwinding 1, // MySend() is called directly by the // application code we want to trace: // skip our own source code, but not // more -1, // default PCTRACE setting for size // of recorded stack &sclhandle ); // if an error occurs, we continue with the sclhandle == VT_NOSCL // that VT_sclstack() sets VT_enter( funchandle, sclhandle ); VT_log_sendmsg( msg->receiver, msg->count, msg->tag, msg->commid, sclhandle ); // do the send here VT_leave( sclhandle ); }
Parameters
pc
record the source code of this program counter value as the innermost call location, then continue with normal stack unwinding;
NULL
if only stack unwinding is to be used
stackframe
start unwinding at this stack frame,
NULL
for starting with the stack frame of
VT_sclstack()
itself: on Intel® 64 architecture the stack frame is found in the RBP register
skip
-1: get the number of stack frames to skip from the
PCTRACE
configuration option
0: first recorded program counter value after the (optional)
pc
address is the return address of the initial stack frame
>0: skip the given number of return addresses
trace
-1: get the number of stack frames to record from the
PCTRACE
configuration option
0: do not record any source code locations for the call stack: returns an SCL ID for the
pc
address if one is given, otherwise returns
VT_NOSCL
immediately
>0: the number of stack frames to record
Return values
sclhandle
points to the integer set by Intel® Trace Collector to a valid SCL handle in case of success and
VT_NOSCL
otherwise
Returns error code
Intel® Trace Collector automatically records all available information about MPI calls. On some systems, the source location of these calls is automatically recorded. On the other systems, the source location of MPI calls can be recorded by calling the
VT_thisloc()
function immediately before the call to the MPI function, with no intervening MPI or Intel® Trace Collector API calls.
VT_thisloc
int VT_thisloc (int sclhandle)
Description
Sets source code location for next activity that is logged by Intel® Trace Collector.
After being logged it is reset to the default behavior again: automatic PC tracing if enabled in the configuration file, and supported or no SCL otherwise.
Fortran
VTTHISL(sclhandle, ierr)
Parameters
sclhandle
handle defined either with
VT_scldef()
Return values
Returns error code

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804