From be858d6f864d3f8a116e2ef97d4cbee2ef262260 Mon Sep 17 00:00:00 2001 From: Ed Baker Date: Fri, 10 Jul 2026 16:12:23 -0700 Subject: [PATCH 1/4] readme: Add CounterType and ProgrammingRestriction Add documentation to describe event fields CounterType and ProgrammingRestriction. --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.md b/README.md index de2a5d89..9bfab4a1 100644 --- a/README.md +++ b/README.md @@ -236,6 +236,34 @@ disabled. [^counterhtoff_footnote]: See **NOTE** in the Intel® SDM section, "Architectural Performance Monitoring Version 3". +### CounterType + +Helps distinguish how the event counter must be configured and used. + +* `FIXED`: Fixed counters support a specific usage and have minimal reconfiguration support. They are typically programmed via the + `FIXED_CTR_CTRL` or `UNCORE_FIXED_CTR_CTRL` MSRs. Core event examples are instructions retired and unhalted core cycles. +* `PGMABLE`: Programmable counters are general purpose and can be programmed to count one of several events. This is typically + achieved by configuring MSRs such as `IA32_PERFEVTSEL` or `UNCORE_PERFEVTSEL`. +* `FREERUN`: Free running counters are always on and monotonically increase. Typically these counters are used by measuring the delta + between two counts. + +### ProgrammingRestriction + +Certain events do not follow the basic programming paradigm for the given `CounterType`. `ProgrammingRestriction` indicates +how to use the provided event attributes to program the event for collection. + +* `None`: The event follows the basic programming paradigm for the given `CounterType`. For Core `FIXED` events, + `FIXED_CTR_CTRL` MSRs must be used. For Core `PGMABLE` events, `PERFEVTSEL` must be used, and so on. +* `MSRIndex-UMask`: Applicable only to `PGMABLE` events. In addition to the normal `PGMABLE` programming constraints, + there is an additional MSR (indicated in `MSRIndex`) which must be configured with the value in `MSRValue`. If + there are several `UMask` entries, then `UMask[N]` and `MSRIndex[N]` are used to select which UMask to program, and + which MSR is written. Any of the `MSRIndex` entries is compatible with counters listed in counter fields. +* `MSRIndex-UMask-Counter`: Applicable only to `PGMABLE` events. In addition to the normal `PGMABLE` programming + constraints, there is an additional MSR (indicated in `MSRIndex`) which must be configured with the value in + `MSRValue`. While the `Counter` field may list multiple compatible GP counters, the `MSRIndex` and `UMask` are + strictly tied to which GP counter is being programmed. The `N`th GP counter must use `UMask[N]`, and write + `MSRValue` to `MSRIndex[N]`. + ### PEBScounters This field is only relevant to PEBS events. It lists the counters where the event can be sampled when it is programmed as a PEBS event. From f5a4e119a833f1afa6e4cebdc649069c556dd905 Mon Sep 17 00:00:00 2001 From: Ed Baker Date: Mon, 3 Aug 2026 08:55:57 -0700 Subject: [PATCH 2/4] Update README.md Co-authored-by: Ryan McLaughlin --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9bfab4a1..b9c00e47 100644 --- a/README.md +++ b/README.md @@ -256,8 +256,9 @@ how to use the provided event attributes to program the event for collection. `FIXED_CTR_CTRL` MSRs must be used. For Core `PGMABLE` events, `PERFEVTSEL` must be used, and so on. * `MSRIndex-UMask`: Applicable only to `PGMABLE` events. In addition to the normal `PGMABLE` programming constraints, there is an additional MSR (indicated in `MSRIndex`) which must be configured with the value in `MSRValue`. If - there are several `UMask` entries, then `UMask[N]` and `MSRIndex[N]` are used to select which UMask to program, and - which MSR is written. Any of the `MSRIndex` entries is compatible with counters listed in counter fields. + there are multiple `UMask` entries, then `UMask` and `MSRIndex` should be used paired in their specified order. + An event configured with the `N`th UMask, `UMask[N]` must write `MSRValue` to the MSR indicated at the `N`th MSRIndex, `MSRIndex[N]` . + Any of the `MSRIndex` entries is compatible with counters listed in counter fields. * `MSRIndex-UMask-Counter`: Applicable only to `PGMABLE` events. In addition to the normal `PGMABLE` programming constraints, there is an additional MSR (indicated in `MSRIndex`) which must be configured with the value in `MSRValue`. While the `Counter` field may list multiple compatible GP counters, the `MSRIndex` and `UMask` are From 6662f91e2dbfb442ea9ebea6364ab31e2fe4acdc Mon Sep 17 00:00:00 2001 From: Ed Baker Date: Tue, 4 Aug 2026 08:29:38 -0700 Subject: [PATCH 3/4] readme: Add ProgrammingRestriction example Add a markdown diagram to showcase a few programming restriction valid and invalid examples. Co-authored-by: Ryan McLaughlin --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/README.md b/README.md index b9c00e47..c84bc5a6 100644 --- a/README.md +++ b/README.md @@ -265,6 +265,71 @@ how to use the provided event attributes to program the event for collection. strictly tied to which GP counter is being programmed. The `N`th GP counter must use `UMask[N]`, and write `MSRValue` to `MSRIndex[N]`. +#### Examples + +```mermaid +flowchart + %% Example showcasing MSRIndex-UMask programming restriction. + MUX(MSRIndex-UMask + UMask: A,B + MSRIndex: C,D + Counter: 0,1) + + MUX_valid_1[Valid Programming + UMask: A + MSRIndex: C + Counter: 0,1] + + MUX_valid_2[Valid Programming + UMask: B + MSRIndex: D + Counter: 0,1] + + MUX_invalid[Invalid Programming + UMask: A + MSRIndex: D + Counter: 0,1] + + MUX --> MUX_valid_1 + MUX --> MUX_valid_2 + MUX -.-> MUX_invalid + + %% Example showcasing MSRIndex-UMask-Counter programming restriction. + MUCX(MSRIndex-UMask-Counter + UMask: A,B + MSRIndex: C,D + Counter: 0,1) + + MUCX_valid_1[Valid Programming + UMask: A + MSRIndex: C + Counter: 0] + + MUCX_valid_2[Valid Programming + UMask: B + MSRIndex: D + Counter: 1] + + MUCX_invalid[Invalid Programming + UMask: A + MSRIndex: C + Counter: 1] + + MUCX --> MUCX_valid_1 + MUCX --> MUCX_valid_2 + MUCX -.-> MUCX_invalid + + %% Style nodes for JSON event content, valid programming, and invalid programming. Colors are + %% from https://github.com/yeun/open-color. + classDef json stroke:#495057,stroke-width:2px + classDef valid stroke:#0ca678,stroke-width:2px + classDef invalid stroke:#f03e3e,stroke-width:2px + + class MUX,MUCX json + class MUX_valid_1,MUX_valid_2,MUCX_valid_1,MUCX_valid_2 valid + class MUX_invalid,MUCX_invalid invalid +``` + ### PEBScounters This field is only relevant to PEBS events. It lists the counters where the event can be sampled when it is programmed as a PEBS event. From f7ecd5afec3344abedbb6ca8040d2d16cef4dce8 Mon Sep 17 00:00:00 2001 From: Ed Baker Date: Fri, 7 Aug 2026 11:16:36 -0700 Subject: [PATCH 4/4] README: Update ProgrammingRestriction Update documentation. Co-authored-by: Ryan McLaughlin --- README.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index c84bc5a6..520a1be5 100644 --- a/README.md +++ b/README.md @@ -249,21 +249,18 @@ Helps distinguish how the event counter must be configured and used. ### ProgrammingRestriction -Certain events do not follow the basic programming paradigm for the given `CounterType`. `ProgrammingRestriction` indicates -how to use the provided event attributes to program the event for collection. - -* `None`: The event follows the basic programming paradigm for the given `CounterType`. For Core `FIXED` events, - `FIXED_CTR_CTRL` MSRs must be used. For Core `PGMABLE` events, `PERFEVTSEL` must be used, and so on. -* `MSRIndex-UMask`: Applicable only to `PGMABLE` events. In addition to the normal `PGMABLE` programming constraints, - there is an additional MSR (indicated in `MSRIndex`) which must be configured with the value in `MSRValue`. If - there are multiple `UMask` entries, then `UMask` and `MSRIndex` should be used paired in their specified order. - An event configured with the `N`th UMask, `UMask[N]` must write `MSRValue` to the MSR indicated at the `N`th MSRIndex, `MSRIndex[N]` . - Any of the `MSRIndex` entries is compatible with counters listed in counter fields. -* `MSRIndex-UMask-Counter`: Applicable only to `PGMABLE` events. In addition to the normal `PGMABLE` programming - constraints, there is an additional MSR (indicated in `MSRIndex`) which must be configured with the value in - `MSRValue`. While the `Counter` field may list multiple compatible GP counters, the `MSRIndex` and `UMask` are - strictly tied to which GP counter is being programmed. The `N`th GP counter must use `UMask[N]`, and write - `MSRValue` to `MSRIndex[N]`. +Certain events do not follow the basic programming paradigm for the given `CounterType`. `ProgrammingRestriction` +indicates how to use the provided event attributes to program the event for collection. + +* `None`: The event follows the basic programming paradigm for its `CounterType`. For example, Core `FIXED` events + are configured through `FIXED_CTR_CTRL` MSRs, while Core `PGMABLE` events are configured through `PERFEVTSEL` MSRs. +* `MSRIndex-UMask`: Applies only to `PGMABLE` events. In addition to standard `PGMABLE` programming requirements, write + the `MSRValue` to the extra MSR specified in `MSRIndex` based on the `UMask`. `UMask`, and `MSRIndex` entries + correspond by position; programming UMask[N] requires programming MSRIndex[N] with `MSRValue`. +* `MSRIndex-UMask-Counter`: Applies only to `PGMABLE` events. In addition to standard `PGMABLE` programming + requirements, write the `MSRValue` to the extra MSR specified in `MSRIndex` based on the chosen `Counter`. `Counter`, + `UMask`, and `MSRIndex` entries correspond by position. Program the Nth `Counter` with UMask[N], and MSRIndex[N] with + `MSRValue`. #### Examples