Skip to content

DLPX-94248 address drgn merge conflict with upstream #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 172 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
172 commits
Select commit Hold shift + click to select a range
33f1331
libdrgn: enable -Wformat-security
osandov Dec 18, 2024
c39cc68
libdrgn: elf_notes: add helper function for looking up notes
osandov Dec 14, 2024
c528375
libdrgn: add CRC-32 implementation
osandov Dec 17, 2024
75f5e88
libdrgn: add hexadecimal encoding/decoding functions
osandov Dec 17, 2024
8e12b67
libdrgn: add functions for deserializing 64- or 32-bit structures
osandov Dec 17, 2024
59b23c8
libdrgn: binary_search_tree: add delete_entry
osandov Dec 17, 2024
7781e49
libdrgn: linux_kernel: parse build ID in VMCOREINFO
osandov Dec 17, 2024
eb40260
libdrgn: linux_kernel: move depmod index code
osandov Dec 17, 2024
e215bd6
libdrgn: debug_info: add debuginfod client scaffolding
osandov Dec 17, 2024
541d5e7
libdrgn: add API for choosing file to write progress bars to
osandov Dec 17, 2024
4e83130
Introduce module and debug info finder APIs
osandov Dec 17, 2024
3ce0fee
tests: don't clobber file in use by libelf
osandov Dec 19, 2024
e6044c7
libdrgn: don't bother getting program language to initialize object
osandov Dec 19, 2024
5ee2dfd
tests: drop leftover debugging print
osandov Dec 19, 2024
89656d4
Update Ubuntu instructions
michel-slm Dec 19, 2024
885a320
libdrgn: kdump: simplify getting the PRSTATUS attributes
ptesarik Dec 2, 2024
4e06cfd
libdrgn: kdump: prepare for incompatible changes in libkdumpfile-0.5.5
ptesarik Dec 3, 2024
a1869f9
Make StackFrame.name fall back to symbol/PC and add StackFrame.functi…
osandov Dec 19, 2024
e7ac089
docs: use envvar directive for environment variables
osandov Jan 14, 2025
970b9a0
libdrgn/python: unexport set_drgn_error()
osandov Jan 13, 2025
6ff98f0
libdrgn: stack_trace: make bad call unwinding an architecture callback
osandov Jan 21, 2025
5855221
libdrgn: register_state: add drgn_register_state_unset_has_register()
osandov Jan 21, 2025
4a3ae32
libdrgn: aarch64: implement bad call unwinding
osandov Jan 21, 2025
cc14bc1
contrib/stack_trace_call_fault.py: support AArch64
osandov Jan 21, 2025
b1ce3f2
libdrgn: stack_trace: give hint when stack_trace(0) fails
osandov Jan 21, 2025
64d82dd
libdrgn/python: remove dead misspelled ifdef block
osandov Jan 21, 2025
4738ddf
libdrgn/python: fix segfault on del prog.language and more
osandov Jan 23, 2025
191a4d5
libdrgn: add VECTOR and HASH_TABLE scope guards
osandov Jan 27, 2025
45c4a22
libdrgn: debug_info: match vmlinux by version if build ID is not avai…
osandov Jan 28, 2025
61b76ca
libdrgn: hash_table: add hash_table_for_each()
osandov Jan 31, 2025
09aa580
libdrgn/python: factor path sequence argument parsing out of Program_…
osandov Jan 23, 2025
bb00871
Replace debug_info_path with debug_info_options
osandov Jan 23, 2025
2cd7bc6
Add Program.find_standard_debug_info()
osandov Jan 24, 2025
5e7bec4
Add debug info options for disabling search methods
osandov Jan 24, 2025
f9ab678
Add a debug info option for kernel directories
osandov Jan 25, 2025
94b6d39
libdrgn: debug_info: clean up drgn_module_standard_files_state
osandov Jan 27, 2025
7dc474d
Support searching for kernel modules without depmod metadata
osandov Jan 31, 2025
4dca429
Build manylinux wheels with debuginfod support
osandov Jan 31, 2025
20e8759
libdrgn: linux_kernel: handle module section/note changes in Linux 6.14
osandov Feb 3, 2025
3d49360
libdrgn: combine libdrgn and _drgn Python extension into one .so
osandov Jan 13, 2025
999e2b1
libdrgn: always make drgn_program available to Python
osandov Jan 13, 2025
ce436a2
libdrgn: replace blocking callbacks with hard-coded functions
osandov Jan 13, 2025
adf6472
Add plugin system
osandov Jan 14, 2025
70391bc
Add 6.14 to supported kernels
osandov Feb 3, 2025
bf69b7b
docs: add a hands-on tutorial for a blk-rq-qos crash
osandov Feb 12, 2025
fa3695e
docs: add video to blk-rq-qos crash tutorial
osandov Feb 12, 2025
1c6307b
README: exclude unsupported repositories from Repology badge
osandov Feb 12, 2025
9f56b1e
libdrgn: dwarf_info: add bias to DW_OP_addr in the middle of an expre…
osandov Feb 13, 2025
972259a
drgn.helpers.experimental.kmodify: apply conversions to literal argum…
osandov Feb 17, 2025
96ce55e
drgn.helpers.experimental.kmodify: sign-extend <32-bit arguments
osandov Feb 17, 2025
a099064
libdrgn: dwarf_info: use uintptr_t for DIE addresses in DWARF index
osandov Feb 20, 2025
b999e7e
tests: skip slow test_mtree_load_three_levels* tests under emulation
osandov Mar 5, 2025
9de433f
libdrgn: dwarf_info: fix DWARF index error handling
osandov Mar 6, 2025
1ade28d
tests: don't run TC tests with old pyroute2
osandov Mar 6, 2025
792458d
tests: remove leftover debugging code in symbols test
osandov Mar 6, 2025
03e90d5
orc_info: don't use ELF_Data when processing orc header
brenns10 Dec 13, 2024
242f0c3
libdrgn: python: add Module_prog
brenns10 Jan 2, 2025
984ab04
module: add object
brenns10 Dec 13, 2024
3ab0f6a
orc_info: enable the use of built-in ORC
brenns10 Dec 14, 2024
6ff3287
orc_info: store biased pc_base
brenns10 Dec 16, 2024
c15fc07
orc_info: use a constant for size of the ORC version header
brenns10 Feb 13, 2025
a842645
tests: linux_kernel: test built-in ORC unwinding
brenns10 Dec 19, 2024
ff8be67
vmtest.kbuild: add patch to work around missing build ID on aarch64:5…
osandov Mar 7, 2025
af535aa
Revert "vmtest.kbuild: add patch to fix 9p slab cache naming on Linux…
osandov Mar 7, 2025
335e4b8
dco-check: enforce that sign-off matches commit author
osandov Mar 7, 2025
bdc3212
Fix exception handling in for_each_child_dentry
septatrix Mar 7, 2025
aeaa16b
vmtest: use cortex-a76 CPU for AArch64 emulation
osandov Mar 9, 2025
109eee6
tests: add test for unwinding through IRQ handler
osandov Mar 10, 2025
dd57978
libdrgn: rename drgn_object_slice() to drgn_object_fragment()
osandov Mar 10, 2025
5d70f34
vmtest.__main__: exit with non-zero status on failure
osandov Mar 10, 2025
09a1bb6
docs: suggest usage of operator.index()/IntegerLike instead of Object…
osandov Mar 10, 2025
c64f74f
docs: update required Sphinx version to 7.3.7
osandov Mar 10, 2025
27deab5
tests: handle PrimitiveType in assertIdentical()
osandov Mar 11, 2025
39cd968
tests: dwarfwriter: rename compile_dwarf() to create_dwarf_file()
osandov Mar 11, 2025
591d707
tests: don't add DWARF to ELF symbol test files
osandov Mar 11, 2025
e2fd91d
tests: dwarfwriter: remove dwarf_sections()
osandov Mar 11, 2025
d171a1d
tests: move .gnu_debug{,alt}link encoding to elfwriter
osandov Mar 11, 2025
4edc604
tests: test all DWARF reference forms
osandov Mar 11, 2025
fb391b8
tests: dwarfwriter: add optional label for top-level DIEs
osandov Mar 11, 2025
4797153
tests: dwarfwriter: add compile_dwarf() function that returns labels
osandov Mar 12, 2025
45628d0
tests: test invalid DW_AT_sibling handling
osandov Mar 13, 2025
e2b60e4
Fix task_cpu() and stack traces for CentOS/RHEL 9 kernels
osandov Mar 14, 2025
72b4ecf
libdrgn: dwarf_info: resolve address of inline member functions
osandov Mar 17, 2025
61088fb
libdrgn: debug_info: check for supplementary debug file in drgn_modul…
osandov Mar 17, 2025
61e2418
libdrgn: dwarf_info: update DWARF index in one OpenMP parallel region
osandov Mar 12, 2025
f8c0a79
libdrgn: dwarf_info: read all abbreviation tables before indexing CUs
osandov Mar 12, 2025
5efb0de
libdrgn: dwarf_info: create separate CU lookup table
osandov Mar 12, 2025
8d838e1
libdrgn: dwarf_info: don't index partial units
osandov Mar 12, 2025
a22c752
libdrgn: dwarf_info: read units of supplementary debug files
osandov Mar 17, 2025
6c5ec7a
libdrgn: dwarf_info: bounds check specifications while indexing
osandov Mar 12, 2025
ef5bda4
libdrgn: dwarf_info: parse specifications in second indexing pass
osandov Mar 12, 2025
b534078
libdrgn: dwarf_info: move drgn_dwarf_index_find_cu() code
osandov Mar 17, 2025
790f79e
libdrgn: dwarf_info: use //-style comments in enum drgn_dwarf_index_a…
osandov Mar 17, 2025
83d40a5
libdrgn: dwarf_info: index imported units
osandov Mar 17, 2025
a46df41
Use shell builtin instead of which
septatrix Mar 14, 2025
06382a6
drgn.helpers.linux: add kthread helpers
osandov Mar 17, 2025
b9deae1
libdrgn/python: modernize drgn_error_from_python()
brenns10 Mar 14, 2025
00c4f66
libdrgn: python: pass fault errors through
brenns10 Mar 14, 2025
ca3f004
tests: test FaultError translation
osandov Mar 17, 2025
9fab646
libdrgn: stack_trace: allow unwinding anything with a pt_regs
brenns10 Feb 5, 2025
0625a27
libdrgn: dwarf_info: skip DW_CFA_GNU_args_size
osandov Mar 17, 2025
0e635df
Handle truncated pr_fname
brenns10 Mar 17, 2025
53e57ea
libdrgn: debug_info: don't set extra module bias if address range is …
osandov Mar 24, 2025
139078e
docs: document details of bias calculation
osandov Mar 24, 2025
284bd5f
docs: emphasize that ExtraModule name and ID are both arbitrary
osandov Mar 24, 2025
4a6a9f3
cli: allow enabling/disabling debug info finders with --{try,no}-symb…
osandov Mar 25, 2025
3736aba
cli: clarify locations -> directories in help strings
osandov Mar 25, 2025
1b05b8c
cli: extract out default_globals()
brenns10 Mar 11, 2025
150ee76
cli: add -e option to exec() code directly
brenns10 Mar 11, 2025
9dea027
tests: add simple CLI smoke test
brenns10 Mar 25, 2025
c521092
cli: fix 'staticmethod' object is not callable for Python < 3.10
brenns10 Mar 25, 2025
4520c3d
cli: set default program for -e
osandov Mar 25, 2025
bafb43f
cli: rename args.script to args.args
osandov Mar 25, 2025
7f63f1a
cli: handle !isatty(stdin)
osandov Mar 25, 2025
f89e3fa
tests: expand CLI tests
osandov Mar 25, 2025
64dd5c8
Add Program.create_loaded_modules()
osandov Mar 25, 2025
21cbafa
libdrgn: debug_info: improve load_debug_info() warnings for kernel
osandov Mar 26, 2025
50bcb65
libdrgn: debug_info: simplify missing debug info error return in load…
osandov Mar 26, 2025
12b789e
cli: log missing main debug info as critical
osandov Mar 26, 2025
9033fb3
drgn.helpers.experimental.kmodify: add wake_up_process() example to c…
osandov Mar 27, 2025
c8c7c17
README: clean up and update installation instructions for libdebuginfod
osandov Apr 1, 2025
75d3ab6
libdrgn: linux_kernel: disable debuginfod except on Fedora
osandov Apr 2, 2025
d03bbe5
cli: include debuginfod support status in version banner
osandov Apr 2, 2025
38f40b3
CI: install pyroute2 < 0.9.1 for Python < 3.9.
osandov Apr 3, 2025
c782893
Add absence reason to absent objects
osandov Apr 7, 2025
2d25e22
Add OPTIMIZED_OUT absence reason and use it for DWARF
osandov Apr 7, 2025
2027d0f
Add NOT_IMPLEMENTED absence reason and use it for DWARF
osandov Apr 7, 2025
644a47b
drgn.helpers.linux.fs: handle DCACHE_MOUNTED value change in 6.15
osandov Apr 8, 2025
36d3065
drgn.helpers.linux.kernfs: add kernfs_parent() and handle 6.15
osandov Apr 8, 2025
70dcba2
drgn.helpers.linux.kernfs: add kernfs_root() helper
osandov Apr 8, 2025
cfe3823
Add 6.15 to supported kernels
osandov Apr 8, 2025
9b7297d
vmtest.config: enable CONFIG_KPROBES for upcoming kmodify breakpoints
osandov Apr 8, 2025
32d29a1
libdrgn: linux_kernel: don't use drgn_module_find_or_create()
osandov Apr 4, 2025
d48a5bb
libdrgn: replace drgn_module_find() with kind-specific find functions
osandov Apr 5, 2025
b9ad36e
libdrgn: hash_table: add delete_entry
osandov Apr 8, 2025
5ce2116
libdrgn: get rid of struct drgn_module_key
osandov Apr 8, 2025
dcf392a
libdrgn: debug_info: index modules by name
osandov Apr 9, 2025
21decd3
Add module lookups by name
osandov Apr 9, 2025
b72fc70
docs: fix formatting of create_loaded_modules() docstring
osandov Apr 9, 2025
4f518e4
Drop "new" return from prog.*_module(create=True)
osandov Apr 9, 2025
d6576fb
docs: split up table of contents into sections
osandov Apr 11, 2025
baa9a14
docs: add man page
osandov Apr 11, 2025
de5d4cc
docs: update Advanced Usage
osandov Apr 11, 2025
63d9fe3
docs: update User Guide
osandov Apr 11, 2025
dee6d4d
Fix the URLs of Oracle Linux documentation
brenns10 Apr 11, 2025
d04dee9
libdrgn: Makefile: add plugins.h to SOURCES
osandov Apr 11, 2025
22ac3f3
tests: don't shell out for CLI tests
osandov Apr 11, 2025
26d6ef8
tests: fix socket ResourceWarning in debuginfod tests
osandov Apr 11, 2025
82bfff4
libdrgn: x86_64: fix restoring rbp for ORC_TYPE_REGS
osandov Apr 11, 2025
4c90e74
libdrgn: optionally split up libdrgn and _drgn Python extension .so f…
osandov Apr 14, 2025
a49bb11
Update libkdumpfile in manylinux wheels to 0.5.5
osandov Apr 14, 2025
4b31a32
vmtest.kbuild: add patch to work around ppc64 build failure
osandov Apr 15, 2025
78ef790
CI: update to Ubuntu 22.04, drop Python 3.6 and 3.7
osandov Apr 15, 2025
235944e
libdrgn: linux_kernel: don't log every module section address
osandov Apr 15, 2025
97a3c5a
cli: document --no-default-{debug,kernel}-directories behavior with p…
osandov Apr 15, 2025
ef3f73b
docs: improve debugging information finder examples
osandov Apr 15, 2025
4834a95
drgn.helpers.linux.mm: fix in_direct_map() docstring
osandov Apr 16, 2025
a938677
docs: revamp Getting Debugging Symbols page
osandov Apr 16, 2025
8449bd7
setup.py: depend on setuptools (for pkg_resources) on Python < 3.8
osandov Apr 16, 2025
0824ffe
docs: add 0.0.31 release highlights
osandov Apr 16, 2025
8209a14
drgn 0.0.31
osandov Apr 16, 2025
3977bdc
tests: fix deserialize_struct64 tests on i386
osandov Apr 19, 2025
20b0ff7
tests: fix issues with CLI test error handling
osandov Apr 25, 2025
7237106
cli: don't enter interactive mode for empty -e argument
osandov Apr 25, 2025
89260b1
vmtest.rootfsbuild: install check
osandov Apr 25, 2025
7d3af16
drgn.helpers.linux.fs: skip cursors in for_each_mount()
brenns10 May 6, 2025
dfe56c2
helpers: add is_pp_page helper
dtatulea Mar 12, 2025
f8bedb9
contrib/pp_leak: add page_pool leak debug scripts
dtatulea Mar 28, 2025
67022e6
libdrgn: python: fix reference leak for held types
brenns10 May 10, 2025
3ccbf9f
libdrgn: python: check correct pointer in StackTrace_dealloc()
osandov May 12, 2025
479c283
libdrgn: python: add missing garbage collection support
osandov May 12, 2025
441b103
Merge remote-tracking branch 'origin/upstreams/develop' into develop
prakashsurya May 14, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 8 additions & 13 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,12 @@ concurrency:

