Rust for Linux List
 help / color / mirror / Atom feed
* [PATCH v22 0/6] rust: page: add page kinds
@ 2026-11-18 16:18 Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 1/6] rust: page: add page kinds and make `Page` reference counted Andreas Hindborg
                   ` (6 more replies)
  0 siblings, 7 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 16:18 UTC (permalink / raw)
  To: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Zi Yan,
	Mike Rapoport, Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang,
	Matthew Wilcox, Danilo Krummrich, Miguel Ojeda, Boqun Feng,
	Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
	Alice Ryhl, Trevor Gross, Daniel Almeida, Tamir Duberstein,
	Alexandre Courbot, Onur Özkan, Greg Kroah-Hartman,
	Arve Hjønnevåg, Todd Kjos, Christian Brauner,
	Carlos Llamas
  Cc: Igor B, Vitaly Wool, linux-mm, rust-for-linux, linux-kernel

Note: The page patches were part of the `Ownable` series [1] until v21.
This series continues the version numbering of that series, and it depends
on v22 of that series for `Ownable`, `Owned` and the split of `RefCounted`
and `AlwaysRefCounted`.

Not all pages can be treated the same way. A page allocated with
`alloc_pages()` is managed by the page reference count, and kernel C code
routinely takes its own references to such a page. A page owned by the
slab allocator must not have references taken to it, but it can still
show up in places such as a bio vector. A frozen page has a reference
count of zero and is exclusively owned by the party that allocated it.

A single `Page` type cannot describe all of these. This series makes
`Page` generic over a sealed `PageKind` that describes what is known about
the page:

 - `Page<Base>` is the base kind. Nothing is known about the page
   beyond the validity of the `struct page`.
 - `Page<RefCounted>` is the default kind. The page is managed by the
   page reference count, and `Page<RefCounted>` implements
   `AlwaysRefCounted`.
 - `Page<Exclusive>` is a uniquely owned frozen page whose data area
   follows standard Rust aliasing rules, so the data is available as
   `&[u8]` and `&mut [u8]`. It is handled through
   `Owned<Page<Exclusive>>` and is the first in-tree user of `Owned`.
 - `Page<Frozen>` is a frozen page whose allocation is uniquely owned.
   Unlike for `Page<Exclusive>`, nothing is known about who accesses the
   data of the page, so the data is only available through the unsafe
   raw accessors.

Operations that are valid for any page are available for all page kinds.
All other page kinds dereference to `Page<Base>`. The purpose of the
dereference is coercion: a reference to a page of any kind can be passed
to code that takes a `&Page<Base>`.

`Page<Exclusive>` is backed by a frozen page, as suggested by Matthew
Wilcox in the review of v21. References cannot be taken to a frozen page,
so the exclusive ownership is upheld by mm rather than only by the Rust
type system.

Patch 1 adds the page kinds `Base` and `RefCounted`, makes
`Page<RefCounted>` reference counted, and updates the users of `Page`.

Patch 2 adds `Page::from_raw()`.

Patch 3 makes `alloc_frozen_pages()` and `free_frozen_pages()` available
outside of mm. The choice of `include/linux/gfp.h` as the new home of the
declarations is open for discussion.

Patch 4 adds the page kind `Exclusive`.

Patch 5 adds the page kind `Frozen`. It has no user in this series and
can be dropped if it is not wanted at this time.

Patch 6 adds slice access to the data of a `Page<Exclusive>`, and
tightens the safety requirements of the raw data accessors accordingly.

[1] https://msgid.link/20260910-unique-ref-v21-0-e83257373062@kernel.org

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
Changes in v22:
- Split the `Page` patches out of the `Ownable` series.
- Make `Page` generic over a `PageKind`, with the kinds `Base`,
  `RefCounted`, `Frozen` and `Exclusive`. `Page<Exclusive>` replaces the
  `ExclusivePage` type (Andreas).
- Back `Page<Exclusive>` by a frozen page (Matthew).
- Add a patch that makes `alloc_frozen_pages()` and `free_frozen_pages()`
  available outside of mm.
- Add the page kind `Frozen` in a separate patch (Andreas).
- Return `&Page<Base>` from `Vmalloc::to_page()` and `AsPageIter`, as
  these pages are not known to be reference counted.
- Make `Page::from_raw()` available for all page kinds. The caller selects
  the kind and upholds its invariants.
- Rename `ExclusivePage::alloc_page()` to `Page::alloc_exclusive()`
  (Andreas).
- Let `Page<Exclusive>` dereference to `Page<Base>` (Andreas).
- Add `Page::as_slice()` and `Page::as_mut_slice()` for `Page<Exclusive>`
  in a separate patch. Always zero the page and never allocate it from
  highmem, and require callers of the raw data accessors to ensure that
  no conflicting reference to the data exists. Update the safety comments
  of the existing callers (Andreas).
- Justify the `AlwaysRefCounted` implementation for `Page` by all
  instances of the type being reference counted, rather than by the type
  not implementing `Ownable` (Alice, Gary).
- Tighten the safety requirements of `Page::from_raw()` to require, for
  `Page<RefCounted>`, that the page is reference counted and that taking
  additional references is permitted (Sashiko).
- Mark `Page::alloc_exclusive()` as `#[inline]` (Sashiko).
- Drop the Reviewed-by tag from the `Page::from_raw()` patch, as its
  safety requirements changed.
- Link to v21: https://msgid.link/20260910-unique-ref-v21-0-e83257373062@kernel.org

The entries below are the `Page` related changes from the change log of
the `Ownable` series.

Changes in v21:
- Import `Page` directly in `allocator.rs` instead of using the
  `page::Page` path (Danilo).
- Convert `Page` to `AlwaysRefCounted` backed by `get_page()` and
  `put_page()` instead of `Ownable`, and return `ARef<Page>` from
  `Page::alloc_page()` (Alice).
- Update Rust Binder to store `ARef<Page>` instead of `Owned<Page>`
  (Alice).
- Add `ExclusivePage` as the in-tree `Owned` user, without
  `Deref<Target = Page>` as that would break its aliasing invariant.
  The type was previously posted as `SafePage` and is renamed here
  (Alice).
- Link to v20: https://msgid.link/20260824-unique-ref-v20-0-490735672187@kernel.org

Changes in v20:
- Use `self.page.get()` rather than `Opaque::cast_into` (Alice).
- Link to v19: https://msgid.link/20260626-unique-ref-v19-0-2607ca88dfdf@kernel.org

Changes in v18:
- Remove `BorrowedPage`; use `&Page` directly (Alice).
- Update Rust Binder for the `Owned<Page>` conversion (Alice).
- Fix stale `Page` docs (Sashiko).
- Link to v17: https://msgid.link/20260604-unique-ref-v17-0-7b4c3d2930b9@kernel.org

Changes in v16:
- Simplify pointer to reference cast in `Page::from_raw`.
- Use `NonNull<Page>` rather than `Owned<Page>` for `BorrowedPage` internals.
- Fix formatting for `Page::from_raw` docs.
- Link to v15: https://msgid.link/20260220-unique-ref-v15-0-893ed86b06cc@kernel.org

Changes in v14:
- Add patch: rust: page: convert to `Ownable`.
- Add patch: rust: page: add `from_raw()`.
- Link to v13: https://lore.kernel.org/r/20251117-unique-ref-v13-0-b5b243df1250@pm.me

---
Andreas Hindborg (6):
      rust: page: add page kinds and make `Page` reference counted
      rust: page: add `from_raw()`
      mm/page_alloc: make alloc_frozen_pages() available outside of mm
      rust: page: add `Exclusive` page kind for race-free page access
      rust: page: add `Frozen` page kind
      rust: page: add slice access to `Page<Exclusive>`

 drivers/android/binder/page_range.rs |  24 +-
 include/linux/gfp.h                  |   9 +
 mm/mempolicy.c                       |   1 +
 mm/page_alloc.c                      |  10 +
 mm/page_alloc.h                      |  14 -
 rust/helpers/page.c                  |  21 ++
 rust/kernel/alloc/allocator.rs       |  29 ++-
 rust/kernel/alloc/allocator/iter.rs  |   7 +-
 rust/kernel/alloc/kbox.rs            |   3 +-
 rust/kernel/alloc/kvec.rs            |   3 +-
 rust/kernel/page.rs                  | 481 ++++++++++++++++++++++++++++-------
 11 files changed, 474 insertions(+), 128 deletions(-)
---
base-commit: 7475ea8b58616b33c04afb976cf0fbaad9dd63fb
change-id: 20261112-page-ownable-2e97941a83b2
prerequisite-change-id: 20250305-unique-ref-29fcd675f9e9:v22
prerequisite-patch-id: 4e3c7a1a2077aaa0ece2d557fa73486355903ae5
prerequisite-patch-id: d1073c5dcd6287fbcba7848a5d182108930230c1
prerequisite-patch-id: 3244def11bbdf2eabaa6e94e15ce06540b2f5814
prerequisite-patch-id: cef14c5bef5ba519ceaf0a0e7c9e93ef974db7b3
prerequisite-patch-id: 56410da35ed8dbe7b210adae0985af705cc0b5b0

Best regards,
--  
Andreas Hindborg <a.hindborg@kernel.org>



^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH v22 1/6] rust: page: add page kinds and make `Page` reference counted
  2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
