PAPI PRESET Events

A Maintenance Guide

Introduction

This introductory information is taken from the Preset Events Section of the PAPI Overview

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 papi_avail in the papi source distribution.

The exact semantics of an event counter 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.

Specifying PRESET event definitions

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. The general format of the file consists of comment rows, CPU identifier rows, and PRESET definition rows. These rows are further defined below:

• #
  defines a comment line; must appear in column 1. Anything after # until a line ending is ignored.

• CPU, <name>
  defines the beginning of a new CPU table. <name> can be any string and contain any ASCII character except commas and line endings. PAPI attempts to match <name> against an internal CPU name that is either hard-coded into the code or extracted from the operating system information. Multiple sequential lines of this format act as synonyms.

• PRESET, <event name>, <type>, [<RPN operators>], <native name>, …
  defines a PRESET event.
  • <event name> must match one of the predefined names from papiStdEventDefs.h.
  • <type> can be one of the following strings:
    • NOT_DERIVED requires a single <native name> operand and produces results identical to that native event.
    • DERIVED_ADD supports two or more <native name> operands and sums them to produce the result.
    • DERIVED_SUB supports two or more <native name> operands and subtracts all operands from the first to produce the result.
    • DERIVED_CMPD requires more than one <native name>, but the result tracks with the first event. This type is only used by Pentium 4.
    • DERIVED_POSTFIX is the only type that accepts and requires the <RPN operators> operand. It applies a string of specified Reverse Polish Notation operators to a collection of <native name> operands.
  • [<RPN operators>] is only applicable to the DERIVED_POSTFIX type as described above. This operand consists of a string of operand names, operators, small integer constants, and separator characters that are processed in RPN order. For example strings, examine the papi_events.csv file itself.
  • <native name> can be one or more valid names of native events, including applicable modifiers as defined by papi_native_avail for the hardware platform in question.

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:

• You can use the –with-papi-events = file option when you run configure. This causes PAPI to load the papi_events.csv file directly whenever PAPI is initialized. This can be particularly useful when developing and testing a new table of PRESET events for a newly supported hardware platform.
• You can define an environment variable to be the name of the csv file you want to use. For PAPI versions less than or equal to 4.2.0 the environment variable is PAPI_PERFMON_EVENT_FILE; for newer versions of PAPI the variable is PAPI_CSV_EVENT_FILE. This approach can be valuable if you are experimenting with alternate definitions of PRESET events for a given hardware platform, or just learning how to define complex events with, for example, the DERIVED_POSTFIX event type.

Summary

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.