rust: Return Option from page_align and ensure no usize overflow
Subsystems (2)
PATCH v3 1/1 rust: Return Option from page_align and ensure no usize overflow
Change page_align() to return Option<usize> to allow validation of the provided addr value. This ensures that any value that is within one PAGE_SIZE of usize::MAX will not panic, and instead returns None to indicate overflow.
---
Changes in v2:
- Reworded commit message to follow the imperative form.
- Expanded the documentation to explain the Some and None return cases.
- Added a period at the end of the documentation comment.
- Link to v1 (and v2): https://lore.kernel.org/rust-for-linux/aSheTh-T1oroAUHR@fedora/T/#t
Changs in v3:
- Fix documentation layout for better rustdoc rendering
- Add doc examples and doctest
- Ensure function is always inlined for performance optimisation
- Restructure function so that early return is the None case and the default is the happy path.
rust/kernel/page.rs | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-)
rust/kernel/page.rs +28 -6
@@ -27,12 +27,34 @@/// Round up the given number to the next multiple of [`PAGE_SIZE`]. /// -/// It is incorrect to pass an address where the next multiple of [`PAGE_SIZE`] doesn't fit in a -/// [`usize`]. -pub const fn page_align (addr:usize ) ->usize { -// Parentheses around `PAGE_SIZE - 1` to avoid triggering overflow sanitizers in the wrong -// cases. - (addr + (PAGE_SIZE -1 )) &PAGE_MASK +/// Returns a page aligned [`usize`] in cases where the value can be aligned. Otherwise, returns `None` +/// if the aligned size will overflow a [`usize`]. +/// # Examples +/// +/// Assuming a `PAGE_SIZE` of 4096 (0x1000): +/// +/// ```rust +/// use kernel::page::{page_align, PAGE_SIZE}; +/// // Case 1: Already aligned +/// assert_eq!(page_align(0x0), Some(0x0)); +/// assert_eq!(page_align(0x1000), Some(0x1000)); +/// +/// // Case 2: Needs alignment up +/// assert_eq!(page_align(0x1), Some(0x1000)); +/// assert_eq!(page_align(0x1001), Some(0x2000)); +/// +/// // Case 3: Requested address causes overflow (returns None) +/// // The check asserts that None is returned when a value is requested within one PAGE_SIZE of +/// usize::MAX. +/// let overflow_addr = usize::MAX - (PAGE_SIZE / 2); +/// assert_eq!(page_align(overflow_addr), None); +/// ``` +#[inline(always)] +pub const fn page_align (addr:usize ) ->Option <usize > { +let Some (sum) = addr.checked_add (PAGE_SIZE -1 )else { +return None ; + }; +Some (sum &PAGE_MASK ) }/// Representation of a non-owning reference to a [`Page`].
base-commit: 765e56e41a5af2d456ddda6cbd617b9d3295ab4e --
2.51.1