docs: add 0.0.23 release highlights

Signed-off-by: Omar Sandoval <[email protected]>

Author: osandov

docs/conf.py

@@ -19,6 +19,10 @@
 ]
 
 extlinks = {
+    "contrib": (
+        "https://github.com/osandov/drgn/blob/main/contrib/%s",
+        "%s",
+    ),
     "linux": (
         "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/%s",
         "%s",

docs/release_highlights.rst

@@ -6,4 +6,5 @@ from the full `release notes <https://github.com/osandov/drgn/releases>`_.
 
 .. toctree::
 
+   release_highlights/0.0.23.rst
    release_highlights/0.0.22.rst

docs/release_highlights/0.0.23.rst

@@ -0,0 +1,172 @@
+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.