NAME

       PAPI_derived_event_files - Describes derived event definition file syntax.

Derived Events

       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.

   General Rules:
       • Blank lines are ignored.
       • Lines that begin with '#' are comments (they are also ignored).
       • 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.
   Commands:
       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:
           Provides 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.
   Notes:
       The PRESET command has traditionally been used in the PAPI provided preset definition
       file. The EVENT command is intended to be used in user defined event definition files. The
       code treats them the same so they are interchangeable and they can both be used in either
       event definition file.
   Derived Types:
       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.
   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.

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