Rename "kernel image" to "vmlinux"

The terms "kernel image" is pretty ambiguous and somewhat nebulous, to
the point that it is probably not clear to many what it or its
properties should be. What we (and other debugging/profiling tools)
really seem to be interested in is what generally seems to be referred
to as vmlinux [0].
Switch terminology from "kernel image" to "vmlinux". The latter is much
more easily discoverable (both in the sense that the meaning of the word
can be pinned down as well as that a file of that name [or with such a
prefix] can be found on the file system) and more precisely defined.

[0] https://en.wikipedia.org/w/index.php?title=Vmlinux&oldid=1252541783

Signed-off-by: Daniel Müller <deso@posteo.net>

CHANGELOG.md

@@ -1,8 +1,9 @@
 Unreleased
 ----------
 - Added support for 32 bit ELF binaries
-- Adjusted kernel symbolization logic to give preference to ELF kernel
-  image, if present
+- Renamed `symbolize::Source::kernel_image` to `vmlinux`
+- Adjusted kernel symbolization logic to give preference to `vmlinux`
+  file, if present
 - Changed `symbolize::Kernel::{kallsyms,kernel_image}` to support
   disabling of the source
 

capi/CHANGELOG.md

@@ -3,7 +3,9 @@ Unreleased
 - Introduced `blaze_trace` function for tapping into the library's
   tracing functionality
 - Added `size` attribute to `blaze_sym` type
-- Added support for disabling `kallsyms` and ELF kernel image to
+- Renamed `kernel_image` member of `blaze_symbolize_src_kernel` to
+  `vmlinux`
+- Added support for disabling `kallsyms` and `vmlinux` to
   `blaze_symbolize_src_kernel`
 
 

capi/include/blazesym.h

