17. Information for Experts

17.1. Hardware Counter Event Names

HPCToolkit uses libpfm4 (Libpfm4 2008) to translate from an event name string to an event code recognized by the kernel. An event name is case insensitive and is defined as followed:

[pmu::][event_name][:unit_mask][:modifier|:modifier=val]

• pmu. Optional name of the PMU (group of events) to which the event belongs to. This is useful to disambiguate events in case events from difference sources have the same name. If no pmu is specified, the first match event is used.

• event_name. The name of the event. It must be the complete name, partial matches are not accepted.

• unit_mask. Some events can be refined using sub-events. A unit_mask designates an optional sub-event. An event may have multiple unit masks and it is possible to combine them (for some events) by repeating :unit_mask pattern.

• modifier. A modifier is an optional filter that restricts when an event counts. The form of a modifier may be either :modifier or :modifier=val. For modifiers without a value, the presence of the modifier is interpreted as a restriction. Events may allow use of multiple modifiers at the same time.

  • hardware event modifiers. Some hardware events support one or more modifiers that restrict counting to a subset of events. For instance, on an Intel Broadwell EP, one can add a modifier to MEM_LOAD_UOPS_RETIRED to count only load operations that are an L2_HIT or an L2_MISS. For information about all modifiers for hardware events, one can direct HPCToolkit’s measurement subsystem to list all native events and their modifiers as described in Section 6.1.

  • precise_ip. For some events, it is possible to control the amount of skid. Skid is a measure of how many instructions may execute between an event and the PC where the event is reported. Smaller skid enables more accurate attribution of events to instructions. Without a skid modifier, hpcrun allows arbitrary skid because some architectures don’t support anything more precise. One may optionally specify one of the following as a skid modifier:

    • :p : a sample must have constant skid.

    • :pp : a sample is requested to have 0 skid.

    • :ppp : a sample must have 0 skid.

    • :P : autodetect the least skid possible.

    NOTE: If the kernel or the hardware does not support the specified value of the skid, no error message will be reported but no samples will be recorded.

17.1.1. Examples

Assume running hpcrun with the following arguments:

$ hpcrun -e UOPS_RETIRED:MS:c=1:e=1:pp  my_program

The above command will run my_program with the UOPS_RETIRED:MS event enabled with precise IP and no skid. The hardware profiling event UOPS_RETIRED:MS:c=1:e=1 counts the number of times a block of code stalls or falls back to the processor’s Microcode Sequencer (MSROM) to execute complex instructions or handle performance faults (assists).

Event Breakdown

• UOPS_RETIRED: Tracks the micro-operations (uops) that successfully complete execution. Modern Intel processors break down complex software instructions into simpler, hardware-level uops.

• :MS: Filters the uops specifically to those issued by the Microcode Sequencer.

• :c=1: A condition (or duration threshold) that counts the number of cycles where at least one MS uop was retired.

• :e=1: An edge trigger that counts the actual occurrences or transitions of this condition, preventing a continuous stream of MS uops from being counted as a single prolonged event.

• :pp: Request precise IP and no skid.