Skip to contentSkip to conversation

rust: Return Option from page_align and ensure no usize overflow

PATCH Superseded Brendan Shephard 3 participants 4 messages Dec 2, 2025 – Dec 4, 2025

Subsystems (2)

v6 of 8 Superseded Latest is v8 →

lore
Share & tools
lore
#0 lore raw

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
index 432fc0297d4a..ac554aaee2d4 100644
@@ -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

reviewer Reviewed-by on v6 1/1
#2 lore raw
In reply to Brendan Shephard
Quoted 6 lines · Brendan Shephard

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.

A few nits below.

Quoted 45 lines

---
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 +1 -2
index 432fc0297d4a..ac554aaee2d4 100644
@@ -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.

#3 lore raw
Quoted 12 lines · Alexandre Courbot
Quoted 6 lines · Brendan Shephard

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.

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.