Skip to content

readme: Add core UMaskExt documentation #358

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
edwarddavidbaker wants to merge 3 commits into
base: main
Choose a base branch
from
Open

readme: Add core UMaskExt documentation #358

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9b2983d
readme: Add core UMaskExt documentation
edwarddavidbaker Dec 19, 2025
a64fe01
readme: Fixup event name and MSR
edwarddavidbaker Dec 19, 2025
b4b35f4
Merge remote-tracking branch 'origin/main' into update-readme-umaskext
edwarddavidbaker Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,9 +199,19 @@ is defined architecturally. Each value corresponds to an event logic unit and sh
mask value to obtain an architectural performance event.

### UMask
This field maps to the Unit Mask filed in the `IA32_PERFEVTSELx[15:8]` MSRs. It further qualifies the event logic
This field maps to the Unit Mask field in the `IA32_PERFEVTSELx[15:8]` MSRs. It further qualifies the event logic
unit selected in the event select field to detect a specific micro-architectural condition.

### UMaskExt (Core events)
This field maps to the Unit Mask 2 field in the `IA32_PERFEVTSELx[47:40]` MSRs. First introduced with architectural
performance monitoring version 6.

> These bits qualify the condition that the selected event logic unit detects. Valid UMASK2 values for each
event logic unit are specific to the unit. The new UMASK2 field may also be used in conjunction with UMASK.

:warning: `UMaskExt` will be renamed to `UMask2` to align with the Intel® SDM. Please refer to
https://github.com/intel/perfmon/issues/357 for additional information.

### EventName
It is a string of characters to identify the programming of an event.

Expand Down Expand Up @@ -237,7 +247,7 @@ This is useful in event-based sampling. This field gives a recommended default o
workload or tool preference.

### MSRIndex
Additional MSRs may be required for programming certain events. This field gives the address of such MSRS.
Additional MSRs may be required for programming certain events. This field gives the address of such MSRs.
Examples include:
* 0x3F6: MSR_PEBS_LD_LAT - used to configure the Load Latency Performance Monitoring Facility
* 0x1A6/0x1A7: MSR_OFFCORE_RSP_X - used to configure the offcore response events
Expand All @@ -253,7 +263,7 @@ Applies to processors that support both precise and non-precise events in **Proc
0. The event cannot be programmed to collect a PEBS record.
1. The event may be programmed to collect a PEBS record, but caution is advised. For instance, PEBS collection of this event may consume limited PEBS resources whereas interrupt-based sampling may be sufficient for the usage model.
2. The event may be programmed to collect a PEBS record, and due to the nature of the event, PEBS collection may be preferred. For instance,
PEBS collection of Goldmont's `HW_INTERUPTS.RECIEVED` event is recommended because the hardware interrupt being counted may lead to the masking of
PEBS collection of Goldmont's `HW_INTERRUPTS.RECEIVED` event is recommended because the hardware interrupt being counted may lead to the masking of
interrupts which would interfere with interrupt-based sampling.
3. The event must be programmed to collect a PEBS record.

Expand Down