PAPI_profil(3)

💖 NAME 💖

PAPI_profil — bestie, this one generates a histogram of hardware counter overflows vs. PC addresses. That's the whole vibe. ✨

Oh and hey, this is from the PAPI manual section 3 — welcome to the PAPI_profil(3) page, grab a snack. 🍓

---

✨ SYNOPSIS ✨

Detailed 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

ngl the profiling routines have no Fortran interface. That's it, that's the whole section. 😭

Parameters

• *buf — pointer to a buffer of bufsiz bytes where the histogram counts live, stored as an array of unsigned short, unsigned int, or unsigned long long values, aka 'buckets'. The size of the buckets is decided by the values in the flags argument. 🎀
• bufsiz — the size of the histogram buffer in bytes. It's computed from the length of the code region you're profiling, the size of the buckets, and the scale factor, as discussed further down.
• offset — the start address of the region to be profiled.
• scale — broadly and historically speaking, a contraction factor that shows how much smaller the histogram buffer is than the region being 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 there's a whole table of representative values for scale. 💅
• EventSet — the PAPI EventSet to profile. This EventSet gets marked as profiling-ready, but profiling doesn't actually start until a PAPI_start() call is issued. Like, it's ready, it's just not going yet, yk?
• EventCode — code of the Event in the EventSet to profile. This event has to already be a member of the EventSet. No gatecrashing. 🚫
• threshold — minimum number of events that must occur before the PC is sampled. If hardware overflow is supported for your component, this threshold triggers an interrupt when it's reached. Otherwise, the counters get sampled periodically and the PC is recorded for the first sample that exceeds the threshold. If threshold is 0, profiling is disabled for this event. ✨
• flags — bit pattern controlling profiling behavior. Defined values are shown in the table further down.

Return values

• PAPI_OK — iconic, everything worked. 👑
• 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. 💀

---

🌸 DESCRIPTION 🌸

PAPI_profil() provides hardware event statistics by profiling the occurrence of specified hardware counter events. It's designed to mimic the UNIX SVR4 profil call — yes, it's giving vintage, but make it PAPI. 💜

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 that identified region is logically broken up into a set of equal size subdivisions, each of which corresponds to a count in the histogram. Cute, right? It's a little grid of code. 🎀

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 occurring in each code subdivision. Slay. 🔥

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 — i.e. the main character addresses. 👑

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 📊

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

(Heads up: the original table's column header is spelled DEFININTION — iconic typo, we stan, but the meanings above are exactly what it lists.)

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. rip to those samples, they were brave 🫡
• 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

iykyk, go read those next bestie 💖

---

🎀 AUTHOR 🎀

Generated automatically by Doxygen for PAPI from the source code. (Not a human, just a robot doing its little robot thing. Respect.) 🤖

---

aaaand that's the page! 💅 This was PAPI_profil(3) from PAPI Version 7.2.0.0, dated Wed Jun 25 2025 19:30:48 — mwah, go profile something gorgeous 🫶✨🌸