Re: [PATCH v5] rust: Return Option from page_align and ensure no usize overflow

[Alice Ryhl <aliceryhl@google.com>]

On Mon, Dec 01, 2025 at 03:45:52PM +1000, Brendan Shephard wrote:
> 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.
> 
> Signed-off-by: Brendan Shephard <bshephar@bne-home.net>
> ---
> 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
> 
> Changes 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.
> 
> Changes in v4:
> - Fix rustdoc missing comment (//) prefix
> - Rebase on master
> - Link to v3: https://lore.kernel.org/rust-for-linux/aSoY31U3uDI2y7V1@fedora/T/#u
> 
> Changes in v5:
> - Use kernel `PAGE_SIZE` for all doctest examples
> - Backtick the backtickable works in example comment
> - Add new example for `usize::MAX` input value
> - Newline before # Examples
> - Link to v4: https://lore.kernel.org/rust-for-linux/aSzDj1htLp11eCWF@fedora/T/#t
> 
> rust/kernel/page.rs | 36 ++++++++++++++++++++++++++++++------
>  1 file changed, 30 insertions(+), 6 deletions(-)
> 
> diff --git a/rust/kernel/page.rs b/rust/kernel/page.rs
> index 432fc0297d4a..4a0cfa32a5d6 100644
> --- a/rust/kernel/page.rs
> +++ b/rust/kernel/page.rs
> @@ -27,12 +27,36 @@
> 
>  /// 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`].

The first line of doc-comments is shown on the module docs. I think it'd
be nice to shorten the first line.

/// Rounds up to the next multiple of [`PAGE_SIZE`].
///
/// Returns `None` on integer overflow.

People reading the module docs will get what they need from "Rounds up
to the next multiple of PAGE_SIZE.", and if they want to know details
such as overflow behavior they can read the page specific to this
method.

Alice