Merge branch 'oracle-samples:main' into main

CHANGELOG.md

@@ -1,11 +1,65 @@
 Changelog
 =========
 
+Release Cycle
+-------------
+
+Prior to v1, the version numbers loosely followed the rule that new features
+would bump the minor version level, and bug fix releases would bump the patch
+version level.
+
+Beginning with v1, a new scheme is adopted which allows for a "development"
+version, and a stable version. Using the version numbers `x.y.z`, we have:
+
+1. The **development** version is of the form `x.0.z`, where `x` represents the
+   major version under development. Each release is performed by incrementing
+   `z`, the patch level, regardless of the type of changes. The development
+   version ends with the release of the "stable" version of `x.1.0`. The
+   development version is maintained on the `main` branch.
+2. The **stable** version is of the form `x.y.z`, where `y >= 1`, and `x` is of
+   course the major version. The "stable" versions are the only ones which are
+   released to Oracle Linux as RPMs. Releases will generally increment `z`, the
+   patch version, for bug fix releases. It's possible that in rare cases, we
+   will increment `y` for backports, in cases where we want to backport a module
+   to the stable release. The stable version is maintained in a branch named
+   `stable/vX`, where `X` is replaced with the major version number (e.g.
+   `stable/v1`).
+
+The stable version is maintained in parallel as the development version is
+developed. Fixes in the stable release must first be present in the development
+release (and all newer stable releases, if applicable).
+
+For the most part, regular maintenance of the stable version will end with the
+release of the next stable version, but maintenance may continue at our
+discretion.
+
+Examples:
+
+- `1.1.0` - the initial public release of the `1.x` stable series.
+- `1.1.1` - the first bugfix release of the `1.x` stable series.
+- `2.0.0` - the initial development version of the `2.x`.
+- `2.0.1` - an incremental development release in `2.x` development. It may
+  contain bug fixes or new features.
+- `2.1.0` - the initial public release of the `2.x` stable series.
+
+
 Unreleased
 ----------
 
 Changes which are committed to git, but not yet released, may appear here.
 
+1.1.0 - Tue, Aug 27, 2023
+-------------------------
+
+This is the first public release of drgn-tools!
+
+* Fixes for the irq, workqueue, bt, & nfs_tools modules.
+* Add ls and fsnotify modules.
+* Added new helpers for tasks & task states.
+* Basic functionality for running on UEK-NEXT (unsupported).
+* RPM name updated to "drgn-tools".
+* Support for CTF debuginfo added for the locks module.
+
 0.9.1 - Mon, Apr 22, 2023
 -------------------------
 

buildrpm/python-drgn-tools.spec

@@ -1,7 +1,7 @@
 # Copyright (c) 2024, Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 Name:           python-drgn-tools
-Version:        0.9.1
+Version:        1.1.0
 Release:        1%{?dist}
 Summary:        Helper scripts for drgn, containing the corelens utility
 
@@ -61,6 +61,9 @@ rm %{buildroot}/usr/bin/DRGN
 %{_mandir}/man1/corelens.1.gz
 
 %changelog
+* Tue Aug 27 2024 Stephen Brennan <[email protected]> - 1.1.0-1
+- Update to 1.1.0
+
 * Mon Apr 22 2024 Stephen Brennan <[email protected]> - 0.9.1-1
 - Update to 0.9.1
 

drgn_tools/slabinfo.py

@@ -4,13 +4,16 @@
 Helper to view slabinfo data
 """
 import argparse
+from typing import List
 from typing import NamedTuple
 from typing import Set
 from typing import Tuple
 
 from drgn import cast
+from drgn import FaultError
 from drgn import Object
 from drgn import Program
+from drgn import ProgramFlags
 from drgn import Type
 from drgn.helpers.linux.cpumask import for_each_present_cpu
 from drgn.helpers.linux.list import list_for_each_entry
@@ -40,6 +43,8 @@ class SlabCacheInfo(NamedTuple):
     """Slab size"""
     name: str
     """Name of the slab cache"""
+    freelist_corrupt_cpus: List[int]
+    """A list of CPUs for which the freelist was found to be corrupt"""
 
 
 def _slab_type(prog: Program) -> Type:
@@ -204,19 +209,41 @@ def slub_per_cpu_partial_free(cpu_partial: Object) -> int:
     return partial_free
 
 
-def kmem_cache_slub_info(cache: Object) -> Tuple[int, int]:
+class _CpuSlubWrapper:
+    def __init__(self, obj):
+        self._obj = obj
+
+    def __getattr__(self, key):
+        if key == "cpu_slab":
+            raise AttributeError("CpuSlubWrapper!")
+        return self._obj.__getattribute__(key)
+
+
+def kmem_cache_slub_info(cache: Object) -> Tuple[int, int, List[int]]:
     """
     For given kmem_cache object, parse through each cpu
     and get number of total slabs and free objects
 
