[PATCH] rust: page: implement BorrowedPage

[PATCH] rust: page: implement BorrowedPage

[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.

Signed-off-by: Danilo Krummrich <dakr@kernel.org>
---
 rust/bindings/bindings_helper.h |  1 +
 rust/kernel/page.rs             | 83 ++++++++++++++++++++++++++++++++-
 2 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index 84d60635e8a9..0e140e07758b 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -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>
diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
index 7c1b17246ed5..bea7f0ab91f4 100644
--- a/rust/kernel/page.rs
+++ b/rust/kernel/page.rs
@@ -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::*};
+/// use kernel::page::{BorrowedPage, Page, PAGE_SIZE};
+/// # use core::ptr;
+/// # use core::ptr::NonNull;
+///
+/// trait PageOwner {
+///     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

base-commit: d2eedaa3909be9102d648a4a0a50ccf64f96c54f
-- 
2.50.1

Re: [PATCH] rust: page: implement BorrowedPage

[Benno Lossin]

On Mon Aug 4, 2025 at 9:50 PM CEST, Danilo Krummrich wrote:
> 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

>
> This is required by the scatterlist abstractions.
>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> ---
>  rust/bindings/bindings_helper.h |  1 +
>  rust/kernel/page.rs             | 83 ++++++++++++++++++++++++++++++++-
>  2 files changed, 83 insertions(+), 1 deletion(-)

Re: [PATCH] rust: page: implement BorrowedPage

[Danilo Krummrich]

On 8/4/25 10:02 PM, Benno Lossin wrote:
> On Mon Aug 4, 2025 at 9:50 PM CEST, Danilo Krummrich wrote:
>> 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.

Re: [PATCH] rust: page: implement BorrowedPage

[Alexandre Courbot]

On Tue Aug 5, 2025 at 4:50 AM JST, Danilo Krummrich wrote:
> 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.
>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

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

Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>

Re: [PATCH] rust: page: implement BorrowedPage

[Alice Ryhl]

On Mon, Aug 4, 2025 at 9:50 PM Danilo Krummrich <dakr@kernel.org> wrote:
>
> 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.
>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

Acked-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH] rust: page: implement BorrowedPage

[Daniel Almeida]

Hi Danilo,

> On 4 Aug 2025, at 16:50, Danilo Krummrich <dakr@kernel.org> wrote:
> 
> 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.


> This is required by the scatterlist abstractions.
> 
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> ---
> rust/bindings/bindings_helper.h |  1 +
> rust/kernel/page.rs             | 83 ++++++++++++++++++++++++++++++++-
> 2 files changed, 83 insertions(+), 1 deletion(-)
> 
> diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
> index 84d60635e8a9..0e140e07758b 100644
> --- a/rust/bindings/bindings_helper.h
> +++ b/rust/bindings/bindings_helper.h
> @@ -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>
> diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
> index 7c1b17246ed5..bea7f0ab91f4 100644
> --- a/rust/kernel/page.rs
> +++ b/rust/kernel/page.rs
> @@ -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::*};
> +/// 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?

> +///     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
> 
> base-commit: d2eedaa3909be9102d648a4a0a50ccf64f96c54f
> -- 
> 2.50.1
> 
> 

The rest of the patch is fine.

— Daniel

Re: [PATCH] rust: page: implement BorrowedPage

[Danilo Krummrich]

On Tue Aug 5, 2025 at 2:30 PM CEST, Daniel Almeida wrote:
> Hi Danilo,
>
>> On 4 Aug 2025, at 16:50, Danilo Krummrich <dakr@kernel.org> wrote:
>> 
>> 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.

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/

>> This is required by the scatterlist abstractions.
>> 
>> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
>> ---
>> rust/bindings/bindings_helper.h |  1 +
>> rust/kernel/page.rs             | 83 ++++++++++++++++++++++++++++++++-
>> 2 files changed, 83 insertions(+), 1 deletion(-)
>> 
>> diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
>> index 84d60635e8a9..0e140e07758b 100644
>> --- a/rust/bindings/bindings_helper.h
>> +++ b/rust/bindings/bindings_helper.h
>> @@ -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>
>> diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
>> index 7c1b17246ed5..bea7f0ab91f4 100644
>> --- a/rust/kernel/page.rs
>> +++ b/rust/kernel/page.rs
>> @@ -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::*};
>> +/// 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.

Re: [PATCH] rust: page: implement BorrowedPage

[Danilo Krummrich]

On Tue Aug 5, 2025 at 2:53 PM CEST, Danilo Krummrich wrote:
> On Tue Aug 5, 2025 at 2:30 PM CEST, Daniel Almeida wrote:
>>> +/// 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::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.

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>

Re: [PATCH] rust: page: implement BorrowedPage

[Daniel Almeida]

> On 5 Aug 2025, at 09:53, Danilo Krummrich <dakr@kernel.org> wrote:
> 
> On Tue Aug 5, 2025 at 2:30 PM CEST, Daniel Almeida wrote:
>> Hi Danilo,
>> 
>>> On 4 Aug 2025, at 16:50, Danilo Krummrich <dakr@kernel.org> wrote:
>>> 
>>> 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.
> 
> 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

Re: [PATCH] rust: page: implement BorrowedPage

[Andreas Hindborg]

"Daniel Almeida" <daniel.almeida@collabora.com> writes:

>> On 5 Aug 2025, at 09:53, Danilo Krummrich <dakr@kernel.org> wrote:
>>
>> On Tue Aug 5, 2025 at 2:30 PM CEST, Daniel Almeida wrote:
>>> Hi Danilo,
>>>
>>>> On 4 Aug 2025, at 16:50, Danilo Krummrich <dakr@kernel.org> wrote:
>>>>
>>>> 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.
>>
>> 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/20250618-unique-ref-v11-0-49eadcdc0aa6@pm.me

Re: [PATCH] rust: page: implement BorrowedPage

[Danilo Krummrich]

On 8/5/25 7:07 PM, Andreas Hindborg wrote:
> 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.