How do I use raw events with perf?

perf, effectively, is a tracing tool and can trace userspace, kernelspace, and hardware events. Hardware events can be things like the count of instructions ran in a second, the count of page faults in a second, etc. These hardware events are typically exposed from the physical CPU known as Performance Monitoring Counters (PMC) or Performance Monitoring Unit (PMU).

Most every CPU exposes a large amount of these PMUs for any operating system to pull from. Most of the time, you can list out the PMUs available to trace with perf list:

$ perf list | head -3
  branch-instructions OR branches                    [Hardware event]
  branch-misses                                      [Hardware event]
  cache-misses                                       [Hardware event]

These are the symbolic name for those events, which are far easier to read by humans and understand what the PMU counts.

The symbolic names are derived from either the sysfs or from the json files in the kernel source. The kernel may also expose certain PMUs in sysfs. If so, those PMUs can be found by their symbolic name under /sys/devices/cpu/events/:

# ls /sys/devices/cpu/events/ | head -3
branch-instructions
branch-misses
cache-misses

Perf can also parse the json files for the PMUs and information on how to access the PMUs found under tools/perf/pmu-events in the kernel source code. This is organized by architecture and then CPU family. Within the json files, the description of the PMU is found along with all the necessary identifiers needed for perf to open the relevant PMU on the CPU:

 $ head -20 tools/perf/pmu-events/arch/x86/sapphirerapids/cache.json
[
    {
        "BriefDescription": "L1D.HWPF_MISS",
        "Counter": "0,1,2,3",
        "EventCode": "0x51",
        "EventName": "L1D.HWPF_MISS",
        "SampleAfterValue": "1000003",
        "UMask": "0x20"
    },
    {
        "BriefDescription": "Counts the number of cache lines replaced in L1 data cache.",
        "Counter": "0,1,2,3",
        "EventCode": "0x51",
        "EventName": "L1D.REPLACEMENT",
        "PublicDescription": "Counts L1D data line replacements including opportunistic replacements, and replacements that require stall-for-replace or block-for-replace.",
        "SampleAfterValue": "100003",
        "UMask": "0x1"
    },
    {
        "BriefDescription": "Number of cycles a demand request has waited due to L1D Fill Buffer (FB) unavailability.",

If perf list does not list out expected PMUs to monitor, check the kernel source code to determine if the kernel version in question has added the symbolic names for perf (below is an example checking for Saphhire Rapid CPUs from Intel):

$ git log --grep 'perf vendor events.*Sapphire' --oneline | bat
───────┬───────────────────────────────────────────────────────────────────────
       │ STDIN
───────┼───────────────────────────────────────────────────────────────────────
   1   │ 90e9b0b0de82 perf vendor events intel: Update event list for Sapphirer
       │ apids
   2   │ 5d1063ef4aa7 perf vendor events intel: Add metrics for Sapphirerapids
   3   │ f653ab15de12 perf vendor events intel: Add uncore event list for Sapph
       │ irerapids
   4   │ da2675214b00 perf vendor events intel: Update core event list for Sapp
       │ hirerapids
───────┴───────────────────────────────────────────────────────────────────────

If not, it is worthwhile to ensure the desired PMUs exist for the CPU and it is exposed for the OS to pull from. For this, you can provide the raw PMU name to perf to check. The raw PMU name is always "r + UMask + EventCode" where UMask and EventCode are found from the json files potentially found upstream. For example, to record all code reads from L2 cache on a CPU, the json file is checked;

$ grep -e "EventName.*L2_RQSTS" -e EventCode -e UMask tools/perf/pmu-events/arch/x86/sapphirerapids/cache.json | grep -A 2 L2_RQSTS.ALL_CODE_RD        
        "EventName": "L2_RQSTS.ALL_CODE_RD",
        "UMask": "0xe4"
        "EventCode": "0x24",

The above means the raw event name is re424:

# perf stat -e re424 -- ls > /dev/null

 Performance counter stats for 'ls':

             6,484      re424  

       0.007828835 seconds time elapsed

       0.000000000 seconds user
       0.007902000 seconds sys

A malformed or incorrect raw event name will fail with "No such file or directory";

# perf stat r9999 -- ls > /dev/null
Workload failed: No such file or directory