PAPI_derived_event_files(5)

📦
version 7.2.0 · 4 versions
, in ubuntu resolute, ubuntu stonking

💅 NAME 💅

PAPI_derived_event_files — okay so this page is literally the whole guide to the syntax of derived event definition files. That's the vibe. 🎀

🦋 Derived Events 🦋

Bestie. PAPI has this iconic ability to let you define events whose value gets derived from multiple native events. The list of native events you wanna use, plus a formula describing how to combine them, lives in an event definition file. ✨

The PAPI team ships one event definition file that describes all of the supported PAPI preset events. PAPI also lets you hand over an event definition file describing a set of user defined events that can extend the events PAPI normally supports. Main character energy fr fr. 👑

This page documents the syntax of the commands that can show up in an event definition file. Let's gooo. 🌸

✨ General Rules ✨

Lowkey the ground rules first, no cap:

  • Blank lines are ignored. 🫥
  • Lines that begin with # are comments — and yep, they're ignored too.
  • Names shown inside < > below represent values that must be provided by the user.
  • If a user provided value contains white space, it must be protected with quotes. Quotes are the security blanket, periodt. 🛡️

🎀 Commands 🎀

CPU,<pmuName>

Specifies a PMU name which controls if the PRESET and EVENT commands that follow this line should be processed. 👀

You can drop multiple CPU commands in a row without any PRESET or EVENT commands between them, and that gives you a list of PMU names that all the derived events after it will apply to.

  • When a PMU name in that list matches a PMU name known to the running system, the events that follow will be created. ✅
  • If none of the PMU names in the list match a PMU name on the running system, the events that follow will be ignored. 💀
  • When a new CPU command follows either a PRESET or an EVENT command, the PMU list gets rebuilt. Fresh start, bestie.

PRESET,<eventName>,<derivedType>,<eventAttr>,LDESC,"<longDesc>",SDESC,"<shortDesc>",NOTE,"<note>"

Declare a PAPI preset derived event. 👑

EVENT,<eventName>,<derivedType>,<eventAttr>,LDESC,"<longDesc>",SDESC,"<shortDesc>",NOTE,"<note>"

Declare a user defined derived event. 🫶

📝 Where:

  • pmuName — the PMU which the following events should apply to. You can get a list of PMU names your system supports by running papi_component_avail on your system. 🧚
  • eventName — the name used to identify this derived event. This name should be unique within the events on your system.
  • derivedType — the kind of derived event being defined (peep 'Derived Types' below). 🌈
  • eventAttr — a formula plus a list of base events that are used to compute the derived event's value. The syntax of this field depends on the derivedType you specified above (again, see 'Derived Types' below).
  • longDesc — the long description of the event. 📖
  • shortDesc — the short description of the event. 📝
  • note — an event note. 🗒️
  • baseEvent (used below) — identifies an event on which this derived event is based. This may be a native event (possibly with event masks), an already known preset event, or an already known user event. So many options, we love versatility. 💅

Notes

So the PRESET command has traditionally been used in the PAPI provided preset definition file. The EVENT command is the one intended for user defined event definition files. But plot twist — the code treats them the same, so they are interchangeable and both can be used in either event definition file. Slay. ✨

Derived Types

This describes the values allowed in the derivedType field of the PRESET and EVENT commands. It also shows the syntax of the eventAttr field for each derived type these commands support.