@ 2026-11-18 16:18 ` Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 2/6] rust: page: add `from_raw()` Andreas Hindborg
                   ` (5 subsequent siblings)
  6 siblings, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 16:18 UTC (permalink / raw)
  To: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Zi Yan,
	Mike Rapoport, Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang,
	Matthew Wilcox, Danilo Krummrich, Miguel Ojeda, Boqun Feng,
	Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
	Alice Ryhl, Trevor Gross, Daniel Almeida, Tamir Duberstein,
	Alexandre Courbot, Onur Özkan, Greg Kroah-Hartman,
	Arve Hjønnevåg, Todd Kjos, Christian Brauner,
	Carlos Llamas
  Cc: Igor B, Vitaly Wool, linux-mm, rust-for-linux, linux-kernel

A `struct page` has a reference count, and the lifetime of most pages is
managed by it. Kernel C code routinely takes its own references to such
pages, for example when a page is inserted into a VMA with
`vm_insert_page()`.

However, not every page is managed by its reference count, and not every
page may have references taken. For instance, a frozen page has a
reference count of zero, and `get_page()` must not be used on pages owned
by the slab allocator. Thus, a single `Page` type cannot represent both
pages that are known to be reference counted and pages for which this is
not known.

Make `Page` generic over a sealed `PageKind`, and add two page kinds:

 - `Base` is the base kind. Nothing is known about a `Page<Base>` beyond
   the validity of the `struct page`.
 - `RefCounted` is the default kind. A `Page<RefCounted>` is managed by
   the page reference count, and taking additional references to it is
   permitted.

Implement the `RefCounted` trait for `Page<RefCounted>`, backed by
`get_page()` and `put_page()`, mark it `AlwaysRefCounted`, and return
`ARef<Page>` from `Page::alloc_page()`. The page is freed when the last
reference to it is dropped; for the order-0 pages allocated here, this is
equivalent to `__free_pages()`.

The `RefCounted` page kind shares its name with the `RefCounted` trait.
The name matches the mm term for a page that is not frozen, and the kind
is the default, so it is rarely spelled out. In `page.rs`, the trait is
referred to as `aref::RefCounted`.

Operations that are valid for any page are available for all page
kinds.

Let `Page<RefCounted>` dereference to `Page<Base>`. The purpose of the
dereference is coercion: a `&Page<RefCounted>` can be passed to code
that takes a `&Page<Base>`.

This also allows pages to be handed out as plain references without
owning the `struct page`. Remove `BorrowedPage` and update users:
`Vmalloc::to_page()` and `AsPageIter` hand out `&Page<Base>`, and binder
uses `&Page` and `ARef<Page>`.

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
 drivers/android/binder/page_range.rs |   8 +-
 rust/helpers/page.c                  |  10 ++
 rust/kernel/alloc/allocator.rs       |  26 ++---
 rust/kernel/alloc/allocator/iter.rs  |   7 +-
 rust/kernel/page.rs                  | 195 ++++++++++++++++++++---------------
 5 files changed, 142 insertions(+), 104 deletions(-)

diff --git a/drivers/android/binder/page_range.rs b/drivers/android/binder/page_range.rs
index b0c797523bc2..451369e07e7f 100644
--- a/drivers/android/binder/page_range.rs
+++ b/drivers/android/binder/page_range.rs
@@ -198,7 +198,7 @@ unsafe impl Send for Inner {}
 #[repr(C)]
 struct PageInfo {
     lru: bindings::list_head,
-    page: Option<Page>,
+    page: Option<ARef<Page>>,
     range: *const ShrinkablePageRange,
 }
 
