mirror of
https://github.com/JakeHillion/drgn.git
synced 2024-12-23 01:33:06 +00:00
2b325b9262
We use /proc/modules and /sys/module to find loaded kernel modules for the running kernel instead of walking the module list in the core dump as an optimization. To make it easier to test the core dump path, add an environment variable to disable the optimization. Signed-off-by: Omar Sandoval <osandov@osandov.com>
104 lines
3.5 KiB
ReStructuredText
104 lines
3.5 KiB
ReStructuredText
Advanced Usage
|
|
==============
|
|
|
|
.. highlight:: pycon
|
|
|
|
The :doc:`user_guide` covers basic usage of drgn, but drgn also supports more
|
|
advanced use cases which are covered here.
|
|
|
|
Loading Debugging Symbols
|
|
-------------------------
|
|
|
|
drgn will automatically load debugging information based on the debugged
|
|
program (e.g., from loaded kernel modules or loaded shared libraries).
|
|
:meth:`drgn.Program.load_debug_info()` can be used to load additional debugging
|
|
information::
|
|
|
|
>>> prog.load_debug_info(['./libfoo.so', '/usr/lib/libbar.so'])
|
|
|
|
Library
|
|
-------
|
|
|
|
In addition to the CLI, drgn is also available as a library.
|
|
:func:`drgn.program_from_core_dump()`, :func:`drgn.program_from_kernel()`, and
|
|
:func:`drgn.program_from_pid()` correspond to the ``-c``, ``-k``, and ``-p``
|
|
command line options, respectively; they return a :class:`drgn.Program` that
|
|
can be used just like the one initialized by the CLI::
|
|
|
|
>>> import drgn
|
|
>>> prog = drgn.program_from_kernel()
|
|
|
|
C Library
|
|
---------
|
|
|
|
The core functionality of drgn is implemented in C and is available as a C
|
|
library, ``libdrgn``. See |drgn.h|_.
|
|
|
|
.. |drgn.h| replace:: ``drgn.h``
|
|
.. _drgn.h: https://github.com/osandov/drgn/blob/master/libdrgn/drgn.h.in
|
|
|
|
Full documentation can be generated by running ``doxygen`` in the ``libdrgn``
|
|
directory of the source code. Note that the API and ABI are not yet stable.
|
|
|
|
Custom Programs
|
|
---------------
|
|
|
|
The main components of a :class:`drgn.Program` are the program memory, types,
|
|
and symbols. The CLI and equivalent library interfaces automatically determine
|
|
these. However, it is also possible to create a "blank" ``Program`` and plug in
|
|
the main components.
|
|
|
|
:meth:`drgn.Program.add_memory_segment()` defines a range of memory and how to
|
|
read that memory. The following example uses a Btrfs filesystem image as the
|
|
program "memory":
|
|
|
|
.. code-block:: python3
|
|
|
|
import drgn
|
|
import os
|
|
import sys
|
|
|
|
|
|
def btrfs_debugger(dev):
|
|
file = open(dev, 'rb')
|
|
size = file.seek(0, 2)
|
|
|
|
def read_file(address, count, physical, offset):
|
|
file.seek(offset)
|
|
return file.read(count)
|
|
|
|
platform = drgn.Platform(drgn.Architecture.UNKNOWN,
|
|
drgn.PlatformFlags.IS_LITTLE_ENDIAN)
|
|
prog = drgn.Program(platform)
|
|
prog.add_memory_segment(0, size, read_file)
|
|
prog.load_debug_info([f'/lib/modules/{os.uname().release}/kernel/fs/btrfs/btrfs.ko'])
|
|
return prog
|
|
|
|
|
|
prog = btrfs_debugger(sys.argv[1] if len(sys.argv) >= 2 else '/dev/sda')
|
|
print(drgn.Object(prog, 'struct btrfs_super_block', address=65536))
|
|
|
|
:meth:`drgn.Program.add_type_finder()` and
|
|
:meth:`drgn.Program.add_symbol_finder()` are the equivalent methods for
|
|
plugging in types and symbols.
|
|
|
|
Environment Variables
|
|
---------------------
|
|
|
|
Some of drgn's behavior can be modified through environment variables:
|
|
|
|
``DRGN_MAX_DEBUG_INFO_ERRORS``
|
|
The maximum number of individual errors to report in a
|
|
:exc:`drgn.MissingDebugInfoError`. Any additional errors are truncated. The
|
|
default is 5; -1 is unlimited.
|
|
|
|
``DRGN_USE_LIBKDUMPFILE_FOR_ELF``
|
|
Whether drgn should use libkdumpfile for ELF vmcores (0 or 1). The default
|
|
is 0. This functionality will be removed in the future.
|
|
|
|
``DRGN_USE_PROC_AND_SYS_MODULES``
|
|
Whether drgn should use ``/proc/modules`` and ``/sys/module`` to find
|
|
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.
|