Okay so all of these derived events provide a list of one or more events that the derived event is based on (baseEvent). Some of them also give you a formula specifying how to compute the derived event's value using the baseEvents in the list. The supported derived types are below, and the syntax of the eventAttr parameter for each one is shown in parentheses. 🎀

  • NOT_DERIVED (<baseEvent>) — this derived type defines an alias for the existing event baseEvent.
  • DERIVED_ADD (<baseEvent1>,<baseEvent2>) — this derived type defines a new event that will be the sum of two other events. It has a value of baseEvent1 plus baseEvent2. Math is mathing. ➕
  • DERIVED_PS (PAPI_TOT_CYC,<baseEvent1>) — this derived type defines a new event that will report the number of baseEvent1 events which occurred per second. It has a value of ((('baseEvent1' * cpu_max_mhz) * 1000000 ) / PAPI_TOT_CYC). The user must provide PAPI_TOT_CYC as the first event of two events in the event list for this to work correctly. Don't skip that part, bestie, it's giving "required." ⏱️
  • DERIVED_ADD_PS (PAPI_TOT_CYC,<baseEvent1>,<baseEvent2>) — this derived type defines a new event that will add together two event counters and then report the number which occurred per second. It has a value of (((('baseEvent1' + baseEvent2) * cpu_max_mhz) * 1000000 ) / PAPI_TOT_CYC). The user must provide PAPI_TOT_CYC as the first event of three events in the event list for this to work correctly. Yes, three. Count them. 🧮
  • DERIVED_CMPD (<baseEvent1>,<baseEvent2) — this derived type works much like the NOT_DERIVED type. It is rarely used, and it looks like the code just returns a single value returned from the kernel. There is no calculation done to compute this event's value. Not sure why multiple input events seem to be needed to use this event type. Genuinely a mystery, iykyk. 🙈
  • DERIVED_SUB (<baseEvent1>,<baseEvent2>) — this derived type defines a new event that will be the difference between two other events. It has a value of baseEvent1 minus baseEvent2. ➖
  • DERIVED_POSTFIX (<pfFormula>,<baseEvent1>,<baseEvent2>, ... ,<baseEventn>) — this derived type defines a new event whose value is computed from several native events using a postfix (reverse polish notation) formula. Its value is the result of processing the postfix formula. The pfFormula is of the form 'N0|N1|N2|5|*|+|-|', where the | acts as a token separator and the tokens N0, N1, and N2 are place holders that represent baseEvent0, baseEvent1, and baseEvent2 respectively. 🧠
  • DERIVED_INFIX (<ifFormula>,<baseEvent1>,<baseEvent2>, ... ,<baseEventn>) — this derived type defines a new event whose value is computed from several native events using an infix (algebraic notation) formula. Its value is the result of processing the infix formula. The ifFormula is of the form 'N0-(N1+(N2*5))', where the tokens N0, N1, and N2 are place holders that represent baseEvent0, baseEvent1, and baseEvent2 respectively. Same energy, different notation. 🌈

Example

In the following example, the events PAPI_SP_OPS, USER_SP_OPS, and ALIAS_SP_OPS will all measure the same events and return the same value. They just demonstrate different ways to use the PRESET and EVENT event definition commands. Obsessed with a good demo tbh. 💖

  • # The following lines define pmu names that all share the following events
  • CPU nhm
  • CPU nhm-ex
  • # Events which should be defined for either of the above pmu types
  • PRESET,PAPI_TOT_CYC,NOT_DERIVED,UNHALTED_CORE_CYCLES
  • PRESET,PAPI_REF_CYC,NOT_DERIVED,UNHALTED_REFERENCE_CYCLES
  • PRESET,PAPI_SP_OPS,DERIVED_POSTFIX,N0|N1|3|*|+|,FP_COMP_OPS_EXE:SSE_SINGLE_PRECISION,FP_COMP_OPS_EXE:SSE_FP_PACKED,NOTE,'Using a postfix formula'
  • EVENT,USER_SP_OPS,DERIVED_INFIX,N0+(N1*3),FP_COMP_OPS_EXE:SSE_SINGLE_PRECISION,FP_COMP_OPS_EXE:SSE_FP_PACKED,NOTE,'Using the same formula in infix format'
  • EVENT,ALIAS_SP_OPS,NOT_DERIVED,PAPI_SP_OPS,LDESC,'Alias for preset event PAPI_SP_OPS'
  • # End of event definitions for above pmu names and start of a section for a new pmu name.
  • CPU snb
That's the whole page, bestie. Go forth and derive responsibly. 💅✨

And that's a wrap! This lil masterpiece is Version 7.2.0.0, dated Wed Jun 25 2025 19:17:03. Byeee! 🦋🎀💖

📦 where this page comes from