jobs:
test:
# We're stuck on Ubuntu 20.04 as long as we want to keep testing on Python
# 3.6 due to actions/setup-python#544.
runs-on: ubuntu-20.04
runs-on: ubuntu-22.04
strategy:
matrix:
python-version: ${{ (github.event_name == 'push' || inputs.test_all_python_versions)
&& fromJSON('["3.13", "3.12", "3.11", "3.10", "3.9", "3.8", "3.7", "3.6"]')
|| fromJSON('["3.12", "3.6"]')}}
&& fromJSON('["3.13", "3.12", "3.11", "3.10", "3.9", "3.8"]')
|| fromJSON('["3.13", "3.8"]')}}
cc: [gcc, clang]
fail-fast: false
env:
Expand All @@ -55,21 +53,18 @@ jobs:
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- name: Check Python version for pre-commit
# Only run pre-commit / mypy on upstream supported Python versions
run: |
if [[ "${{ matrix.python-version }}" =~ ^3\.([89]|[0-9][0-9])$ ]]; then
echo USE_PRE_COMMIT=1 >> $GITHUB_ENV
fi
- name: Install dependencies
run: |
sudo apt-get update -y
sudo apt-get install -y btrfs-progs check dwarves libelf-dev libdw-dev qemu-kvm zstd ${{ matrix.cc == 'clang' && 'libomp-$(clang --version | sed -rn "s/.*clang version ([0-9]+).*/\\1/p")-dev' || '' }}
pip install pyroute2 setuptools ${USE_PRE_COMMIT/1/pre-commit}
# pyroute2 0.9.1 dropped support for Python < 3.9.
if [[ "${{ matrix.python-version }}" =~ ^3\.[678]$ ]]; then
pyroute2_version="<0.9.1"
fi
pip install "pyroute2$pyroute2_version" setuptools pre-commit
- name: Generate version.py
run: python setup.py --version
- name: Check with mypy
if: ${{ env.USE_PRE_COMMIT == '1' }}
run: pre-commit run --all-files mypy
- name: Build and test with ${{ matrix.cc }}
run: CONFIGURE_FLAGS="--enable-compiler-warnings=error" python setup.py test -K ${{ inputs.test_all_kernel_flavors && '-F' || '' }}
Expand Down
24 changes: 16 additions & 8 deletions .github/workflows/dco-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,22 @@ jobs:
git init
git fetch --filter=blob:none "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" "$GITHUB_BASE_REF" "$GITHUB_REF"
- name: Check for DCO sign-offs
shell: bash
run: |
no_sign_off="$(git log --no-merges --grep=Signed-off-by --invert-grep "FETCH_HEAD..$GITHUB_SHA")"
if [ -z "$no_sign_off" ]; then
status=0
while read -r commit; do
author="$(git show --no-patch --pretty='format:%an <%ae>' "$commit")"
if ! git show --no-patch --pretty='format:%(trailers:key=Signed-off-by,valueonly)' "$commit" | grep -Fxq "$author"; then
if [ $status -eq 0 ]; then
echo "The following commits are missing a Developer Certificate of Origin sign-off;"
echo "see https://github.com/osandov/drgn/blob/main/CONTRIBUTING.rst#signing-off"
echo
fi
status=1
git show --no-patch "$commit"
fi
done < <(git rev-list --no-merges "FETCH_HEAD..$GITHUB_SHA")
if [ $status -eq 0 ]; then
echo "All commits have a Developer Certificate of Origin sign-off"
else
echo "The following commits are missing a Developer Certificate of Origin sign-off;"
echo "see https://github.com/osandov/drgn/blob/main/CONTRIBUTING.rst#signing-off"
echo
echo "$no_sign_off"
exit 1
fi
exit $status
4 changes: 1 addition & 3 deletions .github/workflows/vmtest-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,7 @@ jobs:
arch: [x86_64, aarch64, ppc64, s390x, arm]
fail-fast: false
max-parallel: 5
# Build on 20.04 so that we don't get host binaries (e.g., objtool) that
# depend on libraries too new for other distros.
runs-on: ubuntu-20.04
runs-on: ubuntu-22.04
permissions:
contents: write
env:
Expand Down
2 changes: 2 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ build:
os: ubuntu-22.04
tools:
python: "3"
apt_packages:
- graphviz
sphinx:
configuration: docs/conf.py
python:
Expand Down
65 changes: 31 additions & 34 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -66,17 +66,17 @@ Package Manager

