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@google.com>
Signed-off-by: Namhyung Kim <namhyung@kernel.org>

diff --git a/tools/perf/util/sample.h b/tools/perf/util/sample.h
index 3cce8dd202aa91f368d4af88a88955b246aecbe8..9febad1c8207a43f38726f79c4ab7cc26ee06a29 100644 (file)
--- a/tools/perf/util/sample.h
+++ b/tools/perf/util/sample.h
@@ -81,47 +81,148 @@ 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 or PEF_SAMPLE_IDENTIFIER 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 sizeof(u32)
+        *            followed by a multiple of sizeof(u64).
+        */
        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. The instruction itself is held in insn.
+        */
        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 weight2 in
+        *           PERF_SAMPLE_WEIGHT_STRUCT or auxiliary events like
+        *           intel-pt.
+        */
        u16 ins_lat;
-       /** @weight3: On x86 holds retire_lat, on powerpc holds p_stage_cyc. */
+       /**
+        * @weight3: From PERF_SAMPLE_WEIGHT_STRUCT. 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: Pointer into the original event for PERF_SAMPLE_RAW data. */
        void *raw_data;
+       /**
+        * @callchain: Pointer into the original event for PERF_SAMPLE_CALLCHAIN
+        *             data. For deferred callchains this may be a copy that
+        *             needs freeing, see sample__merge_deferred_callchain.
+        */
        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. The valid
+        *        values depend on the attr.read_format PERF_FORMAT_ 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;
 };