rust: Return Option from page_align and ensure no usize overflow
Subsystems (2)
PATCH v5 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
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(-)
rust/kernel/page.rs +30 -6
@@ -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`]. +/// +/// # Examples +/// +/// ```rust +/// use kernel::page::{page_align, PAGE_SIZE}; +/// // Case 1: Already aligned +/// assert_eq!(page_align(0x0), Some(0x0)); +/// assert_eq!(page_align(PAGE_SIZE), Some(PAGE_SIZE)); +/// +/// // Case 2: Needs alignment up +/// assert_eq!(page_align(0x1), Some(PAGE_SIZE)); +/// assert_eq!(page_align(PAGE_SIZE + 1), Some(2 * PAGE_SIZE)); +/// +/// // 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); +/// +/// // Case 4: Requested address size of `usize::MAX` would overflow, and subsequently returns `None`. +/// assert_eq!(page_align(usize::MAX), 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`].
--
2.51.1
Alice Ryhl
maintainerQuoted 41 lines · Brendan Shephard
Change
page_align()to returnOption<usize>to allow validation of the providedaddrvalue. This ensures that any value that is within onePAGE_SIZEofusize::MAXwill not panic, and instead returnsNoneto indicate overflow.Signed-off-by Brendan Shephard <[email protected]>---
Changes in v2:
- Reworded commit message to follow the imperative form.
- Expanded the documentation to explain theSomeandNonereturn 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/#tChanges 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/#uChanges in v5:
- Use kernelPAGE_SIZEfor all doctest examples
- Backtick the backtickable works in example comment
- Add new example forusize::MAXinput 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(-)rust/kernel/page.rs +0
-0@@ -27,12 +27,36 @@
rust/kernel/page.rs line 31
Quoted 10 lines
rust/kernel/page.rs +2
-6/// 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
Quoted 18 lines · Alice Ryhl
rust/kernel/page.rs line 31
Quoted 10 lines
/// Round up the given number to the next multiple of [
PAGE_SIZE]. ///rust/kernel/page.rs +2
-6-/// 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]. ///
/// ReturnsNoneon integer overflow.
Quoted 8 lines
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
Seems reasonable, v6 sent with this adjustment:
https://lore.kernel.org/rust-for-linux/aS6y5blasMX0KcD7@fedora/T/#u
Thanks!
Brendan