1PAPI_derived_event_files(1)          PAPI          PAPI_derived_event_files(1)
2
3
4

NAME

6       PAPI_derived_event_files - Describes derived event definition file
7       syntax.
8

Derived Events

10       PAPI provides the ability to define events whose value will be derived
11       from multiple native events. The list of native events to be used in a
12       derived event and a formula which describes how to use them is provided
13       in an event definition file. The PAPI team provides an event definition
14       file which describes all of the supported PAPI preset events. PAPI also
15       allows a user to provide an event definition file that describes a set
16       of user defined events which can extend the events PAPI normally
17       supports.
18
19       This page documents the syntax of the commands which can appear in an
20       event definition file.
21
22   General Rules:
23       • Blank lines are ignored.
24       • Lines that begin with '#' are comments (they are also ignored).
25       • Names shown inside < > below represent values that must be provided
26         by the user.
27       • If a user provided value contains white space, it must be protected
28         with quotes.
29   Commands:
30       CPU,<pmuName>
31           Specifies a PMU name which controls if the PRESET and EVENT
32           commands that follow this line should be processed. Multiple CPU
33           commands can be entered without PRESET or EVENT commands between
34           them to provide a list of PMU names to which the derived events
35           that follow will apply. When a PMU name provided in the list
36           matches a PMU name known to the running system, the events which
37           follow will be created. If none of the PMU names provided in the
38           list match a PMU name on the running system, the events which
39           follow will be ignored. When a new CPU command follows either a
40           PRESET or EVENT command, the PMU list is rebuilt.
41
42       PRESET,<eventName>,<derivedType>,<eventAttr>,LDESC,"<longDesc>",SDESC,"<shortDesc>",NOTE,"<note>"
43           Declare a PAPI preset derived event.
44
45       EVENT,<eventName>,<derivedType>,<eventAttr>,LDESC,"<longDesc>",SDESC,"<shortDesc>",NOTE,"<note>"
46           Declare a user defined derived event.
47
48       Where:
49
50       pmuName:
51           The PMU which the following events should apply to. A list of PMU
52           names supported by your system can be obtained by running
53           papi_component_avail on your system.
54
55       eventName:
56           Specifies the name used to identify this derived event. This name
57           should be unique within the events on your system.
58
59       derivedType:
60           Specifies the kind of derived event being defined (see 'Derived
61           Types' below).
62
63       eventAttr:
64           Specifies a formula and a list of base events that are used to
65           compute the derived events value. The syntax of this field depends
66           on the 'derivedType' specified above (see 'Derived Types' below).
67
68       longDesc:
69           Provides the long description of the event.
70
71       shortDesc:
72           Provides the short description of the event.
73
74       note:
75           Provides an event note.
76
77       baseEvent (used below):
78           Identifies an event on which this derived event is based. This may
79           be a native event (possibly with event masks), an already known
80           preset event, or an already known user event.
81   Notes:
82       The PRESET command has traditionally been used in the PAPI provided
83       preset definition file. The EVENT command is intended to be used in
84       user defined event definition files. The code treats them the same so
85       they are interchangeable and they can both be used in either event
86       definition file.
87   Derived Types:
88       This describes values allowed in the 'derivedType' field of the PRESET
89       and EVENT commands. It also shows the syntax of the 'eventAttr' field
90       for each derived type supported by these commands. All of the derived
91       events provide a list of one or more events which the derived event is
92       based on (baseEvent). Some derived events provide a formula that
93       specifies how to compute the derived events value using the baseEvents
94       in the list. The following derived types are supported, the syntax of
95       the 'eventAttr' parameter for each derived event type is shown in
96       parentheses.
97
98       NOT_DERIVED (<baseEvent>):
99           This derived type defines an alias for the existing event
100           'baseEvent'.
101
102       DERIVED_ADD (<baseEvent1>,<baseEvent2>):
103           This derived type defines a new event that will be the sum of two
104           other events. It has a value of 'baseEvent1' plus 'baseEvent2'.
105
106       DERIVED_PS (PAPI_TOT_CYC,<baseEvent1>):
107           This derived type defines a new event that will report the number
108           of 'baseEvent1' events which occurred per second. It has a value of
109           ((('baseEvent1' * cpu_max_mhz) * 1000000 ) / PAPI_TOT_CYC). The
110           user must provide PAPI_TOT_CYC as the first event of two events in
111           the event list for this to work correctly.
112
113       DERIVED_ADD_PS (PAPI_TOT_CYC,<baseEvent1>,<baseEvent2>):
114           This derived type defines a new event that will add together two
115           event counters and then report the number which occurred per
116           second. It has a value of (((('baseEvent1' + baseEvent2) *
117           cpu_max_mhz) * 1000000 ) / PAPI_TOT_CYC). The user must provide
118           PAPI_TOT_CYC as the first event of three events in the event list
119           for this to work correctly.
120
121       DERIVED_CMPD (<baseEvent1>,<baseEvent2):
122           This derived type works much like the NOT_DERIVED type. It is
123           rarely used and it looks like the code just returns a single value
124           returned from the kernel. There is no calculation done to compute
125           this events value. Not sure why multiple input events seem to be
126           needed to use this event type.
127
128       DERIVED_SUB (<baseEvent1>,<baseEvent2>):
129           This derived type defines a new event that will be the difference
130           between two other events. It has a value of 'baseEvent1' minus
131           'baseEvent2'.
132
133       DERIVED_POSTFIX (<pfFormula>,<baseEvent1>,<baseEvent2>, ...
134       ,<baseEventn>):
135           This derived type defines a new event whose value is computed from
136           several native events using a postfix (reverse polish notation)
137           formula. Its value is the result of processing the postfix formula.
138           The 'pfFormula' is of the form 'N0|N1|N2|5|*|+|-|' where the '|'
139           acts as a token separator and the tokens N0, N1, and N2 are place
140           holders that represent baseEvent0, baseEvent1, and baseEvent2
141           respectively.
142
143       DERIVED_INFIX (<ifFormula>,<baseEvent1>,<baseEvent2>, ...
144       ,<baseEventn>):
145           This derived type defines a new event whose value is computed from
146           several native events using an infix (algebraic notation) formula.
147           Its value is the result of processing the infix formula. The
148           'ifFormula' is of the form 'N0-(N1+(N2*5))' where the tokens N0,
149           N1, and N2 are place holders that represent baseEvent0, baseEvent1,
150           and baseEvent2 respectively.
151   Example:
152       In the following example, the events PAPI_SP_OPS, USER_SP_OPS, and
153       ALIAS_SP_OPS will all measure the same events and return the same
154       value. They just demonstrate different ways to use the PRESET and EVENT
155       event definition commands.
156
157       • # The following lines define pmu names that all share the following
158         events
159       • CPU nhm
160       • CPU nhm-ex
161       • # Events which should be defined for either of the above pmu types
162       • PRESET,PAPI_TOT_CYC,NOT_DERIVED,UNHALTED_CORE_CYCLES
163       • PRESET,PAPI_REF_CYC,NOT_DERIVED,UNHALTED_REFERENCE_CYCLES
164       • 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
165         a postfix formula'
166       • 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
167         the same formula in infix format'
168       • EVENT,ALIAS_SP_OPS,NOT_DERIVED,PAPI_SP_OPS,LDESC,'Alias for preset
169         event PAPI_SP_OPS'
170       • # End of event definitions for above pmu names and start of a section
171         for a new pmu name.
172       • CPU snb
173Version 6.0.0.0                 Thu Jan 28 2021    PAPI_derived_event_files(1)
Impressum