Add the page kind `Frozen`. A `Page` is a frozen page that is uniquely owned through an `Owned>`. 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`, a `Page` 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`, and let `Page` dereference to `Page`. Signed-off-by: Andreas Hindborg --- 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` is a page for which nothing is known beyond its validity. /// - `Page`, or just `Page`, is a page that is managed by the page reference count. +/// - `Page` is a uniquely owned page that references cannot be taken to. /// - `Page` 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) { // non-zero and it is okay to obtain an `ARef` 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`] is accessed through an owning [`Owned>`], and the page is freed +/// when the [`Owned>`] is dropped. +/// +/// Unlike for a [`Page`], nothing is known about who accesses the data of a +/// [`Page`]. 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`]: +/// +/// - 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`] exists. +/// - The page is owned by a unique [`Owned>`]. No references to the page exist +/// together with the [`Owned>`], other than the ones borrowed from it. +pub struct Frozen; + +impl private::Sealed for Frozen {} +impl PageKind for Frozen {} + +impl Deref for Page { + type Target = Page; + + #[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 { + /// 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, 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` 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` and `Pin<&mut Page>`. + // - 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 { + #[inline] + unsafe fn release(this: NonNull) { + // 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`] is accessed through an owning [`Owned>`]. It has the same -- 2.54.0