Skip to contentSkip to conversation

rust: page: implement BorrowedPage

PATCH Superseded Danilo Krummrich 6 participants 11 messages Aug 4, 2025 – Aug 5, 2025

Subsystems (2)

v1 of 5 Superseded Latest is v5 →

lore
Share & tools
lore

Danilo Krummrich

author reviewer
#0 lore raw

PATCH 1/1 rust: page: implement BorrowedPage

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

This is required by the scatterlist abstractions.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/page.rs             | 83 ++++++++++++++++++++++++++++++++-
 2 files changed, 83 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 84d60635e8a9..0e140e07758b 100644
@@ -57,6 +57,7 @@
 #include <linux/jiffies.h>
 #include <linux/jump_label.h>
 #include <linux/mdio.h>
+#include <linux/mm.h>
 #include <linux/miscdevice.h>
 #include <linux/of_device.h>
 #include <linux/pci.h>
rust/kernel/page.rs +82 -1

95 lines not on this page · raw message

base-commit: d2eedaa3909be9102d648a4a0a50ccf64f96c54f

Signature · 1 line
2.50.1
reviewer
#1 lore raw
Quoted 7 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

Are you going to replace it with &Page once that lands, or will this stay?

---
Cheers,
Benno

Quoted 8 lines

This is required by the scatterlist abstractions.

---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/page.rs             | 83 ++++++++++++++++++++++++++++++++-
 2 files changed, 83 insertions(+), 1 deletion(-)
author reviewer
#2 lore raw
Quoted 11 lines · Benno Lossin
Quoted 7 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

Are you going to replace it with &Page once that lands, or will this stay?

Yes, I think we can then use &'a Page instead.

reviewer Reviewed-by on v1 1/1
#3 lore raw
In reply to Danilo Krummrich
Quoted 11 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

This is required by the scatterlist abstractions.

Thanks, this fills quite a gap for the scatterlist patchset!

maintainer Acked-by on v1 1/1
#4 lore raw
In reply to Danilo Krummrich
Quoted 6 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Quoted 6 lines

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

This is required by the scatterlist abstractions.

#5 lore raw
In reply to Danilo Krummrich

Hi Danilo,

Quoted 9 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

I guess it’s a good idea to expand this part somewhat. Taken as it is, there is no way to know what “the Ownable solution” is.

Quoted 46 lines

This is required by the scatterlist abstractions.

---
rust/bindings/bindings_helper.h | 1 +
rust/kernel/page.rs | 83 ++++++++++++++++++++++++++++++++-

2 files changed, 83 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 84d60635e8a9..0e140e07758b 100644
@@ -57,6 +57,7 @@
 #include <linux/jiffies.h>
 #include <linux/jump_label.h>
 #include <linux/mdio.h>
+#include <linux/mm.h>
 #include <linux/miscdevice.h>
 #include <linux/of_device.h>
 #include <linux/pci.h>
rust/kernel/page.rs +10 -1
index 7c1b17246ed5..bea7f0ab91f4 100644
@@ -9,7 +9,12 @@
    error::Result,
    uaccess::UserSliceReader,
 };
-use core::ptr::{self, NonNull};
+use core::{
+    marker::PhantomData,
+    mem::ManuallyDrop,
+    ops::Deref,
+    ptr::{self, NonNull},
+};
 
 /// A bitwise shift for the page size.
 pub const PAGE_SHIFT: usize = bindings::PAGE_SHIFT as usize;
@@ -30,6 +35,82 @@ pub const fn page_align(addr: usize) -> usize {
    (addr + (PAGE_SIZE - 1)) & 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`].

rust/kernel/page.rs pub const fn page_align(addr: usize) -> usize { · line 51

Quoted 10 lines
rust/kernel/page.rs +10 -0
+///
+/// # Example
+///
+/// ```
+/// # use kernel::{bindings, prelude::*};
+/// use kernel::page::{BorrowedPage, Page, PAGE_SIZE};
+/// # use core::ptr;
+/// # use core::ptr::NonNull;
+///
+/// trait PageOwner {

What is this trait for? Perhaps this assumes some previous discussion that is not in the patch itself?

Quoted 66 lines
rust/kernel/page.rs +62 -0
+///     fn borrow_page<'a>(&'a mut self) -> BorrowedPage<'a>;
+/// }
+///
+/// impl<T> PageOwner for VBox<T> {
+///     // Borrow the first page of a `VBox`.
+///     fn borrow_page<'a>(&'a mut self) -> BorrowedPage<'a> {
+///         let ptr = ptr::from_ref(&**self);
+///
+///         // SAFETY: `ptr` is a valid pointer to `Vmalloc` memory.
+///         let page = unsafe { bindings::vmalloc_to_page(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) };
+///
+///         // 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) }
+///     }
+/// }
+///
+/// let mut vbox = VBox::<[u8; PAGE_SIZE]>::new_uninit(GFP_KERNEL)?;
+/// let page = vbox.borrow_page();
+///
+/// // SAFETY: There is no concurrent read or write to the same page.
+/// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
+/// # Ok::<(), Error>(())
+/// ```
+///
+/// # Invariants
+///
+/// The borrowed underlying pointer to a `struct page` is valid for the entire lifetime `'a`.
+///
+/// [`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)
+    }
+}
+
+impl<'a> Deref for BorrowedPage<'a> {
+    type Target = Page;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
 /// A pointer to a page that owns the page allocation.
 ///
 /// # Invariants
Quoted 5 lines

base-commit: d2eedaa3909be9102d648a4a0a50ccf64f96c54f

Signature · 1 line
2.50.1

The rest of the patch is fine.

— Daniel

author reviewer
#6 lore raw
Quoted 6 lines · Daniel Almeida

Hi Danilo,

Quoted 4 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

Quoted 8 lines
Quoted 5 lines

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

I guess it’s a good idea to expand this part somewhat. Taken as it is, there is no way to know what “the Ownable solution” is.

What do you suggest?

I can link where the type has been proposed by Boqun [1].

[1] https://lore.kernel.org/rust-for-linux/ZnCzLIly3DRK2eab@boqun-archlinux/

Quoted 51 lines
Quoted 51 lines

This is required by the scatterlist abstractions.

---
rust/bindings/bindings_helper.h | 1 +
rust/kernel/page.rs | 83 ++++++++++++++++++++++++++++++++-

2 files changed, 83 insertions(+), 1 deletion(-)
rust/bindings/bindings_helper.h +1 -0
index 84d60635e8a9..0e140e07758b 100644
@@ -57,6 +57,7 @@
 #include <linux/jiffies.h>
 #include <linux/jump_label.h>
 #include <linux/mdio.h>
+#include <linux/mm.h>
 #include <linux/miscdevice.h>
 #include <linux/of_device.h>
 #include <linux/pci.h>
rust/kernel/page.rs +15 -1
index 7c1b17246ed5..bea7f0ab91f4 100644
@@ -9,7 +9,12 @@
    error::Result,
    uaccess::UserSliceReader,
 };
