'\" t .\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "DRGN" "1" "Mar 12, 2024" "0.0.26" "drgn" .SH NAME drgn \- drgn 0.0.26 .sp drgn (pronounced \(dqdragon\(dq) is a debugger with an emphasis on programmability. drgn exposes the types and variables in a program for easy, expressive scripting in Python. For example, you can debug the Linux kernel: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> from drgn.helpers.linux import list_for_each_entry >>> for mod in list_for_each_entry(\(aqstruct module\(aq, \&... prog[\(aqmodules\(aq].address_of_(), \&... \(aqlist\(aq): \&... if mod.refcnt.counter > 10: \&... print(mod.name) \&... (char [56])\(dqsnd\(dq (char [56])\(dqevdev\(dq (char [56])\(dqi915\(dq .EE .UNINDENT .UNINDENT .sp Although other debuggers like \fI\%GDB\fP have scripting support, drgn aims to make scripting as natural as possible so that debugging feels like coding. This makes it well\-suited for introspecting the complex, inter\-connected state in large programs. .sp Additionally, drgn is designed as a library that can be used to build debugging and introspection tools; see the official \fI\%tools\fP\&. .sp drgn was developed at \fI\%Meta\fP for debugging the Linux kernel (as an alternative to the \fI\%crash\fP utility), but it can also debug userspace programs written in C. C++ support is in progress. .sp In addition to the main Python API, an experimental C library, \fBlibdrgn\fP, is also available. .sp See the \fI\%Installation\fP instructions. Then, start with the \fI\%User Guide\fP\&. .SH LICENSE .sp Copyright (c) Meta Platforms, Inc. and affiliates. .sp drgn is licensed under the \fI\%LGPLv2.1\fP or later. .SH ACKNOWLEDGEMENTS .sp drgn is named after \fI\%this\fP because dragons eat \fI\%dwarves\fP\&. .SH TABLE OF CONTENTS .SS Installation .sp There are several options for installing drgn. .SS Dependencies .sp drgn depends on: .INDENT 0.0 .IP \(bu 2 \fI\%Python\fP 3.6 or newer .IP \(bu 2 \fI\%elfutils\fP 0.165 or newer .UNINDENT .sp It optionally depends on: .INDENT 0.0 .IP \(bu 2 \fI\%libkdumpfile\fP for \fI\%makedumpfile\fP compressed kernel core dump format support .UNINDENT .sp The build requires: .INDENT 0.0 .IP \(bu 2 \fI\%GCC\fP .IP \(bu 2 \fI\%GNU Make\fP .IP \(bu 2 \fI\%pkgconf\fP .IP \(bu 2 \fI\%setuptools\fP .UNINDENT .sp Building from the Git repository (rather than a release tarball) additionally requires: .INDENT 0.0 .IP \(bu 2 \fI\%autoconf\fP .IP \(bu 2 \fI\%automake\fP .IP \(bu 2 \fI\%libtool\fP .UNINDENT .SS Installation .SS Package Manager .sp drgn can be installed using the package manager on some Linux distributions. .INDENT 0.0 .IP \(bu 2 Fedora >= 32 .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo dnf install drgn .EE .UNINDENT .UNINDENT .IP \(bu 2 RHEL/CentOS >= 8 .sp \fI\%Enable EPEL\fP\&. Then: .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo dnf install drgn .EE .UNINDENT .UNINDENT .IP \(bu 2 Arch Linux .sp Install the \fI\%drgn\fP package from the \fI\%AUR\fP\&. .IP \(bu 2 Debian >= 12 (Bookworm) .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo apt install python3\-drgn .EE .UNINDENT .UNINDENT .IP \(bu 2 openSUSE .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo zypper install python3\-drgn .EE .UNINDENT .UNINDENT .IP \(bu 2 Ubuntu .sp Enable the \fI\%michel\-slm/kernel\-utils PPA\fP\&. Then: .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo apt install python3\-drgn .EE .UNINDENT .UNINDENT .UNINDENT .SS pip .sp If your Linux distribution doesn\(aqt package the latest release of drgn, you can install it with \fI\%pip\fP\&. .sp First, \fI\%install pip\fP\&. Then, run: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo pip3 install drgn .EE .UNINDENT .UNINDENT .sp This will install a binary wheel by default. If you get a build error, then pip wasn\(aqt able to use the binary wheel. Install the dependencies listed \fI\%below\fP and try again. .sp 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. .SS From Source .sp To get the development version of drgn, you will need to build it from source. First, install dependencies: .INDENT 0.0 .IP \(bu 2 Fedora .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo dnf install autoconf automake elfutils\-devel gcc git libkdumpfile\-devel libtool make pkgconf python3 python3\-devel python3\-pip python3\-setuptools .EE .UNINDENT .UNINDENT .IP \(bu 2 RHEL/CentOS .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo dnf install autoconf automake elfutils\-devel gcc git libtool make pkgconf python3 python3\-devel python3\-pip python3\-setuptools .EE .UNINDENT .UNINDENT .sp Optionally, install \fBlibkdumpfile\-devel\fP from EPEL on RHEL/CentOS >= 8 or install \fI\%libkdumpfile\fP from source if you want support for the makedumpfile format. .sp Replace \fBdnf\fP with \fByum\fP for RHEL/CentOS < 8. .IP \(bu 2 Debian/Ubuntu .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo apt\-get install autoconf automake gcc git liblzma\-dev libelf\-dev libdw\-dev libtool make pkgconf python3 python3\-dev python3\-pip python3\-setuptools zlib1g\-dev .EE .UNINDENT .UNINDENT .sp Optionally, install libkdumpfile from source if you want support for the makedumpfile format. .IP \(bu 2 Arch Linux .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo pacman \-S \-\-needed autoconf automake gcc git libelf libtool make pkgconf python python\-pip python\-setuptools .EE .UNINDENT .UNINDENT .sp Optionally, install \fI\%libkdumpfile\fP from the AUR or from source if you want support for the makedumpfile format. .IP \(bu 2 openSUSE .INDENT 2.0 .INDENT 3.5 .sp .EX $ sudo zypper install autoconf automake gcc git libdw\-devel libelf\-devel libkdumpfile\-devel libtool make pkgconf python3 python3\-devel python3\-pip python3\-setuptools .EE .UNINDENT .UNINDENT .UNINDENT .sp Then, run: .INDENT 0.0 .INDENT 3.5 .sp .EX $ git clone https://github.com/osandov/drgn.git $ cd drgn $ python3 setup.py build $ sudo python3 setup.py install .EE .UNINDENT .UNINDENT .SS Virtual Environment .sp The above options all install drgn globally. You can also install drgn in a \fI\%virtual environment\fP, either with pip: .INDENT 0.0 .INDENT 3.5 .sp .EX $ python3 \-m venv drgnenv $ source drgnenv/bin/activate (drgnenv) $ pip3 install drgn (drgnenv) $ drgn \-\-help .EE .UNINDENT .UNINDENT .sp Or from source: .INDENT 0.0 .INDENT 3.5 .sp .EX $ python3 \-m venv drgnenv $ source drgnenv/bin/activate (drgnenv) $ python3 setup.py install (drgnenv) $ drgn \-\-help .EE .UNINDENT .UNINDENT .SS Running Locally .sp If you build drgn from source, you can also run it without installing it: .INDENT 0.0 .INDENT 3.5 .sp .EX $ python3 setup.py build_ext \-i $ python3 \-m drgn \-\-help .EE .UNINDENT .UNINDENT .SS User Guide .SS Quick Start .sp drgn debugs the running kernel by default; run \fBsudo drgn\fP\&. To debug a running program, run \fBsudo drgn \-p $PID\fP\&. To debug a core dump (either a kernel vmcore or a userspace core dump), run \fBdrgn \-c $PATH\fP\&. Make sure to \fI\%install debugging symbols\fP for whatever you are debugging. .sp Then, you can access variables in the program with \fBprog[\(aqname\(aq]\fP and access structure members with \fB\&.\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo drgn >>> prog[\(aqinit_task\(aq].comm (char [16])\(dqswapper/0\(dq .EE .UNINDENT .UNINDENT .sp You can use various predefined helpers: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> len(list(bpf_prog_for_each())) 11 >>> task = find_task(115) >>> cmdline(task) [b\(aqfindmnt\(aq, b\(aq\-p\(aq] .EE .UNINDENT .UNINDENT .sp You can get stack traces with \fBstack_trace()\fP and access parameters or local variables with \fBtrace[\(aqname\(aq]\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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][\(aqlist\(aq] >>> file = fget(task, poll_list.entries[0].fd) >>> d_path(file.f_path.address_of_()) b\(aq/proc/115/mountinfo\(aq .EE .UNINDENT .UNINDENT .SS Core Concepts .sp The most important interfaces in drgn are \fIprograms\fP, \fIobjects\fP, and \fIhelpers\fP\&. .SS Programs .sp A program being debugged is represented by an instance of the \fI\%drgn.Program\fP class. The drgn CLI is initialized with a \fBProgram\fP named \fBprog\fP; unless you are using the drgn library directly, this is usually the only \fBProgram\fP you will need. .sp A \fBProgram\fP is used to look up type definitions, access variables, and read arbitrary memory: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> prog.type(\(aqunsigned long\(aq) prog.int_type(name=\(aqunsigned long\(aq, size=8, is_signed=False) >>> prog[\(aqjiffies\(aq] Object(prog, \(aqvolatile unsigned long\(aq, address=0xffffffffbe405000) >>> prog.read(0xffffffffbe411e10, 16) b\(aqswapper/0\ex00\ex00\ex00\ex00\ex00\ex00\ex00\(aq .EE .UNINDENT .UNINDENT .sp The \fI\%drgn.Program.type()\fP, \fI\%drgn.Program.variable()\fP, \fI\%drgn.Program.constant()\fP, and \fI\%drgn.Program.function()\fP methods look up those various things in a program. \fI\%drgn.Program.read()\fP reads memory from the program\(aqs address space. The \fI\%[]\fP operator looks up a variable, constant, or function: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> prog[\(aqjiffies\(aq] == prog.variable(\(aqjiffies\(aq) True .EE .UNINDENT .UNINDENT .sp It is usually more convenient to use the \fB[]\fP operator rather than the \fBvariable()\fP, \fBconstant()\fP, or \fBfunction()\fP methods unless the program has multiple objects with the same name, in which case the methods provide more control. .SS Objects .sp Variables, constants, functions, and computed values are all called \fIobjects\fP in drgn. Objects are represented by the \fI\%drgn.Object\fP class. An object may exist in the memory of the program (a \fIreference\fP): .INDENT 0.0 .INDENT 3.5 .sp .EX >>> Object(prog, \(aqint\(aq, address=0xffffffffc09031a0) .EE .UNINDENT .UNINDENT .sp Or, an object may be a constant or temporary computed value (a \fIvalue\fP): .INDENT 0.0 .INDENT 3.5 .sp .EX >>> Object(prog, \(aqint\(aq, value=4) .EE .UNINDENT .UNINDENT .sp What makes drgn scripts expressive is that objects can be used almost exactly like they would be in the program\(aqs own source code. For example, structure members can be accessed with the dot (\fB\&.\fP) operator, arrays can be subscripted with \fB[]\fP, arithmetic can be performed, and objects can be compared: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> print(prog[\(aqinit_task\(aq].comm[0]) (char)115 >>> print(repr(prog[\(aqinit_task\(aq].nsproxy.mnt_ns.mounts + 1)) Object(prog, \(aqunsigned int\(aq, value=34) >>> prog[\(aqinit_task\(aq].nsproxy.mnt_ns.pending_mounts > 0 False .EE .UNINDENT .UNINDENT .sp Python doesn\(aqt have all of the operators that C or C++ do, so some substitutions are necessary: .INDENT 0.0 .IP \(bu 2 Instead of \fB*ptr\fP, dereference a pointer with \fI\%ptr[0]\fP\&. .IP \(bu 2 Instead of \fBptr\->member\fP, access a member through a pointer with \fI\%ptr.member\fP\&. .IP \(bu 2 Instead of \fB&var\fP, get the address of a variable with \fI\%var.address_of_()\fP\&. .UNINDENT .sp A common use case is converting a \fBdrgn.Object\fP to a Python value so it can be used by a standard Python library. There are a few ways to do this: .INDENT 0.0 .IP \(bu 2 The \fI\%drgn.Object.value_()\fP method gets the value of the object with the directly corresponding Python type (i.e., integers and pointers become \fBint\fP, floating\-point types become \fBfloat\fP, booleans become \fBbool\fP, arrays become \fBlist\fP, structures and unions become \fBdict\fP). .IP \(bu 2 The \fI\%drgn.Object.string_()\fP method gets a null\-terminated string as \fBbytes\fP from an array or pointer. .IP \(bu 2 The \fBint()\fP, \fBfloat()\fP, and \fBbool()\fP functions do an explicit conversion to that Python type. .UNINDENT .sp Objects have several attributes; the most important are \fI\%drgn.Object.prog_\fP and \fI\%drgn.Object.type_\fP\&. The former is the \fI\%drgn.Program\fP that the object is from, and the latter is the \fI\%drgn.Type\fP of the object. .sp Note that all attributes and methods of the \fBObject\fP class end with an underscore (\fB_\fP) in order to avoid conflicting with structure or union members. The \fBObject\fP attributes and methods always take precedence; use \fI\%drgn.Object.member_()\fP if there is a conflict. .SS References vs. Values .sp The main difference between reference objects and value objects is how they are evaluated. References are read from the program\(aqs memory every time they are evaluated; values simply return the stored value (\fI\%drgn.Object.read_()\fP reads a reference object and returns it as a value object): .INDENT 0.0 .INDENT 3.5 .sp .EX >>> import time >>> jiffies = prog[\(aqjiffies\(aq] >>> jiffies.value_() 4391639989 >>> time.sleep(1) >>> jiffies.value_() 4391640290 >>> jiffies2 = jiffies.read_() >>> jiffies2.value_() 4391640291 >>> time.sleep(1) >>> jiffies2.value_() 4391640291 >>> jiffies.value_() 4391640593 .EE .UNINDENT .UNINDENT .sp References have a \fI\%drgn.Object.address_\fP attribute, which is the object\(aqs address as a Python \fBint\fP\&. This is slightly different from the \fI\%drgn.Object.address_of_()\fP method, which returns the address as a \fBdrgn.Object\fP\&. Of course, both references and values can have a pointer type; \fBaddress_\fP refers to the address of the pointer object itself, and \fI\%drgn.Object.value_()\fP refers to the value of the pointer (i.e., the address it points to): .INDENT 0.0 .INDENT 3.5 .sp .EX >>> address = prog[\(aqjiffies\(aq].address_ >>> type(address) >>> print(hex(address)) 0xffffffffbe405000 >>> jiffiesp = prog[\(aqjiffies\(aq].address_of_() >>> jiffiesp Object(prog, \(aqvolatile unsigned long *\(aq, value=0xffffffffbe405000) >>> print(hex(jiffiesp.value_())) 0xffffffffbe405000 .EE .UNINDENT .UNINDENT .SS Absent Objects .sp In addition to reference objects and value objects, objects may also be \fIabsent\fP\&. .sp .EX >>> Object(prog, \(dqint\(dq).value_() Traceback (most recent call last): File \(dq\(dq, line 1, in _drgn.ObjectAbsentError: object absent .EE .sp 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. .sp Any attempt to operate on an absent object results in a \fI\%drgn.ObjectAbsentError\fP exception, although basic information including its type may still be accessed. .SS Helpers .sp Some programs have common data structures that you may want to examine. For example, consider linked lists in the Linux kernel: .INDENT 0.0 .INDENT 3.5 .sp .EX struct list_head { struct list_head *next, *prev; }; #define list_for_each(pos, head) \e for (pos = (head)\->next; pos != (head); pos = pos\->next) .EE .UNINDENT .UNINDENT .sp When working with these lists, you\(aqd probably want to define a function: .INDENT 0.0 .INDENT 3.5 .sp .EX def list_for_each(head): pos = head.next while pos != head: yield pos pos = pos.next .EE .UNINDENT .UNINDENT .sp Then, you could use it like so for any list you need to look at: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> for pos in list_for_each(head): \&... do_something_with(pos) .EE .UNINDENT .UNINDENT .sp 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 \fI\%Helpers\fP\&. .SS Validators .sp 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. .sp Validators raise \fI\%drgn.helpers.ValidationError\fP if the data structure is not valid or \fI\%drgn.FaultError\fP if the data structure is invalid in a way that causes a bad memory access. They have names prefixed with \fBvalidate_\fP\&. .sp For example, \fI\%drgn.helpers.linux.list.validate_list()\fP checks the consistency of a linked list in the Linux kernel (in particular, the consistency of the \fBnext\fP and \fBprev\fP pointers): .INDENT 0.0 .INDENT 3.5 .sp .EX >>> validate_list(prog[\(dqmy_list\(dq].address_of_()) drgn.helpers.ValidationError: (struct list_head *)0xffffffffc029e460 next 0xffffffffc029e000 has prev 0xffffffffc029e450 .EE .UNINDENT .UNINDENT .sp \fI\%drgn.helpers.linux.list.validate_list_for_each_entry()\fP does the same checks while also returning the entries in the list for further validation: .INDENT 0.0 .INDENT 3.5 .sp .EX def validate_my_list(prog): for entry in validate_list_for_each_entry( \(dqstruct my_entry\(dq, prog[\(dqmy_list\(dq].address_of_(), \(dqlist\(dq, ): if entry.value < 0: raise ValidationError(\(dqlist contains negative entry\(dq) .EE .UNINDENT .UNINDENT .SS Other Concepts .sp In addition to the core concepts above, drgn provides a few additional abstractions. .SS Threads .sp The \fI\%drgn.Thread\fP class represents a thread. \fI\%drgn.Program.threads()\fP, \fI\%drgn.Program.thread()\fP, \fI\%drgn.Program.main_thread()\fP, and \fI\%drgn.Program.crashed_thread()\fP can be used to find threads: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> for thread in prog.threads(): \&... print(thread.tid) \&... 39143 39144 >>> print(prog.main_thread().tid) 39143 >>> print(prog.crashed_thread().tid) 39144 .EE .UNINDENT .UNINDENT .SS Stack Traces .sp drgn represents stack traces with the \fI\%drgn.StackTrace\fP and \fI\%drgn.StackFrame\fP classes. \fI\%drgn.stack_trace()\fP, \fI\%drgn.Program.stack_trace()\fP, and \fI\%drgn.Thread.stack_trace()\fP return the call stack for a thread. The \fI\%[]\fP operator looks up an object in the scope of a \fBStackFrame\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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[\(aqdo_poll\(aq] (int (struct poll_list *list, struct poll_wqueues *wait, struct timespec64 *end_time)) >>> trace[5][\(aqlist\(aq] *(struct poll_list *)0xffffacca402e3b50 = { .next = (struct poll_list *)0x0, .len = (int)1, .entries = (struct pollfd []){}, } .EE .UNINDENT .UNINDENT .SS Symbols .sp The symbol table of a program is a list of identifiers along with their address and size. drgn represents symbols with the \fI\%drgn.Symbol\fP class, which is returned by \fI\%drgn.Program.symbol()\fP\&. .SS Types .sp drgn automatically obtains type definitions from the program. Types are represented by the \fI\%drgn.Type\fP class and created by various factory functions like \fI\%drgn.Program.int_type()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> prog.type(\(aqint\(aq) prog.int_type(name=\(aqint\(aq, size=4, is_signed=True) .EE .UNINDENT .UNINDENT .sp You won\(aqt usually need to work with types directly, but see \fI\%Types\fP if you do. .SS Platforms .sp Certain operations and objects in a program are platform\-dependent; drgn allows accessing the platform that a program runs with the \fI\%drgn.Platform\fP class. .SS Command Line Interface .sp The drgn CLI is basically a wrapper around the drgn library which automatically creates a \fI\%drgn.Program\fP\&. The CLI can be run in interactive mode or script mode. .SS Script Mode .sp Script mode is useful for reusable scripts. Simply pass the path to the script along with any arguments: .INDENT 0.0 .INDENT 3.5 .sp .EX $ 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\(aqPID {pid} is being run by UID {uid}\(aq) $ sudo drgn script.py 601 PID 601 is being run by UID 1000 .EE .UNINDENT .UNINDENT .sp It\(aqs even possible to run drgn scripts directly with the proper \fI\%shebang\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ cat script2.py #!/usr/bin/env drgn mounts = prog[\(aqinit_task\(aq].nsproxy.mnt_ns.mounts.value_() print(f\(aqYou have {mounts} filesystems mounted\(aq) $ sudo ./script2.py You have 36 filesystems mounted .EE .UNINDENT .UNINDENT .SS Interactive Mode .sp Interactive mode uses the Python interpreter\(aqs \fI\%interactive mode\fP and adds a few nice features, including: .INDENT 0.0 .IP \(bu 2 History .IP \(bu 2 Tab completion .IP \(bu 2 Automatic import of relevant helpers .IP \(bu 2 Pretty printing of objects and types .UNINDENT .sp The default behavior of the Python \fI\%REPL\fP is to print the output of \fBrepr()\fP\&. For \fI\%drgn.Object\fP and \fI\%drgn.Type\fP, this is a raw representation: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> print(repr(prog[\(aqjiffies\(aq])) Object(prog, \(aqvolatile unsigned long\(aq, address=0xffffffffbe405000) >>> print(repr(prog.type(\(aqatomic_t\(aq))) prog.typedef_type(name=\(aqatomic_t\(aq, type=prog.struct_type(tag=None, size=4, members=(TypeMember(prog.type(\(aqint\(aq), name=\(aqcounter\(aq, bit_offset=0),))) .EE .UNINDENT .UNINDENT .sp The standard \fBprint()\fP function uses the output of \fBstr()\fP\&. For drgn objects and types, this is a representation in programming language syntax: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> print(prog[\(aqjiffies\(aq]) (volatile unsigned long)4395387628 >>> print(prog.type(\(aqatomic_t\(aq)) typedef struct { int counter; } atomic_t .EE .UNINDENT .UNINDENT .sp In interactive mode, the drgn CLI automatically uses \fBstr()\fP instead of \fBrepr()\fP for objects and types, so you don\(aqt need to call \fBprint()\fP explicitly: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo drgn >>> prog[\(aqjiffies\(aq] (volatile unsigned long)4395387628 >>> prog.type(\(aqatomic_t\(aq) typedef struct { int counter; } atomic_t .EE .UNINDENT .UNINDENT .SS Next Steps .sp Refer to the \fI\%API Reference\fP\&. Look through the \fI\%Helpers\fP\&. Read some \fI\%Case Studies\fP\&. Browse through the \fI\%tools\fP\&. Check out the \fI\%community contributions\fP\&. .SS Advanced Usage .sp The \fI\%User Guide\fP covers basic usage of drgn, but drgn also supports more advanced use cases which are covered here. .SS Loading Debugging Symbols .sp drgn will automatically load debugging information based on the debugged program (e.g., from loaded kernel modules or loaded shared libraries). \fI\%drgn.Program.load_debug_info()\fP can be used to load additional debugging information: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> prog.load_debug_info([\(aq./libfoo.so\(aq, \(aq/usr/lib/libbar.so\(aq]) .EE .UNINDENT .UNINDENT .SS Library .sp In addition to the CLI, drgn is also available as a library. \fI\%drgn.program_from_core_dump()\fP, \fI\%drgn.program_from_kernel()\fP, and \fI\%drgn.program_from_pid()\fP correspond to the \fB\-c\fP, \fB\-k\fP, and \fB\-p\fP command line options, respectively; they return a \fI\%drgn.Program\fP that can be used just like the one initialized by the CLI: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> import drgn >>> prog = drgn.program_from_kernel() .EE .UNINDENT .UNINDENT .SS C Library .sp The core functionality of drgn is implemented in C and is available as a C library, \fBlibdrgn\fP\&. See \fI\%drgn.h\fP\&. .sp Full documentation can be generated by running \fBdoxygen\fP in the \fBlibdrgn\fP directory of the source code. Note that the API and ABI are not yet stable. .SS Custom Programs .sp The main components of a \fI\%drgn.Program\fP are the program memory, types, and symbols. The CLI and equivalent library interfaces automatically determine these. However, it is also possible to create a \(dqblank\(dq \fBProgram\fP and plug in the main components. The \fI\%drgn.cli.run_interactive()\fP function allows you to run the same drgn CLI once you\(aqve created a \fI\%drgn.Program\fP, so it\(aqs easy to make a custom program which allows interactive debugging. .sp \fI\%drgn.Program.add_memory_segment()\fP defines a range of memory and how to read that memory. The following example uses a Btrfs filesystem image as the program \(dqmemory\(dq: .INDENT 0.0 .INDENT 3.5 .sp .EX import drgn import os import sys from drgn.cli import run_interactive def btrfs_debugger(dev): file = open(dev, \(aqrb\(aq) 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\(aq/lib/modules/{os.uname().release}/kernel/fs/btrfs/btrfs.ko\(aq]) return prog prog = btrfs_debugger(sys.argv[1] if len(sys.argv) >= 2 else \(aq/dev/sda\(aq) print(drgn.Object(prog, \(aqstruct btrfs_super_block\(aq, address=65536)) run_interactive(prog, banner_func=lambda _: \(dqBTRFS debugger\(dq) .EE .UNINDENT .UNINDENT .sp \fI\%drgn.Program.add_type_finder()\fP and \fI\%drgn.Program.add_object_finder()\fP are the equivalent methods for plugging in types and objects. .SS Environment Variables .sp Some of drgn\(aqs behavior can be modified through environment variables: .INDENT 0.0 .TP .B \fBDRGN_MAX_DEBUG_INFO_ERRORS\fP The maximum number of individual errors to report in a \fI\%drgn.MissingDebugInfoError\fP\&. Any additional errors are truncated. The default is 5; \-1 is unlimited. .TP .B \fBDRGN_PREFER_ORC_UNWINDER\fP Whether to prefer using \fI\%ORC\fP 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. .TP .B \fBDRGN_USE_LIBDWFL_REPORT\fP 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\(aqs implementation and will be ignored in the future. .TP .B \fBDRGN_USE_LIBKDUMPFILE_FOR_ELF\fP Whether drgn should use libkdumpfile for ELF vmcores (0 or 1). The default is 0. This functionality will be removed in the future. .TP .B \fBDRGN_USE_SYS_MODULE\fP Whether drgn should use \fB/sys/module\fP 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. .UNINDENT .SS Linux Kernel Special Objects .sp When debugging the Linux kernel, there are some special \fI\%drgn.Object\fPs accessible with \fI\%drgn.Program.object()\fP and \fI\%drgn.Program[]\fP\&. Some of these are available even without debugging information, thanks to metadata called \(dqvmcoreinfo\(dq which is present in kernel core dumps. These special objects include: .INDENT 0.0 .TP .B \fBUTS_RELEASE\fP Object type: \fBconst char []\fP .sp This corresponds to the \fBUTS_RELEASE\fP macro in the Linux kernel source code. This is the exact kernel release (i.e., the output of \fBuname \-r\fP). .sp To use this as a Python string, you must convert it: .INDENT 7.0 .INDENT 3.5 .sp .EX >>> release = prog[\(dqUTS_RELEASE\(dq].string_().decode(\(dqascii\(dq) .EE .UNINDENT .UNINDENT .sp This is available without debugging information. .TP .B \fBPAGE_SIZE\fP Object type: \fBunsigned long\fP .TP .B \fBPAGE_SHIFT\fP Object type: \fBunsigned int\fP .TP .B \fBPAGE_MASK\fP Object type: \fBunsigned long\fP .sp 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. .sp .EX >>> prog[\(aqPAGE_SIZE\(aq] (unsigned long)4096 >>> prog[\(aqPAGE_SHIFT\(aq] (int)12 >>> prog[\(aqPAGE_MASK\(aq] (unsigned long)18446744073709547520 >>> 1 << prog[\(aqPAGE_SHIFT\(aq] == prog[\(aqPAGE_SIZE\(aq] True >>> ~(prog[\(aqPAGE_SIZE\(aq] \- 1) == prog[\(aqPAGE_MASK\(aq] True .EE .sp These are available without debugging information. .TP .B \fBjiffies\fP Object type: \fBvolatile unsigned long\fP .sp This is a counter of timer ticks. It is actually an alias of \fBjiffies_64\fP on 64\-bit architectures, or the least significant 32 bits of \fBjiffies_64\fP on 32\-bit architectures. Since this alias is defined via the linker, drgn handles it specially. .sp This is \fInot\fP available without debugging information. .TP .B \fBvmemmap\fP Object type: \fBstruct page *\fP .sp This is a pointer to the \(dqvirtual memory map\(dq, an array of \fBstruct page\fP 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. .sp This is \fInot\fP available without debugging information. .TP .B \fBVMCOREINFO\fP Object type: \fBconst char []\fP .sp This is the data contained in the vmcoreinfo note, which is present either as an ELF note in \fB/proc/kcore\fP 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. .sp In the Linux kernel, this data is normally stored in a variable called \fBvmcoreinfo_data\fP\&. 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 \fBvmcoreinfo_data\fP, so it is important to distinguish the contents. For that reason, we use the name \fBVMCOREINFO\fP to distinguish it from the kernel variable \fBvmcoreinfo_data\fP\&. .sp This is available without debugging information. .UNINDENT .SS API Reference .SS Programs .INDENT 0.0 .TP .B class drgn.Program A \fBProgram\fP represents a crashed or running program. It can be used to lookup type definitions, access variables, and read arbitrary memory. .sp The main functionality of a \fBProgram\fP is looking up objects (i.e., variables, constants, or functions). This is usually done with the \fI\%[]\fP operator. .INDENT 7.0 .TP .B Program(platform: Optional[\fI\%Platform\fP] = None) Create a \fBProgram\fP with no target program. It is usually more convenient to use one of the \fI\%Program Constructors\fP\&. .INDENT 7.0 .TP .B Parameters \fBplatform\fP \-\- The platform of the program, or \fBNone\fP if it should be determined automatically when a core dump or symbol file is added. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B flags: \fI\%ProgramFlags\fP Flags which apply to this program. .UNINDENT .INDENT 7.0 .TP .B platform: Optional[\fI\%Platform\fP] Platform that this program runs on, or \fBNone\fP if it has not been determined yet. .UNINDENT .INDENT 7.0 .TP .B language: \fI\%Language\fP Default programming language of the program. .sp This is used for interpreting the type name given to \fI\%type()\fP and when creating an \fI\%Object\fP without an explicit type. .sp For the Linux kernel, this defaults to \fI\%Language.C\fP\&. For userspace programs, this defaults to the language of \fBmain\fP in the program, falling back to \fI\%Language.C\fP\&. This heuristic may change in the future. .sp This can be explicitly set to a different language (e.g., if the heuristic was incorrect). .UNINDENT .INDENT 7.0 .TP .B __getitem__(name: str) -> \fI\%Object\fP Implement \fBself[name]\fP\&. Get the object (variable, constant, or function) with the given name. .sp This is equivalent to \fBprog.object(name)\fP except that this raises \fBKeyError\fP instead of \fBLookupError\fP if no objects with the given name are found. .sp If there are multiple objects with the same name, one is returned arbitrarily. In this case, the \fI\%variable()\fP, \fI\%constant()\fP, \fI\%function()\fP, or \fI\%object()\fP methods can be used instead. .sp .EX >>> prog[\(aqjiffies\(aq] Object(prog, \(aqvolatile unsigned long\(aq, address=0xffffffff94c05000) .EE .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Object name. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B __contains__(name: str) -> bool Implement \fBname in self\fP\&. Return whether an object (variable, constant, or function) with the given name exists in the program. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Object name. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B variable(name: str, filename: Optional[str] = None) -> \fI\%Object\fP Get the variable with the given name. .sp .EX >>> prog.variable(\(aqjiffies\(aq) Object(prog, \(aqvolatile unsigned long\(aq, address=0xffffffff94c05000) .EE .sp This is equivalent to \fBprog.object(name, FindObjectFlags.VARIABLE, filename)\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The variable name. .IP \(bu 2 \fBfilename\fP \-\- The source code file that contains the definition. See \fI\%Filenames\fP\&. .UNINDENT .TP .B Raises \fBLookupError\fP \-\- if no variables with the given name are found in the given file .UNINDENT .UNINDENT .INDENT 7.0 .TP .B constant(name: str, filename: Optional[str] = None) -> \fI\%Object\fP Get the constant (e.g., enumeration constant) with the given name. .sp Note that support for macro constants is not yet implemented for DWARF files, and most compilers don\(aqt generate macro debugging information by default anyways. .sp .EX >>> prog.constant(\(aqPIDTYPE_MAX\(aq) Object(prog, \(aqenum pid_type\(aq, value=4) .EE .sp This is equivalent to \fBprog.object(name, FindObjectFlags.CONSTANT, filename)\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The constant name. .IP \(bu 2 \fBfilename\fP \-\- The source code file that contains the definition. See \fI\%Filenames\fP\&. .UNINDENT .TP .B Raises \fBLookupError\fP \-\- if no constants with the given name are found in the given file .UNINDENT .UNINDENT .INDENT 7.0 .TP .B function(name: str, filename: Optional[str] = None) -> \fI\%Object\fP Get the function with the given name. .sp .EX >>> prog.function(\(aqschedule\(aq) Object(prog, \(aqvoid (void)\(aq, address=0xffffffff94392370) .EE .sp This is equivalent to \fBprog.object(name, FindObjectFlags.FUNCTION, filename)\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The function name. .IP \(bu 2 \fBfilename\fP \-\- The source code file that contains the definition. See \fI\%Filenames\fP\&. .UNINDENT .TP .B Raises \fBLookupError\fP \-\- if no functions with the given name are found in the given file .UNINDENT .UNINDENT .INDENT 7.0 .TP .B object(name: str, flags: \fI\%FindObjectFlags\fP = FindObjectFlags.ANY, filename: Optional[str] = None) -> \fI\%Object\fP Get the object (variable, constant, or function) with the given name. .sp When debugging the Linux kernel, this can look up certain special objects documented in \fI\%Linux Kernel Special Objects\fP, sometimes without any debugging information loaded. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The object name. .IP \(bu 2 \fBflags\fP \-\- Flags indicating what kind of object to look for. .IP \(bu 2 \fBfilename\fP \-\- The source code file that contains the definition. See \fI\%Filenames\fP\&. .UNINDENT .TP .B Raises \fBLookupError\fP \-\- if no objects with the given name are found in the given file .UNINDENT .UNINDENT .INDENT 7.0 .TP .B symbol(address_or_name: Union[\fI\%IntegerLike\fP, str]) -> \fI\%Symbol\fP Get a symbol containing the given address, or a symbol with the given name. .sp Global symbols are preferred over weak symbols, and weak symbols are preferred over other symbols. In other words: if a matching \fI\%SymbolBinding.GLOBAL\fP or \fI\%SymbolBinding.UNIQUE\fP symbol is found, it is returned. Otherwise, if a matching \fI\%SymbolBinding.WEAK\fP symbol is found, it is returned. Otherwise, any matching symbol (e.g., \fI\%SymbolBinding.LOCAL\fP) is returned. If there are multiple matching symbols with the same binding, one is returned arbitrarily. To retrieve all matching symbols, use \fI\%symbols()\fP\&. .INDENT 7.0 .TP .B Parameters \fBaddress_or_name\fP \-\- Address or name to search for. This parameter is positional\-only. .TP .B Raises \fBLookupError\fP \-\- if no symbol contains the given address or matches the given name .UNINDENT .UNINDENT .INDENT 7.0 .TP .B symbols(address_or_name: Union[None, \fI\%IntegerLike\fP, str] = None) -> List[\fI\%Symbol\fP] Get a list of global and local symbols, optionally matching a name or address. .sp 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. .INDENT 7.0 .TP .B Parameters \fBaddress_or_name\fP \-\- Address or name to search for. This parameter is positional\-only. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B stack_trace(thread: Union[\fI\%Object\fP, \fI\%IntegerLike\fP]) -> \fI\%StackTrace\fP Get the stack trace for the given thread in the program. .sp \fBthread\fP may be a thread ID (as defined by \fBgettid(2)\fP), in which case this will unwind the stack for the thread with that ID. The ID may be a Python \fBint\fP or an integer \fI\%Object\fP .sp \fBthread\fP may also be a \fBstruct pt_regs\fP or \fBstruct pt_regs *\fP object, in which case the initial register values will be fetched from that object. .sp Finally, if debugging the Linux kernel, \fBthread\fP may be a \fBstruct task_struct *\fP object, in which case this will unwind the stack for that task. See \fI\%drgn.helpers.linux.pid.find_task()\fP\&. .sp This is implemented for the Linux kernel (both live and core dumps) as well as userspace core dumps; it is not yet implemented for live userspace processes. .INDENT 7.0 .TP .B Parameters \fBthread\fP \-\- Thread ID, \fBstruct pt_regs\fP object, or \fBstruct task_struct *\fP object. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B stack_trace_from_pcs(pcs: Sequence[\fI\%IntegerLike\fP]) -> \fI\%StackTrace\fP Get a stack trace with the supplied list of program counters. .INDENT 7.0 .TP .B Parameters \fBpcs\fP \-\- List of program counters. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B type(name: str, filename: Optional[str] = None) -> \fI\%Type\fP Get the type with the given name. .sp .EX >>> prog.type(\(aqlong\(aq) prog.int_type(name=\(aqlong\(aq, size=8, is_signed=True) .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The type name. .IP \(bu 2 \fBfilename\fP \-\- The source code file that contains the definition. See \fI\%Filenames\fP\&. .UNINDENT .TP .B Raises \fBLookupError\fP \-\- if no types with the given name are found in the given file .UNINDENT .UNINDENT .INDENT 7.0 .TP .B type(type: \fI\%Type\fP) -> \fI\%Type\fP Return the given type. .sp This is mainly useful so that helpers can use \fBprog.type()\fP to get a \fI\%Type\fP regardless of whether they were given a \fBstr\fP or a \fI\%Type\fP\&. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX 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) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBtype\fP \-\- Type. .TP .B Returns The exact same type. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B threads() -> Iterator[\fI\%Thread\fP] Get an iterator over all of the threads in the program. .UNINDENT .INDENT 7.0 .TP .B thread(tid: \fI\%IntegerLike\fP) -> \fI\%Thread\fP Get the thread with the given thread ID. .INDENT 7.0 .TP .B Parameters \fBtid\fP \-\- Thread ID (as defined by \fBgettid(2)\fP). .TP .B Raises \fBLookupError\fP \-\- if no thread has the given thread ID .UNINDENT .UNINDENT .INDENT 7.0 .TP .B main_thread() -> \fI\%Thread\fP Get the main thread of the program. .sp This is only defined for userspace programs. .INDENT 7.0 .TP .B Raises \fBValueError\fP \-\- if the program is the Linux kernel .UNINDENT .UNINDENT .INDENT 7.0 .TP .B crashed_thread() -> \fI\%Thread\fP Get the thread that caused the program to crash. .sp For userspace programs, this is the thread that received the fatal signal (e.g., \fBSIGSEGV\fP or \fBSIGQUIT\fP). .sp For the kernel, this is the thread that panicked (either directly or as a result of an oops, \fBBUG_ON()\fP, etc.). .INDENT 7.0 .TP .B Raises \fBValueError\fP \-\- if the program is live (i.e., not a core dump) .UNINDENT .UNINDENT .INDENT 7.0 .TP .B read(address: \fI\%IntegerLike\fP, size: \fI\%IntegerLike\fP, physical: bool = False) -> bytes Read \fIsize\fP bytes of memory starting at \fIaddress\fP in the program. The address may be virtual (the default) or physical if the program supports it. .sp .EX >>> prog.read(0xffffffffbe012b40, 16) b\(aqswapper/0\(aq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddress\fP \-\- The starting address. .IP \(bu 2 \fBsize\fP \-\- The number of bytes to read. .IP \(bu 2 \fBphysical\fP \-\- Whether \fIaddress\fP is a physical memory address. If \fBFalse\fP, then it is a virtual memory address. Physical memory can usually only be read when the program is an operating system kernel. .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%FaultError\fP \-\- if the address range is invalid or the type of address (physical or virtual) is not supported by the program .IP \(bu 2 \fBValueError\fP \-\- if \fIsize\fP is negative .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B read_u8(address: \fI\%IntegerLike\fP, physical: bool = False) -> int .UNINDENT .INDENT 7.0 .TP .B read_u16(address: \fI\%IntegerLike\fP, physical: bool = False) -> int .UNINDENT .INDENT 7.0 .TP .B read_u32(address: \fI\%IntegerLike\fP, physical: bool = False) -> int .UNINDENT .INDENT 7.0 .TP .B read_u64(address: \fI\%IntegerLike\fP, physical: bool = False) -> int .UNINDENT .INDENT 7.0 .TP .B read_word(address: \fI\%IntegerLike\fP, physical: bool = False) -> int Read an unsigned integer from the program\(aqs memory in the program\(aqs byte order. .sp \fI\%read_u8()\fP, \fI\%read_u16()\fP, \fI\%read_u32()\fP, and \fI\%read_u64()\fP read an 8\-, 16\-, 32\-, or 64\-bit unsigned integer, respectively. \fI\%read_word()\fP reads a program word\-sized unsigned integer. .sp For signed integers, alternate byte order, or other formats, you can use \fI\%read()\fP and \fBint.from_bytes()\fP or the \fBstruct\fP module. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddress\fP \-\- Address of the integer. .IP \(bu 2 \fBphysical\fP \-\- Whether \fIaddress\fP is a physical memory address; see \fI\%read()\fP\&. .UNINDENT .TP .B Raises \fI\%FaultError\fP \-\- if the address is invalid; see \fI\%read()\fP .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_memory_segment(address: \fI\%IntegerLike\fP, size: \fI\%IntegerLike\fP, read_fn: Callable[[int, int, int, bool], bytes], physical: bool = False) -> None Define a region of memory in the program. .sp If it overlaps a previously registered segment, the new segment takes precedence. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddress\fP \-\- Address of the segment. .IP \(bu 2 \fBsize\fP \-\- Size of the segment in bytes. .IP \(bu 2 \fBphysical\fP \-\- Whether to add a physical memory segment. If \fBFalse\fP, then this adds a virtual memory segment. .IP \(bu 2 \fBread_fn\fP \-\- 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: \fB(address, count, offset, physical)\fP\&. It should return the requested number of bytes as \fBbytes\fP or another buffer type. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_type_finder(fn: Callable[[\fI\%TypeKind\fP, str, Optional[str]], Optional[\fI\%Type\fP]]) -> None Register a callback for finding types in the program. .sp Callbacks are called in reverse order of the order they were added until the type is found. So, more recently added callbacks take precedence. .INDENT 7.0 .TP .B Parameters \fBfn\fP \-\- Callable taking a \fI\%TypeKind\fP, name, and filename: \fB(kind, name, filename)\fP\&. The filename should be matched with \fI\%filename_matches()\fP\&. This should return a \fI\%Type\fP or \fBNone\fP if not found. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B add_object_finder(fn: Callable[[\fI\%Program\fP, str, \fI\%FindObjectFlags\fP, Optional[str]], Optional[\fI\%Object\fP]]) -> None Register a callback for finding objects in the program. .sp Callbacks are called in reverse order of the order they were added until the object is found. So, more recently added callbacks take precedence. .INDENT 7.0 .TP .B Parameters \fBfn\fP \-\- Callable taking a program, name, \fI\%FindObjectFlags\fP, and filename: \fB(prog, name, flags, filename)\fP\&. The filename should be matched with \fI\%filename_matches()\fP\&. This should return an \fI\%Object\fP or \fBNone\fP if not found. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B set_core_dump(path: Union[Path, int]) -> None Set the program to a core dump. .sp This loads the memory segments from the core dump and determines the mapped executable and libraries. It does not load any debugging symbols; see \fI\%load_default_debug_info()\fP\&. .INDENT 7.0 .TP .B Parameters \fBpath\fP \-\- Core dump file path or open file descriptor. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B set_kernel() -> None Set the program to the running operating system kernel. .sp This loads the memory of the running kernel and thus requires root privileges. It does not load any debugging symbols; see \fI\%load_default_debug_info()\fP\&. .UNINDENT .INDENT 7.0 .TP .B set_pid(pid: int) -> None Set the program to a running process. .sp This loads the memory of the process and determines the mapped executable and libraries. It does not load any debugging symbols; see \fI\%load_default_debug_info()\fP\&. .INDENT 7.0 .TP .B Parameters \fBpid\fP \-\- Process ID. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B 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. .sp Note that this is parallelized, so it is usually faster to load multiple files at once rather than one by one. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpaths\fP \-\- Paths of binary files. .IP \(bu 2 \fBdefault\fP \-\- .sp Also load debugging information which can automatically be determined from the program. .sp For the Linux kernel, this tries to load \fBvmlinux\fP and any loaded kernel modules from a few standard locations. .sp For userspace programs, this tries to load the executable and any loaded libraries. .sp This implies \fBmain=True\fP\&. .IP \(bu 2 \fBmain\fP \-\- .sp Also load debugging information for the main executable. .sp For the Linux kernel, this tries to load \fBvmlinux\fP\&. .sp This is currently ignored for userspace programs. .UNINDENT .TP .B Raises \fI\%MissingDebugInfoError\fP \-\- if debugging information was not available for some files; other files with debugging information are still loaded .UNINDENT .UNINDENT .INDENT 7.0 .TP .B load_default_debug_info() -> None Load debugging information which can automatically be determined from the program. .sp This is equivalent to \fBload_debug_info(None, True)\fP\&. .UNINDENT .INDENT 7.0 .TP .B cache: Dict[Any, Any] Dictionary for caching program metadata. .sp This isn\(aqt 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: .INDENT 7.0 .INDENT 3.5 .sp .EX def my_helper(prog): try: have_foo = prog.cache[\(aqhave_foo\(aq] except KeyError: have_foo = detect_foo_feature(prog) prog.cache[\(aqhave_foo\(aq] = have_foo if have_foo: return prog[\(aqfoo\(aq] else: return prog[\(aqbar\(aq] .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.ProgramFlags Bases: \fBenum.Flag\fP .sp \fBProgramFlags\fP are flags that can apply to a \fI\%Program\fP (e.g., about what kind of program it is). .INDENT 7.0 .TP .B IS_LINUX_KERNEL The program is the Linux kernel. .UNINDENT .INDENT 7.0 .TP .B IS_LIVE The program is currently running (e.g., it is the running operating system kernel or a running process). .UNINDENT .INDENT 7.0 .TP .B IS_LOCAL The program is running on the local machine. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.FindObjectFlags Bases: \fBenum.Flag\fP .sp \fBFindObjectFlags\fP are flags for \fI\%Program.object()\fP\&. These can be combined to search for multiple kinds of objects at once. .INDENT 7.0 .TP .B CONSTANT .UNINDENT .INDENT 7.0 .TP .B FUNCTION .UNINDENT .INDENT 7.0 .TP .B VARIABLE .UNINDENT .INDENT 7.0 .TP .B ANY .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.Thread A thread in a program. .INDENT 7.0 .TP .B tid: Final[int] Thread ID (as defined by \fBgettid(2)\fP). .UNINDENT .INDENT 7.0 .TP .B object: Final[\fI\%Object\fP] If the program is the Linux kernel, the \fBstruct task_struct *\fP object for this thread. Otherwise, not defined. .UNINDENT .INDENT 7.0 .TP .B stack_trace() -> \fI\%StackTrace\fP Get the stack trace for this thread. .sp This is equivalent to \fBprog.stack_trace(thread.tid)\fP\&. See \fI\%Program.stack_trace()\fP\&. .UNINDENT .UNINDENT .SS Filenames .sp The \fI\%Program.type()\fP, \fI\%Program.object()\fP, \fI\%Program.variable()\fP, \fI\%Program.constant()\fP, and \fI\%Program.function()\fP methods all take a \fIfilename\fP 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 \fI\%filename_matches()\fP\&. If multiple definitions match, one is returned arbitrarily. .INDENT 0.0 .TP .B drgn.filename_matches(haystack: Optional[str], needle: Optional[str]) -> bool Return whether a filename containing a definition (\fIhaystack\fP) matches a filename being searched for (\fIneedle\fP). .sp The filename is matched from right to left, so \fB\(aqstdio.h\(aq\fP, \fB\(aqinclude/stdio.h\(aq\fP, \fB\(aqusr/include/stdio.h\(aq\fP, and \fB\(aq/usr/include/stdio.h\(aq\fP would all match a definition in \fB/usr/include/stdio.h\fP\&. If \fIneedle\fP is \fBNone\fP or empty, it matches any definition. If \fIhaystack\fP is \fBNone\fP or empty, it only matches if \fIneedle\fP is also \fBNone\fP or empty. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhaystack\fP \-\- Path of file containing definition. .IP \(bu 2 \fBneedle\fP \-\- Filename to match. .UNINDENT .UNINDENT .UNINDENT .SS Program Constructors .sp The drgn command line interface automatically creates a \fI\%Program\fP named \fBprog\fP\&. However, drgn may also be used as a library without the CLI, in which case a \fBProgram\fP must be created manually. .INDENT 0.0 .TP .B drgn.program_from_core_dump(path: Union[Path, int]) -> \fI\%Program\fP Create a \fI\%Program\fP from a core dump file. The type of program (e.g., userspace or kernel) is determined automatically. .INDENT 7.0 .TP .B Parameters \fBpath\fP \-\- Core dump file path or open file descriptor. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.program_from_kernel() -> \fI\%Program\fP Create a \fI\%Program\fP from the running operating system kernel. This requires root privileges. .UNINDENT .INDENT 0.0 .TP .B drgn.program_from_pid(pid: int) -> \fI\%Program\fP Create a \fI\%Program\fP from a running program with the given PID. This requires appropriate permissions (on Linux, \fBptrace(2)\fP attach permissions). .INDENT 7.0 .TP .B Parameters \fBpid\fP \-\- Process ID of the program to debug. .UNINDENT .UNINDENT .SS Default Program .sp Most functions that take a \fI\%Program\fP can be called without the \fIprog\fP argument. In that case, the \fIdefault program argument\fP is used, which is determined by the rules below. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the drgn CLI, you probably don\(aqt need to care about these details. Simply omit \fIprog\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX # Equivalent in the CLI. find_task(pid) find_task(prog, pid) find_task(prog[\(dqinit_pid_ns\(dq].address_of_(), pid) .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 If \fIprog\fP is given explicitly, either as a positional or keyword argument, then it is used. .IP 2. 3 Otherwise, if the first argument is an \fI\%Object\fP, then \fI\%Object.prog_\fP is used. .IP 3. 3 Otherwise, the \fIdefault program\fP is used. .UNINDENT .sp 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 \fI\%Thread Safety\fP\&. .INDENT 0.0 .TP .B drgn.get_default_prog() -> \fI\%Program\fP Get the default program for the current thread. .INDENT 7.0 .TP .B Raises \fI\%NoDefaultProgramError\fP \-\- if the default program is not set .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.set_default_prog(prog: Optional[\fI\%Program\fP]) -> None Set the default program for the current thread. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program to set as the default, or \fBNone\fP to unset it. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.NoDefaultProgramError Bases: \fBException\fP .sp Error raised when trying to use the default program when it is not set. .UNINDENT .sp For helpers, it is recommended to use the decorators from the \fI\%drgn.helpers.common.prog\fP module instead. .SS Platforms .INDENT 0.0 .TP .B class drgn.Platform A \fBPlatform\fP represents the environment (i.e., architecture and ABI) that a program runs on. .INDENT 7.0 .TP .B Platform(arch: \fI\%Architecture\fP, flags: Optional[\fI\%PlatformFlags\fP] = None) Create a \fBPlatform\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBarch\fP \-\- \fI\%Platform.arch\fP .IP \(bu 2 \fBflags\fP \-\- \fI\%Platform.flags\fP; if \fBNone\fP, default flags for the architecture are used. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B arch: Final[\fI\%Architecture\fP] Instruction set architecture of this platform. .UNINDENT .INDENT 7.0 .TP .B flags: Final[\fI\%PlatformFlags\fP] Flags which apply to this platform. .UNINDENT .INDENT 7.0 .TP .B registers: Final[Sequence[\fI\%Register\fP]] Processor registers on this platform. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.Architecture Bases: \fBenum.Enum\fP .sp An \fBArchitecture\fP represents an instruction set architecture. .INDENT 7.0 .TP .B X86_64 The x86\-64 architecture, a.k.a. AMD64 or Intel 64. .UNINDENT .INDENT 7.0 .TP .B I386 The 32\-bit x86 architecture, a.k.a. i386 or IA\-32. .UNINDENT .INDENT 7.0 .TP .B AARCH64 The AArch64 architecture, a.k.a. ARM64. .UNINDENT .INDENT 7.0 .TP .B ARM The 32\-bit Arm architecture. .UNINDENT .INDENT 7.0 .TP .B PPC64 The 64\-bit PowerPC architecture. .UNINDENT .INDENT 7.0 .TP .B RISCV64 The 64\-bit RISC\-V architecture. .UNINDENT .INDENT 7.0 .TP .B RISCV32 The 32\-bit RISC\-V architecture. .UNINDENT .INDENT 7.0 .TP .B S390X The s390x architecture, a.k.a. IBM Z or z/Architecture. .UNINDENT .INDENT 7.0 .TP .B S390 The 32\-bit s390 architecture, a.k.a. System/390. .UNINDENT .INDENT 7.0 .TP .B 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. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.PlatformFlags Bases: \fBenum.Flag\fP .sp \fBPlatformFlags\fP are flags describing a \fI\%Platform\fP\&. .INDENT 7.0 .TP .B IS_64_BIT Platform is 64\-bit. .UNINDENT .INDENT 7.0 .TP .B IS_LITTLE_ENDIAN Platform is little\-endian. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.Register A \fBRegister\fP represents information about a processor register. .INDENT 7.0 .TP .B names: Final[Sequence[str]] Names of this register. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.host_platform: \fI\%Platform\fP The platform of the host which is running drgn. .UNINDENT .SS Languages .INDENT 0.0 .TP .B class drgn.Language A \fBLanguage\fP represents a programming language supported by drgn. .sp This class cannot be constructed; there are singletons for the supported languages. .INDENT 7.0 .TP .B name: Final[str] Name of the programming language. .UNINDENT .INDENT 7.0 .TP .B C: ClassVar[\fI\%Language\fP] The C programming language. .UNINDENT .INDENT 7.0 .TP .B CPP: ClassVar[\fI\%Language\fP] The C++ programming language. .UNINDENT .UNINDENT .SS Objects .INDENT 0.0 .TP .B class drgn.Object An \fBObject\fP represents a symbol or value in a program. An object may exist in the memory of the program (a \fIreference\fP), it may be a constant or temporary computed value (a \fIvalue\fP), or it may be absent entirely (an \fIabsent\fP object). .sp All instances of this class have two attributes: \fI\%prog_\fP, the program that the object is from; and \fI\%type_\fP, the type of the object. Reference objects also have an \fI\%address_\fP and a \fI\%bit_offset_\fP\&. Objects may also have a \fI\%bit_field_size_\fP\&. .sp \fBrepr()\fP of an object returns a Python representation of the object: .sp .EX >>> print(repr(prog[\(aqjiffies\(aq])) Object(prog, \(aqvolatile unsigned long\(aq, address=0xffffffffbf005000) .EE .sp \fBstr()\fP returns a \(dqpretty\(dq representation of the object in programming language syntax: .sp .EX >>> print(prog[\(aqjiffies\(aq]) (volatile unsigned long)4326237045 .EE .sp The output format of \fBstr()\fP can be modified by using the \fI\%format_()\fP method instead: .sp .EX >>> sysname = prog[\(aqinit_uts_ns\(aq].name.sysname >>> print(sysname) (char [65])\(dqLinux\(dq >>> print(sysname.format_(type_name=False)) \(dqLinux\(dq >>> print(sysname.format_(string=False)) (char [65]){ 76, 105, 110, 117, 120 } .EE .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The drgn CLI is set up so that objects are displayed in the \(dqpretty\(dq format instead of with \fBrepr()\fP (the latter is the default behavior of Python\(aqs interactive mode). Therefore, it\(aqs usually not necessary to call \fBprint()\fP in the drgn CLI. .UNINDENT .UNINDENT .sp Objects support the following operators: .INDENT 7.0 .IP \(bu 2 Arithmetic operators: \fB+\fP, \fB\-\fP, \fB*\fP, \fB/\fP, \fB%\fP .IP \(bu 2 Bitwise operators: \fB<<\fP, \fB>>\fP, \fB&\fP, \fB|\fP, \fB^\fP, \fB~\fP .IP \(bu 2 Relational operators: \fB==\fP, \fB!=\fP, \fB<\fP, \fB>\fP, \fB<=\fP, \fB>=\fP .IP \(bu 2 Subscripting: \fI\%[]\fP (Python does not have a unary \fB*\fP operator, so pointers are dereferenced with \fBptr[0]\fP) .IP \(bu 2 Member access: \fI\%\&.\fP (Python does not have a \fB\->\fP operator, so \fB\&.\fP is also used to access members of pointers to structures) .IP \(bu 2 The address\-of operator: \fI\%drgn.Object.address_of_()\fP (this is a method because Python does not have a \fB&\fP operator) .IP \(bu 2 Array length: \fI\%len()\fP .UNINDENT .sp These operators all have the semantics of the program\(aqs 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: .sp .EX >>> Object(prog, \(aqunsigned long\(aq, 2**64 \- 1) + Object(prog, \(aqint\(aq, 1) Object(prog, \(aqunsigned long\(aq, value=0) .EE .sp If only one operand to a binary operator is an object, the other operand will be converted to an object according to the language\(aqs rules for literals: .sp .EX >>> Object(prog, \(aqchar\(aq, 0) \- 1 Object(prog, \(aqint\(aq, value=\-1) .EE .sp The standard \fBint()\fP, \fBfloat()\fP, and \fBbool()\fP functions convert an object to that Python type. Conversion to \fBbool\fP uses the programming language\(aqs notion of \(dqtruthiness\(dq. Additionally, certain Python functions will automatically coerce an object to the appropriate Python type (e.g., \fBhex()\fP, \fBround()\fP, and \fBlist subscripting\fP). .sp 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 \fI\%member_()\fP if there is a conflict. .sp Objects are usually obtained directly from a \fI\%Program\fP, but they can be constructed manually, as well (for example, if you got a variable address from a log file). .INDENT 7.0 .TP .B Object(prog: \fI\%Program\fP, type: Union[str, \fI\%Type\fP], value: Union[\fI\%IntegerLike\fP, float, bool, Mapping[str, Any], Sequence[Any]], *, bit_field_size: Optional[\fI\%IntegerLike\fP] = None) Create a value object given its type and value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program to create the object in. .IP \(bu 2 \fBtype\fP \-\- Type of the object. .IP \(bu 2 \fBvalue\fP \-\- Value of the object. See \fI\%value_()\fP\&. .IP \(bu 2 \fBbit_field_size\fP \-\- Size in bits of the object if it is a bit field. The default is \fBNone\fP, which means the object is not a bit field. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Object(prog: \fI\%Program\fP, *, value: Union[int, float, bool]) Create a value object from a \(dqliteral\(dq. .sp This is used to emulate a literal number in the source code of the program. The type is deduced from \fIvalue\fP according to the language\(aqs rules for literals. .INDENT 7.0 .TP .B Parameters \fBvalue\fP \-\- Value of the literal. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Object(prog: \fI\%Program\fP, type: Union[str, \fI\%Type\fP], *, address: \fI\%IntegerLike\fP, bit_offset: \fI\%IntegerLike\fP = 0, bit_field_size: Optional[\fI\%IntegerLike\fP] = None) Create a reference object. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBaddress\fP \-\- Address of the object in the program. .IP \(bu 2 \fBbit_offset\fP \-\- Offset in bits from \fIaddress\fP to the beginning of the object. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Object(prog: \fI\%Program\fP, type: Union[str, \fI\%Type\fP], *, bit_field_size: Optional[\fI\%IntegerLike\fP] = None) Create an absent object. .UNINDENT .INDENT 7.0 .TP .B prog_: Final[\fI\%Program\fP] Program that this object is from. .UNINDENT .INDENT 7.0 .TP .B type_: Final[\fI\%Type\fP] Type of this object. .UNINDENT .INDENT 7.0 .TP .B absent_: Final[bool] Whether this object is absent. .sp This is \fBFalse\fP for all values and references (even if the reference has an invalid address). .UNINDENT .INDENT 7.0 .TP .B address_: Final[Optional[int]] Address of this object if it is a reference, \fBNone\fP if it is a value or absent. .UNINDENT .INDENT 7.0 .TP .B bit_offset_: Final[Optional[int]] Offset in bits from this object\(aqs address to the beginning of the object if it is a reference, \fBNone\fP otherwise. This can only be non\-zero for scalars. .UNINDENT .INDENT 7.0 .TP .B bit_field_size_: Final[Optional[int]] Size in bits of this object if it is a bit field, \fBNone\fP if it is not. .UNINDENT .INDENT 7.0 .TP .B __getattr__(name: str) -> \fI\%Object\fP Implement \fBself.name\fP\&. .sp This corresponds to both the member access (\fB\&.\fP) and member access through pointer (\fB\->\fP) operators in C. .sp Note that if \fIname\fP is an attribute or method of the \fI\%Object\fP class, then that takes precedence. Otherwise, this is equivalent to \fI\%member_()\fP\&. .sp .EX >>> print(prog[\(aqinit_task\(aq].pid) (pid_t)0 .EE .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Attribute name. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B __getitem__(idx: \fI\%IntegerLike\fP) -> \fI\%Object\fP Implement \fBself[idx]\fP\&. Get the array element at the given index. .sp .EX >>> print(prog[\(aqinit_task\(aq].comm[1]) (char)119 .EE .sp \fB[0]\fP is also the equivalent of the pointer dereference (\fB*\fP) operator in C: .sp .EX >>> ptr_to_ptr *(void **)0xffff9b86801e2968 = 0xffff9b86801e2460 >>> print(ptr_to_ptr[0]) (void *)0xffff9b86801e2460 .EE .sp This is only valid for pointers and arrays. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Negative indices behave as they would in the object\(aqs language (as opposed to the Python semantics of indexing from the end of the array). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBidx\fP \-\- The array index. .TP .B Raises \fBTypeError\fP \-\- if this object is not a pointer or array .UNINDENT .UNINDENT .INDENT 7.0 .TP .B __len__() -> int Implement \fBlen(self)\fP\&. Get the number of elements in this object. .sp .EX >>> len(prog[\(aqinit_task\(aq].comm) 16 .EE .sp This is only valid for arrays. .INDENT 7.0 .TP .B Raises \fBTypeError\fP \-\- if this object is not an array with complete type .UNINDENT .UNINDENT .INDENT 7.0 .TP .B value_() -> Any Get the value of this object as a Python object. .sp For basic types (integer, floating\-point, boolean), this returns an object of the directly corresponding Python type (\fBint\fP, \fBfloat\fP, \fBbool\fP). For pointers, this returns the address value of the pointer. For enums, this returns an \fBint\fP\&. For structures and unions, this returns a \fBdict\fP of members. For arrays, this returns a \fBlist\fP of values. .INDENT 7.0 .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%FaultError\fP \-\- if reading the object causes a bad memory access .IP \(bu 2 \fBTypeError\fP \-\- if this object has an unreadable type (e.g., \fBvoid\fP) .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B string_() -> bytes Read a null\-terminated string pointed to by this object. .sp This is only valid for pointers and arrays. The element type is ignored; this operates byte\-by\-byte. .sp For pointers and flexible arrays, this stops at the first null byte. .sp For complete arrays, this stops at the first null byte or at the end of the array. .INDENT 7.0 .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%FaultError\fP \-\- if reading the string causes a bad memory access .IP \(bu 2 \fBTypeError\fP \-\- if this object is not a pointer or array .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B member_(name: str) -> \fI\%Object\fP Get a member of this object. .sp This is valid for structures, unions, classes, and pointers to any of those. If the object is a pointer, it is automatically dereferenced first. .sp Normally the dot operator (\fI\%\&.\fP) can be used to accomplish the same thing, but this method can be used if there is a name conflict with an \fBObject\fP attribute or method. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Name of the member. .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fBTypeError\fP \-\- if this object is not a structure, union, class, or a pointer to one of those .IP \(bu 2 \fBLookupError\fP \-\- if this object does not have a member with the given name .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B address_of_() -> \fI\%Object\fP Get a pointer to this object. .sp This corresponds to the address\-of (\fB&\fP) operator in C. It is only possible for reference objects, as value objects don\(aqt have an address in the program. .sp As opposed to \fI\%address_\fP, this returns an \fBObject\fP, not an \fBint\fP\&. .INDENT 7.0 .TP .B Raises \fBValueError\fP \-\- if this object is a value .UNINDENT .UNINDENT .INDENT 7.0 .TP .B read_() -> \fI\%Object\fP Read this object (which may be a reference or a value) and return it as a value object. .sp 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). .sp As opposed to \fI\%value_()\fP, this returns an \fBObject\fP, not a standard Python type. .INDENT 7.0 .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fI\%FaultError\fP \-\- if reading this object causes a bad memory access .IP \(bu 2 \fBTypeError\fP \-\- if this object has an unreadable type (e.g., \fBvoid\fP) .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B to_bytes_() -> bytes Return the binary representation of this object\(aqs value. .UNINDENT .INDENT 7.0 .TP .B classmethod from_bytes_(prog: \fI\%Program\fP, type: Union[str, \fI\%Type\fP], bytes: bytes, *, bit_offset: \fI\%IntegerLike\fP = 0, bit_field_size: Optional[\fI\%IntegerLike\fP] = None) -> \fI\%Object\fP Return a value object from its binary representation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program to create the object in. .IP \(bu 2 \fBtype\fP \-\- Type of the object. .IP \(bu 2 \fBbytes\fP \-\- Buffer containing value of the object. .IP \(bu 2 \fBbit_offset\fP \-\- Offset in bits from the beginning of \fIbytes\fP to the beginning of the object. .IP \(bu 2 \fBbit_field_size\fP \-\- Size in bits of the object if it is a bit field. The default is \fBNone\fP, which means the object is not a bit field. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B format_(*, columns: Optional[\fI\%IntegerLike\fP] = 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. .sp Various format options can be passed (as keyword arguments) to control the output. Options that aren\(aqt passed or are passed as \fBNone\fP fall back to a default. Specifically, \fBobj.format_()\fP (i.e., with no passed options) is equivalent to \fBstr(obj)\fP\&. .sp .EX >>> workqueues = prog[\(aqworkqueues\(aq] >>> 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 } .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcolumns\fP \-\- Number of columns to limit output to when the expression can be reasonably wrapped. Defaults to no limit. .IP \(bu 2 \fBdereference\fP \-\- 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 \fBTrue\fP\&. .IP \(bu 2 \fBsymbolize\fP \-\- Include a symbol name and offset for pointer objects. Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBstring\fP \-\- Format the values of objects with string type as strings. For C, this applies to pointers to and arrays of \fBchar\fP, \fBsigned char\fP, and \fBunsigned char\fP\&. Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBchar\fP \-\- Format objects with character type as character literals. For C, this applies to \fBchar\fP, \fBsigned char\fP, and \fBunsigned char\fP\&. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBtype_name\fP \-\- Include the type name of this object. Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBmember_type_names\fP \-\- Include the type names of structure, union, and class members. Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBelement_type_names\fP \-\- Include the type names of array elements. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBmembers_same_line\fP \-\- Place multiple structure, union, and class members on the same line if they fit within the specified number of \fBcolumns\fP\&. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBelements_same_line\fP \-\- Place multiple array elements on the same line if they fit within the specified number of \fBcolumns\fP\&. Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBmember_names\fP \-\- Include the names of structure, union, and class members. Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBelement_indices\fP \-\- Include the indices of array elements. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBimplicit_members\fP \-\- Include structure, union, and class members which have an implicit value (i.e., for C, zero\-initialized). Defaults to \fBTrue\fP\&. .IP \(bu 2 \fBimplicit_elements\fP \-\- Include array elements which have an implicit value (i.e., for C, zero\-initialized). Defaults to \fBFalse\fP\&. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.NULL(prog: \fI\%Program\fP, type: Union[str, \fI\%Type\fP]) -> \fI\%Object\fP Get an object representing \fBNULL\fP casted to the given type. .sp This is equivalent to \fBObject(prog, type, 0)\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- The program. .IP \(bu 2 \fBtype\fP \-\- The type. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.cast(type: Union[str, \fI\%Type\fP], obj: \fI\%Object\fP) -> \fI\%Object\fP Get the value of the given object casted to another type. .sp Objects with a scalar type (integer, boolean, enumerated, floating\-point, or pointer) can be casted to a different scalar type. Other objects can only be casted to the same type. This always results in a value object. See also \fI\%drgn.reinterpret()\fP\&. .sp .EX >>> cast(\(dqunsigned int\(dq, Object(prog, \(dqfloat\(dq, 2.0)) (unsigned int)2 .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Type to cast to. .IP \(bu 2 \fBobj\fP \-\- Object to cast. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.reinterpret(type: Union[str, \fI\%Type\fP], obj: \fI\%Object\fP) -> \fI\%Object\fP Get the representation of an object reinterpreted as another type. .sp This reinterprets the raw memory of the object, so an object can be reinterpreted as any other type. Reinterpreting a reference results in a reference, and reinterpreting a value results in a value. See also \fI\%drgn.cast()\fP\&. .sp .EX >>> reinterpret(\(dqunsigned int\(dq, Object(prog, \(dqfloat\(dq, 2.0)) (unsigned int)1073741824 .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Type to reinterpret as. .IP \(bu 2 \fBobj\fP \-\- Object to reinterpret. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.container_of(ptr: \fI\%Object\fP, type: Union[str, \fI\%Type\fP], member: str) -> \fI\%Object\fP Get the containing object of a pointer object. .sp This corresponds to the \fBcontainer_of()\fP macro in C. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBptr\fP \-\- Pointer to member in containing object. .IP \(bu 2 \fBtype\fP \-\- Type of containing object. .IP \(bu 2 \fBmember\fP \-\- Name of member in containing object. May include one or more member references and zero or more array subscripts. .UNINDENT .TP .B Returns Pointer to containing object. .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fBTypeError\fP \-\- if \fIptr\fP is not a pointer or \fItype\fP is not a structure, union, or class type .IP \(bu 2 \fBValueError\fP \-\- if the member is not byte\-aligned (e.g., because it is a bit field) .IP \(bu 2 \fBLookupError\fP \-\- if \fItype\fP does not have a member with the given name .UNINDENT .UNINDENT .UNINDENT .SS Symbols .INDENT 0.0 .TP .B class drgn.Symbol A \fBSymbol\fP represents an entry in the symbol table of a program, i.e., an identifier along with its corresponding address range in the program. .INDENT 7.0 .TP .B name: Final[str] Name of this symbol. .UNINDENT .INDENT 7.0 .TP .B address: Final[int] Start address of this symbol. .UNINDENT .INDENT 7.0 .TP .B size: Final[int] Size of this symbol in bytes. .UNINDENT .INDENT 7.0 .TP .B binding: Final[\fI\%SymbolBinding\fP] Linkage behavior and visibility of this symbol. .UNINDENT .INDENT 7.0 .TP .B kind: Final[\fI\%SymbolKind\fP] Kind of entity represented by this symbol. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.SymbolBinding Bases: \fBenum.Enum\fP .sp A \fBSymbolBinding\fP describes the linkage behavior and visibility of a symbol. .INDENT 7.0 .TP .B UNKNOWN Unknown. .UNINDENT .INDENT 7.0 .TP .B LOCAL Not visible outside of the object file containing its definition. .UNINDENT .INDENT 7.0 .TP .B GLOBAL Globally visible. .UNINDENT .INDENT 7.0 .TP .B WEAK Globally visible but may be overridden by a non\-weak global symbol. .UNINDENT .INDENT 7.0 .TP .B UNIQUE Globally visible even if dynamic shared object is loaded locally. See GCC\(aqs \fB\-fno\-gnu\-unique\fP \fI\%option\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.SymbolKind Bases: \fBenum.Enum\fP .sp A \fBSymbolKind\fP describes the kind of entity that a symbol represents. .INDENT 7.0 .TP .B UNKNOWN Unknown or not defined. .UNINDENT .INDENT 7.0 .TP .B OBJECT Data object (e.g., variable or array). .UNINDENT .INDENT 7.0 .TP .B FUNC Function or other executable code. .UNINDENT .INDENT 7.0 .TP .B SECTION Object file section. .UNINDENT .INDENT 7.0 .TP .B FILE Source file. .UNINDENT .INDENT 7.0 .TP .B COMMON Data object in common block. .UNINDENT .INDENT 7.0 .TP .B TLS Thread\-local storage entity. .UNINDENT .INDENT 7.0 .TP .B IFUNC \fI\%Indirect function\fP\&. .UNINDENT .UNINDENT .SS Stack Traces .sp Stack traces are retrieved with \fI\%stack_trace()\fP, \fI\%Program.stack_trace()\fP, or \fI\%Thread.stack_trace()\fP\&. .INDENT 0.0 .TP .B drgn.stack_trace(thread: Union[\fI\%Object\fP, \fI\%IntegerLike\fP]) -> \fI\%StackTrace\fP Get the stack trace for the given thread using the \fI\%default program argument\fP\&. .sp See \fI\%Program.stack_trace()\fP for more details. .INDENT 7.0 .TP .B Parameters \fBthread\fP \-\- Thread ID, \fBstruct pt_regs\fP object, or \fBstruct task_struct *\fP object. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.StackTrace A \fBStackTrace\fP is a sequence of \fI\%StackFrame\fP\&. .sp \fBlen(trace)\fP is the number of stack frames in the trace. \fBtrace[0]\fP is the innermost stack frame, \fBtrace[1]\fP is its caller, and \fBtrace[len(trace) \- 1]\fP is the outermost frame. Negative indexing also works: \fBtrace[\-1]\fP is the outermost frame and \fBtrace[\-len(trace)]\fP is the innermost frame. It is also iterable: .INDENT 7.0 .INDENT 3.5 .sp .EX for frame in trace: if frame.name == \(aqio_schedule\(aq: print(\(aqThread is doing I/O\(aq) .EE .UNINDENT .UNINDENT .sp \fBstr()\fP returns a pretty\-printed stack trace: .sp .EX >>> 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 .EE .sp The format is subject to change. The drgn CLI is set up so that stack traces are displayed with \fBstr()\fP by default. .INDENT 7.0 .TP .B prog: Final[\fI\%Program\fP] Program that this stack trace is from. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.StackFrame A \fBStackFrame\fP represents a single \fIframe\fP in a thread\(aqs call stack. .sp \fBstr()\fP returns a pretty\-printed stack frame: .sp .EX >>> prog.stack_trace(1)[0] #0 at 0xffffffffb64ac287 (__schedule+0x227/0x606) in context_switch at kernel/sched/core.c:4339:2 (inlined) .EE .sp 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 \fBstr()\fP by default. .sp The \fI\%[]\fP operator can look up function parameters, local variables, and global variables in the scope of the stack frame: .sp .EX >>> prog.stack_trace(1)[0][\(aqprev\(aq].pid (pid_t)1 >>> prog.stack_trace(1)[0][\(aqscheduler_running\(aq] (int)1 .EE .INDENT 7.0 .TP .B name: Final[Optional[str]] Name of the function at this frame, or \fBNone\fP if it could not be determined. .sp 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: .INDENT 7.0 .INDENT 3.5 .sp .EX name = frame.name if name is None: try: name = frame.symbol().name except LookupError: name = hex(frame.pc) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B is_inline: Final[bool] Whether this frame is for an inlined call. .sp 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). .UNINDENT .INDENT 7.0 .TP .B interrupted: Final[bool] Whether this stack frame was interrupted (for example, by a hardware interrupt, signal, trap, etc.). .sp If this is \fBTrue\fP, then the register values in this frame are the values at the time that the frame was interrupted. .sp This is \fBFalse\fP 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. .UNINDENT .INDENT 7.0 .TP .B pc: Final[int] Program counter at this stack frame. .UNINDENT .INDENT 7.0 .TP .B sp: Final[int] Stack pointer at this stack frame. .UNINDENT .INDENT 7.0 .TP .B __getitem__(name: str) -> \fI\%Object\fP Implement \fBself[name]\fP\&. Get the object (variable, function parameter, constant, or function) with the given name in the scope of this frame. .sp If the object exists but has been optimized out, this returns an \fI\%absent object\fP\&. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Object name. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B __contains__(name: str) -> bool Implement \fBname in self\fP\&. Return whether an object with the given name exists in the scope of this frame. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Object name. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B 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. .sp Not all names may have present values, but they can be used with the \fI\%[]\fP operator to check. .UNINDENT .INDENT 7.0 .TP .B source() -> Tuple[str, int, int] Get the source code location of this frame. .INDENT 7.0 .TP .B Returns Location as a \fB(filename, line, column)\fP triple. .TP .B Raises \fBLookupError\fP \-\- if the source code location is not available .UNINDENT .UNINDENT .INDENT 7.0 .TP .B symbol() -> \fI\%Symbol\fP Get the function symbol at this stack frame. .sp This is equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .EX prog.symbol(frame.pc \- (0 if frame.interrupted else 1)) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B register(reg: str) -> int Get the value of the given register at this stack frame. .INDENT 7.0 .TP .B Parameters \fBreg\fP \-\- Register name. .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fBValueError\fP \-\- if the register name is not recognized .IP \(bu 2 \fBLookupError\fP \-\- if the register value is not known .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B registers() -> Dict[str, int] Get the values of all available registers at this stack frame as a dictionary with the register names as keys. .UNINDENT .UNINDENT .SS Types .INDENT 0.0 .TP .B class drgn.Type A \fBType\fP 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 \fBAttributeError\fP\&. .sp \fBrepr()\fP of a \fBType\fP returns a Python representation of the type: .sp .EX >>> print(repr(prog.type(\(aqsector_t\(aq))) prog.typedef_type(name=\(aqsector_t\(aq, type=prog.int_type(name=\(aqunsigned long\(aq, size=8, is_signed=False)) .EE .sp \fBstr()\fP returns a representation of the type in programming language syntax: .sp .EX >>> print(prog.type(\(aqsector_t\(aq)) typedef unsigned long sector_t .EE .sp The drgn CLI is set up so that types are displayed with \fBstr()\fP instead of \fBrepr()\fP by default. .sp This class cannot be constructed directly. Instead, use one of the \fI\%Type Constructors\fP\&. .INDENT 7.0 .TP .B prog: Final[\fI\%Program\fP] Program that this type is from. .UNINDENT .INDENT 7.0 .TP .B kind: Final[\fI\%TypeKind\fP] Kind of this type. .UNINDENT .INDENT 7.0 .TP .B primitive: Final[Optional[\fI\%PrimitiveType\fP]] If this is a primitive type (e.g., \fBint\fP or \fBdouble\fP), the kind of primitive type. Otherwise, \fBNone\fP\&. .UNINDENT .INDENT 7.0 .TP .B qualifiers: Final[\fI\%Qualifiers\fP] Bitmask of this type\(aqs qualifier. .UNINDENT .INDENT 7.0 .TP .B language: Final[\fI\%Language\fP] Programming language of this type. .UNINDENT .INDENT 7.0 .TP .B name: Final[str] Name of this type. This is present for integer, boolean, floating\-point, and typedef types. .UNINDENT .INDENT 7.0 .TP .B tag: Final[Optional[str]] Tag of this type, or \fBNone\fP if this is an anonymous type. This is present for structure, union, class, and enumerated types. .UNINDENT .INDENT 7.0 .TP .B size: Final[Optional[int]] Size of this type in bytes, or \fBNone\fP if this is an incomplete type. This is present for integer, boolean, floating\-point, structure, union, class, and pointer types. .UNINDENT .INDENT 7.0 .TP .B length: Final[Optional[int]] Number of elements in this type, or \fBNone\fP if this is an incomplete type. This is only present for array types. .UNINDENT .INDENT 7.0 .TP .B is_signed: Final[bool] Whether this type is signed. This is only present for integer types. .UNINDENT .INDENT 7.0 .TP .B byteorder: Final[str] Byte order of this type: \fB\(aqlittle\(aq\fP if it is little\-endian, or \fB\(aqbig\(aq\fP if it is big\-endian. This is present for integer, boolean, floating\-point, and pointer types. .UNINDENT .INDENT 7.0 .TP .B type: Final[\fI\%Type\fP] Type underlying this type, defined as follows: .INDENT 7.0 .IP \(bu 2 For typedef types, the aliased type. .IP \(bu 2 For enumerated types, the compatible integer type, which is \fBNone\fP if this is an incomplete type. .IP \(bu 2 For pointer types, the referenced type. .IP \(bu 2 For array types, the element type. .IP \(bu 2 For function types, the return type. .UNINDENT .sp For other types, this attribute is not present. .UNINDENT .INDENT 7.0 .TP .B members: Final[Optional[Sequence[\fI\%TypeMember\fP]]] List of members of this type, or \fBNone\fP if this is an incomplete type. This is present for structure, union, and class types. .UNINDENT .INDENT 7.0 .TP .B enumerators: Final[Optional[Sequence[\fI\%TypeEnumerator\fP]]] List of enumeration constants of this type, or \fBNone\fP if this is an incomplete type. This is only present for enumerated types. .UNINDENT .INDENT 7.0 .TP .B parameters: Final[Sequence[\fI\%TypeParameter\fP]] List of parameters of this type. This is only present for function types. .UNINDENT .INDENT 7.0 .TP .B is_variadic: Final[bool] Whether this type takes a variable number of arguments. This is only present for function types. .UNINDENT .INDENT 7.0 .TP .B template_parameters: Final[Sequence[\fI\%TypeTemplateParameter\fP]] List of template parameters of this type. This is present for structure, union, class, and function types. .UNINDENT .INDENT 7.0 .TP .B type_name() -> str Get a descriptive full name of this type. .UNINDENT .INDENT 7.0 .TP .B is_complete() -> bool Get whether this type is complete (i.e., the type definition is known). This is always \fBFalse\fP for void types. It may be \fBFalse\fP 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 \fBTrue\fP\&. .UNINDENT .INDENT 7.0 .TP .B qualified(qualifiers: \fI\%Qualifiers\fP) -> \fI\%Type\fP Get a copy of this type with different qualifiers. .sp Note that the original qualifiers are replaced, not added to. .INDENT 7.0 .TP .B Parameters \fBqualifiers\fP \-\- New type qualifiers. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B unqualified() -> \fI\%Type\fP Get a copy of this type with no qualifiers. .UNINDENT .INDENT 7.0 .TP .B member(name: str) -> \fI\%TypeMember\fP Look up a member in this type by name. .sp 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, \fI\%TypeMember.bit_offset\fP and \fI\%TypeMember.offset\fP are adjusted accordingly. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Name of the member. .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fBTypeError\fP \-\- if this type is not a structure, union, or class type .IP \(bu 2 \fBLookupError\fP \-\- if this type does not have a member with the given name .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B has_member(name: str) -> bool Return whether this type has a member with the given name. .sp If this type has any unnamed members, this also matches members of those unnamed members, recursively. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Name of the member. .TP .B Raises \fBTypeError\fP \-\- if this type is not a structure, union, or class type .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.TypeMember A \fBTypeMember\fP represents a member of a structure, union, or class type. .INDENT 7.0 .TP .B TypeMember(object_or_type: Union[\fI\%Object\fP, \fI\%Type\fP, Callable[[], Union[\fI\%Object\fP, \fI\%Type\fP]]], name: Optional[str] = None, bit_offset: int = 0) Create a \fBTypeMember\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBobject_or_type\fP \-\- .sp One of: .INDENT 2.0 .IP 1. 3 \fI\%TypeMember.object\fP as an \fI\%Object\fP\&. .IP 2. 3 \fI\%TypeMember.type\fP as a \fI\%Type\fP\&. In this case, \fBobject\fP is set to an absent object with that type. .IP 3. 3 A callable that takes no arguments and returns one of the above. It is called when \fBobject\fP or \fBtype\fP is first accessed, and the result is cached. .UNINDENT .IP \(bu 2 \fBname\fP \-\- \fI\%TypeMember.name\fP .IP \(bu 2 \fBbit_offset\fP \-\- \fI\%TypeMember.bit_offset\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B object: Final[\fI\%Object\fP] Member as an \fI\%Object\fP\&. .sp 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.) .UNINDENT .INDENT 7.0 .TP .B type: Final[\fI\%Type\fP] Member type. .sp This is a shortcut for \fBTypeMember.object.type\fP\&. .UNINDENT .INDENT 7.0 .TP .B name: Final[Optional[str]] Member name, or \fBNone\fP if the member is unnamed. .UNINDENT .INDENT 7.0 .TP .B bit_offset: Final[int] Offset of the member from the beginning of the type in bits. .UNINDENT .INDENT 7.0 .TP .B 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 \fBValueError\fP\&. .UNINDENT .INDENT 7.0 .TP .B bit_field_size: Final[Optional[int]] Size in bits of this member if it is a bit field, \fBNone\fP if it is not. .sp This is a shortcut for \fBTypeMember.object.bit_field_size_\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.TypeEnumerator A \fBTypeEnumerator\fP represents a constant in an enumerated type. .sp Its name and value may be accessed as attributes or unpacked: .sp .EX >>> prog.type(\(aqenum pid_type\(aq).enumerators[0].name \(aqPIDTYPE_PID\(aq >>> name, value = prog.type(\(aqenum pid_type\(aq).enumerators[0] >>> value 0 .EE .INDENT 7.0 .TP .B TypeEnumerator(name: str, value: int) Create a \fBTypeEnumerator\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- \fI\%TypeEnumerator.name\fP .IP \(bu 2 \fBvalue\fP \-\- \fI\%TypeEnumerator.value\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Final[str] Enumerator name. .UNINDENT .INDENT 7.0 .TP .B value: Final[int] Enumerator value. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.TypeParameter A \fBTypeParameter\fP represents a parameter of a function type. .INDENT 7.0 .TP .B TypeParameter(default_argument_or_type: Union[\fI\%Object\fP, \fI\%Type\fP, Callable[[], Union[\fI\%Object\fP, \fI\%Type\fP]]], name: Optional[str] = None) Create a \fBTypeParameter\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdefault_argument_or_type\fP \-\- .sp One of: .INDENT 2.0 .IP 1. 3 \fI\%TypeParameter.default_argument\fP as an \fI\%Object\fP\&. .IP 2. 3 \fI\%TypeParameter.type\fP as a \fI\%Type\fP\&. In this case, \fBdefault_argument\fP is set to an absent object with that type. .IP 3. 3 A callable that takes no arguments and returns one of the above. It is called when \fBdefault_argument\fP or \fBtype\fP is first accessed, and the result is cached. .UNINDENT .IP \(bu 2 \fBname\fP \-\- \fI\%TypeParameter.name\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B default_argument: Final[\fI\%Object\fP] Default argument for parameter. .sp If the parameter does not have a default argument, then this is an absent object. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B type: Final[\fI\%Type\fP] Parameter type. .sp This is the same as \fBTypeParameter.default_argument.type_\fP\&. .UNINDENT .INDENT 7.0 .TP .B name: Final[Optional[str]] Parameter name, or \fBNone\fP if the parameter is unnamed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.TypeTemplateParameter A \fBTypeTemplateParameter\fP represents a template parameter of a structure, union, class, or function type. .INDENT 7.0 .TP .B TypeTemplateParameter(argument: Union[\fI\%Type\fP, \fI\%Object\fP, Callable[[], Union[\fI\%Type\fP, \fI\%Object\fP]]], name: Optional[str] = None, is_default: bool = False) Create a \fBTypeTemplateParameter\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBargument\fP \-\- .sp One of: .INDENT 2.0 .IP 1. 3 \fI\%TypeTemplateParameter.argument\fP as a \fI\%Type\fP if the parameter is a type template parameter. .IP 2. 3 \fI\%TypeTemplateParameter.argument\fP as a non\-absent \fI\%Object\fP if the parameter is a non\-type template parameter. .IP 3. 3 A callable that takes no arguments and returns one of the above. It is called when \fBargument\fP is first accessed, and the result is cached. .UNINDENT .IP \(bu 2 \fBname\fP \-\- \fI\%TypeTemplateParameter.name\fP .IP \(bu 2 \fBis_default\fP \-\- \fI\%TypeTemplateParameter.is_default\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B argument: Final[Union[\fI\%Type\fP, \fI\%Object\fP]] Template argument. .sp If this is a type template parameter, then this is a \fI\%Type\fP\&. If this is a non\-type template parameter, then this is an \fI\%Object\fP\&. .UNINDENT .INDENT 7.0 .TP .B name: Final[Optional[str]] Template parameter name, or \fBNone\fP if the parameter is unnamed. .UNINDENT .INDENT 7.0 .TP .B is_default: Final[bool] Whether \fI\%argument\fP is the default for the template parameter. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 There are two ways to interpret this: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 The argument was omitted entirely and thus defaulted to the default argument. .IP 2. 3 The (specified or defaulted) argument is the same as the default argument. .UNINDENT .UNINDENT .UNINDENT .sp Compilers are inconsistent about which interpretation they use. .sp 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. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.TypeKind Bases: \fBenum.Enum\fP .sp A \fBTypeKind\fP represents a kind of type. .INDENT 7.0 .TP .B VOID Void type. .UNINDENT .INDENT 7.0 .TP .B INT Integer type. .UNINDENT .INDENT 7.0 .TP .B BOOL Boolean type. .UNINDENT .INDENT 7.0 .TP .B FLOAT Floating\-point type. .UNINDENT .INDENT 7.0 .TP .B COMPLEX Complex type. .UNINDENT .INDENT 7.0 .TP .B STRUCT Structure type. .UNINDENT .INDENT 7.0 .TP .B UNION Union type. .UNINDENT .INDENT 7.0 .TP .B CLASS Class type. .UNINDENT .INDENT 7.0 .TP .B ENUM Enumerated type. .UNINDENT .INDENT 7.0 .TP .B TYPEDEF Type definition (a.k.a. alias) type. .UNINDENT .INDENT 7.0 .TP .B POINTER Pointer type. .UNINDENT .INDENT 7.0 .TP .B ARRAY Array type. .UNINDENT .INDENT 7.0 .TP .B FUNCTION Function type. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.PrimitiveType Bases: \fBenum.Enum\fP .sp A \fBPrimitiveType\fP represents a primitive type known to drgn. .INDENT 7.0 .TP .B C_VOID .UNINDENT .INDENT 7.0 .TP .B C_CHAR .UNINDENT .INDENT 7.0 .TP .B C_SIGNED_CHAR .UNINDENT .INDENT 7.0 .TP .B C_UNSIGNED_CHAR .UNINDENT .INDENT 7.0 .TP .B C_SHORT .UNINDENT .INDENT 7.0 .TP .B C_UNSIGNED_SHORT .UNINDENT .INDENT 7.0 .TP .B C_INT .UNINDENT .INDENT 7.0 .TP .B C_UNSIGNED_INT .UNINDENT .INDENT 7.0 .TP .B C_LONG .UNINDENT .INDENT 7.0 .TP .B C_UNSIGNED_LONG .UNINDENT .INDENT 7.0 .TP .B C_LONG_LONG .UNINDENT .INDENT 7.0 .TP .B C_UNSIGNED_LONG_LONG .UNINDENT .INDENT 7.0 .TP .B C_BOOL .UNINDENT .INDENT 7.0 .TP .B C_FLOAT .UNINDENT .INDENT 7.0 .TP .B C_DOUBLE .UNINDENT .INDENT 7.0 .TP .B C_LONG_DOUBLE .UNINDENT .INDENT 7.0 .TP .B C_SIZE_T .UNINDENT .INDENT 7.0 .TP .B C_PTRDIFF_T .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.Qualifiers Bases: \fBenum.Flag\fP .sp \fBQualifiers\fP are modifiers on types. .INDENT 7.0 .TP .B NONE No qualifiers. .UNINDENT .INDENT 7.0 .TP .B CONST Constant type. .UNINDENT .INDENT 7.0 .TP .B VOLATILE Volatile type. .UNINDENT .INDENT 7.0 .TP .B RESTRICT \fI\%Restrict\fP type. .UNINDENT .INDENT 7.0 .TP .B ATOMIC Atomic type. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.offsetof(type: \fI\%Type\fP, member: str) -> int Get the offset (in bytes) of a member in a \fI\%Type\fP\&. .sp This corresponds to \fI\%offsetof()\fP in C. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Structure, union, or class type. .IP \(bu 2 \fBmember\fP \-\- Name of member. May include one or more member references and zero or more array subscripts. .UNINDENT .TP .B Raises .INDENT 7.0 .IP \(bu 2 \fBTypeError\fP \-\- if \fItype\fP is not a structure, union, or class type .IP \(bu 2 \fBValueError\fP \-\- if the member is not byte\-aligned (e.g., because it is a bit field) .IP \(bu 2 \fBLookupError\fP \-\- if \fItype\fP does not have a member with the given name .UNINDENT .UNINDENT .UNINDENT .SS Type Constructors .sp Custom drgn types can be created with the following factory functions. These can be used just like types obtained from \fI\%Program.type()\fP\&. .INDENT 0.0 .TP .B Program.void_type(*, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new void type. It has kind \fI\%TypeKind.VOID\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.int_type(name: str, size: \fI\%IntegerLike\fP, is_signed: bool, byteorder: Optional[str] = None, *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new integer type. It has kind \fI\%TypeKind.INT\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- \fI\%Type.name\fP .IP \(bu 2 \fBsize\fP \-\- \fI\%Type.size\fP .IP \(bu 2 \fBis_signed\fP \-\- \fI\%Type.is_signed\fP .IP \(bu 2 \fBbyteorder\fP \-\- \fI\%Type.byteorder\fP, or \fBNone\fP to use the program\(aqs default byte order. .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.bool_type(name: str, size: \fI\%IntegerLike\fP, byteorder: Optional[str] = None, *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new boolean type. It has kind \fI\%TypeKind.BOOL\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- \fI\%Type.name\fP .IP \(bu 2 \fBsize\fP \-\- \fI\%Type.size\fP .IP \(bu 2 \fBbyteorder\fP \-\- \fI\%Type.byteorder\fP, or \fBNone\fP to use the program\(aqs default byte order. .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.float_type(name: str, size: \fI\%IntegerLike\fP, byteorder: Optional[str] = None, *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new floating\-point type. It has kind \fI\%TypeKind.FLOAT\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- \fI\%Type.name\fP .IP \(bu 2 \fBsize\fP \-\- \fI\%Type.size\fP .IP \(bu 2 \fBbyteorder\fP \-\- \fI\%Type.byteorder\fP, or \fBNone\fP to use the program\(aqs default byte order. .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.struct_type(tag: Optional[str], size: \fI\%IntegerLike\fP, members: Sequence[\fI\%TypeMember\fP], *, template_parameters: Sequence[\fI\%TypeTemplateParameter\fP] = (), qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new structure type. It has kind \fI\%TypeKind.STRUCT\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtag\fP \-\- \fI\%Type.tag\fP .IP \(bu 2 \fBsize\fP \-\- \fI\%Type.size\fP .IP \(bu 2 \fBmembers\fP \-\- \fI\%Type.members\fP .IP \(bu 2 \fBtemplate_parameters\fP \-\- \fI\%Type.template_parameters\fP .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.struct_type(tag: Optional[str], size: None = None, members: None = None, *, template_parameters: Sequence[\fI\%TypeTemplateParameter\fP] = (), qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new incomplete structure type. .UNINDENT .INDENT 0.0 .TP .B Program.union_type(tag: Optional[str], size: \fI\%IntegerLike\fP, members: Sequence[\fI\%TypeMember\fP], *, template_parameters: Sequence[\fI\%TypeTemplateParameter\fP] = (), qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new union type. It has kind \fI\%TypeKind.UNION\fP\&. Otherwise, this is the same as as \fI\%struct_type()\fP\&. .UNINDENT .INDENT 0.0 .TP .B Program.union_type(tag: Optional[str], size: None = None, members: None = None, *, template_parameters: Sequence[\fI\%TypeTemplateParameter\fP] = (), qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new incomplete union type. .UNINDENT .INDENT 0.0 .TP .B Program.class_type(tag: Optional[str], size: \fI\%IntegerLike\fP, members: Sequence[\fI\%TypeMember\fP], *, template_parameters: Sequence[\fI\%TypeTemplateParameter\fP] = (), qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new class type. It has kind \fI\%TypeKind.CLASS\fP\&. Otherwise, this is the same as as \fI\%struct_type()\fP\&. .UNINDENT .INDENT 0.0 .TP .B Program.class_type(tag: Optional[str], size: None = None, members: None = None, *, template_parameters: Sequence[\fI\%TypeTemplateParameter\fP] = (), qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new incomplete class type. .UNINDENT .INDENT 0.0 .TP .B Program.enum_type(tag: Optional[str], type: \fI\%Type\fP, enumerators: Sequence[\fI\%TypeEnumerator\fP], *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new enumerated type. It has kind \fI\%TypeKind.ENUM\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtag\fP \-\- \fI\%Type.tag\fP .IP \(bu 2 \fBtype\fP \-\- The compatible integer type (\fI\%Type.type\fP) .IP \(bu 2 \fBenumerators\fP \-\- \fI\%Type.enumerators\fP .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.enum_type(tag: Optional[str], type: None = None, enumerators: None = None, *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new incomplete enumerated type. .UNINDENT .INDENT 0.0 .TP .B Program.typedef_type(name: str, type: \fI\%Type\fP, *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new typedef type. It has kind \fI\%TypeKind.TYPEDEF\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- \fI\%Type.name\fP .IP \(bu 2 \fBtype\fP \-\- The aliased type (\fI\%Type.type\fP) .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.pointer_type(type: \fI\%Type\fP, size: Optional[int] = None, byteorder: Optional[str] = None, *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new pointer type. It has kind \fI\%TypeKind.POINTER\fP, .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- The referenced type (\fI\%Type.type\fP) .IP \(bu 2 \fBsize\fP \-\- \fI\%Type.size\fP, or \fBNone\fP to use the program\(aqs default pointer size. .IP \(bu 2 \fBbyteorder\fP \-\- \fI\%Type.byteorder\fP, or \fBNone\fP to use the program\(aqs default byte order. .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.array_type(type: \fI\%Type\fP, length: Optional[int] = None, *, qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new array type. It has kind \fI\%TypeKind.ARRAY\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- The element type (\fI\%Type.type\fP) .IP \(bu 2 \fBlength\fP \-\- \fI\%Type.length\fP .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Program.function_type(type: \fI\%Type\fP, parameters: Sequence[\fI\%TypeParameter\fP], is_variadic: bool = False, *, template_parameters: Sequence[\fI\%TypeTemplateParameter\fP] = (), qualifiers: \fI\%Qualifiers\fP = Qualifiers.NONE, language: Optional[\fI\%Language\fP] = None) -> \fI\%Type\fP Create a new function type. It has kind \fI\%TypeKind.FUNCTION\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- The return type (\fI\%Type.type\fP) .IP \(bu 2 \fBparameters\fP \-\- \fI\%Type.parameters\fP .IP \(bu 2 \fBis_variadic\fP \-\- \fI\%Type.is_variadic\fP .IP \(bu 2 \fBtemplate_parameters\fP \-\- \fI\%Type.template_parameters\fP .IP \(bu 2 \fBqualifiers\fP \-\- \fI\%Type.qualifiers\fP .IP \(bu 2 \fBlang\fP \-\- \fI\%Type.language\fP .UNINDENT .UNINDENT .UNINDENT .SS Miscellaneous .INDENT 0.0 .TP .B drgn.sizeof(type_or_obj: Union[\fI\%Type\fP, \fI\%Object\fP]) -> int Get the size of a \fI\%Type\fP or \fI\%Object\fP in bytes. .INDENT 7.0 .TP .B Parameters \fBtype_or_obj\fP \-\- Entity to get the size of. .TP .B Raises \fBTypeError\fP \-\- if the type does not have a size (e.g., because it is incomplete or void) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.execscript(path: str, *args: str) -> None Execute a script. .sp 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. .sp This is most useful for executing scripts from interactive mode. For example, you could have a script named \fBexe.py\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX \(dq\(dq\(dqGet all tasks executing a given file.\(dq\(dq\(dq 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] ] .EE .UNINDENT .UNINDENT .sp Then, you could execute it and use the defined variables and functions: .sp .EX >>> execscript(\(aqexe.py\(aq, \(aq/usr/bin/bash\(aq) >>> tasks[0].pid (pid_t)358442 >>> task_exe_path(find_task(357954)) \(aq/usr/bin/vim\(aq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- File path of the script. .IP \(bu 2 \fBargs\fP \-\- Zero or more additional arguments to pass to the script. This is a variable argument list\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.IntegerLike Bases: \fBProtocol\fP .sp An \fBint\fP or integer\-like object. .sp Parameters annotated with this type expect an integer which may be given as a Python \fBint\fP or an \fI\%Object\fP with integer type. .UNINDENT .INDENT 0.0 .TP .B drgn.Path: TypeAlias Filesystem path. .sp Parameters annotated with this type accept a filesystem path as \fBstr\fP, \fBbytes\fP, or \fBos.PathLike\fP\&. .UNINDENT .SS Exceptions .INDENT 0.0 .TP .B class drgn.FaultError Bases: \fBException\fP .sp 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). .INDENT 7.0 .TP .B FaultError(message: str, address: int) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmessage\fP \-\- \fI\%FaultError.message\fP .IP \(bu 2 \fBaddress\fP \-\- \fI\%FaultError.address\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B message: str Error message. .UNINDENT .INDENT 7.0 .TP .B address: int Address that couldn\(aqt be accessed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.MissingDebugInfoError Bases: \fBException\fP .sp This error is raised when one or more files in a program do not have debug information. .UNINDENT .INDENT 0.0 .TP .B class drgn.ObjectAbsentError Bases: \fBException\fP .sp This error is raised when attempting to use an absent object. .UNINDENT .INDENT 0.0 .TP .B class drgn.OutOfBoundsError Bases: \fBException\fP .sp This error is raised when attempting to access beyond the bounds of a value object. .UNINDENT .SS CLI .sp Functions for embedding the drgn CLI. .INDENT 0.0 .TP .B drgn.cli.version_header() -> str Return the version header printed at the beginning of a drgn session. .sp The \fI\%run_interactive()\fP 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 \fI\%run_interactive()\fP\&. .UNINDENT .INDENT 0.0 .TP .B drgn.cli.run_interactive(prog: \fI\%drgn.Program\fP, banner_func: Optional[Callable[[str], str]] = None, globals_func: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None, quiet: bool = False) -> None Run drgn\(aqs \fI\%Interactive Mode\fP until the user exits. .sp This function allows your application to embed the same REPL that drgn provides when it is run on the command line in interactive mode. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Pre\-configured program to run against. Available as a global named \fBprog\fP in the CLI. .IP \(bu 2 \fBbanner_func\fP \-\- 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 \fI\%version_header()\fP\&. .IP \(bu 2 \fBglobals_func\fP \-\- Optional function to modify globals provided to the session. Called with a dictionary of default globals, and must return a dictionary to use instead. .IP \(bu 2 \fBquiet\fP \-\- Ignored. Will be removed in the future. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function uses \fBreadline\fP and modifies some settings. Unfortunately, it is not possible for it to restore all settings. In particular, it clears the \fBreadline\fP history and resets the TAB keybinding to the default. .sp Applications using \fBreadline\fP 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 \fBreadline\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS Logging .sp drgn logs using the standard \fBlogging\fP module to a logger named \fB\(dqdrgn\(dq\fP\&. .SS Thread Safety .sp Only one thread at a time should access the same \fI\%Program\fP (including \fI\%Object\fP, \fI\%Type\fP, \fI\%StackTrace\fP, etc. from that program). It is safe to use different \fI\%Program\fPs from concurrent threads. .SS Helpers .sp The \fBdrgn.helpers\fP 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++. .INDENT 0.0 .TP .B class drgn.helpers.ValidationError Bases: \fBException\fP .sp Error raised by a \fI\%validator\fP when an inconsistent or invalid state is detected. .UNINDENT .SS Common .sp The \fBdrgn.helpers.common\fP 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: .sp .EX >>> from drgn.helpers.common.memory import identify_address >>> from drgn.helpers.common import identify_address .EE .sp Some of these helpers may have additional program\-specific behavior but are otherwise generic. .SS Formatting .sp The \fBdrgn.helpers.common.format\fP module provides generic helpers for formatting different things as text. .INDENT 0.0 .TP .B 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 \fB\e0\fP, \fB\ea\fP, \fB\eb\fP, \fB\et\fP, \fB\en\fP, \fB\ev\fP, \fB\ef\fP, and \fB\er\fP are escaped in hexadecimal format (e.g., \fB\ex7f\fP). By default, printable characters are never escaped. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBc\fP \-\- Character to escape. .IP \(bu 2 \fBescape_single_quote\fP \-\- Whether to escape single quotes to \fB\e\(aq\fP\&. .IP \(bu 2 \fBescape_double_quote\fP \-\- Whether to escape double quotes to \fB\e\(dq\fP\&. .IP \(bu 2 \fBescape_backslash\fP \-\- Whether to escape backslashes to \fB\e\e\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B 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., \fBbytes\fP or \fBbytearray\fP). See \fI\%escape_ascii_character()\fP\&. .INDENT 7.0 .TP .B Parameters \fBbuffer\fP \-\- Byte array to escape. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.common.format.decode_flags(value: \fI\%drgn.IntegerLike\fP, flags: Iterable[Tuple[str, int]], bit_numbers: bool = True) -> str Get a human\-readable representation of a bitmask of flags. .sp By default, flags are specified by their bit number: .sp .EX >>> decode_flags(2, [(\(dqBOLD\(dq, 0), (\(dqITALIC\(dq, 1), (\(dqUNDERLINE\(dq, 2)]) \(aqITALIC\(aq .EE .sp They can also be specified by their value: .sp .EX >>> decode_flags(2, [(\(dqBOLD\(dq, 1), (\(dqITALIC\(dq, 2), (\(dqUNDERLINE\(dq, 4)], \&... bit_numbers=False) \(aqITALIC\(aq .EE .sp Multiple flags are combined with \(dq|\(dq: .sp .EX >>> decode_flags(5, [(\(dqBOLD\(dq, 0), (\(dqITALIC\(dq, 1), (\(dqUNDERLINE\(dq, 2)]) \(aqBOLD|UNDERLINE\(aq .EE .sp If there are multiple names for the same bit, they are all included: .sp .EX >>> decode_flags(2, [(\(dqSMALL\(dq, 0), (\(dqBIG\(dq, 1), (\(dqLARGE\(dq, 1)]) \(aqBIG|LARGE\(aq .EE .sp If there are any unknown bits, their raw value is included: .sp .EX >>> decode_flags(27, [(\(dqBOLD\(dq, 0), (\(dqITALIC\(dq, 1), (\(dqUNDERLINE\(dq, 2)]) \(aqBOLD|ITALIC|0x18\(aq .EE .sp Zero is returned verbatim: .sp .EX >>> decode_flags(0, [(\(dqBOLD\(dq, 0), (\(dqITALIC\(dq, 1), (\(dqUNDERLINE\(dq, 2)]) \(aq0\(aq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvalue\fP \-\- Bitmask to decode. .IP \(bu 2 \fBflags\fP \-\- List of flag names and their bit numbers or values. .IP \(bu 2 \fBbit_numbers\fP \-\- Whether \fIflags\fP specifies the bit numbers (where 0 is the least significant bit) or values of the flags. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.common.format.decode_enum_type_flags(value: \fI\%drgn.IntegerLike\fP, type: \fI\%drgn.Type\fP, bit_numbers: bool = True) -> str Get a human\-readable representation of a bitmask of flags where the flags are specified by an enumerated \fI\%drgn.Type\fP\&. .sp This supports enums where the values are bit numbers: .sp .EX >>> print(bits_enum) enum style_bits { BOLD = 0, ITALIC = 1, UNDERLINE = 2, } >>> decode_enum_type_flags(5, bits_enum) \(aqBOLD|UNDERLINE\(aq .EE .sp Or the values of the flags: .sp .EX >>> print(flags_enum) enum style_flags { BOLD = 1, ITALIC = 2, UNDERLINE = 4, } >>> decode_enum_type_flags(5, flags_enum, bit_numbers=False) \(aqBOLD|UNDERLINE\(aq .EE .sp See \fI\%decode_flags()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvalue\fP \-\- Bitmask to decode. .IP \(bu 2 \fBtype\fP \-\- Enumerated type with bit numbers for enumerators. .IP \(bu 2 \fBbit_numbers\fP \-\- Whether the enumerator values specify the bit numbers or values of the flags. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.common.format.number_in_binary_units(n: SupportsFloat, precision: int = 1) -> str Format a number in binary units (i.e., \(dqK\(dq is 1024, \(dqM\(dq is 1024\s-2\u2\d\s0, etc.). .sp .EX >>> number_in_binary_units(1280) \(aq1.2K\(aq .EE .sp A precision can be specified: .sp .EX >>> number_in_binary_units(1280, precision=2) \(aq1.25K\(aq .EE .sp Exact numbers are printed without a fractional part: .sp .EX >>> number_in_binary_units(1024 * 1024) \(aq1M\(aq .EE .sp Numbers less than 1024 are not scaled: .sp .EX >>> number_in_binary_units(10) \(aq10\(aq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBn\fP \-\- Number to format. .IP \(bu 2 \fBprecision\fP \-\- Number of digits to include in fractional part. .UNINDENT .UNINDENT .UNINDENT .SS Memory .sp The \fBdrgn.helpers.common.memory\fP module provides helpers for working with memory and addresses. .INDENT 0.0 .TP .B drgn.helpers.common.memory.identify_address(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> Optional[str] Try to identify what an address refers to. .sp For all programs, this will identify addresses as follows: .INDENT 7.0 .IP \(bu 2 Object symbols (e.g., addresses in global variables): \fBobject symbol: {symbol_name}+{hex_offset}\fP (where \fBhex_offset\fP is the offset from the beginning of the symbol in hexadecimal). .IP \(bu 2 Function symbols (i.e., addresses in functions): \fBfunction symbol: {symbol_name}+{hex_offset}\fP\&. .IP \(bu 2 Other symbols: \fBsymbol: {symbol_name}+{hex_offset}\fP\&. .UNINDENT .sp Additionally, for the Linux kernel, this will identify: .INDENT 7.0 .IP \(bu 2 Allocated slab objects: \fBslab object: {slab_cache_name}+{hex_offset}\fP (where \fBhex_offset\fP is the offset from the beginning of the object in hexadecimal). .IP \(bu 2 Free slab objects: \fBfree slab object: {slab_cache_name}+{hex_offset}\fP\&. .UNINDENT .sp This may recognize other types of addresses in the future. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns Identity as string, or \fBNone\fP if the address is unrecognized. .UNINDENT .UNINDENT .SS Program Decorators .sp The \fBdrgn.helpers.common.prog\fP module provides decorators to transparently use the \fI\%default program argument\fP\&. .INDENT 0.0 .TP .B drgn.helpers.common.prog.takes_program_or_default(f: TakesProgram[P, R]) -> TakesProgramOrDefault[P, R] Wrap a function taking a \fI\%Program\fP so that it uses the \fI\%default program argument\fP if omitted. .INDENT 7.0 .INDENT 3.5 .sp .EX @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) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.common.prog.takes_object_or_program_or_default(f: Callable[Concatenate[\fI\%drgn.Program\fP, Optional[\fI\%drgn.Object\fP], P], R]) -> TakesObjectOrProgramOrDefault[P, R] Wrap a function taking a \fI\%Program\fP and an optional \fI\%Object\fP so that it accepts a \fBProgram\fP \fIor\fP an \fBObject\fP \fIor neither\fP, in which case the \fI\%default program argument\fP is used. .INDENT 7.0 .INDENT 3.5 .sp .EX @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) .EE .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 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. .INDENT 0.0 .INDENT 3.5 .sp .EX # NOT ALLOWED @takes_object_or_program_or_default def my_helper(prog: Program, obj: Optional[Object], foo: str = \(dq\(dq): ... # OK @takes_object_or_program_or_default def my_helper(prog: Program, obj: Optional[Object], *, foo: str = \(dq\(dq): ... .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The object parameter can be passed as a keyword, but because of \fI\%limitations of the Python type system\fP, type checkers do not recognize this. .UNINDENT .UNINDENT .UNINDENT .SS Stack .sp The \fBdrgn.helpers.common.stack\fP module provides helpers for working with stack traces. .INDENT 0.0 .TP .B drgn.helpers.common.stack.print_annotated_stack(trace: \fI\%drgn.StackTrace\fP) -> None Print the contents of stack memory in a stack trace, annotating values that can be identified. .sp Currently, this will identify any addresses on the stack with \fI\%identify_address()\fP\&. .sp .EX >>> 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] \&... .EE .INDENT 7.0 .TP .B Parameters \fBtrace\fP \-\- Stack trace to print. .UNINDENT .UNINDENT .SS Types .sp The \fBdrgn.helpers.common.type\fP module provides generic helpers for working with types in ways that aren\(aqt provided by the core drgn library. .INDENT 0.0 .TP .B drgn.helpers.common.type.enum_type_to_class(type: \fI\%drgn.Type\fP, name: str, exclude: Container[str] = (), prefix: str = \(aq\(aq) -> Type[enum.IntEnum] Get an \fBenum.IntEnum\fP class from an enumerated \fI\%drgn.Type\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Enumerated type to convert. .IP \(bu 2 \fBname\fP \-\- Name of the \fBIntEnum\fP type to create. .IP \(bu 2 \fBexclude\fP \-\- Container (e.g., list or set) of enumerator names to exclude from the created \fBIntEnum\fP\&. .IP \(bu 2 \fBprefix\fP \-\- Prefix to strip from the beginning of enumerator names. .UNINDENT .UNINDENT .UNINDENT .SS Linux Kernel .sp The \fBdrgn.helpers.linux\fP 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: .sp .EX >>> from drgn.helpers.linux.list import list_for_each_entry >>> from drgn.helpers.linux import list_for_each_entry .EE .sp Iterator macros (\fBfor_each_foo\fP) are a common idiom in the Linux kernel. The equivalent drgn helpers are implemented as Python generators\&. For example, the following code in C: .INDENT 0.0 .INDENT 3.5 .sp .EX list_for_each(pos, head) do_something_with(pos); .EE .UNINDENT .UNINDENT .sp Translates to the following code in Python: .INDENT 0.0 .INDENT 3.5 .sp .EX for pos in list_for_each(head): do_something_with(pos) .EE .UNINDENT .UNINDENT .SS Bit Operations .sp The \fBdrgn.helpers.linux.bitops\fP module provides helpers for common bit operations in the Linux kernel. .INDENT 0.0 .TP .B drgn.helpers.linux.bitops.for_each_set_bit(bitmap: \fI\%drgn.Object\fP, size: \fI\%drgn.IntegerLike\fP) -> Iterator[int] Iterate over all set (one) bits in a bitmap. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbitmap\fP \-\- \fBunsigned long *\fP .IP \(bu 2 \fBsize\fP \-\- Size of \fIbitmap\fP in bits. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.bitops.for_each_clear_bit(bitmap: \fI\%drgn.Object\fP, size: \fI\%drgn.IntegerLike\fP) -> Iterator[int] Iterate over all clear (zero) bits in a bitmap. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbitmap\fP \-\- \fBunsigned long *\fP .IP \(bu 2 \fBsize\fP \-\- Size of \fIbitmap\fP in bits. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.bitops.test_bit(nr: \fI\%drgn.IntegerLike\fP, bitmap: \fI\%drgn.Object\fP) -> bool Return whether a bit in a bitmap is set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnr\fP \-\- Bit number. .IP \(bu 2 \fBbitmap\fP \-\- \fBunsigned long *\fP .UNINDENT .UNINDENT .UNINDENT .SS Block Layer .sp The \fBdrgn.helpers.linux.block\fP module provides helpers for working with the Linux block layer, including disks (\fBstruct gendisk\fP) and partitions. .sp Since Linux v5.11, partitions are represented by \fBstruct block_device\fP\&. Before that, they were represented by \fBstruct hd_struct\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.block.disk_devt(disk: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get a disk\(aqs device number. .INDENT 7.0 .TP .B Parameters \fBdisk\fP \-\- \fBstruct gendisk *\fP .TP .B Returns \fBdev_t\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.block.disk_name(disk: \fI\%drgn.Object\fP) -> bytes Get the name of a disk (e.g., \fBsda\fP). .INDENT 7.0 .TP .B Parameters \fBdisk\fP \-\- \fBstruct gendisk *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.block.for_each_disk(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all disks in the system. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct gendisk *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.block.print_disks(prog: \fI\%drgn.Program\fP) -> None Print all of the disks in the system. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.block.part_devt(part: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get a partition\(aqs device number. .INDENT 7.0 .TP .B Parameters \fBpart\fP \-\- \fBstruct block_device *\fP or \fBstruct hd_struct *\fP depending on the kernel version. .TP .B Returns \fBdev_t\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.block.part_name(part: \fI\%drgn.Object\fP) -> bytes Get the name of a partition (e.g., \fBsda1\fP). .INDENT 7.0 .TP .B Parameters \fBpart\fP \-\- \fBstruct block_device *\fP or \fBstruct hd_struct *\fP depending on the kernel version. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.block.for_each_partition(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all partitions in the system. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct block_device *\fP or \fBstruct hd_struct *\fP objects depending on the kernel version. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.block.print_partitions(prog: \fI\%drgn.Program\fP) -> None Print all of the partitions in the system. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .SS Boot .sp The \fBdrgn.helpers.linux.boot\fP module provides helpers for inspecting the Linux kernel boot configuration. .INDENT 0.0 .TP .B drgn.helpers.linux.boot.kaslr_offset(prog: \fI\%drgn.Program\fP) -> int Get the kernel address space layout randomization offset (zero if it is disabled). .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.boot.pgtable_l5_enabled(prog: \fI\%drgn.Program\fP) -> bool Return whether 5\-level paging is enabled. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .SS BPF .sp The \fBdrgn.helpers.linux.bpf\fP module provides helpers for working with BPF interface in \fI\%include/linux/bpf.h\fP, \fI\%include/linux/bpf\-cgroup.h\fP, etc. .INDENT 0.0 .TP .B drgn.helpers.linux.bpf.bpf_btf_for_each(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all BTF objects. .sp This is only supported since Linux v4.18. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct btf *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.bpf.bpf_link_for_each(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all BPF links. .sp This is only supported since Linux v5.8. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct bpf_link *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.bpf.bpf_map_for_each(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all BPF maps. .sp This is only supported since Linux v4.13. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct bpf_map *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.bpf.bpf_prog_for_each(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all BPF programs. .sp This is only supported since Linux v4.13. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct bpf_prog *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.bpf.cgroup_bpf_prog_for_each(cgrp: \fI\%drgn.Object\fP, bpf_attach_type: \fI\%drgn.IntegerLike\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all cgroup BPF programs of the given attach type attached to the given cgroup. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcgrp\fP \-\- \fBstruct cgroup *\fP .IP \(bu 2 \fBbpf_attach_type\fP \-\- \fBenum bpf_attach_type\fP .UNINDENT .TP .B Returns Iterator of \fBstruct bpf_prog *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.bpf.cgroup_bpf_prog_for_each_effective(cgrp: \fI\%drgn.Object\fP, bpf_attach_type: \fI\%drgn.IntegerLike\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all effective cgroup BPF programs of the given attach type for the given cgroup. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcgrp\fP \-\- \fBstruct cgroup *\fP .IP \(bu 2 \fBbpf_attach_type\fP \-\- \fBenum bpf_attach_type\fP .UNINDENT .TP .B Returns Iterator of \fBstruct bpf_prog *\fP objects. .UNINDENT .UNINDENT .SS Cgroup .sp The \fBdrgn.helpers.linux.cgroup\fP module provides helpers for working with the cgroup interface in \fI\%include/linux/cgroup.h\fP\&. Only cgroup v2 is supported. .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.sock_cgroup_ptr(skcd: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the cgroup for a socket from the given \fBstruct sock_cgroup_data *\fP (usually from \fBstruct sock::sk_cgrp_data\fP). .INDENT 7.0 .TP .B Parameters \fBskcd\fP \-\- \fBstruct sock_cgroup_data *\fP .TP .B Returns \fBstruct cgroup *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.cgroup_parent(cgrp: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the parent cgroup of the given cgroup if it exists, \fBNULL\fP otherwise. .INDENT 7.0 .TP .B Parameters \fBcgrp\fP \-\- \fBstruct cgroup *\fP .TP .B Returns \fBstruct cgroup *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.cgroup_name(cgrp: \fI\%drgn.Object\fP) -> bytes Get the name of the given cgroup. .INDENT 7.0 .TP .B Parameters \fBcgrp\fP \-\- \fBstruct cgroup *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.cgroup_path(cgrp: \fI\%drgn.Object\fP) -> bytes Get the full path of the given cgroup. .INDENT 7.0 .TP .B Parameters \fBcgrp\fP \-\- \fBstruct cgroup *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.cgroup_get_from_path(prog: \fI\%drgn.Program\fP, path: \fI\%drgn.Path\fP) -> \fI\%drgn.Object\fP Look up a cgroup from its default hierarchy path . .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBpath\fP \-\- Path name. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.css_next_child(pos: \fI\%drgn.Object\fP, parent: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the next child (or \fBNULL\fP if there is none) of the given parent starting from the given position (\fBNULL\fP to initiate traversal). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpos\fP \-\- \fBstruct cgroup_subsys_state *\fP .IP \(bu 2 \fBparent\fP \-\- \fBstruct cgroup_subsys_state *\fP .UNINDENT .TP .B Returns \fBstruct cgroup_subsys_state *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.css_next_descendant_pre(pos: \fI\%drgn.Object\fP, root: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the next pre\-order descendant (or \fBNULL\fP if there is none) of the given css root starting from the given position (\fBNULL\fP to initiate traversal). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpos\fP \-\- \fBstruct cgroup_subsys_state *\fP .IP \(bu 2 \fBroot\fP \-\- \fBstruct cgroup_subsys_state *\fP .UNINDENT .TP .B Returns \fBstruct cgroup_subsys_state *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.css_for_each_child(css: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate through children of the given css. .INDENT 7.0 .TP .B Parameters \fBcss\fP \-\- \fBstruct cgroup_subsys_state *\fP .TP .B Returns Iterator of \fBstruct cgroup_subsys_state *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cgroup.css_for_each_descendant_pre(css: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate through the given css\(aqs descendants in pre\-order. .INDENT 7.0 .TP .B Parameters \fBcss\fP \-\- \fBstruct cgroup_subsys_state *\fP .TP .B Returns Iterator of \fBstruct cgroup_subsys_state *\fP objects. .UNINDENT .UNINDENT .SS CPU Masks .sp The \fBdrgn.helpers.linux.cpumask\fP module provides helpers for working with CPU masks from \fI\%include/linux/cpumask.h\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.cpu_online_mask(prog: \fI\%drgn.Program\fP) -> \fI\%drgn.Object\fP Return the mask of online CPUs. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns \fBstruct cpumask *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.cpu_possible_mask(prog: \fI\%drgn.Program\fP) -> \fI\%drgn.Object\fP Return the mask of possible CPUs. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns \fBstruct cpumask *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.cpu_present_mask(prog: \fI\%drgn.Program\fP) -> \fI\%drgn.Object\fP Return the mask of present CPUs. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns \fBstruct cpumask *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.for_each_cpu(mask: \fI\%drgn.Object\fP) -> Iterator[int] Iterate over all of the CPUs in the given mask. .INDENT 7.0 .TP .B Parameters \fBmask\fP \-\- \fBstruct cpumask *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.for_each_online_cpu(prog: \fI\%drgn.Program\fP) -> Iterator[int] Iterate over all online CPUs. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.for_each_possible_cpu(prog: \fI\%drgn.Program\fP) -> Iterator[int] Iterate over all possible CPUs. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.for_each_present_cpu(prog: \fI\%drgn.Program\fP) -> Iterator[int] Iterate over all present CPUs. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.cpumask.cpumask_to_cpulist(mask: \fI\%drgn.Object\fP) -> str Return a CPU mask as a CPU list string. .sp .EX >>> cpumask_to_cpulist(mask) 0\-3,8\-11 .EE .INDENT 7.0 .TP .B Parameters \fBmask\fP \-\- \fBstruct cpumask *\fP .TP .B Returns String in the \fI\%CPU list format\fP\&. .UNINDENT .UNINDENT .SS Devices .sp The \fBdrgn.helpers.linux.device\fP module provides helpers for working with Linux devices, including the kernel encoding of \fBdev_t\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.device.MAJOR(dev: \fI\%drgn.IntegerLike\fP) -> int Return the major ID of a kernel \fBdev_t\fP\&. .INDENT 7.0 .TP .B Parameters \fBdev\fP \-\- \fBdev_t\fP object or \fBint\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.device.MINOR(dev: \fI\%drgn.IntegerLike\fP) -> int Return the minor ID of a kernel \fBdev_t\fP\&. .INDENT 7.0 .TP .B Parameters \fBdev\fP \-\- \fBdev_t\fP object or \fBint\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.device.MKDEV(major: \fI\%drgn.IntegerLike\fP, minor: \fI\%drgn.IntegerLike\fP) -> int Return a kernel \fBdev_t\fP from the major and minor IDs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmajor\fP \-\- Device major ID. .IP \(bu 2 \fBminor\fP \-\- Device minor ID. .UNINDENT .UNINDENT .UNINDENT .SS Virtual Filesystem Layer .sp The \fBdrgn.helpers.linux.fs\fP module provides helpers for working with the Linux virtual filesystem (VFS) layer, including mounts, dentries, and inodes. .INDENT 0.0 .TP .B drgn.helpers.linux.fs.path_lookup(root: Union[\fI\%drgn.Object\fP, \fI\%drgn.Program\fP], path: \fI\%drgn.Path\fP, *, allow_negative: bool = False) -> \fI\%drgn.Object\fP Look up the given path name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBroot\fP \-\- \fBstruct path *\fP to use as the root directory. Defaults to the initial root filesystem if given a \fI\%Program\fP or \fI\%omitted\fP\&. .IP \(bu 2 \fBpath\fP \-\- Path to lookup. .IP \(bu 2 \fBallow_negative\fP \-\- Whether to allow returning a negative dentry (i.e., a dentry for a non\-existent path). .UNINDENT .TP .B Returns \fBstruct path\fP .TP .B Raises \fBException\fP \-\- if the dentry is negative and \fBallow_negative\fP is \fBFalse\fP, 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 \fBopen()\fP or \fBos.stat()\fP): .UNINDENT .sp .EX >>> path_lookup(\(aq/usr/include/stdlib.h\(aq) \&... Exception: could not find \(aq/usr/include/stdlib.h\(aq in dcache >>> open(\(aq/usr/include/stdlib.h\(aq).close() >>> path_lookup(\(aq/usr/include/stdlib.h\(aq) (struct path){ .mnt = (struct vfsmount *)0xffff8b70413cdca0, .dentry = (struct dentry *)0xffff8b702ac2c480, } .EE .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.d_path(path: \fI\%drgn.Object\fP) -> bytes Return the full path of a dentry given a \fBstruct path\fP\&. .INDENT 7.0 .TP .B Parameters \fBpath\fP \-\- \fBstruct path\fP or \fBstruct path *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.d_path(vfsmnt: \fI\%drgn.Object\fP, dentry: \fI\%drgn.Object\fP) -> bytes Return the full path of a dentry given a mount and dentry. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvfsmnt\fP \-\- \fBstruct vfsmount *\fP .IP \(bu 2 \fBdentry\fP \-\- \fBstruct dentry *\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.dentry_path(dentry: \fI\%drgn.Object\fP) -> bytes Return the path of a dentry from the root of its filesystem. .INDENT 7.0 .TP .B Parameters \fBdentry\fP \-\- \fBstruct dentry *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.inode_path(inode: \fI\%drgn.Object\fP) -> Optional[bytes] Return any path of an inode from the root of its filesystem. .INDENT 7.0 .TP .B Parameters \fBinode\fP \-\- \fBstruct inode *\fP .TP .B Returns Path, or \fBNone\fP if the inode has no aliases. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.inode_paths(inode: \fI\%drgn.Object\fP) -> Iterator[bytes] Return an iterator over all of the paths of an inode from the root of its filesystem. .INDENT 7.0 .TP .B Parameters \fBinode\fP \-\- \fBstruct inode *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.mount_src(mnt: \fI\%drgn.Object\fP) -> bytes Get the source device name for a mount. .INDENT 7.0 .TP .B Parameters \fBmnt\fP \-\- \fBstruct mount *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.mount_dst(mnt: \fI\%drgn.Object\fP) -> bytes Get the path of a mount point. .INDENT 7.0 .TP .B Parameters \fBmnt\fP \-\- \fBstruct mount *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.mount_fstype(mnt: \fI\%drgn.Object\fP) -> bytes Get the filesystem type of a mount. .INDENT 7.0 .TP .B Parameters \fBmnt\fP \-\- \fBstruct mount *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.for_each_mount(ns: Union[\fI\%drgn.Object\fP, \fI\%drgn.Program\fP], *, src: Optional[\fI\%drgn.Path\fP] = None, dst: Optional[\fI\%drgn.Path\fP] = None, fstype: Optional[Union[str, bytes]] = None) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the mounts in a given namespace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBns\fP \-\- \fBstruct mnt_namespace *\fP\&. Defaults to the initial mount namespace if given a \fI\%Program\fP or \fI\%omitted\fP\&. .IP \(bu 2 \fBsrc\fP \-\- Only include mounts with this source device name. .IP \(bu 2 \fBdst\fP \-\- Only include mounts with this destination path. .IP \(bu 2 \fBfstype\fP \-\- Only include mounts with this filesystem type. .UNINDENT .TP .B Returns Iterator of \fBstruct mount *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.print_mounts(ns: Union[\fI\%drgn.Object\fP, \fI\%drgn.Program\fP], *, src: Optional[\fI\%drgn.Path\fP] = None, dst: Optional[\fI\%drgn.Path\fP] = None, fstype: Optional[Union[str, bytes]] = None) -> None Print the mount table of a given namespace. The arguments are the same as \fI\%for_each_mount()\fP\&. The output format is similar to \fB/proc/mounts\fP but prints the value of each \fBstruct mount *\fP\&. .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.fget(task: \fI\%drgn.Object\fP, fd: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the kernel file descriptor of the fd of a given task. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtask\fP \-\- \fBstruct task_struct *\fP .IP \(bu 2 \fBfd\fP \-\- File descriptor. .UNINDENT .TP .B Returns \fBstruct file *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.for_each_file(task: \fI\%drgn.Object\fP) -> Iterator[Tuple[int, \fI\%drgn.Object\fP]] Iterate over all of the files open in a given task. .INDENT 7.0 .TP .B Parameters \fBtask\fP \-\- \fBstruct task_struct *\fP .TP .B Returns Iterator of (fd, \fBstruct file *\fP) tuples. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.fs.print_files(task: \fI\%drgn.Object\fP) -> None Print the open files of a given task. .INDENT 7.0 .TP .B Parameters \fBtask\fP \-\- \fBstruct task_struct *\fP .UNINDENT .UNINDENT .SS IDR .sp The \fBdrgn.helpers.linux.idr\fP module provides helpers for working with the IDR data structure in \fI\%include/linux/idr.h\fP\&. An IDR provides a mapping from an ID to a pointer. .INDENT 0.0 .TP .B drgn.helpers.linux.idr.idr_find(idr: \fI\%drgn.Object\fP, id: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Look up the entry with the given ID in an IDR. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBidr\fP \-\- \fBstruct idr *\fP .IP \(bu 2 \fBid\fP \-\- Entry ID. .UNINDENT .TP .B Returns \fBvoid *\fP found entry, or \fBNULL\fP if not found. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.idr.idr_for_each(idr: \fI\%drgn.Object\fP) -> Iterator[Tuple[int, \fI\%drgn.Object\fP]] Iterate over all of the pointers in an IDR. .INDENT 7.0 .TP .B Parameters \fBidr\fP \-\- \fBstruct idr *\fP .TP .B Returns Iterator of (index, \fBvoid *\fP) tuples. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.idr.idr_for_each_entry(idr: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP]) -> Iterator[Tuple[int, \fI\%drgn.Object\fP]] Iterate over all of the entries with the given type in an IDR. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBidr\fP \-\- \fBstruct idr *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .UNINDENT .TP .B Returns Iterator of (index, \fBtype *\fP) tuples. .UNINDENT .UNINDENT .SS Kconfig .sp The \fBdrgn.helpers.linux.kconfig\fP module provides helpers for reading the Linux kernel build configuration. .INDENT 0.0 .TP .B drgn.helpers.linux.kconfig.get_kconfig(prog: \fI\%drgn.Program\fP) -> Mapping[str, str] Get the kernel build configuration as a mapping from the option name to the value. .sp .EX >>> get_kconfig()[\(aqCONFIG_SMP\(aq] \(aqy\(aq >>> get_kconfig()[\(aqCONFIG_HZ\(aq] \(aq300\(aq .EE .sp This is only supported if the kernel was compiled with \fBCONFIG_IKCONFIG\fP\&. Note that most Linux distributions do not enable this option. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .SS Kernfs .sp The \fBdrgn.helpers.linux.kernfs\fP module provides helpers for working with the kernfs pseudo filesystem interface in \fI\%include/linux/kernfs.h\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.kernfs.kernfs_name(kn: \fI\%drgn.Object\fP) -> bytes Get the name of the given kernfs node. .INDENT 7.0 .TP .B Parameters \fBkn\fP \-\- \fBstruct kernfs_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.kernfs.kernfs_path(kn: \fI\%drgn.Object\fP) -> bytes Get full path of the given kernfs node. .INDENT 7.0 .TP .B Parameters \fBkn\fP \-\- \fBstruct kernfs_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.kernfs.kernfs_walk(parent: \fI\%drgn.Object\fP, path: \fI\%drgn.Path\fP) -> \fI\%drgn.Object\fP Find the kernfs node with the given path from the given parent kernfs node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBparent\fP \-\- \fBstruct kernfs_node *\fP .IP \(bu 2 \fBpath\fP \-\- Path name. .UNINDENT .TP .B Returns \fBstruct kernfs_node *\fP (\fBNULL\fP if not found) .UNINDENT .UNINDENT .SS Linked Lists .sp The \fBdrgn.helpers.linux.list\fP module provides helpers for working with the doubly\-linked list implementations (\fBstruct list_head\fP and \fBstruct hlist_head\fP) in \fI\%include/linux/list.h\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_empty(head: \fI\%drgn.Object\fP) -> bool Return whether a list is empty. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct list_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_is_singular(head: \fI\%drgn.Object\fP) -> bool Return whether a list has only one element. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct list_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_count_nodes(head: \fI\%drgn.Object\fP) -> int Return the number of nodes in a list. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct list_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_first_entry(head: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP], member: str) -> \fI\%drgn.Object\fP Return the first entry in a list. .sp The list is assumed to be non\-empty. .sp See also \fI\%list_first_entry_or_null()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhead\fP \-\- \fBstruct list_head *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_first_entry_or_null(head: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP], member: str) -> \fI\%drgn.Object\fP Return the first entry in a list or \fBNULL\fP if the list is empty. .sp See also \fI\%list_first_entry()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhead\fP \-\- \fBstruct list_head *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_last_entry(head: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP], member: str) -> \fI\%drgn.Object\fP Return the last entry in a list. .sp The list is assumed to be non\-empty. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhead\fP \-\- \fBstruct list_head *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_next_entry(pos: \fI\%drgn.Object\fP, member: str) -> \fI\%drgn.Object\fP Return the next entry in a list. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpos\fP \-\- \fBtype*\fP .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_prev_entry(pos: \fI\%drgn.Object\fP, member: str) -> \fI\%drgn.Object\fP Return the previous entry in a list. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpos\fP \-\- \fBtype*\fP .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_for_each(head: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the nodes in a list. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct list_head *\fP .TP .B Returns Iterator of \fBstruct list_head *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_for_each_reverse(head: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the nodes in a list in reverse order. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct list_head *\fP .TP .B Returns Iterator of \fBstruct list_head *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], head: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the entries in a list. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBhead\fP \-\- \fBstruct list_head *\fP .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.list_for_each_entry_reverse(type: Union[str, \fI\%drgn.Type\fP], head: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the entries in a list in reverse order. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBhead\fP \-\- \fBstruct list_head *\fP .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.validate_list(head: \fI\%drgn.Object\fP) -> None Validate that the \fBnext\fP and \fBprev\fP pointers in a list are consistent. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct list_head *\fP .TP .B Raises \fI\%ValidationError\fP \-\- if the list is invalid .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.validate_list_for_each(head: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Like \fI\%list_for_each()\fP, but validates the list like \fI\%validate_list()\fP while iterating. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct list_head *\fP .TP .B Raises \fI\%ValidationError\fP \-\- if the list is invalid .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.validate_list_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], head: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Like \fI\%list_for_each_entry()\fP, but validates the list like \fI\%validate_list()\fP while iterating. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBhead\fP \-\- \fBstruct list_head *\fP .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Raises \fI\%ValidationError\fP \-\- if the list is invalid .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.hlist_empty(head: \fI\%drgn.Object\fP) -> bool Return whether a hash list is empty. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct hlist_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.hlist_for_each(head: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the nodes in a hash list. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct hlist_head *\fP .TP .B Returns Iterator of \fBstruct hlist_node *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list.hlist_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], head: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the entries in a hash list. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBhead\fP \-\- \fBstruct hlist_head *\fP .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .SS Nulls Lists .sp The \fBdrgn.helpers.linux.list_nulls\fP module provides helpers for working with the special version of lists (\fBstruct hlist_nulls_head\fP and \fBstruct hlist_nulls_node\fP) in \fI\%include/linux/list_nulls.h\fP where the end of list is not a \fBNULL\fP pointer, but a \(dqnulls\(dq marker. .INDENT 0.0 .TP .B drgn.helpers.linux.list_nulls.is_a_nulls(pos: \fI\%drgn.Object\fP) -> bool Return whether a a pointer is a nulls marker. .INDENT 7.0 .TP .B Parameters \fBpos\fP \-\- \fBstruct hlist_nulls_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list_nulls.hlist_nulls_empty(head: \fI\%drgn.Object\fP) -> bool Return whether a nulls hash list is empty. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct hlist_nulls_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.list_nulls.hlist_nulls_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], head: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Iterate over all the entries in a nulls hash list. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBhead\fP \-\- \fBstruct hlist_nulls_head *\fP .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .SS Lockless Lists .sp The \fBdrgn.helpers.linux.llist\fP module provides helpers for working with the lockless, \fBNULL\fP\-terminated, singly\-linked list implementation in \fI\%include/linux/llist.h\fP (\fBstruct llist_head\fP and \fBstruct llist_node\fP). .INDENT 0.0 .TP .B drgn.helpers.linux.llist.llist_empty(head: \fI\%drgn.Object\fP) -> bool Return whether an llist is empty. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct llist_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.llist.llist_is_singular(head: \fI\%drgn.Object\fP) -> bool Return whether an llist has only one element. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct llist_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.llist.llist_first_entry(head: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP], member: str) -> \fI\%drgn.Object\fP Return the first entry in an llist. .sp The list is assumed to be non\-empty. .sp See also \fI\%llist_first_entry_or_null()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhead\fP \-\- \fBstruct llist_head *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct llist_node\fP member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.llist.llist_first_entry_or_null(head: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP], member: str) -> \fI\%drgn.Object\fP Return the first entry in an llist or \fBNULL\fP if the llist is empty. .sp See also \fI\%llist_first_entry()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhead\fP \-\- \fBstruct llist_head *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct llist_node\fP member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.llist.llist_next_entry(pos: \fI\%drgn.Object\fP, member: str) -> \fI\%drgn.Object\fP Return the next entry in an llist. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpos\fP \-\- \fBtype*\fP .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct llist_node\fP member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.llist.llist_for_each(node: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the nodes in an llist starting from a given node. .INDENT 7.0 .TP .B Parameters \fBnode\fP \-\- \fBstruct llist_node *\fP .TP .B Returns Iterator of \fBstruct llist_node *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.llist.llist_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], node: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the entries in an llist starting from a given node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBnode\fP \-\- \fBstruct llist_node *\fP .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct llist_node\fP member in entry type. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .SS Maple Trees .sp The \fBdrgn.helpers.linux.mapletree\fP module provides helpers for working with maple trees from \fI\%include/linux/maple_tree.h\fP\&. .sp Maple trees were introduced in Linux 6.1. .INDENT 0.0 .TP .B drgn.helpers.linux.mapletree.mtree_load(mt: \fI\%drgn.Object\fP, index: \fI\%drgn.IntegerLike\fP, *, advanced: bool = False) -> \fI\%drgn.Object\fP Look up the entry at a given index in a maple tree. .sp .EX >>> entry = mtree_load(task.mm.mm_mt.address_of_(), 0x55d65cfaa000) >>> cast(\(dqstruct vm_area_struct *\(dq, entry) *(struct vm_area_struct *)0xffff97ad82bfc930 = { ... } .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmt\fP \-\- \fBstruct maple_tree *\fP .IP \(bu 2 \fBindex\fP \-\- Entry index. .IP \(bu 2 \fBadvanced\fP \-\- Whether to return nodes only visible to the maple tree advanced API. If \fBFalse\fP, zero entries (see \fI\%xa_is_zero()\fP) will be returned as \fBNULL\fP\&. .UNINDENT .TP .B Returns \fBvoid *\fP found entry, or \fBNULL\fP if not found. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mapletree.mt_for_each(mt: \fI\%drgn.Object\fP, *, advanced: bool = False) -> Iterator[Tuple[int, int, \fI\%drgn.Object\fP]] Iterate over all of the entries and their ranges in a maple tree. .sp .EX >>> 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 \&... .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmt\fP \-\- \fBstruct maple_tree *\fP .IP \(bu 2 \fBadvanced\fP \-\- Whether to return nodes only visible to the maple tree advanced API. If \fBFalse\fP, zero entries (see \fI\%xa_is_zero()\fP) will be skipped. .UNINDENT .TP .B Returns Iterator of (first_index, last_index, \fBvoid *\fP) tuples. Both indices are inclusive. .UNINDENT .UNINDENT .SS Memory Management .sp The \fBdrgn.helpers.linux.mm\fP module provides helpers for working with the Linux memory management (MM) subsystem. Only AArch64, ppc64, s390x, and x86\-64 are currently supported. .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageActive(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_active\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageChecked(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_checked\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageDirty(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_dirty\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageDoubleMap(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_double_map\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageError(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_error\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageForeign(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_foreign\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageHWPoison(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_hwpoison\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageHasHWPoisoned(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_has_hwpoisoned\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageIdle(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_idle\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageIsolated(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_isolated\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageLRU(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_lru\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageLocked(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_locked\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageMappedToDisk(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_mappedtodisk\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageMlocked(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_mlocked\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageOwnerPriv1(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_owner_priv_1\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PagePinned(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_pinned\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PagePrivate(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_private\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PagePrivate2(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_private_2\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageReadahead(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_readahead\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageReclaim(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_reclaim\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageReferenced(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_referenced\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageReported(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_reported\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageReserved(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_reserved\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageSavePinned(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_savepinned\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageSkipKASanPoison(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_skip_kasan_poison\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageSlab(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_slab\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageSlobFree(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_slob_free\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageSwapBacked(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_swapbacked\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageUncached(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_uncached\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageUnevictable(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_unevictable\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageUptodate(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_uptodate\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageVmemmapSelfHosted(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_vmemmap_self_hosted\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageWaiters(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_waiters\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageWorkingset(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_workingset\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageWriteback(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_writeback\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageXenRemapped(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_xen_remapped\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageYoung(page: \fI\%drgn.Object\fP) -> bool Return whether the \fBPG_young\fP flag is set on a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageCompound(page: \fI\%drgn.Object\fP) -> bool Return whether a page is part of a \fI\%compound page\fP\&. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageHead(page: \fI\%drgn.Object\fP) -> bool Return whether a page is a head page in a \fI\%compound page\fP\&. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PageTail(page: \fI\%drgn.Object\fP) -> bool Return whether a page is a tail page in a \fI\%compound page\fP\&. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.compound_head(page: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the head page associated with a page. .sp If \fIpage\fP is a tail page, this returns the head page of the \fI\%compound page\fP it belongs to. Otherwise, it returns \fIpage\fP\&. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .TP .B Returns \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.compound_order(page: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the allocation order of a potentially \fI\%compound page\fP\&. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .TP .B Returns \fBunsigned int\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.compound_nr(page: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the number of pages in a potentially \fI\%compound page\fP\&. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.page_size(page: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the number of bytes in a potentially \fI\%compound page\fP\&. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.decode_page_flags(page: \fI\%drgn.Object\fP) -> str Get a human\-readable representation of the flags set on a page. .sp .EX >>> decode_page_flags(page) \(aqPG_uptodate|PG_dirty|PG_lru|PG_reclaim|PG_swapbacked|PG_readahead|PG_savepinned|PG_isolated|PG_reported\(aq .EE .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.for_each_page(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over every \fBstruct page *\fP from the minimum to the maximum page. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This may include offline pages which don\(aqt have a valid \fBstruct page\fP\&. Wrap accesses in a \fBtry\fP ... \fBexcept\fP \fI\%drgn.FaultError\fP: .sp .EX >>> for page in for_each_page(): \&... try: \&... if PageLRU(page): \&... print(hex(page)) \&... except drgn.FaultError: \&... continue 0xfffffb4a000c0000 0xfffffb4a000c0040 \&... .EE .sp This may be fixed in the future. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct page *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PFN_PHYS(prog: \fI\%drgn.Program\fP, pfn: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the physical address of a page frame number (PFN). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBpfn\fP \-\- \fBunsigned long\fP .UNINDENT .TP .B Returns \fBphys_addr_t\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.PHYS_PFN(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page frame number (PFN) of a physical address. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBphys_addr_t\fP .UNINDENT .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.page_to_pfn(page: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the page frame number (PFN) of a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.page_to_phys(page: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the physical address of a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .TP .B Returns \fBphys_addr_t\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.page_to_virt(page: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the directly mapped virtual address of a page. .INDENT 7.0 .TP .B Parameters \fBpage\fP \-\- \fBstruct page *\fP .TP .B Returns \fBvoid *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.pfn_to_page(prog: \fI\%drgn.Program\fP, pfn: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page with a page frame number (PFN). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBpfn\fP \-\- \fBunsigned long\fP .UNINDENT .TP .B Returns \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.pfn_to_virt(prog: \fI\%drgn.Program\fP, pfn: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the directly mapped virtual address of a page frame number (PFN). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBpfn\fP \-\- \fBunsigned long\fP .UNINDENT .TP .B Returns \fBvoid *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.phys_to_page(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page containing a physical address. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBphys_addr_t\fP .UNINDENT .TP .B Returns \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.phys_to_virt(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the directly mapped virtual address of a physical address. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBphys_addr_t\fP .UNINDENT .TP .B Returns \fBvoid *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.virt_to_page(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page containing a directly mapped virtual address. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This only works for virtual addresses from the \(dqdirect map\(dq. This includes address from: .INDENT 0.0 .IP \(bu 2 kmalloc .IP \(bu 2 Slab allocator .IP \(bu 2 Page allocator .UNINDENT .sp But not: .INDENT 0.0 .IP \(bu 2 vmalloc .IP \(bu 2 vmap .IP \(bu 2 ioremap .IP \(bu 2 Symbols (function pointers, global variables) .UNINDENT .sp For vmalloc or vmap addresses, use \fI\%vmalloc_to_page(addr)\fP\&. For arbitrary kernel addresses, use \fI\%follow_page(prog[\(dqinit_mm\(dq].address_of_(), addr)\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.virt_to_pfn(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page frame number (PFN) of a directly mapped virtual address. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This only works for virtual addresses from the \fI\%\(dqdirect map\(dq\fP\&. For vmalloc or vmap addresses, use \fI\%vmalloc_to_pfn(addr)\fP\&. For arbitrary kernel addresses, use \fI\%follow_pfn(prog[\(dqinit_mm\(dq].address_of_(), addr)\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.virt_to_phys(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the physical address of a directly mapped virtual address. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This only works for virtual addresses from the \fI\%\(dqdirect map\(dq\fP\&. For arbitrary kernel addresses, use \fI\%follow_phys(prog[\(dqinit_mm\(dq].address_of_(), addr)\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBphys_addr_t\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.follow_page(mm: \fI\%drgn.Object\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page that a virtual address maps to in a virtual address space. .sp .EX >>> task = find_task(113) >>> follow_page(task.mm, 0x7fffbbb6d4d0) *(struct page *)0xffffbe4bc0337b80 = { ... } .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmm\fP \-\- \fBstruct mm_struct *\fP .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.follow_pfn(mm: \fI\%drgn.Object\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page frame number (PFN) that a virtual address maps to in a virtual address space. .sp .EX >>> task = find_task(113) >>> follow_pfn(task.mm, 0x7fffbbb6d4d0) (unsigned long)52718 .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmm\fP \-\- \fBstruct mm_struct *\fP .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.follow_phys(mm: \fI\%drgn.Object\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the physical address that a virtual address maps to in a virtual address space. .sp .EX >>> task = find_task(113) >>> follow_phys(task.mm, 0x7fffbbb6d4d0) (phys_addr_t)215934160 .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmm\fP \-\- \fBstruct mm_struct *\fP .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBphys_addr_t\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.vmalloc_to_page(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page containing a vmalloc or vmap address. .sp .EX >>> task = find_task(113) >>> vmalloc_to_page(task.stack) *(struct page *)0xffffbe4bc00a2200 = { ... } .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBstruct page *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.vmalloc_to_pfn(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the page frame number (PFN) containing a vmalloc or vmap address. .sp .EX >>> task = find_task(113) >>> vmalloc_to_pfn(task.stack) (unsigned long)10376 .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.access_process_vm(task: \fI\%drgn.Object\fP, address: \fI\%drgn.IntegerLike\fP, size: \fI\%drgn.IntegerLike\fP) -> bytes Read memory from a task\(aqs virtual address space. .sp .EX >>> task = find_task(1490152) >>> access_process_vm(task, 0x7f8a62b56da0, 12) b\(aqhello, world\(aq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtask\fP \-\- \fBstruct task_struct *\fP .IP \(bu 2 \fBaddress\fP \-\- Starting address. .IP \(bu 2 \fBsize\fP \-\- Number of bytes to read. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.access_remote_vm(mm: \fI\%drgn.Object\fP, address: \fI\%drgn.IntegerLike\fP, size: \fI\%drgn.IntegerLike\fP) -> bytes Read memory from a virtual address space. This is similar to \fI\%access_process_vm()\fP, but it takes a \fBstruct mm_struct *\fP instead of a \fBstruct task_struct *\fP\&. .sp .EX >>> task = find_task(1490152) >>> access_remote_vm(task.mm, 0x7f8a62b56da0, 12) b\(aqhello, world\(aq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmm\fP \-\- \fBstruct mm_struct *\fP .IP \(bu 2 \fBaddress\fP \-\- Starting address. .IP \(bu 2 \fBsize\fP \-\- Number of bytes to read. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.cmdline(task: \fI\%drgn.Object\fP) -> Optional[List[bytes]] Get the list of command line arguments of a task, or \fBNone\fP for kernel tasks. .sp .EX >>> cmdline(find_task(1495216)) [b\(aqvim\(aq, b\(aqdrgn/helpers/linux/mm.py\(aq] .EE .INDENT 7.0 .INDENT 3.5 .sp .EX $ tr \(aq\e0\(aq \(aq \(aq < /proc/1495216/cmdline vim drgn/helpers/linux/mm.py .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBtask\fP \-\- \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.environ(task: \fI\%drgn.Object\fP) -> Optional[List[bytes]] Get the list of environment variables of a task, or \fBNone\fP for kernel tasks. .sp .EX >>> environ(find_task(1497797)) [b\(aqHOME=/root\(aq, b\(aqPATH=/usr/local/sbin:/usr/local/bin:/usr/bin\(aq, b\(aqLOGNAME=root\(aq] .EE .INDENT 7.0 .INDENT 3.5 .sp .EX $ tr \(aq\e0\(aq \(aq\en\(aq < /proc/1497797/environ HOME=/root PATH=/usr/local/sbin:/usr/local/bin:/usr/bin LOGNAME=root .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBtask\fP \-\- \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.vma_find(mm: \fI\%drgn.Object\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the virtual memory area (VMA) containing an address. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmm\fP \-\- \fBstruct mm_struct *\fP .IP \(bu 2 \fBaddr\fP \-\- Address to look up. .UNINDENT .TP .B Returns \fBstruct vm_area_struct *\fP (\fBNULL\fP if not found) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.for_each_vma(mm: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over every virtual memory area (VMA) in a virtual address space. .sp .EX >>> for vma in for_each_vma(task.mm): \&... print(vma) \&... *(struct vm_area_struct *)0xffff97ad82bfc930 = { ... } *(struct vm_area_struct *)0xffff97ad82bfc0a8 = { ... } \&... .EE .INDENT 7.0 .TP .B Parameters \fBmm\fP \-\- \fBstruct mm_struct *\fP .TP .B Returns Iterator of \fBstruct vm_area_struct *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.mm.totalram_pages(prog: \fI\%drgn.Program\fP) -> int Return the total number of RAM pages. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .SS Networking .sp The \fBdrgn.helpers.linux.net\fP module provides helpers for working with the Linux kernel networking subsystem. .INDENT 0.0 .TP .B drgn.helpers.linux.net.SOCKET_I(inode: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get a socket from an inode referring to the socket. .INDENT 7.0 .TP .B Parameters \fBinode\fP \-\- \fBstruct inode *\fP .TP .B Returns \fBstruct socket *\fP .TP .B Raises \fBValueError\fP \-\- If \fIinode\fP does not refer to a socket .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.SOCK_INODE(sock: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the inode of a socket. .INDENT 7.0 .TP .B Parameters \fBsock\fP \-\- \fBstruct socket *\fP .TP .B Returns \fBstruct inode *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.for_each_net(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all network namespaces in the system. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct net *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.get_net_ns_by_inode(inode: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get a network namespace from a network namespace NSFS inode, e.g. \fB/proc/$PID/ns/net\fP or \fB/var/run/netns/$NAME\fP\&. .INDENT 7.0 .TP .B Parameters \fBinode\fP \-\- \fBstruct inode *\fP .TP .B Returns \fBstruct net *\fP .TP .B Raises \fBValueError\fP \-\- if \fIinode\fP is not a network namespace inode .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.get_net_ns_by_fd(task: \fI\%drgn.Object\fP, fd: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get a network namespace from a task and a file descriptor referring to a network namespace NSFS inode, e.g. \fB/proc/$PID/ns/net\fP or \fB/var/run/netns/$NAME\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtask\fP \-\- \fBstruct task_struct *\fP .IP \(bu 2 \fBfd\fP \-\- File descriptor. .UNINDENT .TP .B Returns \fBstruct net *\fP .TP .B Raises \fBValueError\fP \-\- If \fIfd\fP does not refer to a network namespace inode .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.netdev_for_each_tx_queue(dev: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all TX queues for a network device. .INDENT 7.0 .TP .B Parameters \fBdev\fP \-\- \fBstruct net_device *\fP .TP .B Returns Iterator of \fBstruct netdev_queue *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.netdev_get_by_index(net: Union[\fI\%drgn.Object\fP, \fI\%drgn.Program\fP], ifindex: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the network device with the given interface index number. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnet\fP \-\- \fBstruct net *\fP\&. Defaults to the initial network namespace if given a \fI\%Program\fP or \fI\%omitted\fP\&. .IP \(bu 2 \fBifindex\fP \-\- Network interface index number. .UNINDENT .TP .B Returns \fBstruct net_device *\fP (\fBNULL\fP if not found) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.netdev_get_by_name(net: Union[\fI\%drgn.Object\fP, \fI\%drgn.Program\fP], name: Union[str, bytes]) -> \fI\%drgn.Object\fP Get the network device with the given interface name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnet\fP \-\- \fBstruct net *\fP\&. Defaults to the initial network namespace if given a \fI\%Program\fP or \fI\%omitted\fP\&. .IP \(bu 2 \fBname\fP \-\- Network interface name. .UNINDENT .TP .B Returns \fBstruct net_device *\fP (\fBNULL\fP if not found) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.netdev_priv(dev: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP] = \(aqvoid\(aq) -> \fI\%drgn.Object\fP Return the private data of a network device. .sp .EX >>> dev = netdev_get_by_name(\(dqwlp0s20f3\(dq) >>> netdev_priv(dev) (void *)0xffff9419c9dec9c0 >>> netdev_priv(dev, \(dqstruct ieee80211_sub_if_data\(dq) *(struct ieee80211_sub_if_data *)0xffff9419c9dec9c0 = { ... } .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdev\fP \-\- \fBstruct net_device *\fP .IP \(bu 2 \fBtype\fP \-\- Type of private data. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.sk_fullsock(sk: \fI\%drgn.Object\fP) -> bool Check whether a socket is a full socket, i.e., not a time\-wait or request socket. .INDENT 7.0 .TP .B Parameters \fBsk\fP \-\- \fBstruct sock *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.sk_nulls_for_each(head: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all the entries in a nulls hash list of sockets specified by \fBstruct hlist_nulls_head\fP head. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct hlist_nulls_head *\fP .TP .B Returns Iterator of \fBstruct sock *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.net.skb_shinfo(skb: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Get the shared info for a socket buffer. .INDENT 7.0 .TP .B Parameters \fBskb\fP \-\- \fBstruct sk_buff *\fP .TP .B Returns \fBstruct skb_shared_info *\fP .UNINDENT .UNINDENT .SS NUMA Node Masks .sp The \fBdrgn.helpers.linux.nodemask\fP module provides helpers for working with NUMA node masks from \fI\%include/linux/nodemask.h\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.nodemask.for_each_node_mask(mask: \fI\%drgn.Object\fP) -> Iterator[int] Iterate over all of the NUMA nodes in the given mask. .INDENT 7.0 .TP .B Parameters \fBmask\fP \-\- \fBnodemask_t\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.nodemask.for_each_node_state(prog: \fI\%drgn.Program\fP, state: \fI\%drgn.IntegerLike\fP) -> Iterator[int] Iterate over all NUMA nodes in the given state. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBstate\fP \-\- \fBenum node_states\fP (e.g., \fBN_NORMAL_MEMORY\fP) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.nodemask.for_each_node(prog: \fI\%drgn.Program\fP) -> Iterator[int] Iterate over all possible NUMA nodes. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.nodemask.for_each_online_node(prog: \fI\%drgn.Program\fP) -> Iterator[int] Iterate over all online NUMA nodes. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.nodemask.node_state(node: \fI\%drgn.IntegerLike\fP, state: \fI\%drgn.Object\fP) -> bool Return whether the given NUMA node has the given state. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBnode\fP \-\- NUMA node number. .IP \(bu 2 \fBstate\fP \-\- \fBenum node_states\fP (e.g., \fBN_NORMAL_MEMORY\fP) .UNINDENT .UNINDENT .UNINDENT .SS Per\-CPU .sp The \fBdrgn.helpers.linux.percpu\fP module provides helpers for working with per\-CPU allocations from \fI\%include/linux/percpu.h\fP and per\-CPU counters from \fI\%include/linux/percpu_counter.h\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.percpu.per_cpu_ptr(ptr: \fI\%drgn.Object\fP, cpu: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the per\-CPU pointer for a given CPU. .sp .EX >>> prog[\(dqinit_net\(dq].loopback_dev.pcpu_refcnt (int *)0x2c980 >>> per_cpu_ptr(prog[\(dqinit_net\(dq].loopback_dev.pcpu_refcnt, 7) *(int *)0xffff925e3ddec980 = 4 .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBptr\fP \-\- Per\-CPU pointer, i.e., \fBtype __percpu *\fP\&. For global variables, it\(aqs usually easier to use \fI\%per_cpu()\fP\&. .IP \(bu 2 \fBcpu\fP \-\- CPU number. .UNINDENT .TP .B Returns \fBtype *\fP object. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.percpu.per_cpu(var: \fI\%drgn.Object\fP, cpu: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the per\-CPU variable for a given CPU. .sp .EX >>> print(repr(prog[\(dqrunqueues\(dq])) Object(prog, \(aqstruct rq\(aq, address=0x278c0) >>> per_cpu(prog[\(dqrunqueues\(dq], 6).curr.comm (char [16])\(dqpython3\(dq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvar\fP \-\- Per\-CPU variable, i.e., \fBtype __percpu\fP (not a pointer; use \fI\%per_cpu_ptr()\fP for that). .IP \(bu 2 \fBcpu\fP \-\- CPU number. .UNINDENT .TP .B Returns \fBtype\fP object. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.percpu.percpu_counter_sum(fbc: \fI\%drgn.Object\fP) -> int Return the sum of a per\-CPU counter. .INDENT 7.0 .TP .B Parameters \fBfbc\fP \-\- \fBstruct percpu_counter *\fP .UNINDENT .UNINDENT .SS Process IDS .sp The \fBdrgn.helpers.linux.pid\fP module provides helpers for looking up process IDs and processes. .INDENT 0.0 .TP .B drgn.helpers.linux.pid.pid_task(pid: \fI\%drgn.Object\fP, pid_type: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the \fBstruct task_struct *\fP containing the given \fBstruct pid *\fP of the given type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpid\fP \-\- \fBstruct pid *\fP .IP \(bu 2 \fBpid_type\fP \-\- \fBenum pid_type\fP .UNINDENT .TP .B Returns \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.pid.find_pid(ns: \fI\%drgn.Object\fP | \fI\%drgn.Program\fP, pid: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the \fBstruct pid *\fP for the given PID number. .INDENT 7.0 .TP .B Parameters \fBns\fP \-\- \fBstruct pid_namespace *\fP\&. Defaults to the initial PID namespace if given a \fI\%Program\fP or \fI\%omitted\fP\&. .TP .B Returns \fBstruct pid *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.pid.for_each_pid(ns: \fI\%drgn.Object\fP | \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all PIDs in a namespace. .INDENT 7.0 .TP .B Parameters \fBns\fP \-\- \fBstruct pid_namespace *\fP\&. Defaults to the initial PID namespace if given a \fI\%Program\fP or \fI\%omitted\fP\&. .TP .B Returns Iterator of \fBstruct pid *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.pid.find_task(ns: \fI\%drgn.Object\fP | \fI\%drgn.Program\fP, pid: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the task with the given PID. .INDENT 7.0 .TP .B Parameters \fBns\fP \-\- \fBstruct pid_namespace *\fP\&. Defaults to the initial PID namespace if given a \fI\%Program\fP or \fI\%omitted\fP\&. .TP .B Returns \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.pid.for_each_task(ns: \fI\%drgn.Object\fP | \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the tasks visible in a namespace. .INDENT 7.0 .TP .B Parameters \fBns\fP \-\- \fBstruct pid_namespace *\fP\&. Defaults to the initial PID namespace if given a \fI\%Program\fP or \fI\%omitted\fP\&. .TP .B Returns Iterator of \fBstruct task_struct *\fP objects. .UNINDENT .UNINDENT .SS Priority\-Sorted Lists .sp The \fBdrgn.helpers.linux.plist\fP module provides helpers for working with descending\-priority\-sorted doubly\-linked lists (\fBstruct plist_head\fP and \fBstruct plist_node\fP) from \fI\%include/linux/plist.h\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.plist.plist_head_empty(head: \fI\%drgn.Object\fP) -> bool Return whether a plist is empty. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct plist_head *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.plist.plist_node_empty(node: \fI\%drgn.Object\fP) -> bool Return whether a plist node is empty (i.e., not on a list). .INDENT 7.0 .TP .B Parameters \fBnode\fP \-\- \fBstruct plist_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.plist.plist_first_entry(head: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP], member: str) -> \fI\%drgn.Object\fP Return the first (highest priority) entry in a plist. .sp The list is assumed to be non\-empty. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhead\fP \-\- \fBstruct plist_head *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.plist.plist_last_entry(head: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP], member: str) -> \fI\%drgn.Object\fP Return the last (lowest priority) entry in a plist. .sp The list is assumed to be non\-empty. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhead\fP \-\- \fBstruct plist_head *\fP .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBmember\fP \-\- Name of list node member in entry type. .UNINDENT .TP .B Returns \fBtype *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.plist.plist_for_each(head: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the nodes in a plist. .INDENT 7.0 .TP .B Parameters \fBhead\fP \-\- \fBstruct plist_head *\fP .TP .B Returns Iterator of \fBstruct plist_node *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.plist.plist_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], head: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the entries in a plist. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBhead\fP \-\- \fBstruct plist_head *\fP .IP \(bu 2 \fBmember\fP \-\- Name of plist node member in entry type. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .SS Log Buffer .sp The \fBdrgn.helpers.linux.printk\fP module provides helpers for reading the Linux kernel log buffer. .INDENT 0.0 .TP .B class drgn.helpers.linux.printk.PrintkRecord Bases: \fBNamedTuple\fP .sp Kernel log record. .INDENT 7.0 .TP .B text: bytes Message text. .UNINDENT .INDENT 7.0 .TP .B facility: int \fBsyslog(3)\fP facility. .UNINDENT .INDENT 7.0 .TP .B level: int Log level. .UNINDENT .INDENT 7.0 .TP .B seq: int Sequence number. .UNINDENT .INDENT 7.0 .TP .B timestamp: int Timestamp in nanoseconds. .UNINDENT .INDENT 7.0 .TP .B caller_tid: Optional[int] Thread ID of thread that logged this record, if available. .sp This is available if the message was logged from task context and if the kernel saves the \fBprintk()\fP caller ID. .sp 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 \fBCONFIG_PRINTK_CALLER\fP\&. Before that, it is never saved. .UNINDENT .INDENT 7.0 .TP .B caller_cpu: Optional[int] Processor ID of CPU that logged this record, if available. .sp 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 \fBprintk()\fP caller ID. .sp See \fI\%caller_tid\fP for when the kernel saves the caller ID. .UNINDENT .INDENT 7.0 .TP .B continuation: bool Whether this record is a continuation of a previous record. .UNINDENT .INDENT 7.0 .TP .B context: Dict[bytes, bytes] Additional metadata for the message. .sp See the \fI\%/dev/kmsg documentation\fP for an explanation of the keys and values. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.printk.get_printk_records(prog: \fI\%drgn.Program\fP) -> List[\fI\%PrintkRecord\fP] Get a list of records in the kernel log buffer. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.printk.get_dmesg(prog: \fI\%drgn.Program\fP) -> bytes Get the contents of the kernel log buffer formatted like \fBdmesg(1)\fP\&. .sp If you just want to print the log buffer, use \fI\%print_dmesg()\fP\&. .sp The format of each line is: .INDENT 7.0 .INDENT 3.5 .sp .EX [ timestamp] message .EE .UNINDENT .UNINDENT .sp If you need to format the log buffer differently, use \fI\%get_printk_records()\fP and format it yourself. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.printk.print_dmesg(prog: \fI\%drgn.Program\fP, *, file: Optional[SupportsWrite[str]] = None) -> None Print the contents of the kernel log buffer. .sp .EX >>> 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: \&... .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBfile\fP \-\- File to print to. Defaults to \fBsys.stdout\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS Radix Trees .sp The \fBdrgn.helpers.linux.radixtree\fP module provides helpers for working with radix trees from \fI\%include/linux/radix\-tree.h\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fI\%XArrays\fP, which were introduced in Linux 4.20 as a replacement for radix trees. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.radixtree.radix_tree_lookup(root: \fI\%drgn.Object\fP, index: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Look up the entry at a given index in a radix tree. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBroot\fP \-\- \fBstruct radix_tree_root *\fP .IP \(bu 2 \fBindex\fP \-\- Entry index. .UNINDENT .TP .B Returns \fBvoid *\fP found entry, or \fBNULL\fP if not found. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.radixtree.radix_tree_for_each(root: \fI\%drgn.Object\fP) -> Iterator[Tuple[int, \fI\%drgn.Object\fP]] Iterate over all of the entries in a radix tree. .INDENT 7.0 .TP .B Parameters \fBroot\fP \-\- \fBstruct radix_tree_root *\fP .TP .B Returns Iterator of (index, \fBvoid *\fP) tuples. .UNINDENT .UNINDENT .SS Red\-Black Trees .sp The \fBdrgn.helpers.linux.rbtree\fP module provides helpers for working with red\-black trees from \fI\%include/linux/rbtree.h\fP\&. .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.RB_EMPTY_ROOT(root: \fI\%drgn.Object\fP) -> bool Return whether a red\-black tree is empty. .INDENT 7.0 .TP .B Parameters \fBnode\fP \-\- \fBstruct rb_root *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.RB_EMPTY_NODE(node: \fI\%drgn.Object\fP) -> bool Return whether a red\-black tree node is empty, i.e., not inserted in a tree. .INDENT 7.0 .TP .B Parameters \fBnode\fP \-\- \fBstruct rb_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rb_parent(node: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the parent node of a red\-black tree node. .INDENT 7.0 .TP .B Parameters \fBnode\fP \-\- \fBstruct rb_node *\fP .TP .B Returns \fBstruct rb_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rb_first(root: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the first node (in sort order) in a red\-black tree, or \fBNULL\fP if the tree is empty. .INDENT 7.0 .TP .B Parameters \fBroot\fP \-\- \fBstruct rb_root *\fP .TP .B Returns \fBstruct rb_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rb_last(root: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the last node (in sort order) in a red\-black tree, or \fBNULL\fP if the tree is empty. .INDENT 7.0 .TP .B Parameters \fBroot\fP \-\- \fBstruct rb_root *\fP .TP .B Returns \fBstruct rb_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rb_next(node: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the next node (in sort order) after a red\-black node, or \fBNULL\fP if the node is the last node in the tree or is empty. .INDENT 7.0 .TP .B Parameters \fBnode\fP \-\- \fBstruct rb_node *\fP .TP .B Returns \fBstruct rb_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rb_prev(node: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the previous node (in sort order) before a red\-black node, or \fBNULL\fP if the node is the first node in the tree or is empty. .INDENT 7.0 .TP .B Parameters \fBnode\fP \-\- \fBstruct rb_node *\fP .TP .B Returns \fBstruct rb_node *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rbtree_inorder_for_each(root: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the nodes in a red\-black tree, in sort order. .INDENT 7.0 .TP .B Parameters \fBroot\fP \-\- \fBstruct rb_root *\fP .TP .B Returns Iterator of \fBstruct rb_node *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rbtree_inorder_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], root: \fI\%drgn.Object\fP, member: str) -> Iterator[\fI\%drgn.Object\fP] Iterate over all of the entries in a red\-black tree in sorted order. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBroot\fP \-\- \fBstruct rb_root *\fP .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct rb_node\fP member in entry type. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.rb_find(type: Union[str, \fI\%drgn.Type\fP], root: \fI\%drgn.Object\fP, member: str, key: KeyType, cmp: Callable[[KeyType, \fI\%drgn.Object\fP], int]) -> \fI\%drgn.Object\fP Find an entry in a red\-black tree given a key and a comparator function. .sp Note that this function does not have an analogue in the Linux kernel source code, as tree searches are all open\-coded. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBroot\fP \-\- \fBstruct rb_root *\fP .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct rb_node\fP member in entry type. .IP \(bu 2 \fBkey\fP \-\- Key to find. .IP \(bu 2 \fBcmp\fP \-\- 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. .UNINDENT .TP .B Returns \fBtype *\fP found entry, or \fBNULL\fP if not found. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.validate_rbtree(type: Union[str, \fI\%drgn.Type\fP], root: \fI\%drgn.Object\fP, member: str, cmp: Callable[[\fI\%drgn.Object\fP, \fI\%drgn.Object\fP], int], allow_equal: bool) -> None Validate a red\-black tree. .sp This checks that: .INDENT 7.0 .IP 1. 3 The tree is a valid binary search tree ordered according to \fIcmp\fP\&. .IP 2. 3 If \fIallow_equal\fP is \fBFalse\fP, there are no nodes that compare equal according to \fIcmp\fP\&. .IP 3. 3 The \fBrb_parent\fP pointers are consistent. .IP 4. 3 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. .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBroot\fP \-\- \fBstruct rb_root *\fP .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct rb_node\fP member in entry type. .IP \(bu 2 \fBcmp\fP \-\- Callback taking two \fBtype *\fP 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. .IP \(bu 2 \fBallow_equal\fP \-\- Whether the tree may contain entries that compare equal to each other. .UNINDENT .TP .B Raises \fI\%ValidationError\fP \-\- if the tree is invalid .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.rbtree.validate_rbtree_inorder_for_each_entry(type: Union[str, \fI\%drgn.Type\fP], root: \fI\%drgn.Object\fP, member: str, cmp: Callable[[\fI\%drgn.Object\fP, \fI\%drgn.Object\fP], int], allow_equal: bool) -> Iterator[\fI\%drgn.Object\fP] Like \fI\%rbtree_inorder_for_each_entry()\fP, but validates the red\-black tree like \fI\%validate_rbtree()\fP while iterating. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP \-\- Entry type. .IP \(bu 2 \fBroot\fP \-\- \fBstruct rb_root *\fP .IP \(bu 2 \fBmember\fP \-\- Name of \fBstruct rb_node\fP member in entry type. .IP \(bu 2 \fBcmp\fP \-\- Callback taking two \fBtype *\fP 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. .IP \(bu 2 \fBallow_equal\fP \-\- Whether the tree may contain entries that compare equal to each other. .UNINDENT .TP .B Raises \fI\%ValidationError\fP \-\- if the tree is invalid .UNINDENT .UNINDENT .SS CPU Scheduler .sp The \fBdrgn.helpers.linux.sched\fP module provides helpers for working with the Linux CPU scheduler. .INDENT 0.0 .TP .B drgn.helpers.linux.sched.task_cpu(task: \fI\%drgn.Object\fP) -> int Return the CPU number that the given task last ran on. .INDENT 7.0 .TP .B Parameters \fBtask\fP \-\- \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.sched.cpu_curr(prog: \fI\%drgn.Program\fP, cpu: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the task running on the given CPU. .sp .EX >>> cpu_curr(7).comm (char [16])\(dqpython3\(dq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBcpu\fP \-\- CPU number. .UNINDENT .TP .B Returns \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.sched.idle_task(prog: \fI\%drgn.Program\fP, cpu: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Return the idle thread (PID 0, a.k.a swapper) for the given CPU. .sp .EX >>> idle_task(1).comm (char [16])\(dqswapper/1\(dq .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBcpu\fP \-\- CPU number. .UNINDENT .TP .B Returns \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.sched.task_state_to_char(task: \fI\%drgn.Object\fP) -> str Get the state of the task as a character (e.g., \fB\(aqR\(aq\fP for running). See \fI\%ps(1)\fP for a description of the process state codes. .INDENT 7.0 .TP .B Parameters \fBtask\fP \-\- \fBstruct task_struct *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.sched.loadavg(prog: \fI\%drgn.Program\fP) -> Tuple[float, float, float] Return system load averaged over 1, 5 and 15 minutes as tuple of three float values. .sp .EX >>> loadavg() (2.34, 0.442, 1.33) .EE .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .SS Slab Allocator .sp The \fBdrgn.helpers.linux.slab\fP module provides helpers for working with the Linux slab allocator. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Beware of slab merging when using these helpers. See \fI\%slab_cache_is_merged()\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.slab_cache_is_merged(slab_cache: \fI\%drgn.Object\fP) -> bool Return whether a slab cache has been merged with any other slab caches. .sp Unless configured otherwise, the kernel may merge slab caches of similar sizes together. See the \fI\%SLUB users guide\fP and \fBslab_merge\fP/\fBslab_nomerge\fP in the \fI\%kernel parameters documentation\fP\&. .sp 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. .sp For example, suppose that we have two types, \fBstruct foo\fP and \fBstruct bar\fP, which have the same size but are otherwise unrelated. If the kernel creates a slab cache named \fBfoo\fP for \fBstruct foo\fP, then another slab cache named \fBbar\fP for \fBstruct bar\fP, then slab cache \fBfoo\fP will be reused instead of creating another cache for \fBbar\fP\&. So the following will fail: .INDENT 7.0 .INDENT 3.5 .sp .EX find_slab_cache(\(dqbar\(dq) .EE .UNINDENT .UNINDENT .sp And the following will also return \fBstruct bar *\fP objects errantly casted to \fBstruct foo *\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX slab_cache_for_each_allocated_object(find_slab_cache(\(dqfoo\(dq), \(dqstruct foo\(dq) .EE .UNINDENT .UNINDENT .sp 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). .INDENT 7.0 .TP .B Parameters \fBslab_cache\fP \-\- \fBstruct kmem_cache *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.get_slab_cache_aliases(prog: \fI\%drgn.Program\fP) -> Dict[str, str] Return a dict mapping slab cache name to the cache it was merged with. .sp The SLAB and SLUB subsystems can merge caches with similar settings and object sizes, as described in the documentation of \fI\%slab_cache_is_merged()\fP\&. 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 \fBCONFIG_SLUB\fP and \fBCONFIG_SYSFS\fP\&. .sp 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 \fI\%find_slab_cache()\fP\&. The dict contains an entry only for caches which were merged into a cache of a different name. .sp .EX >>> cache_to_merged = get_slab_cache_aliases() >>> cache_to_merged[\(dqdnotify_struct\(dq] \(aqavc_xperms_data\(aq >>> \(dqavc_xperms_data\(dq in cache_to_merged False >>> find_slab_cache(\(dqdnotify_struct\(dq) is None True >>> find_slab_cache(\(dqavc_xperms_data\(dq) is None False .EE .INDENT 7.0 .TP .B Warning This function will only work on kernels which are built with \fBCONFIG_SLUB\fP and \fBCONFIG_SYSFS\fP enabled. .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Mapping of slab cache name to final merged name .TP .B Raises \fBLookupError\fP \-\- If the helper fails because the debugged kernel doesn\(aqt have the required configuration .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.for_each_slab_cache(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all slab caches. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct kmem_cache *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.find_slab_cache(prog: \fI\%drgn.Program\fP, name: Union[str, bytes]) -> Optional[\fI\%drgn.Object\fP] Return the slab cache with the given name. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBname\fP \-\- Slab cache name. .UNINDENT .TP .B Returns \fBstruct kmem_cache *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.print_slab_caches(prog: \fI\%drgn.Program\fP) -> None Print the name and \fBstruct kmem_cache *\fP value of all slab caches. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.slab_cache_for_each_allocated_object(slab_cache: \fI\%drgn.Object\fP, type: Union[str, \fI\%drgn.Type\fP]) -> Iterator[\fI\%drgn.Object\fP] Iterate over all allocated objects in a given slab cache. .sp Only the SLUB and SLAB allocators are supported; SLOB does not store enough information to identify objects in a slab cache. .sp .EX >>> dentry_cache = find_slab_cache(\(dqdentry\(dq) >>> next(slab_cache_for_each_allocated_object(dentry_cache, \(dqstruct dentry\(dq)) *(struct dentry *)0xffff905e41404000 = { ... } .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBslab_cache\fP \-\- \fBstruct kmem_cache *\fP .IP \(bu 2 \fBtype\fP \-\- Type of object in the slab cache. .UNINDENT .TP .B Returns Iterator of \fBtype *\fP objects. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.slab_object_info(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> Optional[\fI\%SlabObjectInfo\fP] Get information about an address if it is in a slab object. .sp .EX >>> ptr = find_task(1).comm.address_of_() >>> info = slab_object_info(ptr) >>> info SlabObjectInfo(slab_cache=Object(prog, \(aqstruct kmem_cache *\(aq, address=0xffffdb93c0045e18), slab=Object(prog, \(aqstruct slab *\(aq, value=0xffffdb93c0045e00), address=0xffffa2bf81178000, allocated=True) .EE .sp Note that \fI\%SlabObjectInfo.address\fP is the start address of the object, which may be less than \fIaddr\fP if \fIaddr\fP points to a member inside of the object: .sp .EX >>> ptr.value_() \- info.address 1496 >>> offsetof(prog.type(\(dqstruct task_struct\(dq), \(dqcomm\(dq) 1496 .EE .sp 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 \fBNone\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fI\%SlabObjectInfo\fP if \fIaddr\fP is in a slab object, or \fBNone\fP if not. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class drgn.helpers.linux.slab.SlabObjectInfo Information about an object in the slab allocator. .INDENT 7.0 .TP .B slab_cache: \fI\%drgn.Object\fP \fBstruct kmem_cache *\fP that the slab object is from. .UNINDENT .INDENT 7.0 .TP .B slab: \fI\%drgn.Object\fP Slab containing the slab object. .sp Since Linux v5.17, this is a \fBstruct slab *\fP\&. Before that, it is a \fBstruct page *\fP\&. .UNINDENT .INDENT 7.0 .TP .B address: int Address of the slab object. .UNINDENT .INDENT 7.0 .TP .B allocated: bool \fBTrue\fP if the object is allocated, \fBFalse\fP if it is free. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.slab.find_containing_slab_cache(prog: \fI\%drgn.Program\fP, addr: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get the slab cache that an address was allocated from, if any. .sp 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 \fBNULL\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBaddr\fP \-\- \fBvoid *\fP .UNINDENT .TP .B Returns \fBstruct kmem_cache *\fP containing \fIaddr\fP, or \fBNULL\fP if \fIaddr\fP is not from a slab cache. .UNINDENT .UNINDENT .SS Stack Depot .sp The \fBdrgn.helpers.linux.stackdepot\fP module provides helpers for working with the stack trace storage from \fI\%include/linux/stackdepot.h\fP used by KASAN and other kernel debugging tools. .INDENT 0.0 .TP .B drgn.helpers.linux.stackdepot.stack_depot_fetch(handle: \fI\%drgn.Object\fP) -> Optional[\fI\%drgn.StackTrace\fP] Returns a stack trace for the given stack handle. .INDENT 7.0 .TP .B Parameters \fBhandle\fP \-\- \fBdepot_stack_handle_t\fP .TP .B Returns The stack trace, or \fBNone\fP if not available. .UNINDENT .UNINDENT .SS Traffic Control (TC) .sp The \fBdrgn.helpers.linux.tc\fP module provides helpers for working with the Linux kernel Traffic Control (TC) subsystem. .INDENT 0.0 .TP .B drgn.helpers.linux.tc.qdisc_lookup(dev: \fI\%drgn.Object\fP, major: \fI\%drgn.IntegerLike\fP) -> \fI\%drgn.Object\fP Get a Qdisc from a device and a major handle number. It is worth noting that conventionally handles are hexadecimal, e.g. \fB10:\fP in a \fBtc\fP command means major handle 0x10. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdev\fP \-\- \fBstruct net_device *\fP .IP \(bu 2 \fBmajor\fP \-\- Qdisc major handle number. .UNINDENT .TP .B Returns \fBstruct Qdisc *\fP (\fBNULL\fP if not found) .UNINDENT .UNINDENT .SS TCP .sp The \fBdrgn.helpers.linux.tcp\fP module provides helpers for working with the TCP protocol in the Linux kernel. .INDENT 0.0 .TP .B drgn.helpers.linux.tcp.sk_tcpstate(sk: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the TCP protocol state of a socket. .INDENT 7.0 .TP .B Parameters \fBsk\fP \-\- \fBstruct sock *\fP .TP .B Returns TCP state enum value. .UNINDENT .UNINDENT .SS Users .sp The \fBdrgn.helpers.linux.user\fP module provides helpers for working with users in the Linux kernel. .INDENT 0.0 .TP .B drgn.helpers.linux.user.find_user(prog: \fI\%drgn.Program\fP, uid: Union[\fI\%drgn.Object\fP, \fI\%drgn.IntegerLike\fP]) -> \fI\%drgn.Object\fP Return the user structure with the given UID. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .IP \(bu 2 \fBuid\fP \-\- \fBkuid_t\fP object or integer. .UNINDENT .TP .B Returns \fBstruct user_struct *\fP (\fBNULL\fP if not found) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.user.for_each_user(prog: \fI\%drgn.Program\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all users in the system. .INDENT 7.0 .TP .B Parameters \fBprog\fP \-\- Program, which \fI\%may be omitted to use the default program argument\fP\&. .TP .B Returns Iterator of \fBstruct user_struct *\fP objects. .UNINDENT .UNINDENT .SS Wait Queues .sp The \fBdrgn.helpers.linux.wait\fP module provides helpers for working with wait queues (\fBwait_queue_head_t\fP and \fBwait_queue_entry_t\fP) from \fI\%include/linux/wait.h\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since Linux 4.13, entries in a wait queue have type \fBwait_queue_entry_t\fP\&. Before that, the type was named \fBwait_queue_t\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.wait.waitqueue_active(wq: \fI\%drgn.Object\fP) -> bool Return whether a wait queue has any waiters. .INDENT 7.0 .TP .B Parameters \fBwq\fP \-\- \fBwait_queue_head_t *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.wait.waitqueue_for_each_entry(wq: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all entries in a wait queue. .INDENT 7.0 .TP .B Parameters \fBwq\fP \-\- \fBwait_queue_head_t *\fP .TP .B Returns Iterator of \fBwait_queue_entry_t *\fP or \fBwait_queue_t *\fP objects depending on the kernel version. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.wait.waitqueue_for_each_task(wq: \fI\%drgn.Object\fP) -> Iterator[\fI\%drgn.Object\fP] Iterate over all tasks waiting on a wait queue. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This comes from \fBwait_queue_entry_t::private\fP, which usually stores a task. However, some wait queue entries store a different pointer type, in which case this will return garbage. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters \fBwq\fP \-\- \fBwait_queue_head_t *\fP .TP .B Returns Iterator of \fBstruct task_struct *\fP objects. .UNINDENT .UNINDENT .SS XArrays .sp The \fBdrgn.helpers.linux.xarray\fP module provides helpers for working with the \fI\%XArray\fP data structure from \fI\%include/linux/xarray.h\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 XArrays were introduced in Linux 4.20 as a replacement for \fI\%radix trees\fP\&. To make it easier to work with data structures that were changed from a radix tree to an XArray (like \fBstruct address_space::i_pages\fP), drgn treats XArrays and radix trees interchangeably in some cases. .sp Specifically, \fI\%xa_load()\fP is equivalent to \fI\%radix_tree_lookup()\fP, and \fI\%xa_for_each()\fP is equivalent to \fI\%radix_tree_for_each()\fP, except that the radix tree helpers assume \fBadvanced=False\fP\&. (Therefore, \fI\%xa_load()\fP and \fI\%xa_for_each()\fP also accept a \fBstruct radix_tree_root *\fP, and \fI\%radix_tree_lookup()\fP and \fI\%radix_tree_for_each()\fP also accept a \fBstruct xarray *\fP\&.) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.xarray.xa_load(xa: \fI\%drgn.Object\fP, index: \fI\%drgn.IntegerLike\fP, *, advanced: bool = False) -> \fI\%drgn.Object\fP Look up the entry at a given index in an XArray. .sp .EX >>> entry = xa_load(inode.i_mapping.i_pages.address_of_(), 2) >>> cast(\(dqstruct page *\(dq, entry) *(struct page *)0xffffed6980306f40 = { ... } .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBxa\fP \-\- \fBstruct xarray *\fP .IP \(bu 2 \fBindex\fP \-\- Entry index. .IP \(bu 2 \fBadvanced\fP \-\- Whether to return nodes only visible to the XArray advanced API. If \fBFalse\fP, zero entries (see \fI\%xa_is_zero()\fP) will be returned as \fBNULL\fP\&. .UNINDENT .TP .B Returns \fBvoid *\fP found entry, or \fBNULL\fP if not found. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.xarray.xa_for_each(xa: \fI\%drgn.Object\fP, *, advanced: bool = False) -> Iterator[Tuple[int, \fI\%drgn.Object\fP]] Iterate over all of the entries in an XArray. .sp .EX >>> 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 .EE .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBxa\fP \-\- \fBstruct xarray *\fP .IP \(bu 2 \fBadvanced\fP \-\- Whether to return nodes only visible to the XArray advanced API. If \fBFalse\fP, zero entries (see \fI\%xa_is_zero()\fP) will be skipped. .UNINDENT .TP .B Returns Iterator of (index, \fBvoid *\fP) tuples. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.xarray.xa_is_value(entry: \fI\%drgn.Object\fP) -> bool Return whether an XArray entry is a value. .sp See \fI\%xa_to_value()\fP\&. .INDENT 7.0 .TP .B Parameters \fBentry\fP \-\- \fBvoid *\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.xarray.xa_to_value(entry: \fI\%drgn.Object\fP) -> \fI\%drgn.Object\fP Return the value in an XArray entry. .sp In addition to pointers, XArrays can store integers between 0 and \fBLONG_MAX\fP\&. If \fI\%xa_is_value()\fP returns \fBTrue\fP, use this to get the stored integer. .sp .EX >>> entry = xa_load(xa, 9) >>> entry (void *)0xc9 >>> xa_is_value(entry) True >>> xa_to_value(entry) (unsigned long)100 .EE .INDENT 7.0 .TP .B Parameters \fBentry\fP \-\- \fBvoid *\fP .TP .B Returns \fBunsigned long\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B drgn.helpers.linux.xarray.xa_is_zero(entry: \fI\%drgn.Object\fP) -> bool Return whether an XArray entry is a \(dqzero\(dq entry. .sp 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 \fI\%xa_load()\fP and \fI\%xa_for_each()\fP when \fBadvanced = True\fP\&. .sp .EX >>> entry = xa_load(xa, 10, advanced=True) >>> entry (void *)0x406 >>> xa_is_zero(entry) True >>> xa_load(xa, 10) (void *)0 .EE .INDENT 7.0 .TP .B Parameters \fBentry\fP \-\- \fBvoid *\fP .UNINDENT .UNINDENT .SS Support Matrix .SS Architectures .sp Some features in drgn require architecture\-specific support. The current status of this support is: .TS center; |l|l|l|l|. _ T{ Architecture T} T{ Linux Kernel Modules [1] T} T{ Stack Traces [2] T} T{ Virtual Address Translation [3] T} _ T{ x86\-64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ AArch64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ s390x T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ ppc64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ i386 T} T{ ✓ T} T{ T} T{ T} _ T{ Arm T} T{ ✓ T} T{ T} T{ T} _ T{ RISC\-V T} T{ ✓ T} T{ T} T{ T} _ .TE .sp Key .IP [1] 5 Support for loading debugging symbols for Linux kernel modules. .IP [2] 5 Support for capturing stack traces (\fI\%drgn.Program.stack_trace()\fP, \fI\%drgn.Thread.stack_trace()\fP). .IP [3] 5 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 \fI\%drgn.helpers.linux.mm\fP\&. .sp The listed architectures are recognized in \fI\%drgn.Architecture\fP\&. Other architectures are represented by \fI\%drgn.Architecture.UNKNOWN\fP\&. Features not mentioned above should work on any architecture, listed or not. .SS Cross\-Debugging .sp 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. .SS Linux Kernel Versions .sp drgn officially supports the current mainline, stable, and longterm kernel releases from \fI\%kernel.org\fP\&. (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: .INDENT 0.0 .IP \(bu 2 6.0\-6.8 .IP \(bu 2 5.10\-5.19 .IP \(bu 2 5.4 .IP \(bu 2 4.19 .IP \(bu 2 4.14 .IP \(bu 2 4.9 .UNINDENT .sp Other versions are not tested. They\(aqll probably mostly work, but support is best\-effort. .SS Kernel Configuration .sp drgn supports debugging kernels with various configurations: .INDENT 0.0 .IP \(bu 2 SMP and !SMP. .IP \(bu 2 Preemptible and non\-preemptible. .IP \(bu 2 SLUB, SLAB, and SLOB allocators. .UNINDENT .sp drgn requires a kernel configured with \fBCONFIG_PROC_KCORE=y\fP for live kernel debugging. .SS Case Studies .sp These are writeups of real\-world problems solved with drgn. .SS Recovering a dm\-crypt Encryption Key .nf Author: Omar Sandoval Date: January 11th, 2024 .fi .sp .sp \fI\%dm\-crypt\fP is the Linux kernel\(aqs 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. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The dm\-crypt master key is obviously very sensitive information that shouldn\(aqt be exposed carelessly. .sp As a disclaimer for anyone concerned about the security implications: everything is working as intended here. Debugging the live kernel with drgn requires \fBroot\fP, and \fBroot\fP has many other ways to access sensitive information (loading kernel modules, triggering a kernel core dump, etc.). Solutions like \fI\%inline encryption\fP and \fBkernel_lockdown(7)\fP can be used for defense in depth if necessary. .UNINDENT .UNINDENT .SS Setup .sp For this writeup, I\(aqm going to set up dm\-crypt in a virtual machine running Linux 6.7. .INDENT 0.0 .INDENT 3.5 .sp .EX # uname \-r 6.7.0 # cryptsetup luksFormat /dev/vdb WARNING! ======== This will overwrite data on /dev/vdb irrevocably. Are you sure? (Type \(aqyes\(aq in capital letters): YES Enter passphrase for /dev/vdb: hello Verify passphrase: hello # cryptsetup open /dev/vdb mycrypt Enter passphrase for /dev/vdb: hello .EE .UNINDENT .UNINDENT .sp The default configuration is \fI\%AES\fP in \fI\%XTS\fP mode with a 512\-bit key: .INDENT 0.0 .INDENT 3.5 .sp .EX # 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 .EE .UNINDENT .UNINDENT .sp The new device is \fBdm\-0\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX # realpath /dev/mapper/mycrypt /dev/dm\-0 .EE .UNINDENT .UNINDENT .SS Getting from Device Mapper to the Crypto API .sp The \fI\%dm\-crypt documentation\fP tells us that \(dqDevice\-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.\(dq .sp 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\(aqre going to have to navigate through the device mapper code. .sp To start, let\(aqs find the virtual disk for our dm\-crypt target in drgn using the \fI\%for_each_disk()\fP and \fI\%disk_name()\fP helpers: .sp .EX >>> for disk in for_each_disk(): \&... if disk_name(disk) == b\(dqdm\-0\(dq: \&... print(disk) \&... break \&... *(struct gendisk *)0xffffa3b9421b2c00 = { ... } .EE .sp \fBstruct gendisk\fP has a function table, \fBfops\fP, with callbacks to the disk driver. Specifically, the \fBsubmit_bio\fP callback intercepts disk reads and writes: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> disk.fops.submit_bio (void (*)(struct bio *))dm_submit_bio+0x0 = 0xffffffffc05761e0 .EE .UNINDENT .UNINDENT .sp Let\(aqs take a look at \fI\%dm_submit_bio()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX 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); ... } .EE .UNINDENT .UNINDENT .sp So the disk\(aqs private data is a \fBstruct mapped_device\fP\&. Let\(aqs get it in drgn: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> md = cast(\(dqstruct mapped_device *\(dq, disk.private_data) .EE .UNINDENT .UNINDENT .sp \fI\%dm_get_live_table()\fP gets the device mapper table: .INDENT 0.0 .INDENT 3.5 .sp .EX 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); } .EE .UNINDENT .UNINDENT .sp \fI\%SRCU\fP is a synchronization mechanism which we can blithely ignore: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> map = cast(\(dqstruct dm_table *\(dq, md.map) .EE .UNINDENT .UNINDENT .sp \fBdm_submit_bio()\fP then calls \fI\%dm_split_and_process_bio()\fP, which calls \fI\%__split_and_process_bio()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX 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); } .EE .UNINDENT .UNINDENT .sp \fI\%dm_table_find_target()\fP finds the appropriate device mapper target in a table: .INDENT 0.0 .INDENT 3.5 .sp .EX struct dm_target *dm_table_find_target(struct dm_table *t, sector_t sector) { ... return &t\->targets[(KEYS_PER_NODE * n) + k]; } .EE .UNINDENT .UNINDENT .sp Our simple case only has one target: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> map.num_targets (unsigned int)1 >>> ti = map.targets .EE .UNINDENT .UNINDENT .sp \fB__split_and_process_bio()\fP then calls \fI\%__map_bio()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX 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); ... } .EE .UNINDENT .UNINDENT .sp So we need to look at another callback: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> ti.type.map (dm_map_fn)crypt_map+0x0 = 0xffffffffc08a03f0 .EE .UNINDENT .UNINDENT .sp \fI\%crypt_map()\fP is part of dm\-crypt, so we\(aqve finally made it out of generic device mapper: .INDENT 0.0 .INDENT 3.5 .sp .EX static int crypt_map(struct dm_target *ti, struct bio *bio) { struct dm_crypt_io *io; struct crypt_config *cc = ti\->private; ... .EE .UNINDENT .UNINDENT .sp And we have the dm\-crypt configuration: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> cc = cast(\(dqstruct crypt_config *\(dq, ti.private) .EE .UNINDENT .UNINDENT .sp Dumping it out reveals some crypto API context! .INDENT 0.0 .INDENT 3.5 .sp .EX >>> cc *(struct crypt_config *)0xffffa3b9421b2400 = { ... .cipher_tfm = (union ){ .tfms = (struct crypto_skcipher **)0xffffa3b9438667c0, ... }, .tfms_count = (unsigned int)1, ... } >>> tfm = cc.cipher_tfm.tfms[0] .EE .UNINDENT .UNINDENT .SS Descending Down the Crypto API .sp 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. .sp The crypto API refers to cryptographic ciphers as \fI\%\(dqtransformations\(dq\fP\&. Transformations can be combined and nested in various ways. The \fBtfm\fP variable we found is a \fI\%\(dqtransformation object\(dq\fP, which is an instance of a transformation: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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])\(dqxts(aes)\(dq, ... } .EE .UNINDENT .UNINDENT .sp This is an \fBskcipher\fP, or a symmetric key cipher. It is using the \fBxts(aes)\fP algorithm as expected. \fB__crt_ctx\fP is an opaque context, which is promising if we can figure out how to interpret it. The \fBexit\fP callback looks like a cleanup function. That seems like a good way for us to figure out how \fB__crt_ctx\fP is used. Here are \fI\%crypto_skcipher_exit_tfm()\fP and the \fI\%crypto_skcipher_alg()\fP and \fI\%crypto_skcipher_tfm()\fP getters it uses: .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .sp We can emulate the getters in drgn to find the underlying implementation: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> def crypto_skcipher_alg(tfm): \&... return container_of(tfm.base.__crt_alg, \(dqstruct skcipher_alg\(dq, \(dqbase\(dq) \&... >>> crypto_skcipher_alg(tfm).exit (void (*)(struct crypto_skcipher *))simd_skcipher_exit+0x0 = 0xffffffffc058b1f0 .EE .UNINDENT .UNINDENT .sp My machine supports the \fI\%AES\-NI\fP x86 extension. The kernel cannot use SIMD instructions like AES\-NI in some contexts, so it has an \fI\%extra layer of indirection\fP to go through an asynchronous daemon when necessary. This involves a couple of wrapper transformation objects. \fI\%simd_skcipher_exit()\fP shows us how to unwrap the first one: .INDENT 0.0 .INDENT 3.5 .sp .EX static void simd_skcipher_exit(struct crypto_skcipher *tfm) { struct simd_skcipher_ctx *ctx = crypto_skcipher_ctx(tfm); cryptd_free_skcipher(ctx\->cryptd_tfm); } .EE .UNINDENT .UNINDENT .sp We just need one more getter in drgn, \fI\%crypto_skcipher_ctx()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> def crypto_skcipher_ctx(tfm): \&... return cast(\(dqvoid *\(dq, tfm.base.__crt_ctx) \&... >>> simd_ctx = cast(\(dqstruct simd_skcipher_ctx *\(dq, 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 *[]){}, }, }, } .EE .UNINDENT .UNINDENT .sp We saw \fBcrypto_skcipher_exit_tfm()\fP earlier, so we know where to look next: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> crypto_skcipher_alg(cryptd_tfm.base).exit (void (*)(struct crypto_skcipher *))cryptd_skcipher_exit_tfm+0x0 = 0xffffffffc04d6210 .EE .UNINDENT .UNINDENT .sp \fI\%cryptd_skcipher_exit_tfm()\fP shows us how to unwrap this transformation object: .INDENT 0.0 .INDENT 3.5 .sp .EX static void cryptd_skcipher_exit_tfm(struct crypto_skcipher *tfm) { struct cryptd_skcipher_ctx *ctx = crypto_skcipher_ctx(tfm); crypto_free_skcipher(ctx\->child); } .EE .UNINDENT .UNINDENT .sp Now we can get the actual cipher transformation object: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> cryptd_ctx = cast(\(dqstruct cryptd_skcipher_ctx *\(dq, 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 *[]){}, }, } .EE .UNINDENT .UNINDENT .sp This one doesn\(aqt have an exit callback, so let\(aqs look at the algorithm: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> crypto_skcipher_alg(child_tfm) *(struct skcipher_alg *)0xffffffffc05e7d40 = { .setkey = (int (*)(struct crypto_skcipher *, const u8 *, unsigned int))xts_aesni_setkey+0x0 = 0xffffffffc059efb0, ... } .EE .UNINDENT .UNINDENT .sp \fI\%xts_aesni_setkey()\fP is very enlightening: .INDENT 0.0 .INDENT 3.5 .sp .EX 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); } .EE .UNINDENT .UNINDENT .sp XTS splits the provided key into two keys: one for data and one for a \(dqtweak\(dq. They are stored in \fBctx\->crypt_ctx\fP and \fBctx\->tweak_ctx\fP, respectively. .sp To reach \fBctx\fP, we need one more getter, \fI\%aes_xts_ctx()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX static inline struct aesni_xts_ctx *aes_xts_ctx(struct crypto_skcipher *tfm) { return aes_align_addr(crypto_skcipher_ctx(tfm)); } .EE .UNINDENT .UNINDENT .sp Which uses \fI\%aes_align_addr()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX #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); } .EE .UNINDENT .UNINDENT .sp Implementing that in drgn gets us the key material! .INDENT 0.0 .INDENT 3.5 .sp .EX >>> def aes_xts_ctx(tfm): \&... AESNI_ALIGN = 16 \&... mask = AESNI_ALIGN \- 1 \&... ctx = cast(\(dqunsigned long\(dq, crypto_skcipher_ctx(tfm)) \&... return cast(\(dqstruct aesni_xts_ctx *\(dq, (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, }, } .EE .UNINDENT .UNINDENT .SS Extracting the AES Key .sp Since we have a 512\-bit key, XTS uses two 256\-bit AES keys. You\(aqll notice that the \fBkey_enc\fP fields above are much larger than that. This is because AES expands the key into a number of \(dqround keys\(dq using a \fI\%\(dqkey schedule\(dq\fP\&. Luckily, the first few round keys are copied directly from the original key. .sp With that information, we can finally recover the original key: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> def aes_key_from_ctx(ctx): \&... words = ctx.key_enc.value_()[:ctx.key_length / 4] \&... return b\(dq\(dq.join(word.to_bytes(4, \(dqlittle\(dq) for word in words) \&... >>> aes_key_from_ctx(xts_ctx.crypt_ctx).hex() \(aq005b6e05633d5764a46ebe108f47ce637b1ba4cb1140af05952e5909c51f2120\(aq >>> aes_key_from_ctx(xts_ctx.tweak_ctx).hex() \(aq01f3a0f1aaa11f97aacc77d0de8c9b1946e7610b9fe60125c91d9ca296cadd5d\(aq .EE .UNINDENT .UNINDENT .sp Which we can double check with cryptsetup: .INDENT 0.0 .INDENT 3.5 .sp .EX # 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 \(aqyes\(aq 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 .EE .UNINDENT .UNINDENT .SS Conclusion .sp 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. .sp 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. .sp I converted this case study to the \fI\%dm_crypt_key.py\fP script in drgn\(aqs \fBcontrib\fP directory. It could be extended to cover other ciphers in the future. .SS Using Stack Trace Variables to Find a Kyber Bug .nf Author: Omar Sandoval Date: June 9th, 2021 .fi .sp .sp Jakub Kicinski reported a crash in the \fI\%Kyber I/O scheduler\fP 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. .sp First, we can get the task that crashed: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> task = per_cpu(prog[\(dqrunqueues\(dq], prog[\(dqcrashing_cpu\(dq]).curr .EE .UNINDENT .UNINDENT .sp Then, we can get its stack trace: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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) .EE .UNINDENT .UNINDENT .sp It looks like \fBkyber_bio_merge()\fP tried to lock an invalid spinlock. For reference, this is the source code of \fBkyber_bio_merge()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .sp When printed, the \fBkcq\fP structure containing the spinlock indeed looks like garbage (omitted for brevity). .sp A crash course on the Linux kernel block layer: for each block device, there is a \(dqsoftware queue\(dq (\fBstruct blk_mq_ctx *ctx\fP) for each CPU and a \(dqhardware queue\(dq (\fBstruct blk_mq_hw_ctx *hctx\fP) 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 (\fBstruct kyber_hctx_data *khd\fP) and per software queue (\fBstruct kyber_ctx_queue *kcq\fP). .sp Let\(aqs try to figure out where the bad \fBkcq\fP came from. It should be an element of the \fBkhd\->kcqs\fP array (\fBkhd\fP is optimized out, but we can recover it from \fBhctx\->sched_data\fP): .INDENT 0.0 .INDENT 3.5 .sp .EX >>> trace[4][\(dqkhd\(dq] (struct kyber_hctx_data *) >>> hctx = trace[4][\(dqhctx\(dq] >>> khd = cast(\(dqstruct kyber_hctx_data *\(dq, hctx.sched_data) >>> trace[4][\(dqkcq\(dq] \- khd.kcqs (ptrdiff_t)1 >>> hctx.nr_ctx (unsigned short)1 .EE .UNINDENT .UNINDENT .sp So the \fBkcq\fP is for the second software queue, but the hardware queue is only supposed to have one software queue. Let\(aqs see which CPU was assigned to the hardware queue: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> hctx.ctxs[0].cpu (unsigned int)6 .EE .UNINDENT .UNINDENT .sp Here\(aqs the problem: we\(aqre not running on CPU 6, we\(aqre running on CPU 19: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> prog[\(dqcrashing_cpu\(dq] (int)19 .EE .UNINDENT .UNINDENT .sp And CPU 19 is assigned to a different hardware queue that actually does have two software queues: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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 .EE .UNINDENT .UNINDENT .sp The bug is that the caller gets the \fBhctx\fP for the current CPU, then \fBkyber_bio_merge()\fP gets the \fBctx\fP for the current CPU, and if the thread is migrated to another CPU in between, they won\(aqt match. The fix is to get a consistent view of the \fBhctx\fP and \fBctx\fP\&. The commit that fixes this is \fI\%here\fP\&. .SS Getting Debugging Symbols .sp Most Linux distributions don\(aqt 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: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo drgn could not get debugging information for: kernel (could not find vmlinux for 5.14.14\-200.fc34.x86_64) \&... .EE .UNINDENT .UNINDENT .sp Then you need to install debugging symbols. .SS Fedora .sp Fedora makes it very easy to install debugging symbols with the \fI\%DNF debuginfo\-install plugin\fP, which is installed by default. Simply run \fBsudo dnf debuginfo\-install $package\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo dnf debuginfo\-install python3 .EE .UNINDENT .UNINDENT .sp To find out what package owns a binary, use \fBrpm \-qf\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX $ rpm \-qf $(which python3) python3\-3.9.7\-1.fc34.x86_64 .EE .UNINDENT .UNINDENT .sp To install symbols for the running kernel: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo dnf debuginfo\-install kernel\-$(uname \-r) .EE .UNINDENT .UNINDENT .sp Also see the \fI\%Fedora documentation\fP\&. .SS Debian .sp Debian requires you to manually add the debugging symbol repositories: .INDENT 0.0 .INDENT 3.5 .sp .EX $ 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 .EE .UNINDENT .UNINDENT .sp Then, debugging symbol packages can be installed with \fBsudo apt install\fP\&. Some debugging symbol packages are named with a \fB\-dbg\fP suffix: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo apt install python3\-dbg .EE .UNINDENT .UNINDENT .sp And some are named with a \fB\-dbgsym\fP suffix: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo apt install coreutils\-dbgsym .EE .UNINDENT .UNINDENT .sp You can use the \fBfind\-dbgsym\-packages\fP command from the \fBdebian\-goodies\fP package to find the correct name: .INDENT 0.0 .INDENT 3.5 .sp .EX $ 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 .EE .UNINDENT .UNINDENT .sp To install symbols for the running kernel: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo apt install linux\-image\-$(uname \-r)\-dbg .EE .UNINDENT .UNINDENT .sp Also see the \fI\%Debian documentation\fP\&. .SS Ubuntu .sp On Ubuntu, you must install the debugging symbol archive signing key and manually add the debugging symbol repositories: .INDENT 0.0 .INDENT 3.5 .sp .EX $ 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 .EE .UNINDENT .UNINDENT .sp Like Debian, some debugging symbol packages are named with a \fB\-dbg\fP suffix and some are named with a \fB\-dbgsym\fP suffix: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo apt install python3\-dbg $ sudo apt install coreutils\-dbgsym .EE .UNINDENT .UNINDENT .sp You can use the \fBfind\-dbgsym\-packages\fP command from the \fBdebian\-goodies\fP package to find the correct name: .INDENT 0.0 .INDENT 3.5 .sp .EX $ 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 .EE .UNINDENT .UNINDENT .sp To install symbols for the running kernel: .INDENT 0.0 .INDENT 3.5 .sp .EX $ sudo apt install linux\-image\-$(uname \-r)\-dbgsym .EE .UNINDENT .UNINDENT .sp Also see the \fI\%Ubuntu documentation\fP\&. .SS Arch Linux .sp Arch Linux unfortunately does not make debugging symbols available. Packages must be manually rebuilt with debugging symbols enabled. See the \fI\%ArchWiki\fP and the \fI\%feature request\fP\&. .SS Release Highlights .sp These are highlights of each release of drgn focusing on a few exciting items from the full \fI\%release notes\fP\&. .SS 0.0.26 (Released March 11th, 2024) .sp These are some of the highlights of drgn 0.0.26. See the \fI\%GitHub release\fP for the full release notes, including more improvements and bug fixes. .SS Miscellaneous Helpers .sp This release added several new Linux kernel helpers with no particular theme: .INDENT 0.0 .IP \(bu 2 \fI\%print_dmesg()\fP, a shortcut for printing the kernel log buffer. .IP \(bu 2 \fI\%idr_for_each_entry()\fP, a shortcut for iterating over an IDR and casting its entries to a specific type. .IP \(bu 2 \fI\%stack_depot_fetch()\fP for getting stack traces from the storage used by KASAN and other kernel debugging tools. This was contributed by Peter Collingbourne. .IP \(bu 2 \fI\%plist_head_empty()\fP, \fI\%plist_node_empty()\fP, \fI\%plist_first_entry()\fP, \fI\%plist_last_entry()\fP, \fI\%plist_for_each()\fP, and \fI\%plist_for_each_entry()\fP, helpers for working with the kernel\(aqs priority\-sorted lists. .UNINDENT .SS \fBfsrefs.py\fP Tool .sp The \fBfsrefs.py\fP tool was added to the \fBtools\fP directory. It prints information about everything that is referencing a file or filesystem. This is similar to \fBfuser(1)\fP and \fBlsof(8)\fP, but it can find more since it has access to kernel internals. .INDENT 0.0 .INDENT 3.5 .sp .EX $ ./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 \&... .EE .UNINDENT .UNINDENT .sp \fBfsrefs.py\fP currently checks: .INDENT 0.0 .IP \(bu 2 File descriptors .IP \(bu 2 Task working directories .IP \(bu 2 Task root directories .IP \(bu 2 Memory mappings .IP \(bu 2 Filesystem mounts .IP \(bu 2 \fI\%binfmt_misc\fP .IP \(bu 2 \fBloop(4)\fP devices .IP \(bu 2 Swap files .IP \(bu 2 \fI\%uprobes\fP .UNINDENT .sp It will be extended to check more as the need arises, so feel free to report anything it missed. .sp (Note that as opposed to the \fBcontrib\fP directory, scripts in the \fBtools\fP directory are regularly maintained and tested.) .SS DWARF Package Files .sp drgn now supports split DWARF package (.dwp) files. These are generated by the \fBdwp\fP and \fBllvm\-dwp\fP tools. .SS Linux 6.8 Support .sp 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. .sp From \fI\%path_lookup()\fP or \fI\%for_each_mount()\fP (fixed by Johannes Thumshirn): .INDENT 0.0 .INDENT 3.5 .sp .EX AttributeError: \(aqstruct mnt_namespace\(aq has no member \(aqlist\(aq .EE .UNINDENT .UNINDENT .sp From \fI\%path_lookup()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX AttributeError: \(aqstruct dentry\(aq has no member \(aqd_subdirs\(aq .EE .UNINDENT .UNINDENT .SS Python 3.13 Support .sp Python 3.13, currently in alpha, removed or changed some private APIs (\fB_PyDict_GetItemIdWithError()\fP, \fB_PyDict_SetItemId()\fP, and \fB_PyLong_AsByteArray()\fP) that drgn depended on, which caused build failures. This was fixed by using public APIs instead. .SS 0.0.25 (Released December 1st, 2023) .sp These are some of the highlights of drgn 0.0.25. See the \fI\%GitHub release\fP for the full release notes, including more improvements and bug fixes. .SS Omitting the \fBprog\fP Argument .sp As a usability improvement, \fBprog\fP can now be omitted from most function calls. For example, instead of \fI\%find_task(prog, 1234)\fP, you can now simply write \fI\%find_task(1234)\fP\&. Additionally, instead of \fI\%prog.stack_trace(1234)\fP, you can now write \fI\%stack_trace(1234)\fP\&. (The old way will continue to be supported.) .sp Most CLI users don\(aqt need to worry about how this works, but library users may want to understand the \fI\%Default Program\fP\&. .sp It\(aqs tricky balancing interactive convenience and sensible APIs for scripting, but we think this is a nice improvement overall! .SS Running Without \fBroot\fP .sp drgn debugs the live Linux kernel via \fB/proc/kcore\fP, which can only be accessed by the \fBroot\fP user (or a user with the \fBCAP_SYS_RAWIO\fP capability, to be precise). However, it\(aqs not necessary (or ideal) for the rest of drgn to run as \fBroot\fP\&. .sp Now when drgn is run against the live kernel as an unprivileged user, it will attempt to open \fB/proc/kcore\fP via \fBsudo(8)\fP\&. The rest of drgn will then run without extra privileges. .sp In other words, in order to debug the live kernel, all you need to do is \fI\%install debugging symbols\fP and run: .INDENT 0.0 .INDENT 3.5 .sp .EX $ drgn .EE .UNINDENT .UNINDENT .sp This feature was contributed by Stephen Brennan. .SS Maple Tree Helpers .sp \fI\%Maple trees\fP were introduced in Linux 6.1, initially to store virtual memory areas (VMAs). This release adds a couple of helpers for working with them. .sp \fI\%mtree_load()\fP looks up an entry in a maple tree: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> mtree_load(task.mm.mm_mt.address_of_(), 0x55d65cfaa000) (void *)0xffff97ad82bfc930 .EE .UNINDENT .UNINDENT .sp \fI\%mt_for_each()\fP iterates over a maple tree: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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 \&... .EE .UNINDENT .UNINDENT .SS VMA Helpers .sp This release also adds higher\-level helpers specifically for VMAs. .sp \fI\%vma_find()\fP looks up a VMA by address: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> vma_find(task.mm, 0x55d65cfaa000) *(struct vm_area_struct *)0xffff97ad82bfc930 = { ... } >>> vma_find(task.mm, 0x55d65cfa9fff) (struct vm_area_struct *)0 .EE .UNINDENT .UNINDENT .sp \fI\%for_each_vma()\fP iterates over every VMA in an address space: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> for vma in for_each_vma(task.mm): \&... print(vma) \&... *(struct vm_area_struct *)0xffff97ad82bfc930 = { ... } *(struct vm_area_struct *)0xffff97ad82bfc0a8 = { ... } \&... .EE .UNINDENT .UNINDENT .sp These helpers also handle older kernels without maple trees. .SS Wait Queue Helpers .sp Wait queues are a fundamental data structure and synchronization mechanism in the Linux kernel. Imran Khan contributed a few helpers for working with them. .sp \fI\%waitqueue_active()\fP returns whether a wait queue has any waiters: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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 .EE .UNINDENT .UNINDENT .sp \fI\%waitqueue_for_each_entry()\fP iterates over each entry in a wait queue: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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, }, } .EE .UNINDENT .UNINDENT .sp \fI\%waitqueue_for_each_task()\fP iterates over each task waiting on a wait queue (although note that this does not work for some special wait queues that don\(aqt store tasks): .INDENT 0.0 .INDENT 3.5 .sp .EX >>> for task in waitqueue_for_each_task(wq): \&... print(task.pid, task.comm) \&... (pid_t)294708 (char [16])\(dqzsh\(dq .EE .UNINDENT .UNINDENT .SS ppc64 Radix MMU Support .sp Sourabh Jain contributed ppc64 radix MMU virtual address translation support. This is the state of architecture support in this release: .SS drgn 0.0.25 Architecture Support .TS center; |l|l|l|l|. _ T{ Architecture T} T{ Linux Kernel Modules T} T{ Stack Traces T} T{ Virtual Address Translation T} _ T{ x86\-64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ AArch64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ s390x T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ ppc64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ i386 T} T{ ✓ T} T{ T} T{ T} _ T{ Arm T} T{ ✓ T} T{ T} T{ T} _ T{ RISC\-V T} T{ ✓ T} T{ T} T{ T} _ .TE .SS 0.0.24 (Released September 8th, 2023) .sp These are some of the highlights of drgn 0.0.24. See the \fI\%GitHub release\fP for the full release notes, including more improvements and bug fixes. .SS Linked List Length Helper .sp This release added \fI\%list_count_nodes()\fP, which returns the length of a Linux kernel linked list: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> list_count_nodes(prog[\(dqworkqueues\(dq].address_of_()) 29 .EE .UNINDENT .UNINDENT .SS Networking Helpers .sp This release added a couple of Linux kernel networking helpers requested by Jakub Kicinski. .sp \fI\%netdev_priv()\fP returns the private data of a network device: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> dev = netdev_get_by_name(prog, \(dqwlp0s20f3\(dq) >>> netdev_priv(dev) (void *)0xffff9419c9dec9c0 >>> netdev_priv(dev, \(dqstruct ieee80211_sub_if_data\(dq) *(struct ieee80211_sub_if_data *)0xffff9419c9dec9c0 = { ... } .EE .UNINDENT .UNINDENT .sp \fI\%skb_shinfo()\fP returns the shared info for a socket buffer. .SS C++ Lookups .sp This release added support for a few C++ features. .SS Simple Type Specifiers .sp Unlike C, C++ allows referring to \fBclass\fP, \fBstruct\fP, \fBunion\fP, and \fBenum\fP types without their respective keywords. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX class Foo { ... }; Foo foo; // Equivalent to class Foo foo; .EE .UNINDENT .UNINDENT .sp Previously, drgn always required the keyword, so \fBprog.type(\(dqclass Foo\(dq)\fP would succeed but \fBprog.type(\(dqFoo\(dq)\fP would fail with a \fBLookupError\fP\&. This requirement was surprising to C++ developers, so it was removed. For C++ programs, \fBprog.type(\(dqFoo\(dq)\fP will now find a \fBclass\fP, \fBstruct\fP, \fBunion\fP, or \fBenum\fP type named \fBFoo\fP (for C programs, the keyword is still required). .SS Nested Classes .sp Again unlike C, C++ allows \fBclass\fP, \fBstruct\fP, and \fBunion\fP types to be defined inside of other \fBclass\fP, \fBstruct\fP, and \fBunion\fP types. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX class Foo { public: class Bar { ... }; ... }; Foo::Bar bar; .EE .UNINDENT .UNINDENT .sp drgn can now find such types with \fBprog.type(\(dqFoo::Bar\(dq)\fP\&. .SS Member Functions .sp C++ supports member functions (a.k.a. methods). For example: .INDENT 0.0 .INDENT 3.5 .sp .EX class Foo { int method() { ... } }; .EE .UNINDENT .UNINDENT .sp drgn can now find member functions with \fI\%drgn.Program.function()\fP, \fI\%drgn.Program.object()\fP, or \fI\%drgn.Program[]\fP (e.g., \fBprog.function(\(dqFoo::method\(dq)\fP or \fBprog[\(dqFoo::method\(dq]\fP). .SS Split DWARF .sp drgn now supports split DWARF object (.dwo) files. This is enabled by the \fB\-gsplit\-dwarf\fP option in GCC and Clang or for the Linux kernel with \fBCONFIG_DEBUG_INFO_SPLIT=y\fP\&. .sp Split DWARF package (.dwp) file support is still in progress. .SS Performance Improvements .sp 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. .sp The C++ lookup and split DWARF support mentioned above require processing more information in drgn\(aqs debugging information indexing step, which it does on startup and whenever debugging information is manually loaded. This could\(aqve been a performance regression, but instead, indexing was reworked from the ground up in a way that\(aqs usually \fIfaster\fP despite the added features. .SS 0.0.23 (Released June 28th, 2023) .sp These are some of the highlights of drgn 0.0.23. See the \fI\%GitHub release\fP for the full release notes, including more improvements and bug fixes. .SS Virtual Address Translation Helpers .sp This release added several Linux kernel helpers for translating virtual addresses. .sp \fI\%follow_phys()\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> task = find_task(prog, 115) >>> address = 0x7f7fe46a4270 >>> print(hex(follow_phys(task.mm, address))) 0x4090270 .EE .UNINDENT .UNINDENT .sp \fI\%follow_page()\fP translates a virtual address to the \fBstruct page *\fP that it maps to: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> follow_page(task.mm, address) *(struct page *)0xffffd20ac0102400 = { ... } .EE .UNINDENT .UNINDENT .sp \fI\%follow_pfn()\fP translates a virtual address to the page frame number (PFN) of the page that it maps to: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> follow_pfn(task.mm, address) (unsigned long)16528 .EE .UNINDENT .UNINDENT .sp These can be used to translate arbitrary kernel virtual addresses by passing \fBprog[\(dqinit_mm\(dq].address_of_()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> print(hex(follow_phys(prog[\(dqinit_mm\(dq].address_of_(), 0xffffffffc0483000))) 0x2e4b000 .EE .UNINDENT .UNINDENT .SS Vmalloc/Vmap Address Translation Helpers .sp \fI\%vmalloc_to_page()\fP is a special case of \fI\%follow_page()\fP for vmalloc and vmap addresses: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> vmalloc_to_page(prog, 0xffffffffc0477000) *(struct page *)0xffffc902400b8980 = { ... } .EE .UNINDENT .UNINDENT .sp Likewise, \fI\%vmalloc_to_pfn()\fP is a special case of \fI\%follow_pfn()\fP for vmalloc and vmap addresses: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> vmalloc_to_pfn(prog, 0xffffffffc0477000) (unsigned long)11814 .EE .UNINDENT .UNINDENT .SS \fBcontrib\fP Directory .sp Martin Liška, Boris Burkov, and Johannes Thumshirn added lots of new scripts to the \fBcontrib\fP directory: .INDENT 0.0 .IP \(bu 2 \fI\%btrfs_tree.py\fP: work\-in\-progress helpers for Btrfs B\-trees .IP \(bu 2 \fI\%btrfs_tree_mod_log.py\fP: simulator for the Btrfs tree modification log .IP \(bu 2 \fI\%dump_btrfs_bgs.py\fP: print block groups in a Btrfs filesystem .IP \(bu 2 \fI\%kcore_list.py\fP: print memory regions from \fB/proc/kcore\fP .IP \(bu 2 \fI\%kernel_sys.py\fP: print system information (similar to crash\(aqs \fBsys\fP command) .IP \(bu 2 \fI\%mount.py\fP: print a filesystem mount table .IP \(bu 2 \fI\%platform_drivers.py\fP: print registered \fI\%platform drivers\fP .IP \(bu 2 \fI\%vmmap.py\fP: print memory mappings in a process (similar to \fB/proc/$pid/maps\fP) .IP \(bu 2 \fI\%vmstat.py\fP: print information about kernel memory usage .UNINDENT .SS Embedding Interactive Mode .sp \fI\%drgn.cli.run_interactive()\fP runs drgn\(aqs interactive mode. It can be used to embed drgn in another application. For example, you could use it for a custom \fI\%drgn.Program\fP that the standard drgn CLI can\(aqt set up: .INDENT 0.0 .INDENT 3.5 .sp .EX 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) .EE .UNINDENT .UNINDENT .SS Full s390x Support .sp Sven Schnelle contributed s390x virtual address translation support. This is the state of architecture support in this release: .SS drgn 0.0.23 Architecture Support .TS center; |l|l|l|l|. _ T{ Architecture T} T{ Linux Kernel Modules T} T{ Stack Traces T} T{ Virtual Address Translation T} _ T{ x86\-64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ AArch64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ ppc64 T} T{ ✓ T} T{ ✓ T} T{ T} _ T{ s390x T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ i386 T} T{ ✓ T} T{ T} T{ T} _ T{ Arm T} T{ ✓ T} T{ T} T{ T} _ T{ RISC\-V T} T{ ✓ T} T{ T} T{ T} _ .TE .SS Linux 6.3 & 6.4 Support .sp 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. .sp On startup (fixed by Ido Schimmel): .INDENT 0.0 .INDENT 3.5 .sp .EX warning: could not get debugging information for: kernel modules (could not find loaded kernel modules: \(aqstruct module\(aq has no member \(aqcore_size\(aq) .EE .UNINDENT .UNINDENT .sp From \fI\%drgn.Program.stack_trace()\fP and \fI\%drgn.Thread.stack_trace()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX Exception: unknown ORC entry type 3 .EE .UNINDENT .UNINDENT .sp From \fI\%compound_order()\fP and \fI\%compound_nr()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX AttributeError: \(aqstruct page\(aq has no member \(aqcompound_order\(aq .EE .UNINDENT .UNINDENT .sp From \fI\%for_each_disk()\fP and \fI\%for_each_partition()\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX AttributeError: \(aqstruct class\(aq has no member \(aqp\(aq .EE .UNINDENT .UNINDENT .SS Python 3.12 Support .sp Python 3.12, currently in beta, changed an implementation detail that drgn depended on, which caused crashes like: .INDENT 0.0 .INDENT 3.5 .sp .EX Py_SIZE: Assertion \(gaob\->ob_type != &PyLong_Type\(aq failed. .EE .UNINDENT .UNINDENT .sp Stephen Brennan fixed this. .SS 0.0.22 (Released January 5th, 2023) .sp These are some of the highlights of drgn 0.0.22. See the \fI\%GitHub release\fP for the full release notes, including more improvements and bug fixes. .SS Listing Stack Frame Locals .sp \fI\%drgn.StackFrame.locals()\fP 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\(aqs going on in a function without needing to read the source code right away. .sp Let\(aqs use the \fB__schedule\fP stack frame from the following trace as an example: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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() [\(aqsched_mode\(aq, \(aqprev\(aq, \(aqnext\(aq, \(aqswitch_count\(aq, \(aqprev_state\(aq, \(aqrf\(aq, \(aqrq\(aq, \(aqcpu\(aq] >>> 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) rf (struct rq_flags){ .flags = (unsigned long)1, .cookie = (struct pin_cookie){}, .clock_update_flags = (unsigned int)4, } rq (struct rq *)0xffffa3b67fda9640 cpu (int) .EE .UNINDENT .UNINDENT .sp Compare this to the \fI\%kernel source code\fP\&. Note that some of the variables have been optimized out by the compiler. .sp This feature was contributed by Stephen Brennan. .SS Merged Slab Caches .sp The Linux kernel slab allocator merges \(dqsimilar\(dq slab caches as an optimization, which often causes confusion. \fI\%slab_cache_is_merged()\fP (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 \fI\%get_slab_cache_aliases()\fP, which provides a mapping from a slab cache name to the name of the cache it was merged into: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> get_slab_cache_aliases(prog) {\(aqio_kiocb\(aq: \(aqmaple_node\(aq, \(aqip_dst_cache\(aq: \(aquid_cache\(aq, \(aqaio_kiocb\(aq: \(aquid_cache\(aq, \(aqip_fib_alias\(aq: \(aqAcpi\-Parse\(aq, \(aqpid_namespace\(aq: \(aqpid\(aq, \(aqiommu_iova\(aq: \(aqvmap_area\(aq, \(aqfasync_cache\(aq: \(aqftrace_event_field\(aq, \(aqdnotify_mark\(aq: \(aqAcpi\-State\(aq, \(aqtcp_bind2_bucket\(aq: \(aqvmap_area\(aq, \(aqnsproxy\(aq: \(aqAcpi\-Operand\(aq, \(aqshared_policy_node\(aq: \(aqftrace_event_field\(aq, \(aqeventpoll_epi\(aq: \(aqpid\(aq, \(aqfib6_nodes\(aq: \(aqvmap_area\(aq, \(aqAcpi\-Namespace\(aq: \(aqftrace_event_field\(aq, \(aqposix_timers_cache\(aq: \(aqmaple_node\(aq, \(aqinotify_inode_mark\(aq: \(aqAcpi\-State\(aq, \(aqkernfs_iattrs_cache\(aq: \(aqtrace_event_file\(aq, \(aqfs_cache\(aq: \(aqvmap_area\(aq, \(aqUDP\-Lite\(aq: \(aqUDP\(aq, \(aqanon_vma_chain\(aq: \(aqvmap_area\(aq, \(aqip6_dst_cache\(aq: \(aqmaple_node\(aq, \(aqeventpoll_pwq\(aq: \(aqvmap_area\(aq, \(aqinet_peer_cache\(aq: \(aquid_cache\(aq, \(aqfsnotify_mark_connector\(aq: \(aqnuma_policy\(aq, \(aqip_fib_trie\(aq: \(aqftrace_event_field\(aq, \(aqfilp\(aq: \(aqmaple_node\(aq, \(aqdnotify_struct\(aq: \(aqnuma_policy\(aq, \(aqUDPLITEv6\(aq: \(aqUDPv6\(aq, \(aqbiovec\-16\(aq: \(aqmaple_node\(aq, \(aqPING\(aq: \(aqsignal_cache\(aq, \(aqep_head\(aq: \(aqblkdev_ioc\(aq, \(aqtcp_bind_bucket\(aq: \(aqpid\(aq, \(aqAcpi\-ParseExt\(aq: \(aqAcpi\-State\(aq, \(aqcred_jar\(aq: \(aqpid\(aq, \(aqovl_aio_req\(aq: \(aqpid\(aq, \(aqpool_workqueue\(aq: \(aqmaple_node\(aq, \(aqsigqueue\(aq: \(aqAcpi\-State\(aq, \(aqfile_lock_ctx\(aq: \(aqAcpi\-Parse\(aq, \(aqkernfs_node_cache\(aq: \(aqpid\(aq} .EE .UNINDENT .UNINDENT .sp This means that if you\(aqre looking for \fBio_kiocb\fP allocations, you actually need to look at the \fBmaple_node\fP slab cache. Conversely, if you\(aqre looking at the \fBmaple_node\fP slab cache, you need to be aware that it also contains allocations from all of the following slab caches: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> [merged for merged, canonical in get_slab_cache_aliases(prog).items() if canonical == \(dqmaple_node\(dq] [\(aqio_kiocb\(aq, \(aqposix_timers_cache\(aq, \(aqip6_dst_cache\(aq, \(aqfilp\(aq, \(aqbiovec\-16\(aq, \(aqpool_workqueue\(aq] .EE .UNINDENT .UNINDENT .SS Slab Address Information .sp This release extended \fI\%identify_address()\fP to show additional information about slab allocations: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> ptr1 = 0xffffa3b601178438 >>> ptr2 = 0xffffa3b601176cc0 >>> identify_address(prog, ptr1) \(aqslab object: task_struct+0x438\(aq >>> identify_address(prog, ptr2) \(aqfree slab object: mm_struct+0x0\(aq .EE .UNINDENT .UNINDENT .sp This means that \fBptr1\fP is an address 0x438 bytes into an allocated object from the \fBtask_struct\fP slab cache, and \fBptr2\fP is a free object from the \fBmm_struct\fP slab cache. .sp \fI\%slab_object_info()\fP provides the same information programmatically: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> slab_object_info(prog, ptr1) SlabObjectInfo(slab_cache=Object(prog, \(aqstruct kmem_cache *\(aq, value=0xffffa3b601045500), slab=Object(prog, \(aqstruct slab *\(aq, value=0xffffe80840045e00), address=0xffffa3b601178000, allocated=True) >>> slab_object_info(prog, ptr2) SlabObjectInfo(slab_cache=Object(prog, \(aqstruct kmem_cache *\(aq, value=0xffffa3b601045900), slab=Object(prog, \(aqstruct slab *\(aq, value=0xffffe80840045c00), address=0xffffa3b601176cc0, allocated=False) .EE .UNINDENT .UNINDENT .SS Annotated Stack Memory .sp \fI\%print_annotated_stack()\fP prints a stack trace and all of its memory, identifying anything that it can: .INDENT 0.0 .INDENT 3.5 .sp .EX >>> 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] .EE .UNINDENT .UNINDENT .sp Like \fI\%drgn.StackFrame.locals()\fP, this provides a nice overview of everything happening in a function, which might include useful hints. Keep in mind that it may identify \(dqstale\(dq addresses for anything that a function hasn\(aqt reinitialized yet, and as always, be careful of slab cache merging. .sp This was inspired by the crash \fBbt \-FF\fP command. It was contributed by Nhat Pham. .SS XArray Helpers .sp XArrays were introduced in Linux 4.20 as a replacement for radix trees. drgn\(aqs radix tree helpers also support XArrays in some cases, but this is awkward, not obvious, and doesn\(aqt work for new, XArray\-only functionality. .sp This release added dedicated XArray helpers like \fI\%xa_load()\fP and \fI\%xa_for_each()\fP\&. .SS s390x Support .sp Sven Schnelle contributed s390x support for Linux kernel modules and stack traces. This is the state of architecture support in this release: .SS drgn 0.0.22 Architecture Support .TS center; |l|l|l|l|. _ T{ Architecture T} T{ Linux Kernel Modules T} T{ Stack Traces T} T{ Virtual Address Translation T} _ T{ x86\-64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ AArch64 T} T{ ✓ T} T{ ✓ T} T{ ✓ T} _ T{ ppc64 T} T{ ✓ T} T{ ✓ T} T{ T} _ T{ s390x T} T{ ✓ T} T{ ✓ T} T{ T} _ T{ i386 T} T{ ✓ T} T{ T} T{ T} _ T{ Arm T} T{ ✓ T} T{ T} T{ T} _ T{ RISC\-V T} T{ ✓ T} T{ T} T{ T} _ .TE .SS Relicensing to LGPL .sp 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, \fI\%Object Introspection\fP, a userspace memory profiler recently open sourced by Meta, uses drgn to parse debugging information. .SH AUTHOR Omar Sandoval .SH COPYRIGHT Omar Sandoval .\" Generated by docutils manpage writer. .