drgn/docs/release_highlights/0.0.23.rst

0.0.23 (Released June 28th, 2023)
=================================

These are some of the highlights of drgn 0.0.23. See the `GitHub release
<https://github.com/osandov/drgn/releases/tag/v0.0.23>`_ for the full release
notes, including more improvements and bug fixes.

.. highlight:: pycon

Virtual Address Translation Helpers
-----------------------------------

This release added several Linux kernel helpers for translating virtual
addresses.

:func:`~drgn.helpers.linux.mm.follow_phys()` translates a virtual address to a
physical address in a given address space. For example, to get the physical
address that virtual address 0x7f7fe46a4270 maps to in process 115::

    >>> task = find_task(prog, 115)
    >>> address = 0x7f7fe46a4270
    >>> print(hex(follow_phys(task.mm, address)))
    0x4090270

:func:`~drgn.helpers.linux.mm.follow_page()` translates a virtual address to
the ``struct page *`` that it maps to::

    >>> follow_page(task.mm, address)
    *(struct page *)0xffffd20ac0102400 = {
        ...
    }

:func:`~drgn.helpers.linux.mm.follow_pfn()` translates a virtual address to the
page frame number (PFN) of the page that it maps to::

    >>> follow_pfn(task.mm, address)
    (unsigned long)16528

These can be used to translate arbitrary kernel virtual addresses by passing
``prog["init_mm"].address_of_()``::

    >>> print(hex(follow_phys(prog["init_mm"].address_of_(), 0xffffffffc0483000)))
    0x2e4b000

Vmalloc/Vmap Address Translation Helpers
----------------------------------------

:func:`~drgn.helpers.linux.mm.vmalloc_to_page()` is a special case of
:func:`~drgn.helpers.linux.mm.follow_page()` for vmalloc and vmap addresses::

    >>> vmalloc_to_page(prog, 0xffffffffc0477000)
    *(struct page *)0xffffc902400b8980 = {
        ...
    }

Likewise, :func:`~drgn.helpers.linux.mm.vmalloc_to_pfn()` is a special case of
:func:`~drgn.helpers.linux.mm.follow_pfn()` for vmalloc and vmap addresses::

    >>> vmalloc_to_pfn(prog, 0xffffffffc0477000)
    (unsigned long)11814

``contrib`` Directory
---------------------

Martin Liška, Boris Burkov, and Johannes Thumshirn added lots of new scripts to
the ``contrib`` directory:

- :contrib:`btrfs_tree.py`: work-in-progress helpers for Btrfs B-trees
- :contrib:`btrfs_tree_mod_log.py`: simulator for the Btrfs tree modification log
- :contrib:`dump_btrfs_bgs.py`: print block groups in a Btrfs filesystem
- :contrib:`kcore_list.py`: print memory regions from ``/proc/kcore``
- :contrib:`kernel_sys.py`: print system information (similar to crash's ``sys`` command)
- :contrib:`mount.py`: print a filesystem mount table
- :contrib:`platform_drivers.py`: print registered `platform drivers <https://docs.kernel.org/driver-api/driver-model/platform.html>`_
- :contrib:`vmmap.py`: print memory mappings in a process (similar to ``/proc/$pid/maps``)
- :contrib:`vmstat.py`: print information about kernel memory usage

Embedding Interactive Mode
--------------------------

:meth:`drgn.cli.run_interactive()` runs drgn's interactive mode. It can be used
to embed drgn in another application. For example, you could use it for a
custom :class:`drgn.Program` that the standard drgn CLI can't set up:

.. code-block:: python3

   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)

Full s390x Support
------------------

Sven Schnelle contributed s390x virtual address translation support. This is
the state of architecture support in this release:

.. list-table:: drgn 0.0.23 Architecture Support
    :header-rows: 1

    * - Architecture
      - Linux Kernel Modules
      - Stack Traces
      - Virtual Address Translation
    * - x86-64
      - ✓
      - ✓
      - ✓
    * - AArch64
      - ✓
      - ✓
      - ✓
    * - ppc64
      - ✓
      - ✓
      -
    * - s390x
      - ✓
      - ✓
      - ✓
    * - i386
      - ✓
      -
      -
    * - Arm
      - ✓
      -
      -
    * - RISC-V
      - ✓
      -
      -

Linux 6.3 & 6.4 Support
-----------------------

Linux 6.3 and 6.4 had an unusual number of breaking changes for drgn. Here are
some errors you might see with older versions of drgn that are fixed in this
release.

On startup (fixed by Ido Schimmel)::

    warning: could not get debugging information for:
    kernel modules (could not find loaded kernel modules: 'struct module' has no member 'core_size')

From :meth:`drgn.Program.stack_trace()` and :meth:`drgn.Thread.stack_trace()`::

    Exception: unknown ORC entry type 3

From :func:`~drgn.helpers.linux.mm.compound_order()` and
:func:`~drgn.helpers.linux.mm.compound_nr()`::

    AttributeError: 'struct page' has no member 'compound_order'

From :func:`~drgn.helpers.linux.block.for_each_disk()` and
:func:`~drgn.helpers.linux.block.for_each_partition()`::

    AttributeError: 'struct class' has no member 'p'

Python 3.12 Support
-------------------

Python 3.12, currently in beta, changed an implementation detail that drgn
depended on, which caused crashes like::

    Py_SIZE: Assertion `ob->ob_type != &PyLong_Type' failed.

Stephen Brennan fixed this.