KHO PERSISTENT MEMORY TRACKER(9)

🧠 KHO persistent memory tracker 💾✨

section 9 — Kernel API Manual

---

🌸 DESCRIPTION 🌸

Okay so bestie, gather round — KHO keeps track of preserved memory using a radix tree data structure. And when I say every node of the tree is exactly a single page, I mean exactly one page, no notes, no exceptions, periodt. 🎀

The leaf nodes? They're bitmaps where each set bit is a preserved page of any order. And the intermediate nodes are tables of physical addresses that point down to a lower level node. It's giving organized. It's giving hierarchical. We stan a structured queen. 👑

The tree hierarchy is shown below:

  root
  +-------------------+
  |     Level 5       | (struct kho_radix_node)
  +-------------------+
    |
    v
  +-------------------+
  |     Level 4       | (struct kho_radix_node)
  +-------------------+
    |
    | ... (intermediate levels)
    |
    v
  +-------------------+
  |      Level 0      | (struct kho_radix_leaf)
  +-------------------+

---

So how do we actually walk this thing? 🚶‍♀️ We traverse the tree using a key that encodes the page's physical address (pa) and its order into a single unsigned long value. Lowkey iconic. The encoded key value is composed of two parts: the 'order bit' in the upper part and the —

  +------------+-----------------------------+--------------------------+
  | Page Order | Order Bit                   | Shifted Physical Address |
  +------------+-----------------------------+--------------------------+
  | 0          | ...000100 ... (at bit 52)   | pa >> (PAGE_SHIFT + 0)   |
  | 1          | ...000010 ... (at bit 51)   | pa >> (PAGE_SHIFT + 1)   |
  | 2          | ...000001 ... (at bit 50)   | pa >> (PAGE_SHIFT + 2)   |
  | ...        | ...                         | ...                      |
  +------------+-----------------------------+--------------------------+

✨ Shifted Physical Address ✨

The 'shifted physical address' is the physical address normalized for its order. It effectively represents the PFN shifted right by the order. Cute, efficient, no cap. 🦋

✨ Order Bit ✨

The 'order bit' encodes the page order by setting a single bit at a specific position. And the way that the position itself represents the order? Obsessed. 🤯

---

For instance, on a 64-bit system with 4KB pages (PAGE_SHIFT = 12), the maximum range for the shifted physical address (for order 0) is 52 bits (64 - 12). This address occupies bits [0-51]. For order 0, the order bit is set at position 52. Math ate, fr fr. 💅

The following diagram illustrates how the encoded key value is split into indices for the tree levels, with PAGE_SIZE of 4KB:

       63:60   59:51    50:42    41:33    32:24    23:15         14:0
  +---------+--------+--------+--------+--------+--------+-----------------+
  |    0    |  Lv 5  |  Lv 4  |  Lv 3  |  Lv 2  |  Lv 1  |  Lv 0 (bitmap)  |
  +---------+--------+--------+--------+--------+--------+-----------------+

---

The radix tree stores pages of all orders in a single 6-level hierarchy. 🌈 It efficiently shares higher tree levels, especially due to common zero top address bits, allowing a single, efficient algorithm to manage all pages. One algorithm to rule them all, main character energy honestly. ✨

And the bitmap approach also offers memory efficiency — for example, a 512KB bitmap can cover a 16GB memory range for 0-order pages with PAGE_SIZE = 4KB. Like?? The lewk. The economy. 🍓

---

🎀 ABI NOTES (well, the ABI warning) 🎀

⚠️ Bestie, listen to me carefully on this one. The data structures defined here are part of the KHO ABI. Any modification to these structures that breaks backward compatibility must be accompanied by an update to the "compatible" string. No sneaky edits, okay? This ensures that a newer kernel can correctly interpret the data passed by an older kernel. Respect the contract. 🫶

---

💖 SEE ALSO 💖

• Kernel file ./include/linux/kho/abi/kexec_handover.h — Kexec Handover ABI(9)
• Kexec Handover ABI for vmalloc Preservation(9)

---

Source: ./include/linux/kho/abi 🌸 October 2026 🌸

okay that's the whole page bestie, go forth and preserve some memory, ily, mwah 💋🎀✨