[PATCH] docs/mm: document slab cache isolation with SLAB_NO_MERGE

[PATCH] docs/mm: document slab cache isolation with SLAB_NO_MERGE

[Mohammed EL Kadiri]

Add documentation explaining when and how to use SLAB_NO_MERGE to
protect security-critical slab caches from cross-cache heap
exploitation.

The document covers:
- Criteria for identifying caches that need isolation
- How the SLUB merge mechanism works and what prevents merging
- How to verify merge status on a running system
- The cross-cache attack class with CVE reference
- Tradeoffs (memory cost vs security benefit)
- Relationship to CONFIG_RANDOM_KMALLOC_CACHES, SLAB_TYPESAFE_BY_RCU,
  and the slab_nomerge boot parameter

This information was previously undocumented, requiring developers to
read mm/slab_common.c to understand when SLAB_NO_MERGE is appropriate.

Signed-off-by: Mohammed EL Kadiri <med08elkadiri@gmail.com>
---
 Documentation/mm/index.rst          |   1 +
 Documentation/mm/slab-isolation.rst | 113 ++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+)
 create mode 100644 Documentation/mm/slab-isolation.rst

diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst
index fb45acba16ac..c2d5349dfc34 100644
--- a/Documentation/mm/index.rst
+++ b/Documentation/mm/index.rst
@@ -17,6 +17,7 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
    page_allocation
    vmalloc
    slab
+   slab-isolation
    highmem
    page_reclaim
    swap
diff --git a/Documentation/mm/slab-isolation.rst b/Documentation/mm/slab-isolation.rst
new file mode 100644
index 000000000000..d51472eb0c95
--- /dev/null
+++ b/Documentation/mm/slab-isolation.rst
@@ -0,0 +1,113 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
+Slab Cache Isolation for Security
+==================================
+
+Overview
+========
+
+The SLUB allocator merges slab caches with compatible size, alignment, and
+flags to reduce memory fragmentation. While this improves memory efficiency,
+it allows objects of different types to share the same slab pages. This
+enables cross-cache heap exploitation, where a use-after-free in one object
+type can be leveraged to corrupt an unrelated type.
+
+The `SLAB_NO_MERGE` flag prevents a cache from being merged, ensuring it
+receives dedicated slab pages.
+
+When to use SLAB_NO_MERGE
+==========================
+
+`SLAB_NO_MERGE` should be considered for slab caches that meet the
+following criteria:
+
+1. *Security-critical contents*: The object holds data whose corruption
+   leads directly to privilege escalation or security bypass, such as
+   credentials, cryptographic keys, or capability sets.
+
+2. *Actually mergeable*: The cache must not already be unmergeable.
+   A cache is already unmergeable if any of the following is true:
+
+   - It has a constructor (`ctor` argument is non-NULL).
+   - It has a non-zero `usersize` (with `CONFIG_HARDENED_USERCOPY`).
+   - It already has `SLAB_NO_MERGE` or another `SLAB_NEVER_MERGE` flag.
+
+3. *Bounded allocation volume*: The cache has a predictable number of
+   active objects, so the memory cost of dedicated slab pages is
+   acceptable.
+
+How merging works
+=================
+
+When `kmem_cache_create()` is called:
+
+1. If `usersize` is non-zero, the merge path is skipped entirely.
+
+2. Otherwise, `find_mergeable()` in `mm/slab_common.c` searches for a
+   compatible existing cache. A merge is prevented if:
+
+   - The `slab_nomerge` boot parameter is set
+   - The new cache has a constructor
+   - The new cache's flags include `SLAB_NO_MERGE`
+   - No existing cache has compatible size and flags
+
+3. If a compatible cache is found, the new cache becomes an alias. Both
+   share the same slab pages.
+
+Verifying merge status
+======================
+
+To check whether a cache is merged on a running system::
+
+    # Check how many other caches share its pages
+    cat /sys/kernel/slab/<cache_name>/aliases
+
+    # aliases > 0 means other types share this cache's pages
+
+The cross-cache attack class
+=============================
+
+Cross-cache attacks exploit slab merging to achieve type confusion:
+
+1. Attacker triggers a use-after-free in object type A.
+2. Type A's cache is merged with type B (they share slab pages).
+3. The freed type A slot is reallocated as type B.
+4. Attacker uses the dangling pointer to corrupt type B.
+5. Privilege escalation.
+
+CVE-2022-29582 demonstrates this technique: an io_uring use-after-free is
+exploited via cross-cache page-level reallocation to achieve root.
+
+`SLAB_NO_MERGE` prevents step 2: dedicated pages mean a freed slot of
+one type cannot be reallocated as a different type.
+
+Tradeoffs
+=========
+
+*Memory*: Isolated caches may have partially-filled slab pages that
+cannot be used by other types. For caches with bounded allocation counts,
+this is typically a few extra pages.
+
+*Performance*: Zero impact on `kmem_cache_alloc()` and
+`kmem_cache_free()`. The only effect is at boot when the cache is
+created.
+
+Relationship to other mitigations
+==================================
+
+`CONFIG_RANDOM_KMALLOC_CACHES`
+    Creates 16 copies of each `kmalloc` size class and randomly assigns
+    allocations among them. Only affects `kmalloc()` users. Does not
+    affect named caches created with `kmem_cache_create()`.
+
+`SLAB_TYPESAFE_BY_RCU`
+    Delays freeing the slab page by an RCU grace period. Does not delay
+    object slot reuse. Does not prevent cross-cache merging. Solves a
+    different problem: safe lockless access to freed-and-reallocated
+    objects of the same type.
+
+`slab_nomerge` boot parameter
+    Disables merging for all caches globally. `SLAB_NO_MERGE` provides
+    the same protection selectively for individual caches without the
+    global memory cost.
-- 
2.43.0

