Linux Certif

Toute la documentation sur la certification Linux LPI

PAPI_sprofil

NAME

PAPI_sprofil - generate PC histogram data from multiple code regions where hardware counter overflow occurs

SYNOPSIS

C Interface

 #include <papi.h>
 int PAPI_sprofil(PAPI_sprofil_t * prof, int profcnt, int EventSet,
                  int EventCode,  int threshold,  int flags  );
 

Fortran Interface

 The profiling routines have no Fortran interface.
 

DESCRIPTION

PAPI_sprofil() is a structure driven profiler that profiles one or more disjoint regions of code in a single call. It accepts a pointer to a preinitialized array of sprofil structures, and initiates profiling based on the values contained in the array. Each structure in the array defines the profiling parameters that are normally passed to PAPI_profil(). For more information on profiling, see: PAPI_pofil(3)

STRUCTURE FIELDS

*pr_base -- pointer to the base address of the buffer.

pr_size -- the size of the histogram buffer in pr_base.

pr_off -- the start address of        the region to be profiled.

pr_scale -- the scaling factor applied to the buffer.

These fields are described in greater detail in the documentation for PAPI_pofil(3)

ARGUMENTS

*prof -- pointer to an array of PAPI_sprofil_t structures.

profcnt -- number of structures in the prof array for hardware profiling.

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 given in a table in the documentation for PAPI_pofil(3)

RETURN VALUES

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

ERRORS

Error returns for PAPI_sprofil() are identical to those for PAPI_profil(3) Please refer to that page for further details.

EXAMPLES

 int retval;
 unsigned long length;
 PAPI_exe_info_t *prginfo;
 unsigned short *profbuf1, *profbuf2, profbucket;
 PAPI_sprofil_t sprof[3];
 
 if ((prginfo = PAPI_get_executable_info()) == NULL)
   handle_error(1);
 
 length = (unsigned long)(prginfo->text_end - prginfo->text_start);
 
 /* Allocate 2 buffers of equal length */
 profbuf1 = (unsigned short *)malloc(length);
 profbuf2 = (unsigned short *)malloc(length);
 if ((profbuf1 == NULL) || (profbuf2 == NULL))
   handle_error(1);
 memset(profbuf1,0x00,length);
 memset(profbuf2,0x00,length);
 
 /* First buffer */
 sprof[0].pr_base = profbuf1;
 sprof[0].pr_size = length;
 sprof[0].pr_off = (caddr_t) DO_FLOPS;
 sprof[0].pr_scale = 0x10000;
 
 /* Second buffer */
 sprof[1].pr_base = profbuf2;
 sprof[1].pr_size = length;
 sprof[1].pr_off = (caddr_t) DO_READS;
 sprof[1].pr_scale = 0x10000;
 
 /* Overflow bucket */
 sprof[2].pr_base = profbucket;
 sprof[2].pr_size = 1;
 sprof[2].pr_off = 0;
 sprof[2].pr_scale = 0x0002;
 
 if ((retval = PAPI_sprofil(sprof, EventSet, PAPI_FP_INS, 1000000,
                  PAPI_PROFIL_POSIX | PAPI_PROFIL_BUCKET_16)) != PAPI_OK)
   handle_error(retval);
 

BUGS

These functions have no known bugs.

SEE ALSO

PAPI_profil(3), PAPI_get_executable_info(3), PAPI_overflow(3)