PAPI_profil.3 - Online Linux Manual Page

PAPI_profil - Online Linux Manual PageSection : 3
Updated : September, 2004
Source : PAPI Programmer's Reference
Note : PAPI

NAMEPAPI_profil − generate a histogram of hardware counter overflows vs. PC addresses

SYNOPSISC 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.

DESCRIPTIONPAPI_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.

ARGUMENTS*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 below. offset -- the start address ofthe 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: Representative values for the scale variable HEXDECIMALDEFININTION 0x20000131072Maps precisely one instruction address to a unique bucket in buf. 0x10000 65536Maps precisely two instruction addresses to a unique bucket in buf.
0xFFFF 65535Maps approximately two instruction addresses to a unique bucket in buf.
0x8000 32768Maps every four instruction addresses to a bucket in buf.
0x4000 16384Maps every eight instruction addresses to a bucket in buf.
0x0002 2Maps all instruction addresses to the same bucket in buf.
0x0001 1Undefined.
0x0000 0Undefined. 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 scale - as defined above 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 substrate, 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 below: 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.

RETURN VALUESOn success, this function returns PAPI_OK."
On error, a non-zero error code is returned.

ERRORSPAPI_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.

EXAMPLESint 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);

BUGSIf you call PAPI_profil, PAPI allocates buffer space that will not be freed if you call PAPI_shutdown or PAPI_cleanup_eventset. To clean all memory, you must call PAPI_profil on the Events with a 0 threshold.

Johanes Gumabo

Data Size : 20,596 byte
man-PAPI_profil.3Build : 2024-12-05, 20:55 :
Visitor Screen : x
Visitor Counter ( page / site ) : 5 / 175,855
Visitor ID : :
Visitor IP : 3.144.37.178 :
Visitor Provider : AMAZON-02 :
Provider Position ( lat x lon ) : 39.962500 x -83.006100 : x
Provider Accuracy Radius ( km ) : 1000 :
Provider City : Columbus :
Provider Province : Ohio , : ,
Provider Country : United States :
Provider Continent : North America :
Visitor Recorder : Version :
Visitor Recorder : Library :
Online Linux Manual Page : Version : Online Linux Manual Page - Fedora.40 - march=x86-64 - mtune=generic - 24.12.05
Online Linux Manual Page : Library : lib_c - 24.10.03 - march=x86-64 - mtune=generic - Fedora.40
Online Linux Manual Page : Library : lib_m - 24.10.03 - march=x86-64 - mtune=generic - Fedora.40
Data Base : Version : Online Linux Manual Page Database - 24.04.13 - march=x86-64 - mtune=generic - fedora-38
Data Base : Library : lib_c - 23.02.07 - march=x86-64 - mtune=generic - fedora.36

Very long time ago, I have the best tutor, Wenzel Svojanovsky . If someone knows the email address of Wenzel Svojanovsky , please send an email to johanes_gumabo@yahoo.co.id .

If error, please print screen and send to johanes_gumabo@yahoo.co.id
Under development. Support me via PayPal.