rust: Return Option from page_align and ensure no usize overflow
Subsystems (2)
PATCH v6 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 words 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
Changes in v6:
- Simplified Doc text
- Link to v5: https://lore.kernel.org/rust-for-linux/[email protected]/T/#t
rust/kernel/page.rs | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-)
rust/kernel/page.rs +30 -7
@@ -25,14 +25,37 @@/// A bitmask that gives the page containing a given address. pub const PAGE_MASK :usize = !(PAGE_SIZE -1 ); -/// Round up the given number to the next multiple of [`PAGE_SIZE`]. +/// Rounds up 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 [`None`] on integer overflow. +/// +/// # 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
Quoted 6 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]>
Quoted 6 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]>
A few nits below.
Quoted 45 lines
---
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 words 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/#tChanges in v6:
- Simplified Doc text
- Link to v5: https://lore.kernel.org/rust-for-linux/[email protected]/T/#trust/kernel/page.rs | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-)rust/kernel/page.rs +1
-2@@ -25,14 +25,37 @@/// A bitmask that gives the page containing a given address. pub const PAGE_MASK :usize = !(PAGE_SIZE -1 ); -/// Round up the given number to the next multiple of [`PAGE_SIZE`]. +/// Rounds up 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
rust/kernel/page.rs line 34
Quoted 10 lines
rust/kernel/page.rs +5
-5-/// [`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 [`None`] on integer overflow. +/// +/// # Examples +/// +/// ```rust
I never see the language specified in other doctests. I guess it doesn't hurt, but just mentioning it for consistency.
rust/kernel/page.rs line 36
Quoted 2 lines
rust/kernel/page.rs +2
-0+/// use kernel::page::{page_align, PAGE_SIZE}; +/// // Case 1: Already aligned
Why number the examples? It doesn't add anything since we don't refer to them later.
Quoted 12 lines · Alexandre Courbot
Quoted 6 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]>Reviewed-by Alexandre Courbot <[email protected]>A few nits below.
Quoted 9 lines
rust/kernel/page.rs line 34
Quoted 5 lines
rust/kernel/page.rs +5
-0+/// Returns [`None`] on integer overflow. +/// +/// # Examples +/// +/// ```rust I never see the language specified in other doctests. I guess it doesn't hurt, but just mentioning it for consistency.
Fair, I just took this from the example on the rustdocs page:
https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html
And I didn't give it much additional thought. But I probably should have confirmed formatting of other examples in the project.
Quoted 6 lines
rust/kernel/page.rs line 36
Quoted 2 lines
rust/kernel/page.rs +2
-0+/// use kernel::page::{page_align, PAGE_SIZE}; +/// // Case 1: Already aligned Why number the examples? It doesn't add anything since we don't refer to them later.
Another valid point. I think a common theme in my reviews is that I'm being a bit too verbose. Most of it, like in this case comes from my own internal monologue while I'm figuring it out. I'll take that on-board and try to be more INFO and less DEBUG moving forward.