Installation
There are several options for installing drgn.
Dependencies
drgn depends on:
• Python 3.6 or newer
• elfutils 0.165 or newer
It optionally depends on:
• libkdumpfile for makedumpfile compressed kernel core dump format support
The build requires:
• GCC
• GNUMake
• pkgconf
• setuptools
Running tests requires:
• check 0.10.0 or newer
Building from the Git repository (rather than a release tarball) additionally requires:
• autoconf
• automake
• libtoolInstallationPackageManager
drgn can be installed using the package manager on some Linux distributions.
• Fedora >= 32
$ sudo dnf install drgn
• RHEL/CentOS >= 8
EnableEPEL. Then:
$ sudo dnf install drgn
• Oracle Linux >= 8
Enable the ol8_addons or ol9_addons repository and install drgn:
$ sudo dnf config-manager --enable ol8_addons # OR: ol9_addons
$ sudo dnf install drgn
Drgn is also available for Python versions in application streams. For example, use dnfinstallpython3.12-drgn to install drgn for Python 3.12. See the documentation for drgn in OracleLinux9 and
OracleLinux8 for more information.
• Arch Linux
$ sudo pacman -S drgn
• Debian >= 12 (Bookworm)
$ sudo apt install python3-drgn
• Gentoo
$ sudo emerge dev-debug/drgn
• openSUSE
$ sudo zypper install python3-drgn
• Ubuntu
Enable the michel-slm/kernel-utilsPPA. Then:
$ sudo apt install python3-drgn
pip
If your Linux distribution doesn't package the latest release of drgn, you can install it with pip.
First, installpip. Then, run:
$ sudo pip3 install drgn
This will install a binary wheel by default. If you get a build error, then pip wasn't able to use the
binary wheel. Install the dependencies listed below and try again.
Note that RHEL/CentOS 6, Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and older) ship Python
versions which are too old. Python 3.6 or newer must be installed.
FromSource
To get the development version of drgn, you will need to build it from source. First, install
dependencies:
• Fedora
$ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
• RHEL/CentOS/Oracle Linux
$ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
Optionally, install libkdumpfile-devel from EPEL on RHEL/CentOS >= 8 or install libkdumpfile from
source if you want support for the makedumpfile format. For Oracle Linux >= 7, libkdumpfile-devel can
be installed directly from the corresponding addons repository (e.g. ol9_addons).
Replace dnf with yum for RHEL/CentOS/Oracle Linux < 8.
When building on RHEL/CentOS/Oracle Linux < 8, you may need to use a newer version of GCC, for example,
using the devtoolset-12 developer toolset. Check your distribution's documentation for information on
installing and using these newer toolchains.
• Debian/Ubuntu
$ sudo apt install autoconf automake check gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
Optionally, install libkdumpfile from source if you want support for the makedumpfile format.
• Arch Linux
$ sudo pacman -S --needed autoconf automake check gcc git libelf libkdumpfile libtool make pkgconf python python-pip python-setuptools
• Gentoo
$ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils sys-devel/gcc dev-vcs/git dev-libs/libkdumpfile dev-build/libtool dev-build/make dev-python/pip virtual/pkgconfig dev-lang/python dev-python/setuptools
• openSUSE
$ sudo zypper install autoconf automake check-devel gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
Then, run:
$ git clone https://github.com/osandov/drgn.git
$ cd drgn
$ python3 setup.py build
$ sudo python3 setup.py install
VirtualEnvironment
The above options all install drgn globally. You can also install drgn in a virtualenvironment, either
with pip:
$ python3 -m venv drgnenv
$ source drgnenv/bin/activate
(drgnenv) $ pip3 install drgn
(drgnenv) $ drgn --help
Or from source:
$ python3 -m venv drgnenv
$ source drgnenv/bin/activate
(drgnenv) $ python3 setup.py install
(drgnenv) $ drgn --help
RunningLocally
If you build drgn from source, you can also run it without installing it:
$ python3 setup.py build_ext -i
$ python3 -m drgn --help
UserGuideQuickStart
drgn debugs the running kernel by default; run sudodrgn. To debug a running program, run sudodrgn-p$PID. To debug a core dump (either a kernel vmcore or a userspace core dump), run drgn-c$PATH. Make
sure to installdebuggingsymbols for whatever you are debugging.
Then, you can access variables in the program with prog['name'] and access structure members with .:
$ sudo drgn
>>> prog['init_task'].comm
(char [16])"swapper/0"
You can use various predefined helpers:
>>> len(list(bpf_prog_for_each()))
11
>>> task = find_task(115)
>>> cmdline(task)
[b'findmnt', b'-p']
You can get stack traces with stack_trace() and access parameters or local variables with trace['name']:
>>> trace = stack_trace(task)
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> poll_list = trace[5]['list']
>>> file = fget(task, poll_list.entries[0].fd)
>>> d_path(file.f_path.address_of_())
b'/proc/115/mountinfo'
CoreConcepts
The most important interfaces in drgn are programs, objects, and helpers.
Programs
A program being debugged is represented by an instance of the drgn.Program class. The drgn CLI is
initialized with a Program named prog; unless you are using the drgn library directly, this is usually
the only Program you will need.
A Program is used to look up type definitions, access variables, and read arbitrary memory:
>>> prog.type('unsigned long')
prog.int_type(name='unsigned long', size=8, is_signed=False)
>>> prog['jiffies']
Object(prog, 'volatile unsigned long', address=0xffffffffbe405000)
>>> prog.read(0xffffffffbe411e10, 16)
b'swapper/0\x00\x00\x00\x00\x00\x00\x00'
The drgn.Program.type(), drgn.Program.variable(), drgn.Program.constant(), and drgn.Program.function()
methods look up those various things in a program. drgn.Program.read() reads memory from the program's
address space. The [] operator looks up a variable, constant, or function:
>>> prog['jiffies'] == prog.variable('jiffies')
True
It is usually more convenient to use the [] operator rather than the variable(), constant(), or
function() methods unless the program has multiple objects with the same name, in which case the methods
provide more control.
Objects
Variables, constants, functions, and computed values are all called objects in drgn. Objects are
represented by the drgn.Object class. An object may exist in the memory of the program (a reference):
>>> Object(prog, 'int', address=0xffffffffc09031a0)
Or, an object may be a constant or temporary computed value (a value):
>>> Object(prog, 'int', value=4)
What makes drgn scripts expressive is that objects can be used almost exactly like they would be in the
program's own source code. For example, structure members can be accessed with the dot (.) operator,
arrays can be subscripted with [], arithmetic can be performed, and objects can be compared:
>>> print(prog['init_task'].comm[0])
(char)115
>>> print(repr(prog['init_task'].nsproxy.mnt_ns.mounts + 1))
Object(prog, 'unsigned int', value=34)
>>> prog['init_task'].nsproxy.mnt_ns.pending_mounts > 0
False
Python doesn't have all of the operators that C or C++ do, so some substitutions are necessary:
• Instead of *ptr, dereference a pointer with ptr[0].
• Instead of ptr->member, access a member through a pointer with ptr.member.
• Instead of &var, get the address of a variable with var.address_of_().
A common use case is converting a drgn.Object to a Python value so it can be used by a standard Python
library. There are a few ways to do this:
• The drgn.Object.value_() method gets the value of the object with the directly corresponding Python
type (i.e., integers and pointers become int, floating-point types become float, booleans become bool,
arrays become list, structures and unions become dict).
• The drgn.Object.string_() method gets a null-terminated string as bytes from an array or pointer.
• The int(), float(), and bool() functions do an explicit conversion to that Python type.
Objects have several attributes; the most important are drgn.Object.prog_ and drgn.Object.type_. The
former is the drgn.Program that the object is from, and the latter is the drgn.Type of the object.
Note that all attributes and methods of the Object class end with an underscore (_) in order to avoid
conflicting with structure or union members. The Object attributes and methods always take precedence;
use drgn.Object.member_() if there is a conflict.
Referencesvs.Values
The main difference between reference objects and value objects is how they are evaluated. References are
read from the program's memory every time they are evaluated; values simply return the stored value (‐
drgn.Object.read_() reads a reference object and returns it as a value object):
>>> import time
>>> jiffies = prog['jiffies']
>>> jiffies.value_()
4391639989
>>> time.sleep(1)
>>> jiffies.value_()
4391640290
>>> jiffies2 = jiffies.read_()
>>> jiffies2.value_()
4391640291
>>> time.sleep(1)
>>> jiffies2.value_()
4391640291
>>> jiffies.value_()
4391640593
References have a drgn.Object.address_ attribute, which is the object's address as a Python int. This is
slightly different from the drgn.Object.address_of_() method, which returns the address as a drgn.Object.
Of course, both references and values can have a pointer type; address_ refers to the address of the
pointer object itself, and drgn.Object.value_() refers to the value of the pointer (i.e., the address it
points to):
>>> address = prog['jiffies'].address_
>>> type(address)
<class 'int'>
>>> print(hex(address))
0xffffffffbe405000
>>> jiffiesp = prog['jiffies'].address_of_()
>>> jiffiesp
Object(prog, 'volatile unsigned long *', value=0xffffffffbe405000)
>>> print(hex(jiffiesp.value_()))
0xffffffffbe405000
AbsentObjects
In addition to reference objects and value objects, objects may also be absent.
>>> Object(prog, "int").value_()
Traceback (most recent call last):
File "<console>", line 1, in <module>
_drgn.ObjectAbsentError: object absent
This represents an object whose value or address is not known. For example, this can happen if the object
was optimized out of the program by the compiler.
Any attempt to operate on an absent object results in a drgn.ObjectAbsentError exception, although basic
information including its type may still be accessed.
Helpers
Some programs have common data structures that you may want to examine. For example, consider linked
lists in the Linux kernel:
struct list_head {
struct list_head *next, *prev;
};
#define list_for_each(pos, head) \
for (pos = (head)->next; pos != (head); pos = pos->next)
When working with these lists, you'd probably want to define a function:
def list_for_each(head):
pos = head.next
while pos != head:
yield pos
pos = pos.next
Then, you could use it like so for any list you need to look at:
>>> for pos in list_for_each(head):
... do_something_with(pos)
Of course, it would be a waste of time and effort for everyone to have to define these helpers for
themselves, so drgn includes a collection of helpers for many use cases. See Helpers.
Validators
Validators are a special category of helpers that check the consistency of a data structure. In general,
helpers assume that the data structures that they examine are valid. Validators do not make this
assumption and do additional (potentially expensive) checks to detect broken invariants, corruption, etc.
Validators raise drgn.helpers.ValidationError if the data structure is not valid or drgn.FaultError if
the data structure is invalid in a way that causes a bad memory access. They have names prefixed with
validate_.
For example, drgn.helpers.linux.list.validate_list() checks the consistency of a linked list in the Linux
kernel (in particular, the consistency of the next and prev pointers):
>>> validate_list(prog["my_list"].address_of_())
drgn.helpers.ValidationError: (struct list_head *)0xffffffffc029e460 next 0xffffffffc029e000 has prev 0xffffffffc029e450
drgn.helpers.linux.list.validate_list_for_each_entry() does the same checks while also returning the
entries in the list for further validation:
def validate_my_list(prog):
for entry in validate_list_for_each_entry(
"struct my_entry",
prog["my_list"].address_of_(),
"list",
):
if entry.value < 0:
raise ValidationError("list contains negative entry")
OtherConcepts
In addition to the core concepts above, drgn provides a few additional abstractions.
Threads
The drgn.Thread class represents a thread. drgn.Program.threads(), drgn.Program.thread(),
drgn.Program.main_thread(), and drgn.Program.crashed_thread() can be used to find threads:
>>> for thread in prog.threads():
... print(thread.tid)
...
39143
39144
>>> print(prog.main_thread().tid)
39143
>>> print(prog.crashed_thread().tid)
39144
StackTraces
drgn represents stack traces with the drgn.StackTrace and drgn.StackFrame classes. drgn.stack_trace(),
drgn.Program.stack_trace(), and drgn.Thread.stack_trace() return the call stack for a thread. The []
operator looks up an object in the scope of a StackFrame:
>>> trace = stack_trace(115)
>>> trace
#0 context_switch (./kernel/sched/core.c:4683:2)
#1 __schedule (./kernel/sched/core.c:5940:8)
#2 schedule (./kernel/sched/core.c:6019:3)
#3 schedule_hrtimeout_range_clock (./kernel/time/hrtimer.c:2148:3)
#4 poll_schedule_timeout (./fs/select.c:243:8)
#5 do_poll (./fs/select.c:961:8)
#6 do_sys_poll (./fs/select.c:1011:12)
#7 __do_sys_poll (./fs/select.c:1076:8)
#8 __se_sys_poll (./fs/select.c:1064:1)
#9 __x64_sys_poll (./fs/select.c:1064:1)
#10 do_syscall_x64 (./arch/x86/entry/common.c:50:14)
#11 do_syscall_64 (./arch/x86/entry/common.c:80:7)
#12 entry_SYSCALL_64+0x7c/0x15b (./arch/x86/entry/entry_64.S:113)
#13 0x7f3344072af7
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> prog['do_poll']
(int (struct poll_list *list, struct poll_wqueues *wait, struct timespec64 *end_time))<absent>
>>> trace[5]['list']
*(struct poll_list *)0xffffacca402e3b50 = {
.next = (struct poll_list *)0x0,
.len = (int)1,
.entries = (struct pollfd []){},
}
Symbols
The symbol table of a program is a list of identifiers along with their address and size. drgn represents
symbols with the drgn.Symbol class, which is returned by drgn.Program.symbol().
Types
drgn automatically obtains type definitions from the program. Types are represented by the drgn.Type
class and created by various factory functions like drgn.Program.int_type():
>>> prog.type('int')
prog.int_type(name='int', size=4, is_signed=True)
You won't usually need to work with types directly, but see Types if you do.
Platforms
Certain operations and objects in a program are platform-dependent; drgn allows accessing the platform
that a program runs with the drgn.Platform class.
CommandLineInterface
The drgn CLI is basically a wrapper around the drgn library which automatically creates a drgn.Program.
The CLI can be run in interactive mode or script mode.
ScriptMode
Script mode is useful for reusable scripts. Simply pass the path to the script along with any arguments:
$ cat script.py
import sys
from drgn.helpers.linux import find_task
pid = int(sys.argv[1])
uid = find_task(pid).cred.uid.val.value_()
print(f'PID {pid} is being run by UID {uid}')
$ sudo drgn script.py 601
PID 601 is being run by UID 1000
It's even possible to run drgn scripts directly with the proper shebang:
$ cat script2.py
#!/usr/bin/env drgn
mounts = prog['init_task'].nsproxy.mnt_ns.mounts.value_()
print(f'You have {mounts} filesystems mounted')
$ sudo ./script2.py
You have 36 filesystems mounted
InteractiveMode
Interactive mode uses the Python interpreter's interactivemode and adds a few nice features, including:
• History
• Tab completion
• Automatic import of relevant helpers
• Pretty printing of objects and types
The default behavior of the Python REPL is to print the output of repr(). For drgn.Object and drgn.Type,
this is a raw representation:
>>> print(repr(prog['jiffies']))
Object(prog, 'volatile unsigned long', address=0xffffffffbe405000)
>>> print(repr(prog.type('atomic_t')))
prog.typedef_type(name='atomic_t', type=prog.struct_type(tag=None, size=4, members=(TypeMember(prog.type('int'), name='counter', bit_offset=0),)))
The standard print() function uses the output of str(). For drgn objects and types, this is a
representation in programming language syntax:
>>> print(prog['jiffies'])
(volatile unsigned long)4395387628
>>> print(prog.type('atomic_t'))
typedef struct {
int counter;
} atomic_t
In interactive mode, the drgn CLI automatically uses str() instead of repr() for objects and types, so
you don't need to call print() explicitly:
$ sudo drgn
>>> prog['jiffies']
(volatile unsigned long)4395387628
>>> prog.type('atomic_t')
typedef struct {
int counter;
} atomic_t
NextSteps
Refer to the APIReference. Look through the Helpers. Read some CaseStudies. Browse through the tools.
Check out the communitycontributions.
AdvancedUsage
The UserGuide covers basic usage of drgn, but drgn also supports more advanced use cases which are
covered here.
LoadingDebuggingSymbols
drgn will automatically load debugging information based on the debugged program (e.g., from loaded
kernel modules or loaded shared libraries). drgn.Program.load_debug_info() can be used to load
additional debugging information:
>>> prog.load_debug_info(['./libfoo.so', '/usr/lib/libbar.so'])
Library
In addition to the CLI, drgn is also available as a library. drgn.program_from_core_dump(),
drgn.program_from_kernel(), and drgn.program_from_pid() correspond to the -c, -k, and -p command line
options, respectively; they return a drgn.Program that can be used just like the one initialized by the
CLI:
>>> import drgn
>>> prog = drgn.program_from_kernel()
CLibrary
The core functionality of drgn is implemented in C and is available as a C library, libdrgn. See drgn.h.
Full documentation can be generated by running doxygen in the libdrgn directory of the source code. Note
that the API and ABI are not yet stable.
CustomPrograms
The main components of a drgn.Program are the program memory, types, and symbols. The CLI and equivalent
library interfaces automatically determine these. However, it is also possible to create a "blank"
Program and plug in the main components. The drgn.cli.run_interactive() function allows you to run the
same drgn CLI once you've created a drgn.Program, so it's easy to make a custom program which allows
interactive debugging.
drgn.Program.add_memory_segment() defines a range of memory and how to read that memory. The following
example uses a Btrfs filesystem image as the program "memory":
import drgn
import os
import sys
from drgn.cli import run_interactive
def btrfs_debugger(dev):
file = open(dev, 'rb')
size = file.seek(0, 2)
def read_file(address, count, offset, physical):
file.seek(offset)
return file.read(count)
platform = drgn.Platform(drgn.Architecture.UNKNOWN,
drgn.PlatformFlags.IS_LITTLE_ENDIAN)
prog = drgn.Program(platform)
prog.add_memory_segment(0, size, read_file)
prog.load_debug_info([f'/lib/modules/{os.uname().release}/kernel/fs/btrfs/btrfs.ko'])
return prog
prog = btrfs_debugger(sys.argv[1] if len(sys.argv) >= 2 else '/dev/sda')
print(drgn.Object(prog, 'struct btrfs_super_block', address=65536))
run_interactive(prog, banner_func=lambda _: "BTRFS debugger")
drgn.Program.register_type_finder() and drgn.Program.register_object_finder() are the equivalent methods
for plugging in types and objects.
EnvironmentVariables
Some of drgn's behavior can be modified through environment variables:
DRGN_MAX_DEBUG_INFO_ERRORS
The maximum number of individual errors to report in a drgn.MissingDebugInfoError. Any additional
errors are truncated. The default is 5; -1 is unlimited.
DRGN_PREFER_ORC_UNWINDER
Whether to prefer using ORC over DWARF for stack unwinding (0 or 1). The default is 0. Note that
drgn will always fall back to ORC for functions lacking DWARF call frame information and vice
versa. This environment variable is mainly intended for testing and may be ignored in the future.
DRGN_USE_LIBDWFL_REPORT
Whether drgn should use libdwfl to find debugging information for core dumps instead of its own
implementation (0 or 1). The default is 0. This environment variable is mainly intended as an
escape hatch in case of bugs in drgn's implementation and will be ignored in the future.
DRGN_USE_LIBKDUMPFILE_FOR_ELF
Whether drgn should use libkdumpfile for ELF vmcores (0 or 1). The default is 0. This
functionality will be removed in the future.
DRGN_USE_SYS_MODULE
Whether drgn should use /sys/module to find information about loaded kernel modules for the
running kernel instead of getting them from the core dump (0 or 1). The default is 1. This
environment variable is mainly intended for testing and may be ignored in the future.
PYTHON_BASIC_REPL
If non-empty, don't try to use the newinteractiveREPL added in Python 3.13. drgn makes use of
the new REPL through internal implementation details since there is notyet a public API for it.
If it breaks, this may be used as an escape hatch.
LinuxKernelSpecialObjects
When debugging the Linux kernel, there are some special drgn.Objects accessible with
drgn.Program.object() and drgn.Program[]. Some of these are available even without debugging information,
thanks to metadata called "vmcoreinfo" which is present in kernel core dumps. These special objects
include:
UTS_RELEASE
Object type: constchar[]
This corresponds to the UTS_RELEASE macro in the Linux kernel source code. This is the exact
kernel release (i.e., the output of uname-r).
To use this as a Python string, you must convert it:
>>> release = prog["UTS_RELEASE"].string_().decode("ascii")
This is available without debugging information.
PAGE_SIZE
Object type: unsignedlongPAGE_SHIFT
Object type: unsignedintPAGE_MASK
Object type: unsignedlong
These correspond to the macros of the same name in the Linux kernel source code. The page size is
the smallest contiguous unit of physical memory which can be allocated or mapped by the kernel.
>>> prog['PAGE_SIZE']
(unsigned long)4096
>>> prog['PAGE_SHIFT']
(int)12
>>> prog['PAGE_MASK']
(unsigned long)18446744073709547520
>>> 1 << prog['PAGE_SHIFT'] == prog['PAGE_SIZE']
True
>>> ~(prog['PAGE_SIZE'] - 1) == prog['PAGE_MASK']
True
These are available without debugging information.
jiffies
Object type: volatileunsignedlong
This is a counter of timer ticks. It is actually an alias of jiffies_64 on 64-bit architectures,
or the least significant 32 bits of jiffies_64 on 32-bit architectures. Since this alias is
defined via the linker, drgn handles it specially.
This is not available without debugging information.
vmemmap
Object type: structpage*
This is a pointer to the "virtual memory map", an array of structpage for each physical page of
memory. While the purpose and implementation details of this array are beyond the scope of this
documentation, it is enough to say that it is represented in the kernel source in an
architecture-dependent way, frequently as a macro or constant. The definition provided by drgn
ensures that users can access it without resorting to architecture-specific logic.
This is not available without debugging information.
VMCOREINFO
Object type: constchar[]
This is the data contained in the vmcoreinfo note, which is present either as an ELF note in
/proc/kcore or ELF vmcores, or as a special data section in kdump-formatted vmcores. The
vmcoreinfo note contains critical data necessary for interpreting the kernel image, such as KASLR
offsets and data structure locations.
In the Linux kernel, this data is normally stored in a variable called vmcoreinfo_data. However,
drgn reads this information from ELF note or from the diskdump header. It is possible (in rare
cases, usually with vmcores created by hypervisors) for a vmcore to contain vmcoreinfo which
differs from the data in vmcoreinfo_data, so it is important to distinguish the contents. For that
reason, we use the name VMCOREINFO to distinguish it from the kernel variable vmcoreinfo_data.
This is available without debugging information.
APIReferenceProgramsclassdrgn.Program
A Program represents a crashed or running program. It can be used to lookup type definitions,
access variables, and read arbitrary memory.
The main functionality of a Program is looking up objects (i.e., variables, constants, or
functions). This is usually done with the [] operator.
Program(platform:Optional[Platform]=None,*,vmcoreinfo:Union[bytes,str,None]=None)
Create a Program with no target program. It is usually more convenient to use one of the
ProgramConstructors.
Parameters
• platform -- The platform of the program, or None if it should be determined
automatically when a core dump or symbol file is added.
• vmcoreinfo -- Optionally provide the VMCOREINFO note data for Linux kernel core
dumps, which will override any detected data. When not provided or None,
automatically detect the info.
flags:ProgramFlags
Flags which apply to this program.
platform:Optional[Platform]
Platform that this program runs on, or None if it has not been determined yet.
language:Language
Default programming language of the program.
This is used for interpreting the type name given to type() and when creating an Object
without an explicit type.
For the Linux kernel, this defaults to Language.C. For userspace programs, this defaults to
the language of main in the program, falling back to Language.C. This heuristic may change
in the future.
This can be explicitly set to a different language (e.g., if the heuristic was incorrect).
__getitem__(name:str)->Object
Implement self[name]. Get the object (variable, constant, or function) with the given name.
This is equivalent to prog.object(name) except that this raises KeyError instead of
LookupError if no objects with the given name are found.
If there are multiple objects with the same name, one is returned arbitrarily. In this
case, the variable(), constant(), function(), or object() methods can be used instead.
>>> prog['jiffies']
Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
Parametersname -- Object name.
__contains__(name:str)->bool
Implement nameinself. Return whether an object (variable, constant, or function) with the
given name exists in the program.
Parametersname -- Object name.
variable(name:str,filename:Optional[str]=None)->Object
Get the variable with the given name.
>>> prog.variable('jiffies')
Object(prog, 'volatile unsigned long', address=0xffffffff94c05000)
This is equivalent to prog.object(name,FindObjectFlags.VARIABLE,filename).
Parameters
• name -- The variable name.
• filename -- The source code file that contains the definition. See Filenames.
RaisesLookupError -- if no variables with the given name are found in the given file
constant(name:str,filename:Optional[str]=None)->Object
Get the constant (e.g., enumeration constant) with the given name.
Note that support for macro constants is not yet implemented for DWARF files, and most
compilers don't generate macro debugging information by default anyways.
>>> prog.constant('PIDTYPE_MAX')
Object(prog, 'enum pid_type', value=4)
This is equivalent to prog.object(name,FindObjectFlags.CONSTANT,filename).
Parameters
• name -- The constant name.
• filename -- The source code file that contains the definition. See Filenames.
RaisesLookupError -- if no constants with the given name are found in the given file
function(name:str,filename:Optional[str]=None)->Object
Get the function with the given name.
>>> prog.function('schedule')
Object(prog, 'void (void)', address=0xffffffff94392370)
This is equivalent to prog.object(name,FindObjectFlags.FUNCTION,filename).
Parameters
• name -- The function name.
• filename -- The source code file that contains the definition. See Filenames.
RaisesLookupError -- if no functions with the given name are found in the given file
object(name:str,flags:FindObjectFlags=FindObjectFlags.ANY,filename:Optional[str]=None)->Object
Get the object (variable, constant, or function) with the given name.
When debugging the Linux kernel, this can look up certain special objects documented in
LinuxKernelSpecialObjects, sometimes without any debugging information loaded.
Parameters
• name -- The object name.
• flags -- Flags indicating what kind of object to look for.
• filename -- The source code file that contains the definition. See Filenames.
RaisesLookupError -- if no objects with the given name are found in the given file
symbol(address_or_name:Union[IntegerLike,str],/)->Symbol
Get a symbol containing the given address, or a symbol with the given name.
Global symbols are preferred over weak symbols, and weak symbols are preferred over other
symbols. In other words: if a matching SymbolBinding.GLOBAL or SymbolBinding.UNIQUE symbol
is found, it is returned. Otherwise, if a matching SymbolBinding.WEAK symbol is found, it
is returned. Otherwise, any matching symbol (e.g., SymbolBinding.LOCAL) is returned. If
there are multiple matching symbols with the same binding, one is returned arbitrarily. To
retrieve all matching symbols, use symbols().
Parametersaddress_or_name -- Address or name to search for.
RaisesLookupError -- if no symbol contains the given address or matches the given name
symbols(address_or_name:Union[None,IntegerLike,str]=None,/)->List[Symbol]
Get a list of global and local symbols, optionally matching a name or address.
If a string argument is given, this returns all symbols matching that name. If an
integer-like argument given, this returns a list of all symbols containing that address. If
no argument is given, all symbols in the program are returned. In all cases, the symbols
are returned in an unspecified order.
Parametersaddress_or_name -- Address or name to search for.
stack_trace(thread:Union[Object,IntegerLike])->StackTrace
Get the stack trace for the given thread in the program.
thread may be a thread ID (as defined by gettid(2)),inwhichcasethiswillunwindthestackforthethreadwiththatID.TheIDmaybeaPythonintoranintegerObjectthreadmayalsobeastructpt_regsorstructpt_regs*object,inwhichcasetheinitialregistervalueswillbefetchedfromthatobject.Finally,ifdebuggingtheLinuxkernel,threadmaybeastructtask_struct*object,inwhichcasethiswillunwindthestackforthattask.Seedrgn.helpers.linux.pid.find_task().ThisisimplementedfortheLinuxkernel(bothliveandcoredumps)aswellasuserspacecoredumps;itisnotyetimplementedforliveuserspaceprocesses.Parametersthread -- Thread ID, structpt_regs object, or structtask_struct* object.
stack_trace_from_pcs(pcs:Sequence[IntegerLike])->StackTrace
Get a stack trace with the supplied list of program counters.
Parameterspcs -- List of program counters.
type(name:str,filename:Optional[str]=None)->Type
Get the type with the given name.
>>> prog.type('long')
prog.int_type(name='long', size=8, is_signed=True)
Parameters
• name -- The type name.
• filename -- The source code file that contains the definition. See Filenames.
RaisesLookupError -- if no types with the given name are found in the given file
type(type:Type,/)->Type
Return the given type.
This is mainly useful so that helpers can use prog.type() to get a Type regardless of
whether they were given a str or a Type. For example:
def my_helper(obj: Object, type: Union[str, Type]) -> bool:
# type may be str or Type.
type = obj.prog_.type(type)
# type is now always Type.
return sizeof(obj) > sizeof(type)
Parameterstype -- Type.
Returns
The exact same type.
threads()->Iterator[Thread]
Get an iterator over all of the threads in the program.
thread(tid:IntegerLike)->Thread
Get the thread with the given thread ID.
Parameterstid -- Thread ID (as defined by gettid(2)).RaisesLookupError -- if no thread has the given thread ID
main_thread()->Thread
Get the main thread of the program.
This is only defined for userspace programs.
RaisesValueError -- if the program is the Linux kernel
crashed_thread()->Thread
Get the thread that caused the program to crash.
For userspace programs, this is the thread that received the fatal signal (e.g., SIGSEGV or
SIGQUIT).
For the kernel, this is the thread that panicked (either directly or as a result of an
oops, BUG_ON(), etc.).
RaisesValueError -- if the program is live (i.e., not a core dump)
read(address:IntegerLike,size:IntegerLike,physical:bool=False)->bytes
Read size bytes of memory starting at address in the program. The address may be virtual
(the default) or physical if the program supports it.
>>> prog.read(0xffffffffbe012b40, 16)
b'swapper/0'
Parameters
• address -- The starting address.
• size -- The number of bytes to read.
• physical -- Whether address is a physical memory address. If False, then it is a
virtual memory address. Physical memory can usually only be read when the program
is an operating system kernel.
Raises
• FaultError -- if the address range is invalid or the type of address (physical or
virtual) is not supported by the program
• ValueError -- if size is negative
read_u8(address:IntegerLike,physical:bool=False)->intread_u16(address:IntegerLike,physical:bool=False)->intread_u32(address:IntegerLike,physical:bool=False)->intread_u64(address:IntegerLike,physical:bool=False)->intread_word(address:IntegerLike,physical:bool=False)->int
Read an unsigned integer from the program's memory in the program's byte order.
read_u8(), read_u16(), read_u32(), and read_u64() read an 8-, 16-, 32-, or 64-bit unsigned
integer, respectively. read_word() reads a program word-sized unsigned integer.
For signed integers, alternate byte order, or other formats, you can use read() and
int.from_bytes() or the struct module.
Parameters
• address -- Address of the integer.
• physical -- Whether address is a physical memory address; see read().
RaisesFaultError -- if the address is invalid; see read()add_memory_segment(address:IntegerLike,size:IntegerLike,read_fn:Callable[[int,int,int,bool],bytes],physical:bool=False)->None
Define a region of memory in the program.
If it overlaps a previously registered segment, the new segment takes precedence.
Parameters
• address -- Address of the segment.
• size -- Size of the segment in bytes.
• physical -- Whether to add a physical memory segment. If False, then this adds a
virtual memory segment.
• read_fn -- Callable to call to read memory from the segment. It is passed the
address being read from, the number of bytes to read, the offset in bytes from the
beginning of the segment, and whether the address is physical: (address,count,offset,physical). It should return the requested number of bytes as bytes or
another buffer type.
register_type_finder(name:str,fn:Callable[[Program,TypeKindSet,str,Optional[str]],Optional[Type]],*,enable_index:Optional[int]=None)->None
Register a callback for finding types in the program.
This does not enable the finder unless enable_index is given.
Parameters
• name -- Finder name.
• fn -- Callable taking the program, a TypeKindSet, name, and filename: (prog,kinds,name,filename). The filename should be matched with filename_matches().
This should return a Type or None if not found.
• enable_index -- Insert the finder into the list of enabled type finders at the
given index. If -1 or greater than the number of enabled finders, insert it at the
end. If None or not given, don't enable the finder.
RaisesValueError -- if there is already a finder with the given name
registered_type_finders()->Set[str]
Return the names of all registered type finders.
set_enabled_type_finders(names:Sequence[str])->None
Set the list of enabled type finders.
Finders are called in the same order as the list until a type is found.
Finders that are not in the list are not called.
Parametersnames -- Names of finders to enable, in order.
RaisesValueError -- if no finder has a given name or the same name is given more than once
enabled_type_finders()->List[str]
Return the names of enabled type finders, in order.
register_object_finder(name:str,fn:Callable[[Program,str,FindObjectFlags,Optional[str]],Optional[Object]],*,enable_index:Optional[int]=None)->None
Register a callback for finding objects in the program.
This does not enable the finder unless enable_index is given.
Parameters
• name -- Finder name.
• fn -- Callable taking the program, name, FindObjectFlags, and filename: (prog,name,flags,filename). The filename should be matched with filename_matches().
This should return an Object or None if not found.
• enable_index -- Insert the finder into the list of enabled object finders at the
given index. If -1 or greater than the number of enabled finders, insert it at the
end. If None or not given, don't enable the finder.
RaisesValueError -- if there is already a finder with the given name
registered_object_finders()->Set[str]
Return the names of all registered object finders.
set_enabled_object_finders(names:Sequence[str])->None
Set the list of enabled object finders.
Finders are called in the same order as the list until an object is found.
Finders that are not in the list are not called.
Parametersnames -- Names of finders to enable, in order.
RaisesValueError -- if no finder has a given name or the same name is given more than once
enabled_object_finders()->List[str]
Return the names of enabled object finders, in order.
register_symbol_finder(name:str,fn:Callable[[Program,Optional[str],Optional[int],bool],Sequence[Symbol]],*,enable_index:Optional[int]=None)->None
Register a callback for finding symbols in the program.
This does not enable the finder unless enable_index is given.
The callback should take four arguments: the program, a name, an address, and a boolean
flag one. It should return a list of symbols or an empty list if no matches are found.
If name is not None, then only symbols with that name should be returned. If address is not
None, then only symbols containing that address should be returned. If neither is None,
then the returned symbols must match both. If both are None, then all symbols should be
considered matching.
When the one flag is False, the callback should return a list of all matching symbols. When
it is True, it should return a list with at most one symbol which is the best match.
Parameters
• name -- Finder name.
• fn -- Callable taking (prog,name,address,one) and returning a sequence of
Symbols.
• enable_index -- Insert the finder into the list of enabled finders at the given
index. If -1 or greater than the number of enabled finders, insert it at the end.
If None or not given, don't enable the finder.
RaisesValueError -- if there is already a finder with the given name
registered_symbol_finders()->Set[str]
Return the names of all registered symbol finders.
set_enabled_symbol_finders(names:Sequence[str])->None
Set the list of enabled symbol finders.
Finders are called in the same order as the list. When the one flag is set, the search will
short-circuit after the first finder which returns a result, and subsequent finders will
not be called. Otherwise, all callbacks will be called, and all results will be returned.
Finders that are not in the list are not called.
Parametersnames -- Names of finders to enable, in order.
RaisesValueError -- if no finder has a given name or the same name is given more than once
enabled_symbol_finders()->List[str]
Return the names of enabled symbol finders, in order.
add_type_finder(fn:Callable[[TypeKind,str,Optional[str]],Optional[Type]])->None
Deprecated method to register and enable a callback for finding types in the program.
Deprecated since version 0.0.27: Use register_type_finder() instead.
The differences from register_type_finder() are:
1. fn is not passed prog.
2. fn is passed a TypeKind instead of a TypeKindSet. If multiple kinds are being searched
for, fn will be called multiple times.
3. A name for the finder is generated from fn.
4. The finder is always enabled before any existing finders.
add_object_finder(fn:Callable[[Program,str,FindObjectFlags,Optional[str]],Optional[Object]])->None
Deprecated method to register and enable a callback for finding objects in the program.
Deprecated since version 0.0.27: Use register_object_finder() instead.
The differences from register_object_finder() are:
1. A name for the finder is generated from fn.
2. The finder is always enabled before any existing finders.
set_core_dump(path:Union[Path,int])->None
Set the program to a core dump.
This loads the memory segments from the core dump and determines the mapped executable and
libraries. It does not load any debugging symbols; see load_default_debug_info().
Parameterspath -- Core dump file path or open file descriptor.
set_kernel()->None
Set the program to the running operating system kernel.
This loads the memory of the running kernel and thus requires root privileges. It does not
load any debugging symbols; see load_default_debug_info().
set_pid(pid:int)->None
Set the program to a running process.
This loads the memory of the process and determines the mapped executable and libraries. It
does not load any debugging symbols; see load_default_debug_info().
Parameterspid -- Process ID.
load_debug_info(paths:Optional[Iterable[Path]]=None,default:bool=False,main:bool=False)->None
Load debugging information for a list of executable or library files.
Note that this is parallelized, so it is usually faster to load multiple files at once
rather than one by one.
Parameters
• paths -- Paths of binary files.
• default --
Also load debugging information which can automatically be determined from the
program.
For the Linux kernel, this tries to load vmlinux and any loaded kernel modules
from a few standard locations.
For userspace programs, this tries to load the executable and any loaded
libraries.
This implies main=True.
• main --
Also load debugging information for the main executable.
For the Linux kernel, this tries to load vmlinux.
This is currently ignored for userspace programs.
RaisesMissingDebugInfoError -- if debugging information was not available for some files;
other files with debugging information are still loaded
load_default_debug_info()->None
Load debugging information which can automatically be determined from the program.
This is equivalent to load_debug_info(None,True).
cache:Dict[Any,Any]
Dictionary for caching program metadata.
This isn't used by drgn itself. It is intended to be used by helpers to cache metadata
about the program. For example, if a helper for a program depends on the program version or
an optional feature, the helper can detect it and cache it for subsequent invocations:
def my_helper(prog):
try:
have_foo = prog.cache['have_foo']
except KeyError:
have_foo = detect_foo_feature(prog)
prog.cache['have_foo'] = have_foo
if have_foo:
return prog['foo']
else:
return prog['bar']
classdrgn.ProgramFlags
Bases: enum.FlagProgramFlags are flags that can apply to a Program (e.g., about what kind of program it is).
IS_LINUX_KERNEL
The program is the Linux kernel.
IS_LIVE
The program is currently running (e.g., it is the running operating system kernel or a
running process).
IS_LOCAL
The program is running on the local machine.
classdrgn.FindObjectFlags
Bases: enum.FlagFindObjectFlags are flags for Program.object(). These can be combined to search for multiple kinds
of objects at once.
CONSTANTFUNCTIONVARIABLEANYclassdrgn.Thread
A thread in a program.
tid:Final[int]
Thread ID (as defined by gettid(2)).name:Optional[str]
Thread name, or None if unknown.
See PR_SET_NAME and /proc/pid/comm.
NOTE:
Linux userspace core dumps only save the name of the main thread, so name will be None
for other threads.
object:Final[Object]
If the program is the Linux kernel, the structtask_struct* object for this thread.
Otherwise, not defined.
stack_trace()->StackTrace
Get the stack trace for this thread.
This is equivalent to prog.stack_trace(thread.tid). See Program.stack_trace().
Filenames
The Program.type(), Program.object(), Program.variable(), Program.constant(), and Program.function()
methods all take a filename parameter to distinguish between multiple definitions with the same name. The
filename refers to the source code file that contains the definition. It is matched with
filename_matches(). If multiple definitions match, one is returned arbitrarily.
drgn.filename_matches(haystack:Optional[str],needle:Optional[str])->bool
Return whether a filename containing a definition (haystack) matches a filename being searched for
(needle).
The filename is matched from right to left, so 'stdio.h', 'include/stdio.h',
'usr/include/stdio.h', and '/usr/include/stdio.h' would all match a definition in
/usr/include/stdio.h. If needle is None or empty, it matches any definition. If haystack is None
or empty, it only matches if needle is also None or empty.
Parameters
• haystack -- Path of file containing definition.
• needle -- Filename to match.
ProgramConstructors
The drgn command line interface automatically creates a Program named prog. However, drgn may also be
used as a library without the CLI, in which case a Program must be created manually.
drgn.program_from_core_dump(path:Union[Path,int])->Program
Create a Program from a core dump file. The type of program (e.g., userspace or kernel) is
determined automatically.
Parameterspath -- Core dump file path or open file descriptor.
drgn.program_from_kernel()->Program
Create a Program from the running operating system kernel. This requires root privileges.
drgn.program_from_pid(pid:int)->Program
Create a Program from a running program with the given PID. This requires appropriate permissions
(on Linux, ptrace(2)attachpermissions).Parameterspid -- Process ID of the program to debug.
DefaultProgram
Most functions that take a Program can be called without the prog argument. In that case, the defaultprogramargument is used, which is determined by the rules below.
NOTE:
In the drgn CLI, you probably don't need to care about these details. Simply omit prog:
# Equivalent in the CLI.
find_task(pid)
find_task(prog, pid)
find_task(prog["init_pid_ns"].address_of_(), pid)
1. If prog is given explicitly, either as a positional or keyword argument, then it is used.
2. Otherwise, if the first argument is an Object, then Object.prog_ is used.
3. Otherwise, the defaultprogram is used.
The default program is set automatically in the CLI. Library users can get and set it manually. The
default program is a per-thread setting. See ThreadSafety.
drgn.get_default_prog()->Program
Get the default program for the current thread.
RaisesNoDefaultProgramError -- if the default program is not set
drgn.set_default_prog(prog:Optional[Program],/)->None
Set the default program for the current thread.
Parametersprog -- Program to set as the default, or None to unset it.
classdrgn.NoDefaultProgramError
Bases: Exception
Error raised when trying to use the default program when it is not set.
For helpers, it is recommended to use the decorators from the drgn.helpers.common.prog module instead.
Platformsclassdrgn.Platform
A Platform represents the environment (i.e., architecture and ABI) that a program runs on.
Platform(arch:Architecture,flags:Optional[PlatformFlags]=None)
Create a Platform.
Parameters
• arch -- Platform.arch
• flags -- Platform.flags; if None, default flags for the architecture are used.
arch:Final[Architecture]
Instruction set architecture of this platform.
flags:Final[PlatformFlags]
Flags which apply to this platform.
registers:Final[Sequence[Register]]
Processor registers on this platform.
classdrgn.Architecture
Bases: enum.Enum
An Architecture represents an instruction set architecture.
X86_64 The x86-64 architecture, a.k.a. AMD64 or Intel 64.
I386 The 32-bit x86 architecture, a.k.a. i386 or IA-32.
AARCH64
The AArch64 architecture, a.k.a. ARM64.
ARM The 32-bit Arm architecture.
PPC64 The 64-bit PowerPC architecture.
RISCV64
The 64-bit RISC-V architecture.
RISCV32
The 32-bit RISC-V architecture.
S390X The s390x architecture, a.k.a. IBM Z or z/Architecture.
S390 The 32-bit s390 architecture, a.k.a. System/390.
UNKNOWN
An architecture which is not known to drgn. Certain features are not available when the
architecture is unknown, but most of drgn will still work.
classdrgn.PlatformFlags
Bases: enum.FlagPlatformFlags are flags describing a Platform.
IS_64_BIT
Platform is 64-bit.
IS_LITTLE_ENDIAN
Platform is little-endian.
classdrgn.Register
A Register represents information about a processor register.
names:Final[Sequence[str]]
Names of this register.
drgn.host_platform:Platform
The platform of the host which is running drgn.
Languagesclassdrgn.Language
A Language represents a programming language supported by drgn.
This class cannot be constructed; there are singletons for the supported languages.
name:Final[str]
Name of the programming language.
C:ClassVar[Language]
The C programming language.
CPP:ClassVar[Language]
The C++ programming language.
Objectsclassdrgn.Object
An Object represents a symbol or value in a program. An object may exist in the memory of the
program (a reference), it may be a constant or temporary computed value (a value), or it may be
absent entirely (an absent object).
All instances of this class have two attributes: prog_, the program that the object is from; and
type_, the type of the object. Reference objects also have an address_ and a bit_offset_.
Objects may also have a bit_field_size_.
repr() of an object returns a Python representation of the object:
>>> print(repr(prog['jiffies']))
Object(prog, 'volatile unsigned long', address=0xffffffffbf005000)
str() returns a "pretty" representation of the object in programming language syntax:
>>> print(prog['jiffies'])
(volatile unsigned long)4326237045
The output format of str() can be modified by using the format_() method instead:
>>> sysname = prog['init_uts_ns'].name.sysname
>>> print(sysname)
(char [65])"Linux"
>>> print(sysname.format_(type_name=False))
"Linux"
>>> print(sysname.format_(string=False))
(char [65]){ 76, 105, 110, 117, 120 }
NOTE:
The drgn CLI is set up so that objects are displayed in the "pretty" format instead of with
repr() (the latter is the default behavior of Python's interactive mode). Therefore, it's
usually not necessary to call print() in the drgn CLI.
Objects support the following operators:
• Arithmetic operators: +, -, *, /, %
• Bitwise operators: <<, >>, &, |, ^, ~
• Relational operators: ==, !=, <, >, <=, >=
• Subscripting: [] (Python does not have a unary * operator, so pointers are dereferenced with
ptr[0])
• Member access: . (Python does not have a -> operator, so . is also used to access members of
pointers to structures)
• The address-of operator: drgn.Object.address_of_() (this is a method because Python does not
have a & operator)
• Array length: len()
These operators all have the semantics of the program's programming language. For example, adding
two objects from a program written in C results in an object with a type and value according to
the rules of C:
>>> Object(prog, 'unsigned long', 2**64 - 1) + Object(prog, 'int', 1)
Object(prog, 'unsigned long', value=0)
If only one operand to a binary operator is an object, the other operand will be converted to an
object according to the language's rules for literals:
>>> Object(prog, 'char', 0) - 1
Object(prog, 'int', value=-1)
The standard int(), float(), and bool() functions convert an object to that Python type.
Conversion to bool uses the programming language's notion of "truthiness". Additionally, certain
Python functions will automatically coerce an object to the appropriate Python type (e.g., hex(),
round(), and listsubscripting).
Object attributes and methods are named with a trailing underscore to avoid conflicting with
structure, union, or class members. The attributes and methods always take precedence; use
member_() if there is a conflict.
Objects are usually obtained directly from a Program, but they can be constructed manually, as
well (for example, if you got a variable address from a log file).
Object(prog:Program,type:Union[str,Type],value:Union[IntegerLike,float,bool,Mapping[str,Any],Sequence[Any]],*,bit_field_size:Optional[IntegerLike]=None)
Create a value object given its type and value.
Parameters
• prog -- Program to create the object in.
• type -- Type of the object.
• value -- Value of the object. See value_().
• bit_field_size -- Size in bits of the object if it is a bit field. The default is
None, which means the object is not a bit field.
Object(prog:Program,*,value:Union[int,float,bool])
Create a value object from a "literal".
This is used to emulate a literal number in the source code of the program. The type is
deduced from value according to the language's rules for literals.
Parametersvalue -- Value of the literal.
Object(prog:Program,type:Union[str,Type],*,address:IntegerLike,bit_offset:IntegerLike=0,bit_field_size:Optional[IntegerLike]=None)
Create a reference object.
Parameters
• address -- Address of the object in the program.
• bit_offset -- Offset in bits from address to the beginning of the object.
Object(prog:Program,type:Union[str,Type],*,bit_field_size:Optional[IntegerLike]=None)
Create an absent object.
prog_:Final[Program]
Program that this object is from.
type_:Final[Type]
Type of this object.
absent_:Final[bool]
Whether this object is absent.
This is False for all values and references (even if the reference has an invalid address).
address_:Final[Optional[int]]
Address of this object if it is a reference, None if it is a value or absent.
bit_offset_:Final[Optional[int]]
Offset in bits from this object's address to the beginning of the object if it is a
reference, None otherwise. This can only be non-zero for scalars.
bit_field_size_:Final[Optional[int]]
Size in bits of this object if it is a bit field, None if it is not.
__getattr__(name:str)->Object
Implement self.name.
This corresponds to both the member access (.) and member access through pointer (->)
operators in C.
Note that if name is an attribute or method of the Object class, then that takes
precedence. Otherwise, this is equivalent to member_().
>>> print(prog['init_task'].pid)
(pid_t)0
Parametersname -- Attribute name.
__getitem__(idx:IntegerLike)->Object
Implement self[idx]. Get the array element at the given index.
>>> print(prog['init_task'].comm[1])
(char)119
[0] is also the equivalent of the pointer dereference (*) operator in C:
>>> ptr_to_ptr
*(void **)0xffff9b86801e2968 = 0xffff9b86801e2460
>>> print(ptr_to_ptr[0])
(void *)0xffff9b86801e2460
This is only valid for pointers and arrays.
NOTE:
Negative indices behave as they would in the object's language (as opposed to the Python
semantics of indexing from the end of the array).
Parametersidx -- The array index.
RaisesTypeError -- if this object is not a pointer or array
__len__()->int
Implement len(self). Get the number of elements in this object.
>>> len(prog['init_task'].comm)
16
This is only valid for arrays.
RaisesTypeError -- if this object is not an array with complete type
value_()->Any
Get the value of this object as a Python object.
For basic types (integer, floating-point, boolean), this returns an object of the directly
corresponding Python type (int, float, bool). For pointers, this returns the address value
of the pointer. For enums, this returns an int. For structures and unions, this returns a
dict of members. For arrays, this returns a list of values.
Raises
• FaultError -- if reading the object causes a bad memory access
• TypeError -- if this object has an unreadable type (e.g., void)
string_()->bytes
Read a null-terminated string pointed to by this object.
This is only valid for pointers and arrays. The element type is ignored; this operates
byte-by-byte.
For pointers and flexible arrays, this stops at the first null byte.
For complete arrays, this stops at the first null byte or at the end of the array.
Raises
• FaultError -- if reading the string causes a bad memory access
• TypeError -- if this object is not a pointer or array
member_(name:str)->Object
Get a member of this object.
This is valid for structures, unions, classes, and pointers to any of those. If the object
is a pointer, it is automatically dereferenced first.
Normally the dot operator (.) can be used to accomplish the same thing, but this method can
be used if there is a name conflict with an Object attribute or method.
Parametersname -- Name of the member.
Raises
• TypeError -- if this object is not a structure, union, class, or a pointer to one
of those
• LookupError -- if this object does not have a member with the given name
address_of_()->Object
Get a pointer to this object.
This corresponds to the address-of (&) operator in C. It is only possible for reference
objects, as value objects don't have an address in the program.
As opposed to address_, this returns an Object, not an int.
RaisesValueError -- if this object is a value
read_()->Object
Read this object (which may be a reference or a value) and return it as a value object.
This is useful if the object can change in the running program (but of course nothing stops
the program from modifying the object while it is being read).
As opposed to value_(), this returns an Object, not a standard Python type.
Raises
• FaultError -- if reading this object causes a bad memory access
• TypeError -- if this object has an unreadable type (e.g., void)
to_bytes_()->bytes
Return the binary representation of this object's value.
classmethodfrom_bytes_(prog:Program,type:Union[str,Type],bytes:collections.abc.Buffer,*,bit_offset:IntegerLike=0,bit_field_size:Optional[IntegerLike]=None)->Object
Return a value object from its binary representation.
>>> print(Object.from_bytes_(prog, "int", b""))
(int)16
Parameters
• prog -- Program to create the object in.
• type -- Type of the object.
• bytes -- Buffer containing value of the object.
• bit_offset -- Offset in bits from the beginning of bytes to the beginning of the
object.
• bit_field_size -- Size in bits of the object if it is a bit field. The default is
None, which means the object is not a bit field.
format_(*,columns:Optional[IntegerLike]=None,dereference:Optional[bool]=None,symbolize:Optional[bool]=None,string:Optional[bool]=None,char:Optional[bool]=None,type_name:Optional[bool]=None,member_type_names:Optional[bool]=None,element_type_names:Optional[bool]=None,members_same_line:Optional[bool]=None,elements_same_line:Optional[bool]=None,member_names:Optional[bool]=None,element_indices:Optional[bool]=None,implicit_members:Optional[bool]=None,implicit_elements:Optional[bool]=None)->str
Format this object in programming language syntax.
Various format options can be passed (as keyword arguments) to control the output. Options
that aren't passed or are passed as None fall back to a default. Specifically,
obj.format_() (i.e., with no passed options) is equivalent to str(obj).
>>> workqueues = prog['workqueues']
>>> print(workqueues)
(struct list_head){
.next = (struct list_head *)0xffff932ecfc0ae10,
.prev = (struct list_head *)0xffff932e3818fc10,
}
>>> print(workqueues.format_(type_name=False,
... member_type_names=False,
... member_names=False,
... members_same_line=True))
{ 0xffff932ecfc0ae10, 0xffff932e3818fc10 }
Parameters
• columns -- Number of columns to limit output to when the expression can be
reasonably wrapped. Defaults to no limit.
• dereference -- If this object is a pointer, include the dereferenced value. This
does not apply to structure, union, or class members, or array elements, as
dereferencing those could lead to an infinite loop. Defaults to True.
• symbolize -- Include a symbol name and offset for pointer objects. Defaults to
True.
• string -- Format the values of objects with string type as strings. For C, this
applies to pointers to and arrays of char, signedchar, and unsignedchar.
Defaults to True.
• char -- Format objects with character type as character literals. For C, this
applies to char, signedchar, and unsignedchar. Defaults to False.
• type_name -- Include the type name of this object. Defaults to True.
• member_type_names -- Include the type names of structure, union, and class
members. Defaults to True.
• element_type_names -- Include the type names of array elements. Defaults to
False.
• members_same_line -- Place multiple structure, union, and class members on the
same line if they fit within the specified number of columns. Defaults to False.
• elements_same_line -- Place multiple array elements on the same line if they fit
within the specified number of columns. Defaults to True.
• member_names -- Include the names of structure, union, and class members. Defaults
to True.
• element_indices -- Include the indices of array elements. Defaults to False.
• implicit_members -- Include structure, union, and class members which have an
implicit value (i.e., for C, zero-initialized). Defaults to True.
• implicit_elements -- Include array elements which have an implicit value (i.e.,
for C, zero-initialized). Defaults to False.
drgn.NULL(prog:Program,type:Union[str,Type])->Object
Get an object representing NULL casted to the given type.
This is equivalent to Object(prog,type,0).
Parameters
• prog -- The program.
• type -- The type.
drgn.cast(type:Union[str,Type],obj:Object)->Object
Get the value of an object explicitly casted to another type.
This uses the programming language's rules for explicit conversions, like the cast operator.
>>> cast("unsigned int", Object(prog, "float", 2.0))
(unsigned int)2
>>> cast("void *", Object(prog, "int", 0))
(void *)0x0
See also implicit_convert() for implicit conversions (which usually do stricter type checking) and
reinterpret() for reinterpreting the raw memory of an object.
Parameters
• type -- Type to cast to.
• obj -- Object to cast.
Returns
Casted object. This is always a value object.
RaisesTypeError -- if casting obj to type is not allowed
drgn.implicit_convert(type:Union[str,Type],obj:Object)->Object
Get the value of an object implicitly converted to another type.
This uses the programming language's rules for implicit conversions, like when assigning to a
variable or passing arguments to a function call.
>>> implicit_convert("unsigned int", Object(prog, "float", 2.0))
(unsigned int)2
>>> implicit_convert("void *", Object(prog, "int", 0))
Traceback (most recent call last):
...
TypeError: cannot convert 'int' to incompatible type 'void *'
See also cast() for explicit conversions and reinterpret() for reinterpreting the raw memory of an
object.
Parameters
• type -- Type to convert to.
• obj -- Object to convert.
Returns
Converted object. This is always a value object.
RaisesTypeError -- if converting obj to type is not allowed
drgn.reinterpret(type:Union[str,Type],obj:Object)->Object
Get the representation of an object reinterpreted as another type.
This reinterprets the raw memory of the object, so an object can be reinterpreted as any other
type.
>>> reinterpret("unsigned int", Object(prog, "float", 2.0))
(unsigned int)1073741824
NOTE:
You usually want cast() or implicit_convert() instead, which convert the value of an object
instead of its in-memory representation.
Parameters
• type -- Type to reinterpret as.
• obj -- Object to reinterpret.
Returns
Reinterpreted object. If obj is a reference object, then this is a reference object. If obj
is a value object, then this is a value object.
RaisesOutOfBoundsError -- if obj is a value object and type is larger than objdrgn.container_of(ptr:Object,type:Union[str,Type],member:str)->Object
Get the containing object of a pointer object.
This corresponds to the container_of() macro in C.
Parameters
• ptr -- Pointer to member in containing object.
• type -- Type of containing object.
• member -- Name of member in containing object. May include one or more member references
and zero or more array subscripts.
Returns
Pointer to containing object.
Raises
• TypeError -- if ptr is not a pointer or type is not a structure, union, or class type
• ValueError -- if the member is not byte-aligned (e.g., because it is a bit field)
• LookupError -- if type does not have a member with the given name
Symbolsclassdrgn.Symbol
A Symbol represents an entry in the symbol table of a program, i.e., an identifier along with its
corresponding address range in the program.
Symbol(name:str,address:int,size:int,binding:SymbolBinding,kind:SymbolKind)
Create a Symbol.
Parameters
• name -- Symbol.name
• address -- Symbol.address
• size -- Symbol.size
• binding -- Symbol.binding
• kind -- Symbol.kindname:Final[str]
Name of this symbol.
address:Final[int]
Start address of this symbol.
size:Final[int]
Size of this symbol in bytes.
binding:Final[SymbolBinding]
Linkage behavior and visibility of this symbol.
kind:Final[SymbolKind]
Kind of entity represented by this symbol.
classdrgn.SymbolBinding
Bases: enum.Enum
A SymbolBinding describes the linkage behavior and visibility of a symbol.
UNKNOWN
Unknown.
LOCAL Not visible outside of the object file containing its definition.
GLOBAL Globally visible.
WEAK Globally visible but may be overridden by a non-weak global symbol.
UNIQUE Globally visible even if dynamic shared object is loaded locally. See GCC's -fno-gnu-uniqueoption.
classdrgn.SymbolKind
Bases: enum.Enum
A SymbolKind describes the kind of entity that a symbol represents.
UNKNOWN
Unknown or not defined.
OBJECT Data object (e.g., variable or array).
FUNC Function or other executable code.
SECTION
Object file section.
FILE Source file.
COMMON Data object in common block.
TLS Thread-local storage entity.
IFUNCIndirectfunction.
classdrgn.SymbolIndex
A SymbolIndex contains a static set of symbols and allows efficient lookup by name and address.
With Program.register_symbol_finder(), you can add a callback to provide custom symbol finding
logic. However, in many cases, all that is necessary is to provide drgn with a list of symbols
that you know to be part of the program. This object allows you to do that. It efficiently
implements the Symbol Finder API given a static set of symbols. For example:
>>> prog = drgn.Program()
>>> symbol = drgn.Symbol("foo", 0x123, 1, drgn.SymbolBinding.GLOBAL, drgn.SymbolKind.OBJECT)
>>> finder = drgn.SymbolIndex([symbol])
>>> prog.register_symbol_finder("SymbolIndex", finder, enable_index=0)
>>> prog.symbols()
[Symbol(name='foo', address=0x123, size=0x1, binding=<SymbolBinding.GLOBAL: 2>, kind=<SymbolKind.OBJECT: 1>)]
>>> prog.symbol("bar")
Traceback (most recent call last):
File "<console>", line 1, in <module>
LookupError: not found
>>> prog.symbol("foo")
Symbol(name='foo', address=0x123, size=0x1, binding=<SymbolBinding.GLOBAL: 2>, kind=<SymbolKind.OBJECT: 1>)
>>> prog.symbol(0x100)
Traceback (most recent call last):
File "<console>", line 1, in <module>
LookupError: not found
>>> prog.symbol(0x123)
Symbol(name='foo', address=0x123, size=0x1, binding=<SymbolBinding.GLOBAL: 2>, kind=<SymbolKind.OBJECT: 1>)
SymbolIndex(symbols:Iterable[Symbol])
Create a SymbolIndex from a sequence of symbols
The returned symbol index satisfies the Symbol Finder API. It supports overlapping symbol
address ranges and duplicate symbol names. However, in the case of these sorts of
conflicts, it doesn't provide any guarantee on the order of the results, or which result is
returned when a single symbol is requested.
Parameterssymbols -- An iterable of symbols
Returns
A callable object suitable to provide to Program.register_symbol_finder().
__call__(prog:Program,name:Optional[str],address:Optional[int],one:bool)->List[Symbol]
Lookup symbol by name, address, or both.
Parameters
• prog -- (unused) the program looking up this symbol
• name -- if given, only return symbols with this name
• address -- if given, only return symbols spanning this address
• one -- if given, limit the result to a single symbol
Returns
a list of matching symbols (empty if none are found)
StackTraces
Stack traces are retrieved with stack_trace(), Program.stack_trace(), or Thread.stack_trace().
drgn.stack_trace(thread:Union[Object,IntegerLike])->StackTrace
Get the stack trace for the given thread using the defaultprogramargument.
See Program.stack_trace() for more details.
Parametersthread -- Thread ID, structpt_regs object, or structtask_struct* object.
classdrgn.StackTrace
A StackTrace is a sequence of StackFrame.
len(trace) is the number of stack frames in the trace. trace[0] is the innermost stack frame,
trace[1] is its caller, and trace[len(trace)-1] is the outermost frame. Negative indexing also
works: trace[-1] is the outermost frame and trace[-len(trace)] is the innermost frame. It is also
iterable:
for frame in trace:
if frame.name == 'io_schedule':
print('Thread is doing I/O')
str() returns a pretty-printed stack trace:
>>> prog.stack_trace(1)
#0 context_switch (kernel/sched/core.c:4339:2)
#1 __schedule (kernel/sched/core.c:5147:8)
#2 schedule (kernel/sched/core.c:5226:3)
#3 do_wait (kernel/exit.c:1534:4)
#4 kernel_wait4 (kernel/exit.c:1678:8)
#5 __do_sys_wait4 (kernel/exit.c:1706:13)
#6 do_syscall_64 (arch/x86/entry/common.c:47:14)
#7 entry_SYSCALL_64+0x7c/0x15b (arch/x86/entry/entry_64.S:112)
#8 0x4d49dd
The format is subject to change. The drgn CLI is set up so that stack traces are displayed with
str() by default.
prog:Final[Program]
Program that this stack trace is from.
classdrgn.StackFrame
A StackFrame represents a single frame in a thread's call stack.
str() returns a pretty-printed stack frame:
>>> prog.stack_trace(1)[0]
#0 at 0xffffffffb64ac287 (__schedule+0x227/0x606) in context_switch at kernel/sched/core.c:4339:2 (inlined)
This includes more information than when printing the full stack trace. The format is subject to
change. The drgn CLI is set up so that stack frames are displayed with str() by default.
The [] operator can look up function parameters, local variables, and global variables in the
scope of the stack frame:
>>> prog.stack_trace(1)[0]['prev'].pid
(pid_t)1
>>> prog.stack_trace(1)[0]['scheduler_running']
(int)1
name:Final[Optional[str]]
Name of the function at this frame, or None if it could not be determined.
The name cannot be determined if debugging information is not available for the function,
e.g., because it is implemented in assembly. It may be desirable to use the symbol name or
program counter as a fallback:
name = frame.name
if name is None:
try:
name = frame.symbol().name
except LookupError:
name = hex(frame.pc)
is_inline:Final[bool]
Whether this frame is for an inlined call.
An inline frame shares the same stack frame in memory as its caller. Therefore, it has the
same registers (including program counter and thus symbol).
interrupted:Final[bool]
Whether this stack frame was interrupted (for example, by a hardware interrupt, signal,
trap, etc.).
If this is True, then the register values in this frame are the values at the time that the
frame was interrupted.
This is False if the frame is for a function call, in which case the register values are
the values when control returns to this frame. In particular, the program counter is the
return address, which is typically the instruction after the call instruction.
pc:Final[int]
Program counter at this stack frame.
sp:Final[int]
Stack pointer at this stack frame.
__getitem__(name:str)->Object
Implement self[name]. Get the object (variable, function parameter, constant, or function)
with the given name in the scope of this frame.
If the object exists but has been optimized out, this returns an absentobject.
Parametersname -- Object name.
__contains__(name:str)->bool
Implement nameinself. Return whether an object with the given name exists in the scope of
this frame.
Parametersname -- Object name.
locals()->List[str]
Get a list of the names of all local objects (local variables, function parameters, local
constants, and nested functions) in the scope of this frame.
Not all names may have present values, but they can be used with the [] operator to check.
source()->Tuple[str,int,int]
Get the source code location of this frame.
Returns
Location as a (filename,line,column) triple.
RaisesLookupError -- if the source code location is not available
symbol()->Symbol
Get the function symbol at this stack frame.
This is equivalent to:
prog.symbol(frame.pc - (0 if frame.interrupted else 1))
register(reg:str)->int
Get the value of the given register at this stack frame.
Parametersreg -- Register name.
Raises
• ValueError -- if the register name is not recognized
• LookupError -- if the register value is not known
registers()->Dict[str,int]
Get the values of all available registers at this stack frame as a dictionary with the
register names as keys.
Typesclassdrgn.Type
A Type object describes a type in a program. Each kind of type (e.g., integer, structure) has
different attributes (e.g., name, size). Types can also have qualifiers (e.g., constant, atomic).
Accessing an attribute which does not apply to a type raises an AttributeError.
repr() of a Type returns a Python representation of the type:
>>> print(repr(prog.type('sector_t')))
prog.typedef_type(name='sector_t', type=prog.int_type(name='unsigned long', size=8, is_signed=False))
str() returns a representation of the type in programming language syntax:
>>> print(prog.type('sector_t'))
typedef unsigned long sector_t
The drgn CLI is set up so that types are displayed with str() instead of repr() by default.
This class cannot be constructed directly. Instead, use one of the TypeConstructors.
prog:Final[Program]
Program that this type is from.
kind:Final[TypeKind]
Kind of this type.
primitive:Final[Optional[PrimitiveType]]
If this is a primitive type (e.g., int or double), the kind of primitive type. Otherwise,
None.
qualifiers:Final[Qualifiers]
Bitmask of this type's qualifier.
language:Final[Language]
Programming language of this type.
name:Final[str]
Name of this type. This is present for integer, boolean, floating-point, and typedef types.
tag:Final[Optional[str]]
Tag of this type, or None if this is an anonymous type. This is present for structure,
union, class, and enumerated types.
size:Final[Optional[int]]
Size of this type in bytes, or None if this is an incomplete type. This is present for
integer, boolean, floating-point, structure, union, class, and pointer types.
length:Final[Optional[int]]
Number of elements in this type, or None if this is an incomplete type. This is only
present for array types.
is_signed:Final[bool]
Whether this type is signed. This is only present for integer types.
byteorder:Final[str]
Byte order of this type: 'little' if it is little-endian, or 'big' if it is big-endian.
This is present for integer, boolean, floating-point, and pointer types.
type:Final[Type]
Type underlying this type, defined as follows:
• For typedef types, the aliased type.
• For enumerated types, the compatible integer type, which is None if this is an incomplete
type.
• For pointer types, the referenced type.
• For array types, the element type.
• For function types, the return type.
For other types, this attribute is not present.
members:Final[Optional[Sequence[TypeMember]]]
List of members of this type, or None if this is an incomplete type. This is present for
structure, union, and class types.
enumerators:Final[Optional[Sequence[TypeEnumerator]]]
List of enumeration constants of this type, or None if this is an incomplete type. This is
only present for enumerated types.
parameters:Final[Sequence[TypeParameter]]
List of parameters of this type. This is only present for function types.
is_variadic:Final[bool]
Whether this type takes a variable number of arguments. This is only present for function
types.
template_parameters:Final[Sequence[TypeTemplateParameter]]
List of template parameters of this type. This is present for structure, union, class, and
function types.
type_name()->str
Get a descriptive full name of this type.
is_complete()->bool
Get whether this type is complete (i.e., the type definition is known). This is always
False for void types. It may be False for structure, union, class, enumerated, and array
types, as well as typedef types where the underlying type is one of those. Otherwise, it is
always True.
qualified(qualifiers:Qualifiers)->Type
Get a copy of this type with different qualifiers.
Note that the original qualifiers are replaced, not added to.
Parametersqualifiers -- New type qualifiers.
unqualified()->Type
Get a copy of this type with no qualifiers.
member(name:str)->TypeMember
Look up a member in this type by name.
If this type has any unnamed members, this also matches members of those unnamed members,
recursively. If the member is found in an unnamed member, TypeMember.bit_offset and
TypeMember.offset are adjusted accordingly.
Parametersname -- Name of the member.
Raises
• TypeError -- if this type is not a structure, union, or class type
• LookupError -- if this type does not have a member with the given name
has_member(name:str)->bool
Return whether this type has a member with the given name.
If this type has any unnamed members, this also matches members of those unnamed members,
recursively.
Parametersname -- Name of the member.
RaisesTypeError -- if this type is not a structure, union, or class type
classdrgn.TypeMember
A TypeMember represents a member of a structure, union, or class type.
TypeMember(object_or_type:Union[Object,Type,Callable[[],Union[Object,Type]]],name:Optional[str]=None,bit_offset:int=0)
Create a TypeMember.
Parameters
• object_or_type --
One of:
1. TypeMember.object as an Object.
2. TypeMember.type as a Type. In this case, object is set to an absent object with
that type.
3. A callable that takes no arguments and returns one of the above. It is called
when object or type is first accessed, and the result is cached.
• name -- TypeMember.name
• bit_offset -- TypeMember.bit_offsetobject:Final[Object]
Member as an Object.
This is the default initializer for the member, or an absent object if the member has no
default initializer. (However, the DWARF specification as of version 5 does not actually
support default member initializers, so this is usually absent.)
type:Final[Type]
Member type.
This is a shortcut for TypeMember.object.type.
name:Final[Optional[str]]
Member name, or None if the member is unnamed.
bit_offset:Final[int]
Offset of the member from the beginning of the type in bits.
offset:Final[int]
Offset of the member from the beginning of the type in bytes. If the offset is not
byte-aligned, accessing this attribute raises ValueError.
bit_field_size:Final[Optional[int]]
Size in bits of this member if it is a bit field, None if it is not.
This is a shortcut for TypeMember.object.bit_field_size_.
classdrgn.TypeEnumerator
A TypeEnumerator represents a constant in an enumerated type.
Its name and value may be accessed as attributes or unpacked:
>>> prog.type('enum pid_type').enumerators[0].name
'PIDTYPE_PID'
>>> name, value = prog.type('enum pid_type').enumerators[0]
>>> value
0
TypeEnumerator(name:str,value:int)
Create a TypeEnumerator.
Parameters
• name -- TypeEnumerator.name
• value -- TypeEnumerator.valuename:Final[str]
Enumerator name.
value:Final[int]
Enumerator value.
classdrgn.TypeParameter
A TypeParameter represents a parameter of a function type.
TypeParameter(default_argument_or_type:Union[Object,Type,Callable[[],Union[Object,Type]]],name:Optional[str]=None)
Create a TypeParameter.
Parameters
• default_argument_or_type --
One of:
1. TypeParameter.default_argument as an Object.
2. TypeParameter.type as a Type. In this case, default_argument is set to an
absent object with that type.
3. A callable that takes no arguments and returns one of the above. It is called
when default_argument or type is first accessed, and the result is cached.
• name -- TypeParameter.namedefault_argument:Final[Object]
Default argument for parameter.
If the parameter does not have a default argument, then this is an absent object.
NOTE:
Neither GCC nor Clang emits debugging information for default arguments (as of GCC 10
and Clang 11), and drgn does not yet parse it, so this is usually absent.
type:Final[Type]
Parameter type.
This is the same as TypeParameter.default_argument.type_.
name:Final[Optional[str]]
Parameter name, or None if the parameter is unnamed.
classdrgn.TypeTemplateParameter
A TypeTemplateParameter represents a template parameter of a structure, union, class, or function
type.
TypeTemplateParameter(argument:Union[Type,Object,Callable[[],Union[Type,Object]]],name:Optional[str]=None,is_default:bool=False)
Create a TypeTemplateParameter.
Parameters
• argument --
One of:
1. TypeTemplateParameter.argument as a Type if the parameter is a type template
parameter.
2. TypeTemplateParameter.argument as a non-absent Object if the parameter is a
non-type template parameter.
3. A callable that takes no arguments and returns one of the above. It is called
when argument is first accessed, and the result is cached.
• name -- TypeTemplateParameter.name
• is_default -- TypeTemplateParameter.is_defaultargument:Final[Union[Type,Object]]
Template argument.
If this is a type template parameter, then this is a Type. If this is a non-type template
parameter, then this is an Object.
name:Final[Optional[str]]
Template parameter name, or None if the parameter is unnamed.
is_default:Final[bool]
Whether argument is the default for the template parameter.
NOTE:
There are two ways to interpret this:
1. The argument was omitted entirely and thus defaulted to the default argument.
2. The (specified or defaulted) argument is the same as the default argument.
Compilers are inconsistent about which interpretation they use.
GCC added this information in version 4.9. Clang added it in version 11 (and only when
emitting DWARF version 5). If the program was compiled by an older version, this is
always false.
classdrgn.TypeKind
Bases: enum.Enum
A TypeKind represents a kind of type.
VOID Void type.
INT Integer type.
BOOL Boolean type.
FLOAT Floating-point type.
STRUCT Structure type.
UNION Union type.
CLASS Class type.
ENUM Enumerated type.
TYPEDEF
Type definition (a.k.a. alias) type.
POINTER
Pointer type.
ARRAY Array type.
FUNCTION
Function type.
classdrgn.TypeKindSet
Bases: collections.abc.Set[TypeKind]
Immutable set of TypeKinds.
>>> kinds = TypeKindSet({TypeKind.STRUCT, TypeKind.CLASS})
>>> TypeKind.STRUCT in kinds
True
>>> TypeKind.INT in kinds
False
>>> for kind in kinds:
... print(kind)
...
TypeKind.STRUCT
TypeKind.CLASS
classdrgn.PrimitiveType
Bases: enum.Enum
A PrimitiveType represents a primitive type known to drgn.
C_VOIDC_CHARC_SIGNED_CHARC_UNSIGNED_CHARC_SHORTC_UNSIGNED_SHORTC_INTC_UNSIGNED_INTC_LONGC_UNSIGNED_LONGC_LONG_LONGC_UNSIGNED_LONG_LONGC_BOOLC_FLOATC_DOUBLEC_LONG_DOUBLEC_SIZE_TC_PTRDIFF_Tclassdrgn.Qualifiers
Bases: enum.FlagQualifiers are modifiers on types.
NONE No qualifiers.
CONST Constant type.
VOLATILE
Volatile type.
RESTRICTRestrict type.
ATOMIC Atomic type.
drgn.alignof(type:Type,/)->int
Get the alignment requirement (in bytes) of a Type.
This corresponds to _Alignof() in C.
RaisesTypeError -- if type is a function type or an incomplete type
drgn.offsetof(type:Type,member:str)->int
Get the offset (in bytes) of a member in a Type.
This corresponds to offsetof() in C.
Parameters
• type -- Structure, union, or class type.
• member -- Name of member. May include one or more member references and zero or more
array subscripts.
Raises
• TypeError -- if type is not a structure, union, or class type
• ValueError -- if the member is not byte-aligned (e.g., because it is a bit field)
• LookupError -- if type does not have a member with the given name
TypeConstructors
Custom drgn types can be created with the following factory functions. These can be used just like types
obtained from Program.type().
Program.void_type(*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new void type. It has kind TypeKind.VOID.
Parameters
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.int_type(name:str,size:IntegerLike,is_signed:bool,byteorder:Optional[str]=None,*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new integer type. It has kind TypeKind.INT.
Parameters
• name -- Type.name
• size -- Type.size
• is_signed -- Type.is_signed
• byteorder -- Type.byteorder, or None to use the program's default byte order.
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.bool_type(name:str,size:IntegerLike,byteorder:Optional[str]=None,*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new boolean type. It has kind TypeKind.BOOL.
Parameters
• name -- Type.name
• size -- Type.size
• byteorder -- Type.byteorder, or None to use the program's default byte order.
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.float_type(name:str,size:IntegerLike,byteorder:Optional[str]=None,*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new floating-point type. It has kind TypeKind.FLOAT.
Parameters
• name -- Type.name
• size -- Type.size
• byteorder -- Type.byteorder, or None to use the program's default byte order.
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.struct_type(tag:Optional[str],size:IntegerLike,members:Sequence[TypeMember],*,template_parameters:Sequence[TypeTemplateParameter]=(),qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new structure type. It has kind TypeKind.STRUCT.
Parameters
• tag -- Type.tag
• size -- Type.size
• members -- Type.members
• template_parameters -- Type.template_parameters
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.struct_type(tag:Optional[str],size:None=None,members:None=None,*,template_parameters:Sequence[TypeTemplateParameter]=(),qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[‐Language]=None)->Type
Create a new incomplete structure type.
Program.union_type(tag:Optional[str],size:IntegerLike,members:Sequence[TypeMember],*,template_parameters:Sequence[TypeTemplateParameter]=(),qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new union type. It has kind TypeKind.UNION. Otherwise, this is the same as as
struct_type().
Program.union_type(tag:Optional[str],size:None=None,members:None=None,*,template_parameters:Sequence[TypeTemplateParameter]=(),qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[‐Language]=None)->Type
Create a new incomplete union type.
Program.class_type(tag:Optional[str],size:IntegerLike,members:Sequence[TypeMember],*,template_parameters:Sequence[TypeTemplateParameter]=(),qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new class type. It has kind TypeKind.CLASS. Otherwise, this is the same as as
struct_type().
Program.class_type(tag:Optional[str],size:None=None,members:None=None,*,template_parameters:Sequence[TypeTemplateParameter]=(),qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[‐Language]=None)->Type
Create a new incomplete class type.
Program.enum_type(tag:Optional[str],type:Type,enumerators:Sequence[TypeEnumerator],*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new enumerated type. It has kind TypeKind.ENUM.
Parameters
• tag -- Type.tag
• type -- The compatible integer type (Type.type)
• enumerators -- Type.enumerators
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.enum_type(tag:Optional[str],type:None=None,enumerators:None=None,*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new incomplete enumerated type.
Program.typedef_type(name:str,type:Type,*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new typedef type. It has kind TypeKind.TYPEDEF.
Parameters
• name -- Type.name
• type -- The aliased type (Type.type)
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.pointer_type(type:Type,size:Optional[int]=None,byteorder:Optional[str]=None,*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new pointer type. It has kind TypeKind.POINTER,
Parameters
• type -- The referenced type (Type.type)
• size -- Type.size, or None to use the program's default pointer size.
• byteorder -- Type.byteorder, or None to use the program's default byte order.
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.array_type(type:Type,length:Optional[int]=None,*,qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new array type. It has kind TypeKind.ARRAY.
Parameters
• type -- The element type (Type.type)
• length -- Type.length
• qualifiers -- Type.qualifiers
• lang -- Type.languageProgram.function_type(type:Type,parameters:Sequence[TypeParameter],is_variadic:bool=False,*,template_parameters:Sequence[TypeTemplateParameter]=(),qualifiers:Qualifiers=Qualifiers.NONE,language:Optional[Language]=None)->Type
Create a new function type. It has kind TypeKind.FUNCTION.
Parameters
• type -- The return type (Type.type)
• parameters -- Type.parameters
• is_variadic -- Type.is_variadic
• template_parameters -- Type.template_parameters
• qualifiers -- Type.qualifiers
• lang -- Type.languageMiscellaneousdrgn.sizeof(type_or_obj:Union[Type,Object],/)->int
Get the size of a Type or Object in bytes.
Parameterstype_or_obj -- Entity to get the size of.
RaisesTypeError -- if the type does not have a size (e.g., because it is incomplete or void)
drgn.execscript(path:str,*args:str)->None
Execute a script.
The script is executed in the same context as the caller: currently defined globals are available
to the script, and globals defined by the script are added back to the calling context.
This is most useful for executing scripts from interactive mode. For example, you could have a
script named exe.py:
"""Get all tasks executing a given file."""
import sys
from drgn.helpers.linux.fs import d_path
from drgn.helpers.linux.pid import find_task
def task_exe_path(task):
if task.mm:
return d_path(task.mm.exe_file.f_path).decode()
else:
return None
tasks = [
task for task in for_each_task()
if task_exe_path(task) == sys.argv[1]
]
Then, you could execute it and use the defined variables and functions:
>>> execscript('exe.py', '/usr/bin/bash')
>>> tasks[0].pid
(pid_t)358442
>>> task_exe_path(find_task(357954))
'/usr/bin/vim'
Parameters
• path -- File path of the script.
• args -- Zero or more additional arguments to pass to the script. This is a variable
argument list.
classdrgn.IntegerLike
Bases: Protocol
An int or integer-like object.
Parameters annotated with this type expect an integer which may be given as a Python int or an
Object with integer type.
drgn.Path:TypeAlias
Filesystem path.
Parameters annotated with this type accept a filesystem path as str, bytes, or os.PathLike.
Exceptionsclassdrgn.FaultError
Bases: Exception
This error is raised when a bad memory access is attempted (i.e., when accessing a memory address
which is not valid in a program).
FaultError(message:str,address:int)Parameters
• message -- FaultError.message
• address -- FaultError.addressmessage:str
Error message.
address:int
Address that couldn't be accessed.
classdrgn.MissingDebugInfoError
Bases: Exception
This error is raised when one or more files in a program do not have debug information.
classdrgn.ObjectAbsentError
Bases: Exception
This error is raised when attempting to use an absent object.
classdrgn.OutOfBoundsError
Bases: Exception
This error is raised when attempting to access beyond the bounds of a value object.
CLI
Functions for embedding the drgn CLI.
drgn.cli.version_header()->str
Return the version header printed at the beginning of a drgn session.
The run_interactive() function does not include this banner at the beginning of an interactive
session. Use this function to retrieve one line of text to add to the beginning of the drgn
banner, or print it before calling run_interactive().
drgn.cli.run_interactive(prog:drgn.Program,banner_func:Optional[Callable[[str],str]]=None,globals_func:Optional[Callable[[Dict[str,Any]],Dict[str,Any]]]=None,quiet:bool=False)->None
Run drgn's InteractiveMode until the user exits.
This function allows your application to embed the same REPL that drgn provides when it is run on
the command line in interactive mode.
Parameters
• prog -- Pre-configured program to run against. Available as a global named prog in the
CLI.
• banner_func -- Optional function to modify the printed banner. Called with the default
banner, and must return a string to use as the new banner. The default banner does not
include the drgn version, which can be retrieved via version_header().
• globals_func -- Optional function to modify globals provided to the session. Called with
a dictionary of default globals, and must return a dictionary to use instead.
• quiet -- Ignored. Will be removed in the future.
NOTE:
This function uses readline and modifies some settings. Unfortunately, it is not possible for
it to restore all settings. In particular, it clears the readline history and resets the TAB
keybinding to the default.
Applications using readline should save their history and clear any custom settings before
calling this function. After calling this function, applications should restore their history
and settings before using readline.
Logging
drgn logs using the standard logging module to a logger named "drgn".
ThreadSafety
Only one thread at a time should access the same Program (including Object, Type, StackTrace, etc. from
that program). It is safe to use different Programs from concurrent threads.
Helpers
The drgn.helpers package contains subpackages which provide helpers for working with particular types of
programs. Currently, there are common helpers and helpers for the Linux kernel. In the future, there may
be helpers for, e.g., glibc and libstdc++.
classdrgn.helpers.ValidationError
Bases: Exception
Error raised by a validator when an inconsistent or invalid state is detected.
Common
The drgn.helpers.common package provides helpers that can be used with any program. The helpers are
available from the individual modules in which they are defined and from this top-level package. E.g.,
the following are both valid:
>>> from drgn.helpers.common.memory import identify_address
>>> from drgn.helpers.common import identify_address
Some of these helpers may have additional program-specific behavior but are otherwise generic.
Formatting
The drgn.helpers.common.format module provides generic helpers for formatting different things as text.
drgn.helpers.common.format.escape_ascii_character(c:int,escape_single_quote:bool=False,escape_double_quote:bool=False,escape_backslash:bool=False)->str
Format an ASCII byte value as a character, possibly escaping it. Non-printable characters are
always escaped. Non-printable characters other than \0, \a, \b, \t, \n, \v, \f, and \r are escaped
in hexadecimal format (e.g., \x7f). By default, printable characters are never escaped.
Parameters
• c -- Character to escape.
• escape_single_quote -- Whether to escape single quotes to \'.
• escape_double_quote -- Whether to escape double quotes to \".
• escape_backslash -- Whether to escape backslashes to \\.
drgn.helpers.common.format.escape_ascii_string(buffer:Iterable[int],escape_single_quote:bool=False,escape_double_quote:bool=False,escape_backslash:bool=False)->str
Escape an iterable of ASCII byte values (e.g., bytes or bytearray). See escape_ascii_character().
Parametersbuffer -- Byte array to escape.
drgn.helpers.common.format.decode_flags(value:drgn.IntegerLike,flags:Iterable[Tuple[str,int]],bit_numbers:bool=True)->str
Get a human-readable representation of a bitmask of flags.
By default, flags are specified by their bit number:
>>> decode_flags(2, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'ITALIC'
They can also be specified by their value:
>>> decode_flags(2, [("BOLD", 1), ("ITALIC", 2), ("UNDERLINE", 4)],
... bit_numbers=False)
'ITALIC'
Multiple flags are combined with "|":
>>> decode_flags(5, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'BOLD|UNDERLINE'
If there are multiple names for the same bit, they are all included:
>>> decode_flags(2, [("SMALL", 0), ("BIG", 1), ("LARGE", 1)])
'BIG|LARGE'
If there are any unknown bits, their raw value is included:
>>> decode_flags(27, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'BOLD|ITALIC|0x18'
Zero is returned verbatim:
>>> decode_flags(0, [("BOLD", 0), ("ITALIC", 1), ("UNDERLINE", 2)])
'0'
Parameters
• value -- Bitmask to decode.
• flags -- List of flag names and their bit numbers or values.
• bit_numbers -- Whether flags specifies the bit numbers (where 0 is the least significant
bit) or values of the flags.
drgn.helpers.common.format.decode_enum_type_flags(value:drgn.IntegerLike,type:drgn.Type,bit_numbers:bool=True)->str
Get a human-readable representation of a bitmask of flags where the flags are specified by an
enumerated drgn.Type.
This supports enums where the values are bit numbers:
>>> print(bits_enum)
enum style_bits {
BOLD = 0,
ITALIC = 1,
UNDERLINE = 2,
}
>>> decode_enum_type_flags(5, bits_enum)
'BOLD|UNDERLINE'
Or the values of the flags:
>>> print(flags_enum)
enum style_flags {
BOLD = 1,
ITALIC = 2,
UNDERLINE = 4,
}
>>> decode_enum_type_flags(5, flags_enum, bit_numbers=False)
'BOLD|UNDERLINE'
See decode_flags().
Parameters
• value -- Bitmask to decode.
• type -- Enumerated type with bit numbers for enumerators.
• bit_numbers -- Whether the enumerator values specify the bit numbers or values of the
flags.
drgn.helpers.common.format.number_in_binary_units(n:SupportsFloat,precision:int=1)->str
Format a number in binary units (i.e., "K" is 1024, "M" is 10242, etc.).
>>> number_in_binary_units(1280)
'1.2K'
A precision can be specified:
>>> number_in_binary_units(1280, precision=2)
'1.25K'
Exact numbers are printed without a fractional part:
>>> number_in_binary_units(1024 * 1024)
'1M'
Numbers less than 1024 are not scaled:
>>> number_in_binary_units(10)
'10'
Parameters
• n -- Number to format.
• precision -- Number of digits to include in fractional part.
Memory
The drgn.helpers.common.memory module provides helpers for working with memory and addresses.
drgn.helpers.common.memory.identify_address(prog:drgn.Program,addr:drgn.IntegerLike,*,cache:Optional[Dict[Any,Any]]=None)->Optional[str]
Try to identify what an address refers to.
For all programs, this will identify addresses as follows:
• Object symbols (e.g., addresses in global variables): objectsymbol:{symbol_name}+{hex_offset}
(where hex_offset is the offset from the beginning of the symbol in hexadecimal).
• Function symbols (i.e., addresses in functions): functionsymbol:{symbol_name}+{hex_offset}.
• Other symbols: symbol:{symbol_name}+{hex_offset}.
Additionally, for the Linux kernel, this will identify:
• Allocated slab objects: slabobject:{slab_cache_name}+{hex_offset} (where hex_offset is the
offset from the beginning of the object in hexadecimal).
• Free slab objects: freeslabobject:{slab_cache_name}+{hex_offset}.
• Vmap addresses (e.g., vmalloc, ioremap): vmap:{hex_start_address}-{hex_end_address}. If the
function that allocated the vmap is known, this also includes caller{function_name}+{hex_offset}.
• Vmap kernel stacks: vmapstack:{pid}({comm})+{hex_offset} (where pid and comm identify the
task and hex_offset is the offset from the beginning of the stack in hexadecimal).
This may recognize other types of addresses in the future.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*
• cache -- Opaque cache used to amortize expensive lookups. If you're going to call this
function many times in a short period, create an empty dictionary and pass the same
dictionary as cache to each call. Don't reuse it indefinitely or you may get stale
results.
Returns
Identity as string, or None if the address is unrecognized.
drgn.helpers.common.memory.print_annotated_memory(prog:drgn.Program,address:drgn.IntegerLike,size:drgn.IntegerLike,physical:bool=False)->None
Print the contents of a range of memory, annotating values that can be identified.
Currently, this will identify any addresses in the memory range with identify_address().
See print_annotated_stack() for a similar function that annotates stack traces.
>>> print_annotated_memory(0xffffffff963eb200, 56)
ADDRESS VALUE
ffffffff963eb200: 00000000000000b8
ffffffff963eb208: 000000000000a828
ffffffff963eb210: 0000000000000000
ffffffff963eb218: ffff8881042948e0 [slab object: mnt_cache+0x20]
ffffffff963eb220: ffff88810074a540 [slab object: dentry+0x0]
ffffffff963eb228: ffff8881042948e0 [slab object: mnt_cache+0x20]
ffffffff963eb230: ffff88810074a540 [slab object: dentry+0x0]
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• address -- Starting address.
• size -- Number of bytes to read.
• physical -- Whether address is a physical memory address. If False, then it is a virtual
memory address.
ProgramDecorators
The drgn.helpers.common.prog module provides decorators to transparently use the defaultprogramargument.
drgn.helpers.common.prog.takes_program_or_default(f:TakesProgram[P,R])->TakesProgramOrDefault[P,R]
Wrap a function taking a Program so that it uses the defaultprogramargument if omitted.
@takes_program_or_default
def my_helper(prog: Program, n: IntegerLike) -> Foo:
...
my_helper(1)
# is equivalent to
my_helper(get_default_prog(), 1)
obj = Object(...)
my_helper(obj)
# is equivalent to
my_helper(obj.prog_, obj)
drgn.helpers.common.prog.takes_object_or_program_or_default(f:Callable[Concatenate[drgn.Program,Optional[drgn.Object],P],R])->TakesObjectOrProgramOrDefault[P,R]
Wrap a function taking a Program and an optional Object so that it accepts a Programor an Objectorneither, in which case the defaultprogramargument is used.
@takes_object_or_program_or_default
def my_helper(prog: Program, obj: Optional[Object], n: IntegerLike) -> Foo:
...
my_helper(prog, 1)
# is equivalent to
my_helper.__wrapped__(prog, None, 1)
obj = Object(...)
my_helper(obj, 1)
# is equivalent to
my_helper.__wrapped__(obj.prog_, obj, 1)
my_helper(1)
# is equivalent to
my_helper.__wrapped__(get_default_prog(), None, 1)
one_obj = Object(..., 1)
my_helper(one_obj)
# is equivalent to
my_helper.__wrapped__(one_obj.prog_, None, one_obj)
WARNING:
This cannot be used with positional parameters with a default value, as that would create
ambiguity. Keyword-only parameters with a default value are OK.
# NOT ALLOWED
@takes_object_or_program_or_default
def my_helper(prog: Program, obj: Optional[Object], foo: str = ""): ...
# OK
@takes_object_or_program_or_default
def my_helper(prog: Program, obj: Optional[Object], *, foo: str = ""): ...
NOTE:
The object parameter can be passed as a keyword, but because of limitationsofthePythontypesystem, type checkers do not recognize this.
Stack
The drgn.helpers.common.stack module provides helpers for working with stack traces.
drgn.helpers.common.stack.print_annotated_stack(trace:drgn.StackTrace)->None
Print the contents of stack memory in a stack trace, annotating values that can be identified.
Currently, this will identify any addresses on the stack with identify_address().
See print_annotated_memory() for a similar function that annotates arbitrary memory ranges.
>>> print_annotated_stack(stack_trace(1))
STACK POINTER VALUE
[stack frame #0 at 0xffffffff8dc93c41 (__schedule+0x429/0x488) in context_switch at ./kernel/sched/core.c:5209:2 (inlined)]
[stack frame #1 at 0xffffffff8dc93c41 (__schedule+0x429/0x488) in __schedule at ./kernel/sched/core.c:6521:8]
ffffa903c0013d28: ffffffff8d8497bf [function symbol: __flush_tlb_one_user+0x5]
ffffa903c0013d30: 000000008d849eb5
ffffa903c0013d38: 0000000000000001
ffffa903c0013d40: 0000000000000004
ffffa903c0013d48: efdea37bb7cb1f00
ffffa903c0013d50: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d58: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d60: ffffa903c0013e10
ffffa903c0013d68: ffff926641177ff0 [slab object: mm_struct+0x70]
ffffa903c0013d70: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d78: ffff926641178000 [slab object: task_struct+0x0]
ffffa903c0013d80: ffffffff8dc93d29 [function symbol: schedule+0x89]
...
Parameterstrace -- Stack trace to print.
Types
The drgn.helpers.common.type module provides generic helpers for working with types in ways that aren't
provided by the core drgn library.
drgn.helpers.common.type.enum_type_to_class(type:drgn.Type,name:str,exclude:Container[str]=(),prefix:str='')->Type[enum.IntEnum]
Get an enum.IntEnum class from an enumerated drgn.Type.
Parameters
• type -- Enumerated type to convert.
• name -- Name of the IntEnum type to create.
• exclude -- Container (e.g., list or set) of enumerator names to exclude from the created
IntEnum.
• prefix -- Prefix to strip from the beginning of enumerator names.
drgn.helpers.common.type.member_at_offset(type:drgn.Type,offset:drgn.IntegerLike)->str
Return the name of the member at an offset in a type.
This is effectively the opposite of offsetof().
>>> prog.type('struct list_head')
struct list_head {
struct list_head *next;
struct list_head *prev;
}
>>> member_at_offset(prog.type('struct list_head'), 0)
'next'
>>> member_at_offset(prog.type('struct list_head'), 8)
'prev'
This includes nested structures and array elements:
>>> prog.type('struct sigpending')
struct sigpending {
struct list_head list;
sigset_t signal;
}
>>> prog.type('sigset_t')
typedef struct {
unsigned long sig[1];
} sigset_t
>>> member_at_offset(prog.type('struct sigpending'), 0)
'list.next'
>>> member_at_offset(prog.type('struct sigpending'), 8)
'list.prev'
>>> member_at_offset(prog.type('struct sigpending'), 16)
'signal.sig[0]'
This also includes all possible matches for a union:
>>> prog.type('union mc_target')
union mc_target {
struct folio *folio;
swp_entry_t ent;
}
>>> prog.type('swp_entry_t')
typedef struct {
unsigned long val;
} swp_entry_t
>>> member_at_offset(prog.type('union mc_target'), 0)
'folio or ent.val'
Offsets in the middle of a member are represented:
>>> member_at_offset(prog.type('struct list_head'), 4)
'next+0x4'
Offsets in padding or past the end of the type are also represented:
>>> prog.type('struct autogroup')
struct autogroup {
struct kref kref;
struct task_group *tg;
struct rw_semaphore lock;
unsigned long id;
int nice;
}
>>> member_at_offset(prog.type('struct autogroup'), 4)
'<padding between kref and tg>'
>>> member_at_offset(prog.type('struct autogroup'), 70)
'<padding at end>'
>>> member_at_offset(prog.type('struct autogroup'), 72)
'<end>'
>>> member_at_offset(prog.type('struct autogroup'), 80)
'<past end>'
Parameters
• type -- Type to check.
• offset -- Offset in bytes.
RaisesTypeError -- if type is not a structure, union, class, or array type (or a typedef of one
of those)
Experimental
The drgn.helpers.experimental package contains experimental helpers with no stability guarantees. They
may change, move to another package, or be removed. They are not automatically imported by the CLI.
Kmodify
The drgn.helpers.experimental.kmodify module provides experimental helpers for modifying the state of the
running kernel. This works by loading a temporary kernel module, so the kernel must support loadable
kernel modules (CONFIG_MODULES=y) and allow loading unsigned modules (CONFIG_MODULE_SIG_FORCE=n). It is
currently only implemented for x86-64.
WARNING:
These helpers are powerful but extremely dangerous. Use them with care.
drgn.helpers.experimental.kmodify.write_memory(prog:drgn.Program,address:drgn.IntegerLike,value:bytes)->None
Write a byte string to kernel memory.
>>> os.uname().sysname
'Linux'
>>> write_memory(prog["init_uts_ns"].name.sysname.address_, b"Lol\0")
>>> os.uname().sysname
'Lol'
WARNING:
This attempts to detect writes to bad addresses and raise a FaultError, but this is best-effort
and may still crash the kernel. Writing bad data can of course also cause a crash when the data
is used. Additionally, this is not atomic, so the data may be accessed while it is partially
written.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• address -- Address to write to.
• value -- Byte string to write.
RaisesFaultError -- if the address cannot be written to
drgn.helpers.experimental.kmodify.write_object(object:drgn.Object,value:Any,*,dereference:Optional[bool]=None)->None
Write to an object in kernel memory.
>>> os.system("uptime -p")
up 12 minutes
>>> write_object(prog["init_time_ns"].offsets.boottime.tv_sec, 1000000000)
>>> os.system("uptime -p")
up 3 decades, 1 year, 37 weeks, 1 hour, 59 minutes
WARNING:
The warnings about write_memory() also apply to write_object().
Parameters
• object -- Object to write to.
• value -- Value to write. This may be an Object or a Python value. Either way, it will be
converted to the type of object.
• dereference -- If object is a pointer, whether to dereference it. If True, then write to
the object pointed to by object (*ptr=value). If False, then write to the pointer
itself (ptr=value). This is a common source of confusion, so it is required if object
is a pointer.
Raises
• ValueError -- if object is not a reference object (i.e., its address is not known)
• TypeError -- if object is a pointer and dereference is not given
• TypeError -- if object is not a pointer and dereference is Truedrgn.helpers.experimental.kmodify.call_function(prog:drgn.Program,func:Union[str,drgn.Object],*args:Any)->drgn.Object
Call a function in the kernel.
Arguments can be either Objects or Python values. The function return value is returned as an
Object:
>>> # GFP_KERNEL isn't in the kernel debug info
>>> # We have to use this trick to get it.
>>> for flag in prog["gfpflag_names"]:
... if flag.name.string_() == b"GFP_KERNEL":
... GFP_KERNEL = flag.mask
... break
...
>>> # kmalloc() is actually a macro.
>>> # We have to call the underlying function.
>>> p = call_function("__kmalloc_noprof", 13, GFP_KERNEL)
>>> p
(void *)0xffff991701ef43c0
>>> identify_address(p)
'slab object: kmalloc-16+0x0'
>>> call_function("kfree", p)
(void)<absent>
>>> identify_address(p)
'free slab object: kmalloc-16+0x0'
Variadic functions are also supported:
>>> call_function("_printk", "Hello, world! %d\n", Object(prog, "int", 1234))
(int)18
>>> os.system("dmesg | tail -1")
[ 1138.223004] Hello, world! 1234
Constructed values can be passed by pointer using pass_pointer():
>>> sb = prog["init_fs"].root.mnt.mnt_sb
>>> sb.s_shrink.scan_objects
(unsigned long (*)(struct shrinker *, struct shrink_control *))super_cache_scan+0x0 = 0xffffffffbda4c487
>>> sc = pass_pointer(Object(prog, "struct shrink_control",
... {"gfp_mask": GFP_KERNEL, "nr_to_scan": 100, "nr_scanned": 100}))
>>> call_function(sb.s_shrink.scan_objects, sb.s_shrink, sc)
(unsigned long)31
If the function modifies the passed value, the pass_pointer object is updated:
>>> sc.object
(struct shrink_control){
.gfp_mask = (gfp_t)3264,
.nid = (int)0,
.nr_to_scan = (unsigned long)1,
.nr_scanned = (unsigned long)100,
.memcg = (struct mem_cgroup *)0x0,
}
NOTE:
It is not possible to call some functions, including inlined functions and function-like
macros. If the unavailable function is a wrapper around another function, sometimes the wrapped
function can be called instead.
WARNING:
Calling a function incorrectly may cause the kernel to crash or misbehave in various ways.
The function is called from process context. Note that the function may have context, locking,
or reference counting requirements.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• func -- Function to call. May be a function name, function object, or function pointer
object.
• args -- Function arguments. int, float, and bool arguments are converted as "literals"
with Object(prog,value=...). str and bytes arguments are converted to char array
objects. pass_pointer arguments are copied to the kernel, passed by pointer, and copied
back.
Returns
Function return value.
Raises
• TypeError -- if the passed arguments have incorrect types for the function
• ObjectAbsentError -- if the function cannot be called because it is inlined
• LookupError -- if a function with the given name is not found (possibly because it is
actually a function-like macro)
classdrgn.helpers.experimental.kmodify.pass_pointer(object:Any)
Wrapper used to pass values to call_function() by pointer.
Parametersobject -- Object or Python value to wrap.
object:Any
Wrapped object. Updated to an Object containing the final value after the function call.
LinuxKernel
The drgn.helpers.linux package contains several modules for working with data structures and subsystems
in the Linux kernel. The helpers are available from the individual modules in which they are defined and
from this top-level package. E.g., the following are both valid:
>>> from drgn.helpers.linux.list import list_for_each_entry
>>> from drgn.helpers.linux import list_for_each_entry
Iterator macros (for_each_foo) are a common idiom in the Linux kernel. The equivalent drgn helpers are
implemented as Python generators. For example, the following code in C:
list_for_each(pos, head)
do_something_with(pos);
Translates to the following code in Python:
for pos in list_for_each(head):
do_something_with(pos)
BitOperations
The drgn.helpers.linux.bitops module provides helpers for common bit operations in the Linux kernel.
drgn.helpers.linux.bitops.for_each_set_bit(bitmap:drgn.Object,size:drgn.IntegerLike)->Iterator[int]
Iterate over all set (one) bits in a bitmap.
Parameters
• bitmap -- unsignedlong*
• size -- Size of bitmap in bits.
drgn.helpers.linux.bitops.for_each_clear_bit(bitmap:drgn.Object,size:drgn.IntegerLike)->Iterator[int]
Iterate over all clear (zero) bits in a bitmap.
Parameters
• bitmap -- unsignedlong*
• size -- Size of bitmap in bits.
drgn.helpers.linux.bitops.test_bit(nr:drgn.IntegerLike,bitmap:drgn.Object)->bool
Return whether a bit in a bitmap is set.
Parameters
• nr -- Bit number.
• bitmap -- unsignedlong*BlockLayer
The drgn.helpers.linux.block module provides helpers for working with the Linux block layer, including
disks (structgendisk) and partitions.
Since Linux v5.11, partitions are represented by structblock_device. Before that, they were represented
by structhd_struct.
drgn.helpers.linux.block.disk_devt(disk:drgn.Object)->drgn.Object
Get a disk's device number.
Parametersdisk -- structgendisk*Returnsdev_tdrgn.helpers.linux.block.disk_name(disk:drgn.Object)->bytes
Get the name of a disk (e.g., sda).
Parametersdisk -- structgendisk*drgn.helpers.linux.block.bdev_partno(bdev:drgn.Object)->drgn.Object
Get the partition number of a block device.
Parametersbdev -- structblock_device*Returnsu8drgn.helpers.linux.block.for_each_disk(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all disks in the system.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structgendisk* objects.
drgn.helpers.linux.block.print_disks(prog:drgn.Program)->None
Print all of the disks in the system.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.block.part_devt(part:drgn.Object)->drgn.Object
Get a partition's device number.
Parameterspart -- structblock_device* or structhd_struct* depending on the kernel version.
Returnsdev_tdrgn.helpers.linux.block.part_name(part:drgn.Object)->bytes
Get the name of a partition (e.g., sda1).
Parameterspart -- structblock_device* or structhd_struct* depending on the kernel version.
drgn.helpers.linux.block.for_each_partition(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all partitions in the system.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structblock_device* or structhd_struct* objects depending on the kernel
version.
drgn.helpers.linux.block.print_partitions(prog:drgn.Program)->None
Print all of the partitions in the system.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Boot
The drgn.helpers.linux.boot module provides helpers for inspecting the Linux kernel boot configuration.
drgn.helpers.linux.boot.kaslr_offset(prog:drgn.Program)->int
Get the kernel address space layout randomization offset (zero if it is disabled).
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.boot.pgtable_l5_enabled(prog:drgn.Program)->bool
Return whether 5-level paging is enabled.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
BPF
The drgn.helpers.linux.bpf module provides helpers for working with BPF interface in include/linux/bpf.h,
include/linux/bpf-cgroup.h, etc.
drgn.helpers.linux.bpf.bpf_btf_for_each(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all BTF objects.
This is only supported since Linux v4.18.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structbtf* objects.
drgn.helpers.linux.bpf.bpf_link_for_each(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all BPF links.
This is only supported since Linux v5.8.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structbpf_link* objects.
drgn.helpers.linux.bpf.bpf_map_for_each(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all BPF maps.
This is only supported since Linux v4.13.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structbpf_map* objects.
drgn.helpers.linux.bpf.bpf_prog_for_each(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all BPF programs.
This is only supported since Linux v4.13.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structbpf_prog* objects.
drgn.helpers.linux.bpf.cgroup_bpf_prog_for_each(cgrp:drgn.Object,bpf_attach_type:drgn.IntegerLike)->Iterator[drgn.Object]
Iterate over all cgroup BPF programs of the given attach type attached to the given cgroup.
Parameters
• cgrp -- structcgroup*
• bpf_attach_type -- enumcgroup_bpf_attach_type (enumbpf_attach_type before Linux 5.15)
Returns
Iterator of structbpf_prog* objects.
drgn.helpers.linux.bpf.cgroup_bpf_prog_for_each_effective(cgrp:drgn.Object,bpf_attach_type:drgn.IntegerLike)->Iterator[drgn.Object]
Iterate over all effective cgroup BPF programs of the given attach type for the given cgroup.
Parameters
• cgrp -- structcgroup*
• bpf_attach_type -- enumbpf_attach_typeReturns
Iterator of structbpf_prog* objects.
Cgroup
The drgn.helpers.linux.cgroup module provides helpers for working with the cgroup interface in ‐
include/linux/cgroup.h. Only cgroup v2 is supported.
drgn.helpers.linux.cgroup.sock_cgroup_ptr(skcd:drgn.Object)->drgn.Object
Get the cgroup for a socket from the given structsock_cgroup_data* (usually from structsock::sk_cgrp_data).
Parametersskcd -- structsock_cgroup_data*Returnsstructcgroup*drgn.helpers.linux.cgroup.cgroup_parent(cgrp:drgn.Object)->drgn.Object
Return the parent cgroup of the given cgroup if it exists, NULL otherwise.
Parameterscgrp -- structcgroup*Returnsstructcgroup*drgn.helpers.linux.cgroup.cgroup_name(cgrp:drgn.Object)->bytes
Get the name of the given cgroup.
Parameterscgrp -- structcgroup*drgn.helpers.linux.cgroup.cgroup_path(cgrp:drgn.Object)->bytes
Get the full path of the given cgroup.
Parameterscgrp -- structcgroup*drgn.helpers.linux.cgroup.cgroup_get_from_path(prog:drgn.Program,path:drgn.Path)->drgn.Object
Look up a cgroup from its default hierarchy path .
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• path -- Path name.
drgn.helpers.linux.cgroup.css_next_child(pos:drgn.Object,parent:drgn.Object)->drgn.Object
Get the next child (or NULL if there is none) of the given parent starting from the given position
(NULL to initiate traversal).
Parameters
• pos -- structcgroup_subsys_state*
• parent -- structcgroup_subsys_state*Returnsstructcgroup_subsys_state*drgn.helpers.linux.cgroup.css_next_descendant_pre(pos:drgn.Object,root:drgn.Object)->drgn.Object
Get the next pre-order descendant (or NULL if there is none) of the given css root starting from
the given position (NULL to initiate traversal).
Parameters
• pos -- structcgroup_subsys_state*
• root -- structcgroup_subsys_state*Returnsstructcgroup_subsys_state*drgn.helpers.linux.cgroup.css_for_each_child(css:drgn.Object)->Iterator[drgn.Object]
Iterate through children (offline included) of the given css.
Parameterscss -- structcgroup_subsys_state*Returns
Iterator of structcgroup_subsys_state* objects.
drgn.helpers.linux.cgroup.css_for_each_descendant_pre(css:drgn.Object)->Iterator[drgn.Object]
Iterate through the given css's descendants (offline included) in pre-order.
Parameterscss -- structcgroup_subsys_state*Returns
Iterator of structcgroup_subsys_state* objects.
CPUMasks
The drgn.helpers.linux.cpumask module provides helpers for working with CPU masks from ‐
include/linux/cpumask.h.
drgn.helpers.linux.cpumask.cpu_online_mask(prog:drgn.Program)->drgn.Object
Return the mask of online CPUs.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returnsstructcpumask*drgn.helpers.linux.cpumask.cpu_possible_mask(prog:drgn.Program)->drgn.Object
Return the mask of possible CPUs.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returnsstructcpumask*drgn.helpers.linux.cpumask.cpu_present_mask(prog:drgn.Program)->drgn.Object
Return the mask of present CPUs.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returnsstructcpumask*drgn.helpers.linux.cpumask.for_each_cpu(mask:drgn.Object)->Iterator[int]
Iterate over all of the CPUs in the given mask.
Parametersmask -- structcpumask*drgn.helpers.linux.cpumask.for_each_online_cpu(prog:drgn.Program)->Iterator[int]
Iterate over all online CPUs.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.cpumask.for_each_possible_cpu(prog:drgn.Program)->Iterator[int]
Iterate over all possible CPUs.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.cpumask.for_each_present_cpu(prog:drgn.Program)->Iterator[int]
Iterate over all present CPUs.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.cpumask.cpumask_to_cpulist(mask:drgn.Object)->str
Return a CPU mask as a CPU list string.
>>> cpumask_to_cpulist(mask)
0-3,8-11
Parametersmask -- structcpumask*Returns
String in the CPUlistformat.
Devices
The drgn.helpers.linux.device module provides helpers for working with Linux devices, including the
kernel encoding of dev_t.
drgn.helpers.linux.device.MAJOR(dev:drgn.IntegerLike)->int
Return the major ID of a kernel dev_t.
Parametersdev -- dev_t object or int.
drgn.helpers.linux.device.MINOR(dev:drgn.IntegerLike)->int
Return the minor ID of a kernel dev_t.
Parametersdev -- dev_t object or int.
drgn.helpers.linux.device.MKDEV(major:drgn.IntegerLike,minor:drgn.IntegerLike)->int
Return a kernel dev_t from the major and minor IDs.
Parameters
• major -- Device major ID.
• minor -- Device minor ID.
VirtualFilesystemLayer
The drgn.helpers.linux.fs module provides helpers for working with the Linux virtual filesystem (VFS)
layer, including mounts, dentries, and inodes.
drgn.helpers.linux.fs.path_lookup(root:Union[drgn.Object,drgn.Program],path:drgn.Path,*,allow_negative:bool=False)->drgn.Object
Look up the given path name.
Parameters
• root -- structpath* to use as the root directory. Defaults to the initial root
filesystem if given a Program or omitted.
• path -- Path to lookup.
• allow_negative -- Whether to allow returning a negative dentry (i.e., a dentry for a
non-existent path).
ReturnsstructpathRaisesException -- if the dentry is negative and allow_negative is False, or if the path is not
present in the dcache. The latter does not necessarily mean that the path does not exist;
it may be uncached. On a live system, you can make the kernel cache the path by accessing
it (e.g., with open() or os.stat()):
>>> path_lookup('/usr/include/stdlib.h')
...
Exception: could not find '/usr/include/stdlib.h' in dcache
>>> open('/usr/include/stdlib.h').close()
>>> path_lookup('/usr/include/stdlib.h')
(struct path){
.mnt = (struct vfsmount *)0xffff8b70413cdca0,
.dentry = (struct dentry *)0xffff8b702ac2c480,
}
drgn.helpers.linux.fs.d_path(path:drgn.Object)->bytes
Return the full path of a dentry given a structpath.
Parameterspath -- structpath or structpath*drgn.helpers.linux.fs.d_path(vfsmnt:drgn.Object,dentry:drgn.Object)->bytes
Return the full path of a dentry given a mount and dentry.
Parameters
• vfsmnt -- structvfsmount*
• dentry -- structdentry*drgn.helpers.linux.fs.d_path(dentry:drgn.Object)->bytes
Return the full path of a dentry.
Since a mount is not provided, this arbitrarily selects a mount to determine the path.
Parametersdentry -- structdentry*drgn.helpers.linux.fs.dentry_path(dentry:drgn.Object)->bytes
Return the path of a dentry from the root of its filesystem.
Parametersdentry -- structdentry*drgn.helpers.linux.fs.inode_path(inode:drgn.Object)->Optional[bytes]
Return any path of an inode from the root of its filesystem.
Parametersinode -- structinode*Returns
Path, or None if the inode has no aliases.
drgn.helpers.linux.fs.inode_paths(inode:drgn.Object)->Iterator[bytes]
Return an iterator over all of the paths of an inode from the root of its filesystem.
Parametersinode -- structinode*drgn.helpers.linux.fs.mount_src(mnt:drgn.Object)->bytes
Get the source device name for a mount.
Parametersmnt -- structmount*drgn.helpers.linux.fs.mount_dst(mnt:drgn.Object)->bytes
Get the path of a mount point.
Parametersmnt -- structmount*drgn.helpers.linux.fs.mount_fstype(mnt:drgn.Object)->bytes
Get the filesystem type of a mount.
Parametersmnt -- structmount*drgn.helpers.linux.fs.for_each_mount(ns:Union[drgn.Object,drgn.Program],*,src:Optional[drgn.Path]=None,dst:Optional[drgn.Path]=None,fstype:Optional[Union[str,bytes]]=None)->Iterator[‐drgn.Object]
Iterate over all of the mounts in a given namespace.
Parameters
• ns -- structmnt_namespace*. Defaults to the initial mount namespace if given a Program
or omitted.
• src -- Only include mounts with this source device name.
• dst -- Only include mounts with this destination path.
• fstype -- Only include mounts with this filesystem type.
Returns
Iterator of structmount* objects.
drgn.helpers.linux.fs.print_mounts(ns:Union[drgn.Object,drgn.Program],*,src:Optional[drgn.Path]=None,dst:Optional[drgn.Path]=None,fstype:Optional[Union[str,bytes]]=None)->None
Print the mount table of a given namespace. The arguments are the same as for_each_mount(). The
output format is similar to /proc/mounts but prints the value of each structmount*.
drgn.helpers.linux.fs.fget(task:drgn.Object,fd:drgn.IntegerLike)->drgn.Object
Return the kernel file descriptor of the fd of a given task.
Parameters
• task -- structtask_struct*
• fd -- File descriptor.
Returnsstructfile*drgn.helpers.linux.fs.for_each_file(task:drgn.Object)->Iterator[Tuple[int,drgn.Object]]
Iterate over all of the files open in a given task.
Parameterstask -- structtask_struct*Returns
Iterator of (fd, structfile*) tuples.
drgn.helpers.linux.fs.print_files(task:drgn.Object)->None
Print the open files of a given task.
Parameterstask -- structtask_struct*IDR
The drgn.helpers.linux.idr module provides helpers for working with the IDR data structure in ‐
include/linux/idr.h. An IDR provides a mapping from an ID to a pointer.
drgn.helpers.linux.idr.idr_find(idr:drgn.Object,id:drgn.IntegerLike)->drgn.Object
Look up the entry with the given ID in an IDR.
Parameters
• idr -- structidr*
• id -- Entry ID.
Returnsvoid* found entry, or NULL if not found.
drgn.helpers.linux.idr.idr_for_each(idr:drgn.Object)->Iterator[Tuple[int,drgn.Object]]
Iterate over all of the pointers in an IDR.
Parametersidr -- structidr*Returns
Iterator of (index, void*) tuples.
drgn.helpers.linux.idr.idr_for_each_entry(idr:drgn.Object,type:Union[str,drgn.Type])->Iterator[Tuple[int,drgn.Object]]
Iterate over all of the entries with the given type in an IDR.
Parameters
• idr -- structidr*
• type -- Entry type.
Returns
Iterator of (index, type*) tuples.
Kallsyms
The drgn.helpers.linux.kallsyms module contains helpers which allow you to use the built-in kallsyms
symbol table for drgn symbol lookup. Combined with an alternative type information source, this can
enable debugging Linux kernel core dumps without the corresponding DWARF debuginfo files. Even without
type information, kallsyms can be used to help locate objects, and drgn's low-level memory reading
functions can be used to do basic debugging tasks.
drgn.helpers.linux.kallsyms.load_vmlinux_kallsyms(prog:drgn.Program)->drgn.SymbolIndex
Create a kallsyms index for vmlinux
This function loads the kallsyms for the core kernel and returns a symbol index. This function
does not require that any debuginfo is loaded for the kernel: it either relies on /proc/kallsyms
(which requires running drgn as root) or it parses internal data structures using information
found from the VMCOREINFO note (which requires Linux 6.0 or later, or a backport of commit
f09bddbd86619("vmcoreinfo:addkallsyms_num_symssymbol") and its dependencies).
Returns
a symbol index containing kallsyms for the core kernel (vmlinux)
drgn.helpers.linux.kallsyms.load_module_kallsyms(prog:drgn.Program)->drgn.SymbolIndex
Return a symbol index containing all module symbols from kallsyms
For kernels built with CONFIG_KALLSYMS, loaded kernel modules contain an ELF symbol table in
kernel memory. This function can parse those data structures and create a symbol index usable by
drgn. However, it requires that you already have debuginfo for the vmlinux image.
Returns
a symbol index containing all symbols from module kallsyms
Kconfig
The drgn.helpers.linux.kconfig module provides helpers for reading the Linux kernel build configuration.
drgn.helpers.linux.kconfig.get_kconfig(prog:drgn.Program)->Mapping[str,str]
Get the kernel build configuration as a mapping from the option name to the value.
>>> get_kconfig()['CONFIG_SMP']
'y'
>>> get_kconfig()['CONFIG_HZ']
'300'
This is only supported if the kernel was compiled with CONFIG_IKCONFIG. Note that most Linux
distributions do not enable this option.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Kernfs
The drgn.helpers.linux.kernfs module provides helpers for working with the kernfs pseudo filesystem
interface in include/linux/kernfs.h.
drgn.helpers.linux.kernfs.kernfs_name(kn:drgn.Object)->bytes
Get the name of the given kernfs node.
Parameterskn -- structkernfs_node*drgn.helpers.linux.kernfs.kernfs_path(kn:drgn.Object)->bytes
Get full path of the given kernfs node.
Parameterskn -- structkernfs_node*drgn.helpers.linux.kernfs.kernfs_walk(parent:drgn.Object,path:drgn.Path)->drgn.Object
Find the kernfs node with the given path from the given parent kernfs node.
Parameters
• parent -- structkernfs_node*
• path -- Path name.
Returnsstructkernfs_node* (NULL if not found)
LinkedLists
The drgn.helpers.linux.list module provides helpers for working with the doubly-linked list
implementations (structlist_head and structhlist_head) in include/linux/list.h.
drgn.helpers.linux.list.list_empty(head:drgn.Object)->bool
Return whether a list is empty.
Parametershead -- structlist_head*drgn.helpers.linux.list.list_is_singular(head:drgn.Object)->bool
Return whether a list has only one element.
Parametershead -- structlist_head*drgn.helpers.linux.list.list_count_nodes(head:drgn.Object)->int
Return the number of nodes in a list.
Parametershead -- structlist_head*drgn.helpers.linux.list.list_first_entry(head:drgn.Object,type:Union[str,drgn.Type],member:str)->drgn.Object
Return the first entry in a list.
The list is assumed to be non-empty.
See also list_first_entry_or_null().
Parameters
• head -- structlist_head*
• type -- Entry type.
• member -- Name of list node member in entry type.
Returnstype*drgn.helpers.linux.list.list_first_entry_or_null(head:drgn.Object,type:Union[str,drgn.Type],member:str)->drgn.Object
Return the first entry in a list or NULL if the list is empty.
See also list_first_entry().
Parameters
• head -- structlist_head*
• type -- Entry type.
• member -- Name of list node member in entry type.
Returnstype*drgn.helpers.linux.list.list_last_entry(head:drgn.Object,type:Union[str,drgn.Type],member:str)->drgn.Object
Return the last entry in a list.
The list is assumed to be non-empty.
Parameters
• head -- structlist_head*
• type -- Entry type.
• member -- Name of list node member in entry type.
Returnstype*drgn.helpers.linux.list.list_next_entry(pos:drgn.Object,member:str)->drgn.Object
Return the next entry in a list.
Parameters
• pos -- type*
• member -- Name of list node member in entry type.
Returnstype*drgn.helpers.linux.list.list_prev_entry(pos:drgn.Object,member:str)->drgn.Object
Return the previous entry in a list.
Parameters
• pos -- type*
• member -- Name of list node member in entry type.
Returnstype*drgn.helpers.linux.list.list_for_each(head:drgn.Object)->Iterator[drgn.Object]
Iterate over all of the nodes in a list.
Parametershead -- structlist_head*Returns
Iterator of structlist_head* objects.
drgn.helpers.linux.list.list_for_each_reverse(head:drgn.Object)->Iterator[drgn.Object]
Iterate over all of the nodes in a list in reverse order.
Parametershead -- structlist_head*Returns
Iterator of structlist_head* objects.
drgn.helpers.linux.list.list_for_each_entry(type:Union[str,drgn.Type],head:drgn.Object,member:str)->Iterator[drgn.Object]
Iterate over all of the entries in a list.
Parameters
• type -- Entry type.
• head -- structlist_head*
• member -- Name of list node member in entry type.
Returns
Iterator of type* objects.
drgn.helpers.linux.list.list_for_each_entry_reverse(type:Union[str,drgn.Type],head:drgn.Object,member:str)->Iterator[drgn.Object]
Iterate over all of the entries in a list in reverse order.
Parameters
• type -- Entry type.
• head -- structlist_head*
• member -- Name of list node member in entry type.
Returns
Iterator of type* objects.
drgn.helpers.linux.list.validate_list(head:drgn.Object)->None
Validate that the next and prev pointers in a list are consistent.
Parametershead -- structlist_head*RaisesValidationError -- if the list is invalid
drgn.helpers.linux.list.validate_list_for_each(head:drgn.Object)->Iterator[drgn.Object]
Like list_for_each(), but validates the list like validate_list() while iterating.
Parametershead -- structlist_head*RaisesValidationError -- if the list is invalid
drgn.helpers.linux.list.validate_list_for_each_entry(type:Union[str,drgn.Type],head:drgn.Object,member:str)->Iterator[drgn.Object]
Like list_for_each_entry(), but validates the list like validate_list() while iterating.
Parameters
• type -- Entry type.
• head -- structlist_head*
• member -- Name of list node member in entry type.
RaisesValidationError -- if the list is invalid
drgn.helpers.linux.list.hlist_empty(head:drgn.Object)->bool
Return whether a hash list is empty.
Parametershead -- structhlist_head*drgn.helpers.linux.list.hlist_for_each(head:drgn.Object)->Iterator[drgn.Object]
Iterate over all of the nodes in a hash list.
Parametershead -- structhlist_head*Returns
Iterator of structhlist_node* objects.
drgn.helpers.linux.list.hlist_for_each_entry(type:Union[str,drgn.Type],head:drgn.Object,member:str)->Iterator[drgn.Object]
Iterate over all of the entries in a hash list.
Parameters
• type -- Entry type.
• head -- structhlist_head*
• member -- Name of list node member in entry type.
Returns
Iterator of type* objects.
NullsLists
The drgn.helpers.linux.list_nulls module provides helpers for working with the special version of lists
(structhlist_nulls_head and structhlist_nulls_node) in include/linux/list_nulls.h where the end of list
is not a NULL pointer, but a "nulls" marker.
drgn.helpers.linux.list_nulls.is_a_nulls(pos:drgn.Object)->bool
Return whether a a pointer is a nulls marker.
Parameterspos -- structhlist_nulls_node*drgn.helpers.linux.list_nulls.hlist_nulls_empty(head:drgn.Object)->bool
Return whether a nulls hash list is empty.
Parametershead -- structhlist_nulls_head*drgn.helpers.linux.list_nulls.hlist_nulls_for_each_entry(type:Union[str,drgn.Type],head:drgn.Object,member:str)->Iterator[drgn.Object]
Iterate over all the entries in a nulls hash list.
Parameters
• type -- Entry type.
• head -- structhlist_nulls_head*
• member -- Name of list node member in entry type.
Returns
Iterator of type* objects.
LocklessLists
The drgn.helpers.linux.llist module provides helpers for working with the lockless, NULL-terminated,
singly-linked list implementation in include/linux/llist.h (structllist_head and structllist_node).
drgn.helpers.linux.llist.llist_empty(head:drgn.Object)->bool
Return whether an llist is empty.
Parametershead -- structllist_head*drgn.helpers.linux.llist.llist_is_singular(head:drgn.Object)->bool
Return whether an llist has only one element.
Parametershead -- structllist_head*drgn.helpers.linux.llist.llist_first_entry(head:drgn.Object,type:Union[str,drgn.Type],member:str)->drgn.Object
Return the first entry in an llist.
The list is assumed to be non-empty.
See also llist_first_entry_or_null().
Parameters
• head -- structllist_head*
• type -- Entry type.
• member -- Name of structllist_node member in entry type.
Returnstype*drgn.helpers.linux.llist.llist_first_entry_or_null(head:drgn.Object,type:Union[str,drgn.Type],member:str)->drgn.Object
Return the first entry in an llist or NULL if the llist is empty.
See also llist_first_entry().
Parameters
• head -- structllist_head*
• type -- Entry type.
• member -- Name of structllist_node member in entry type.
Returnstype*drgn.helpers.linux.llist.llist_next_entry(pos:drgn.Object,member:str)->drgn.Object
Return the next entry in an llist.
Parameters
• pos -- type*
• member -- Name of structllist_node member in entry type.
Returnstype*drgn.helpers.linux.llist.llist_for_each(node:drgn.Object)->Iterator[drgn.Object]
Iterate over all of the nodes in an llist starting from a given node.
Parametersnode -- structllist_node*Returns
Iterator of structllist_node* objects.
drgn.helpers.linux.llist.llist_for_each_entry(type:Union[str,drgn.Type],node:drgn.Object,member:str)->Iterator[drgn.Object]
Iterate over all of the entries in an llist starting from a given node.
Parameters
• type -- Entry type.
• node -- structllist_node*
• member -- Name of structllist_node member in entry type.
Returns
Iterator of type* objects.
MapleTrees
The drgn.helpers.linux.mapletree module provides helpers for working with maple trees from ‐
include/linux/maple_tree.h.
Maple trees were introduced in Linux 6.1.
drgn.helpers.linux.mapletree.mtree_load(mt:drgn.Object,index:drgn.IntegerLike,*,advanced:bool=False)->drgn.Object
Look up the entry at a given index in a maple tree.
>>> entry = mtree_load(task.mm.mm_mt.address_of_(), 0x55d65cfaa000)
>>> cast("struct vm_area_struct *", entry)
*(struct vm_area_struct *)0xffff97ad82bfc930 = {
...
}
Parameters
• mt -- structmaple_tree*
• index -- Entry index.
• advanced -- Whether to return nodes only visible to the maple tree advanced API. If
False, zero entries (see xa_is_zero()) will be returned as NULL.
Returnsvoid* found entry, or NULL if not found.
drgn.helpers.linux.mapletree.mt_for_each(mt:drgn.Object,*,advanced:bool=False)->Iterator[Tuple[int,int,drgn.Object]]
Iterate over all of the entries and their ranges in a maple tree.
>>> for first_index, last_index, entry in mt_for_each(task.mm.mm_mt.address_of_()):
... print(hex(first_index), hex(last_index), entry)
...
0x55d65cfaa000 0x55d65cfaafff (void *)0xffff97ad82bfc930
0x55d65cfab000 0x55d65cfabfff (void *)0xffff97ad82bfc0a8
0x55d65cfac000 0x55d65cfacfff (void *)0xffff97ad82bfc000
0x55d65cfad000 0x55d65cfadfff (void *)0xffff97ad82bfcb28
...
Parameters
• mt -- structmaple_tree*
• advanced -- Whether to return nodes only visible to the maple tree advanced API. If
False, zero entries (see xa_is_zero()) will be skipped.
Returns
Iterator of (first_index, last_index, void*) tuples. Both indices are inclusive.
MemoryManagement
The drgn.helpers.linux.mm module provides helpers for working with the Linux memory management (MM)
subsystem.
Helpers that translate virtual addresses or read virtual memory may fail for multiple reasons:
1. If the address is invalid.
2. If the address is swapped or paged out.
3. If the address is in highmemory. High memory is only used for userspace memory by 32-bit systems with
a lot of physical memory, and only if CONFIG_HIGHMEM is enabled.
3a. If the page table is in high memory. This is only possible if CONFIG_HIGHPTE is enabled.
drgn.helpers.linux.mm.PageActive(page:drgn.Object)->bool
Return whether the PG_active flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageChecked(page:drgn.Object)->bool
Return whether the PG_checked flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageDirty(page:drgn.Object)->bool
Return whether the PG_dirty flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageDoubleMap(page:drgn.Object)->bool
Return whether the PG_double_map flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageError(page:drgn.Object)->bool
Return whether the PG_error flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageForeign(page:drgn.Object)->bool
Return whether the PG_foreign flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageHWPoison(page:drgn.Object)->bool
Return whether the PG_hwpoison flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageHasHWPoisoned(page:drgn.Object)->bool
Return whether the PG_has_hwpoisoned flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageIdle(page:drgn.Object)->bool
Return whether the PG_idle flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageIsolated(page:drgn.Object)->bool
Return whether the PG_isolated flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageLRU(page:drgn.Object)->bool
Return whether the PG_lru flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageLocked(page:drgn.Object)->bool
Return whether the PG_locked flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageMappedToDisk(page:drgn.Object)->bool
Return whether the PG_mappedtodisk flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageMlocked(page:drgn.Object)->bool
Return whether the PG_mlocked flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageOwnerPriv1(page:drgn.Object)->bool
Return whether the PG_owner_priv_1 flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PagePinned(page:drgn.Object)->bool
Return whether the PG_pinned flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PagePrivate(page:drgn.Object)->bool
Return whether the PG_private flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PagePrivate2(page:drgn.Object)->bool
Return whether the PG_private_2 flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageReadahead(page:drgn.Object)->bool
Return whether the PG_readahead flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageReclaim(page:drgn.Object)->bool
Return whether the PG_reclaim flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageReferenced(page:drgn.Object)->bool
Return whether the PG_referenced flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageReported(page:drgn.Object)->bool
Return whether the PG_reported flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageReserved(page:drgn.Object)->bool
Return whether the PG_reserved flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageSavePinned(page:drgn.Object)->bool
Return whether the PG_savepinned flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageSkipKASanPoison(page:drgn.Object)->bool
Return whether the PG_skip_kasan_poison flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageSlobFree(page:drgn.Object)->bool
Return whether the PG_slob_free flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageSwapBacked(page:drgn.Object)->bool
Return whether the PG_swapbacked flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageUncached(page:drgn.Object)->bool
Return whether the PG_uncached flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageUnevictable(page:drgn.Object)->bool
Return whether the PG_unevictable flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageUptodate(page:drgn.Object)->bool
Return whether the PG_uptodate flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageVmemmapSelfHosted(page:drgn.Object)->bool
Return whether the PG_vmemmap_self_hosted flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageWaiters(page:drgn.Object)->bool
Return whether the PG_waiters flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageWorkingset(page:drgn.Object)->bool
Return whether the PG_workingset flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageWriteback(page:drgn.Object)->bool
Return whether the PG_writeback flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageXenRemapped(page:drgn.Object)->bool
Return whether the PG_xen_remapped flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageYoung(page:drgn.Object)->bool
Return whether the PG_young flag is set on a page.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageSlab(page:drgn.Object)->bool
Return whether a page belongs to the slab allocator.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageCompound(page:drgn.Object)->bool
Return whether a page is part of a compoundpage.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageHead(page:drgn.Object)->bool
Return whether a page is a head page in a compoundpage.
Parameterspage -- structpage*drgn.helpers.linux.mm.PageTail(page:drgn.Object)->bool
Return whether a page is a tail page in a compoundpage.
Parameterspage -- structpage*drgn.helpers.linux.mm.compound_head(page:drgn.Object)->drgn.Object
Get the head page associated with a page.
If page is a tail page, this returns the head page of the compoundpage it belongs to. Otherwise,
it returns page.
Parameterspage -- structpage*Returnsstructpage*drgn.helpers.linux.mm.compound_order(page:drgn.Object)->drgn.Object
Return the allocation order of a potentially compoundpage.
Parameterspage -- structpage*Returnsunsignedintdrgn.helpers.linux.mm.compound_nr(page:drgn.Object)->drgn.Object
Return the number of pages in a potentially compoundpage.
Parameterspage -- structpage*Returnsunsignedlongdrgn.helpers.linux.mm.page_size(page:drgn.Object)->drgn.Object
Return the number of bytes in a potentially compoundpage.
Parameterspage -- structpage*Returnsunsignedlongdrgn.helpers.linux.mm.decode_page_flags(page:drgn.Object)->str
Get a human-readable representation of the flags set on a page.
>>> decode_page_flags(page)
'PG_uptodate|PG_dirty|PG_lru|PG_reclaim|PG_swapbacked|PG_readahead|PG_savepinned|PG_isolated|PG_reported'
Parameterspage -- structpage*drgn.helpers.linux.mm.for_each_page(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over every structpage* from the minimum to the maximum page.
NOTE:
This may include offline pages which don't have a valid structpage. Wrap accesses in a try ...
exceptdrgn.FaultError:
>>> for page in for_each_page():
... try:
... if PageLRU(page):
... print(hex(page))
... except drgn.FaultError:
... continue
0xfffffb4a000c0000
0xfffffb4a000c0040
...
This may be fixed in the future.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structpage* objects.
drgn.helpers.linux.mm.PFN_PHYS(prog:drgn.Program,pfn:drgn.IntegerLike)->drgn.Object
Get the physical address of a page frame number (PFN).
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• pfn -- unsignedlongReturnsphys_addr_tdrgn.helpers.linux.mm.PHYS_PFN(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the page frame number (PFN) of a physical address.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- phys_addr_tReturnsunsignedlongdrgn.helpers.linux.mm.page_to_pfn(page:drgn.Object)->drgn.Object
Get the page frame number (PFN) of a page.
Parameterspage -- structpage*Returnsunsignedlongdrgn.helpers.linux.mm.page_to_phys(page:drgn.Object)->drgn.Object
Get the physical address of a page.
Parameterspage -- structpage*Returnsphys_addr_tdrgn.helpers.linux.mm.page_to_virt(page:drgn.Object)->drgn.Object
Get the directly mapped virtual address of a page.
Parameterspage -- structpage*Returnsvoid*drgn.helpers.linux.mm.pfn_to_page(prog:drgn.Program,pfn:drgn.IntegerLike)->drgn.Object
Get the page with a page frame number (PFN).
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• pfn -- unsignedlongReturnsstructpage*drgn.helpers.linux.mm.pfn_to_virt(prog:drgn.Program,pfn:drgn.IntegerLike)->drgn.Object
Get the directly mapped virtual address of a page frame number (PFN).
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• pfn -- unsignedlongReturnsvoid*drgn.helpers.linux.mm.phys_to_page(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the page containing a physical address.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- phys_addr_tReturnsstructpage*drgn.helpers.linux.mm.phys_to_virt(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the directly mapped virtual address of a physical address.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- phys_addr_tReturnsvoid*drgn.helpers.linux.mm.virt_to_page(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the page containing a directly mapped virtual address.
NOTE:
This only works for virtual addresses from the "direct map". This includes address from:
• kmalloc
• Slab allocator
• Page allocator
But not:
• vmalloc
• vmap
• ioremap
• Symbols (function pointers, global variables)
For vmalloc or vmap addresses, use vmalloc_to_page(addr). For arbitrary kernel addresses, use
follow_page(prog["init_mm"].address_of_(),addr).
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*Returnsstructpage*drgn.helpers.linux.mm.virt_to_pfn(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the page frame number (PFN) of a directly mapped virtual address.
NOTE:
This only works for virtual addresses from the "directmap". For vmalloc or vmap addresses, use
vmalloc_to_pfn(addr). For arbitrary kernel addresses, use
follow_pfn(prog["init_mm"].address_of_(),addr).
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*Returnsunsignedlongdrgn.helpers.linux.mm.virt_to_phys(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the physical address of a directly mapped virtual address.
NOTE:
This only works for virtual addresses from the "directmap". For arbitrary kernel addresses,
use follow_phys(prog["init_mm"].address_of_(),addr).
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*Returnsphys_addr_tdrgn.helpers.linux.mm.follow_page(mm:drgn.Object,addr:drgn.IntegerLike)->drgn.Object
Get the page that a virtual address maps to in a virtual address space.
>>> task = find_task(113)
>>> follow_page(task.mm, 0x7fffbbb6d4d0)
*(struct page *)0xffffbe4bc0337b80 = {
...
}
Parameters
• mm -- structmm_struct*
• addr -- void*Returnsstructpage*Raises
• FaultError -- if the virtual address cannotbetranslated
• NotImplementedError -- if virtual address translation is notsupported for this
architecture yet
drgn.helpers.linux.mm.follow_pfn(mm:drgn.Object,addr:drgn.IntegerLike)->drgn.Object
Get the page frame number (PFN) that a virtual address maps to in a virtual address space.
>>> task = find_task(113)
>>> follow_pfn(task.mm, 0x7fffbbb6d4d0)
(unsigned long)52718
Parameters
• mm -- structmm_struct*
• addr -- void*ReturnsunsignedlongRaises
• FaultError -- if the virtual address cannotbetranslated
• NotImplementedError -- if virtual address translation is notsupported for this
architecture yet
drgn.helpers.linux.mm.follow_phys(mm:drgn.Object,addr:drgn.IntegerLike)->drgn.Object
Get the physical address that a virtual address maps to in a virtual address space.
>>> task = find_task(113)
>>> follow_phys(task.mm, 0x7fffbbb6d4d0)
(phys_addr_t)215934160
Parameters
• mm -- structmm_struct*
• addr -- void*Returnsphys_addr_tRaises
• FaultError -- if the virtual address cannotbetranslated
• NotImplementedError -- if virtual address translation is notsupported for this
architecture yet
drgn.helpers.linux.mm.vmalloc_to_page(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the page containing a vmalloc or vmap address.
>>> task = find_task(113)
>>> vmalloc_to_page(task.stack)
*(struct page *)0xffffbe4bc00a2200 = {
...
}
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*Returnsstructpage*drgn.helpers.linux.mm.vmalloc_to_pfn(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the page frame number (PFN) containing a vmalloc or vmap address.
>>> task = find_task(113)
>>> vmalloc_to_pfn(task.stack)
(unsigned long)10376
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*Returnsunsignedlongdrgn.helpers.linux.mm.find_vmap_area(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Return the structvmap_area* containing an address.
>>> find_vmap_area(0xffffa2b680081000)
*(struct vmap_area *)0xffffa16541046b40 = {
...
}
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- Address to look up.
Returnsstructvmap_area* (NULL if not found)
drgn.helpers.linux.mm.for_each_vmap_area(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over every structvmap_area* on the system.
>>> for va in for_each_vmap_area():
... caller = ""
... if va.vm:
... sym = prog.symbol(va.vm.caller)
... if sym:
... caller = f" {sym.name}"
... print(f"{hex(va.va_start)}-{hex(va.va_end)}{caller}")
...
0xffffa2b680000000-0xffffa2b680005000 irq_init_percpu_irqstack
0xffffa2b680005000-0xffffa2b680007000 acpi_os_map_iomem
0xffffa2b68000b000-0xffffa2b68000d000 hpet_enable
0xffffa2b680080000-0xffffa2b680085000 kernel_clone
...
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structvmap_area* objects.
drgn.helpers.linux.mm.access_process_vm(task:drgn.Object,address:drgn.IntegerLike,size:drgn.IntegerLike)->bytes
Read memory from a task's virtual address space.
>>> task = find_task(1490152)
>>> access_process_vm(task, 0x7f8a62b56da0, 12)
b'hello, world'
Parameters
• task -- structtask_struct*
• address -- Starting address.
• size -- Number of bytes to read.
Raises
• FaultError -- if the virtual address cannotbetranslated
• NotImplementedError -- if virtual address translation is notsupported for this
architecture yet
drgn.helpers.linux.mm.access_remote_vm(mm:drgn.Object,address:drgn.IntegerLike,size:drgn.IntegerLike)->bytes
Read memory from a virtual address space. This is similar to access_process_vm(), but it takes a
structmm_struct* instead of a structtask_struct*.
>>> task = find_task(1490152)
>>> access_remote_vm(task.mm, 0x7f8a62b56da0, 12)
b'hello, world'
Parameters
• mm -- structmm_struct*
• address -- Starting address.
• size -- Number of bytes to read.
Raises
• FaultError -- if the virtual address cannotbetranslated
• NotImplementedError -- if virtual address translation is notsupported for this
architecture yet
drgn.helpers.linux.mm.cmdline(task:drgn.Object)->Optional[List[bytes]]
Get the list of command line arguments of a task, or None for kernel tasks.
>>> cmdline(find_task(1495216))
[b'vim', b'drgn/helpers/linux/mm.py']
$ tr '\0' ' ' < /proc/1495216/cmdline
vim drgn/helpers/linux/mm.py
Parameterstask -- structtask_struct*Raises
• FaultError -- if the virtual address containing the command line cannotbetranslated
• NotImplementedError -- if virtual address translation is notsupported for this
architecture yet
drgn.helpers.linux.mm.environ(task:drgn.Object)->Optional[List[bytes]]
Get the list of environment variables of a task, or None for kernel tasks.
>>> environ(find_task(1497797))
[b'HOME=/root', b'PATH=/usr/local/sbin:/usr/local/bin:/usr/bin', b'LOGNAME=root']
$ tr '\0' '\n' < /proc/1497797/environ
HOME=/root
PATH=/usr/local/sbin:/usr/local/bin:/usr/bin
LOGNAME=root
Parameterstask -- structtask_struct*Raises
• FaultError -- if the virtual address containing the environment cannotbetranslated
• NotImplementedError -- if virtual address translation is notsupported for this
architecture yet
drgn.helpers.linux.mm.vma_find(mm:drgn.Object,addr:drgn.IntegerLike)->drgn.Object
Return the virtual memory area (VMA) containing an address.
Parameters
• mm -- structmm_struct*
• addr -- Address to look up.
Returnsstructvm_area_struct* (NULL if not found)
drgn.helpers.linux.mm.for_each_vma(mm:drgn.Object)->Iterator[drgn.Object]
Iterate over every virtual memory area (VMA) in a virtual address space.
>>> for vma in for_each_vma(task.mm):
... print(vma)
...
*(struct vm_area_struct *)0xffff97ad82bfc930 = {
...
}
*(struct vm_area_struct *)0xffff97ad82bfc0a8 = {
...
}
...
Parametersmm -- structmm_struct*Returns
Iterator of structvm_area_struct* objects.
drgn.helpers.linux.mm.totalram_pages(prog:drgn.Program)->int
Return the total number of RAM pages.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.mm.in_direct_map(prog:drgn.Program,addr:drgn.IntegerLike)->bool
Return True if an address is within the kernel's direct memory mapping :param prog: Program, which
maybeomittedtousethedefaultprogramargument.:param addr: address to check
Modules
The drgn.helpers.linux.module module contains helpers for working with loaded kernel modules.
drgn.helpers.linux.module.for_each_module(prog:drgn.Program)->Iterable[drgn.Object]
Returns all loaded kernel modules
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterable of structmodule* objects
drgn.helpers.linux.module.find_module(prog:drgn.Program,name:Union[str,bytes])->drgn.Object
Lookup a kernel module by name, or return NULL if not found
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• name -- name to search for
Returns
the structmodule* by that name, or NULL
drgn.helpers.linux.module.module_percpu_region(mod:drgn.Object)->Tuple[int,int]
Lookup the percpu memory region of a module.
Given a structmodule*, return the address (as a an int) and the length of the percpu memory
region. Modules may have a NULL percpu region, in which case (0, 0) is returned. Rarely, on
kernels without CONFIG_SMP, there is no percpu region at all, and this function returns (0, 0)
Parametersmod -- Object of type structmodule*Returns
(base, size) of the module percpu region
drgn.helpers.linux.module.module_address_regions(mod:drgn.Object)->List[Tuple[int,int]]
Returns a list of address ranges for a module
Given a structmodule*, return every address range associated with the module. Note that the
number of address ranges and their interpretations vary across kernel versions. Some kernel
versions provide additional information about some regions (e.g. text, data, R/O, init). This API
doesn't distinguish. However, this API does not provide the module's percpu region: use
module_percpu_region() for that.
Parametersmod -- Object of type structmodule*Returns
list of tuples: (starting memory address, length of address range)
drgn.helpers.linux.module.address_to_module(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Return the structmodule* associated with a memory address
If the address is a text, data, or read-only data address associated with a kernel module, then
this function returns the module it is associated with. Otherwise, returns NULL. Note that
dynamic memory (e.g. slab objects) generally can't be associated with the module that allocated
it. Further, static & dynamic per-cpu address cannot be associated with their associated module
either.
Normally, this lookup is efficient, thanks to CONFIG_MODULES_TREE_LOOKUP, which provides a
red-black tree of module address ranges, and is verycommonly enabled. However, on some uncommon
configurations the rbtree may not be present. In those cases, we fall back to a linear search of
each kernel module's memory regions.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- memory address to lookup
Returns
the structmodule* associated with the memory, or NULL
Networking
The drgn.helpers.linux.net module provides helpers for working with the Linux kernel networking
subsystem.
drgn.helpers.linux.net.SOCKET_I(inode:drgn.Object)->drgn.Object
Get a socket from an inode referring to the socket.
Parametersinode -- structinode*Returnsstructsocket*RaisesValueError -- If inode does not refer to a socket
drgn.helpers.linux.net.SOCK_INODE(sock:drgn.Object)->drgn.Object
Get the inode of a socket.
Parameterssock -- structsocket*Returnsstructinode*drgn.helpers.linux.net.for_each_net(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all network namespaces in the system.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structnet* objects.
drgn.helpers.linux.net.get_net_ns_by_inode(inode:drgn.Object)->drgn.Object
Get a network namespace from a network namespace NSFS inode, e.g. /proc/$PID/ns/net or
/var/run/netns/$NAME.
Parametersinode -- structinode*Returnsstructnet*RaisesValueError -- if inode is not a network namespace inode
drgn.helpers.linux.net.get_net_ns_by_fd(task:drgn.Object,fd:drgn.IntegerLike)->drgn.Object
Get a network namespace from a task and a file descriptor referring to a network namespace NSFS
inode, e.g. /proc/$PID/ns/net or /var/run/netns/$NAME.
Parameters
• task -- structtask_struct*
• fd -- File descriptor.
Returnsstructnet*RaisesValueError -- If fd does not refer to a network namespace inode
drgn.helpers.linux.net.netdev_for_each_tx_queue(dev:drgn.Object)->Iterator[drgn.Object]
Iterate over all TX queues for a network device.
Parametersdev -- structnet_device*Returns
Iterator of structnetdev_queue* objects.
drgn.helpers.linux.net.netdev_get_by_index(net:Union[drgn.Object,drgn.Program],ifindex:drgn.IntegerLike)->drgn.Object
Get the network device with the given interface index number.
Parameters
• net -- structnet*. Defaults to the initial network namespace if given a Program or
omitted.
• ifindex -- Network interface index number.
Returnsstructnet_device* (NULL if not found)
drgn.helpers.linux.net.netdev_get_by_name(net:Union[drgn.Object,drgn.Program],name:Union[str,bytes])->drgn.Object
Get the network device with the given interface name.
Parameters
• net -- structnet*. Defaults to the initial network namespace if given a Program or
omitted.
• name -- Network interface name.
Returnsstructnet_device* (NULL if not found)
drgn.helpers.linux.net.netdev_priv(dev:drgn.Object,type:Union[str,drgn.Type]='void')->drgn.Object
Return the private data of a network device.
>>> dev = netdev_get_by_name("wlp0s20f3")
>>> netdev_priv(dev)
(void *)0xffff9419c9dec9c0
>>> netdev_priv(dev, "struct ieee80211_sub_if_data")
*(struct ieee80211_sub_if_data *)0xffff9419c9dec9c0 = {
...
}
Parameters
• dev -- structnet_device*
• type -- Type of private data.
Returnstype*drgn.helpers.linux.net.sk_fullsock(sk:drgn.Object)->bool
Check whether a socket is a full socket, i.e., not a time-wait or request socket.
Parameterssk -- structsock*drgn.helpers.linux.net.sk_nulls_for_each(head:drgn.Object)->Iterator[drgn.Object]
Iterate over all the entries in a nulls hash list of sockets specified by structhlist_nulls_head
head.
Parametershead -- structhlist_nulls_head*Returns
Iterator of structsock* objects.
drgn.helpers.linux.net.skb_shinfo(skb:drgn.Object)->drgn.Object
Get the shared info for a socket buffer.
Parametersskb -- structsk_buff*Returnsstructskb_shared_info*NUMANodeMasks
The drgn.helpers.linux.nodemask module provides helpers for working with NUMA node masks from ‐
include/linux/nodemask.h.
drgn.helpers.linux.nodemask.for_each_node_mask(mask:drgn.Object)->Iterator[int]
Iterate over all of the NUMA nodes in the given mask.
Parametersmask -- nodemask_tdrgn.helpers.linux.nodemask.for_each_node_state(prog:drgn.Program,state:drgn.IntegerLike)->Iterator[int]
Iterate over all NUMA nodes in the given state.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• state -- enumnode_states (e.g., N_NORMAL_MEMORY)
drgn.helpers.linux.nodemask.for_each_node(prog:drgn.Program)->Iterator[int]
Iterate over all possible NUMA nodes.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.nodemask.for_each_online_node(prog:drgn.Program)->Iterator[int]
Iterate over all online NUMA nodes.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.nodemask.node_state(node:drgn.IntegerLike,state:drgn.Object)->bool
Return whether the given NUMA node has the given state.
Parameters
• node -- NUMA node number.
• state -- enumnode_states (e.g., N_NORMAL_MEMORY)
Per-CPU
The drgn.helpers.linux.percpu module provides helpers for working with per-CPU allocations from ‐
include/linux/percpu.h and per-CPU counters from include/linux/percpu_counter.h.
drgn.helpers.linux.percpu.per_cpu_ptr(ptr:drgn.Object,cpu:drgn.IntegerLike)->drgn.Object
Return the per-CPU pointer for a given CPU.
>>> prog["init_net"].loopback_dev.pcpu_refcnt
(int *)0x2c980
>>> per_cpu_ptr(prog["init_net"].loopback_dev.pcpu_refcnt, 7)
*(int *)0xffff925e3ddec980 = 4
Parameters
• ptr -- Per-CPU pointer, i.e., type__percpu*. For global variables, it's usually easier
to use per_cpu().
• cpu -- CPU number.
Returnstype* object.
drgn.helpers.linux.percpu.per_cpu(var:drgn.Object,cpu:drgn.IntegerLike)->drgn.Object
Return the per-CPU variable for a given CPU.
>>> print(repr(prog["runqueues"]))
Object(prog, 'struct rq', address=0x278c0)
>>> per_cpu(prog["runqueues"], 6).curr.comm
(char [16])"python3"
Parameters
• var -- Per-CPU variable, i.e., type__percpu (not a pointer; use per_cpu_ptr() for that).
• cpu -- CPU number.
Returnstype object.
drgn.helpers.linux.percpu.percpu_counter_sum(fbc:drgn.Object)->int
Return the sum of a per-CPU counter.
Parametersfbc -- structpercpu_counter*ProcessIDS
The drgn.helpers.linux.pid module provides helpers for looking up process IDs and processes.
drgn.helpers.linux.pid.pid_task(pid:drgn.Object,pid_type:drgn.IntegerLike)->drgn.Object
Return the structtask_struct* containing the given structpid* of the given type.
Parameters
• pid -- structpid*
• pid_type -- enumpid_typeReturnsstructtask_struct*drgn.helpers.linux.pid.find_pid(ns:drgn.Object|drgn.Program,pid:drgn.IntegerLike)->drgn.Object
Return the structpid* for the given PID number.
Parametersns -- structpid_namespace*. Defaults to the initial PID namespace if given a Program or
omitted.
Returnsstructpid*drgn.helpers.linux.pid.for_each_pid(ns:drgn.Object|drgn.Program)->Iterator[drgn.Object]
Iterate over all PIDs in a namespace.
Parametersns -- structpid_namespace*. Defaults to the initial PID namespace if given a Program or
omitted.
Returns
Iterator of structpid* objects.
drgn.helpers.linux.pid.find_task(ns:drgn.Object|drgn.Program,pid:drgn.IntegerLike)->drgn.Object
Return the task with the given PID.
Parametersns -- structpid_namespace*. Defaults to the initial PID namespace if given a Program or
omitted.
Returnsstructtask_struct*drgn.helpers.linux.pid.for_each_task(ns:drgn.Object|drgn.Program)->Iterator[drgn.Object]
Iterate over all of the tasks visible in a namespace.
Parametersns -- structpid_namespace*. Defaults to the initial PID namespace if given a Program or
omitted.
Returns
Iterator of structtask_struct* objects.
Priority-SortedLists
The drgn.helpers.linux.plist module provides helpers for working with descending-priority-sorted
doubly-linked lists (structplist_head and structplist_node) from include/linux/plist.h.
drgn.helpers.linux.plist.plist_head_empty(head:drgn.Object)->bool
Return whether a plist is empty.
Parametershead -- structplist_head*drgn.helpers.linux.plist.plist_node_empty(node:drgn.Object)->bool
Return whether a plist node is empty (i.e., not on a list).
Parametersnode -- structplist_node*drgn.helpers.linux.plist.plist_first_entry(head:drgn.Object,type:Union[str,drgn.Type],member:str)->drgn.Object
Return the first (highest priority) entry in a plist.
The list is assumed to be non-empty.
Parameters
• head -- structplist_head*
• type -- Entry type.
• member -- Name of list node member in entry type.
Returnstype*drgn.helpers.linux.plist.plist_last_entry(head:drgn.Object,type:Union[str,drgn.Type],member:str)->drgn.Object
Return the last (lowest priority) entry in a plist.
The list is assumed to be non-empty.
Parameters
• head -- structplist_head*
• type -- Entry type.
• member -- Name of list node member in entry type.
Returnstype*drgn.helpers.linux.plist.plist_for_each(head:drgn.Object)->Iterator[drgn.Object]
Iterate over all of the nodes in a plist.
Parametershead -- structplist_head*Returns
Iterator of structplist_node* objects.
drgn.helpers.linux.plist.plist_for_each_entry(type:Union[str,drgn.Type],head:drgn.Object,member:str)->Iterator[drgn.Object]
Iterate over all of the entries in a plist.
Parameters
• type -- Entry type.
• head -- structplist_head*
• member -- Name of plist node member in entry type.
Returns
Iterator of type* objects.
LogBuffer
The drgn.helpers.linux.printk module provides helpers for reading the Linux kernel log buffer.
classdrgn.helpers.linux.printk.PrintkRecord
Bases: NamedTuple
Kernel log record.
text:bytes
Message text.
facility:intsyslog(3)facility.level:int
Log level.
seq:int
Sequence number.
timestamp:int
Timestamp in nanoseconds.
caller_tid:Optional[int]
Thread ID of thread that logged this record, if available.
This is available if the message was logged from task context and if the kernel saves the
printk() caller ID.
As of Linux 5.10, the kernel always saves the caller ID. From Linux 5.1 through 5.9, it is
saved only if the kernel was compiled with CONFIG_PRINTK_CALLER. Before that, it is never
saved.
caller_cpu:Optional[int]
Processor ID of CPU that logged this record, if available.
This is available only if the message was logged when not in task context (e.g., in an
interrupt handler) and if the kernel saves the printk() caller ID.
See caller_tid for when the kernel saves the caller ID.
continuation:bool
Whether this record is a continuation of a previous record.
context:Dict[bytes,bytes]
Additional metadata for the message.
See the /dev/kmsgdocumentation for an explanation of the keys and values.
drgn.helpers.linux.printk.get_printk_records(prog:drgn.Program)->List[PrintkRecord]
Get a list of records in the kernel log buffer.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.printk.get_dmesg(prog:drgn.Program)->bytes
Get the contents of the kernel log buffer formatted like dmesg(1).Ifyoujustwanttoprintthelogbuffer,useprint_dmesg().Theformatofeachlineis:
[ timestamp] message
Ifyouneedtoformatthelogbufferdifferently,useget_printk_records()andformatityourself.Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
drgn.helpers.linux.printk.print_dmesg(prog:drgn.Program,*,file:Optional[SupportsWrite[str]]=None)->None
Print the contents of the kernel log buffer.
>>> print_dmesg()
[ 0.000000] Linux version 6.8.0-vmtest28.1default (drgn@drgn) (x86_64-linux-gcc (GCC) 12.2.0, GNU ld (GNU Binutils) 2.39) #1 SMP PREEMPT_DYNAMIC Mon Mar 11 06:38:45 UTC 2024
[ 0.000000] Command line: rootfstype=9p rootflags=trans=virtio,cache=loose,msize=1048576 ro console=ttyS0,115200 panic=-1 crashkernel=256M init=/tmp/drgn-vmtest-rudzppeo/init
[ 0.000000] BIOS-provided physical RAM map:
...
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• file -- File to print to. Defaults to sys.stdout.
RadixTrees
The drgn.helpers.linux.radixtree module provides helpers for working with radix trees from ‐
include/linux/radix-tree.h.
SEEALSO:XArrays, which were introduced in Linux 4.20 as a replacement for radix trees.
drgn.helpers.linux.radixtree.radix_tree_lookup(root:drgn.Object,index:drgn.IntegerLike)->drgn.Object
Look up the entry at a given index in a radix tree.
Parameters
• root -- structradix_tree_root*
• index -- Entry index.
Returnsvoid* found entry, or NULL if not found.
drgn.helpers.linux.radixtree.radix_tree_for_each(root:drgn.Object)->Iterator[Tuple[int,drgn.Object]]
Iterate over all of the entries in a radix tree.
Parametersroot -- structradix_tree_root*Returns
Iterator of (index, void*) tuples.
Red-BlackTrees
The drgn.helpers.linux.rbtree module provides helpers for working with red-black trees from ‐
include/linux/rbtree.h.
drgn.helpers.linux.rbtree.RB_EMPTY_ROOT(root:drgn.Object)->bool
Return whether a red-black tree is empty.
Parametersnode -- structrb_root*drgn.helpers.linux.rbtree.RB_EMPTY_NODE(node:drgn.Object)->bool
Return whether a red-black tree node is empty, i.e., not inserted in a tree.
Parametersnode -- structrb_node*drgn.helpers.linux.rbtree.rb_parent(node:drgn.Object)->drgn.Object
Return the parent node of a red-black tree node.
Parametersnode -- structrb_node*Returnsstructrb_node*drgn.helpers.linux.rbtree.rb_first(root:drgn.Object)->drgn.Object
Return the first node (in sort order) in a red-black tree, or NULL if the tree is empty.
Parametersroot -- structrb_root*Returnsstructrb_node*drgn.helpers.linux.rbtree.rb_last(root:drgn.Object)->drgn.Object
Return the last node (in sort order) in a red-black tree, or NULL if the tree is empty.
Parametersroot -- structrb_root*Returnsstructrb_node*drgn.helpers.linux.rbtree.rb_next(node:drgn.Object)->drgn.Object
Return the next node (in sort order) after a red-black node, or NULL if the node is the last node
in the tree or is empty.
Parametersnode -- structrb_node*Returnsstructrb_node*drgn.helpers.linux.rbtree.rb_prev(node:drgn.Object)->drgn.Object
Return the previous node (in sort order) before a red-black node, or NULL if the node is the first
node in the tree or is empty.
Parametersnode -- structrb_node*Returnsstructrb_node*drgn.helpers.linux.rbtree.rbtree_inorder_for_each(root:drgn.Object)->Iterator[drgn.Object]
Iterate over all of the nodes in a red-black tree, in sort order.
Parametersroot -- structrb_root*Returns
Iterator of structrb_node* objects.
drgn.helpers.linux.rbtree.rbtree_inorder_for_each_entry(type:Union[str,drgn.Type],root:drgn.Object,member:str)->Iterator[drgn.Object]
Iterate over all of the entries in a red-black tree in sorted order.
Parameters
• type -- Entry type.
• root -- structrb_root*
• member -- Name of structrb_node member in entry type.
Returns
Iterator of type* objects.
drgn.helpers.linux.rbtree.rb_find(type:Union[str,drgn.Type],root:drgn.Object,member:str,key:KeyType,cmp:Callable[[KeyType,drgn.Object],int])->drgn.Object
Find an entry in a red-black tree given a key and a comparator function.
Note that this function does not have an analogue in the Linux kernel source code, as tree
searches are all open-coded.
Parameters
• type -- Entry type.
• root -- structrb_root*
• member -- Name of structrb_node member in entry type.
• key -- Key to find.
• cmp -- Callback taking key and entry that returns < 0 if the key is less than the entry,
> 0 if the key is greater than the entry, and 0 if the key matches the entry.
Returnstype* found entry, or NULL if not found.
drgn.helpers.linux.rbtree.validate_rbtree(type:Union[str,drgn.Type],root:drgn.Object,member:str,cmp:Callable[[drgn.Object,drgn.Object],int],allow_equal:bool)->None
Validate a red-black tree.
This checks that:
1. The tree is a valid binary search tree ordered according to cmp.
2. If allow_equal is False, there are no nodes that compare equal according to cmp.
3. The rb_parent pointers are consistent.
4. The red-black tree requirements are satisfied: the root node is black, no red node has a red
child, and every path from any node to any of its descendant leaf nodes goes through the same
number of black nodes.
Parameters
• type -- Entry type.
• root -- structrb_root*
• member -- Name of structrb_node member in entry type.
• cmp -- Callback taking two type* entry objects that returns < 0 if the first entry is
less than the second entry, > 0 if the first entry is greater than the second entry, and
0 if they are equal.
• allow_equal -- Whether the tree may contain entries that compare equal to each other.
RaisesValidationError -- if the tree is invalid
drgn.helpers.linux.rbtree.validate_rbtree_inorder_for_each_entry(type:Union[str,drgn.Type],root:drgn.Object,member:str,cmp:Callable[[drgn.Object,drgn.Object],int],allow_equal:bool)->Iterator[drgn.Object]
Like rbtree_inorder_for_each_entry(), but validates the red-black tree like validate_rbtree()
while iterating.
Parameters
• type -- Entry type.
• root -- structrb_root*
• member -- Name of structrb_node member in entry type.
• cmp -- Callback taking two type* entry objects that returns < 0 if the first entry is
less than the second entry, > 0 if the first entry is greater than the second entry, and
0 if they are equal.
• allow_equal -- Whether the tree may contain entries that compare equal to each other.
RaisesValidationError -- if the tree is invalid
CPUScheduler
The drgn.helpers.linux.sched module provides helpers for working with the Linux CPU scheduler.
drgn.helpers.linux.sched.task_cpu(task:drgn.Object)->int
Return the CPU number that the given task last ran on.
Parameterstask -- structtask_struct*drgn.helpers.linux.sched.task_thread_info(task:drgn.Object)->drgn.Object
Return the thread information structure for a task.
Parameterstask -- structtask_struct*Returnsstructthread_info*drgn.helpers.linux.sched.cpu_curr(prog:drgn.Program,cpu:drgn.IntegerLike)->drgn.Object
Return the task running on the given CPU.
>>> cpu_curr(7).comm
(char [16])"python3"
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• cpu -- CPU number.
Returnsstructtask_struct*drgn.helpers.linux.sched.idle_task(prog:drgn.Program,cpu:drgn.IntegerLike)->drgn.Object
Return the idle thread (PID 0, a.k.a swapper) for the given CPU.
>>> idle_task(1).comm
(char [16])"swapper/1"
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• cpu -- CPU number.
Returnsstructtask_struct*drgn.helpers.linux.sched.task_state_to_char(task:drgn.Object)->str
Get the state of the task as a character (e.g., 'R' for running). See ps(1) for a description of
the process state codes.
Parameterstask -- structtask_struct*drgn.helpers.linux.sched.loadavg(prog:drgn.Program)->Tuple[float,float,float]
Return system load averaged over 1, 5 and 15 minutes as tuple of three float values.
>>> loadavg()
(2.34, 0.442, 1.33)
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
SlabAllocator
The drgn.helpers.linux.slab module provides helpers for working with the Linux slab allocator.
WARNING:
Beware of slab merging when using these helpers. See slab_cache_is_merged().
drgn.helpers.linux.slab.slab_cache_is_merged(slab_cache:drgn.Object)->bool
Return whether a slab cache has been merged with any other slab caches.
Unless configured otherwise, the kernel may merge slab caches of similar sizes together. See the ‐
SLUBusersguide and slab_merge/slab_nomerge in the kernelparametersdocumentation.
This can cause confusion, as only the name of the first cache will be found, and objects of
different types will be mixed in the same slab cache.
For example, suppose that we have two types, structfoo and structbar, which have the same size
but are otherwise unrelated. If the kernel creates a slab cache named foo for structfoo, then
another slab cache named bar for structbar, then slab cache foo will be reused instead of
creating another cache for bar. So the following will fail:
find_slab_cache("bar")
And the following will also return structbar* objects errantly casted to structfoo*:
slab_cache_for_each_allocated_object(find_slab_cache("foo"), "struct foo")
Unfortunately, these issues are difficult to work around generally, so one must be prepared to
handle them on a case-by-case basis (e.g., by looking up the slab cache by its variable name and
by checking that members of the structure make sense for the expected type).
Parametersslab_cache -- structkmem_cache*drgn.helpers.linux.slab.get_slab_cache_aliases(prog:drgn.Program)->Dict[str,str]
Return a dict mapping slab cache name to the cache it was merged with.
The SLAB and SLUB subsystems can merge caches with similar settings and object sizes, as described
in the documentation of slab_cache_is_merged(). In some cases, the information about which caches
were merged is lost, but in other cases, we can reconstruct the info. This function reconstructs
the mapping, but requires that the kernel is configured with CONFIG_SLUB and CONFIG_SYSFS.
The returned dict maps from original cache name, to merged cache name. You can use this mapping to
discover the correct cache to lookup via find_slab_cache(). The dict contains an entry only for
caches which were merged into a cache of a different name.
>>> cache_to_merged = get_slab_cache_aliases()
>>> cache_to_merged["dnotify_struct"]
'avc_xperms_data'
>>> "avc_xperms_data" in cache_to_merged
False
>>> find_slab_cache("dnotify_struct") is None
True
>>> find_slab_cache("avc_xperms_data") is None
False
Warning
This function will only work on kernels which are built with CONFIG_SLUB and CONFIG_SYSFS
enabled.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Mapping of slab cache name to final merged name
RaisesLookupError -- If the helper fails because the debugged kernel doesn't have the required
configuration
drgn.helpers.linux.slab.for_each_slab_cache(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all slab caches.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structkmem_cache* objects.
drgn.helpers.linux.slab.find_slab_cache(prog:drgn.Program,name:Union[str,bytes])->Optional[‐drgn.Object]
Return the slab cache with the given name.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• name -- Slab cache name.
Returnsstructkmem_cache*drgn.helpers.linux.slab.print_slab_caches(prog:drgn.Program)->None
Print the name and structkmem_cache* value of all slab caches.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
classdrgn.helpers.linux.slab.SlabCorruptionError
Bases: drgn.helpers.ValidationError
Error raised when a corruption is encountered in a slab allocator data structure.
classdrgn.helpers.linux.slab.SlabFreelistCycleError
Bases: SlabCorruptionError
Error raised when a cycle is encountered in a slab allocator freelist.
drgn.helpers.linux.slab.slab_cache_for_each_allocated_object(slab_cache:drgn.Object,type:Union[str,drgn.Type])->Iterator[drgn.Object]
Iterate over all allocated objects in a given slab cache.
Only the SLUB and SLAB allocators are supported; SLOB does not store enough information to
identify objects in a slab cache.
>>> dentry_cache = find_slab_cache("dentry")
>>> next(slab_cache_for_each_allocated_object(dentry_cache, "struct dentry"))
*(struct dentry *)0xffff905e41404000 = {
...
}
Parameters
• slab_cache -- structkmem_cache*
• type -- Type of object in the slab cache.
Returns
Iterator of type* objects.
drgn.helpers.linux.slab.slab_object_info(prog:drgn.Program,addr:drgn.IntegerLike)->Optional[‐SlabObjectInfo]
Get information about an address if it is in a slab object.
>>> ptr = find_task(1).comm.address_of_()
>>> info = slab_object_info(ptr)
>>> info
SlabObjectInfo(slab_cache=Object(prog, 'struct kmem_cache *', address=0xffffdb93c0045e18), slab=Object(prog, 'struct slab *', value=0xffffdb93c0045e00), address=0xffffa2bf81178000, allocated=True)
Note that SlabObjectInfo.address is the start address of the object, which may be less than addr
if addr points to a member inside of the object:
>>> ptr.value_() - info.address
1496
>>> offsetof(prog.type("struct task_struct"), "comm")
1496
Note that SLOB does not store enough information to identify slab objects, so if the kernel is
configured to use SLOB, this will always return None.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*ReturnsSlabObjectInfo if addr is in a slab object, or None if not.
classdrgn.helpers.linux.slab.SlabObjectInfo
Information about an object in the slab allocator.
slab_cache:drgn.Objectstructkmem_cache* that the slab object is from.
slab:drgn.Object
Slab containing the slab object.
Since Linux v5.17, this is a structslab*. Before that, it is a structpage*.
address:int
Address of the slab object.
allocated:Optional[bool]True if the object is allocated, False if it is free, or None if not known because the slab
cache is corrupted.
drgn.helpers.linux.slab.find_containing_slab_cache(prog:drgn.Program,addr:drgn.IntegerLike)->drgn.Object
Get the slab cache that an address was allocated from, if any.
Note that SLOB does not store enough information to identify objects in a slab cache, so if the
kernel is configured to use SLOB, this will always return NULL.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• addr -- void*Returnsstructkmem_cache* containing addr, or NULL if addr is not from a slab cache.
StackDepot
The drgn.helpers.linux.stackdepot module provides helpers for working with the stack trace storage from ‐
include/linux/stackdepot.h used by KASAN and other kernel debugging tools.
drgn.helpers.linux.stackdepot.stack_depot_fetch(handle:drgn.Object)->Optional[drgn.StackTrace]
Returns a stack trace for the given stack handle.
Parametershandle -- depot_stack_handle_tReturns
The stack trace, or None if not available.
TrafficControl(TC)
The drgn.helpers.linux.tc module provides helpers for working with the Linux kernel Traffic Control (TC)
subsystem.
drgn.helpers.linux.tc.qdisc_lookup(dev:drgn.Object,major:drgn.IntegerLike)->drgn.Object
Get a Qdisc from a device and a major handle number. It is worth noting that conventionally
handles are hexadecimal, e.g. 10: in a tc command means major handle 0x10.
Parameters
• dev -- structnet_device*
• major -- Qdisc major handle number.
ReturnsstructQdisc* (NULL if not found)
TCP
The drgn.helpers.linux.tcp module provides helpers for working with the TCP protocol in the Linux kernel.
drgn.helpers.linux.tcp.sk_tcpstate(sk:drgn.Object)->drgn.Object
Return the TCP protocol state of a socket.
Parameterssk -- structsock*Returns
TCP state enum value.
Users
The drgn.helpers.linux.user module provides helpers for working with users in the Linux kernel.
drgn.helpers.linux.user.find_user(prog:drgn.Program,uid:Union[drgn.Object,drgn.IntegerLike])->drgn.Object
Return the user structure with the given UID.
Parameters
• prog -- Program, which maybeomittedtousethedefaultprogramargument.
• uid -- kuid_t object or integer.
Returnsstructuser_struct* (NULL if not found)
drgn.helpers.linux.user.for_each_user(prog:drgn.Program)->Iterator[drgn.Object]
Iterate over all users in the system.
Parametersprog -- Program, which maybeomittedtousethedefaultprogramargument.
Returns
Iterator of structuser_struct* objects.
WaitQueues
The drgn.helpers.linux.wait module provides helpers for working with wait queues (wait_queue_head_t and
wait_queue_entry_t) from include/linux/wait.h.
NOTE:
Since Linux 4.13, entries in a wait queue have type wait_queue_entry_t. Before that, the type was
named wait_queue_t.
drgn.helpers.linux.wait.waitqueue_active(wq:drgn.Object)->bool
Return whether a wait queue has any waiters.
Parameterswq -- wait_queue_head_t*drgn.helpers.linux.wait.waitqueue_for_each_entry(wq:drgn.Object)->Iterator[drgn.Object]
Iterate over all entries in a wait queue.
Parameterswq -- wait_queue_head_t*Returns
Iterator of wait_queue_entry_t* or wait_queue_t* objects depending on the kernel version.
drgn.helpers.linux.wait.waitqueue_for_each_task(wq:drgn.Object)->Iterator[drgn.Object]
Iterate over all tasks waiting on a wait queue.
WARNING:
This comes from wait_queue_entry_t::private, which usually stores a task. However, some wait
queue entries store a different pointer type, in which case this will return garbage.
Parameterswq -- wait_queue_head_t*Returns
Iterator of structtask_struct* objects.
XArrays
The drgn.helpers.linux.xarray module provides helpers for working with the XArray data structure from ‐
include/linux/xarray.h.
NOTE:
XArrays were introduced in Linux 4.20 as a replacement for radixtrees. To make it easier to work
with data structures that were changed from a radix tree to an XArray (like structaddress_space::i_pages), drgn treats XArrays and radix trees interchangeably in some cases.
Specifically, xa_load() is equivalent to radix_tree_lookup(), and xa_for_each() is equivalent to
radix_tree_for_each(), except that the radix tree helpers assume advanced=False. (Therefore, xa_load()
and xa_for_each() also accept a structradix_tree_root*, and radix_tree_lookup() and
radix_tree_for_each() also accept a structxarray*.)
drgn.helpers.linux.xarray.xa_load(xa:drgn.Object,index:drgn.IntegerLike,*,advanced:bool=False)->drgn.Object
Look up the entry at a given index in an XArray.
>>> entry = xa_load(inode.i_mapping.i_pages.address_of_(), 2)
>>> cast("struct page *", entry)
*(struct page *)0xffffed6980306f40 = {
...
}
Parameters
• xa -- structxarray*
• index -- Entry index.
• advanced -- Whether to return nodes only visible to the XArray advanced API. If False,
zero entries (see xa_is_zero()) will be returned as NULL.
Returnsvoid* found entry, or NULL if not found.
drgn.helpers.linux.xarray.xa_for_each(xa:drgn.Object,*,advanced:bool=False)->Iterator[Tuple[int,drgn.Object]]
Iterate over all of the entries in an XArray.
>>> for index, entry in xa_for_each(inode.i_mapping.i_pages.address_of_()):
... print(index, entry)
...
0 (void *)0xffffed6980356140
1 (void *)0xffffed6980306f80
2 (void *)0xffffed6980306f40
3 (void *)0xffffed6980355b40
Parameters
• xa -- structxarray*
• advanced -- Whether to return nodes only visible to the XArray advanced API. If False,
zero entries (see xa_is_zero()) will be skipped.
Returns
Iterator of (index, void*) tuples.
drgn.helpers.linux.xarray.xa_is_value(entry:drgn.Object)->bool
Return whether an XArray entry is a value.
See xa_to_value().
Parametersentry -- void*drgn.helpers.linux.xarray.xa_to_value(entry:drgn.Object)->drgn.Object
Return the value in an XArray entry.
In addition to pointers, XArrays can store integers between 0 and LONG_MAX. If xa_is_value()
returns True, use this to get the stored integer.
>>> entry = xa_load(xa, 9)
>>> entry
(void *)0xc9
>>> xa_is_value(entry)
True
>>> xa_to_value(entry)
(unsigned long)100
Parametersentry -- void*Returnsunsignedlongdrgn.helpers.linux.xarray.xa_is_zero(entry:drgn.Object)->bool
Return whether an XArray entry is a "zero" entry.
A zero entry is an entry that was reserved but is not present. These are only visible to the
XArray advanced API, so they are only returned by xa_load() and xa_for_each() when advanced=True.
>>> entry = xa_load(xa, 10, advanced=True)
>>> entry
(void *)0x406
>>> xa_is_zero(entry)
True
>>> xa_load(xa, 10)
(void *)0
Parametersentry -- void*SupportMatrixArchitectures
Some features in drgn require architecture-specific support. The current status of this support is:
┌──────────────┬────────────────────────┬──────────────────┬────────────────────────┐
│ Architecture │ Linux Kernel Modules │ Stack Traces [2] │ Virtual Address │
│ │ [1] │ │ Translation [3] │
├──────────────┼────────────────────────┼──────────────────┼────────────────────────┤
│ x86-64 │ ✓ │ ✓ │ ✓ │
├──────────────┼────────────────────────┼──────────────────┼────────────────────────┤
│ AArch64 │ ✓ │ ✓ │ ✓ │
├──────────────┼────────────────────────┼──────────────────┼────────────────────────┤
│ s390x │ ✓ │ ✓ │ ✓ │
├──────────────┼────────────────────────┼──────────────────┼────────────────────────┤
│ ppc64 │ ✓ │ ✓ │ ✓ │
├──────────────┼────────────────────────┼──────────────────┼────────────────────────┤
│ i386 │ ✓ │ │ │
├──────────────┼────────────────────────┼──────────────────┼────────────────────────┤
│ Arm │ ✓ │ ✓ │ ✓ │
├──────────────┼────────────────────────┼──────────────────┼────────────────────────┤
│ RISC-V │ ✓ │ │ │
└──────────────┴────────────────────────┴──────────────────┴────────────────────────┘
Key
[1] Support for loading debugging symbols for Linux kernel modules.
[2] Support for capturing stack traces (drgn.Program.stack_trace(), drgn.Thread.stack_trace()).
[3] Support for translating virtual addresses, which is required for reading from vmalloc/vmap and
module memory in Linux kernel vmcores and for various helpers in drgn.helpers.linux.mm.
The listed architectures are recognized in drgn.Architecture. Other architectures are represented by
drgn.Architecture.UNKNOWN. Features not mentioned above should work on any architecture, listed or
not.
Cross-Debugging
drgn can debug architectures different from the host. For example, you can debug an AArch64 (kernel or
userspace) core dump from an x86-64 machine.
LinuxKernelVersions
drgn officially supports the current mainline, stable, and longterm kernel releases from kernel.org.
(There may be some delay before a new mainline version is fully supported.) End-of-life versions are
supported until it becomes too difficult to do so. The kernel versions currently fully supported are:
• 6.0-6.13
• 5.10-5.19
• 5.4
• 4.19
• 4.14
• 4.9
Other versions are not tested. They'll probably mostly work, but support is best-effort.
KernelConfiguration
drgn supports debugging kernels with various configurations:
• SMP and !SMP.
• Preemptible and non-preemptible.
• SLUB, SLAB, and SLOB allocators.
drgn requires a kernel configured with CONFIG_PROC_KCORE=y for live kernel debugging.
CaseStudies
These are writeups of real-world problems solved with drgn.
Recoveringadm-cryptEncryptionKey
Author: Omar Sandoval
Date: January 11th, 2024
dm-crypt is the Linux kernel's transparent disk encryption subsystem. I recently had to recover the
master key for an encrypted disk where the passphrase was no longer known, but the dm-crypt device was
still open. Normally, the key is stored in kernel space and cannot be accessed by user space. However,
with drgn, we can traverse kernel data structures to recover the key. This is a great example of how to
jump between kernel code and drgn to navigate a subsystem.
WARNING:
The dm-crypt master key is obviously very sensitive information that shouldn't be exposed carelessly.
As a disclaimer for anyone concerned about the security implications: everything is working as
intended here. Debugging the live kernel with drgn requires root, and root has many other ways to
access sensitive information (loading kernel modules, triggering a kernel core dump, etc.). Solutions
like inlineencryption and kernel_lockdown(7)canbeusedfordefenseindepthifnecessary.Setup
For this writeup, I'm going to set up dm-crypt in a virtual machine running Linux 6.7.
# uname -r
6.7.0
# cryptsetup luksFormat /dev/vdb
WARNING!
========
This will overwrite data on /dev/vdb irrevocably.
Are you sure? (Type 'yes' in capital letters): YES
Enter passphrase for /dev/vdb: hello
Verify passphrase: hello
# cryptsetup open /dev/vdb mycrypt
Enter passphrase for /dev/vdb: hello
The default configuration is AES in XTS mode with a 512-bit key:
# cryptsetup status mycrypt
/dev/mapper/mycrypt is active.
type: LUKS2
cipher: aes-xts-plain64
keysize: 512 bits
key location: keyring
device: /dev/vdb
sector size: 512
offset: 32768 sectors
size: 33521664 sectors
mode: read/write
The new device is dm-0:
# realpath /dev/mapper/mycrypt
/dev/dm-0
GettingfromDeviceMappertotheCryptoAPI
The dm-cryptdocumentation tells us that "Device-mapper is infrastructure in the Linux kernel that
provides a generic way to create virtual layers of block devices. Device-mapper crypt target provides
transparent encryption of block devices using the kernel crypto API."
Our first goal is therefore to get to whatever context is used by the crypto API, which likely includes
the encryption key. To do that, we're going to have to navigate through the device mapper code.
To start, let's find the virtual disk for our dm-crypt target in drgn using the for_each_disk() and
disk_name() helpers:
>>> for disk in for_each_disk():
... if disk_name(disk) == b"dm-0":
... print(disk)
... break
...
*(struct gendisk *)0xffffa3b9421b2c00 = {
...
}
structgendisk has a function table, fops, with callbacks to the disk driver. Specifically, the
submit_bio callback intercepts disk reads and writes:
>>> disk.fops.submit_bio
(void (*)(struct bio *))dm_submit_bio+0x0 = 0xffffffffc05761e0
Let's take a look at dm_submit_bio():
static void dm_submit_bio(struct bio *bio)
{
struct mapped_device *md = bio->bi_bdev->bd_disk->private_data;
int srcu_idx;
struct dm_table *map;
map = dm_get_live_table(md, &srcu_idx);
...
dm_split_and_process_bio(md, map, bio);
...
}
So the disk's private data is a structmapped_device. Let's get it in drgn:
>>> md = cast("struct mapped_device *", disk.private_data)
dm_get_live_table() gets the device mapper table:
struct dm_table *dm_get_live_table(struct mapped_device *md,
int *srcu_idx) __acquires(md->io_barrier)
{
*srcu_idx = srcu_read_lock(&md->io_barrier);
return srcu_dereference(md->map, &md->io_barrier);
}
SRCU is a synchronization mechanism which we can blithely ignore:
>>> map = cast("struct dm_table *", md.map)
dm_submit_bio() then calls dm_split_and_process_bio(), which calls __split_and_process_bio():
static blk_status_t __split_and_process_bio(struct clone_info *ci)
{
struct bio *clone;
struct dm_target *ti;
unsigned int len;
ti = dm_table_find_target(ci->map, ci->sector);
...
__map_bio(clone);
}
dm_table_find_target() finds the appropriate device mapper target in a table:
struct dm_target *dm_table_find_target(struct dm_table *t, sector_t sector)
{
...
return &t->targets[(KEYS_PER_NODE * n) + k];
}
Our simple case only has one target:
>>> map.num_targets
(unsigned int)1
>>> ti = map.targets
__split_and_process_bio() then calls __map_bio():
static void __map_bio(struct bio *clone)
{
struct dm_target_io *tio = clone_to_tio(clone);
struct dm_target *ti = tio->ti;
struct dm_io *io = tio->io;
struct mapped_device *md = io->md;
int r;
...
if (likely(ti->type->map == linear_map))
r = linear_map(ti, clone);
else if (ti->type->map == stripe_map)
r = stripe_map(ti, clone);
else
r = ti->type->map(ti, clone);
...
}
So we need to look at another callback:
>>> ti.type.map
(dm_map_fn)crypt_map+0x0 = 0xffffffffc08a03f0
crypt_map() is part of dm-crypt, so we've finally made it out of generic device mapper:
static int crypt_map(struct dm_target *ti, struct bio *bio)
{
struct dm_crypt_io *io;
struct crypt_config *cc = ti->private;
...
And we have the dm-crypt configuration:
>>> cc = cast("struct crypt_config *", ti.private)
Dumping it out reveals some crypto API context!
>>> cc
*(struct crypt_config *)0xffffa3b9421b2400 = {
...
.cipher_tfm = (union <anonymous>){
.tfms = (struct crypto_skcipher **)0xffffa3b9438667c0,
...
},
.tfms_count = (unsigned int)1,
...
}
>>> tfm = cc.cipher_tfm.tfms[0]
DescendingDowntheCryptoAPI
The Linux kernel crypto API is very generic and is implemented with a lot of runtime polymorphism. Our
next goal is to traverse through the crypto API data structures to find the key.
The crypto API refers to cryptographic ciphers as "transformations". Transformations can be combined and
nested in various ways. The tfm variable we found is a "transformationobject", which is an instance of a
transformation:
>>> tfm
*(struct crypto_skcipher *)0xffffa3b948218c00 = {
.reqsize = (unsigned int)160,
.base = (struct crypto_tfm){
.refcnt = (refcount_t){
.refs = (atomic_t){
.counter = (int)1,
},
},
.crt_flags = (u32)0,
.node = (int)-1,
.exit = (void (*)(struct crypto_tfm *))crypto_skcipher_exit_tfm+0x0 = 0xffffffffb77d2600,
.__crt_alg = (struct crypto_alg *)0xffffa3b943dab448,
.__crt_ctx = (void *[]){},
},
}
>>> tfm.base.__crt_alg
*(struct crypto_alg *)0xffffa3b943dab448 = {
...
.cra_name = (char [128])"xts(aes)",
...
}
This is an skcipher, or a symmetric key cipher. It is using the xts(aes) algorithm as expected. __crt_ctx
is an opaque context, which is promising if we can figure out how to interpret it. The exit callback
looks like a cleanup function. That seems like a good way for us to figure out how __crt_ctx is used.
Here are crypto_skcipher_exit_tfm() and the crypto_skcipher_alg() and crypto_skcipher_tfm() getters it
uses:
static void crypto_skcipher_exit_tfm(struct crypto_tfm *tfm)
{
struct crypto_skcipher *skcipher = __crypto_skcipher_cast(tfm);
struct skcipher_alg *alg = crypto_skcipher_alg(skcipher);
alg->exit(skcipher);
}
static inline struct skcipher_alg *crypto_skcipher_alg(
struct crypto_skcipher *tfm)
{
return container_of(crypto_skcipher_tfm(tfm)->__crt_alg,
struct skcipher_alg, base);
}
static inline struct crypto_tfm *crypto_skcipher_tfm(
struct crypto_skcipher *tfm)
{
return &tfm->base;
}
We can emulate the getters in drgn to find the underlying implementation:
>>> def crypto_skcipher_alg(tfm):
... return container_of(tfm.base.__crt_alg, "struct skcipher_alg", "base")
...
>>> crypto_skcipher_alg(tfm).exit
(void (*)(struct crypto_skcipher *))simd_skcipher_exit+0x0 = 0xffffffffc058b1f0
My machine supports the AES-NI x86 extension. The kernel cannot use SIMD instructions like AES-NI in some
contexts, so it has an extralayerofindirection to go through an asynchronous daemon when necessary.
This involves a couple of wrapper transformation objects. simd_skcipher_exit() shows us how to unwrap the
first one:
static void simd_skcipher_exit(struct crypto_skcipher *tfm)
{
struct simd_skcipher_ctx *ctx = crypto_skcipher_ctx(tfm);
cryptd_free_skcipher(ctx->cryptd_tfm);
}
We just need one more getter in drgn, crypto_skcipher_ctx():
>>> def crypto_skcipher_ctx(tfm):
... return cast("void *", tfm.base.__crt_ctx)
...
>>> simd_ctx = cast("struct simd_skcipher_ctx *", crypto_skcipher_ctx(tfm))
>>> cryptd_tfm = simd_ctx.cryptd_tfm
>>> cryptd_tfm
*(struct cryptd_skcipher *)0xffffa3b94b5e4cc0 = {
.base = (struct crypto_skcipher){
.reqsize = (unsigned int)80,
.base = (struct crypto_tfm){
.refcnt = (refcount_t){
.refs = (atomic_t){
.counter = (int)1,
},
},
.crt_flags = (u32)0,
.node = (int)-1,
.exit = (void (*)(struct crypto_tfm *))crypto_skcipher_exit_tfm+0x0 = 0xffffffffb77d2600,
.__crt_alg = (struct crypto_alg *)0xffffa3b9421b2848,
.__crt_ctx = (void *[]){},
},
},
}
We saw crypto_skcipher_exit_tfm() earlier, so we know where to look next:
>>> crypto_skcipher_alg(cryptd_tfm.base).exit
(void (*)(struct crypto_skcipher *))cryptd_skcipher_exit_tfm+0x0 = 0xffffffffc04d6210
cryptd_skcipher_exit_tfm() shows us how to unwrap this transformation object:
static void cryptd_skcipher_exit_tfm(struct crypto_skcipher *tfm)
{
struct cryptd_skcipher_ctx *ctx = crypto_skcipher_ctx(tfm);
crypto_free_skcipher(ctx->child);
}
Now we can get the actual cipher transformation object:
>>> cryptd_ctx = cast("struct cryptd_skcipher_ctx *", crypto_skcipher_ctx(cryptd_tfm.base))
>>> child_tfm = cryptd_ctx.child
>>> child_tfm
*(struct crypto_skcipher *)0xffffa3b945dc4000 = {
.reqsize = (unsigned int)0,
.base = (struct crypto_tfm){
.refcnt = (refcount_t){
.refs = (atomic_t){
.counter = (int)1,
},
},
.crt_flags = (u32)0,
.node = (int)-1,
.exit = (void (*)(struct crypto_tfm *))0x0,
.__crt_alg = (struct crypto_alg *)0xffffffffc05e7d80,
.__crt_ctx = (void *[]){},
},
}
This one doesn't have an exit callback, so let's look at the algorithm:
>>> crypto_skcipher_alg(child_tfm)
*(struct skcipher_alg *)0xffffffffc05e7d40 = {
.setkey = (int (*)(struct crypto_skcipher *, const u8 *, unsigned int))xts_aesni_setkey+0x0 = 0xffffffffc059efb0,
...
}
xts_aesni_setkey() is very enlightening:
static int xts_aesni_setkey(struct crypto_skcipher *tfm, const u8 *key,
unsigned int keylen)
{
struct aesni_xts_ctx *ctx = aes_xts_ctx(tfm);
int err;
err = xts_verify_key(tfm, key, keylen);
if (err)
return err;
keylen /= 2;
/* first half of xts-key is for crypt */
err = aes_set_key_common(&ctx->crypt_ctx, key, keylen);
if (err)
return err;
/* second half of xts-key is for tweak */
return aes_set_key_common(&ctx->tweak_ctx, key + keylen, keylen);
}
XTS splits the provided key into two keys: one for data and one for a "tweak". They are stored in
ctx->crypt_ctx and ctx->tweak_ctx, respectively.
To reach ctx, we need one more getter, aes_xts_ctx():
static inline struct aesni_xts_ctx *aes_xts_ctx(struct crypto_skcipher *tfm)
{
return aes_align_addr(crypto_skcipher_ctx(tfm));
}
Which uses aes_align_addr():
#define AESNI_ALIGN 16
static inline void *aes_align_addr(void *addr)
{
if (crypto_tfm_ctx_alignment() >= AESNI_ALIGN)
return addr;
return PTR_ALIGN(addr, AESNI_ALIGN);
}
Implementing that in drgn gets us the key material!
>>> def aes_xts_ctx(tfm):
... AESNI_ALIGN = 16
... mask = AESNI_ALIGN - 1
... ctx = cast("unsigned long", crypto_skcipher_ctx(tfm))
... return cast("struct aesni_xts_ctx *", (ctx + mask) & ~mask)
...
>>> xts_ctx = aes_xts_ctx(cryptd_ctx.child)
>>> xts_ctx
*(struct aesni_xts_ctx *)0xffffa3b945dc4030 = {
.tweak_ctx = (struct crypto_aes_ctx){
.key_enc = (u32 [60]){
4053857025, 2535432618, 3497512106, 429624542,
190965574, 620881567, 2728140233, 1574816406,
1642869364, 4143158238, 646209396, 1059050410,
2124513770, 1537238901, 4181490364, 2766254122,
2225457809, 1918261583, 1423050299, 1808651665,
18645611, 1522328862, 2743115682, 123809672, 1080042880,
842431695, 1726249716, 220835685, 3602512678,
2349145656, 797278618, 686075410, 2304003180,
3143774371, 3716565591, 3501188402, 2797609477,
717569085, 88128935, 765727669, 1552680193, 3891148194,
979927029, 3938949831, 554080963, 197371646, 243473241,
589760748, 2460666129, 1967455411, 1328317254,
2783648129, 669994703, 741140529, 581956456, 25754500,
3453357406, 3096637933, 4156453547, 1381329706,
},
.key_dec = (u32 [60]){
3453357406, 3096637933, 4156453547, 1381329706,
1691590497, 1611861415, 2033812690, 3535200077,
1503779265, 1400120959, 2713205381, 402136101,
2278736107, 79729350, 422218101, 2878299039, 3072023845,
181796798, 4073463034, 3057657504, 2722800653,
2199015981, 501881779, 2997211882, 893456792,
3184435867, 4162446148, 1150040666, 3430456984,
559478304, 2667071902, 2941241689, 2504843709,
2291118851, 1171735007, 3163937054, 4210330224,
3978324152, 3214983102, 834109639, 179351664, 499339966,
3445158620, 4181891265, 4283462504, 399827656,
1384175366, 2383888249, 3581021031, 393470670,
3499860066, 874146333, 3319833674, 3901002144,
1163146702, 3700942975, 4053857025, 2535432618,
3497512106, 429624542,
},
.key_length = (u32)32,
},
.crypt_ctx = (struct crypto_aes_ctx){
.key_enc = (u32 [60]){
91118336, 1683438947, 280915620, 1674463119, 3416529787,
95371281, 156839573, 539041733, 2748950209, 3348011938,
3610309894, 3036590729, 1176448220, 1135635661,
1256800856, 1791516061, 4259008143, 978703661,
3982827563, 1503367842, 2366333926, 3468365611,
2219986291, 4003074286, 3589535297, 4020642668,
46334791, 1532531173, 3026313791, 2061167892,
4270366823, 269660297, 1916354478, 2644450498,
2673614725, 3288632928, 2828270575, 3528005371,
750892700, 1020462613, 735205841, 3058517267, 689003158,
3977630966, 4257919917, 797156694, 54662090, 1066472927,
3047676072, 65707451, 721143597, 3354268635, 1004719636,
341928770, 388200584, 682782039, 4002672596, 3984159343,
3347232066, 7120537,
},
.key_dec = (u32 [60]){
4002672596, 3984159343, 3347232066, 7120537, 2275767381,
3582792214, 728749911, 250810445, 2145441323,
3415330885, 1171250799, 717236012, 72947820, 1378379331,
4276274497, 631031578, 3286455042, 3027306094,
2388528682, 1863317827, 1027747936, 1450278447,
2898961154, 3682468443, 2929020077, 2006078828,
976160836, 3780245353, 3002856629, 1798524495,
4206615853, 2008326489, 523503039, 3641121217,
1304255784, 3682533165, 3583917429, 3653810938,
2441646946, 2366602356, 2101484483, 3325238398,
2495235305, 2529403397, 1276800912, 206997391,
1212164504, 478670614, 2260253082, 3144746941,
1384732823, 41543404, 2858181789, 1078781983,
1142337047, 1422378638, 91118336, 1683438947, 280915620,
1674463119,
},
.key_length = (u32)32,
},
}
ExtractingtheAESKey
Since we have a 512-bit key, XTS uses two 256-bit AES keys. You'll notice that the key_enc fields above
are much larger than that. This is because AES expands the key into a number of "round keys" using a "keyschedule". Luckily, the first few round keys are copied directly from the original key.
With that information, we can finally recover the original key:
>>> def aes_key_from_ctx(ctx):
... words = ctx.key_enc.value_()[:ctx.key_length / 4]
... return b"".join(word.to_bytes(4, "little") for word in words)
...
>>> aes_key_from_ctx(xts_ctx.crypt_ctx).hex()
'005b6e05633d5764a46ebe108f47ce637b1ba4cb1140af05952e5909c51f2120'
>>> aes_key_from_ctx(xts_ctx.tweak_ctx).hex()
'01f3a0f1aaa11f97aacc77d0de8c9b1946e7610b9fe60125c91d9ca296cadd5d'
Which we can double check with cryptsetup:
# cryptsetup luksDump --dump-master-key /dev/vdb
WARNING!
========
The header dump with volume key is sensitive information
that allows access to encrypted partition without a passphrase.
This dump should be stored encrypted in a safe place.
Are you sure? (Type 'yes' in capital letters): YES
Enter passphrase for /dev/vdb: hello
LUKS header information for /dev/vdb
Cipher name: aes
Cipher mode: xts-plain64
Payload offset: 32768
UUID: b43cba2c-532b-4491-bbb9-763b55bd7f03
MK bits: 512
MK dump: 00 5b 6e 05 63 3d 57 64 a4 6e be 10 8f 47 ce 63
7b 1b a4 cb 11 40 af 05 95 2e 59 09 c5 1f 21 20
01 f3 a0 f1 aa a1 1f 97 aa cc 77 d0 de 8c 9b 19
46 e7 61 0b 9f e6 01 25 c9 1d 9c a2 96 ca dd 5d
Conclusion
Before this, I had almost no knowledge of device mapper or crypto API internals. drgn makes it easy to
explore the kernel and learn how it works.
Note that different system configurations will have different representations in the crypto API. For
example, different ciphers modes will obviously have different transformations. Even the lack of AES-NI
with the same cipher mode results in different transformation objects.
I converted this case study to the dm_crypt_key.py script in drgn's contrib directory. It could be
extended to cover other ciphers in the future.
UsingStackTraceVariablestoFindaKyberBug
Author: Omar Sandoval
Date: June 9th, 2021
Jakub Kicinski reported a crash in the KyberI/Oscheduler when he was testing Linux 5.12. He captured a
core dump and asked me to debug it. This is a quick writeup of that investigation.
First, we can get the task that crashed:
>>> task = per_cpu(prog["runqueues"], prog["crashing_cpu"]).curr
Then, we can get its stack trace:
>>> trace = prog.stack_trace(task)
>>> trace
#0 queued_spin_lock_slowpath (../kernel/locking/qspinlock.c:471:3)
#1 queued_spin_lock (../include/asm-generic/qspinlock.h:85:2)
#2 do_raw_spin_lock (../kernel/locking/spinlock_debug.c:113:2)
#3 spin_lock (../include/linux/spinlock.h:354:2)
#4 kyber_bio_merge (../block/kyber-iosched.c:573:2)
#5 blk_mq_sched_bio_merge (../block/blk-mq-sched.h:37:9)
#6 blk_mq_submit_bio (../block/blk-mq.c:2182:6)
#7 __submit_bio_noacct_mq (../block/blk-core.c:1015:9)
#8 submit_bio_noacct (../block/blk-core.c:1048:10)
#9 submit_bio (../block/blk-core.c:1125:9)
#10 submit_stripe_bio (../fs/btrfs/volumes.c:6553:2)
#11 btrfs_map_bio (../fs/btrfs/volumes.c:6642:3)
#12 btrfs_submit_data_bio (../fs/btrfs/inode.c:2440:8)
#13 submit_one_bio (../fs/btrfs/extent_io.c:175:9)
#14 submit_extent_page (../fs/btrfs/extent_io.c:3229:10)
#15 __extent_writepage_io (../fs/btrfs/extent_io.c:3793:9)
#16 __extent_writepage (../fs/btrfs/extent_io.c:3872:8)
#17 extent_write_cache_pages (../fs/btrfs/extent_io.c:4514:10)
#18 extent_writepages (../fs/btrfs/extent_io.c:4635:8)
#19 do_writepages (../mm/page-writeback.c:2352:10)
#20 __writeback_single_inode (../fs/fs-writeback.c:1467:8)
#21 writeback_sb_inodes (../fs/fs-writeback.c:1732:3)
#22 __writeback_inodes_wb (../fs/fs-writeback.c:1801:12)
#23 wb_writeback (../fs/fs-writeback.c:1907:15)
#24 wb_check_background_flush (../fs/fs-writeback.c:1975:10)
#25 wb_do_writeback (../fs/fs-writeback.c:2063:11)
#26 wb_workfn (../fs/fs-writeback.c:2091:20)
#27 process_one_work (../kernel/workqueue.c:2275:2)
#28 worker_thread (../kernel/workqueue.c:2421:4)
#29 kthread (../kernel/kthread.c:292:9)
#30 ret_from_fork+0x1f/0x2a (../arch/x86/entry/entry_64.S:294)
It looks like kyber_bio_merge() tried to lock an invalid spinlock. For reference, this is the source code
of kyber_bio_merge():
static bool kyber_bio_merge(struct blk_mq_hw_ctx *hctx, struct bio *bio,
unsigned int nr_segs)
{
struct kyber_hctx_data *khd = hctx->sched_data;
struct blk_mq_ctx *ctx = blk_mq_get_ctx(hctx->queue);
struct kyber_ctx_queue *kcq = &khd->kcqs[ctx->index_hw[hctx->type]];
unsigned int sched_domain = kyber_sched_domain(bio->bi_opf);
struct list_head *rq_list = &kcq->rq_list[sched_domain];
bool merged;
spin_lock(&kcq->lock);
merged = blk_bio_list_merge(hctx->queue, rq_list, bio, nr_segs);
spin_unlock(&kcq->lock);
return merged;
}
When printed, the kcq structure containing the spinlock indeed looks like garbage (omitted for brevity).
A crash course on the Linux kernel block layer: for each block device, there is a "software queue"
(structblk_mq_ctx*ctx) for each CPU and a "hardware queue" (structblk_mq_hw_ctx*hctx) for each I/O
queue provided by the device. Each hardware queue has one or more software queues assigned to it. Kyber
keeps additional data per hardware queue (structkyber_hctx_data*khd) and per software queue (structkyber_ctx_queue*kcq).
Let's try to figure out where the bad kcq came from. It should be an element of the khd->kcqs array (khd
is optimized out, but we can recover it from hctx->sched_data):
>>> trace[4]["khd"]
(struct kyber_hctx_data *)<absent>
>>> hctx = trace[4]["hctx"]
>>> khd = cast("struct kyber_hctx_data *", hctx.sched_data)
>>> trace[4]["kcq"] - khd.kcqs
(ptrdiff_t)1
>>> hctx.nr_ctx
(unsigned short)1
So the kcq is for the second software queue, but the hardware queue is only supposed to have one software
queue. Let's see which CPU was assigned to the hardware queue:
>>> hctx.ctxs[0].cpu
(unsigned int)6
Here's the problem: we're not running on CPU 6, we're running on CPU 19:
>>> prog["crashing_cpu"]
(int)19
And CPU 19 is assigned to a different hardware queue that actually does have two software queues:
>>> ctx = per_cpu_ptr(hctx.queue.queue_ctx, 19)
>>> other_hctx = ctx.hctxs[hctx.type]
>>> other_hctx == hctx
False
>>> other_hctx.nr_ctx
(unsigned short)2
The bug is that the caller gets the hctx for the current CPU, then kyber_bio_merge() gets the ctx for the
current CPU, and if the thread is migrated to another CPU in between, they won't match. The fix is to get
a consistent view of the hctx and ctx. The commit that fixes this is here.
GettingDebuggingSymbols
Most Linux distributions don't install debugging symbols for installed packages by default. This page
documents how to install debugging symbols on common distributions. If drgn prints an error like:
$ sudo drgn
could not get debugging information for:
kernel (could not find vmlinux for 5.14.14-200.fc34.x86_64)
...
Then you need to install debugging symbols.
Fedora
Fedora makes it very easy to install debugging symbols with the DNFdebuginfo-installplugin, which is
installed by default. Simply run sudodnfdebuginfo-install$package:
$ sudo dnf debuginfo-install python3
To find out what package owns a binary, use rpm-qf:
$ rpm -qf $(which python3)
python3-3.9.7-1.fc34.x86_64
To install symbols for the running kernel:
$ sudo dnf debuginfo-install kernel-$(uname -r)
Also see the Fedoradocumentation.
Debian
Debian requires you to manually add the debugging symbol repositories:
$ sudo tee /etc/apt/sources.list.d/debug.list << EOF
deb http://deb.debian.org/debian-debug/ $(lsb_release -cs)-debug main
deb http://deb.debian.org/debian-debug/ $(lsb_release -cs)-proposed-updates-debug main
EOF
$ sudo apt update
Then, debugging symbol packages can be installed with sudoaptinstall. Some debugging symbol packages
are named with a -dbg suffix:
$ sudo apt install python3-dbg
And some are named with a -dbgsym suffix:
$ sudo apt install coreutils-dbgsym
You can use the find-dbgsym-packages command from the debian-goodies package to find the correct name:
$ sudo apt install debian-goodies
$ find-dbgsym-packages $(which python3)
libc6-dbg libexpat1-dbgsym python3.9-dbg zlib1g-dbgsym
$ find-dbgsym-packages $(which cat)
coreutils-dbgsym libc6-dbg
To install symbols for the running kernel:
$ sudo apt install linux-image-$(uname -r)-dbg
Also see the Debiandocumentation.
Ubuntu
On Ubuntu, you must install the debugging symbol archive signing key and manually add the debugging
symbol repositories:
$ sudo apt update
$ sudo apt install ubuntu-dbgsym-keyring
$ sudo tee /etc/apt/sources.list.d/debug.list << EOF
deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse
deb http://ddebs.ubuntu.com $(lsb_release -cs)-updates main restricted universe multiverse
deb http://ddebs.ubuntu.com $(lsb_release -cs)-proposed main restricted universe multiverse
EOF
$ sudo apt update
Like Debian, some debugging symbol packages are named with a -dbg suffix and some are named with a
-dbgsym suffix:
$ sudo apt install python3-dbg
$ sudo apt install coreutils-dbgsym
You can use the find-dbgsym-packages command from the debian-goodies package to find the correct name:
$ sudo apt install debian-goodies
$ find-dbgsym-packages $(which python3)
libc6-dbg libexpat1-dbgsym python3.9-dbg zlib1g-dbgsym
$ find-dbgsym-packages $(which cat)
coreutils-dbgsym libc6-dbg
To install symbols for the running kernel:
$ sudo apt install linux-image-$(uname -r)-dbgsym
Also see the Ubuntudocumentation.
ArchLinux
Arch Linux unfortunately does not make debugging symbols available. Packages must be manually rebuilt
with debugging symbols enabled. See the ArchWiki and the featurerequest.
OracleLinux
Oracle Linux provides documentation on using installing the necessary debugging symbols. See the
documentation for OracleLinux9 and OracleLinux8.
ReleaseHighlights
These are highlights of each release of drgn focusing on a few exciting items from the full releasenotes.
0.0.30(ReleasedDecember18th,2024)
These are some of the highlights of drgn 0.0.30. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
This release is relatively small, as most development effort has been focused on the upcoming moduleAPI,
which is expected to land in the next release.
SymbolIndexandKallsyms
Stephen Brennan continued his efforts towards makingitpossibletodebugtheLinuxkernelwithoutfullDWARFdebugginginformation. The next step in this release was adding new helpers for looking up symbols
from kallsyms: load_vmlinux_kallsyms() and load_module_kallsyms(). These are built on top of a new,
generic API for fast symbol lookups: drgn.SymbolIndex.
NewPython3.13REPL
Python 3.13 added a vastly improved REPL with multiline editing, colorized output, interactive help, and
more. drgn now makes use of this REPL when it is available.
StackTracingThroughInterruptHandlers
drgn had a longstanding bug where stack traces would stop at an interrupt handler frame. This release
fixes that (as long as the kernel is configured to use the ORC unwinder).
Linux6.13Support
No drgn changes were required to support Linux 6.13 as of rc3.
0.0.28&0.0.29(ReleasedOctober7th&8th,2024)
These are some of the highlights of drgn 0.0.28. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
drgn 0.0.29 was released shortly after 0.0.28 with a single bug fix for the
drgn.helpers.experimental.kmodify module. See the releasenotes.
CallingArbitraryFunctionsintheRunningKernel
This release added call_function(), which calls a function in the running kernel. This is the first ever
feature in drgn that allows modifying the state of the kernel. Its primary use cases are experimentation
in development environments and mitigating kernel bugs in production. For example, this recent lost
wake-up bug could be mitigated with something like:
from drgn.helpers.experimental.kmodify import call_function
for task in for_each_task():
for frame in stack_trace(task):
if frame.name == "perf_event_free_task":
call_function("wake_up_process", task)
break
Note that this feature is currently experimental, only supported on x86-64, and may have a different API
in the future.
There is a blogpost about how this feature works.
WritingtoKernelMemory
In a similar vein, drgn can now write to kernel memory, either via an address (with write_memory()):
>>> import os
>>> from drgn.helpers.experimental.kmodify import write_memory
>>> os.uname().sysname
'Linux'
>>> write_memory(prog["init_uts_ns"].name.sysname.address_, b"Lol\\0")
>>> os.uname().sysname
'Lol'
or an object (with write_object()):
>>> from drgn.helpers.experimental.kmodify import write_object
>>> os.system("uptime -p")
up 12 minutes
>>> write_object(prog["init_time_ns"].offsets.boottime.tv_sec, 1000000000)
>>> os.system("uptime -p")
up 3 decades, 1 year, 37 weeks, 1 hour, 59 minutes
This feature is also experimental. It uses the same underlying mechanism as call_function().
MoreCOperators
This release added a couple of new functions corresponding to operators in C. The alignof() function is
analogous to the _Alignof() operator in C:
>>> alignof(prog.type("long long"))
8
The implicit_convert() function implements implicit conversions in C, like when assigning a variable,
passing an argument to a function call, or returning a value:
>>> implicit_convert("unsigned int", Object(prog, "float", 2.0))
(unsigned int)2
>>> implicit_convert("void *", Object(prog, "int", 0))
Traceback (most recent call last):
...
TypeError: cannot convert 'int' to incompatible type 'void *'
KernelModuleHelpers
Stephen Brennan contributed several helpers for working with Linux kernel modules.
for_each_module() iterates over loaded modules:
>>> for module in for_each_module():
... print(module.name.string_().decode())
...
overlay
vhost_net
vhost
...
find_module() finds the module with a given name:
>>> module = find_module("overlay")
>>> module
*(struct module *)0xffffffffc23dae00 = {
...
}
module_address_regions() and module_percpu_region() return all of the memory regions associated with a
module, and address_to_module() finds the module containing an address:
>>> for start, size in module_address_regions(module):
... print(hex(start), size)
...
0xffffffffc23be000 102400
0xffffffffc23d8000 65536
0xffffffffc23e9000 73728
0xffffffffc2385000 4096
0x0 0
0x0 0
0x0 0
>>> address_to_module(0xffffffffc23bf000) == module
True
ThreadNames
Ryan Wilson added the name attribute to drgn.Thread. This provides a consistent interface for getting the
name of a thread regardless of whether you're debugging the kernel or a userspace program.
(Unfortunately, userspace core dumps on Linux don't save the name of any threads other than the main
thread.)
Full32-BitArmSupport
This release added support for virtual address translation and stack traces on 32-bit Arm. This is the
state of architecture support in this release:
┌──────────────┬──────────────────────┬──────────────┬────────────────────────┐
│ Architecture │ Linux Kernel Modules │ Stack Traces │ Virtual Address │
│ │ │ │ Translation │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ x86-64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ AArch64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ s390x │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ ppc64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ i386 │ ✓ │ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ Arm │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ RISC-V │ ✓ │ │ │
└──────────────┴──────────────────────┴──────────────┴────────────────────────┘
Note that there are known Linux kernel issues with debugging 32-bit Arm, both live and in kdump. Please
reach out to the linux-debuggers@vger.kernel.org mailing list if these affect you.
AArch64ands390xVirtualAddressTranslationFixes
As of Linux 6.9, the default AArch64 kernel configuration enables 52-bit virtual addresses and fallsback
to a smaller virtual address size if the hardware does not support 52 bits. This required updates to
drgn that were missed in v0.0.27.
As of Linux 6.10, on s390x, virtual addresses in the direct mapping are nolonger equal to physical
addresses. This also required updates to drgn that were missed in v0.0.27.
Linux6.11and6.12Support
A change in Linux 6.12 broke tools/fsrefs.py. This error from visit_uprobes() is fixed in this release:
TypeError: cannot convert 'struct list_head' to bool
No other changes were required to support Linux 6.11 and 6.12.
0.0.27(ReleasedJuly1st,2024)
These are some of the highlights of drgn 0.0.27. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
FindingtheTypeMemberatanOffset
This release added member_at_offset(), which returns the name of the member at an offset in a type:
>>> prog.type('struct list_head')
struct list_head {
struct list_head *next;
struct list_head *prev;
}
>>> member_at_offset(prog.type('struct list_head'), 0)
'next'
>>> member_at_offset(prog.type('struct list_head'), 8)
'prev'
It also handles more complicated cases, like nested structures, arrays, unions, and padding.
It is particularly useful in combination with identify_address() or slab_object_info():
>>> identify_address(0xffff984fc7cc6708)
'slab object: fuse_inode+0x188'
>>> member_at_offset(prog.type("struct fuse_inode"), 0x188)
'inode.i_data.i_pages.xa_head'
(Note that in some cases, the slab cache name isn't identical to the type name. Slab merging also
complicates this; see slab_cache_is_merged(). In those cases, this trick requires some extra effort.)
IdentifyingMemory
This release added print_annotated_memory(), which dumps a range of memory, annotating values that can be
identified:
>>> print_annotated_memory(0xffff985163300698, 64)
ADDRESS VALUE
ffff985163300698: ffff984f415456a0 [slab object: mnt_cache+0x20]
ffff9851633006a0: ffff984f587b7840 [slab object: dentry+0x0]
ffff9851633006a8: ffff984f404bfa38 [slab object: inode_cache+0x0]
ffff9851633006b0: ffffffff8b4890c0 [object symbol: signalfd_fops+0x0]
ffff9851633006b8: 0000000000000000
ffff9851633006c0: ffff984f9307c078 [slab object: lsm_file_cache+0x0]
ffff9851633006c8: ffff984f8afe3980 [slab object: kmalloc-8+0x0]
ffff9851633006d0: ffff984f414730f0 [slab object: ep_head+0x0]
(This is similar to print_annotated_stack() but for arbitrary memory ranges.)
identify_address() (used by print_annotated_memory() and print_annotated_stack()) can now also identify
vmap addresses and vmap kernel stacks:
>>> print(identify_address(0xffffffffc0536540))
vmap: 0xffffffffc0536000-0xffffffffc0545000 caller load_module+0x811
>>> print(identify_address(0xffffbb88e2283f58))
vmap stack: 2220305 (python3) +0x3f58
ConfigurableTypeandObjectFinders
drgn already supported registering custom callbacks that could satisfy type and object lookups:
Program.add_type_finder() and Program.add_object_finder(). However, there was no way to disable
previously added callbacks or control the order in which they are called. This release adds an interface
for doing so.
Program.registered_object_finders() returns the set of registered object finders:
>>> prog.registered_object_finders()
{'dwarf', 'linux'}
Program.enabled_object_finders() returns the list of enabled object finders in the order that they are
called:
>>> prog.enabled_object_finders()
['linux', 'dwarf']
Program.register_object_finder() registers and optionally enables a finder:
>>> def my_object_finder(prog, name, flags, filename):
... ...
...
>>> prog.register_object_finder("foo", my_object_finder)
>>> prog.registered_object_finders()
{'foo', 'dwarf', 'linux'}
>>> prog.enabled_object_finders()
['linux', 'dwarf']
>>> def my_object_finder2(prog, name, flags, filename):
... ...
...
>>> prog.register_object_finder("bar", my_object_finder2, enable_index=0)
>>> prog.registered_object_finders()
{'foo', 'dwarf', 'bar', 'linux'}
>>> prog.enabled_object_finders()
['bar', 'linux', 'dwarf']
Program.set_enabled_object_finders() sets the list of enabled finders. This can enable, disable, and
reorder finders.
>>> prog.set_enabled_object_finders(['dwarf', 'foo'])
>>> prog.enabled_object_finders()
['dwarf', 'foo']
Type finders have equivalent methods: Program.registered_type_finders(), Program.enabled_type_finders(),
Program.register_type_finder(), and Program.set_enabled_type_finders().
The old interface is now deprecated.
SymbolFinders
Previously, symbols could only be looked up using the ELF symbol table. In this release, Stephen Brennan
added support for custom symbol finders: Program.registered_symbol_finders(),
Program.enabled_symbol_finders(), Program.register_symbol_finder(), and
Program.set_enabled_symbol_finders().
contribDirectory
A few new scripts were added to the contrib directory, and others were updated.
contrib/search_kernel_memory.py
This script does a brute force search through kernel RAM for a given byte string and prints all of the
addresses where it is found. It's useful as a last resort for finding what is referencing an object, for
example.
>>> folio = stack_trace(task)[5]["folio"]
>>> search_memory(prog, folio.value_().to_bytes(8, "little"))
0xffff8882f67539e8 vmap stack: 2232297 (io_thread) +0x39e8
0xffff8882f6753a18 vmap stack: 2232297 (io_thread) +0x3a18
0xffff8882f6753a60 vmap stack: 2232297 (io_thread) +0x3a60
0xffff8882f6753ac8 vmap stack: 2232297 (io_thread) +0x3ac8
0xffff888300405530 slab object: kmalloc-16+0x0
0xffff8883b8c6ca38
contrib/gcore.py
This script creates a core dump of a live process. This works even if the process is stuck in D state
(Uninterruptible Sleep), which normally causes debuggers attempting to attach to the process to hang,
too. The generated core dump can be debugged with GDB, LLDB, or even drgn.
By default, gcore.py reads the task's memory through /proc/$pid/mem. However, if mmap_lock/mmap_sem is
stuck, then this will also hang. If the --no-procfs flag is used, drgn bypasses this, too, by reading the
process's page tables and reading the memory directly. This has a couple of big downsides: paged out
memory will be skipped, and it's a lot slower. But if the task is badly stuck in memory management,
--no-procfs is a great escape hatch.
gcore.py can also extract userspace core dumps out of a kernel core dump, but note that makedumpfile(8)
is normally configured to filter out userspace memory.
contrib/negdentdelete.pyNegativedentries are a cache of failed filename lookups. They can take up a lot of memory, and it's
difficult to get rid of them by normal means. Stephen Brennan contributed a script that can be used to
get rid of negative dentries in a directory.
contrib/btrfs_tree.py
This script contains work-in-progress helpers for reading Btrfs metadata. It was added in drgn 0.0.23,
but this release expanded and improved it. It will likely be adapted into proper helpers in a future
release.
This script was used to investigate a bug, culminating in Linux kernel commit 9d274c19a71b("btrfs:fixcrashonracingfsyncandsize-extendingwriteintoprealloc").
contrib/bpf_inspect.py
Leon Hwang made many improvements to this script, including adding more detailed information, new
commands, and updating it for recent kernels.
Linux6.9and6.10Support
Changes in Linux 6.9 and 6.10 broke a few drgn helpers. Here are some errors you might see with older
versions of drgn that are fixed in this release.
From stack_depot_fetch():
AttributeError: 'union handle_parts' has no member 'pool_index'
From for_each_disk():
AttributeError: 'struct block_device' has no member 'bd_partno'
Additionally, slab_cache_for_each_allocated_object(), slab_object_info(), and
find_containing_slab_cache() may fail to find anything.
0.0.26(ReleasedMarch11th,2024)
These are some of the highlights of drgn 0.0.26. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
MiscellaneousHelpers
This release added several new Linux kernel helpers with no particular theme:
• print_dmesg(), a shortcut for printing the kernel log buffer.
• idr_for_each_entry(), a shortcut for iterating over an IDR and casting its entries to a specific type.
• stack_depot_fetch() for getting stack traces from the storage used by KASAN and other kernel debugging
tools. This was contributed by Peter Collingbourne.
• plist_head_empty(), plist_node_empty(), plist_first_entry(), plist_last_entry(), plist_for_each(), and
plist_for_each_entry(), helpers for working with the kernel's priority-sorted lists.
fsrefs.pyTool
The fsrefs.py tool was added to the tools directory. It prints information about everything that is
referencing a file or filesystem. This is similar to fuser(1)andlsof(8),butitcanfindmoresinceithasaccesstokernelinternals.
$ ./tools/fsrefs.py --inode /dev/urandom
pid 1349 (bluetoothd) fd 16 (struct file *)0xffff8881458cf000
pid 1368 (udisksd) fd 15 (struct file *)0xffff888145c13100
...
$ ./tools/fsrefs.py --super-block /run
mount /run (struct mount *)0xffff8881015cc140
pid 1 (systemd) fd 256 (struct file *)0xffff8881012f3d00 /run/initctl
pid 1 (systemd) fd 380 (struct file *)0xffff88810bf88800 /run/dmeventd-server
pid 1 (systemd) fd 385 (struct file *)0xffff88810bf88f00 /run/dmeventd-client
mount /run (mount namespace 4026532545) (struct mount *)0xffff8881474028c0
pid 2135770 (systemd-journal) vma 0x7f7d94f2a000-0x7f7d94f2b000 (struct file *)0xffff88813925bf00 /run/systemd/journal/kernel-seqnum
pid 2135770 (systemd-journal) vma 0x7f7d94f2b000-0x7f7d94f2c000 (struct file *)0xffff88813925a100 /run/systemd/journal/seqnum
...
fsrefs.pycurrentlychecks:
• File descriptors
• Task working directories
• Task root directories
• Memory mappings
• Filesystem mounts
• binfmt_misc
• loop(4)devices
• Swap files
• uprobes
It will be extended to check more as the need arises, so feel free to report anything it missed.
(Note that as opposed to the contrib directory, scripts in the tools directory are regularly maintained
and tested.)
DWARFPackageFiles
drgn now supports split DWARF package (.dwp) files. These are generated by the dwp and llvm-dwp tools.
Linux6.8Support
Linux 6.8 changed some filesystem internals in a way that broke a couple of drgn helpers. Here are some
errors you might see with older versions of drgn that are fixed in this release.
From path_lookup() or for_each_mount() (fixed by Johannes Thumshirn):
AttributeError: 'struct mnt_namespace' has no member 'list'
From path_lookup():
AttributeError: 'struct dentry' has no member 'd_subdirs'
Python3.13Support
Python 3.13, currently in alpha, removed or changed some private APIs (_PyDict_GetItemIdWithError(),
_PyDict_SetItemId(), and _PyLong_AsByteArray()) that drgn depended on, which caused build failures. This
was fixed by using public APIs instead.
0.0.25(ReleasedDecember1st,2023)
These are some of the highlights of drgn 0.0.25. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
OmittingtheprogArgument
As a usability improvement, prog can now be omitted from most function calls. For example, instead of
find_task(prog,1234), you can now simply write find_task(1234). Additionally, instead of
prog.stack_trace(1234), you can now write stack_trace(1234). (The old way will continue to be supported.)
Most CLI users don't need to worry about how this works, but library users may want to understand the
DefaultProgram.
It's tricky balancing interactive convenience and sensible APIs for scripting, but we think this is a
nice improvement overall!
RunningWithoutroot
drgn debugs the live Linux kernel via /proc/kcore, which can only be accessed by the root user (or a user
with the CAP_SYS_RAWIO capability, to be precise). However, it's not necessary (or ideal) for the rest of
drgn to run as root.
Now when drgn is run against the live kernel as an unprivileged user, it will attempt to open /proc/kcore
via sudo(8).Therestofdrgnwillthenrunwithoutextraprivileges.Inotherwords,inordertodebugthelivekernel,allyouneedtodoisinstalldebuggingsymbolsandrun:
$ drgn
ThisfeaturewascontributedbyStephenBrennan.MapleTreeHelpersMapletrees were introduced in Linux 6.1, initially to store virtual memory areas (VMAs). This release
adds a couple of helpers for working with them.
mtree_load() looks up an entry in a maple tree:
>>> mtree_load(task.mm.mm_mt.address_of_(), 0x55d65cfaa000)
(void *)0xffff97ad82bfc930
mt_for_each() iterates over a maple tree:
>>> for first_index, last_index, entry in mt_for_each(task.mm.mm_mt.address_of_()):
... print(hex(first_index), hex(last_index), entry)
...
0x55d65cfaa000 0x55d65cfaafff (void *)0xffff97ad82bfc930
0x55d65cfab000 0x55d65cfabfff (void *)0xffff97ad82bfc0a8
0x55d65cfac000 0x55d65cfacfff (void *)0xffff97ad82bfc000
0x55d65cfad000 0x55d65cfadfff (void *)0xffff97ad82bfcb28
...
VMAHelpers
This release also adds higher-level helpers specifically for VMAs.
vma_find() looks up a VMA by address:
>>> vma_find(task.mm, 0x55d65cfaa000)
*(struct vm_area_struct *)0xffff97ad82bfc930 = {
...
}
>>> vma_find(task.mm, 0x55d65cfa9fff)
(struct vm_area_struct *)0
for_each_vma() iterates over every VMA in an address space:
>>> for vma in for_each_vma(task.mm):
... print(vma)
...
*(struct vm_area_struct *)0xffff97ad82bfc930 = {
...
}
*(struct vm_area_struct *)0xffff97ad82bfc0a8 = {
...
}
...
These helpers also handle older kernels without maple trees.
WaitQueueHelpers
Wait queues are a fundamental data structure and synchronization mechanism in the Linux kernel. Imran
Khan contributed a few helpers for working with them.
waitqueue_active() returns whether a wait queue has any waiters:
>>> wq
*(wait_queue_head_t *)0xffff8da80d618e18 = {
.lock = (spinlock_t){
.rlock = (struct raw_spinlock){
.raw_lock = (arch_spinlock_t){
.val = (atomic_t){
.counter = (int)0,
},
.locked = (u8)0,
.pending = (u8)0,
.locked_pending = (u16)0,
.tail = (u16)0,
},
},
},
.head = (struct list_head){
.next = (struct list_head *)0xffffae44e3007ce8,
.prev = (struct list_head *)0xffffae44e3007ce8,
},
}
>>> waitqueue_active(wq)
True
waitqueue_for_each_entry() iterates over each entry in a wait queue:
>>> for entry in waitqueue_for_each_entry(wq):
... print(entry)
...
*(wait_queue_entry_t *)0xffffae44e3007cd0 = {
.flags = (unsigned int)0,
.private = (void *)0xffff8da7863ec000,
.func = (wait_queue_func_t)woken_wake_function+0x0 = 0xffffffffa8181010,
.entry = (struct list_head){
.next = (struct list_head *)0xffff8da80d618e20,
.prev = (struct list_head *)0xffff8da80d618e20,
},
}
waitqueue_for_each_task() iterates over each task waiting on a wait queue (although note that this does
not work for some special wait queues that don't store tasks):
>>> for task in waitqueue_for_each_task(wq):
... print(task.pid, task.comm)
...
(pid_t)294708 (char [16])"zsh"
ppc64RadixMMUSupport
Sourabh Jain contributed ppc64 radix MMU virtual address translation support. This is the state of
architecture support in this release:
drgn0.0.25ArchitectureSupport
┌──────────────┬──────────────────────┬──────────────┬────────────────────────┐
│ Architecture │ Linux Kernel Modules │ Stack Traces │ Virtual Address │
│ │ │ │ Translation │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ x86-64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ AArch64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ s390x │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ ppc64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ i386 │ ✓ │ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ Arm │ ✓ │ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ RISC-V │ ✓ │ │ │
└──────────────┴──────────────────────┴──────────────┴────────────────────────┘
0.0.24(ReleasedSeptember8th,2023)
These are some of the highlights of drgn 0.0.24. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
LinkedListLengthHelper
This release added list_count_nodes(), which returns the length of a Linux kernel linked list:
>>> list_count_nodes(prog["workqueues"].address_of_())
29
NetworkingHelpers
This release added a couple of Linux kernel networking helpers requested by Jakub Kicinski.
netdev_priv() returns the private data of a network device:
>>> dev = netdev_get_by_name(prog, "wlp0s20f3")
>>> netdev_priv(dev)
(void *)0xffff9419c9dec9c0
>>> netdev_priv(dev, "struct ieee80211_sub_if_data")
*(struct ieee80211_sub_if_data *)0xffff9419c9dec9c0 = {
...
}
skb_shinfo() returns the shared info for a socket buffer.
C++Lookups
This release added support for a few C++ features.
SimpleTypeSpecifiers
Unlike C, C++ allows referring to class, struct, union, and enum types without their respective keywords.
For example:
class Foo { ... };
Foo foo; // Equivalent to class Foo foo;
Previously, drgn always required the keyword, so prog.type("classFoo") would succeed but
prog.type("Foo") would fail with a LookupError. This requirement was surprising to C++ developers, so it
was removed. For C++ programs, prog.type("Foo") will now find a class, struct, union, or enum type named
Foo (for C programs, the keyword is still required).
NestedClasses
Again unlike C, C++ allows class, struct, and union types to be defined inside of other class, struct,
and union types. For example:
class Foo {
public:
class Bar { ... };
...
};
Foo::Bar bar;
drgn can now find such types with prog.type("Foo::Bar").
MemberFunctions
C++ supports member functions (a.k.a. methods). For example:
class Foo {
int method() { ... }
};
drgn can now find member functions with drgn.Program.function(), drgn.Program.object(), or drgn.Program[]
(e.g., prog.function("Foo::method") or prog["Foo::method"]).
SplitDWARF
drgn now supports split DWARF object (.dwo) files. This is enabled by the -gsplit-dwarf option in GCC and
Clang or for the Linux kernel with CONFIG_DEBUG_INFO_SPLIT=y.
Split DWARF package (.dwp) file support is still in progress.
PerformanceImprovements
Thierry Treyer found a bug that made us search through much more debugging information than necessary
when getting a stack trace. Fixing this made stack traces almost twice as fast.
The C++ lookup and split DWARF support mentioned above require processing more information in drgn's
debugging information indexing step, which it does on startup and whenever debugging information is
manually loaded. This could've been a performance regression, but instead, indexing was reworked from the
ground up in a way that's usually faster despite the added features.
0.0.23(ReleasedJune28th,2023)
These are some of the highlights of drgn 0.0.23. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
VirtualAddressTranslationHelpers
This release added several Linux kernel helpers for translating virtual addresses.
follow_phys() translates a virtual address to a physical address in a given address space. For example,
to get the physical address that virtual address 0x7f7fe46a4270 maps to in process 115:
>>> task = find_task(prog, 115)
>>> address = 0x7f7fe46a4270
>>> print(hex(follow_phys(task.mm, address)))
0x4090270
follow_page() translates a virtual address to the structpage* that it maps to:
>>> follow_page(task.mm, address)
*(struct page *)0xffffd20ac0102400 = {
...
}
follow_pfn() translates a virtual address to the page frame number (PFN) of the page that it maps to:
>>> follow_pfn(task.mm, address)
(unsigned long)16528
These can be used to translate arbitrary kernel virtual addresses by passing
prog["init_mm"].address_of_():
>>> print(hex(follow_phys(prog["init_mm"].address_of_(), 0xffffffffc0483000)))
0x2e4b000
Vmalloc/VmapAddressTranslationHelpersvmalloc_to_page() is a special case of follow_page() for vmalloc and vmap addresses:
>>> vmalloc_to_page(prog, 0xffffffffc0477000)
*(struct page *)0xffffc902400b8980 = {
...
}
Likewise, vmalloc_to_pfn() is a special case of follow_pfn() for vmalloc and vmap addresses:
>>> vmalloc_to_pfn(prog, 0xffffffffc0477000)
(unsigned long)11814
contribDirectory
Martin Liška, Boris Burkov, and Johannes Thumshirn added lots of new scripts to the contrib directory:
• btrfs_tree.py: work-in-progress helpers for Btrfs B-trees
• btrfs_tree_mod_log.py: simulator for the Btrfs tree modification log
• dump_btrfs_bgs.py: print block groups in a Btrfs filesystem
• kcore_list.py: print memory regions from /proc/kcore
• kernel_sys.py: print system information (similar to crash's sys command)
• mount.py: print a filesystem mount table
• platform_drivers.py: print registered platformdrivers
• vmmap.py: print memory mappings in a process (similar to /proc/$pid/maps)
• vmstat.py: print information about kernel memory usage
EmbeddingInteractiveModedrgn.cli.run_interactive() runs drgn's interactive mode. It can be used to embed drgn in another
application. For example, you could use it for a custom drgn.Program that the standard drgn CLI can't set
up:
import drgn
import drgn.cli
prog = drgn.Program()
prog.add_type_finder(...)
prog.add_object_finder(...)
prog.add_memory_segment(...)
drgn.cli.run_interactive(prog)
Fulls390xSupport
Sven Schnelle contributed s390x virtual address translation support. This is the state of architecture
support in this release:
drgn0.0.23ArchitectureSupport
┌──────────────┬──────────────────────┬──────────────┬────────────────────────┐
│ Architecture │ Linux Kernel Modules │ Stack Traces │ Virtual Address │
│ │ │ │ Translation │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ x86-64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ AArch64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ ppc64 │ ✓ │ ✓ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ s390x │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ i386 │ ✓ │ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ Arm │ ✓ │ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ RISC-V │ ✓ │ │ │
└──────────────┴──────────────────────┴──────────────┴────────────────────────┘
Linux6.3&6.4Support
Linux 6.3 and 6.4 had an unusual number of breaking changes for drgn. Here are some errors you might see
with older versions of drgn that are fixed in this release.
On startup (fixed by Ido Schimmel):
warning: could not get debugging information for:
kernel modules (could not find loaded kernel modules: 'struct module' has no member 'core_size')
From drgn.Program.stack_trace() and drgn.Thread.stack_trace():
Exception: unknown ORC entry type 3
From compound_order() and compound_nr():
AttributeError: 'struct page' has no member 'compound_order'
From for_each_disk() and for_each_partition():
AttributeError: 'struct class' has no member 'p'
Python3.12Support
Python 3.12, currently in beta, changed an implementation detail that drgn depended on, which caused
crashes like:
Py_SIZE: Assertion `ob->ob_type != &PyLong_Type' failed.
Stephen Brennan fixed this.
0.0.22(ReleasedJanuary5th,2023)
These are some of the highlights of drgn 0.0.22. See the GitHubrelease for the full release notes,
including more improvements and bug fixes.
ListingStackFrameLocalsdrgn.StackFrame.locals() returns the names of all arguments and local variables in the scope of a stack
frame. This allows you to get a quick idea of what's going on in a function without needing to read the
source code right away.
Let's use the __schedule stack frame from the following trace as an example:
>>> trace = prog.stack_trace(1)
>>> trace
#0 context_switch (./kernel/sched/core.c:5209:2)
#1 __schedule (./kernel/sched/core.c:6521:8)
#2 schedule (./kernel/sched/core.c:6597:3)
#3 do_wait (./kernel/exit.c:1562:4)
#4 kernel_wait4 (./kernel/exit.c:1706:8)
#5 __do_sys_wait4 (./kernel/exit.c:1734:13)
#6 do_syscall_x64 (./arch/x86/entry/common.c:50:14)
#7 do_syscall_64 (./arch/x86/entry/common.c:80:7)
#8 entry_SYSCALL_64+0x9b/0x197 (./arch/x86/entry/entry_64.S:120)
#9 0x7f6a34a00057
>>> trace[1].locals()
['sched_mode', 'prev', 'next', 'switch_count', 'prev_state', 'rf', 'rq', 'cpu']
>>> for name in trace[1].locals():
... print(name, trace[1][name].format_(dereference=False))
...
sched_mode (unsigned int)0
prev (struct task_struct *)0xffffa3b601178000
next (struct task_struct *)0xffffa3b6026db800
switch_count (unsigned long *)0xffffa3b601178528
prev_state (unsigned long)<absent>
rf (struct rq_flags){
.flags = (unsigned long)1,
.cookie = (struct pin_cookie){},
.clock_update_flags = (unsigned int)4,
}
rq (struct rq *)0xffffa3b67fda9640
cpu (int)<absent>
Compare this to the kernelsourcecode. Note that some of the variables have been optimized out by the
compiler.
This feature was contributed by Stephen Brennan.
MergedSlabCaches
The Linux kernel slab allocator merges "similar" slab caches as an optimization, which often causes
confusion. slab_cache_is_merged() (added back in 0.0.20) returns whether or not a slab cache has been
merged, but not what it was merged with. In this release, Stephen Brennan added get_slab_cache_aliases(),
which provides a mapping from a slab cache name to the name of the cache it was merged into:
>>> get_slab_cache_aliases(prog)
{'io_kiocb': 'maple_node', 'ip_dst_cache': 'uid_cache', 'aio_kiocb': 'uid_cache', 'ip_fib_alias': 'Acpi-Parse', 'pid_namespace': 'pid', 'iommu_iova': 'vmap_area', 'fasync_cache': 'ftrace_event_field', 'dnotify_mark': 'Acpi-State', 'tcp_bind2_bucket': 'vmap_area', 'nsproxy': 'Acpi-Operand', 'shared_policy_node': 'ftrace_event_field', 'eventpoll_epi': 'pid', 'fib6_nodes': 'vmap_area', 'Acpi-Namespace': 'ftrace_event_field', 'posix_timers_cache': 'maple_node', 'inotify_inode_mark': 'Acpi-State', 'kernfs_iattrs_cache': 'trace_event_file', 'fs_cache': 'vmap_area', 'UDP-Lite': 'UDP', 'anon_vma_chain': 'vmap_area', 'ip6_dst_cache': 'maple_node', 'eventpoll_pwq': 'vmap_area', 'inet_peer_cache': 'uid_cache', 'fsnotify_mark_connector': 'numa_policy', 'ip_fib_trie': 'ftrace_event_field', 'filp': 'maple_node', 'dnotify_struct': 'numa_policy', 'UDPLITEv6': 'UDPv6', 'biovec-16': 'maple_node', 'PING': 'signal_cache', 'ep_head': 'blkdev_ioc', 'tcp_bind_bucket': 'pid', 'Acpi-ParseExt': 'Acpi-State', 'cred_jar': 'pid', 'ovl_aio_req': 'pid', 'pool_workqueue': 'maple_node', 'sigqueue': 'Acpi-State', 'file_lock_ctx': 'Acpi-Parse', 'kernfs_node_cache': 'pid'}
This means that if you're looking for io_kiocb allocations, you actually need to look at the maple_node
slab cache. Conversely, if you're looking at the maple_node slab cache, you need to be aware that it also
contains allocations from all of the following slab caches:
>>> [merged for merged, canonical in get_slab_cache_aliases(prog).items() if canonical == "maple_node"]
['io_kiocb', 'posix_timers_cache', 'ip6_dst_cache', 'filp', 'biovec-16', 'pool_workqueue']
SlabAddressInformation
This release extended identify_address() to show additional information about slab allocations:
>>> ptr1 = 0xffffa3b601178438
>>> ptr2 = 0xffffa3b601176cc0
>>> identify_address(prog, ptr1)
'slab object: task_struct+0x438'
>>> identify_address(prog, ptr2)
'free slab object: mm_struct+0x0'
This means that ptr1 is an address 0x438 bytes into an allocated object from the task_struct slab cache,
and ptr2 is a free object from the mm_struct slab cache.
slab_object_info() provides the same information programmatically:
>>> slab_object_info(prog, ptr1)
SlabObjectInfo(slab_cache=Object(prog, 'struct kmem_cache *', value=0xffffa3b601045500), slab=Object(prog, 'struct slab *', value=0xffffe80840045e00), address=0xffffa3b601178000, allocated=True)
>>> slab_object_info(prog, ptr2)
SlabObjectInfo(slab_cache=Object(prog, 'struct kmem_cache *', value=0xffffa3b601045900), slab=Object(prog, 'struct slab *', value=0xffffe80840045c00), address=0xffffa3b601176cc0, allocated=False)
AnnotatedStackMemoryprint_annotated_stack() prints a stack trace and all of its memory, identifying anything that it can:
>>> print_annotated_stack(prog.stack_trace(1))
STACK POINTER VALUE
[stack frame #0 at 0xffffffffaf8a68e9 (__schedule+0x429/0x488) in context_switch at ./kernel/sched/core.c:5209:2 (inlined)]
[stack frame #1 at 0xffffffffaf8a68e9 (__schedule+0x429/0x488) in __schedule at ./kernel/sched/core.c:6521:8]
ffffbb1ac0013d28: ffffffffaf4498f5 [function symbol: __flush_tlb_one_user+0x5]
ffffbb1ac0013d30: 00000000af449feb
ffffbb1ac0013d38: 0000000000000001
ffffbb1ac0013d40: 0000000000000004
ffffbb1ac0013d48: 25c5ff9539edc200
ffffbb1ac0013d50: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d58: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d60: ffffbb1ac0013e10
ffffbb1ac0013d68: ffffa3b601177ff0 [slab object: mm_struct+0x70]
ffffbb1ac0013d70: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d78: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013d80: ffffffffaf8a69d1 [function symbol: schedule+0x89]
[stack frame #2 at 0xffffffffaf8a69d1 (schedule+0x89/0xc7) in schedule at ./kernel/sched/core.c:6597:3]
ffffbb1ac0013d88: ffffbb1ac0013de8
ffffbb1ac0013d90: 0000000000000000
ffffbb1ac0013d98: ffffffffaf4595ee [function symbol: do_wait+0x231]
[stack frame #3 at 0xffffffffaf4595ee (do_wait+0x231/0x2e3) in do_wait at ./kernel/exit.c:1562:4]
ffffbb1ac0013da0: ffffa3b601178450 [slab object: task_struct+0x450]
ffffbb1ac0013da8: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013db0: 0000000000000004
ffffbb1ac0013db8: 0000000000000000
ffffbb1ac0013dc0: 00007ffe0984a170
ffffbb1ac0013dc8: 0000000000000000
ffffbb1ac0013dd0: fffffffffffffffd
ffffbb1ac0013dd8: 0000000000000004
ffffbb1ac0013de0: ffffffffaf45a42f [function symbol: kernel_wait4+0xc2]
[stack frame #4 at 0xffffffffaf45a42f (kernel_wait4+0xc2/0x11b) in kernel_wait4 at ./kernel/exit.c:1706:8]
ffffbb1ac0013de8: 0000000400000004
ffffbb1ac0013df0: 0000000000000000
ffffbb1ac0013df8: 0000000000000000
ffffbb1ac0013e00: 0000000000000000
ffffbb1ac0013e08: 0000000000000000
ffffbb1ac0013e10: ffffffff00000000
ffffbb1ac0013e18: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013e20: ffffffffaf45890c [function symbol: child_wait_callback+0x0]
ffffbb1ac0013e28: ffffa3b601188028 [slab object: signal_cache+0x28]
ffffbb1ac0013e30: ffffa3b601188028 [slab object: signal_cache+0x28]
ffffbb1ac0013e38: 000055d500000000
ffffbb1ac0013e40: 25c5ff9539edc200
ffffbb1ac0013e48: 0000000000000000
ffffbb1ac0013e50: ffffbb1ac0013f30
ffffbb1ac0013e58: ffffbb1ac0013f58
ffffbb1ac0013e60: 0000000000000000
ffffbb1ac0013e68: 0000000000000000
ffffbb1ac0013e70: 0000000000000000
ffffbb1ac0013e78: ffffffffaf45a4c0 [function symbol: __do_sys_wait4+0x38]
[stack frame #5 at 0xffffffffaf45a4c0 (__do_sys_wait4+0x38/0x8c) in __do_sys_wait4 at ./kernel/exit.c:1734:13]
ffffbb1ac0013e80: ffffffffaf8aaa21 [function symbol: _raw_spin_unlock_irq+0x10]
ffffbb1ac0013e88: ffffffffaf46460c [function symbol: do_sigaction+0xf8]
ffffbb1ac0013e90: ffffa3b601180020 [slab object: sighand_cache+0x20]
ffffbb1ac0013e98: ffffa3b6028d02d0 [slab object: vm_area_struct+0x0]
ffffbb1ac0013ea0: 25c5ff9539edc200
ffffbb1ac0013ea8: 0000000000000002
ffffbb1ac0013eb0: 00007ffe09849fb0
ffffbb1ac0013eb8: ffffbb1ac0013f58
ffffbb1ac0013ec0: 0000000000000000
ffffbb1ac0013ec8: 0000000000000000
ffffbb1ac0013ed0: 0000000000000046
ffffbb1ac0013ed8: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013ee0: ffffa3b601178000 [slab object: task_struct+0x0]
ffffbb1ac0013ee8: ffffbb1ac0013f58
ffffbb1ac0013ef0: 0000000000000000
ffffbb1ac0013ef8: ffffffffaf426def [function symbol: fpregs_assert_state_consistent+0x1b]
ffffbb1ac0013f00: 0000000000000000
ffffbb1ac0013f08: ffffffffaf4b2f53 [function symbol: exit_to_user_mode_prepare+0xa6]
ffffbb1ac0013f10: 0000000000000000
ffffbb1ac0013f18: 25c5ff9539edc200
ffffbb1ac0013f20: ffffbb1ac0013f58
ffffbb1ac0013f28: 0000000000000000
ffffbb1ac0013f30: ffffbb1ac0013f48
ffffbb1ac0013f38: ffffffffaf8a1573 [function symbol: do_syscall_64+0x70]
[stack frame #6 at 0xffffffffaf8a1573 (do_syscall_64+0x70/0x8a) in do_syscall_x64 at ./arch/x86/entry/common.c:50:14 (inlined)]
[stack frame #7 at 0xffffffffaf8a1573 (do_syscall_64+0x70/0x8a) in do_syscall_64 at ./arch/x86/entry/common.c:80:7]
ffffbb1ac0013f40: 0000000000000000
ffffbb1ac0013f48: 0000000000000000
ffffbb1ac0013f50: ffffffffafa0009b [symbol: entry_SYSCALL_64+0x9b]
[stack frame #8 at 0xffffffffafa0009b (entry_SYSCALL_64+0x9b/0x197) at ./arch/x86/entry/entry_64.S:120]
ffffbb1ac0013f58: 0000000000000000
[stack frame #9 at 0x7f6a34a00057]
Like drgn.StackFrame.locals(), this provides a nice overview of everything happening in a function, which
might include useful hints. Keep in mind that it may identify "stale" addresses for anything that a
function hasn't reinitialized yet, and as always, be careful of slab cache merging.
This was inspired by the crash bt-FF command. It was contributed by Nhat Pham.
XArrayHelpers
XArrays were introduced in Linux 4.20 as a replacement for radix trees. drgn's radix tree helpers also
support XArrays in some cases, but this is awkward, not obvious, and doesn't work for new, XArray-only
functionality.
This release added dedicated XArray helpers like xa_load() and xa_for_each().
s390xSupport
Sven Schnelle contributed s390x support for Linux kernel modules and stack traces. This is the state of
architecture support in this release:
drgn0.0.22ArchitectureSupport
┌──────────────┬──────────────────────┬──────────────┬────────────────────────┐
│ Architecture │ Linux Kernel Modules │ Stack Traces │ Virtual Address │
│ │ │ │ Translation │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ x86-64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ AArch64 │ ✓ │ ✓ │ ✓ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ ppc64 │ ✓ │ ✓ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ s390x │ ✓ │ ✓ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ i386 │ ✓ │ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ Arm │ ✓ │ │ │
├──────────────┼──────────────────────┼──────────────┼────────────────────────┤
│ RISC-V │ ✓ │ │ │
└──────────────┴──────────────────────┴──────────────┴────────────────────────┘
RelicensingtoLGPL
drgn was originally licensed as GPLv3+. In this release, it was changed to LGPLv2.1+. The motivation for
this change was to enable the long term vision for drgn that more projects can use it as a library
providing programmatic interfaces for debugger functionality. For example, ObjectIntrospection, a
userspace memory profiler recently open sourced by Meta, uses drgn to parse debugging information.
Install Now
PNG Icons