-use core::ptr::{self, NonNull};
+use core::{
+    marker::PhantomData,
+    mem::ManuallyDrop,
+    ops::Deref,
+    ptr::{self, NonNull},
+};
 
 /// A bitwise shift for the page size.
 pub const PAGE_SHIFT: usize = bindings::PAGE_SHIFT as usize;
@@ -30,6 +35,82 @@ pub const fn page_align(addr: usize) -> usize {
    (addr + (PAGE_SIZE - 1)) & 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::*};
Quoted 8 lines

rust/kernel/page.rs pub const fn page_align(addr: usize) -> usize { · line 51

Quoted 5 lines
rust/kernel/page.rs +5 -0
+/// use kernel::page::{BorrowedPage, Page, PAGE_SIZE};
+/// # use core::ptr;
+/// # use core::ptr::NonNull;
+///
+/// trait PageOwner {

What is this trait for? Perhaps this assumes some previous discussion that is not in the patch itself?

It's just example code to show how a BorrowedPage may be obtained from something that owns a page, i.e. a PageOwner.

However, I'm actually working on a trait similar to this example one as well.

author reviewer
#7 lore raw
Quoted 19 lines · Danilo Krummrich
Quoted 9 lines · Daniel Almeida
Quoted 9 lines
rust/kernel/page.rs +9 -0
+/// 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::*};
Quoted 8 lines

rust/kernel/page.rs pub const fn page_align(addr: usize) -> usize { · line 51

Quoted 5 lines
rust/kernel/page.rs +5 -0
+/// use kernel::page::{BorrowedPage, Page, PAGE_SIZE};
+/// # use core::ptr;
+/// # use core::ptr::NonNull;
+///
+/// trait PageOwner {

What is this trait for? Perhaps this assumes some previous discussion that is not in the patch itself?

Quoted 2 lines

It's just example code to show how a BorrowedPage may be obtained from something that owns a page, i.e. a PageOwner.

Maybe let me simplify the example a bit and just use the following function for the example instead of the generic trait approach.

	 fn borrow_first_page<'a>(vbox: &'a mut VBox<MaybeUninit<[u8; PAGE_SIZE]>>) -> BorrowedPage<'a>
#8 lore raw
In reply to Danilo Krummrich
Quoted 17 lines · Danilo Krummrich
Quoted 12 lines · Daniel Almeida

Hi Danilo,

Quoted 9 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

Quoted 8 lines
Quoted 2 lines

I guess it’s a good idea to expand this part somewhat. Taken as it is, there is no way to know what “the Ownable solution” is.

What do you suggest?

I can link where the type has been proposed by Boqun [1].

[1] https://lore.kernel.org/rust-for-linux/ZnCzLIly3DRK2eab@boqun-archlinux/

Just this link is fine IMHO. I wasn’t aware of this discussion.

— Daniel

#9 lore raw
Quoted 18 lines · Daniel Almeida
Quoted 18 lines · Danilo Krummrich
Quoted 14 lines · Daniel Almeida

Hi Danilo,

Quoted 9 lines · Danilo Krummrich

Currently, a Page always owns the underlying struct page.

However, sometimes a struct page may be owned by some other entity, e.g. a vmalloc allocation.

Hence, introduce BorrowedPage to support such cases, until the Ownable solution lands.

I guess it’s a good idea to expand this part somewhat. Taken as it is, there is no way to know what “the Ownable solution” is.

Quoted 8 lines
Quoted 5 lines

What do you suggest?

I can link where the type has been proposed by Boqun [1].

[1] https://lore.kernel.org/rust-for-linux/ZnCzLIly3DRK2eab@boqun-archlinux/

Just this link is fine IMHO. I wasn’t aware of this discussion.

As far as I know, "[PATCH v11 0/4] New trait OwnableRefCounted for ARef<->Owned conversion." [1] is the latest and greatest.

Best regards,
Andreas Hindborg

[1] https://lore.kernel.org/r/[email protected]

author reviewer
#10 lore raw
Quoted 2 lines · Andreas Hindborg

As far as I know, "[PATCH v11 0/4] New trait OwnableRefCounted for ARef<->Owned conversion." [1] is the latest and greatest.

Thanks -- I wasn't aware since myself and other relevant maintainers are not Cc'd.