| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20260209174032.4142096-2-irogers@google.com>
Date: Mon, 9 Feb 2026 09:40:08 -0800
From: Ian Rogers <irogers@...gle.com>
To: Peter Zijlstra <peterz@...radead.org>, Ingo Molnar <mingo@...hat.com>,
Arnaldo Carvalho de Melo <acme@...nel.org>, Namhyung Kim <namhyung@...nel.org>,
Alexander Shishkin <alexander.shishkin@...ux.intel.com>, Jiri Olsa <jolsa@...nel.org>,
Ian Rogers <irogers@...gle.com>, Adrian Hunter <adrian.hunter@...el.com>,
James Clark <james.clark@...aro.org>, Paul Walmsley <pjw@...nel.org>,
Palmer Dabbelt <palmer@...belt.com>, Albert Ou <aou@...s.berkeley.edu>,
Alexandre Ghiti <alex@...ti.fr>, Leo Yan <leo.yan@....com>, Tianyou Li <tianyou.li@...el.com>,
Athira Rajeev <atrajeev@...ux.ibm.com>, Derek Foreman <derek.foreman@...labora.com>,
Thomas Falcon <thomas.falcon@...el.com>, Howard Chu <howardchu95@...il.com>,
Dmitry Vyukov <dvyukov@...gle.com>, Andi Kleen <ak@...ux.intel.com>, tanze <tanze@...inos.cn>,
Hrishikesh Suresh <hrishikesh123s@...il.com>, Quan Zhou <zhouquan@...as.ac.cn>,
Andrew Jones <ajones@...tanamicro.com>, Anup Patel <anup@...infault.org>,
Dapeng Mi <dapeng1.mi@...ux.intel.com>, "Dr. David Alan Gilbert" <linux@...blig.org>,
"Krzysztof Łopatowski" <krzysztof.m.lopatowski@...il.com>, Chun-Tse Shao <ctshao@...gle.com>,
Ravi Bangoria <ravi.bangoria@....com>, Swapnil Sapkal <swapnil.sapkal@....com>,
Chen Ni <nichen@...as.ac.cn>, Blake Jones <blakejones@...gle.com>,
Yujie Liu <yujie.liu@...el.com>, linux-perf-users@...r.kernel.org,
linux-kernel@...r.kernel.org
Subject: [PATCH v1 01/25] perf sample: Document struct perf_sample
Add kernel-doc for struct perf_sample capturing the somewhat unusual
population of fields and lifetime relationships.
Signed-off-by: Ian Rogers <irogers@...gle.com>
---
tools/perf/util/sample.h | 90 ++++++++++++++++++++++++++++++++++++++--
1 file changed, 87 insertions(+), 3 deletions(-)
diff --git a/tools/perf/util/sample.h b/tools/perf/util/sample.h
index 3cce8dd202aa..3fd2a5e01308 100644
--- a/tools/perf/util/sample.h
+++ b/tools/perf/util/sample.h
@@ -81,47 +81,131 @@ struct simd_flags {
#define SIMD_OP_FLAGS_PRED_PARTIAL 0x01 /* partial predicate */
#define SIMD_OP_FLAGS_PRED_EMPTY 0x02 /* empty predicate */
+/**
+ * struct perf_sample
+ *
+ * A sample is generally filled in by evlist__parse_sample/evsel__parse_sample
+ * which fills in the variables from a "union perf_event *event" which is data
+ * from a perf ring buffer or perf.data file. The "event" sample is variable in
+ * length as determined by the perf_event_attr (in the evsel) and details within
+ * the sample event itself. A struct perf_sample avoids needing to care about
+ * the variable length nature of the original event.
+ *
+ * To avoid being excessively large parts of the struct perf_sample are pointers
+ * into the original sample event. In general the lifetime of a struct
+ * perf_sample needs to be less than the "union perf_event *event" it was
+ * derived from.
+ *
+ * The struct regs_dump user_regs and intr_regs are lazily allocated again for
+ * size reasons, due to them holding a cache of looked up registers. The
+ * function pair of perf_sample__init and perf_sample__exit correctly initialize
+ * and clean up these values.
+ */
struct perf_sample {
+ /** @ip: The sample event PERF_SAMPLE_IP value. */
u64 ip;
- u32 pid, tid;
+ /** @pid: The sample event PERF_SAMPLE_TID pid value. */
+ u32 pid;
+ /** @tid: The sample event PERF_SAMPLE_TID tid value. */
+ u32 tid;
+ /** @time: The sample event PERF_SAMPLE_TIME value. */
u64 time;
+ /** @addr: The sample event PERF_SAMPLE_ADDR value. */
u64 addr;
+ /** @id: The sample event PERF_SAMPLE_ID value. */
u64 id;
+ /** @stream_id: The sample event PERF_SAMPLE_STREAM_ID value. */
u64 stream_id;
+ /** @period: The sample event PERF_SAMPLE_PERIOD value. */
u64 period;
+ /** @weight: Data determined by PERF_SAMPLE_WEIGHT or PERF_SAMPLE_WEIGHT_STRUCT. */
u64 weight;
+ /** @transaction: The sample event PERF_SAMPLE_TRANSACTION value. */
u64 transaction;
+ /** @insn_cnt: Filled in and used by intel-pt. */
u64 insn_cnt;
+ /** @cyc_cnt: Filled in and used by intel-pt. */
u64 cyc_cnt;
+ /** @cpu: The sample event PERF_SAMPLE_CPU value. */
u32 cpu;
+ /**
+ * @raw_size: The size in bytes of raw data from PERF_SAMPLE_RAW. For
+ * alignment reasons this should always be a multiple of
+ * sizeof(u64) + sizeof(u32).
+ */
u32 raw_size;
+ /** @data_src: The sample event PERF_SAMPLE_DATA_SRC value. */
u64 data_src;
+ /** @phys_addr: The sample event PERF_SAMPLE_PHYS_ADDR value. */
u64 phys_addr;
+ /** @data_page_size: The sample event PERF_SAMPLE_DATA_PAGE_SIZE value. */
u64 data_page_size;
+ /** @code_page_size: The sample event PERF_SAMPLE_CODE_PAGE_SIZE value. */
u64 code_page_size;
+ /** @cgroup: The sample event PERF_SAMPLE_CGROUP value. */
u64 cgroup;
+ /** @flags: Extra flag data from auxiliary events like intel-pt. */
u32 flags;
+ /** @machine_pid: The guest machine pid derived from the sample id. */
u32 machine_pid;
+ /** @vcpu: The guest machine vcpu derived from the sample id. */
u32 vcpu;
+ /** @insn_len: Instruction length from auxiliary events like intel-pt. */
u16 insn_len;
+ /**
+ * @cpumode: The cpumode from struct perf_event_header misc variable
+ * masked with CPUMODE_MASK. Gives user, kernel and hypervisor
+ * information.
+ */
u8 cpumode;
+ /** @misc: The entire struct perf_event_header misc variable. */
u16 misc;
+ /** @ins_lat: Instruction latency information from auxiliary events like intel-pt. */
u16 ins_lat;
/** @weight3: On x86 holds retire_lat, on powerpc holds p_stage_cyc. */
u16 weight3;
- bool no_hw_idx; /* No hw_idx collected in branch_stack */
- bool deferred_callchain; /* Has deferred user callchains */
+ /**
+ * @no_hw_idx: For PERF_SAMPLE_BRANCH_STACK, true when
+ * PERF_SAMPLE_BRANCH_HW_INDEX isn't set.
+ */
+ bool no_hw_idx;
+ /**
+ * @deferred_callchain: When processing PERF_SAMPLE_CALLCHAIN a deferred
+ * user callchain marker was encountered.
+ */
+ bool deferred_callchain;
+ /**
+ * @deferred_cookie: Identifier of the deferred callchain in the later
+ * PERF_RECORD_CALLCHAIN_DEFERRED event.
+ */
u64 deferred_cookie;
+ /** @insn: A copy of the sampled instruction filled in by perf_sample__fetch_insn. */
char insn[MAX_INSN];
+ /** @raw_data: Byte aligned pointer into the original event for PERF_SAMPLE_RAW data. */
void *raw_data;
+ /** @callchain: Pointer into the original event for PERF_SAMPLE_CALLCHAIN data. */
struct ip_callchain *callchain;
+ /** @branch_stack: Pointer into the original event for PERF_SAMPLE_BRANCH_STACK data. */
struct branch_stack *branch_stack;
+ /**
+ * @branch_stack_cntr: Pointer into the original event for
+ * PERF_SAMPLE_BRANCH_COUNTERS data.
+ */
u64 *branch_stack_cntr;
+ /** @user_regs: Values and pointers into the sample for PERF_SAMPLE_REGS_USER. */
struct regs_dump *user_regs;
+ /** @intr_regs: Values and pointers into the sample for PERF_SAMPLE_REGS_INTR. */
struct regs_dump *intr_regs;
+ /** @user_stack: Size and pointer into the sample for PERF_SAMPLE_STACK_USER. */
struct stack_dump user_stack;
+ /** @read: The sample event PERF_SAMPLE_READ counter values. */
struct sample_read read;
+ /**
+ * @aux_sample: Similar to raw data but with a 64-bit size and
+ * alignment, PERF_SAMPLE_AUX data.
+ */
struct aux_sample aux_sample;
+ /** @simd_flags: SIMD flag information from ARM SPE auxiliary events. */
struct simd_flags simd_flags;
};
--
2.53.0.239.g8d8fc8a987-goog
Powered by blists - more mailing lists