Drgn

This release adds new APIs for providing symbol information to drgn, support for the new Python 3.13 REPL, and a few important bug fixes.

New features:

- The `drgn.SymbolIndex` class was added. It provides an efficient implementation of a symbol finder for a static list of symbols. Contributed by Stephen Brennan.
- The `drgn.helpers.linux.kallsyms` module was added. It provides two helpers, `load_vmlinux_kallsyms()` and `load_module_kallsyms()`, that can be used to look up symbols without full debugging information. Contributed by Stephen Brennan.
- The CLI will now use the enhanced REPL added in Python 3.13 when available. This greatly improves the user experience with multiline editing, colorized output, and more. Contributed by Stephen Brennan.
- Linux 6.13 is now supported. No updates were required.

Bug fixes:

- Linux kernel stack traces now reliably continue through interrupt handlers as long as the kernel uses the ORC unwinder.
- The `slab_cache_for_each_allocated_object()` and `slab_object_info()` helpers in `drgn.helpers.linux.slab` now report cycles in SLUB freelists instead of getting stuck in an infinite loop.
- QEMU guest memory dumps of the Linux kernel with KASLR disabled can now be debugged.
- The `css_for_each_child()` and `css_for_each_descendant_pre()` helpers in `drgn.helpers.linux.cgroup` were fixed to include offlined css objects. Contributed by Michal Koutný.
- The REPL now gracefully displays objects that cannot be read instead of failing with a `drgn.FaultError`.
- A double reference count decrement in an error path of initializing the drgn Python bindings was fixed.

Documentation:

- Documentation for installing drgn on Arch Linux was updated now that drgn is officially packaged on Arch Linux. Contributed by Christian Heusel.
- Documentation for installing drgn and debugging symbols on Oracle Linux was added. Contributed by Stephen Brennan.

`contrib` directory:

- `contrib/bpf_inspect.py` was fixed to handle Linux < 5.10 when printing BPF programs. Contributed by Ze Gao.
- `contrib/cgroup.py` now has a `stat` subcommand for printing the number of online and dying css objects. Contributed by Michal Koutný.
- `contrib/cgroup.py`'s `bpf` subcommand was fixed to not access an array out of bounds on Linux >= 5.15.
- `contrib/ptdrgn.py` was fixed to gracefully display objects that cannot be read. Contributed by Stephen Brennan.

Internal:

- Many preparations were made for the upcoming module API.
- The internal `drgndoc` Sphinx extension was fixed to handle deprecated `ast` nodes that were removed in Python 3.14.

This is a small release fixing the `call_function()`, `write_memory()`, and `write_object()` helpers in `drgn.helpers.experimental.kmodify` for kernels with `CONFIG_MODVERSIONS=y`.

New features:

- The `drgn.helpers.experimental.kmodify` module was added. It provides helpers for modifying the running kernel, including calling arbitrary functions (`call_function()`) and writing to memory (`write_memory()`, `write_object()`).
- Virtual address translation and stack trace support for 32-bit Arm were added.
- The `drgn.implicit_convert()` function was added. It converts an object to a type using C's implicit conversion rules (i.e., the rules used when assigning to a variable without an explicit cast).
- The `drgn.alignof()` function was added. It returns the alignment requirement of a type.
- The `drgn.helpers.linux.module` module was added. It provides helpers for looking up and inspecting Linux kernel modules: `address_to_module()`, `find_module()`, `for_each_module()`, `module_address_regions()`, and `module_percpu_region()`. Contributed by Stephen Brennan.
- The `drgn.helpers.linux.sched.task_thread_info()` helper was added. It returns the `struct thread_info *` for a given `struct task_struct *`.
- The `drgn.helpers.linux.fs.d_path()` helper can now return an absolute path given only a dentry. Contributed by Stephen Brennan.
- `drgn.Thread` now has a `name` attribute. Contributed by Ryan Wilson.
- `tools/fsrefs.py` gained a new mode for finding what is using the filesystem on a given block device.
- Linux 6.11 and 6.12 are now supported.
- `tools/fsrefs.py` was updated to handle changes to uprobes in Linux 6.12.
- Virtual address translation on AArch64 now supports Armv8.7 `FEAT_LPA2` (52-bit virtual addresses with 4k or 16k pages, added in Linux 6.9).
- Absent objects with `void` type can now be printed instead of raising a `TypeError`.