Re: [PATCH] docs/mm: document slab cache isolation with SLAB_NO_MERGE

[Jonathan Corbet]

Mohammed EL Kadiri <med08elkadiri@gmail.com> writes:

> Add documentation explaining when and how to use SLAB_NO_MERGE to
> protect security-critical slab caches from cross-cache heap
> exploitation.
>
> The document covers:
> - Criteria for identifying caches that need isolation
> - How the SLUB merge mechanism works and what prevents merging
> - How to verify merge status on a running system
> - The cross-cache attack class with CVE reference
> - Tradeoffs (memory cost vs security benefit)
> - Relationship to CONFIG_RANDOM_KMALLOC_CACHES, SLAB_TYPESAFE_BY_RCU,
>   and the slab_nomerge boot parameter
>
> This information was previously undocumented, requiring developers to
> read mm/slab_common.c to understand when SLAB_NO_MERGE is appropriate.
>
> Signed-off-by: Mohammed EL Kadiri <med08elkadiri@gmail.com>
> ---
>  Documentation/mm/index.rst          |   1 +
>  Documentation/mm/slab-isolation.rst | 113 ++++++++++++++++++++++++++++
>  2 files changed, 114 insertions(+)
>  create mode 100644 Documentation/mm/slab-isolation.rst

Thank you for working to improve our documentation.

Did you write this with machine assistance?

Please review our documentation and adhere to our markup conventions.
For example, function names should just be function(), with no
additional markup.

Thanks,

jon

Re: [PATCH] docs/mm: document slab cache isolation with SLAB_NO_MERGE

[Mohammed EL Kadiri]

Hi Jonathan,

Thank you for the review.

Yes, I used AI assistance in writing this document. The technical
content reflects my understanding from working on the SLAB_NO_MERGE
patches (one of which was Acked by Vlastimil Babka), but I failed to
follow the documentation markup conventions.

I will fix the markup and resubmit as v2.

Mohammed

Re: [PATCH] docs/mm: document slab cache isolation with SLAB_NO_MERGE

[Jonathan Corbet]

Mohammed EL Kadiri <med08elkadiri@gmail.com> writes:

> Hi Jonathan,
>
> Thank you for the review.
>
> Yes, I used AI assistance in writing this document.

Please see Documentation/process/coding-assistants.rst for information
on how to document that use.

I would also consider starting to fill out Documentation/mm/slab.rst
rather than creating a new standalone file.

Thanks,

jon

Re: [PATCH] docs/mm: document slab cache isolation with SLAB_NO_MERGE

[Matthew Wilcox]

On Sat, Jun 06, 2026 at 04:58:55PM +0100, Mohammed EL Kadiri wrote:
> +The SLUB allocator merges slab caches with compatible size, alignment, and

More of a question for Vlastimil ... do we want to continue to
distinguish between slab (the API) and SLUB (the implementation)?
I don't think we ever want to go back to a situation where we have
multiple competing implementations of the slab API in the kernel.
So shouldn't we deprecate uses of SLUB, particularly in the
documentation?

