[PATCH v22 5/6] rust: page: add `Frozen` page kind
From: Andreas Hindborg
Date: Wed Nov 18 2026 - 11:20:26 EST
Add the page kind `Frozen`. A `Page<Frozen>` is a frozen page that is
uniquely owned through an `Owned<Page<Frozen>>`. The reference count of
a frozen page is zero and references to it cannot be taken, so the
ownership is exclusive.
In contrast to `Page<Exclusive>`, a `Page<Frozen>` has no invariant on
who accesses the data of the page. The owner can share the data with a
device, and thus the data is accessed through the unsafe raw accessors
only.
Add `Page::alloc_frozen()` to allocate a `Page<Frozen>`, and let
`Page<Frozen>` dereference to `Page<Base>`.
Signed-off-by: Andreas Hindborg <a.hindborg@xxxxxxxxxx>
---
This currently has no users, but I add it here for completeness. Let's
discuss if we should keep it or not.
---
rust/kernel/page.rs | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 89 insertions(+), 1 deletion(-)
diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
index c885bcf4f886..c629764f773b 100644
--- a/rust/kernel/page.rs
+++ b/rust/kernel/page.rs
@@ -93,7 +93,7 @@ pub trait Sealed {}
/// Marker trait for the kinds of a [`Page`].
///
/// A page kind describes what is known about a `struct page`, and thereby what a [`Page`] of that
-/// kind can be used for. See [`Base`], [`RefCounted`] and [`Exclusive`].
+/// kind can be used for. See [`Base`], [`RefCounted`], [`Frozen`] and [`Exclusive`].
///
/// A [`Page`] of any other kind dereferences to a [`Page`] of the base kind [`Base`]. The
/// purpose of the dereference is coercion: a reference to a page of any kind can be passed to code
@@ -138,6 +138,7 @@ impl PageKind for RefCounted {}
///
/// - `Page<Base>` is a page for which nothing is known beyond its validity.
/// - `Page<RefCounted>`, or just `Page`, is a page that is managed by the page reference count.
+/// - `Page<Frozen>` is a uniquely owned page that references cannot be taken to.
/// - `Page<Exclusive>` is a uniquely owned page whose data follows standard Rust aliasing rules.
///
/// Operations that are valid for any page are available for all page kinds. All other page kinds
@@ -435,6 +436,93 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
// non-zero and it is okay to obtain an `ARef<Page>` from it.
unsafe impl AlwaysRefCounted for Page {}
+/// A [`PageKind`] for a frozen page.
+///
+/// The reference count of a frozen page is zero, and references to it cannot be taken. A
+/// [`Page<Frozen>`] is accessed through an owning [`Owned<Page<Frozen>>`], and the page is freed
+/// when the [`Owned<Page<Frozen>>`] is dropped.
+///
+/// Unlike for a [`Page<Exclusive>`], nothing is known about who accesses the data of a
+/// [`Page<Frozen>`]. For instance, the owner can share the data of the page with a device. Thus,
+/// the data is accessed through the unsafe raw accessors of [`Page`] only.
+///
+/// # Invariants
+///
+/// For a [`Page<Frozen>`]:
+///
+/// - The page is an order 0 frozen page: it was allocated with `alloc_frozen_pages()`, and its
+/// reference count is zero for as long as the [`Page<Frozen>`] exists.
+/// - The page is owned by a unique [`Owned<Page<Frozen>>`]. No references to the page exist
+/// together with the [`Owned<Page<Frozen>>`], other than the ones borrowed from it.
+pub struct Frozen;
+
+impl private::Sealed for Frozen {}
+impl PageKind for Frozen {}
+
+impl Deref for Page<Frozen> {
+ type Target = Page<Base>;
+
+ #[inline]
+ fn deref(&self) -> &Self::Target {
+ // SAFETY: `Page` is transparent over `struct page` for all page kinds, so the pointer cast
+ // is valid. `Base` has no invariants in addition to the ones of `Page`, which hold for
+ // `self`.
+ unsafe { &*ptr::from_ref(self).cast() }
+ }
+}
+
+impl Page<Frozen> {
+ /// Allocates a new frozen page.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::page::{
+ /// Page,
+ /// PAGE_SIZE, //
+ /// };
+ ///
+ /// let page = Page::alloc_frozen(GFP_KERNEL)?;
+ ///
+ /// // SAFETY: The page was just allocated and is not shared, so there are no concurrent reads
+ /// // or writes to the page.
+ /// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
+ /// # Ok::<(), Error>(())
+ /// ```
+ #[inline]
+ pub fn alloc_frozen(flags: Flags) -> Result<Owned<Self>, AllocError> {
+ // SAFETY: Depending on the value of `gfp_flags`, this call may sleep. Other than that, it
+ // is always safe to call this method.
+ let page = unsafe { bindings::alloc_frozen_pages(flags.as_raw(), 0) };
+ let page = NonNull::new(page).ok_or(AllocError)?;
+
+ // INVARIANT: The page was just allocated with `alloc_frozen_pages()`, so it is frozen and
+ // we own it.
+ // SAFETY:
+ // - We just successfully allocated the page, so `page` points to a valid `struct page`.
+ // Since `Page` is transparent over `struct page`, we can cast the pointer directly.
+ // - The page was just allocated, so no other `Owned` exists for it.
+ // - A `struct page` is never moved, so the page is pinned.
+ // - `Page<Frozen>` allows no other references to exist together with the `Owned`, and
+ // none exist, as the page is newly allocated and references cannot be taken to a frozen
+ // page. Thus, it is sound to hand out `&Page<Frozen>` and `Pin<&mut Page<Frozen>>`.
+ // - Pages have no logic that relies on them staying on a given thread or on them not being
+ // accessed concurrently.
+ Ok(unsafe { Owned::from_raw(page.cast()) })
+ }
+}
+
+impl Ownable for Page<Frozen> {
+ #[inline]
+ unsafe fn release(this: NonNull<Self>) {
+ // SAFETY: By the function safety requirements, we have exclusive ownership of the page, and
+ // by the type invariant the page is an order 0 frozen page, so we can free it with
+ // `free_frozen_pages()`. Since `Page` is transparent over `struct page`, we can cast the
+ // pointer directly.
+ unsafe { bindings::free_frozen_pages(this.cast().as_ptr(), 0) };
+ }
+}
+
/// A [`PageKind`] for a page whose data area follows standard Rust aliasing rules.
///
/// A [`Page<Exclusive>`] is accessed through an owning [`Owned<Page<Exclusive>>`]. It has the same
--
2.54.0