[PATCH v3 11/19] tools headers UAPI: Sync linux/perf_event.h for BUILD_ID_OFFSET

From: Ian Rogers

Date: Mon Nov 16 2026 - 02:45:44 EST


Synchronize tools/include/uapi/linux/perf_event.h with the kernel UAPI
header for PERF_SAMPLE_BUILD_ID_OFFSET and
PERF_SAMPLE_CALLCHAIN_BUILD_ID_OFFSET, and add struct
perf_sample_build_id_offset and the struct perf_record_callchain_deferred
build ID union fields to tools/lib/perf/include/perf/event.h.

Suggested-by: Namhyung Kim <namhyung@xxxxxxxxxx>
Signed-off-by: Ian Rogers <irogers@xxxxxxxxxx>
---
tools/include/uapi/linux/perf_event.h | 59 ++++++++++++++++++++++++---
tools/lib/perf/include/perf/event.h | 29 ++++++++++++-
2 files changed, 81 insertions(+), 7 deletions(-)

diff --git a/tools/include/uapi/linux/perf_event.h b/tools/include/uapi/linux/perf_event.h
index deb7c42d109b..775420ed9aee 100644
--- a/tools/include/uapi/linux/perf_event.h
+++ b/tools/include/uapi/linux/perf_event.h
@@ -165,8 +165,10 @@ enum perf_event_sample_format {
PERF_SAMPLE_DATA_PAGE_SIZE = 1U << 22,
PERF_SAMPLE_CODE_PAGE_SIZE = 1U << 23,
PERF_SAMPLE_WEIGHT_STRUCT = 1U << 24,
+ PERF_SAMPLE_BUILD_ID_OFFSET = 1U << 25,
+ PERF_SAMPLE_CALLCHAIN_BUILD_ID_OFFSET = 1U << 26,

- PERF_SAMPLE_MAX = 1U << 25, /* non-ABI */
+ PERF_SAMPLE_MAX = 1U << 27, /* non-ABI */
};

#define PERF_SAMPLE_WEIGHT_TYPE (PERF_SAMPLE_WEIGHT | PERF_SAMPLE_WEIGHT_STRUCT)
@@ -840,7 +842,8 @@ struct perf_event_mmap_page {
*
* PERF_RECORD_MISC_EXACT_IP - PERF_RECORD_SAMPLE of precise events
* PERF_RECORD_MISC_SWITCH_OUT_PREEMPT - PERF_RECORD_SWITCH* events
- * PERF_RECORD_MISC_MMAP_BUILD_ID - PERF_RECORD_MMAP2 event
+ * PERF_RECORD_MISC_MMAP_BUILD_ID - PERF_RECORD_MMAP2 and
+ * PERF_RECORD_CALLCHAIN_DEFERRED events
*
*
* PERF_RECORD_MISC_EXACT_IP:
@@ -852,7 +855,7 @@ struct perf_event_mmap_page {
* Indicates that thread was preempted in TASK_RUNNING state.
*
* PERF_RECORD_MISC_MMAP_BUILD_ID:
- * Indicates that mmap2 event carries build ID data.
+ * Indicates that mmap2 or deferred callchain event carries build ID data.
*/
#define PERF_RECORD_MISC_EXACT_IP (1 << 14)
#define PERF_RECORD_MISC_SWITCH_OUT_PREEMPT (1 << 14)
@@ -1095,6 +1098,38 @@ enum perf_event_type {
* { u64 code_page_size;} && PERF_SAMPLE_CODE_PAGE_SIZE
* { u64 size;
* char data[size]; } && PERF_SAMPLE_AUX
+ * { union {
+ * struct {
+ * struct perf_build_id bid;
+ * u64 offset;
+ * };
+ * struct {
+ * u64 zero;
+ * u64 context;
+ * u64 cookie;
+ * u64 ip;
+ * }; && attr.defer_callchain
+ * }; } && PERF_SAMPLE_BUILD_ID_OFFSET
+ * { u32 nr_build_ids;
+ * u32 nr_offsets;
+ * struct {
+ * u8 size;
+ * u8 data[size];
+ * }[nr_build_ids];
+ * u8 pad[];
+ * u64 offsets[nr_offsets];
+ * #
+ * # Entries in offsets[] include PERF_CONTEXT_* markers (which
+ * # have top 8 bits 0xff). Kernel/hypervisor entries (after
+ * # PERF_CONTEXT_KERNEL, PERF_CONTEXT_HV, PERF_CONTEXT_GUEST,
+ * # or PERF_CONTEXT_GUEST_KERNEL) and the cookie word following
+ * # PERF_CONTEXT_USER_DEFERRED are raw 64-bit values. User
+ * # entries (after PERF_CONTEXT_USER or PERF_CONTEXT_GUEST_USER,
+ * # or in PERF_RECORD_CALLCHAIN_DEFERRED) use the top 8 bits to
+ * # encode a 1-based index (1..254) into the build_ids table and
+ * # the lower 56 bits for the DSO file offset, or 0x00 for an
+ * # unresolved user virtual address.
+ * } && PERF_SAMPLE_CALLCHAIN_BUILD_ID_OFFSET
* };
*/
PERF_RECORD_SAMPLE = 9,
@@ -1306,8 +1341,22 @@ enum perf_event_type {
* struct {
* struct perf_event_header header;
* u64 cookie;
- * u64 nr;
- * u64 ips[nr];
+ * union {
+ * struct {
+ * u64 nr;
+ * u64 ips[nr];
+ * };
+ * struct {
+ * u32 nr_build_ids;
+ * u32 nr_offsets;
+ * struct {
+ * u8 size;
+ * u8 data[size];
+ * }[nr_build_ids];
+ * u8 pad[];
+ * u64 offsets[nr_offsets];
+ * }; && (header.misc & PERF_RECORD_MISC_MMAP_BUILD_ID)
+ * };
* struct sample_id sample_id;
* };
*/
diff --git a/tools/lib/perf/include/perf/event.h b/tools/lib/perf/include/perf/event.h
index 867dd55f0969..216f42f7485b 100644
--- a/tools/lib/perf/include/perf/event.h
+++ b/tools/lib/perf/include/perf/event.h
@@ -3,6 +3,7 @@
#define __LIBPERF_EVENT_H

#include <linux/perf_event.h>
+#include <linux/stddef.h>
#include <linux/types.h>
#include <linux/limits.h>
#include <linux/bpf.h>
@@ -168,6 +169,21 @@ struct perf_record_switch {
__u32 next_prev_tid;
};

+struct perf_sample_build_id_offset {
+ union {
+ struct perf_build_id bid;
+ struct {
+ __u64 zero;
+ __u64 context;
+ __u64 cookie;
+ };
+ };
+ union {
+ __u64 offset;
+ __u64 ip;
+ };
+};
+
struct perf_record_callchain_deferred {
struct perf_event_header header;
/*
@@ -176,8 +192,17 @@ struct perf_record_callchain_deferred {
* the PERF_CONTEXT_USER_DEFERRED entry.
*/
__u64 cookie;
- __u64 nr;
- __u64 ips[];
+ union {
+ struct {
+ __u64 nr;
+ __u64 ips[];
+ };
+ struct {
+ __u32 nr_build_ids;
+ __u32 nr_offsets;
+ __u8 build_ids[];
+ };
+ };
};

struct perf_record_header_attr {
--
2.56.1.703.gf848ed807c-goog