TutorialOptions

Introduction

Almost all hardware performance monitoring configuration registers offer bits or bit fields to set event options. In most cases, the options are optional but there also exist some events that require a specific option configuration to count at all. Since there is almost no explanation of the event options, I try to give a small tutorial how to use them with LIKWID and how they affect the counting behavior. A description of the options can be found at https://github.com/RRZE-HPC/likwid/wiki/DescOptions.

Setting of HPM event options

Since LIKWID 4, the list of available events and counters contains the supported options for counters. There are also some events that extend the supported counter options to limit the counting of the event or to configure it at all. Basically, setting options in LIKWID is rather simple, just add the option to a event/counter combination:

ARITH_DIVIDER_CYCLES:PMC0:EDGEDETECT:THRESHOLD=0x1

Without the options, this configures the counter register PMC0 to measure the clock cycles in which the divide unit is active. The options give the event a different meaning. With the EDGEDETECT option the counter should only increment at the transition from inactive to active divide unit and vice versa. The option THRESHOLD=0x1 further specifies the event that should only increment at the transition from inactive to active, hence when the event without options would increment by one or more cycles. To sum up, this event with options counts the number of divide operations. This can be used, for example, to measure the average latency for the divide operation.

Which options are supported for an event or counter

There are different knowledge bases for this information:

• likwid-perfctr -e:

[...]
PMC0, Core-local general purpose counters, EDGEDETECT|THRESHOLD|INVERT|KERNEL|ANYTHREAD|IN_TRANSACTION
[...]
UOPS_ISSUED_ANY, 0xE, 0x1, PMC
[...]
OFFCORE_RESPONSE_0_OPTIONS, 0xB7, 0x1, PMC, MATCH0|MATCH1
OFFCORE_RESPONSE_1_OPTIONS, 0xBB, 0x1, PMC, MATCH0|MATCH1
[...]

At first, the counters have a list of supported events EDGEDETECT|THRESHOLD|.... These options can be used with all events that can be measured by the counter, e.g. UOPS_ISSUED_ANY. Moreover, there are a few events that need options to work probably, like the OFFCORE_RESPONSE_*_OPTIONS events. These event specific options are listed behind the events, here MATCH0|MATCH1.

• Option lists in the Wiki: This wiki contains a page for each supported architecture with the supported events and how the option is programmed to the event. Just look at the sidebar in the wiki for your architecture.

Event options in performance groups

Performance groups are one of the main concepts of LIKWID. They ease the usage by calculating derived metrics from predefined event sets. Of course, it is possible to use options in the event sets inside performance groups. There is one thing to consider: If you set a counter option in the event set, the counter option also must be used in the formulas for the derived metrics. Example for an DIVIDE performance group:

SHORT Information about divide operations

EVENTSET
PMC0  ARITH_DIVIDER_CYCLES
PMC1:EDGEDETECT:THRESHOLD=0x1 ARITH_DIVIDER_CYCLES

METRICS
Avg. divide duration [cyc] PMC0/PMC1:EDGEDETECT:THRESHOLD=0x1

LONG:
Avg. divide duration [cyc] = ARITH_DIVIDER_CYCLES/ARITH_DIVIDER_CYCLES:EDGEDETECT:THRESHOLD=0x1

Altough LIKWID could purge all options before applying the formula so that we can write PMC0/PMC1, it is much clearer for other users to understand what is calculated exactly with this metric. It is also good style to add the options to the event for the formula description in the LONG section.