drgn can be installed using the package manager on some Linux distributions.

.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg
.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg?exclude_unsupported=1
:target: https://repology.org/project/drgn/versions
:alt: Packaging Status

* Fedora >= 32
* Fedora, RHEL/CentOS Stream >= 9

.. code-block:: console

$ sudo dnf install drgn

* RHEL/CentOS >= 8
* RHEL/CentOS < 9

`Enable EPEL <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_. Then:

Expand All @@ -86,32 +86,35 @@ drgn can be installed using the package manager on some Linux distributions.

* Oracle Linux >= 8

Enable the ``ol8_addons`` or ``ol9_addons`` repository and install drgn:
Enable the ``ol8_addons`` or ``ol9_addons`` repository. Then:

.. code-block:: console

$ sudo dnf config-manager --enable ol8_addons # OR: ol9_addons
$ sudo dnf install drgn

Drgn is also available for Python versions in application streams. For
drgn is also available for Python versions in application streams. For
example, use ``dnf install python3.12-drgn`` to install drgn for Python 3.12.
See the documentation for drgn in `Oracle Linux 9
<https://docs.oracle.com/en/operating-systems/oracle-linux/9/drgn/how_to_install_drgn.html>`_
and `Oracle Linux 8
<https://docs.oracle.com/en/operating-systems/oracle-linux/8/drgn/how_to_install_drgn.html>`_
for more information.