> +flags to reduce memory fragmentation. While this improves memory efficiency,
> +it allows objects of different types to share the same slab pages. This

s/ pages//

> +enables cross-cache heap exploitation, where a use-after-free in one object
> +type can be leveraged to corrupt an unrelated type.
> +
> +The `SLAB_NO_MERGE` flag prevents a cache from being merged, ensuring it
> +receives dedicated slab pages.

s/slab pages/a dedicated slab/

> +2. *Actually mergeable*: The cache must not already be unmergeable.
> +   A cache is already unmergeable if any of the following is true:
> +
> +   - It has a constructor (`ctor` argument is non-NULL).
> +   - It has a non-zero `usersize` (with `CONFIG_HARDENED_USERCOPY`).
> +   - It already has `SLAB_NO_MERGE` or another `SLAB_NEVER_MERGE` flag.

I don't know if this is good advice for users of the API.  It's true
that the slab will already be unmergable for these other reasons, but
it's harmless to specify SLAB_NO_MERGE in that case.  And it
communicates intent.  And in case somebody removes the ctor in the
future, or we decide to change which flags are in SLAB_NEVER_MERGE,
the slab will still be unmergable.

> +3. *Bounded allocation volume*: The cache has a predictable number of
> +   active objects, so the memory cost of dedicated slab pages is
> +   acceptable.

I don't understand why this is a criteria.

> +How merging works
> +=================
> +
> +When `kmem_cache_create()` is called:
> +
> +1. If `usersize` is non-zero, the merge path is skipped entirely.
> +
> +2. Otherwise, `find_mergeable()` in `mm/slab_common.c` searches for a
> +   compatible existing cache. A merge is prevented if:
> +
> +   - The `slab_nomerge` boot parameter is set
> +   - The new cache has a constructor
> +   - The new cache's flags include `SLAB_NO_MERGE`
> +   - No existing cache has compatible size and flags
> +
> +3. If a compatible cache is found, the new cache becomes an alias. Both
> +   share the same slab pages.

This feels like documenting internals rather than documenting how to use
the flag.  I'd drop it entirely.

> +The cross-cache attack class
> +=============================
> +
> +Cross-cache attacks exploit slab merging to achieve type confusion:
> +
> +1. Attacker triggers a use-after-free in object type A.
> +2. Type A's cache is merged with type B (they share slab pages).
> +3. The freed type A slot is reallocated as type B.
> +4. Attacker uses the dangling pointer to corrupt type B.
> +5. Privilege escalation.
> +
> +CVE-2022-29582 demonstrates this technique: an io_uring use-after-free is
> +exploited via cross-cache page-level reallocation to achieve root.
> +
> +`SLAB_NO_MERGE` prevents step 2: dedicated pages mean a freed slot of
> +one type cannot be reallocated as a different type.

Not sure this section adds anything to what was already described.

> +Tradeoffs
> +=========
> +
> +*Memory*: Isolated caches may have partially-filled slab pages that
> +cannot be used by other types. For caches with bounded allocation counts,
> +this is typically a few extra pages.
> +
> +*Performance*: Zero impact on `kmem_cache_alloc()` and
> +`kmem_cache_free()`. The only effect is at boot when the cache is
> +created.
> +
> +Relationship to other mitigations
> +==================================
> +
> +`CONFIG_RANDOM_KMALLOC_CACHES`
> +    Creates 16 copies of each `kmalloc` size class and randomly assigns
> +    allocations among them. Only affects `kmalloc()` users. Does not
> +    affect named caches created with `kmem_cache_create()`.
> +
> +`SLAB_TYPESAFE_BY_RCU`
> +    Delays freeing the slab page by an RCU grace period. Does not delay
> +    object slot reuse. Does not prevent cross-cache merging. Solves a
> +    different problem: safe lockless access to freed-and-reallocated
> +    objects of the same type.
> +
> +`slab_nomerge` boot parameter
> +    Disables merging for all caches globally. `SLAB_NO_MERGE` provides
> +    the same protection selectively for individual caches without the
> +    global memory cost.

These two sections also feel unnecessary.

[PATCH v2] docs/mm/slab: document cache isolation with SLAB_NO_MERGE

[Mohammed EL Kadiri]

Add documentation to slab.rst explaining when and how to use
SLAB_NO_MERGE to protect security-critical slab caches from
cross-cache heap exploitation.

