1PAPI_derived_event_files(1) PAPI PAPI_derived_event_files(1)
2
6 PAPI_derived_event_files - Describes derived event definition file
7 syntax.
8
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 This page documents the syntax of the commands which can appear in an
20 event definition file.
21 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 PRESET,<eventName>,<derivedType>,<eventAttr>,LDESC,"<longDesc>",SDESC,"<shortDesc>",NOTE,"<note>"
43 Declare a PAPI preset derived event.
44 EVENT,<eventName>,<derivedType>,<eventAttr>,LDESC,"<longDesc>",SDESC,"<shortDesc>",NOTE,"<note>"
46 Declare a user defined derived event.
47 Where:
49 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 eventName:
56 Specifies the name used to identify this derived event. This name
57 should be unique within the events on your system.
58 derivedType:
60 Specifies the kind of derived event being defined (see 'Derived
61 Types' below).
62 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 longDesc:
69 Provides the long description of the event.
70 shortDesc:
72 Provides the short description of the event.
73 note:
75 Provides an event note.
76 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 NOT_DERIVED (<baseEvent>):
99 This derived type defines an alias for the existing event
100 'baseEvent'.
101 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 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 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 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 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 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 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 • # 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 7.0.1.0 Thu Jul 20 2023 00:00:00PAPI_derived_event_files(1)