perf dso: kernel-doc for enum dso_binary_type

There are many and non-obvious meanings to the dso_binary_type enum
values. Add kernel-doc to speed interpretting their meanings.

Acked-by: Arnaldo Carvalho de Melo <acme@redhat.com>
Signed-off-by: Ian Rogers <irogers@google.com>
Reviewed-by: Namhyung Kim <namhyung@kernel.org>
Link: https://lore.kernel.org/r/20250319050741.269828-3-irogers@google.com
Signed-off-by: Namhyung Kim <namhyung@kernel.org>

diff --git a/tools/perf/util/dso.h b/tools/perf/util/dso.h
index fc43f037b410467baa5ce56dcb5b854fb07d5c47..a4980101e22b67446100d3d5cf168979df9271e3 100644 (file)
--- a/tools/perf/util/dso.h
+++ b/tools/perf/util/dso.h
@@ -20,31 +20,88 @@ struct perf_env;
 #define DSO__NAME_KALLSYMS     "[kernel.kallsyms]"
 #define DSO__NAME_KCORE                "[kernel.kcore]"
 
+/**
+ * enum dso_binary_type - The kind of DSO generally associated with a memory
+ *                        region (struct map).
+ */
 enum dso_binary_type {
+       /** @DSO_BINARY_TYPE__KALLSYMS: Symbols from /proc/kallsyms file. */
        DSO_BINARY_TYPE__KALLSYMS = 0,
+       /** @DSO_BINARY_TYPE__GUEST_KALLSYMS: Guest /proc/kallsyms file. */
        DSO_BINARY_TYPE__GUEST_KALLSYMS,
+       /** @DSO_BINARY_TYPE__VMLINUX: Path to kernel /boot/vmlinux file. */
        DSO_BINARY_TYPE__VMLINUX,
+       /** @DSO_BINARY_TYPE__GUEST_VMLINUX: Path to guest kernel /boot/vmlinux file. */
        DSO_BINARY_TYPE__GUEST_VMLINUX,
+       /** @DSO_BINARY_TYPE__JAVA_JIT: Symbols from /tmp/perf.map file. */
        DSO_BINARY_TYPE__JAVA_JIT,
+       /**
+        * @DSO_BINARY_TYPE__DEBUGLINK: Debug file readable from the file path
+        * in the .gnu_debuglink ELF section of the dso.
+        */
        DSO_BINARY_TYPE__DEBUGLINK,
+       /**
+        * @DSO_BINARY_TYPE__BUILD_ID_CACHE: File named after buildid located in
+        * the buildid cache with an elf filename.
+        */
        DSO_BINARY_TYPE__BUILD_ID_CACHE,
+       /**
+        * @DSO_BINARY_TYPE__BUILD_ID_CACHE_DEBUGINFO: File named after buildid
+        * located in the buildid cache with a debug filename.
+        */
        DSO_BINARY_TYPE__BUILD_ID_CACHE_DEBUGINFO,
+       /**
+        * @DSO_BINARY_TYPE__FEDORA_DEBUGINFO: Debug file in /usr/lib/debug
+        * with .debug suffix.
+        */
        DSO_BINARY_TYPE__FEDORA_DEBUGINFO,
+       /** @DSO_BINARY_TYPE__UBUNTU_DEBUGINFO: Debug file in /usr/lib/debug. */
        DSO_BINARY_TYPE__UBUNTU_DEBUGINFO,
+       /**
+        * @DSO_BINARY_TYPE__MIXEDUP_UBUNTU_DEBUGINFO: dso__long_name debuginfo
+        * file in /usr/lib/debug/lib rather than the expected
+        * /usr/lib/debug/usr/lib.
+        */
        DSO_BINARY_TYPE__MIXEDUP_UBUNTU_DEBUGINFO,
+       /**
+        * @DSO_BINARY_TYPE__BUILDID_DEBUGINFO: File named after buildid located
+        * in /usr/lib/debug/.build-id/.
+        */
        DSO_BINARY_TYPE__BUILDID_DEBUGINFO,
+       /**
+        * @DSO_BINARY_TYPE__GNU_DEBUGDATA: MiniDebuginfo where a compressed
+        * ELF file is placed in a .gnu_debugdata section.
+        */
        DSO_BINARY_TYPE__GNU_DEBUGDATA,
+       /** @DSO_BINARY_TYPE__SYSTEM_PATH_DSO: A regular executable/shared-object file. */
        DSO_BINARY_TYPE__SYSTEM_PATH_DSO,
+       /** @DSO_BINARY_TYPE__GUEST_KMODULE: Guest kernel module .ko file. */
        DSO_BINARY_TYPE__GUEST_KMODULE,
+       /** @DSO_BINARY_TYPE__GUEST_KMODULE_COMP: Guest kernel module .ko.gz file. */
        DSO_BINARY_TYPE__GUEST_KMODULE_COMP,
+       /** @DSO_BINARY_TYPE__SYSTEM_PATH_KMODULE: Kernel module .ko file. */
        DSO_BINARY_TYPE__SYSTEM_PATH_KMODULE,
+       /** @DSO_BINARY_TYPE__SYSTEM_PATH_KMODULE_COMP: Kernel module .ko.gz file. */
        DSO_BINARY_TYPE__SYSTEM_PATH_KMODULE_COMP,
+       /** @DSO_BINARY_TYPE__KCORE: /proc/kcore file. */
        DSO_BINARY_TYPE__KCORE,
+       /** @DSO_BINARY_TYPE__GUEST_KCORE: Guest /proc/kcore file. */
        DSO_BINARY_TYPE__GUEST_KCORE,
+       /**
+        * @DSO_BINARY_TYPE__OPENEMBEDDED_DEBUGINFO: Openembedded/Yocto -dbg
+        * package debug info.
+        */
        DSO_BINARY_TYPE__OPENEMBEDDED_DEBUGINFO,
+       /** @DSO_BINARY_TYPE__BPF_PROG_INFO: jitted BPF code. */
        DSO_BINARY_TYPE__BPF_PROG_INFO,
+       /** @DSO_BINARY_TYPE__BPF_IMAGE: jitted BPF trampoline or dispatcher code. */
        DSO_BINARY_TYPE__BPF_IMAGE,
+       /**
+        * @DSO_BINARY_TYPE__OOL: out of line code such as kprobe-replaced
+        * instructions or optimized kprobes or ftrace trampolines.
+        */
        DSO_BINARY_TYPE__OOL,
+       /** @DSO_BINARY_TYPE__NOT_FOUND: Unknown DSO kind. */
        DSO_BINARY_TYPE__NOT_FOUND,
 };