PAPI_sprofil(3)

1PAPI_sprofil(3)                      PAPI                      PAPI_sprofil(3)
2
3
4

NAME

6       PAPI_sprofil  -  generate  PC histogram data from multiple code regions
7       where hardware counter overflow occurs
8
9

SYNOPSIS

11       C Interface
12       #include <papi.h>
13       int PAPI_sprofil(PAPI_sprofil_t * prof, int profcnt, int EventSet,
14                        int EventCode,  int threshold,  int flags  );
15
16       Fortran Interface
17       The profiling routines have no Fortran interface.
18
19

DESCRIPTION

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

STRUCTURE FIELDS

30       *pr_base -- pointer to the base address of the buffer.
31
32       pr_size -- the size of the histogram buffer in pr_base.
33
34       pr_off -- the start address of  the region to be profiled.
35
36       pr_scale -- the scaling factor applied to the buffer.
37
38       These  fields  are described in greater detail in the documentation for
39       PAPI_pofil(3)
40
41

ARGUMENTS

43       *prof -- pointer to an array of PAPI_sprofil_t structures.
44
45       profcnt -- number of structures in the prof array for hardware  profil‐
46       ing.
47
48       EventSet  --  The  PAPI EventSet to profile. This EventSet is marked as
49       profiling-ready,  but  profiling  doesn't  actually   start   until   a
50       PAPI_start() call is issued.
51
52       EventCode  --  Code of the Event in the EventSet to profile. This event
53       must already be a member of the EventSet.
54
55       threshold -- minimum number of events that must occur before the PC  is
56       sampled.  If  hardware  overflow  is supported for your substrate, this
57       threshold will trigger an interrupt when reached.  Otherwise, the coun‐
58       ters  will  be sampled periodically and the PC will be recorded for the
59       first sample that exceeds the threshold. If the value of  threshold  is
60       0, profiling will be disabled for this event.
61
62
63       flags  -- bit pattern to control profiling behavior. Defined values are
64       given in a table in the documentation for PAPI_pofil(3)
65
66

RETURN VALUES

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

ERRORS

73       Error returns for PAPI_sprofil() are identical to those  for  PAPI_pro‐
74       fil(3) Please refer to that page for further details.
75
76

EXAMPLES

78       int retval;
79       unsigned long length;
80       PAPI_exe_info_t *prginfo;
81       unsigned short *profbuf1, *profbuf2, profbucket;
82       PAPI_sprofil_t sprof[3];
83
84       if ((prginfo = PAPI_get_executable_info()) == NULL)
85         handle_error(1);
86
87       length = (unsigned long)(prginfo->text_end - prginfo->text_start);
88
89       /* Allocate 2 buffers of equal length */
90       profbuf1 = (unsigned short *)malloc(length);
91       profbuf2 = (unsigned short *)malloc(length);
92       if ((profbuf1 == NULL) || (profbuf2 == NULL))
93         handle_error(1);
94       memset(profbuf1,0x00,length);
95       memset(profbuf2,0x00,length);
96
97       /* First buffer */
98       sprof[0].pr_base = profbuf1;
99       sprof[0].pr_size = length;
100       sprof[0].pr_off = (caddr_t) DO_FLOPS;
101       sprof[0].pr_scale = 0x10000;
102
103       /* Second buffer */
104       sprof[1].pr_base = profbuf2;
105       sprof[1].pr_size = length;
106       sprof[1].pr_off = (caddr_t) DO_READS;
107       sprof[1].pr_scale = 0x10000;
108
109       /* Overflow bucket */
110       sprof[2].pr_base = profbucket;
111       sprof[2].pr_size = 1;
112       sprof[2].pr_off = 0;
113       sprof[2].pr_scale = 0x0002;
114
115       if ((retval = PAPI_sprofil(sprof, EventSet, PAPI_FP_INS, 1000000,
116                        PAPI_PROFIL_POSIX | PAPI_PROFIL_BUCKET_16)) != PAPI_OK)
117         handle_error(retval);
118
119

BUGS

121       These functions have no known bugs.
122
123