mirror of
https://github.com/JakeHillion/drgn.git
synced 2024-12-24 10:03:05 +00:00
9b563170f8
Rather than exposing the underlying open and load steps of DWARF index, simplify it down to a single load step.
81 lines
2.5 KiB
ReStructuredText
81 lines
2.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
|
|
|
|
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
|
|
|
|
|
|
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)
|
|
|
|
prog = drgn.Program(drgn.Architecture.IS_LITTLE_ENDIAN)
|
|
prog.add_memory_segment(0, None, size, read_file)
|
|
prog.load_debug_info([f'/lib/modules/{os.uname().release}/kernel/fs/btrfs/btrfs.ko'])
|
|
return prog
|
|
|
|
|
|
prog = btrfs_debugger('/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.
|