PAPI provides the ability to define events whose value will be
derived from multiple native events. The list of native events to be used in
a derived event and a formula which describes how to use them is provided in
an event definition file. The PAPI team provides an event definition file
which describes all of the supported PAPI preset events. PAPI also allows a
user to provide an event definition file that describes a set of user
defined events which can extend the events PAPI normally supports.
This page documents the syntax of the commands which can appear in
an event definition file.
CPU,<pmuName>
Specifies a PMU name which controls if the PRESET and
EVENT commands that follow this line should be processed. Multiple CPU
commands can be entered without PRESET or EVENT commands between them to
provide a list of PMU names to which the derived events that follow will
apply. When a PMU name provided in the list matches a PMU name known to the
running system, the events which follow will be created. If none of the PMU
names provided in the list match a PMU name on the running system, the events
which follow will be ignored. When a new CPU command follows either a PRESET
or EVENT command, the PMU list is rebuilt.
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. A
list of PMU names supported by your system can be obtained by running
papi_component_avail on your system.
eventName:
Specifies the name used to identify this derived event.
This name should be unique within the events on your system.
derivedType:
Specifies the kind of derived event being defined (see
'Derived Types' below).
eventAttr:
Specifies a formula and a list of base events that are
used to compute the derived events value. The syntax of this field depends on
the 'derivedType' specified above (see 'Derived Types' below).
longDesc:
Provides the long description of the event.
shortDesc:
Provides the short description of the 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.
This describes 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 supported by these commands. All of the derived events
provide a list of one or more events which the derived event is based on
(baseEvent). Some derived events provide a formula that specifies how to
compute the derived events value using the baseEvents in the list. The
following derived types are supported, the syntax of the 'eventAttr'
parameter for each derived event type 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'.
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.
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.
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 events
value. Not sure why multiple input events seem to be needed to use this event
type.
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.