1 // SPDX-License-Identifier: GPL-2.0
3 //! Kernel page allocation and management.
14 /// A bitwise shift for the page size.
17 /// The number of bytes in a page.
20 /// A bitmask that gives the page containing a given address.
21 pub const PAGE_MASK: usize = !(PAGE_SIZE - 1);
23 /// A pointer to a page that owns the page allocation.
27 /// The pointer is valid, and has ownership over the page.
28 pub struct Page {  struct
29     page: NonNull<bindings::page>,  field
34 unsafe impl Send for Page {}  implementation
38 unsafe impl Sync for Page {}  implementation
40 impl Page {  impl
41     /// Allocates a new page.
45     /// Allocate memory for a page.
48     /// use kernel::page::Page;
50     /// # fn dox() -> Result<(), kernel::alloc::AllocError> {
51     /// let page = Page::alloc_page(GFP_KERNEL)?;
55     /// Allocate memory for a page and zero its contents.
58     /// use kernel::page::Page;
60     /// # fn dox() -> Result<(), kernel::alloc::AllocError> {
61     /// let page = Page::alloc_page(GFP_KERNEL | __GFP_ZERO)?;
64     pub fn alloc_page(flags: Flags) -> Result<Self, AllocError> {  in alloc_page()
67         let page = unsafe { bindings::alloc_pages(flags.as_raw(), 0) };  in alloc_page()  localVariable
68         let page = NonNull::new(page).ok_or(AllocError)?;  in alloc_page()  localVariable
69         // INVARIANT: We just successfully allocated a page, so we now have ownership of the newly  in alloc_page()
70         // allocated page. We transfer that ownership to the new `Page` object.  in alloc_page()
71         Ok(Self { page })  in alloc_page()
74     /// Returns a raw pointer to the page.
75     pub fn as_ptr(&self) -> *mut bindings::page {  in as_ptr()  argument
76         self.page.as_ptr()  in as_ptr()
79     /// Runs a piece of code with this page mapped to an address.
81     /// The page is unmapped when this call returns.
91     /// If multiple threads map the same page at the same time, then they may reference with
95     fn with_page_mapped<T>(&self, f: impl FnOnce(*mut u8) -> T) -> T {  in with_page_mapped()
96         // SAFETY: `page` is valid due to the type invariants on `Page`.  in with_page_mapped()
101         // This unmaps the page mapped above.  in with_page_mapped()
106         // In other words, if this call to `kunmap_local` happens when a different page should be  in with_page_mapped()
115     /// Runs a piece of code with a raw pointer to a slice of this page, with bounds checking.
118     /// page, and the pointer will be valid for at least `len` bytes. The pointer is only valid on
121     /// If `off` and `len` refers to a region outside of this page, then this method returns
132     /// If multiple threads map the same page at the same time, then they may reference with
140         f: impl FnOnce(*mut u8) -> Result<T>,  in with_pointer_into_page()
141     ) -> Result<T> {  in with_pointer_into_page()
146                 // SAFETY: The `off` integer is at most `PAGE_SIZE`, so this pointer offset will  in with_pointer_into_page()
147                 // result in a pointer that is in bounds or one off the end of the page.  in with_pointer_into_page()
155     /// Maps the page and reads from it into the given buffer.
157     /// This method will perform bounds checks on the page offset. If `offset .. offset+len` goes
158     /// outside of the page, then this call returns [`EINVAL`].
163     /// * Callers must ensure that this call does not race with a write to the same page that
165     pub unsafe fn read_raw(&self, dst: *mut u8, offset: usize, len: usize) -> Result {  in read_raw()
166         self.with_pointer_into_page(offset, len, move |src| {  in read_raw()
177     /// Maps the page and writes into it from the given buffer.
179     /// This method will perform bounds checks on the page offset. If `offset .. offset+len` goes
180     /// outside of the page, then this call returns [`EINVAL`].
185     /// * Callers must ensure that this call does not race with a read or write to the same page
187     pub unsafe fn write_raw(&self, src: *const u8, offset: usize, len: usize) -> Result {  in write_raw()
188         self.with_pointer_into_page(offset, len, move |dst| {  in write_raw()
198     /// Maps the page and zeroes the given slice.
200     /// This method will perform bounds checks on the page offset. If `offset .. offset+len` goes
201     /// outside of the page, then this call returns [`EINVAL`].
205     /// Callers must ensure that this call does not race with a read or write to the same page that
207     pub unsafe fn fill_zero_raw(&self, offset: usize, len: usize) -> Result {  in fill_zero_raw()
208         self.with_pointer_into_page(offset, len, move |dst| {  in fill_zero_raw()
218     /// Copies data from userspace into this page.
220     /// This method will perform bounds checks on the page offset. If `offset .. offset+len` goes
221     /// outside of the page, then this call returns [`EINVAL`].
224     /// However, they are not allowed on the page you are copying into.
228     /// Callers must ensure that this call does not race with a read or write to the same page that
233         offset: usize,  in copy_from_user_slice_raw()
235     ) -> Result {  in copy_from_user_slice_raw()
236         self.with_pointer_into_page(offset, len, move |dst| {  in copy_from_user_slice_raw()
245 impl Drop for Page {  implementation
247         // SAFETY: By the type invariants, we have ownership of the page and can free it.  in drop()
248         unsafe { bindings::__free_pages(self.page.as_ptr(), 0) };  in drop()