Bug fixes:

- The `drgn.cast()` function was fixed to allow casting anything to a `void` type.
- The `drgn.cast()` function's handling of casting to `bool` was fixed to convert to 0 or 1 instead of truncating to 8 bits.
- The `bool()` operator was fixed to return `False` for array objects with address 0 (which is possible with weak symbols).
- The `bool()` operator was fixed to allow passing a function object instead of raising a `TypeError`.
- Functions that have both out-of-line and inline instances now have their address properly reported instead of being returned as absent objects.
- Virtual address translation support on s390x was fixed to handle the virtual/physical address split in Linux 6.10.
- Virtual address translation support on AArch64 was fixed to handle the fallback from 52- to 48- or 47-bit virtual addresses with 4k or 16k pages if the hardware doesn't support `FEAT_LPA2`.
- The `drgn.helpers.common.memory.identify_address()` helper was fixed to not fail on kernels using the SLOB allocator. Contributed by Stephen Brennan.
- The `drgn.helpers.common.memory.identify_address()` helper was fixed to properly identify vmap allocations on kernels not using vmap stacks.
- The type annotation for `drgn.Object.from_bytes_()` was fixed to accept buffer types other than `bytes`.
- A build script was fixed to work on POSIX (non-Bash) shells. Contributed by Sam James.

API changes:

- The `struct`, `union`, `class`, and `enum` keywords are now omitted when formatting a C++ type name.
- The `bit_offset` and `bit_field_size` parameters of `drgn.Object.from_bytes_()` were fixed to be keyword-only as intended. They were previously annotated as keyword-only but were accepted positionally at runtime.

Documentation:

- Gentoo installation instructions were added. Contributed by Sam James.
- Positional-only parameters are now documented (using the standard `/` syntax).
- Helpers that depend on virtual address translation support now document that dependency, including the ways it can fail.
- Stale documentation referring to complex types, which are not implemented, was removed.

`contrib` directory:

- `contrib/bpf_inspect.py` can now show maps and subprograms used by a BPF program. Contributed by Leon Hwang.
- `contrib/bpf_inspect.py` was fixed to work on Python < 3.12. Contributed by Stephen Brennan.
- `contrib/slabinfo.py` was added. It dumps slab allocator statistics similar to `/proc/slabinfo`. Contributed by Kuan-Ying Lee.
- `contrib/vmallocinfo.py` was added. It dumps vmalloc information similar to `/proc/vmallocinfo`. Contributed by Kuan-Ying Lee.
- `contrib/btrfs_print_fs_uuids_cache.py` was added. It prints Btrfs's internal list of filesystem UUIDs. Contributed by Srivathsa Dara.
- `contrib/dm_crypt_key.py` was updated to handle Linux < 6.7.

Internal:

- Some code was moved to a new, top-level Python package, `_drgn_util`.

This release adds a few helpers, more pluggability for finding types, objects, and symbols, lots of new or improved scripts in `contrib`, and other improvements and bug fixes.

New features:

- The `print_annotated_memory()` helper was added to `drgn.helpers.common.memory`. It dumps a region of memory and annotates values that can be identified.
- The `identify_address()` helper in `drgn.helpers.common.memory` can now identify Linux kernel vmap addresses and vmap kernel stacks.
- The `member_at_offset()` helper was added to `drgn.helpers.common.type`. It returns the name of the member at an offset in a type.
- The `bdev_partno()` helper was added to `drgn.helpers.linux.block`. It returns the partition number of a block device.
- More flexible APIs for naming, reordering, and disabling type and object finders were added.
- An API for registering custom symbol finders was added. Contributed by Stephen Brennan.
- Support for Linux 6.9 and 6.10 was added.
- The `drgn.helpers.linux.stackdepot.stack_depot_fetch()` helper was updated for Linux 6.9 (and 6.8.5).
- The `drgn.helpers.linux.block.for_each_disk()` and `drgn.helpers.linux.mm.PageSlab()` helpers were updated for Linux 6.10.
- The VMCOREINFO metadata for a kernel core dump can now be manually overridden through the Python API or the CLI. Contributed by Stephen Brennan.
- x86-64 kernel core dumps without virtual memory information can now be read. Contributed by Stephen Brennan and Illia Ostapyshyn.
- RISC-V kdump-compressed core dumps are now recognized as RISC-V when compiled with libkdumpfile 0.5.4 or newer. Contributed by Stephen Brennan.

