PAPI PRESET Events
A Maintenance Guide
Preset events, also known as predefined events, are a common set of events deemed relevant and useful for application performance tuning. These events are typically found in many CPUs that provide performance counters and give access to the memory hierarchy, cache coherence protocol events, cycle and instruction counts, functional unit, and pipeline status. Furthermore, preset events are mappings from symbolic names (PAPI preset name) to machine specific definitions (native countable events) for a particular hardware resource. For example, Total Cycles (in user mode) is PAPI_TOT_CYC. Also, PAPI supports presets that may be derived from the underlying hardware metrics. For example, Total L1 Cache Misses (PAPI_L1_TCM) might be the sum of L1 Data Misses and L1 Instruction Misses on a given platform. A preset can be either directly available as a single counter, derived using a combination of counters, or unavailable on any particular platform.
The PAPI library names approximately 100 preset events, which are defined in the header file, papiStdEventDefs.h. For a given platform, a subset of these preset events can be counted through either a simple high-level programming interface or a more complete C or Fortran low-level interface. A table of the currently defined preset events can be found here. To determine exactly which preset events are available on a specific platform, run the papi_avail utility in the papi source distribution.
The exact semantics of an event are platform dependent. PAPI preset names are mapped onto available events so as to map as many countable events as possible on different platforms. Due to hardware implementation differences, it is not necessarily feasible to directly compare the counts of a particular PAPI preset event obtained on different hardware platforms.
The Event Definition File
The definitions of PRESET events are stored in a comma-separated-values (csv) text file called papi_events.csv. The csv format is commonly used to represent data arranged in rows and columns, such as a spreadsheet like Microsoft Excel. Each column in a row is separated by a comma from the next column, and rows are separated by line endings including CR, LF, or CRLF. csv files are human readable, can be edited with any text editor, and can be loaded into any application, such as Excel, that recognizes the format. The papi_events.csv file contains PRESET event definitions for all common cpus supported by PAPI.
Event tables are prefaced by one or more CPU names that are matched internally to PAPI to find the set of events appropriate for a given CPU. If there is more that one CPU name, they act as synonyms. There can also be more than one table with the same name. In such cases, the second table overrides or appends to the contents of the first table. With this feature, common tables for multiple similar architectures, such as Intel SandyBridge and IvyBridge, can be augmented with event definitions specific to a given architecture. Event tables consist of a series of event definitions as described below.
Specifying PRESET event definitions
The general format of the event table entries consists of comment rows, CPU identifier rows, and PRESET definition rows. These rows are further defined below:
PRESET,PAPI_SP_OPS,DERIVED_POSTFIX,N0|N1|4|*|N2|8|*|+|+|,FP_COMP_OPS_EXE:SSE_FP_SCALAR_SINGLE,FP_COMP_OPS_EXE:SSE_PACKED_SINGLE,SIMD_FP_256:PACKED_SINGLE This definition multiplies the second operator (FP_COMP_OPS_EXE:SSE_PACKED_SINGLE) by 4 and multiplies the third operator (SIMD_FP_256:PACKED_SINGLE) by eight and then adds these two values to the first operator (FP_COMP_OPS_EXE:SSE_FP_SCALAR_SINGLE) to form the sum of all single precision floating point operations for Intel SandyBridge.
Loading a papi_events.csv File
By default, the PAPI configuration script uses a simple shell script to convert the papi_events.csv file into a properly formed c header file, papi_events_table.h, which contains the PRESET event definitions. This file is then included in papi_libpfm_presets.c to provide built-in definitions for PRESET events. If you wish to load PRESET definitions at runtime instead of compile time, you have several options:
The csv data format is a handy and useful way to define PRESET events for PAPI cpu components. It’s also flexible enough to allow you to test alternate definitions for many basic PAPI events. Many of the principles behind the definition of DERIVED events for PAPI PRESETS are also applicable for USER DEFINED events as well. Future directions for PRESET events may include expanding the existing table of events for cpus, or extending the PRESET model to other component domains.