+    If the CPU freelist was corrupt, then we do our best effort to count free
+    objects, but we may undercount them. We set the corruption flag when this
+    happens.
+
     :param: ``struct kmem_cache`` drgn object
-    :returns: total slabs, free objects
+    :returns: total slabs, free objects, corruption instances
     """
     prog = cache.prog_
     use_slab = _has_struct_slab(prog)
 
     total_slabs = objects = free_objects = 0
-    slub_helper = _get_slab_cache_helper(cache)
+
+    # The "cpu_slab" variable is used by the slab helper to preload the percpu
+    # freelists. Not only does this duplicate work we're about to do, but also
+    # corrupt slab caches will crash this function before we can detect which
+    # CPU is corrupt. Pretend we have no "cpu_slab" variable when getting the
+    # helper. This depends on implementation details: we will improve the helper
+    # upstream to avoid this for the future.
+    slub_helper = _get_slab_cache_helper(_CpuSlubWrapper(cache))
+    corrupt = []
 
     for cpuid in for_each_present_cpu(prog):
         per_cpu_slab = per_cpu_ptr(cache.cpu_slab, cpuid)
@@ -237,15 +264,25 @@ def kmem_cache_slub_info(cache: Object) -> Tuple[int, int]:
             objects = 0
 
         free_objects += objects - page_inuse
-        cpu_free_objects = slub_get_cpu_freelist_cnt(cpu_freelist, slub_helper)
-        free_objects += cpu_free_objects
+
+        # Easily the most common form of corruption in the slab allocator comes
+        # from use after free, which overwrites the freelist pointer and causes
+        # a fault error. Catch this and report it for later.
+        try:
+            cpu_free_objects = slub_get_cpu_freelist_cnt(
+                cpu_freelist, slub_helper
+            )
+        except FaultError:
+            corrupt.append(cpuid)
+        else:
+            free_objects += cpu_free_objects
 
         partial_frees = slub_per_cpu_partial_free(cpu_partial)
         free_objects += partial_frees
 
         total_slabs += 1
 
-    return total_slabs, free_objects
+    return total_slabs, free_objects, corrupt
 
 
 def get_kmem_cache_slub_info(cache: Object) -> SlabCacheInfo:
@@ -255,7 +292,7 @@ def get_kmem_cache_slub_info(cache: Object) -> SlabCacheInfo:
     :param cache: ``struct kmem_cache`` drgn object
     :returns: a :class:`SlabCacheInfo` with statistics about the cache
     """
-    total_slabs, free_objects = kmem_cache_slub_info(cache)
+    total_slabs, free_objects, corrupt = kmem_cache_slub_info(cache)
     (
         nr_slabs,
         nr_total_objs,
@@ -280,6 +317,7 @@ def get_kmem_cache_slub_info(cache: Object) -> SlabCacheInfo:
         total_slabs,
         ssize,
         cache.name.string_().decode("utf-8"),
+        corrupt,
     )
 
 
@@ -296,19 +334,42 @@ def print_slab_info(prog: Program) -> None:
             "NAME",
         ]
     )
+    corruption = []
     for cache in for_each_slab_cache(prog):
         slabinfo = get_kmem_cache_slub_info(cache)
+        maybe_asterisk = ""
+        if slabinfo.freelist_corrupt_cpus:
+            maybe_asterisk = "*"
+            corruption.append(slabinfo)
         table.row(
             slabinfo.cache.value_(),
             slabinfo.objsize,
-            slabinfo.allocated,
+            f"{slabinfo.allocated}{maybe_asterisk}",
             slabinfo.total,
             slabinfo.nr_slabs,
             f"{int(slabinfo.ssize / 1024)}k",
             slabinfo.name,
         )
     table.write()
 
+    if corruption:
+        if prog.flags & ProgramFlags.IS_LIVE:
+            print(
+                "NOTE: freelist corruption was detected. This is not "
+                "necessarily an error, as live systems may encounter race "
+                "conditions."
+            )
+        else:
+            print(
+                "WARNING: freelist corruption was detected. It is likely that "
+                "a use-after-free bug occurred."
+            )
+        table = FixedTable(["CACHE:<24s", "CORRUPT CPUS"])
+        for slabinfo in corruption:
+            cpus = ", ".join(map(str, slabinfo.freelist_corrupt_cpus))
+            table.row(slabinfo.name, cpus)
+        table.write()
+
 
 class SlabInfo(CorelensModule):
     """Print info about each slab cache"""

setup.py

@@ -9,7 +9,7 @@
 
 long_description = "drgn helper script repository"
 
-RELEASE_VERSION = "0.9.1"
+RELEASE_VERSION = "1.1.0"
 PACKAGES = ["drgn_tools"]
 if not os.environ.get("DRGN_TOOLS_V2_OMIT"):
     PACKAGES.append("drgn_tools.v2")