Bug fixes:

- A case where drgn would fail to get the value of a local variable in an inlined function (usually when it had been spilled to the stack) was fixed.
- Stack traces from kernel core dumps with missing (offline or unresponsive) CPUs were fixed.
- Missing exception throws were added for some internal allocation failure checks in the drgn Python bindings.

`contrib` directory:

- `contrib/search_kernel_memory.py` was added. It searches all of kernel RAM for a given byte string.
- `contrib/gcore.py` was added. It can extract a core dump of a running process without stopping it, or of a process from a kernel core dump.
- `contrib/btrfs_tree.py` was substantially improved with new helpers and support for almost all Btrfs item types.
- `contrib/negdentdelete.py` was added. It frees negative dentries. Contributed by Stephen Brennan.
- `contrib/bpf_inspect.py` was updated to work on Linux 6.4 and later, gained a new command to list BPF links, gained an interactive mode, and added more detailed information. Contributed by Leon Hwang.
- `contrib/irq.py` was updated to work on Linux 6.5 and later. Contributed by Imran Khan.
- `contrib/lsmod.py` was updated to work on Linux 6.4 and later.

Internal:

- libdrgn's internal hash table implementation was optimized to use slightly less memory.
- Unit tests were added for a lot of libdrgn internals.
- Stephen Brennan fixed an issue with builds for free-threaded Python.
- Michel Lind enabled Packit builds for CentOS Stream 9.

This release adds several helpers, support for DWARF package files, the `fsrefs.py` tool, and a few other improvements and bug fixes.

New features:

- The `print_dmesg()` helper was added to `drgn.helpers.linux.printk`. It is a shortcut for printing the contents of the kernel log buffer.
- The `idr_for_each_entry()` helper was added to `drgn.helpers.linux.idr`.
- Helpers for the Linux kernel's plist (priority-sorted list) data structure were added in `drgn.helpers.linux.plist`. Plists are used by futexes, real-time scheduling classes, and swap.
- The `stack_depot_fetch()` helper was added in `drgn.helpers.linux.stackdepot`. It gets a stack trace from the stack depot, which is used by KASAN and other debugging tools in the kernel to store unique stack traces. Contributed by Peter Collingbourne.
- `drgn.Program.stack_trace_from_pcs()` was added. It creates a `drgn.StackTrace` from a list of program counters. Contributed by Peter Collingbourne.
- Support for Linux 6.8 was added.
- The `for_each_mount()` and `path_lookup()` helpers from `drgn.helpers.linux.fs` were updated for Linux 6.8. The `for_each_mount()` update was contributed by Johannes Thumshirn.
- DWARF package (.dwp) files are now supported when built with elfutils >= 0.191.
- `drgn.reinterpret()` can now be used for primitive scalar values (but you usually want `drgn.cast()`).
- drgn now transparently supports reading from pointers using AArch64's Top Byte Ignore (TBI) feature. Contributed by Peter Collingbourne.

Bug fixes:

- The `print_annotated_stack()` helper from `drgn.helpers.common.stack` was made more robust against corrupted stack traces.
- A memory leak when handling types with C++ template parameters was fixed.
- Types from type units from split DWARF files can now be searched by name.

Other improvements:

- `drgn.FaultError` is now imported in the CLI by default.
- `drgn.FaultError`s caused by invalid physical addresses will now indicate that the address was physical.
- Build errors when compiling against Python 3.13 alpha 4 were fixed.

Tools:

- `tools/fsrefs.py` was added. It searches for everything in the kernel referencing a file or filesystem.

`contrib` directory:

