Struct BorrowedPage

pub struct BorrowedPage<'a>(/* private fields */);

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::page::{BorrowedPage, Page, PAGE_SIZE};

fn borrow_page<'a>(vbox: &'a mut VBox<MaybeUninit<[u8; PAGE_SIZE]>>) -> BorrowedPage<'a> {
    let ptr = ptr::from_ref(&**vbox);

    // 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 = borrow_page(&mut vbox);

// SAFETY: There is no concurrent read or write to this page.
unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };

Invariants

The borrowed underlying pointer to a struct page is valid for the entire lifetime 'a.

Implementations

impl<'a> BorrowedPage<'a>

pub unsafe fn from_raw(ptr: NonNull<page>) -> Self

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.

Methods from Deref<Target = Page>

pub fn as_ptr(&self) -> *mut page

Returns a raw pointer to the page.

pub unsafe fn read_raw(&self, dst: *mut u8, offset: usize, len: usize) -> Result

Maps the page and reads from it into the given buffer.

This method will perform bounds checks on the page offset. If offset .. offset+len goes outside of the page, then this call returns EINVAL.

Safety

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

pub unsafe fn write_raw( &self, src: *const u8, offset: usize, len: usize, ) -> Result

Maps the page and writes into it from the given buffer.

This method will perform bounds checks on the page offset. If offset .. offset+len goes outside of the page, then this call returns EINVAL.

Safety

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

pub unsafe fn fill_zero_raw(&self, offset: usize, len: usize) -> Result

Maps the page and zeroes the given slice.

This method will perform bounds checks on the page offset. If offset .. offset+len goes outside of the page, then this call returns EINVAL.

Safety

Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write.

pub unsafe fn copy_from_user_slice_raw( &self, reader: &mut UserSliceReader, offset: usize, len: usize, ) -> Result

Copies data from userspace into this page.

This method will perform bounds checks on the page offset. If offset .. offset+len goes outside of the page, then this call returns EINVAL.

Like the other UserSliceReader methods, data races are allowed on the userspace address. However, they are not allowed on the page you are copying into.

Safety

Callers must ensure that this call does not race with a read or write to the same page that overlaps with this write.

Trait Implementations

impl<'a> Deref for BorrowedPage<'a>

type Target = Page

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.