{
  "id": "wire-format/perf-event-ring",
  "family": "wire-format",
  "slug": "perf-event-ring",
  "title": "perf_event_open ring buffer page (perf_event_mmap_page)",
  "summary": "The perf_event_open(2) syscall returns a file descriptor; mmap'ing it gives a shared memory region whose first page is a perf_event_mmap_page control structure. It contains the data_head/data_tail pointers (for the ring buffer), time conversion parameters (for converting hardware timestamps to nanoseconds), and capability bits.",
  "kind": "wire-format",
  "aliases": [
    "perf_event_open ring buffer page (perf_event_mmap_page)"
  ],
  "status": "standard",
  "verification": "verified",
  "tier": "B",
  "source_url": "https://www.kernel.org/doc/html/latest/",
  "source_version": "Linux kernel docs, retrieved 2026-05-29",
  "retrieved_date": "2026-05-29",
  "ext_type": "wire-format@1",
  "ext": {
    "spec": "Linux kernel (perf_event_open)",
    "summary": "The perf_event_open(2) syscall returns a file descriptor; mmap'ing it gives a shared memory region whose first page is a perf_event_mmap_page control structure. It contains the data_head/data_tail pointers (for the ring buffer), time conversion parameters (for converting hardware timestamps to nanoseconds), and capability bits.",
    "structure": [
      {
        "field": "version",
        "size": "4 bytes (__u32)",
        "meaning": "Version of the structure (current = 1)."
      },
      {
        "field": "compat_version",
        "size": "4 bytes (__u32)",
        "meaning": "Lowest compatible version."
      },
      {
        "field": "lock",
        "size": "4 bytes (__u32)",
        "meaning": "Seqlock for consistent reads of the time fields."
      },
      {
        "field": "index",
        "size": "8 bytes (__u64)",
        "meaning": "Hardware PMU counter index (if PERF_FORMAT_TOTAL_TIME_ENABLED)."
      },
      {
        "field": "offset",
        "size": "8 bytes (__u64)",
        "meaning": "Offset to add to the raw counter value."
      },
      {
        "field": "time_enabled",
        "size": "8 bytes (__u64)",
        "meaning": "Time the event was enabled (in nanoseconds)."
      },
      {
        "field": "time_running",
        "size": "8 bytes (__u64)",
        "meaning": "Time the event was running (accounts for multiplexing)."
      },
      {
        "field": "cap (union)",
        "size": "8 bytes",
        "meaning": "Capability bits: cap_usr_time, cap_usr_rdpmc, cap_bit0_is_deprecated, etc."
      },
      {
        "field": "pmc_width",
        "size": "2 bytes (__u16)",
        "meaning": "Width of the PMU counter in bits."
      },
      {
        "field": "time_shift",
        "size": "2 bytes (__u16)",
        "meaning": "Shift for time conversion: (time_enabled - time_zero) >> time_shift."
      },
      {
        "field": "time_mult",
        "size": "4 bytes (__u32)",
        "meaning": "Multiplier for time conversion."
      },
      {
        "field": "time_offset",
        "size": "8 bytes (__u64)",
        "meaning": "Offset for time conversion."
      },
      {
        "field": "time_zero",
        "size": "8 bytes (__u64)",
        "meaning": "Time base for conversion."
      },
      {
        "field": "size",
        "size": "4 bytes (__u32)",
        "meaning": "Size of this structure."
      },
      {
        "field": "data_head",
        "size": "8 bytes (__u64)",
        "meaning": "Head of the data ring (written by kernel; read by userspace)."
      },
      {
        "field": "data_tail",
        "size": "8 bytes (__u64)",
        "meaning": "Tail of the data ring (written by userspace; read by kernel)."
      },
      {
        "field": "data_offset",
        "size": "8 bytes (__u64)",
        "meaning": "Offset from mmap base to the data ring."
      },
      {
        "field": "data_size",
        "size": "8 bytes (__u64)",
        "meaning": "Size of the data ring (power of 2)."
      }
    ],
    "example_hex": "01 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00",
    "example_decoded": "perf_event_mmap_page with version 1, data_head=0, data_tail=0",
    "notes": [
      "The ring buffer stores perf_event_header records (type, size, plus type-specific data: sample, mmap, comm, fork, exit, ...).",
      "time_enabled/time_running account for multiplexing when more events than PMU counters.",
      "rdpmc (cap_usr_rdpmc) allows userspace to read the PMU counter directly without a syscall.",
      "perf_event_open can profile hardware counters, software events, tracepoints, kprobes, uprobes, and BPF programs."
    ]
  },
  "updated": "2026-05-29"
}