- `contrib/btrfs_orphan_subvolumes.py` was added. It looks for Btrfs subvolumes that have been deleted but not yet cleaned up.
- `contrib/dm_crypt_key.py` was added. It reads the master key of a dm-crypt device from kernel memory (currently only if the encryption mode is `aes-xts-plain64`).

This release adds some usability improvements, lots of new helpers, fixes for stack traces from exotic core dumps, and more.

New features:

- The `prog` argument can now be omitted from most function calls in the CLI. Library users can configure the same behavior with `drgn.set_default_prog()` and `drgn.get_default_prog()`.
- `drgn.stack_trace()` was added as a shortcut for `drgn.Program.stack_trace()`.
- drgn can now be run against the live kernel as a non-root user. It uses sudo to open `/proc/kcore`. Contributed by Stephen Brennan.
- Helpers for the Linux kernel's maple tree data structure were added in `drgn.helpers.linux.maple`.
- `vma_find()` and `for_each_vma()` helpers were added to `drgn.helpers.linux.mm`. They look up or iterate over virtual memory areas in an address space, respectively.
- Helpers for Linux kernel wait queues were added in `drgn.helpers.linux.wait`. Contributed by Imran Khan.
- The `drgn.helpers.linux.cpumask.cpumask_to_cpulist()` helper was added. It converts a `struct cpumask *` to a CPU list string. Contributed by Imran Khan.
- `cpu_online_mask()`, `cpu_possible_mask()`, and `cpu_present_mask()` helpers were added to `drgn.helpers.linux.cpumask`.
- Support for Linux 6.6 and 6.7 was added.
- The `drgn.helpers.linux.mm.compound_order()` helper was updated for Linux 6.6.
- The `drgn.Program.threads()` iterator was updated for Linux 6.7.
- The `drgn.helpers.linux.slab` helpers were updated to handle kernels with `CONFIG_SLUB_TINY` enabled.
- The compound page helpers in `drgn.helpers.linux.mm` were updated to handle the RHEL 7 kernel. Contributed by Oleksandr Natalenko.
- Virtual address translation support was added for ppc64. Contributed by Sourabh Jain.
- drgn now supports the flattened kdump format when built with libkdumpfile support. Contributed by Petr Tesarik.
- `drgn.Program.set_core_dump()` and `drgn.program_from_core_dump()` now accept a file descriptor. Contributed by Stephen Brennan.

Backwards-incompatible changes:

- The `allow_negative` parameter of `drgn.helpers.linux.fs.path_lookup()`, and the `src`, `dst`, and `fstype` parameters of `drgn.helpers.linux.fs.for_each_mount()` and `drgn.helpers.linux.fs.print_mounts()` are all now keyword-only. This was necessary to allow omitting the `prog` argument without ambiguity.
- Type hints are no longer supported for Python 3.6 and Python 3.7. Those Python versions are still supported at runtime.

Bug fixes:

- Stack traces were fixed for core dumps from QEMU's `dump-guest-memory` command, ppc64 vmcores on Linux 6.5+ (and recent stable kernels), and s390x vmcores.
- Type annotations and documentation for `drgn.Program.add_type_finder()` and `drgn.Program.add_object_finder()` were corrected. Contributed by Stephen Brennan.
- Relocations for 32-bit Arm and x86 were fixed to use drgn's own implementation as intended instead of libdwfl's. This is mainly a performance improvement.

Other improvements:

- The `cmdline()` and `environ()` helpers in `drgn.helpers.linux.mm` now return `None` for kernel threads instead of raising an exception. Contributed by Peter Collingbourne.
- AArch64 virtual address translation was optimized to only read the minimum amount of page table data. Contributed by Peter Collingbourne.
- The warning when debugging symbols are not found now includes a link to the drgn documentation for how to get debugging symbols. Contributed by Alex Gartrell.
- The documentation for C operator equivalents was improved.

`contrib` directory:

- `contrib/find_struct_file.py` was added. It looks for references to a `struct file *`.
- `contrib/stack_trace_call_fault.py` was added. It manually unwinds a stack trace from a call to an invalid address on x86-64.
- `contrib/irq.py` was added. It prints out IRQs, their affinities, and statistics. Contributed by Imran Khan.
- `contrib/vmmap.py` was updated to work on Linux 6.1+.