crash.kernel module

class crash.kernel.CrashKernel(roots: Union[List[str], str] = None, vmlinux_debuginfo: Union[List[str], str] = None, module_path: Union[List[str], str] = None, module_debuginfo_path: Union[List[str], str] = None, verbose: bool = False, debug: bool = False)[source]

Bases: object

Initialize a basic kernel semantic debugging session.

This means that we load the following:

  • Kernel image symbol table (and debuginfo, if not integrated) relocated to the base offset used by kASLR
  • Kernel modules that were loaded on the the crashed system (again, with debuginfo if not integrated)
  • Percpu ranges used by kernel module
  • Architecture-specific details
  • Linux tasks populated into the GDB thread table

If kernel module files and debuginfo cannot be located, backtraces may be incomplete if the addresses used by the modules are crossed. Percpu ranges will be properly loaded regardless.

For arguments that accept paths to specify a base directory to be used, the entire directory structure will be read and cached to speed up subsequent searches. Still, reading large directory trees is a time consuming operation and being exact as possible will improve startup time.

Parameters:
  • root (None for defaults) –

    The roots of trees to search for debuginfo files. When specified, all roots will be searched using the following arguments (including the absolute paths in the defaults if unspecified).

    Defaults to: /

  • vmlinux_debuginfo (None for defaults) –

    The location of the separate debuginfo file corresponding to the kernel being debugged.

    Defaults to:

    • <loaded kernel path>.debug
    • ./vmlinux-<kernel version>.debug
    • /usr/lib/debug/.build-id/xx/<build-id>.debug
    • /usr/lib/debug/<loaded kernel path>.debug
    • /usr/lib/debug/boot/<loaded kernel name>.debug
    • /usr/lib/debug/boot/vmlinux-<kernel version>
  • module_path (None for defaults) –

    The base directory to be used to search for kernel modules (e.g. module.ko) to be used to load symbols for the kernel being debugged.

    Defaults to:

    • ./modules
    • /lib/modules/<kernel-version>
  • module_debuginfo_path (None for defaults) –

    The base directory to search for debuginfo matching the kernel modules already loaded.

    Defaults to:

    • ./modules.debug
    • /usr/lib/debug/.build-id/xx/<build-id>.debug
    • /usr/lib/debug/lib/modules/<kernel-version>
Raises:
  • CrashKernelError – If the kernel debuginfo cannot be loaded.
  • InvalidArgumentError – If any of the arguments are not None, str, or list of str
static build_id_path(objfile: gdb.Objfile) → Optional[str][source]

Returns the relative path for debuginfo using the objfile’s build-id.

Parameters:objfile – The objfile for which to return the path
extract_modinfo_from_module(modpath: str) → Dict[str, str][source]

Returns the modinfo from a module file

Parameters:modpath – The path to the module file.
Returns:A dictionary containing the names and values of the modinfo variables.
Return type:dict
extract_vermagic() → str[source]

Returns the vermagic from the loaded vmlinux

Returns:The version text.
Return type:str
extract_version() → str[source]

Returns the version from the loaded vmlinux

If debuginfo is available, init_uts_ns will be used. Otherwise, it will be extracted from the version banner.

Returns:The version text.
Return type:str
load_modules(verbose: bool = False, debug: bool = False) → None[source]

Load modules (including debuginfo) into the crash session.

This routine will attempt to locate modules and the corresponding debuginfo files, if separate, using the parameters defined when the CrashKernel object was initialized.

Parameters:
  • verbose (default=False) – enable verbose output
  • debug (default=False) – enable even more verbose debugging output
Raises:

CrashKernelError – An error was encountered while loading a module. This does not include a failure to locate a module or its debuginfo.
setup_tasks() → None[source]

Populate GDB’s thread list using the kernel’s task lists

This method will iterate over the kernel’s task lists, create a LinuxTask object, and create a gdb thread for each one. The threads will be built so that the registers are ready to be populated, which allows symbolic stack traces to be made available.

symbols = <crash.util.symbols.Symbols object>
symvals = <crash.util.symbols.Symvals object>
types = <crash.util.symbols.Types object>
exception crash.kernel.CrashKernelError[source]

Bases: RuntimeError

Raised when an error occurs while initializing the debugging session