* Arch Linux
* Debian >= 12 (Bookworm)/Ubuntu >= 24.04 (Noble Numbat)

.. code-block:: console

$ sudo pacman -S drgn
$ sudo apt install python3-drgn

* Debian >= 12 (Bookworm)
To get the latest version on Ubuntu, enable the `michel-slm/kernel-utils PPA
<https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>`_ first.

* Arch Linux

.. code-block:: console

$ sudo apt install python3-drgn
$ sudo pacman -S drgn

* Gentoo

Expand All @@ -125,15 +128,6 @@ drgn can be installed using the package manager on some Linux distributions.

$ sudo zypper install python3-drgn

* Ubuntu

Enable the `michel-slm/kernel-utils PPA <https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>`_.
Then:

.. code-block:: console

$ sudo apt install python3-drgn

pip
^^^

Expand All @@ -156,19 +150,21 @@ 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.

.. _installation-from-source:

From Source
^^^^^^^^^^^

To get the development version of drgn, you will need to build it from source.
First, install dependencies:

* Fedora
* Fedora, RHEL/CentOS Stream >= 9

.. code-block:: console

$ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
$ sudo dnf install autoconf automake check-devel elfutils-debuginfod-client-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

* RHEL/CentOS/Oracle Linux
* RHEL/CentOS < 9, Oracle Linux

