drgn.helpers.linux.mm: document catching FaultError for for_each_page()

for_each_page() can return offline pages that don't actually exist. Fixing this is difficult (see #228), but working around it by catching FaultError is easy. Document the recommended usage. Signed-off-by: Omar Sandoval <[email protected]>
osandov · Dec 15, 2022 · 0d9252e · 0d9252e
1 parent c6a24ee
commit 0d9252e
Showing 1 changed file with 17 additions and 1 deletion.
diff --git a/drgn/helpers/linux/mm.py b/drgn/helpers/linux/mm.py
@@ -690,7 +690,23 @@ def decode_page_flags(page: Object) -> str:
 
 def for_each_page(prog: Program) -> Iterator[Object]:
     """
-    Iterate over all pages in the system.
+    Iterate over every ``struct page *`` from the minimum to the maximum page.
+
+    .. note::
+
+        This may include offline pages which don't have a valid ``struct
+        page``. Wrap accesses in a ``try`` ... ``except``
+        :class:`drgn.FaultError`:
+
+        >>> for page in for_each_page(prog):
+        ...     try:
+        ...         if PageLRU(page):
+        ...             print(hex(page))
+        ...     except drgn.FaultError:
+        ...         continue
+        0xfffffb4a000c0000
+        0xfffffb4a000c0040
+        ...
 
     :return: Iterator of ``struct page *`` objects.
     """