From 9152b8b4701dce98e7a314b782a1c26a22800325 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20M=C3=BCller?= Date: Tue, 4 Feb 2025 10:37:48 -0800 Subject: [PATCH] Rename "kernel image" to "vmlinux" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CHANGELOG.md | 5 ++-- capi/CHANGELOG.md | 4 ++- capi/include/blazesym.h | 37 ++++++++++++------------ capi/src/symbolize.rs | 57 +++++++++++++++++++------------------ cli/CHANGELOG.md | 2 +- cli/src/args.rs | 8 +++--- cli/src/main.rs | 4 +-- src/kernel/resolver.rs | 12 ++++---- src/symbolize/source.rs | 36 ++++++++++++----------- src/symbolize/symbolizer.rs | 18 ++++++------ tests/suite/symbolize.rs | 23 +++++++-------- 11 files changed, 107 insertions(+), 99 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 49e5322a..83ce8b50 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/capi/CHANGELOG.md b/capi/CHANGELOG.md index 5454a3bf..e44dfffb 100644 --- a/capi/CHANGELOG.md +++ b/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` diff --git a/capi/include/blazesym.h b/capi/include/blazesym.h index 97783b66..b4e73a0c 100644 --- a/capi/include/blazesym.h +++ b/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; /** diff --git a/capi/src/symbolize.rs b/capi/src/symbolize.rs index 2ab456bf..c24c4d81 100644 --- a/capi/src/symbolize.rs +++ b/capi/src/symbolize.rs @@ -92,9 +92,6 @@ impl From 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::(), kallsyms: ptr::null(), - kernel_image: ptr::null(), + vmlinux: ptr::null(), debug_syms: false, reserved: [0; 7], } @@ -163,13 +164,13 @@ impl From 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")) ); } diff --git a/cli/CHANGELOG.md b/cli/CHANGELOG.md index 5f248c94..0dc6fdff 100644 --- a/cli/CHANGELOG.md +++ b/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 diff --git a/cli/src/args.rs b/cli/src/args.rs index 23f66a78..c59c818b 100644 --- a/cli/src/args.rs +++ b/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, - /// 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, + pub vmlinux: Option, /// The addresses to symbolize. #[arg(value_parser = parse_addr)] pub addrs: Vec, diff --git a/cli/src/main.rs b/cli/src/main.rs index 340b8bda..cc8b5e7a 100644 --- a/cli/src/main.rs +++ b/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()), diff --git a/src/kernel/resolver.rs b/src/kernel/resolver.rs index 79b3bb39..89e5d94c 100644 --- a/src/kernel/resolver.rs +++ b/src/kernel/resolver.rs @@ -28,7 +28,7 @@ impl KernelResolver { ) -> Result { 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) diff --git a/src/symbolize/source.rs b/src/symbolize/source.rs index 977a8d65..24e1bbac 100644 --- a/src/symbolize/source.rs +++ b/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, - /// 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, - /// 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, + /// 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: (), } diff --git a/src/symbolize/symbolizer.rs b/src/symbolize/symbolizer.rs index 1f795bbe..1d8f3849 100644 --- a/src/symbolize/symbolizer.rs +++ b/src/symbolize/symbolizer.rs @@ -941,7 +941,7 @@ impl Symbolizer { let Kernel { kallsyms, - kernel_image, + vmlinux, debug_syms, _non_exhaustive: (), } = src; @@ -968,11 +968,11 @@ 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 => { @@ -980,23 +980,23 @@ impl Symbolizer { 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 } diff --git a/tests/suite/symbolize.rs b/tests/suite/symbolize.rs index 95602324..dc90e6ba 100644 --- a/tests/suite/symbolize.rs +++ b/tests/suite/symbolize.rs @@ -554,7 +554,7 @@ fn symbolize_breakpad_inlined() { } /// Check that we can symbolize the `abort_creds` function inside a -/// kernel image properly. Inside of +/// vmlinux file properly. Inside of /// vmlinux-5.17.12-100.fc34.x86_64.dwarf, this function's address range /// and name are in separate attributes: /// ```text @@ -1023,7 +1023,7 @@ fn symbolize_zip_with_custom_dispatch_errors() { fn symbolize_kernel_no_valid_source() { let kernel = Kernel { kallsyms: MaybeDefault::None, - kernel_image: MaybeDefault::None, + vmlinux: MaybeDefault::None, ..Default::default() }; let src = Source::Kernel(kernel); @@ -1043,14 +1043,14 @@ fn symbolize_kernel_no_valid_source() { /// file. #[test] fn symbolize_kernel_kallsyms() { - fn test(kernel_image: MaybeDefault) { + fn test(vmlinux: MaybeDefault) { let kernel = Kernel { kallsyms: MaybeDefault::from( Path::new(&env!("CARGO_MANIFEST_DIR")) .join("data") .join("kallsyms"), ), - kernel_image, + vmlinux, ..Default::default() }; let src = Source::Kernel(kernel); @@ -1064,7 +1064,7 @@ fn symbolize_kernel_kallsyms() { } test(MaybeDefault::None); - // Provide a valid "kernel" image file, but given that it does not + // Provide a valid "vmlinux" file, but given that it does not // contain the address we attempt to symbolize we should end up // falling back to using kallsyms. test(MaybeDefault::Some( @@ -1074,9 +1074,9 @@ fn symbolize_kernel_kallsyms() { )); } -/// Test symbolization of a "kernel" address in an ELF file. +/// Test symbolization of a "kernel" address in an vmlinux ELF file. #[test] -fn symbolize_kernel_image() { +fn symbolize_kernel_vmlinux() { #[track_caller] fn test(kernel: Kernel, has_code_info: bool) { let src = Source::Kernel(kernel); @@ -1100,10 +1100,9 @@ fn symbolize_kernel_image() { let mut src = Kernel { kallsyms: MaybeDefault::None, - // We use a fake kernel image here for testing purposes, which - // really is just a regular ELF file, but that's what the kernel - // image would be anyway. - kernel_image: MaybeDefault::Some( + // We use a fake vmlinux here for testing purposes, which really + // is just a regular ELF file. + vmlinux: MaybeDefault::Some( Path::new(&env!("CARGO_MANIFEST_DIR")) .join("data") .join("test-stable-addrs.bin"), @@ -1119,7 +1118,7 @@ fn symbolize_kernel_image() { test(src.clone(), false); // Source has no debug syms and we do not want to use them. - src.kernel_image = MaybeDefault::Some( + src.vmlinux = MaybeDefault::Some( Path::new(&env!("CARGO_MANIFEST_DIR")) .join("data") .join("test-stable-addrs-no-dwarf.bin"),