.. code-block:: console

Expand All @@ -191,10 +187,11 @@ First, install dependencies:

.. code-block:: console

$ sudo apt install autoconf automake check gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
$ sudo apt install autoconf automake check gcc git libdebuginfod-dev libkdumpfile-dev liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev

Optionally, install libkdumpfile from source if you want support for the
makedumpfile format.
On Debian <= 11 (Bullseye) and Ubuntu <= 22.04 (Jammy Jellyfish),
``libkdumpfile-dev`` is not available, so you must install libkdumpfile from
source if you want support for the makedumpfile format.

* Arch Linux

Expand All @@ -212,7 +209,7 @@ First, install dependencies:

.. code-block:: console

$ sudo zypper install autoconf automake check-devel gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
$ sudo zypper install autoconf automake check-devel gcc git libdebuginfod-devel libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools

Then, run:

Expand All @@ -233,20 +230,20 @@ Quick Start

.. start-quick-start

drgn debugs the running kernel by default; run ``sudo drgn``. To debug a
running program, run ``sudo drgn -p $PID``. To debug a core dump (either a
kernel vmcore or a userspace core dump), run ``drgn -c $PATH``. Make sure to
`install debugging symbols
drgn debugs the running kernel by default; simply run ``drgn``. To debug a
running program, run ``drgn -p $PID``. To debug a core dump (either a kernel
vmcore or a userspace core dump), run ``drgn -c $PATH``. Make sure to `install
debugging symbols
<https://drgn.readthedocs.io/en/latest/getting_debugging_symbols.html>`_ for
whatever you are debugging.

Then, you can access variables in the program with ``prog['name']`` and access
Then, you can access variables in the program with ``prog["name"]`` and access
structure members with ``.``:

.. code-block:: pycon

$ sudo drgn
>>> prog['init_task'].comm
$ drgn
>>> prog["init_task"].comm
(char [16])"swapper/0"

You can use various predefined helpers:
Expand All @@ -260,14 +257,14 @@ You can use various predefined helpers:
[b'findmnt', b'-p']

You can get stack traces with ``stack_trace()`` and access parameters or local
variables with ``trace['name']``:
variables with ``trace["name"]``:

.. code-block:: pycon

>>> trace = stack_trace(task)
>>> trace[5]
#5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
>>> poll_list = trace[5]['list']
>>> poll_list = trace[5]["list"]
>>> file = fget(task, poll_list.entries[0].fd)
>>> d_path(file.f_path.address_of_())
b'/proc/115/mountinfo'
Expand Down
Loading
Loading