@@ -794,9 +794,6 @@ typedef struct blaze_symbolize_src_process {
 
 /**
  * The parameters to load symbols and debug information from a kernel.
- *
- * Use a kernel image and a snapshot of its kallsyms as a source of symbols and
- * debug information.
  */
 typedef struct blaze_symbolize_src_kernel {
   /**
@@ -813,28 +810,32 @@ typedef struct blaze_symbolize_src_kernel {
    * If set to `'\0'` (`""`) usage of `kallsyms` will be disabled.
    * Otherwise the copy at the given path will be used.
    *
-   * If both a kernel image as well as a `kallsyms` file are found,
-   * the kernel image will generally be given preference and
-   * `kallsyms` acts as a fallback.
+   * If both a `vmlinux` as well as a `kallsyms` file are found,
+   * `vmlinux` will generally be given preference and `kallsyms` acts
+   * as a fallback.
    */
   const char *kallsyms;
   /**
-   * The path of the kernel image to use.
+   * The path of the `vmlinux` file to use.
+   *
+   * `vmlinux` is generally an uncompressed and unstripped object
+   * file that is typically used in debugging, profiling, and
+   * similar use cases.
    *
-   * When `NULL`, the library will search for kernel image candidates
-   * in various locations, taking into account the currently running
-   * kernel version. If set to `'\0'` (`""`) usage of a kernel image
-   * will be disabled. Otherwise the copy at the given path will be
-   * used.
+   * When `NULL`, the library will search for `vmlinux` candidates in
+   * various locations, taking into account the currently running
+   * kernel version. If set to `'\0'` (`""`) discovery and usage of a
+   * `vmlinux` will be disabled. Otherwise the copy at the given path
+   * will be used.
    *
-   * If both a kernel image as well as a `kallsyms` file are found,
-   * the kernel image will generally be given preference and
-   * `kallsyms` acts as a fallback.
+   * If both a `vmlinux` as well as a `kallsyms` file are found,
+   * `vmlinux` will generally be given preference and `kallsyms` acts
+   * as a fallback.
    */
-  const char *kernel_image;
+  const char *vmlinux;
   /**
-   * Whether or not to consult debug symbols from `kernel_image`
-   * to satisfy the request (if present).
+   * Whether or not to consult debug symbols from `vmlinux` to
+   * satisfy the request (if present).
    */
   bool debug_syms;
   /**

capi/src/symbolize.rs

@@ -92,9 +92,6 @@ impl From<blaze_symbolize_src_elf> for Elf {
 
 
 /// The parameters to load symbols and debug information from a kernel.
-///
-/// Use a kernel image and a snapshot of its kallsyms as a source of symbols and
-/// debug information.
 #[repr(C)]
 #[derive(Debug)]
 pub struct blaze_symbolize_src_kernel {
@@ -109,24 +106,28 @@ pub struct blaze_symbolize_src_kernel {
     /// If set to `'\0'` (`""`) usage of `kallsyms` will be disabled.
     /// Otherwise the copy at the given path will be used.
     ///
-    /// If both a kernel image as well as a `kallsyms` file are found,
-    /// the kernel image will generally be given preference and
-    /// `kallsyms` acts as a fallback.
+    /// If both a `vmlinux` as well as a `kallsyms` file are found,
+    /// `vmlinux` will generally be given preference and `kallsyms` acts
+    /// as a fallback.
     pub kallsyms: *const c_char,
-    /// The path of the kernel image to use.
+    /// The path of the `vmlinux` file to use.
+    ///
+    /// `vmlinux` is generally an uncompressed and unstripped object
+    /// file that is typically used in debugging, profiling, and
+    /// similar use cases.
     ///
-    /// When `NULL`, the library will search for kernel image candidates
-    /// in various locations, taking into account the currently running
-    /// kernel version. If set to `'\0'` (`""`) usage of a kernel image
-    /// will be disabled. Otherwise the copy at the given path will be
-    /// used.
+    /// When `NULL`, the library will search for `vmlinux` candidates in
+    /// various locations, taking into account the currently running
+    /// kernel version. If set to `'\0'` (`""`) discovery and usage of a
+    /// `vmlinux` will be disabled. Otherwise the copy at the given path
+    /// will be used.
     ///
-    /// If both a kernel image as well as a `kallsyms` file are found,
-    /// the kernel image will generally be given preference and
-    /// `kallsyms` acts as a fallback.
-    pub kernel_image: *const c_char,
-    /// Whether or not to consult debug symbols from `kernel_image`
-    /// to satisfy the request (if present).
+    /// If both a `vmlinux` as well as a `kallsyms` file are found,
+    /// `vmlinux` will generally be given preference and `kallsyms` acts
+    /// as a fallback.
+    pub vmlinux: *const c_char,
+    /// Whether or not to consult debug symbols from `vmlinux` to
+    /// satisfy the request (if present).
     pub debug_syms: bool,
     /// Unused member available for future expansion. Must be initialized
     /// to zero.
@@ -138,7 +139,7 @@ impl Default for blaze_symbolize_src_kernel {
         Self {
             type_size: mem::size_of::<Self>(),
             kallsyms: ptr::null(),
-            kernel_image: ptr::null(),
+            vmlinux: ptr::null(),
             debug_syms: false,
             reserved: [0; 7],
         }
@@ -163,13 +164,13 @@ impl From<blaze_symbolize_src_kernel> for Kernel {
         let blaze_symbolize_src_kernel {
             type_size: _,
             kallsyms,
-            kernel_image,
+            vmlinux,
             debug_syms,
             reserved: _,
         } = kernel;
         Self {
             kallsyms: to_maybe_path(kallsyms),
-            kernel_image: to_maybe_path(kernel_image),
+            vmlinux: to_maybe_path(vmlinux),
             debug_syms,
             _non_exhaustive: (),
         }
@@ -1179,7 +1180,7 @@ mod tests {
         };
         assert_eq!(
             format!("{kernel:?}"),
-            "blaze_symbolize_src_kernel { type_size: 32, kallsyms: 0x0, kernel_image: 0x0, debug_syms: true, reserved: [0, 0, 0, 0, 0, 0, 0] }"
+            "blaze_symbolize_src_kernel { type_size: 32, kallsyms: 0x0, vmlinux: 0x0, debug_syms: true, reserved: [0, 0, 0, 0, 0, 0, 0] }"
         );
 
         let process = blaze_symbolize_src_process {
@@ -1304,20 +1305,20 @@ mod tests {
         let kernel = blaze_symbolize_src_kernel::default();
         let kernel = Kernel::from(kernel);
         assert_eq!(kernel.kallsyms, MaybeDefault::Default);
-        assert_eq!(kernel.kernel_image, MaybeDefault::Default);
+        assert_eq!(kernel.vmlinux, MaybeDefault::Default);
 
         let kernel = blaze_symbolize_src_kernel {
             kallsyms: b"\0" as *const _ as *const c_char,
-            kernel_image: b"\0" as *const _ as *const c_char,
+            vmlinux: b"\0" as *const _ as *const c_char,
             ..Default::default()
         };
         let kernel = Kernel::from(kernel);
         assert_eq!(kernel.kallsyms, MaybeDefault::None);
-        assert_eq!(kernel.kernel_image, MaybeDefault::None);
+        assert_eq!(kernel.vmlinux, MaybeDefault::None);
 
         let kernel = blaze_symbolize_src_kernel {
             kallsyms: b"/proc/kallsyms\0" as *const _ as *const c_char,
-            kernel_image: b"/boot/image\0" as *const _ as *const c_char,
+            vmlinux: b"/boot/vmlinux\0" as *const _ as *const c_char,
             debug_syms: false,
             ..Default::default()
         };
@@ -1328,8 +1329,8 @@ mod tests {
             MaybeDefault::Some(PathBuf::from("/proc/kallsyms"))
         );
         assert_eq!(
-            kernel.kernel_image,
-            MaybeDefault::Some(PathBuf::from("/boot/image"))
+            kernel.vmlinux,
+            MaybeDefault::Some(PathBuf::from("/boot/vmlinux"))
         );
     }
 

cli/CHANGELOG.md

@@ -1,7 +1,7 @@
 Unreleased
 ----------
 - Added `--no-debug-syms` option to `inspect dump elf` sub-command
-- Added `--kallsyms` and `--kernel-image` options to `symbolize-kernel
+- Added `--kallsyms` and `--vmlinux` options to `symbolize-kernel
   sub-command
 
 

cli/src/args.rs

@@ -263,11 +263,11 @@ pub mod symbolize {
         // assignment, whereas `PathBuf` does not.
         #[arg(long, value_hint = ValueHint::FilePath)]
         pub kallsyms: Option<OsString>,
-        /// The kernel image file to use. If not provided, default
-        /// system locations will be searched for suitable candidates.
-        /// To disable usage provide an empty argument.
+        /// The vmlinux file to use. If not provided, default system
+        /// locations will be searched for suitable candidates. To
+        /// disable usage provide an empty argument.
         #[arg(long, value_hint = ValueHint::FilePath)]
-        pub kernel_image: Option<OsString>,
+        pub vmlinux: Option<OsString>,
         /// The addresses to symbolize.
         #[arg(value_parser = parse_addr)]
         pub addrs: Vec<Addr>,

cli/src/main.rs

@@ -270,7 +270,7 @@ fn symbolize(symbolize: args::symbolize::Symbolize) -> Result<()> {
         }
         args::symbolize::Symbolize::Kernel(args::symbolize::Kernel {
             kallsyms,
-            kernel_image,
+            vmlinux,
             ref addrs,
         }) => {
             let kernel = symbolize::Kernel {
@@ -279,7 +279,7 @@ fn symbolize(symbolize: args::symbolize::Symbolize) -> Result<()> {
                     Some(path) if path.as_os_str().is_empty() => MaybeDefault::None,
                     Some(path) => MaybeDefault::Some(path.into()),
                 },
-                kernel_image: match kernel_image {
+                vmlinux: match vmlinux {
                     None => MaybeDefault::Default,
                     Some(path) if path.as_os_str().is_empty() => MaybeDefault::None,
                     Some(path) => MaybeDefault::Some(path.into()),

src/kernel/resolver.rs

@@ -28,7 +28,7 @@ impl KernelResolver {
     ) -> Result<KernelResolver> {
         if ksym_resolver.is_none() && elf_resolver.is_none() {
             return Err(Error::with_not_found(
-                    "failed to create kernel resolver: neither ksym resolver nor kernel image ELF resolver are present",
+                "failed to create kernel resolver: neither kallsyms nor vmlinux symbol source are present",
             ))
         }
 
@@ -45,11 +45,11 @@ impl Symbolize for KernelResolver {
             (Some(elf_resolver), None) => elf_resolver.find_sym(addr, opts),
             (None, Some(ksym_resolver)) => ksym_resolver.find_sym(addr, opts),
             (Some(elf_resolver), Some(ksym_resolver)) => {
-                // We give preference to the kernel image resolver, because it
-                // is likely to report more information. If it could not find
-                // an address, though, we fall back to kallsyms. This is
-                // helpful for example for kernel modules, which naturally are
-                // not captured by the core kernel image.
+                // We give preference to vmlinux, because it is likely
+                // to report more information. If it could not find an
+                // address, though, we fall back to kallsyms. This is
+                // helpful for example for kernel modules, which
+                // naturally are not captured by vmlinux.
                 let result = elf_resolver.find_sym(addr, opts)?;
                 if result.is_ok() {
                     Ok(result)

src/symbolize/source.rs

@@ -174,24 +174,28 @@ pub struct Kernel {
     /// If set to [`None`][MaybeDefault::None] usage of `kallsyms` will
     /// be disabled. Otherwise the copy at the given path will be used.
     ///
-    /// If both a kernel image as well as a `kallsyms` file are found,
-    /// the kernel image will generally be given preference and
-    /// `kallsyms` acts as a fallback.
+    /// If both a `vmlinux` as well as a `kallsyms` file are found,
+    /// `vmlinux` will generally be given preference and `kallsyms` acts
+    /// as a fallback.
     pub kallsyms: MaybeDefault<PathBuf>,
-    /// The path of the kernel image to use.
+    /// The path of the `vmlinux` file to use.
     ///
-    /// By default, the library will search for kernel image candidates
-    /// in various locations, taking into account the currently running
-    /// kernel version. If set to [`None`][MaybeDefault::None] usage of
-    /// a kernel image will be disabled. Otherwise the copy at the given
-    /// path will be used.
+    /// `vmlinux` is generally an uncompressed and unstripped object
+    /// file that is typically used in debugging, profiling, and
+    /// similar use cases.
     ///
-    /// If both a kernel image as well as a `kallsyms` file are found,
-    /// the kernel image will generally be given preference and
-    /// `kallsyms` acts as a fallback.
-    pub kernel_image: MaybeDefault<PathBuf>,
-    /// Whether or not to consult debug symbols from `kernel_image`
-    /// to satisfy the request (if present).
+    /// By default, the library will search for candidates in various
+    /// locations, taking into account the currently running kernel
+    /// version. If set to [`None`][MaybeDefault::None] discovery and
+    /// usage of a vmlinux file will be disabled. Otherwise the copy at
+    /// the given path will be used.
+    ///
+    /// If both a `vmlinux` as well as a `kallsyms` file are found,
+    /// `vmlinux` will generally be given preference and `kallsyms` acts
+    /// as a fallback.
+    pub vmlinux: MaybeDefault<PathBuf>,
+    /// Whether or not to consult debug symbols from `vmlinux` to
+    /// satisfy the request (if present).
     ///
     /// On top of this runtime configuration, the crate needs to be
     /// built with the `dwarf` feature to actually consult debug
@@ -207,7 +211,7 @@ impl Default for Kernel {
     fn default() -> Self {
         Self {
             kallsyms: MaybeDefault::Default,
-            kernel_image: MaybeDefault::Default,
+            vmlinux: MaybeDefault::Default,
             debug_syms: true,
             _non_exhaustive: (),
         }

src/symbolize/symbolizer.rs

@@ -941,7 +941,7 @@ impl Symbolizer {
 
         let Kernel {
             kallsyms,
-            kernel_image,
+            vmlinux,
             debug_syms,
             _non_exhaustive: (),
         } = src;
@@ -968,35 +968,35 @@ impl Symbolizer {
             MaybeDefault::None => None,
         };
 
-        let elf_resolver = match kernel_image {
-            MaybeDefault::Some(image) => {
+        let elf_resolver = match vmlinux {
+            MaybeDefault::Some(vmlinux) => {
                 let resolver = self
                     .elf_cache
-                    .elf_resolver(image, self.maybe_debug_dirs(*debug_syms))?;
+                    .elf_resolver(vmlinux, self.maybe_debug_dirs(*debug_syms))?;
                 Some(resolver)
             }
             MaybeDefault::Default => {
                 let release = uname_release()?;
                 let release = bytes_to_os_str(release.as_bytes())?;
                 let basename = OsStr::new("vmlinux-");
                 let dirs = [Path::new("/boot/"), Path::new("/usr/lib/debug/boot/")];
-                let kernel_image = dirs.iter().find_map(|dir| {
+                let vmlinux = dirs.iter().find_map(|dir| {
                     let mut file = basename.to_os_string();
                     let () = file.push(release);
                     let path = dir.join(file);
                     path.exists().then_some(path)
                 });
 
-                if let Some(image) = kernel_image {
+                if let Some(vmlinux) = vmlinux {
                     let result = self
                         .elf_cache
-                        .elf_resolver(&image, self.maybe_debug_dirs(*debug_syms));
+                        .elf_resolver(&vmlinux, self.maybe_debug_dirs(*debug_syms));
                     match result {
                         Ok(resolver) => Some(resolver),
                         Err(err) => {
                             log::warn!(
-                                "failed to load kernel image {}: {err}; ignoring...",
-                                image.display()
+                                "failed to load vmlinux `{}`: {err}; ignoring...",
+                                vmlinux.display()
                             );
                             None
                         }