The document covers:
- When to use SLAB_NO_MERGE and what it communicates
- How to verify merge status on a running system
- Tradeoffs (memory cost vs performance)
- Relationship to CONFIG_RANDOM_KMALLOC_CACHES, SLAB_TYPESAFE_BY_RCU,
  and the slab_nomerge boot parameter

Assisted-by: Claude:claude-opus-4.6
Signed-off-by: Mohammed EL Kadiri <med08elkadiri@gmail.com>
---
Changes in v2 (per Jonathan Corbet and Matthew Wilcox feedback):
- Add content to existing slab.rst instead of creating new file
- Fix markup: use plain function() without additional formatting
- Use slab terminology consistently, not SLUB
- Remove How merging works section (implementation internals)
- Remove cross-cache attack class section (redundant)
- Remove Bounded allocation volume criteria
- Rephrase unmergeability guidance per Matthew Wilcox suggestion
- Add Assisted-by tag per coding-assistants.rst
 Documentation/mm/slab.rst | 60 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/Documentation/mm/slab.rst b/Documentation/mm/slab.rst
index 2bcc58ada302..c485bd257c44 100644
--- a/Documentation/mm/slab.rst
+++ b/Documentation/mm/slab.rst
@@ -4,6 +4,66 @@
 Slab Allocation
 ===============
 
+Cache isolation with SLAB_NO_MERGE
+===================================
+
+The slab allocator merges caches with compatible size, alignment, and flags
+to reduce memory fragmentation. While this improves memory efficiency, it
+allows objects of different types to share the same slab. This enables
+cross-cache heap exploitation, where a use-after-free in one object type can
+be leveraged to corrupt an unrelated type.
+
+SLAB_NO_MERGE prevents a cache from being merged, ensuring it receives a
+dedicated slab. A freed slot in an isolated cache can only be reallocated as
+the same object type.
+
+When to use SLAB_NO_MERGE
+--------------------------
+
+SLAB_NO_MERGE should be considered for caches holding security-critical
+objects whose corruption leads directly to privilege escalation, such as
+credentials, cryptographic keys, or capability sets.
+
+It is harmless to specify SLAB_NO_MERGE even if the cache is already
+unmergeable for other reasons (e.g., it has a constructor or a non-zero
+usersize). The flag communicates intent and ensures the cache remains
+isolated if those other properties change in the future.
+
+Verifying merge status
+-----------------------
+
+To check whether a cache is merged on a running system::
+
+    # Check how many other caches share its slab
+    cat /sys/kernel/slab/<cache_name>/aliases
+
+    # aliases > 0 means other types share this cache's slab
+
+Tradeoffs
+----------
+
+**Memory**: Isolated caches may have partially-filled slabs that cannot be
+used by other types. The overhead is typically a few extra pages.
+
+**Performance**: Zero impact on kmem_cache_alloc() and kmem_cache_free().
+The only effect is at boot when the cache is created.
+
+Relationship to other mitigations
+----------------------------------
+
+CONFIG_RANDOM_KMALLOC_CACHES creates multiple copies of each kmalloc size
+class and randomly assigns allocations among them. It only affects kmalloc()
+users and does not affect named caches created with kmem_cache_create().
+
+SLAB_TYPESAFE_BY_RCU delays freeing the slab by an RCU grace period. It
+does not delay object slot reuse and does not prevent cross-cache merging.
+It solves a different problem: safe lockless access to freed-and-reallocated
+objects of the same type.
+
+The slab_nomerge boot parameter disables merging for all caches globally.
+SLAB_NO_MERGE provides the same protection selectively for individual caches
+without the global memory cost.
+
 Functions and structures
 ========================
 
-- 
2.43.0

Re: [PATCH v2] docs/mm/slab: document cache isolation with SLAB_NO_MERGE

[Vishal Moola]

On Sun, Jun 07, 2026 at 08:06:45AM +0100, Mohammed EL Kadiri wrote:
> Add documentation to slab.rst explaining when and how to use
> SLAB_NO_MERGE to protect security-critical slab caches from
> cross-cache heap exploitation.

Thanks for helping improve the documentation. I haven't looked at the
patch, but have some comments in regards to the process.

We prefer to send new iterations of patches as separate threads,
with the exception being small fixes/cleanups.

Also, I'd recommend waiting a bit longer between versions to let the
maintainers comment since getting documentation is pretty particular.