[PATCH v3 03/19] perf/uapi: Add BUILD_ID_OFFSET sample types to UAPI

From: Ian Rogers

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


Introduce PERF_SAMPLE_BUILD_ID_OFFSET and
PERF_SAMPLE_CALLCHAIN_BUILD_ID_OFFSET in enum perf_event_sample_format.

For PERF_SAMPLE_CALLCHAIN_BUILD_ID_OFFSET (and
PERF_RECORD_CALLCHAIN_DEFERRED when PERF_RECORD_MISC_MMAP_BUILD_ID is
set), encode a deduplicated table of variable-length build IDs
(u32 nr_build_ids, u32 nr_offsets, followed by packed { u8 size;
u8 data[size]; } entries padded to 8-byte alignment) and an array of
64-bit offsets whose top 8 bits encode the 1-based build ID index (or
0x00 for unresolved user addresses and 0xff for kernel/context entries).
In common cases where multiple callchain frames belong to the same
binary, each unique build ID is encoded only once.

Suggested-by: Namhyung Kim <namhyung@xxxxxxxxxx>
Signed-off-by: Ian Rogers <irogers@xxxxxxxxxx>
---
include/uapi/linux/perf_event.h | 59 ++++++++++++++++++++++++++++++---
1 file changed, 54 insertions(+), 5 deletions(-)

diff --git a/include/uapi/linux/perf_event.h b/include/uapi/linux/perf_event.h
index deb7c42d109b..775420ed9aee 100644
--- a/include/uapi/linux/perf_event.h
+++ b/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;
* };
*/
--
2.56.1.703.gf848ed807c-goog