PAPI_profil(3) PAPI PAPI_profil(3)NAMEPAPI_profil-
Generate a histogram of hardware counter overflows vs. PC addresses.
SYNOPSISDetailed Description
C Interface:
#include <papi.h>
int PAPI_profil(void *buf, unsigned bufsiz, unsigned long offset,
unsigned scale, int EventSet, int EventCode, int threshold, int
flags );
Fortran Interface
The profiling routines have no Fortran interface.
Parameters:
*buf -- pointer to a buffer of bufsiz bytes in which the histogram
counts are stored in an array of unsigned short, unsigned int, or
unsigned long long values, or 'buckets'. The size of the buckets is
determined by values in the flags argument.
bufsiz -- the size of the histogram buffer in bytes. It is computed
from the length of the code region to be profiled, the size of the
buckets, and the scale factor as discussed above.
offset -- the start address of the region to be profiled.
scale -- broadly and historically speaking, a contraction factor
that indicates how much smaller the histogram buffer is than the
region to be profiled. More precisely, scale is interpreted as an
unsigned 16-bit fixed-point fraction with the decimal point implied
on the left. Its value is the reciprocal of the number of addresses
in a subdivision, per counter of histogram buffer. Below is a table
of representative values for scale.
EventSet -- The PAPI EventSet to profile. This EventSet is marked
as profiling-ready, but profiling doesn't actually start until a
PAPI_start() call is issued.
EventCode -- Code of the Event in the EventSet to profile. This
event must already be a member of the EventSet.
threshold -- minimum number of events that must occur before the PC
is sampled. If hardware overflow is supported for your component,
this threshold will trigger an interrupt when reached. Otherwise,
the counters will be sampled periodically and the PC will be
recorded for the first sample that exceeds the threshold. If the
value of threshold is 0, profiling will be disabled for this event.
flags -- bit pattern to control profiling behavior. Defined values
are shown in the table above.
Return values:
PAPI_OK
PAPI_EINVAL One or more of the arguments is invalid.
PAPI_ENOMEM Insufficient memory to complete the operation.
PAPI_ENOEVST The EventSet specified does not exist.
PAPI_EISRUN The EventSet is currently counting events.
PAPI_ECNFLCT The underlying counter hardware can not count this
event and other events in the EventSet simultaneously.
PAPI_ENOEVNT The PAPI preset is not available on the underlying
hardware.
PAPI_profil() provides hardware event statistics by profiling the
occurence of specified hardware counter events. It is designed to mimic
the UNIX SVR4 profil call.
The statistics are generated by creating a histogram of hardware
counter event overflows vs. program counter addresses for the current
process. The histogram is defined for a specific region of program code
to be profiled, and the identified region is logically broken up into a
set of equal size subdivisions, each of which corresponds to a count in
the histogram.
With each hardware event overflow, the current subdivision is
identified and its corresponding histogram count is incremented. These
counts establish a relative measure of how many hardware counter events
are occuring in each code subdivision.
The resulting histogram counts for a profiled region can be used to
identify those program addresses that generate a disproportionately
high percentage of the event of interest.
Events to be profiled are specified with the EventSet and EventCode
parameters. More than one event can be simultaneously profiled by
calling PAPI_profil() several times with different EventCode values.
Profiling can be turned off for a given event by calling PAPI_profil()
with a threshold value of 0.
Representative values for the scale variable
HEX DECIMAL DEFININTION
0x20000 131072 Maps precisely one instruction address to a
unique bucket in buf.
0x10000 65536 Maps precisely two instruction addresses to a
unique bucket in buf.
0x0FFFF 65535 Maps approximately two instruction addresses to
a unique bucket in buf.
0x08000 32768 Maps every four instruction addresses to a
bucket in buf.
0x04000 16384 Maps every eight instruction addresses to a
bucket in buf.
0x00002 2 Maps all instruction addresses to the same
bucket in buf.
0x00001 1 Undefined.
0x00000 0 Undefined.
Historically, the scale factor was introduced to allow the allocation
of buffers smaller than the code size to be profiled. Data and
instruction sizes were assumed to be multiples of 16-bits. These
assumptions are no longer necessarily true. PAPI_profil() has preserved
the traditional definition of scale where appropriate, but deprecated
the definitions for 0 and 1 (disable scaling) and extended the range of
scale to include 65536 and 131072 to allow for exactly two addresses
and exactly one address per profiling bucket.
The value of bufsiz is computed as follows:
bufsiz = (end - start)*(bucket_size/2)*(scale/65536) where
· bufsiz - the size of the buffer in bytes
· end, start - the ending and starting addresses of the profiled region
· bucket_size - the size of each bucket in bytes; 2, 4, or 8 as defined
in flags
Defined bits for the flags variable:
· PAPI_PROFIL_POSIX Default type of profiling, similar to profil
(3).
· PAPI_PROFIL_RANDOM Drop a random 25% of the samples.
· PAPI_PROFIL_WEIGHTED Weight the samples by their value.
· PAPI_PROFIL_COMPRESS Ignore samples as values in the hash buckets
get big.
· PAPI_PROFIL_BUCKET_16 Use unsigned short (16 bit) buckets, This
is the default bucket.
· PAPI_PROFIL_BUCKET_32 Use unsigned int (32 bit) buckets.
· PAPI_PROFIL_BUCKET_64 Use unsigned long long (64 bit) buckets.
· PAPI_PROFIL_FORCE_SW Force software overflow in profiling.
Example
* int retval;
* unsigned long length;
* PAPI_exe_info_t *prginfo;
* unsigned short *profbuf;
*
* if ((prginfo = PAPI_get_executable_info()) == NULL)
* handle_error(1);
*
* length = (unsigned long)(prginfo->text_end - prginfo->text_start);
*
* profbuf = (unsigned short *)malloc(length);
* if (profbuf == NULL)
* handle_error(1);
* memset(profbuf,0x00,length);
*
* if ((retval = PAPI_profil(profbuf, length, start, 65536, EventSet,
* PAPI_FP_INS, 1000000, PAPI_PROFIL_POSIX | PAPI_PROFIL_BUCKET_16))
* != PAPI_OK)
* handle_error(retval);
*
See Also:
PAPI_overflow
PAPI_sprofil
Author
Generated automatically by Doxygen for PAPI from the source code.
Version 5.2.0.0 Mon Oct 28 2013 PAPI_profil(3)