@@ -206,7 +206,7 @@ impl PageInfo {
     /// # Safety
     ///
     /// The caller ensures that writing to `me.page` is ok, and that the page is not currently set.
-    unsafe fn set_page(me: *mut PageInfo, page: Page) {
+    unsafe fn set_page(me: *mut PageInfo, page: ARef<Page>) {
         // SAFETY: This pointer offset is in bounds.
         let ptr = unsafe { &raw mut (*me).page };
 
@@ -229,13 +229,13 @@ unsafe fn get_page<'a>(me: *const PageInfo) -> Option<&'a Page> {
         let ptr = unsafe { &raw const (*me).page };
 
         // SAFETY: The pointer is valid for reading.
-        unsafe { (*ptr).as_ref() }
+        unsafe { (*ptr).as_deref() }
     }
 
     /// # Safety
     ///
     /// The caller ensures that writing to `me.page` is ok for the duration of 'a.
-    unsafe fn take_page(me: *mut PageInfo) -> Option<Page> {
+    unsafe fn take_page(me: *mut PageInfo) -> Option<ARef<Page>> {
         // SAFETY: This pointer offset is in bounds.
         let ptr = unsafe { &raw mut (*me).page };
 
diff --git a/rust/helpers/page.c b/rust/helpers/page.c
index f8463fbed2a2..906eb4b18f02 100644
--- a/rust/helpers/page.c
+++ b/rust/helpers/page.c
@@ -10,6 +10,16 @@ __rust_helper struct page *rust_helper_alloc_pages(gfp_t gfp_mask,
 	return alloc_pages(gfp_mask, order);
 }
 
+__rust_helper void rust_helper_get_page(struct page *page)
+{
+	get_page(page);
+}
+
+__rust_helper void rust_helper_put_page(struct page *page)
+{
+	put_page(page);
+}
+
 __rust_helper void *rust_helper_kmap_local_page(struct page *page)
 {
 	return kmap_local_page(page);
diff --git a/rust/kernel/alloc/allocator.rs b/rust/kernel/alloc/allocator.rs
index cd4203f27aed..bf20714156c5 100644
--- a/rust/kernel/alloc/allocator.rs
+++ b/rust/kernel/alloc/allocator.rs
@@ -17,7 +17,10 @@
 
 use crate::{
     bindings,
-    page, //
+    page::{
+        Base,
+        Page, //
+    }, //
 };
 
 use core::{
@@ -169,7 +172,7 @@ unsafe fn realloc(
 }
 
 impl Vmalloc {
-    /// Convert a pointer to a [`Vmalloc`] allocation to a [`page::BorrowedPage`].
+    /// Convert a pointer to a [`Vmalloc`] allocation to a [`Page<Base>`] reference.
     ///
     /// # Examples
     ///
@@ -202,20 +205,19 @@ impl Vmalloc {
     ///
     /// - `ptr` must be a valid pointer to a [`Vmalloc`] allocation.
     /// - `ptr` must remain valid for the entire duration of `'a`.
-    pub unsafe fn to_page<'a>(ptr: NonNull<u8>) -> page::BorrowedPage<'a> {
+    pub unsafe fn to_page<'a>(ptr: NonNull<u8>) -> &'a Page<Base> {
         // SAFETY: `ptr` is a valid pointer to `Vmalloc` memory.
         let page = unsafe { bindings::vmalloc_to_page(ptr.as_ptr().cast()) };
 
-        // SAFETY: `vmalloc_to_page` returns a valid pointer to a `struct page` for a valid pointer
-        // to `Vmalloc` memory.
-        let page = unsafe { NonNull::new_unchecked(page) };
-
+        // INVARIANT: `Base` has no invariants in addition to the validity of the `struct page`,
+        // which is argued below.
         // SAFETY:
-        // - `page` is a valid pointer to a `struct page`, given that by the safety requirements of
-        //   this function `ptr` is a valid pointer to a `Vmalloc` allocation.
-        // - By the safety requirements of this function `ptr` is valid for the entire lifetime of
-        //   `'a`.
-        unsafe { page::BorrowedPage::from_raw(page) }
+        // - `vmalloc_to_page` returns a valid, non-null pointer to a `struct page` for a valid
+        //   pointer to `Vmalloc` memory, given that by the safety requirements of this function
+        //   `ptr` is a valid pointer to a `Vmalloc` allocation.
+        // - By the safety requirements of this function `ptr`, and hence the `struct page`, is
+        //   valid for the entire lifetime of `'a`.
+        unsafe { &*page.cast() }
     }
 }
 
diff --git a/rust/kernel/alloc/allocator/iter.rs b/rust/kernel/alloc/allocator/iter.rs
index 02fda3ea5cae..7c69ef31fb0c 100644
--- a/rust/kernel/alloc/allocator/iter.rs
+++ b/rust/kernel/alloc/allocator/iter.rs
@@ -9,7 +9,8 @@
     ptr::NonNull, //
 };
 
-/// An [`Iterator`] of [`page::BorrowedPage`] items owned by a [`Vmalloc`] allocation.
+/// An [`Iterator`] of [`Page<Base>`](page::Page) references to the pages of a [`Vmalloc`]
+/// allocation.
 ///
 /// # Guarantees
 ///
@@ -28,11 +29,11 @@ pub struct VmallocPageIter<'a> {
     size: usize,
     /// The current page index of the [`Iterator`].
     index: usize,
-    _p: PhantomData<page::BorrowedPage<'a>>,
+    _p: PhantomData<&'a page::Page<page::Base>>,
 }
 
 impl<'a> Iterator for VmallocPageIter<'a> {
-    type Item = page::BorrowedPage<'a>;
+    type Item = &'a page::Page<page::Base>;
 
     fn next(&mut self) -> Option<Self::Item> {
         let offset = self.index.checked_mul(page::PAGE_SIZE)?;
diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
index 1c0796ea229f..b2a17c86e7de 100644
--- a/rust/kernel/page.rs
+++ b/rust/kernel/page.rs
@@ -12,11 +12,16 @@
         code::*,
         Result, //
     },
+    sync::aref::{
+        self,
+        ARef,
+        AlwaysRefCounted, //
+    },
+    types::Opaque,
     uaccess::UserSliceReader, //
 };
 use core::{
     marker::PhantomData,
-    mem::ManuallyDrop,
     ops::Deref,
     ptr::{
         self,
@@ -65,104 +70,106 @@ pub const fn page_align(addr: usize) -> Option<usize> {
     Some(sum & PAGE_MASK)
 }
 
-/// Representation of a non-owning reference to a [`Page`].
-///
-/// This type provides a borrowed version of a [`Page`] that is owned by some other entity, e.g. a
-/// [`Vmalloc`] allocation such as [`VBox`].
-///
-/// # Example
-///
-/// ```
-/// # use kernel::{bindings, prelude::*};
-/// use kernel::page::{BorrowedPage, Page, PAGE_SIZE};
-/// # use core::{mem::MaybeUninit, ptr, ptr::NonNull };
+/// Trait to be implemented by types which provide an [`Iterator`] of [`Page<Base>`] references,
+/// such as [`VmallocPageIter`](kernel::alloc::allocator::VmallocPageIter).
+pub trait AsPageIter {
+    /// The [`Iterator`] type, e.g. [`VmallocPageIter`](kernel::alloc::allocator::VmallocPageIter).
+    type Iter<'a>: Iterator<Item = &'a Page<Base>>
+    where
+        Self: 'a;
+
+    /// Returns an [`Iterator`] of [`Page<Base>`] references over all pages owned by `self`.
+    fn page_iter(&mut self) -> Self::Iter<'_>;
+}
+
+mod private {
+    pub trait Sealed {}
+}
+
+/// Marker trait for the kinds of a [`Page`].
 ///
-/// fn borrow_page<'a>(vbox: &'a mut VBox<MaybeUninit<[u8; PAGE_SIZE]>>) -> BorrowedPage<'a> {
-///     let ptr = ptr::from_ref(&**vbox);
+/// 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`] and [`RefCounted`].
 ///
-///     // SAFETY: `ptr` is a valid pointer to `Vmalloc` memory.
-///     let page = unsafe { bindings::vmalloc_to_page(ptr.cast()) };
+/// 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
+/// that takes a `&Page<Base>`.
+pub trait PageKind: private::Sealed {}
+
+/// The base [`PageKind`]: a valid page with no further guarantees.
 ///
-///     // SAFETY: `vmalloc_to_page` returns a valid pointer to a `struct page` for a valid
-///     // pointer to `Vmalloc` memory.
-///     let page = unsafe { NonNull::new_unchecked(page) };
+/// Nothing is known about how the allocation of a [`Page<Base>`] is managed. In particular,
+/// the page is not necessarily managed by the page reference count. For instance, pages owned by
+/// the slab allocator are not. Thus, it is not possible to obtain an [`ARef`] from a
+/// `&Page<Base>`.
 ///
-///     // SAFETY:
-///     // - `self.0` is a valid pointer to a `struct page`.
-///     // - `self.0` is valid for the entire lifetime of `self`.
-///     unsafe { BorrowedPage::from_raw(page) }
-/// }
+/// # Invariants
 ///
-/// let mut vbox = VBox::<[u8; PAGE_SIZE]>::new_uninit(GFP_KERNEL)?;
-/// let page = borrow_page(&mut vbox);
+/// A [`Page<Base>`] has no invariants in addition to the ones of [`Page`].
+pub struct Base;
+
+impl private::Sealed for Base {}
+impl PageKind for Base {}
+
+/// The default [`PageKind`]: a page that is managed by the page reference count.
 ///
-/// // SAFETY: There is no concurrent read or write to this page.
-/// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
-/// # Ok::<(), Error>(())
-/// ```
+/// A [`Page<RefCounted>`] is accessed through a shared reference or through an owning
+/// [`ARef<Page>`]. The page allocation is freed when the last reference to it is dropped.
 ///
 /// # Invariants
 ///
-/// The borrowed underlying pointer to a `struct page` is valid for the entire lifetime `'a`.
+/// For a [`Page<RefCounted>`]:
 ///
-/// [`VBox`]: kernel::alloc::VBox
-/// [`Vmalloc`]: kernel::alloc::allocator::Vmalloc
-pub struct BorrowedPage<'a>(ManuallyDrop<Page>, PhantomData<&'a Page>);
-
-impl<'a> BorrowedPage<'a> {
-    /// Constructs a [`BorrowedPage`] from a raw pointer to a `struct page`.
-    ///
-    /// # Safety
-    ///
-    /// - `ptr` must point to a valid `bindings::page`.
-    /// - `ptr` must remain valid for the entire lifetime `'a`.
-    pub unsafe fn from_raw(ptr: NonNull<bindings::page>) -> Self {
-        let page = Page { page: ptr };
-
-        // INVARIANT: The safety requirements guarantee that `ptr` is valid for the entire lifetime
-        // `'a`.
-        Self(ManuallyDrop::new(page), PhantomData)
-    }
-}
+/// - The allocation of the page is managed by the page reference count, and the reference count is
+///   non-zero.
+/// - It is permitted to take additional references to the page with `get_page()`.
+pub struct RefCounted;
 
-impl<'a> Deref for BorrowedPage<'a> {
-    type Target = Page;
+impl private::Sealed for RefCounted {}
+impl PageKind for RefCounted {}
 
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-
-/// Trait to be implemented by types which provide an [`Iterator`] implementation of
-/// [`BorrowedPage`] items, such as [`VmallocPageIter`](kernel::alloc::allocator::VmallocPageIter).
-pub trait AsPageIter {
-    /// The [`Iterator`] type, e.g. [`VmallocPageIter`](kernel::alloc::allocator::VmallocPageIter).
-    type Iter<'a>: Iterator<Item = BorrowedPage<'a>>
-    where
-        Self: 'a;
-
-    /// Returns an [`Iterator`] of [`BorrowedPage`] items over all pages owned by `self`.
-    fn page_iter(&mut self) -> Self::Iter<'_>;
-}
-
-/// A pointer to a page that owns the page allocation.
+/// A `struct page`.
+///
+/// A `Page` is generic over a [`PageKind`], which describes what is known about the page:
+///
+/// - `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.
+///
+/// Operations that are valid for any page are available for all page kinds. All other page kinds
+/// dereference to [`Page<Base>`], so that a reference to a page of any kind coerces to a
+/// `&Page<Base>`.
 ///
 /// # Invariants
 ///
-/// The pointer is valid, and has ownership over the page.
-pub struct Page {
-    page: NonNull<bindings::page>,
+/// - The `Page` is backed by a valid `struct page`.
+/// - The invariants of `Kind` hold for the page, see the documentation of the [`PageKind`] types.
+#[repr(transparent)]
+pub struct Page<Kind: PageKind = RefCounted> {
+    page: Opaque<bindings::page>,
+    _kind: PhantomData<Kind>,
 }
 
 // SAFETY: Pages have no logic that relies on them staying on a given thread, so moving them across
 // threads is safe.
-unsafe impl Send for Page {}
+unsafe impl<Kind: PageKind> Send for Page<Kind> {}
 
 // SAFETY: Pages have no logic that relies on them not being accessed concurrently, so accessing
 // them concurrently is safe.
-unsafe impl Sync for Page {}
+unsafe impl<Kind: PageKind> Sync for Page<Kind> {}
 
-impl Page {
+impl Deref for Page<RefCounted> {
+    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<RefCounted> {
     /// Allocates a new page.
     ///
     /// # Examples
@@ -185,19 +192,22 @@ impl Page {
     /// # Ok::<(), kernel::alloc::AllocError>(())
     /// ```
     #[inline]
-    pub fn alloc_page(flags: Flags) -> Result<Self, AllocError> {
+    pub fn alloc_page(flags: Flags) -> Result<ARef<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_pages(flags.as_raw(), 0) };
         let page = NonNull::new(page).ok_or(AllocError)?;
-        // INVARIANT: We just successfully allocated a page, so we now have ownership of the newly
-        // allocated page. We transfer that ownership to the new `Page` object.
-        Ok(Self { page })
+        // SAFETY: We just successfully allocated a page, so we own the reference count returned
+        // by `alloc_pages`, and we transfer that reference to the new `ARef<Page>`. Since `Page`
+        // is transparent, we can cast the pointer directly.
+        Ok(unsafe { ARef::from_raw(page.cast()) })
     }
+}
 
+impl<Kind: PageKind> Page<Kind> {
     /// Returns a raw pointer to the page.
     pub fn as_ptr(&self) -> *mut bindings::page {
-        self.page.as_ptr()
+        self.page.get()
     }
 
     /// Get the node id containing this page.
@@ -373,10 +383,25 @@ pub unsafe fn copy_from_user_slice_raw(
     }
 }
 
-impl Drop for Page {
+// SAFETY: By the type invariant, a `Page<RefCounted>` is managed by the page reference count.
+// Incrementing it via `get_page()` keeps the page alive at least until a matching `put_page()`,
+// which frees the page when the count reaches zero.
+unsafe impl aref::RefCounted for Page<RefCounted> {
+    #[inline]
+    fn inc_ref(&self) {
+        // SAFETY: By the type invariant, `self.as_ptr()` points to a valid `struct page` with a
+        // non-zero reference count.
+        unsafe { bindings::get_page(self.as_ptr()) };
+    }
+
     #[inline]
-    fn drop(&mut self) {
-        // SAFETY: By the type invariants, we have ownership of the page and can free it.
-        unsafe { bindings::__free_pages(self.page.as_ptr(), 0) };
+    unsafe fn dec_ref(obj: NonNull<Self>) {
+        // SAFETY: By the function safety requirements, the caller relinquishes a reference count
+        // on the page. Since `Page` is transparent, we can cast the pointer directly.
+        unsafe { bindings::put_page(obj.cast().as_ptr()) };
     }
 }
+
+// SAFETY: All instances of `Page` are reference counted, so a `&Page` proves that the refcount is
+// non-zero and it is okay to obtain an `ARef<Page>` from it.
+unsafe impl AlwaysRefCounted for Page {}

-- 
2.54.0



^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v22 2/6] rust: page: add `from_raw()`
  2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 1/6] rust: page: add page kinds and make `Page` reference counted Andreas Hindborg
@ 2026-11-18 16:18 ` Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 3/6] mm/page_alloc: make alloc_frozen_pages() available outside of mm Andreas Hindborg
                   ` (4 subsequent siblings)
  6 siblings, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 16:18 UTC (permalink / raw)
  To: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Zi Yan,
	Mike Rapoport, Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang,
	Matthew Wilcox, Danilo Krummrich, Miguel Ojeda, Boqun Feng,
	Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
	Alice Ryhl, Trevor Gross, Daniel Almeida, Tamir Duberstein,
	Alexandre Courbot, Onur Özkan, Greg Kroah-Hartman,
	Arve Hjønnevåg, Todd Kjos, Christian Brauner,
	Carlos Llamas
  Cc: Igor B, Vitaly Wool, linux-mm, rust-for-linux, linux-kernel

Add a method to `Page` that allows construction of a reference from a
`struct page` pointer.

The method is available for all page kinds. The caller selects the page
kind and must ensure that the invariants of that kind hold for the page.

A `&Page<RefCounted>` can be converted to an `ARef<Page>`. Thus, for
`Page<RefCounted>`, the page must be managed by the page reference count
and taking additional references to it must be permitted. This is not the
case for all pages, for instance pages owned by the slab allocator. Such
pages can be referenced as `Page<Base>`.

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
 rust/kernel/page.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
index b2a17c86e7de..2ceeac0237d5 100644
--- a/rust/kernel/page.rs
+++ b/rust/kernel/page.rs
@@ -217,6 +217,30 @@ pub fn nid(&self) -> i32 {
         unsafe { bindings::page_to_nid(self.as_ptr()) }
     }
 
+    /// Create a `&Page<Kind>` from a raw `struct page` pointer.
+    ///
+    /// It is up to the caller to select the correct [`PageKind`] for the page.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that, for the duration of `'a`:
+    /// - `ptr` is convertible to a shared reference.
+    /// - The invariants of `Kind` hold for the page pointed to by `ptr`, see the documentation of
+    ///   the [`PageKind`] types.
+    ///
+    /// Note that the invariants of [`RefCounted`] do not hold for all pages. For instance, pages
+    /// owned by the slab allocator are not managed by the page reference count. Use [`Base`] for
+    /// pages where nothing is known beyond their validity.
+    #[inline]
+    pub unsafe fn from_raw<'a>(ptr: *const bindings::page) -> &'a Self {
+        // INVARIANT: By the function safety requirements, `ptr` refers to a valid `struct page`
+        // for which the invariants of `Kind` hold, so the returned reference upholds the type
+        // invariants of `Page<Kind>`.
+        // SAFETY: By function safety requirements, `ptr` is not null and is convertible to a shared
+        // reference.
+        unsafe { &*ptr.cast() }
+    }
+
     /// Runs a piece of code with this page mapped to an address.
     ///
     /// The page is unmapped when this call returns.

-- 
2.54.0



^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v22 3/6] mm/page_alloc: make alloc_frozen_pages() available outside of mm
  2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 1/6] rust: page: add page kinds and make `Page` reference counted Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 2/6] rust: page: add `from_raw()` Andreas Hindborg
@ 2026-11-18 16:18 ` Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 4/6] rust: page: add `Exclusive` page kind for race-free page access Andreas Hindborg
                   ` (3 subsequent siblings)
  6 siblings, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 16:18 UTC (permalink / raw)
  To: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Zi Yan,
	Mike Rapoport, Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang,
	Matthew Wilcox, Danilo Krummrich, Miguel Ojeda, Boqun Feng,
	Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
	Alice Ryhl, Trevor Gross, Daniel Almeida, Tamir Duberstein,
	Alexandre Courbot, Onur Özkan, Greg Kroah-Hartman,
	Arve Hjønnevåg, Todd Kjos, Christian Brauner,
	Carlos Llamas
  Cc: Igor B, Vitaly Wool, linux-mm, rust-for-linux, linux-kernel

alloc_frozen_pages() and free_frozen_pages() are declared in the private
header mm/page_alloc.h, and free_frozen_pages() is not exported. Thus,
frozen pages cannot be allocated outside of mm, and not from modules.

The Rust page abstractions need frozen pages. The reference count of a
frozen page is zero and references to it cannot be taken, so the caller
that allocates a frozen page is guaranteed by mm to be its only owner.
The Rust abstractions rely on this to hand out the data of a page as a
Rust reference.

Move the declarations of alloc_frozen_pages(),
alloc_frozen_pages_noprof() and free_frozen_pages() to
include/linux/gfp.h, and export alloc_frozen_pages_noprof() and
free_frozen_pages() with EXPORT_SYMBOL_GPL().

For !CONFIG_NUMA, alloc_frozen_pages_noprof() is a static inline function
that passes ALLOC_DEFAULT to __alloc_frozen_pages_noprof(). ALLOC_DEFAULT
is private to mm, so the function cannot move to the public header as it
is. Move it out of line to mm/page_alloc.c instead. This adds a function
call to the existing callers in mm/slub.c on !CONFIG_NUMA kernels.

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
 include/linux/gfp.h |  9 +++++++++
 mm/mempolicy.c      |  1 +
 mm/page_alloc.c     | 10 ++++++++++
 mm/page_alloc.h     | 14 --------------
 4 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/include/linux/gfp.h b/include/linux/gfp.h
index 63a7654c725f..7e1f24658f9e 100644
--- a/include/linux/gfp.h
+++ b/include/linux/gfp.h
@@ -302,6 +302,15 @@ static inline struct folio *vma_alloc_folio_noprof(gfp_t gfp, int order,
 
 #define alloc_page(gfp_mask) alloc_pages(gfp_mask, 0)
 
+/*
+ * Allocate frozen pages. The reference count of a frozen page is zero, and
+ * references to it cannot be taken. The caller owns the pages and frees them
+ * with free_frozen_pages().
+ */
+struct page *alloc_frozen_pages_noprof(gfp_t gfp, unsigned int order);
+#define alloc_frozen_pages(...)			alloc_hooks(alloc_frozen_pages_noprof(__VA_ARGS__))
+void free_frozen_pages(struct page *page, unsigned int order);
+
 static inline struct page *alloc_page_vma_noprof(gfp_t gfp,
 		struct vm_area_struct *vma, unsigned long addr)
 {
diff --git a/mm/mempolicy.c b/mm/mempolicy.c
index 0cb6da1c47a4..6d872db9fc6a 100644
--- a/mm/mempolicy.c
+++ b/mm/mempolicy.c
@@ -2582,6 +2582,7 @@ struct page *alloc_frozen_pages_noprof(gfp_t gfp, unsigned order)
 	return alloc_pages_mpol(gfp, order, pol, NO_INTERLEAVE_INDEX,
 				       numa_node_id());
 }
+EXPORT_SYMBOL_GPL(alloc_frozen_pages_noprof);
 
 /**
  * alloc_pages - Allocate pages.
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index eb4f02617f53..d6284cf965cf 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -2993,6 +2993,7 @@ void free_frozen_pages(struct page *page, unsigned int order)
 {
 	__free_frozen_pages(page, order, FPI_NONE);
 }
+EXPORT_SYMBOL_GPL(free_frozen_pages);
 
 void free_frozen_pages_nolock(struct page *page, unsigned int order)
 {
@@ -5491,6 +5492,15 @@ struct page *__alloc_frozen_pages_noprof(gfp_t gfp, unsigned int order,
 }
 EXPORT_SYMBOL(__alloc_frozen_pages_noprof);
 
+#ifndef CONFIG_NUMA
+struct page *alloc_frozen_pages_noprof(gfp_t gfp, unsigned int order)
+{
+	return __alloc_frozen_pages_noprof(gfp, order, numa_node_id(), NULL,
+					   ALLOC_DEFAULT);
+}
+EXPORT_SYMBOL_GPL(alloc_frozen_pages_noprof);
+#endif
+
 struct page *__alloc_pages_noprof(gfp_t gfp, unsigned int order,
 		int preferred_nid, nodemask_t *nodemask, unsigned int alloc_flags)
 {
diff --git a/mm/page_alloc.h b/mm/page_alloc.h
index 7097ea1805f6..541fa8b3f532 100644
--- a/mm/page_alloc.h
+++ b/mm/page_alloc.h
@@ -237,22 +237,8 @@ struct page *__alloc_frozen_pages_noprof(gfp_t gfp, unsigned int order, int nid,
 		nodemask_t *nodemask, unsigned int alloc_flags);
 #define __alloc_frozen_pages(...) \
 	alloc_hooks(__alloc_frozen_pages_noprof(__VA_ARGS__))
-void free_frozen_pages(struct page *page, unsigned int order);
 void free_unref_folios(struct folio_batch *fbatch);
 
-#ifdef CONFIG_NUMA
-struct page *alloc_frozen_pages_noprof(gfp_t, unsigned int order);
-#else
-static inline struct page *alloc_frozen_pages_noprof(gfp_t gfp, unsigned int order)
-{
-	return __alloc_frozen_pages_noprof(gfp, order, numa_node_id(), NULL,
-					   ALLOC_DEFAULT);
-}
-#endif
-
-#define alloc_frozen_pages(...) \
-	alloc_hooks(alloc_frozen_pages_noprof(__VA_ARGS__))
-
 struct page *alloc_frozen_pages_nolock_noprof(gfp_t gfp_flags, int nid, unsigned int order);
 #define alloc_frozen_pages_nolock(...) \
 	alloc_hooks(alloc_frozen_pages_nolock_noprof(__VA_ARGS__))

-- 
2.54.0



^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v22 4/6] rust: page: add `Exclusive` page kind for race-free page access
  2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
                   ` (2 preceding siblings ...)
  2026-11-18 16:18 ` [PATCH v22 3/6] mm/page_alloc: make alloc_frozen_pages() available outside of mm Andreas Hindborg
@ 2026-11-18 16:18 ` Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 5/6] rust: page: add `Frozen` page kind Andreas Hindborg
                   ` (2 subsequent siblings)
  6 siblings, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 16:18 UTC (permalink / raw)
  To: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Zi Yan,
	Mike Rapoport, Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang,
	Matthew Wilcox, Danilo Krummrich, Miguel Ojeda, Boqun Feng,
	Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
	Alice Ryhl, Trevor Gross, Daniel Almeida, Tamir Duberstein,
	Alexandre Courbot, Onur Özkan, Greg Kroah-Hartman,
	Arve Hjønnevåg, Todd Kjos, Christian Brauner,
	Carlos Llamas
  Cc: Igor B, Vitaly Wool, linux-mm, rust-for-linux, linux-kernel

Add the page kind `Exclusive`. A `Page<Exclusive>` is a page that is
uniquely owned through an `Owned<Page<Exclusive>>`, with the added
invariant that the page data area does not incur data races. This means a
`Page<Exclusive>` cannot be mapped to user space or shared with devices,
and it becomes simpler to directly reference the contents of the page.

Back `Page<Exclusive>` by a frozen page, allocated with
`alloc_frozen_pages()` and freed with `free_frozen_pages()`. The reference
count of a frozen page is zero and references to it cannot be taken, so the
exclusive ownership is upheld by mm and not only by the Rust type system.

Add `Page::alloc_exclusive()` to allocate a `Page<Exclusive>`. The function
is not named `alloc_page()`, because inherent functions of the same name on
two page kinds would make the call `Page::alloc_page()` ambiguous.

`Page<Exclusive>` dereferences to `Page<Base>`. This does not allow
safe code to break the aliasing invariant of `Page<Exclusive>`:
`Page<Base>` does not implement `AlwaysRefCounted`, so no `ARef` to the
page can be obtained, and the raw data accessors are unsafe and already
require their callers to rule out races with all other accesses to the
page.

Suggested-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
 rust/helpers/page.c |  6 ++++
 rust/kernel/page.rs | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 100 insertions(+), 2 deletions(-)

diff --git a/rust/helpers/page.c b/rust/helpers/page.c
index 906eb4b18f02..8f9f624ea141 100644
--- a/rust/helpers/page.c
+++ b/rust/helpers/page.c
@@ -10,6 +10,12 @@ __rust_helper struct page *rust_helper_alloc_pages(gfp_t gfp_mask,
 	return alloc_pages(gfp_mask, order);
 }
 
+__rust_helper struct page *rust_helper_alloc_frozen_pages(gfp_t gfp_mask,
+							  unsigned int order)
+{
+	return alloc_frozen_pages(gfp_mask, order);
+}
+
 __rust_helper void rust_helper_get_page(struct page *page)
 {
 	get_page(page);
diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
index 2ceeac0237d5..c885bcf4f886 100644
--- a/rust/kernel/page.rs
+++ b/rust/kernel/page.rs
@@ -17,7 +17,11 @@
         ARef,
         AlwaysRefCounted, //
     },
-    types::Opaque,
+    types::{
+        Opaque,
+        Ownable,
+        Owned, //
+    },
     uaccess::UserSliceReader, //
 };
 use core::{
@@ -89,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`] and [`RefCounted`].
+/// kind can be used for. See [`Base`], [`RefCounted`] 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
@@ -134,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<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
 /// dereference to [`Page<Base>`], so that a reference to a page of any kind coerces to a
@@ -429,3 +434,90 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
 // SAFETY: All instances of `Page` are reference counted, so a `&Page` proves that the refcount is
 // non-zero and it is okay to obtain an `ARef<Page>` from it.
 unsafe impl AlwaysRefCounted for Page {}
+
+/// 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
+/// usage constraints as other Rust types. Thus, it cannot be mapped to user space or shared with
+/// devices. This makes it safe to reference the contents of the page while the page is mapped in
+/// kernel space.
+///
+/// A [`Page<Exclusive>`] is backed by a frozen page. The reference count of a frozen page is zero,
+/// and references to it cannot be taken. Thus, the exclusive ownership of the page is upheld by
+/// the kernel, and not only by the Rust type system.
+///
+/// # Invariants
+///
+/// For a [`Page<Exclusive>`]:
+///
+/// - 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<Exclusive>`] exists.
+/// - The page is owned by a unique [`Owned<Page<Exclusive>>`]. No references to the page exist
+///   together with the [`Owned<Page<Exclusive>>`], other than the ones borrowed from it.
+/// - The data of the page is accessed only through references to the [`Page<Exclusive>`],
+///   including the [`Page<Base>`] references it dereferences to.
+/// - Safe code reads the data of the page only through a shared reference, and writes it only
+///   through a mutable reference. The unsafe raw accessors of [`Page`] can write through a shared
+///   reference, their callers are required to rule out races with all other accesses.
+pub struct Exclusive;
+
+impl private::Sealed for Exclusive {}
+impl PageKind for Exclusive {}
+
+impl Deref for Page<Exclusive> {
+    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<Exclusive> {
+    /// Allocates a new exclusive page.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::page::Page;
+    ///
+    /// let page = Page::alloc_exclusive(GFP_KERNEL | __GFP_ZERO)?;
+    /// # Ok::<(), kernel::alloc::AllocError>(())
+    /// ```
+    #[inline]
+    pub fn alloc_exclusive(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, we
+        // own it, and its data is only accessible through the returned `Owned<Page<Exclusive>>`.
+        // 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<Exclusive>` 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<Exclusive>` and
+        //   `Pin<&mut Page<Exclusive>>`.
+        // - 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<Exclusive> {
+    #[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) };
+    }
+}

-- 
2.54.0



^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v22 5/6] rust: page: add `Frozen` page kind
  2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
                   ` (3 preceding siblings ...)
  2026-11-18 16:18 ` [PATCH v22 4/6] rust: page: add `Exclusive` page kind for race-free page access Andreas Hindborg
@ 2026-11-18 16:18 ` Andreas Hindborg
  2026-11-18 16:18 ` [PATCH v22 6/6] rust: page: add slice access to `Page<Exclusive>` Andreas Hindborg
  2026-11-18 17:02 ` [PATCH v22 0/6] rust: page: add page kinds Zi Yan
  6 siblings, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 16:18 UTC (permalink / raw)
  To: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Zi Yan,
	Mike Rapoport, Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang,
	Matthew Wilcox, Danilo Krummrich, Miguel Ojeda, Boqun Feng,
	Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
	Alice Ryhl, Trevor Gross, Daniel Almeida, Tamir Duberstein,
	Alexandre Courbot, Onur Özkan, Greg Kroah-Hartman,
	Arve Hjønnevåg, Todd Kjos, Christian Brauner,
	Carlos Llamas
  Cc: Igor B, Vitaly Wool, linux-mm, rust-for-linux, linux-kernel

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@kernel.org>

---

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



^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v22 6/6] rust: page: add slice access to `Page<Exclusive>`
  2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
                   ` (4 preceding siblings ...)
  2026-11-18 16:18 ` [PATCH v22 5/6] rust: page: add `Frozen` page kind Andreas Hindborg
@ 2026-11-18 16:18 ` Andreas Hindborg
  2026-11-18 17:02 ` [PATCH v22 0/6] rust: page: add page kinds Zi Yan
  6 siblings, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 16:18 UTC (permalink / raw)
  To: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Zi Yan,
	Mike Rapoport, Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang,
	Matthew Wilcox, Danilo Krummrich, Miguel Ojeda, Boqun Feng,
	Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
	Alice Ryhl, Trevor Gross, Daniel Almeida, Tamir Duberstein,
	Alexandre Courbot, Onur Özkan, Greg Kroah-Hartman,
	Arve Hjønnevåg, Todd Kjos, Christian Brauner,
	Carlos Llamas
  Cc: Igor B, Vitaly Wool, linux-mm, rust-for-linux, linux-kernel

The data of a `Page<Exclusive>` follows standard Rust aliasing rules, so
it can be handed out as a slice. Add `Page::as_slice()` and
`Page::as_mut_slice()` for `Page<Exclusive>`, which return the data of
the page as `&[u8]` and `&mut [u8]` respectively.

For this to be sound, add two invariants to the `Exclusive` page kind:

 - The data of the page is initialized. Thus, always allocate the page
   with `__GFP_ZERO`.
 - The page is not a highmem page. The data of the page is then
   permanently mapped in the kernel address space, and a slice can refer
   to it without a temporary mapping. Thus, never allocate the page
   with `__GFP_HIGHMEM`.

A `Page<Exclusive>` dereferences to `Page<Base>`, so the unsafe raw
data accessors can be called on it. These only required their callers to
rule out data races, which does not prevent a write to the page while a
slice to the data of the page exists. Thus, tighten the safety
requirements of the raw accessors: no reference to the data that is
written may exist, no mutable reference to the data that is read may
exist, and data written to a `Page<Exclusive>` with `write_raw()` must
be initialized.

Update the safety comments of the existing callers of the raw accessors,
in the binder driver and in the allocator documentation examples, to
cover the new requirements.

Add the helper `rust_helper_page_address()`, as `page_address()` is a
macro in some configurations.

Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
 drivers/android/binder/page_range.rs | 16 ++++--
 rust/helpers/page.c                  |  5 ++
 rust/kernel/alloc/allocator.rs       |  3 +-
 rust/kernel/alloc/kbox.rs            |  3 +-
 rust/kernel/alloc/kvec.rs            |  3 +-
 rust/kernel/page.rs                  | 98 +++++++++++++++++++++++++++++++-----
 6 files changed, 110 insertions(+), 18 deletions(-)

diff --git a/drivers/android/binder/page_range.rs b/drivers/android/binder/page_range.rs
index 451369e07e7f..db0853751993 100644
--- a/drivers/android/binder/page_range.rs
+++ b/drivers/android/binder/page_range.rs
@@ -538,7 +538,9 @@ pub(crate) unsafe fn copy_from_user_slice(
         offset: usize,
         size: usize,
     ) -> Result {
-        // SAFETY: `self.iterate` has the same safety requirements as `copy_from_user_slice`.
+        // SAFETY: `self.iterate` has the same safety requirements as `copy_from_user_slice`. The
+        // pages of this range are `Page<RefCounted>` pages, and this driver never creates a
+        // reference to their data, so no reference to the data that is written exists.
         unsafe {
             self.iterate(offset, size, |page, offset, to_copy| {
                 page.copy_from_user_slice_raw(reader, offset, to_copy)
@@ -560,6 +562,9 @@ pub(crate) unsafe fn read<T: FromBytes>(&self, offset: usize) -> Result<T> {
                 // SAFETY: The sum of `offset` and `to_copy` is bounded by the size of T.
                 let obj_ptr = out.as_mut_ptr().cast::<u8>().add(out_offset);
                 // SAFETY: The pointer points is in-bounds of the `out` variable, so it is valid.
+                // The pages of this range are `Page<RefCounted>` pages, and this driver never
+                // creates a reference to their data, so no mutable reference to the data that is
+                // read exists.
                 page.read_raw(obj_ptr, offset, to_copy)?;
                 out_offset += to_copy;
                 Ok(())
@@ -581,7 +586,10 @@ pub(crate) unsafe fn write<T: ?Sized>(&self, offset: usize, obj: &T) -> Result {
             self.iterate(offset, size_of_val(obj), |page, offset, to_copy| {
                 // SAFETY: The sum of `offset` and `to_copy` is bounded by the size of T.
                 let obj_ptr = ptr::from_ref(obj).cast::<u8>().add(obj_offset);
-                // SAFETY: We have a reference to the object, so the pointer is valid.
+                // SAFETY: We have a reference to the object, so the pointer is valid. The pages
+                // of this range are `Page<RefCounted>` pages, and this driver never creates a
+                // reference to their data, so no reference to the data that is written exists. As
+                // the page is not a `Page<Exclusive>`, the object does not have to be initialized.
                 page.write_raw(obj_ptr, offset, to_copy)?;
                 obj_offset += to_copy;
                 Ok(())
@@ -595,7 +603,9 @@ pub(crate) unsafe fn write<T: ?Sized>(&self, offset: usize, obj: &T) -> Result {
     ///
     /// All pages touched by this operation must be in use for the duration of this call.
     pub(crate) unsafe fn fill_zero(&self, offset: usize, size: usize) -> Result {
-        // SAFETY: `self.iterate` has the same safety requirements as `copy_into`.
+        // SAFETY: `self.iterate` has the same safety requirements as `fill_zero`. The pages of
+        // this range are `Page<RefCounted>` pages, and this driver never creates a reference to
+        // their data, so no reference to the data that is written exists.
         unsafe {
             self.iterate(offset, size, |page, offset, len| {
                 page.fill_zero_raw(offset, len)
diff --git a/rust/helpers/page.c b/rust/helpers/page.c
index 8f9f624ea141..313a3a3b30b7 100644
--- a/rust/helpers/page.c
+++ b/rust/helpers/page.c
@@ -26,6 +26,11 @@ __rust_helper void rust_helper_put_page(struct page *page)
 	put_page(page);
 }
 
+__rust_helper void *rust_helper_page_address(const struct page *page)
+{
+	return page_address(page);
+}
+
 __rust_helper void *rust_helper_kmap_local_page(struct page *page)
 {
 	return kmap_local_page(page);
diff --git a/rust/kernel/alloc/allocator.rs b/rust/kernel/alloc/allocator.rs
index bf20714156c5..5d13dd1a8942 100644
--- a/rust/kernel/alloc/allocator.rs
+++ b/rust/kernel/alloc/allocator.rs
@@ -195,7 +195,8 @@ impl Vmalloc {
     ///     // `ptr` is valid for the entire lifetime of `page`.
     ///     let page = unsafe { Vmalloc::to_page(ptr.cast()) };
     ///
-    ///     // SAFETY: There is no concurrent read or write to the same page.
+    ///     // SAFETY: There is no concurrent read or write to the same page, and no reference to
+    ///     // the data of the page exists.
     ///     unsafe { page.fill_zero_raw(0, page::PAGE_SIZE)? };
     /// }
     /// # Ok::<(), Error>(())
diff --git a/rust/kernel/alloc/kbox.rs b/rust/kernel/alloc/kbox.rs
index 7e8ce3b36673..0d02b95b219e 100644
--- a/rust/kernel/alloc/kbox.rs
+++ b/rust/kernel/alloc/kbox.rs
@@ -745,7 +745,8 @@ fn drop(&mut self) {
 ///
 /// let page = vbox.page_iter().next().expect("At least one page should be available.\n");
 ///
-/// // SAFETY: There is no concurrent read or write to the same page.
+/// // SAFETY: There is no concurrent read or write to the same page, and no reference to the
+/// // data of the page exists.
 /// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
 /// # Ok::<(), Error>(())
 /// ```
diff --git a/rust/kernel/alloc/kvec.rs b/rust/kernel/alloc/kvec.rs
index c7546b9da4fa..57e0242a1dde 100644
--- a/rust/kernel/alloc/kvec.rs
+++ b/rust/kernel/alloc/kvec.rs
@@ -1230,7 +1230,8 @@ fn into_iter(self) -> Self::IntoIter {
 ///
 /// let page = vec.page_iter().next().expect("At least one page should be available.\n");
 ///
-/// // SAFETY: There is no concurrent read or write to the same page.
+/// // SAFETY: There is no concurrent read or write to the same page, and no reference to the
+/// // data of the page exists.
 /// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
 /// # Ok::<(), Error>(())
 /// ```
diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
index c629764f773b..19b9c35a3e70 100644
--- a/rust/kernel/page.rs
+++ b/rust/kernel/page.rs
@@ -4,6 +4,10 @@
 
 use crate::{
     alloc::{
+        flags::{
+            __GFP_HIGHMEM,
+            __GFP_ZERO, //
+        },
         AllocError,
         Flags, //
     },
@@ -27,6 +31,7 @@
 use core::{
     marker::PhantomData,
     ops::Deref,
+    pin::Pin,
     ptr::{
         self,
         NonNull, //
@@ -333,6 +338,8 @@ fn with_pointer_into_page<T>(
     /// * Callers must ensure that `dst` is valid for writing `len` bytes.
     /// * Callers must ensure that this call does not race with a write to the same page that
     ///   overlaps with this read.
+    /// * Callers must ensure that no mutable reference to the data of the page that overlaps with
+    ///   this read exists during this call.
     pub unsafe fn read_raw(&self, dst: *mut u8, offset: usize, len: usize) -> Result {
         self.with_pointer_into_page(offset, len, move |src| {
             // SAFETY: If `with_pointer_into_page` calls into this closure, then
@@ -355,6 +362,11 @@ pub unsafe fn read_raw(&self, dst: *mut u8, offset: usize, len: usize) -> Result
     /// * Callers must ensure that `src` is valid for reading `len` bytes.
     /// * Callers must ensure that this call does not race with a read or write to the same page
     ///   that overlaps with this write.
+    /// * Callers must ensure that no reference to the data of the page that overlaps with this
+    ///   write exists during this call. Such references can be obtained from a
+    ///   [`Page<Exclusive>`], see [`Page::as_slice`].
+    /// * If the page is a [`Page<Exclusive>`], callers must ensure that the `len` bytes at `src`
+    ///   are initialized.
     pub unsafe fn write_raw(&self, src: *const u8, offset: usize, len: usize) -> Result {
         self.with_pointer_into_page(offset, len, move |dst| {
             // SAFETY: If `with_pointer_into_page` calls into this closure, then it has performed a
@@ -373,8 +385,11 @@ pub unsafe fn write_raw(&self, src: *const u8, offset: usize, len: usize) -> Res
     ///
     /// # Safety
     ///
-    /// Callers must ensure that this call does not race with a read or write to the same page that
-    /// overlaps with this write.
+    /// * Callers must ensure that this call does not race with a read or write to the same page
+    ///   that overlaps with this write.
+    /// * Callers must ensure that no reference to the data of the page that overlaps with this
+    ///   write exists during this call. Such references can be obtained from a
+    ///   [`Page<Exclusive>`], see [`Page::as_slice`].
     pub unsafe fn fill_zero_raw(&self, offset: usize, len: usize) -> Result {
         self.with_pointer_into_page(offset, len, move |dst| {
             // SAFETY: If `with_pointer_into_page` calls into this closure, then it has performed a
@@ -396,8 +411,11 @@ pub unsafe fn fill_zero_raw(&self, offset: usize, len: usize) -> Result {
     ///
     /// # Safety
     ///
-    /// Callers must ensure that this call does not race with a read or write to the same page that
-    /// overlaps with this write.
+    /// * Callers must ensure that this call does not race with a read or write to the same page
+    ///   that overlaps with this write.
+    /// * Callers must ensure that no reference to the data of the page that overlaps with this
+    ///   write exists during this call. Such references can be obtained from a
+    ///   [`Page<Exclusive>`], see [`Page::as_slice`].
     pub unsafe fn copy_from_user_slice_raw(
         &self,
         reader: &mut UserSliceReader,
@@ -485,7 +503,7 @@ impl Page<Frozen> {
     /// 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.
+    /// // or writes to the page, and no reference to the data of the page exists.
     /// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
     /// # Ok::<(), Error>(())
     /// ```
@@ -527,8 +545,8 @@ unsafe fn release(this: NonNull<Self>) {
 ///
 /// A [`Page<Exclusive>`] is accessed through an owning [`Owned<Page<Exclusive>>`]. It has the same
 /// usage constraints as other Rust types. Thus, it cannot be mapped to user space or shared with
-/// devices. This makes it safe to reference the contents of the page while the page is mapped in
-/// kernel space.
+/// devices. This makes it safe to reference the contents of the page, see [`Page::as_slice`] and
+/// [`Page::as_mut_slice`].
 ///
 /// A [`Page<Exclusive>`] is backed by a frozen page. The reference count of a frozen page is zero,
 /// and references to it cannot be taken. Thus, the exclusive ownership of the page is upheld by
@@ -546,7 +564,11 @@ unsafe fn release(this: NonNull<Self>) {
 ///   including the [`Page<Base>`] references it dereferences to.
 /// - Safe code reads the data of the page only through a shared reference, and writes it only
 ///   through a mutable reference. The unsafe raw accessors of [`Page`] can write through a shared
-///   reference, their callers are required to rule out races with all other accesses.
+///   reference, their callers are required to rule out races with all other accesses, and to
+///   ensure that no reference to the data they write exists.
+/// - The data of the page is initialized.
+/// - The page is not a highmem page, so its data is permanently mapped in the kernel address
+///   space.
 pub struct Exclusive;
 
 impl private::Sealed for Exclusive {}
@@ -567,23 +589,39 @@ fn deref(&self) -> &Self::Target {
 impl Page<Exclusive> {
     /// Allocates a new exclusive page.
     ///
+    /// The page is always zeroed, and it is never allocated from highmem. That is, `__GFP_ZERO` is
+    /// added to `flags`, and `__GFP_HIGHMEM` is removed from `flags`.
+    ///
     /// # Examples
     ///
     /// ```
-    /// use kernel::page::Page;
+    /// use kernel::page::{
+    ///     Page,
+    ///     PAGE_SIZE, //
+    /// };
+    ///
+    /// let mut page = Page::alloc_exclusive(GFP_KERNEL)?;
+    /// assert_eq!(page.as_slice().len(), PAGE_SIZE);
+    /// assert!(page.as_slice().iter().all(|byte| *byte == 0));
     ///
-    /// let page = Page::alloc_exclusive(GFP_KERNEL | __GFP_ZERO)?;
+    /// page.as_pin_mut().as_mut_slice()[..4].copy_from_slice(&[1, 2, 3, 4]);
+    /// assert_eq!(page.as_slice()[..5], [1, 2, 3, 4, 0]);
     /// # Ok::<(), kernel::alloc::AllocError>(())
     /// ```
     #[inline]
     pub fn alloc_exclusive(flags: Flags) -> Result<Owned<Self>, AllocError> {
+        let flags = (flags | __GFP_ZERO) & !__GFP_HIGHMEM;
+
         // 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, we
-        // own it, and its data is only accessible through the returned `Owned<Page<Exclusive>>`.
+        // INVARIANT:
+        // - The page was just allocated with `alloc_frozen_pages()`, so it is frozen, we own it,
+        //   and its data is only accessible through the returned `Owned<Page<Exclusive>>`.
+        // - We allocated with `__GFP_ZERO`, so the data of the page is initialized.
+        // - We allocated without `__GFP_HIGHMEM`, so the page is not a highmem page.
         // 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.
@@ -597,6 +635,42 @@ pub fn alloc_exclusive(flags: Flags) -> Result<Owned<Self>, AllocError> {
         //   accessed concurrently.
         Ok(unsafe { Owned::from_raw(page.cast()) })
     }
+
+    /// Returns a pointer to the data of the page.
+    #[inline]
+    fn data_ptr(&self) -> *mut u8 {
+        // SAFETY: By the type invariant of `Page`, `self.as_ptr()` points to a valid `struct page`.
+        unsafe { bindings::page_address(self.as_ptr()) }.cast()
+    }
+
+    /// Returns the data of the page as a slice of [`PAGE_SIZE`] bytes.
+    #[inline]
+    pub fn as_slice(&self) -> &[u8] {
+        // SAFETY:
+        // - By the type invariant, the page is not a highmem page, so `data_ptr()` returns a
+        //   non-null pointer that is valid for reads of `PAGE_SIZE` bytes for as long as the page
+        //   exists, which is at least the lifetime of `self`.
+        // - By the type invariant, the data of the page is initialized.
+        // - By the type invariant, the data of the page is only written by safe code through a
+        //   mutable reference to the page, which cannot exist together with `self`. Callers of the
+        //   unsafe raw accessors must ensure that no reference to the data they write exists.
+        //   Thus, the data is not mutated for the lifetime of the returned reference.
+        unsafe { core::slice::from_raw_parts(self.data_ptr(), PAGE_SIZE) }
+    }
+
+    /// Returns the data of the page as a mutable slice of [`PAGE_SIZE`] bytes.
+    #[inline]
+    pub fn as_mut_slice(self: Pin<&mut Self>) -> &mut [u8] {
+        // SAFETY:
+        // - By the type invariant, the page is not a highmem page, so `data_ptr()` returns a
+        //   non-null pointer that is valid for reads and writes of `PAGE_SIZE` bytes for as long as
+        //   the page exists, which is at least the lifetime of `self`.
+        // - By the type invariant, the data of the page is initialized.
+        // - By the type invariant, the data of the page is only accessed through references to the
+        //   page. `self` is a mutable reference, so no other reference to the page exists, and
+        //   thus no other access to the data happens for the lifetime of the returned reference.
+        unsafe { core::slice::from_raw_parts_mut(self.data_ptr(), PAGE_SIZE) }
+    }
 }
 
 impl Ownable for Page<Exclusive> {

-- 
2.54.0



^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: [PATCH v22 0/6] rust: page: add page kinds
  2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
                   ` (5 preceding siblings ...)
  2026-11-18 16:18 ` [PATCH v22 6/6] rust: page: add slice access to `Page<Exclusive>` Andreas Hindborg
@ 2026-11-18 17:02 ` Zi Yan
  2026-11-18 19:34   ` Andreas Hindborg
  6 siblings, 1 reply; 9+ messages in thread
From: Zi Yan @ 2026-11-18 17:02 UTC (permalink / raw)
  To: Andreas Hindborg
  Cc: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Mike Rapoport,
	Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang, Matthew Wilcox,
	Danilo Krummrich, Miguel Ojeda, Boqun Feng, Gary Guo,
	Björn Roy Baron, Benno Lossin, Alice Ryhl, Trevor Gross,
	Daniel Almeida, Tamir Duberstein, Alexandre Courbot,
	Onur Özkan, Greg Kroah-Hartman, Arve Hjønnevåg,
	Todd Kjos, Christian Brauner, Carlos Llamas, Igor B, Vitaly Wool,
	linux-mm, rust-for-linux, linux-kernel

On 18 Nov 2026, at 11:18, Andreas Hindborg wrote:

> Note: The page patches were part of the `Ownable` series [1] until v21.
> This series continues the version numbering of that series, and it depends
> on v22 of that series for `Ownable`, `Owned` and the split of `RefCounted`
> and `AlwaysRefCounted`.
>
> Not all pages can be treated the same way. A page allocated with
> `alloc_pages()` is managed by the page reference count, and kernel C code
> routinely takes its own references to such a page. A page owned by the
> slab allocator must not have references taken to it, but it can still
> show up in places such as a bio vector. A frozen page has a reference
> count of zero and is exclusively owned by the party that allocated it.
>
> A single `Page` type cannot describe all of these. This series makes
> `Page` generic over a sealed `PageKind` that describes what is known about
> the page:
>
>  - `Page<Base>` is the base kind. Nothing is known about the page
>    beyond the validity of the `struct page`.
>  - `Page<RefCounted>` is the default kind. The page is managed by the
>    page reference count, and `Page<RefCounted>` implements
>    `AlwaysRefCounted`.
>  - `Page<Exclusive>` is a uniquely owned frozen page whose data area
>    follows standard Rust aliasing rules, so the data is available as
>    `&[u8]` and `&mut [u8]`. It is handled through
>    `Owned<Page<Exclusive>>` and is the first in-tree user of `Owned`.
>  - `Page<Frozen>` is a frozen page whose allocation is uniquely owned.
>    Unlike for `Page<Exclusive>`, nothing is known about who accesses the
>    data of the page, so the data is only available through the unsafe
>    raw accessors.

Why do we need to allocate Page<Frozen> when we can allocate Page<Exclusive>?
To me, Page<Frozen> is an observed page state from a non-owner point
of view.

In core-mm, a page is frozen, when its refcount == 0. The code looking
at the page knows the page is exclusively owned by others. If the code
allocates a frozen page, it will not check its refcount, because
the code knows it has the exclusive ownership of the page. To reflect
this, the code calling alloc_frozen_pages() should just get Page<Exclusive>
and if the code encounters a Page<Base> and finds it has no refcount,
it should convert it to Page<Frozen> or there should be a method
that accepts PFN and return Page<Frozen> if the page of the PFN has no
refcount, for PFN walkers.

“the data” mentioned in Page<Exclusive> and Page<Frozen> is struct page
data or the data in the physical frame pointed by Page<...>? If it
is the former, is it better to use metadata?

I am new to Rust, so feel free to correct me. Thanks. :)

>
> Operations that are valid for any page are available for all page kinds.
> All other page kinds dereference to `Page<Base>`. The purpose of the
> dereference is coercion: a reference to a page of any kind can be passed
> to code that takes a `&Page<Base>`.
>
> `Page<Exclusive>` is backed by a frozen page, as suggested by Matthew
> Wilcox in the review of v21. References cannot be taken to a frozen page,
> so the exclusive ownership is upheld by mm rather than only by the Rust
> type system.
>


Best Regards,
Yan, Zi

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH v22 0/6] rust: page: add page kinds
  2026-11-18 17:02 ` [PATCH v22 0/6] rust: page: add page kinds Zi Yan
@ 2026-11-18 19:34   ` Andreas Hindborg
  0 siblings, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2026-11-18 19:34 UTC (permalink / raw)
  To: Zi Yan
  Cc: Andrew Morton, Vlastimil Babka, Lorenzo Stoakes, Liam R. Howlett,
	Uladzislau Rezki, David Hildenbrand, Suren Baghdasaryan,
	Michal Hocko, Brendan Jackman, Johannes Weiner, Mike Rapoport,
	Joshua Hahn, Rakie Kim, Gregory Price, Ying Huang, Matthew Wilcox,
	Danilo Krummrich, Miguel Ojeda, Boqun Feng, Gary Guo,
	Björn Roy Baron, Benno Lossin, Alice Ryhl, Trevor Gross,
	Daniel Almeida, Tamir Duberstein, Alexandre Courbot,
	Onur Özkan, Greg Kroah-Hartman, Arve Hjønnevåg,
	Todd Kjos, Christian Brauner, Carlos Llamas, Igor B, Vitaly Wool,
	linux-mm, rust-for-linux, linux-kernel

Zi Yan <ziy@nvidia.com> writes:

> On 18 Nov 2026, at 11:18, Andreas Hindborg wrote:
>
>> Note: The page patches were part of the `Ownable` series [1] until v21.
>> This series continues the version numbering of that series, and it depends
>> on v22 of that series for `Ownable`, `Owned` and the split of `RefCounted`
>> and `AlwaysRefCounted`.
>>
>> Not all pages can be treated the same way. A page allocated with
>> `alloc_pages()` is managed by the page reference count, and kernel C code
>> routinely takes its own references to such a page. A page owned by the
>> slab allocator must not have references taken to it, but it can still
>> show up in places such as a bio vector. A frozen page has a reference
>> count of zero and is exclusively owned by the party that allocated it.
>>
>> A single `Page` type cannot describe all of these. This series makes
>> `Page` generic over a sealed `PageKind` that describes what is known about
>> the page:
>>
>>  - `Page<Base>` is the base kind. Nothing is known about the page
>>    beyond the validity of the `struct page`.
>>  - `Page<RefCounted>` is the default kind. The page is managed by the
>>    page reference count, and `Page<RefCounted>` implements
>>    `AlwaysRefCounted`.
>>  - `Page<Exclusive>` is a uniquely owned frozen page whose data area
>>    follows standard Rust aliasing rules, so the data is available as
>>    `&[u8]` and `&mut [u8]`. It is handled through
>>    `Owned<Page<Exclusive>>` and is the first in-tree user of `Owned`.
>>  - `Page<Frozen>` is a frozen page whose allocation is uniquely owned.
>>    Unlike for `Page<Exclusive>`, nothing is known about who accesses the
>>    data of the page, so the data is only available through the unsafe
>>    raw accessors.
>
> Why do we need to allocate Page<Frozen> when we can allocate Page<Exclusive>?
> To me, Page<Frozen> is an observed page state from a non-owner point
> of view.

I'm not sure we need it, which is why I added this note:

 This currently has no users, but I add it here for completeness. Let's
 discuss if we should keep it or not.

The difference between the `Page<Frozen>` and `Page<Exclusive>` is that
`Page<Exclusive>` has stronger invariants. Namely that the (physical)
memory region of the page does not incur data races, and that the page
not in highmem. From a Rust point of view, this allows us to obtain a
reference to the page contents without jumping through any hoops.

I do not have a user for a frozen page without these invariants, but I
would assume there are use cases?

> In core-mm, a page is frozen, when its refcount == 0. The code looking
> at the page knows the page is exclusively owned by others. If the code
> allocates a frozen page, it will not check its refcount, because
> the code knows it has the exclusive ownership of the page. To reflect
> this, the code calling alloc_frozen_pages() should just get
> Page<Exclusive>

Is it always the case that users of frozen pages will use them in such a
way that they can guarantee no races to the page contents (physical
memory)? They cannot be mapped for DMA access or anything like that -
that always requires a refcount?

> and if the code encounters a Page<Base> and finds it has no refcount,
> it should convert it to Page<Frozen> or there should be a method
> that accepts PFN and return Page<Frozen> if the page of the PFN has no
> refcount, for PFN walkers.

We can add conversion functions, that makes sense.

>
> “the data” mentioned in Page<Exclusive> and Page<Frozen> is struct page
> data or the data in the physical frame pointed by Page<...>? If it
> is the former, is it better to use metadata?

I'm referring to the actual physical memory region that the struct page
describes.

>
> I am new to Rust, so feel free to correct me. Thanks. :)
>

I'm new to mm, I really appreciate your eyes on this.


Best regards,
Andreas Hindborg



^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2026-11-18 19:34 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-18 16:18 [PATCH v22 0/6] rust: page: add page kinds Andreas Hindborg
2026-11-18 16:18 ` [PATCH v22 1/6] rust: page: add page kinds and make `Page` reference counted Andreas Hindborg
2026-11-18 16:18 ` [PATCH v22 2/6] rust: page: add `from_raw()` Andreas Hindborg
2026-11-18 16:18 ` [PATCH v22 3/6] mm/page_alloc: make alloc_frozen_pages() available outside of mm Andreas Hindborg
2026-11-18 16:18 ` [PATCH v22 4/6] rust: page: add `Exclusive` page kind for race-free page access Andreas Hindborg
2026-11-18 16:18 ` [PATCH v22 5/6] rust: page: add `Frozen` page kind Andreas Hindborg
2026-11-18 16:18 ` [PATCH v22 6/6] rust: page: add slice access to `Page<Exclusive>` Andreas Hindborg
2026-11-18 17:02 ` [PATCH v22 0/6] rust: page: add page kinds Zi Yan
2026-11-18 19:34   ` Andreas Hindborg

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox