rust: Return Option from page_align and ensure no usize overflow
Subsystems (2)
PATCH v8 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(-)
Changes in v7:
- Addressed nits by Reviewer Alexandre Courbot
- Link to v6: https://lore.kernel.org/rust-for-linux/[email protected]/#R
Changes in v8:
- Consistent periods at end of sentences
- Removed unnecessary tests and comments
- Link to v7: https://lore.kernel.org/rust-for-linux/[email protected]/
rust/kernel/page.rs | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-)
rust/kernel/page.rs +26 -7
@@ -25,14 +25,33 @@/// 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 +/// +/// ``` +/// use kernel::page::{page_align, PAGE_SIZE}; +/// +/// // Requested address is already aligned. +/// assert_eq!(page_align(0x0), Some(0x0)); +/// assert_eq!(page_align(PAGE_SIZE), Some(PAGE_SIZE)); +/// +/// // Requested address needs alignment up. +/// assert_eq!(page_align(0x1), Some(PAGE_SIZE)); +/// assert_eq!(page_align(PAGE_SIZE + 1), Some(2 * PAGE_SIZE)); +/// +/// // Requested address causes overflow (returns None). +/// 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: e6640487845061255af9614ec0a192e4fafa486e
Signature · 1 line
2.51.1
Danilo Krummrich
reviewerQuoted 9 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 Alice Ryhl <[email protected]>Reviewed-by Alexandre Courbot <[email protected]>Reviewed-by Daniel Almeida <[email protected]>
Alice, unless you have any concerns I'd take this through the drm-rust tree, so I can pick up the corresponding nova-drm patch as well.
Alice Ryhl
maintainerQuoted 7 lines · Danilo Krummrich
Quoted 5 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.
Quoted 7 lines
Quoted 4 lines
Signed-off-by Brendan Shephard <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Reviewed-by Alexandre Courbot <[email protected]>Reviewed-by Daniel Almeida <[email protected]>Alice, unless you have any concerns I'd take this through the drm-rust tree, so I can pick up the corresponding nova-drm patch as well.
Sounds good to me.
Quoted 10 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 Alice Ryhl <[email protected]>Reviewed-by Alexandre Courbot <[email protected]>Reviewed-by Daniel Almeida <[email protected]>
Looks good, thanks for having added the examples and going through all the feedback -- welcome!
Quoted 1 line
+/// // Requested address causes overflow (returns None).
None
rust/kernel/page.rs line 47
Quoted 2 lines
rust/kernel/page.rs +2
-0+/// let overflow_addr = usize::MAX - (PAGE_SIZE / 2); +/// assert_eq!(page_align(overflow_addr), None);
I still think this could eventually just test the top address more easily (and then the extra line we gain could be used to test a one plus the previous page), but it is fine as it is, let's merge it as-is :)
Thanks!
Cheers,
Miguel
Quoted 9 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 Alice Ryhl <[email protected]>Reviewed-by Alexandre Courbot <[email protected]>Reviewed-by Daniel Almeida <[email protected]>
Applied to drm-rust-next, thanks!
[ Use kernel vertical style for imports; use markdown in comments.
- Danilo ]
Brendan, can you please send a follow-up patch addressing [1] and [2]?
[1] https://lore.kernel.org/all/CANiq72kcMLXz=xyZeKC0=j_e0BzJEY3wGpBTTxfJsc6EZhCnXA@mail.gmail.com/
[2] https://lore.kernel.org/rust-for-linux/CANiq72mLPvB_6Ow3bW5-V4-km=RyA59chQ1g1x9qUt2P-zZweg@mail.gmail.com/
Quoted 13 lines · Danilo Krummrich
Quoted 9 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 Alice Ryhl <[email protected]>Reviewed-by Alexandre Courbot <[email protected]>Reviewed-by Daniel Almeida <[email protected]>Applied to drm-rust-next, thanks!
Quoted 8 lines
[ Use kernel vertical style for imports; use markdown in comments.
- Danilo ]Brendan, can you please send a follow-up patch addressing [1] and [2]?
[1] https://lore.kernel.org/all/CANiq72kcMLXz=xyZeKC0=j_e0BzJEY3wGpBTTxfJsc6EZhCnXA@mail.gmail.com/
[2] https://lore.kernel.org/rust-for-linux/CANiq72mLPvB_6Ow3bW5-V4-km=RyA59chQ1g1x9qUt2P-zZweg@mail.gmail.com/
Hey Danilo,
Thanks! I can indeed send a follow-up to address those.
Cheers,
Brendan