[PATCH 2/3] rust: page: add reference counting, raw pointers and a private bit lock
From: Vitaly Wool
Date: Tue Nov 17 2026 - 18:32:47 EST
From: Igor B <igor.b@xxxxxxxxx>
A `Page` always owns its page exclusively, with no way to take another
reference or keep it as a raw pointer. Add:
- `Page::get()`, which takes another reference with `get_page()`;
- `Page::into_raw()` and `Page::from_raw()`, to convert a `Page` to and
from the `struct page` pointer it holds a reference to;
- `Page::try_get_raw()`, which takes a reference from a possibly stale
pointer with `get_page_unless_zero()`, for lock-free lookups like
brd_lookup_page(). This is sound because a `struct page` is never
freed, even once its memory is;
- `Page::lock_private_bit()`, which takes a bit spinlock in the page's
`private` field and returns a guard that releases it. This gives a
page used as plain memory a lock of its own at no memory cost.
Add Rust helpers for `get_page()`, `get_page_unless_zero()`,
`bit_spin_lock()` and `bit_spin_unlock()`.
This patch was tested with the help of Claude Code AI coding assistant.
Signed-off-by: Igor Belousov <igor.b@xxxxxxxxx>
Signed-off-by: Vitaly Wool <vitaly.wool@xxxxxxxxxxx>
---
rust/helpers/bit_spinlock.c | 13 +++
rust/helpers/helpers.c | 1 +
rust/helpers/page.c | 10 +++
rust/kernel/page.rs | 160 ++++++++++++++++++++++++++++++++++++
4 files changed, 184 insertions(+)
create mode 100644 rust/helpers/bit_spinlock.c
diff --git a/rust/helpers/bit_spinlock.c b/rust/helpers/bit_spinlock.c
new file mode 100644
index 000000000000..5c59632bd171
--- /dev/null
+++ b/rust/helpers/bit_spinlock.c
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: GPL-2.0
+
+#include <linux/bit_spinlock.h>
+
+__rust_helper void rust_helper_bit_spin_lock(int bitnum, unsigned long *addr)
+{
+ bit_spin_lock(bitnum, addr);
+}
+
+__rust_helper void rust_helper_bit_spin_unlock(int bitnum, unsigned long *addr)
+{
+ bit_spin_unlock(bitnum, addr);
+}
diff --git a/rust/helpers/helpers.c b/rust/helpers/helpers.c
index d62c7be1ca7b..e955a33e3535 100644
--- a/rust/helpers/helpers.c
+++ b/rust/helpers/helpers.c
@@ -44,6 +44,7 @@
#include "barrier.c"
#include "binder.c"
#include "bitmap.c"
+#include "bit_spinlock.c"
#include "bitops.c"
#include "blk.c"
#include "bug.c"
diff --git a/rust/helpers/page.c b/rust/helpers/page.c
index f8463fbed2a2..9c287bfcc371 100644
--- a/rust/helpers/page.c
+++ b/rust/helpers/page.c
@@ -26,3 +26,13 @@ __rust_helper int rust_helper_page_to_nid(const struct page *page)
return page_to_nid(page);
}
#endif
+
+__rust_helper void rust_helper_get_page(struct page *page)
+{
+ get_page(page);
+}
+
+__rust_helper bool rust_helper_get_page_unless_zero(struct page *page)
+{
+ return get_page_unless_zero(page);
+}
diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
index 1c0796ea229f..e75d9efbcce6 100644
--- a/rust/kernel/page.rs
+++ b/rust/kernel/page.rs
@@ -12,6 +12,11 @@
code::*,
Result, //
},
+ ffi::{
+ c_int,
+ c_ulong, //
+ },
+ types::NotThreadSafe,
uaccess::UserSliceReader, //
};
use core::{
@@ -200,6 +205,139 @@ pub fn as_ptr(&self) -> *mut bindings::page {
self.page.as_ptr()
}
+ /// Takes an additional reference on this page.
+ ///
+ /// The returned [`Page`] independently owns one reference to the same page as `self`. The
+ /// page is only actually freed once every such [`Page`], including `self`, has been dropped.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::page::Page;
+ ///
+ /// let page = Page::alloc_page(GFP_KERNEL)?;
+ /// let page2 = page.get();
+ ///
+ /// drop(page);
+ /// // `page2` still keeps the page alive.
+ /// drop(page2);
+ /// # Ok::<(), kernel::alloc::AllocError>(())
+ /// ```
+ #[inline]
+ pub fn get(&self) -> Self {
+ // SAFETY: `self.page` is valid by the type invariant, and calling `get_page` on a page
+ // that is kept alive by `self` is always safe.
+ unsafe { bindings::get_page(self.page.as_ptr()) };
+ // INVARIANT: We just took a new reference to the page pointed to by `self.page`, so the
+ // new `Page` has ownership over that reference.
+ Self { page: self.page }
+ }
+
+ /// Consumes the [`Page`], returning the raw pointer to its `struct page`.
+ ///
+ /// The reference owned by `self` is not dropped: the caller becomes responsible for it, and
+ /// releases it by turning the pointer back into a [`Page`] with [`from_raw`](Self::from_raw).
+ #[inline]
+ pub fn into_raw(self) -> NonNull<bindings::page> {
+ ManuallyDrop::new(self).page
+ }
+
+ /// Takes back ownership of a page from a pointer returned by [`into_raw`](Self::into_raw).
+ ///
+ /// # Safety
+ ///
+ /// `ptr` must have been returned by [`Page::into_raw`], and the reference it stands for must
+ /// not have been taken back already, by an earlier call to this function.
+ #[inline]
+ pub unsafe fn from_raw(ptr: NonNull<bindings::page>) -> Self {
+ // INVARIANT: By the safety requirements of this function, `ptr` stands for a reference to a
+ // valid page that nobody else owns.
+ Self { page: ptr }
+ }
+
+ /// Attempts to take ownership of a page from a raw, possibly stale pointer.
+ ///
+ /// On success, returns a new [`Page`] that owns one reference to the page. On failure
+ /// (meaning the page's reference count had already reached zero, i.e. its last owner had
+ /// already released it), returns `None` without otherwise touching the page.
+ ///
+ /// This is the kernel's usual way of giving a lock-free, concurrent lookup (such as one
+ /// protected by the RCU read lock; see [`kernel::sync::rcu`](crate::sync::rcu)) a safe way to
+ /// turn a pointer it found into an owned reference, without taking any lock: unlike
+ /// [`get`](Self::get), this does not assume `ptr` is already known to be alive.
+ ///
+ /// # Safety
+ ///
+ /// `ptr` must point at a valid `struct page`. Note that, unlike most kernel objects, a
+ /// `struct page` is never freed or reused for a different purpose for as long as the system
+ /// is running: only the memory it describes is freed and may be reused once its reference
+ /// count drops to zero. It is therefore always safe to inspect and modify the reference count
+ /// through a `struct page` pointer that was, at some point, validly obtained, even if the
+ /// page has since been fully released by its last owner, as long as the pointer has not since
+ /// been reused to mean something other than a `struct page` pointer (which can only happen if
+ /// the caller itself reinterprets it as something else).
+ #[inline]
+ pub unsafe fn try_get_raw(ptr: NonNull<bindings::page>) -> Option<Self> {
+ // SAFETY: By the safety requirements of this function, `ptr` points at a valid
+ // `struct page`.
+ //
+ // INVARIANT: If this call returns `true`, then it has just incremented the reference
+ // count of the page pointed to by `ptr`, and we have ownership over that new reference.
+ if unsafe { bindings::get_page_unless_zero(ptr.as_ptr()) } {
+ Some(Self { page: ptr })
+ } else {
+ None
+ }
+ }
+
+ /// Returns a pointer to the `private` field of this page.
+ #[inline]
+ fn private_ptr(&self) -> *mut c_ulong {
+ // SAFETY: `self.page` points to a valid `struct page` by the type invariant. Taking the
+ // address of a field neither reads nor writes it.
+ unsafe { &raw mut (*self.as_ptr()).__bindgen_anon_1.__bindgen_anon_1.private }
+ }
+
+ /// Acquires bit `BIT` of the page's `private` field as a bit spinlock.
+ ///
+ /// Spins until the bit is clear, then sets it. The lock is released when the returned guard
+ /// is dropped. As with any spinlock, preemption is disabled while it is held. Bit spinlocks
+ /// are not tracked by lockdep.
+ ///
+ /// This gives a page that is used as plain memory, such as a page holding the contents of a
+ /// RAM disk, a lock of its own without growing any other structure.
+ ///
+ /// # Safety
+ ///
+ /// The caller must own the page's `private` field, and must only access it through this
+ /// function while the page is shared. This is the case for a page allocated with
+ /// [`Page::alloc_page`], which has `private` zeroed, as long as the page is never handed to
+ /// another user of `private`, such as the page cache.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use kernel::page::Page;
+ ///
+ /// let page = Page::alloc_page(GFP_KERNEL)?;
+ /// // SAFETY: `page` was just allocated, and its `private` field is only used here.
+ /// let guard = unsafe { page.lock_private_bit::<0>() };
+ /// drop(guard);
+ /// # Ok::<(), kernel::alloc::AllocError>(())
+ /// ```
+ #[inline]
+ pub unsafe fn lock_private_bit<const BIT: u32>(&self) -> PagePrivateBitGuard<'_, BIT> {
+ const { assert!(BIT < c_ulong::BITS) };
+ // SAFETY: `private_ptr()` returns a valid pointer, and the caller guarantees that the
+ // field is only accessed by bit spinlock operations.
+ unsafe { bindings::bit_spin_lock(BIT as c_int, self.private_ptr()) };
+ // INVARIANT: The lock was just acquired.
+ PagePrivateBitGuard {
+ page: self,
+ _not_send: NotThreadSafe,
+ }
+ }
+
/// Get the node id containing this page.
#[inline]
pub fn nid(&self) -> i32 {
@@ -373,6 +511,28 @@ pub unsafe fn copy_from_user_slice_raw(
}
}
+/// A bit spinlock held in the `private` field of a [`Page`].
+///
+/// Created by [`Page::lock_private_bit`]. The lock is released when the guard is dropped.
+///
+/// # Invariants
+///
+/// The guard holds bit `BIT` of the `private` field of `page` locked.
+#[must_use = "the lock is released immediately when the guard is unused"]
+pub struct PagePrivateBitGuard<'a, const BIT: u32> {
+ page: &'a Page,
+ _not_send: NotThreadSafe,
+}
+
+impl<const BIT: u32> Drop for PagePrivateBitGuard<'_, BIT> {
+ #[inline]
+ fn drop(&mut self) {
+ // SAFETY: `private_ptr()` returns a valid pointer, and the lock is held by the type
+ // invariant.
+ unsafe { bindings::bit_spin_unlock(BIT as c_int, self.page.private_ptr()) };
+ }
+}
+
impl Drop for Page {
#[inline]
fn drop(&mut self) {
--
2.39.5