The data of a `Page` is initialized and is not referenced by Rust references, so it can be accessed safely with byte-wise atomic operations. The existing accessors of `Page` are available for all page kinds and are thus unsafe: a write can alias a slice obtained from a `Page`. Add the safe method `Page::with_page_as_sysmem_local()` for `Page`. It maps a range of the page and passes it to a closure as a `SysMemLocal` view. The view is not `Send`, since the mapping that backs it can be local to the current task. A `Page` does not dereference to a `Page`, so the method is not available for it. Signed-off-by: Andreas Hindborg --- rust/kernel/page.rs | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 85 insertions(+), 4 deletions(-) diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs index 85c710fa3dfd..7fa037f5938b 100644 --- a/rust/kernel/page.rs +++ b/rust/kernel/page.rs @@ -20,7 +20,8 @@ Io, IoCopyable, SysMem, - SysMemBackend, // + SysMemBackend, + SysMemLocal, // }, sync::aref::{ self, @@ -132,6 +133,8 @@ impl PageKind for Base {} /// /// The data of a [`Page`] can be accessed concurrently by other parties, such as user /// space, devices or other kernel code. Thus, no Rust reference to the data of the page exists. +/// The data is accessed with volatile or byte-wise atomic operations through a [`SysMemLocal`], +/// see [`Page::with_page_as_sysmem_local`]. /// /// A [`Page`] and a [`Page`] dereference to a [`Page`]. A page that /// is managed by other means can be referenced as a [`Page`] with [`Page::from_raw`]. @@ -374,13 +377,14 @@ fn with_pointer_into_page( /// Runs a piece of code with a range of this page mapped as a [`SysMem`] view. /// /// If `f` is called, then it is called with a view of the `len` bytes of the page that start - /// at `offset`. Accesses through the view are volatile or byte-wise atomic, so the view is - /// suitable for a page whose data is subject to concurrent writes by hardware or user space. - /// The view is valid for the duration of the call to `f`. + /// at `offset`. The view is valid for the duration of the call to `f`. /// /// If `offset` and `len` refer to a region outside of this page, then this method returns /// [`EINVAL`] and does not call `f`. /// + /// This is the building block for the accessors of [`Page`]. Use + /// [`Page::with_page_as_sysmem_local`] for safe access to the data of a [`Page`]. + /// /// # Safety /// /// * Callers must ensure that no plain access to the mapped range races with an access @@ -658,6 +662,83 @@ pub unsafe fn copy_from_user_slice_raw( } } +impl Page { + /// Runs a piece of code with a range of this page mapped as a [`SysMemLocal`] view. + /// + /// If `f` is called, then it is called with a view of the `len` bytes of the page that start + /// at `offset`. Accesses through the view are volatile or byte-wise atomic, so the view is + /// suitable for a page whose data is subject to concurrent accesses by hardware, by user space + /// or by other kernel code. When an access races with a write, the data observed may be + /// arbitrary. The view is valid for the duration of the call to `f`. + /// + /// The view is not [`Send`], as it can be backed by a mapping that is local to the current + /// task. + /// + /// If `offset` and `len` refer to a region outside of this page, then this method returns + /// [`EINVAL`] and does not call `f`. + /// + /// This method is not available for a [`Page`], as writing through the view would + /// violate the aliasing rules for the slices returned by [`Page::as_slice`] and + /// [`Page::as_mut_slice`]. + /// + /// # Examples + /// + /// ``` + /// use kernel::{ + /// io::Io, + /// page::Page, // + /// }; + /// + /// let page = Page::alloc_page(GFP_KERNEL)?; + /// let mut buf = [0xffu8; 4]; + /// + /// page.with_page_as_sysmem_local(8, 4, |view| { + /// view.copy_to_slice(&mut buf); + /// assert_eq!(buf, [0u8; 4]); + /// + /// view.copy_from_slice(&[1, 2, 3, 4]); + /// view.copy_to_slice(&mut buf); + /// assert_eq!(buf, [1, 2, 3, 4]); + /// + /// view.fill_zero(); + /// view.copy_to_slice(&mut buf); + /// assert_eq!(buf, [0u8; 4]); + /// Ok(()) + /// })?; + /// # Ok::<(), Error>(()) + /// ``` + /// + /// Copy data from user space to a page: + /// + /// ``` + /// use kernel::{ + /// page::Page, + /// uaccess::UserSliceReader, // + /// }; + /// + /// fn copy_to_page(page: &Page, reader: &mut UserSliceReader, len: usize) -> Result { + /// page.with_page_as_sysmem_local(0, len, |view| reader.read_sysmem(view)) + /// } + /// ``` + pub fn with_page_as_sysmem_local( + &self, + offset: usize, + len: usize, + f: impl FnOnce(SysMemLocal<'_, [u8]>) -> Result, + ) -> Result { + let f = move |mem: SysMem<'_, [u8]>| f(SysMemLocal::from(mem)); + + // SAFETY: + // - By the type invariant of `Page`, no plain access to the data of the page races + // with another access, and no Rust reference to the data of the page exists. + // - Safe code can only write initialized bytes through a `SysMemLocal`. + // - `f` converts the view to a `SysMemLocal` before it is used. A `SysMemLocal` is not + // `Send` and it cannot outlive the call to `f`, so the view is only used on the current + // task. + unsafe { self.with_page_as_sysmem(offset, len, f) } + } +} + // SAFETY: By the type invariant, a `Page` is managed by the page reference count. // Incrementing it via `get_page()` keeps the page alive at least until a matching `put_page()`, // which frees the page when the count reaches zero. -- 2.54.0