perf header: Add kerneldoc to 'struct perf_file_header'

Some of the values are a little strange so add documentation to
resolve ambiguity.

Signed-off-by: Ian Rogers <irogers@google.com>
Cc: Adrian Hunter <adrian.hunter@intel.com>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: James Clark <james.clark@linaro.org>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Kan Liang <kan.liang@linux.intel.com>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Namhyung Kim <namhyung@kernel.org>
Cc: Nick Terrell <terrelln@fb.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Yicong Yang <yangyicong@hisilicon.com>
Link: https://lore.kernel.org/r/20240829150154.37929-4-irogers@google.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

diff --git a/tools/perf/util/header.h b/tools/perf/util/header.h
index 07ff647197ff9fc565b0156b5e9d3b27a85825e8..3285981948d79a32d5fd6391870ae6f7c1698eb1 100644 (file)
--- a/tools/perf/util/header.h
+++ b/tools/perf/util/header.h
@@ -61,14 +61,28 @@ struct perf_file_section {
        u64 size;
 };
 
+/**
+ * struct perf_file_header: Header representation on disk.
+ */
 struct perf_file_header {
+       /** @magic: Holds "PERFILE2". */
        u64                             magic;
+       /** @size: Size of this header - sizeof(struct perf_file_header). */
        u64                             size;
+       /**
+        * @attr_size: Size of attrs entries - sizeof(struct perf_event_attr) +
+        * sizeof(struct perf_file_section).
+        */
        u64                             attr_size;
+       /** @attrs: Offset and size of file section holding attributes. */
        struct perf_file_section        attrs;
+       /** @data: Offset and size of file section holding regular event data. */
        struct perf_file_section        data;
-       /* event_types is ignored */
+       /** @event_types: Ignored. */
        struct perf_file_section        event_types;
+       /**
+        * @adds_features: Bitmap of features. The features are immediately after the data section.
+        */
        DECLARE_BITMAP(adds_features, HEADER_FEAT_BITS);
 };