rust: Return Option from page_align and ensure no usize overflow
Subsystems (2)
PATCH 1/1 rust: Return Option from page_align and ensure no usize overflow
Changed page_align() to return Option<usize> which allows for validation of the provided addr value. This ensures that any value that is provided within one PAGE_SIZE of usize::MAX will not panic and instead page_align will return None.
Callers of page_align() should raise a EINVAL when they receive None from page_align().
--- rust/kernel/page.rs | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-)
rust/kernel/page.rs +6 -7
@@ -26,13 +26,12 @@pub const PAGE_MASK :usize = !(PAGE_SIZE -1 );/// 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 +/// Return None in cases where the next multiple of [`PAGE_SIZE`] would overflow a [`usize`] +pub const fn page_align (addr:usize ) ->Option <usize > { +if let Some (sum) = addr.checked_add (PAGE_SIZE -1 ) { +return Some (sum &PAGE_MASK ); + } +None }/// Representation of a non-owning reference to a [`Page`].
--
2.51.1
Alexandre Courbot
reviewerQuoted 1 line · Brendan Shephard
Changed
page_align()to return Option<usize> which allows for validation
Please use imperative style as per the patch submission guidelines:
"Change page_align() ...".
https://docs.kernel.org/process/submitting-patches.html
Quoted 6 lines
of the provided addr value. This ensures that any value that is provided within one
PAGE_SIZEofusize::MAXwill not panic and insteadpage_alignwill return None.Callers of
page_align()should raise a EINVAL when they receive None frompage_align().
Callers will return the error that is relevant to them. :) This sentence is not needed.
Quoted 12 lines
Signed-off-by Brendan Shephard <[email protected]>--- rust/kernel/page.rs | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-)rust/kernel/page.rs +0
-0@@ -26,13 +26,12 @@pub const PAGE_MASK :usize = !(PAGE_SIZE -1 );
rust/kernel/page.rs line 29
Quoted 10 lines
rust/kernel/page.rs +1
-7/// 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 +/// Return None in cases where the next multiple of [`PAGE_SIZE`] would overflow a [`usize`]
You can doclink to [None].
Nit: dot at end of sentence missing.
rust/kernel/page.rs line 34
Quoted 5 lines
rust/kernel/page.rs +5
-0+pub const fn page_align (addr:usize ) ->Option <usize > { +if let Some (sum) = addr.checked_add (PAGE_SIZE -1 ) { +return Some (sum &PAGE_MASK ); + } +None
A more idiomatic way to do this:
addr.checked_add(PAGE_SIZE - 1).map(|sum| sum & PAGE_MASK)
Quoted 5 lines · Brendan Shephard
Changed
page_align()to return Option<usize> which allows for validation
nit: imperative voice here
Quoted 17 lines
of the provided addr value. This ensures that any value that is provided within one
PAGE_SIZEofusize::MAXwill not panic and insteadpage_alignwill return None.Callers of
page_align()should raise a EINVAL when they receive None frompage_align().Signed-off-by Brendan Shephard <[email protected]>---
rust/kernel/page.rs| 13 ++++++-------1 file changed, 6 insertions(+), 7 deletions(-)rust/kernel/page.rs +0
-0
rust/kernel/page.rs line 31
Quoted 6 lines
rust/kernel/page.rs +0
-3@@ -26,13 +26,12 @@pub const PAGE_MASK :usize = !(PAGE_SIZE -1 );/// 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`].
Can you document the return value? I’d find it weird that this returns Option otherwise.
Quoted 14 lines
rust/kernel/page.rs +6
-5-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 +/// Return None in cases where the next multiple of [`PAGE_SIZE`] would overflow a [`usize`] +pub const fn page_align (addr:usize ) ->Option <usize > { +if let Some (sum) = addr.checked_add (PAGE_SIZE -1 ) { +return Some (sum &PAGE_MASK ); + } +None }/// Representation of a non-owning reference to a [`Page`]. --
Quoted 2 lines
2.51.1
With the change above:
Quoted 8 lines · Alexandre Courbot
Quoted 1 line · Brendan Shephard
Changed
page_align()to return Option<usize> which allows for validationPlease use imperative style as per the patch submission guidelines:
"Changepage_align()...".
Eh, my bad. Yeah, I'll fix that in v2.
Quoted 10 lines
Quoted 6 lines
of the provided addr value. This ensures that any value that is provided within one
PAGE_SIZEofusize::MAXwill not panic and insteadpage_alignwill return None.Callers of
page_align()should raise a EINVAL when they receive None frompage_align().Callers will return the error that is relevant to them. :) This sentence is not needed.
Ack, I'll remove that part.
Quoted 25 lines
Quoted 12 lines
Signed-off-by Brendan Shephard <[email protected]>--- rust/kernel/page.rs | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-)rust/kernel/page.rs +0
-0@@ -26,13 +26,12 @@pub const PAGE_MASK :usize = !(PAGE_SIZE -1 );rust/kernel/page.rs line 29
Quoted 10 lines
rust/kernel/page.rs +1
-7/// 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 +/// Return None in cases where the next multiple of [`PAGE_SIZE`] would overflow a [`usize`] You can doclink to [
None].
Quoted 2 lines
Nit: dot at end of sentence missing.
Will fix this in v2
Quoted 11 lines
rust/kernel/page.rs line 34
Quoted 5 lines
rust/kernel/page.rs +5
-0+pub const fn page_align (addr:usize ) ->Option <usize > { +if let Some (sum) = addr.checked_add (PAGE_SIZE -1 ) { +return Some (sum &PAGE_MASK ); + } +None A more idiomatic way to do this:
addr.checked_add(PAGE_SIZE - 1).map(|sum| sum &PAGE_MASK)
That would be nice, but alas since this is a const fn, we can't use map here. I assume that was done for optimisation to ensure this could be referenced at compile time. So I'm not sure we want to remove that optimisation here.
Quoted 8 lines · Daniel Almeida
Quoted 5 lines · Brendan Shephard
Changed
page_align()to return Option<usize> which allows for validationnit: imperative voice here
Yeah, my bad. I'll fix that in v2.
Quoted 19 lines
Quoted 19 lines
of the provided addr value. This ensures that any value that is provided within one
PAGE_SIZEofusize::MAXwill not panic and insteadpage_alignwill return None.Callers of
page_align()should raise a EINVAL when they receive None frompage_align().Signed-off-by Brendan Shephard <[email protected]>---
rust/kernel/page.rs| 13 ++++++-------1 file changed, 6 insertions(+), 7 deletions(-)rust/kernel/page.rs +0
-0@@ -26,13 +26,12 @@pub const PAGE_MASK :usize = !(PAGE_SIZE -1 );
Quoted 7 lines
rust/kernel/page.rs line 31
Quoted 4 lines
rust/kernel/page.rs +0
-3/// 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`]. Can you document the return value? I’d find it weird that this returns Option otherwise.
Sounds like a good plan. I'll document both return Options in v2. None if the resulting value would overflow a usize::MAX, or Some usize that is page aligned.
Quoted 21 lines
Quoted 14 lines
rust/kernel/page.rs +6
-5-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 +/// Return None in cases where the next multiple of [`PAGE_SIZE`] would overflow a [`usize`] +pub const fn page_align (addr:usize ) ->Option <usize > { +if let Some (sum) = addr.checked_add (PAGE_SIZE -1 ) { +return Some (sum &PAGE_MASK ); + } +None }/// Representation of a non-owning reference to a [`Page`]. --Quoted 2 lines
2.51.1
With the change above:
Reviewed-by Daniel Almeida <[email protected]>
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.
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.
--- rust/kernel/page.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)
rust/kernel/page.rs +7 -7
@@ -26,13 +26,13 @@pub const PAGE_MASK :usize = !(PAGE_SIZE -1 );/// 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 +/// Return Some [`usize`] that is page aligned. Or None in cases where the next multiple of +/// [`PAGE_SIZE`] would overflow a [`usize`]. +pub const fn page_align (addr:usize ) ->Option <usize > { +if let Some (sum) = addr.checked_add (PAGE_SIZE -1 ) { +return Some (sum &PAGE_MASK ); + } +None }/// Representation of a non-owning reference to a [`Page`].
Signature · 1 line
2.51.1
Quoted 5 lines · Brendan Shephard
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.
This shouldn't be in the commit message. It should instead be placed below the first --- line (the one below the Signed-off-by).
Also, I would recommend not replying to the previous version but starting a new thread instead (it is good to provide a lore.kernel.org to the previous version in the change log).
In addition, if possible, it is nice to use --base to tell Git to provide the base commit.
rust/kernel/page.rs line 30
Quoted 2 lines
rust/kernel/page.rs +2
-0+/// Return Some [`usize`] that is page aligned. Or None in cases where the next multiple of +/// [`PAGE_SIZE`] would overflow a [`usize`].
Missing intra-doc link (this was feedback in v1). In addition, this reads a bit strangely, and it looks like the first line of the description wasn't removed? That would make the "short description" (the first paragraph) quite long. Please generate the docs to see if it looks good when generated.
More importantly, please add some examples (doctests). They are tested as KUnit tests automatically. For new APIs, we always try to do add examples, and in cases where there are edge cases like here, it clarifies quite a bit, i.e. please provide a representative example of the Some case and the None case.
Thanks!
Cheers,
Miguel
Alexandre Courbot
reviewerQuoted 60 lines · Brendan Shephard
Quoted 8 lines · Alexandre Courbot
Quoted 1 line · Brendan Shephard
Changed
page_align()to return Option<usize> which allows for validationPlease use imperative style as per the patch submission guidelines:
"Changepage_align()...".Eh, my bad. Yeah, I'll fix that in v2.
Quoted 10 lines
Quoted 6 lines
of the provided addr value. This ensures that any value that is provided within one
PAGE_SIZEofusize::MAXwill not panic and insteadpage_alignwill return None.Callers of
page_align()should raise a EINVAL when they receive None frompage_align().Callers will return the error that is relevant to them. :) This sentence is not needed.
Ack, I'll remove that part.
Quoted 25 lines
Quoted 12 lines
Signed-off-by Brendan Shephard <[email protected]>--- rust/kernel/page.rs | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-)rust/kernel/page.rs +0
-0@@ -26,13 +26,12 @@pub const PAGE_MASK :usize = !(PAGE_SIZE -1 );rust/kernel/page.rs line 29
Quoted 10 lines
rust/kernel/page.rs +1
-7/// 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 +/// Return None in cases where the next multiple of [`PAGE_SIZE`] would overflow a [`usize`] You can doclink to [
None].Quoted 2 lines
Nit: dot at end of sentence missing.
Will fix this in v2
Quoted 8 lines
rust/kernel/page.rs line 34
Quoted 5 lines
rust/kernel/page.rs +5
-0+pub const fn page_align (addr:usize ) ->Option <usize > { +if let Some (sum) = addr.checked_add (PAGE_SIZE -1 ) { +return Some (sum &PAGE_MASK ); + } +None A more idiomatic way to do this:
Quoted 7 lines
Quoted 3 lines
addr.checked_add(PAGE_SIZE - 1).map(|sum| sum &PAGE_MASK)That would be nice, but alas since this is a const fn, we can't use map here. I assume that was done for optimisation to ensure this could be referenced at compile time. So I'm not sure we want to remove that optimisation here.
Ah, indeed. In that case, can we make the if arms symmetric:
if let Some(sum) = addr.checked_add(PAGE_SIZE - 1) {
Some(sum & PAGE_MASK);
} else {
None
}Quoted 8 lines · Alexandre Courbot
Ah, indeed. In that case, can we make the if arms symmetric:
if let Some(sum) = addr.checked_add(PAGE_SIZE - 1) { Some(sum & PAGE_MASK); } else { None }
Early return style makes the happy path less indented and is more consistent with the C side. However, here the happy case would be the indented case, so let else would be better:
let Some(sum) = addr.checked_add(PAGE_SIZE - 1) else {
return None;
};
Some(sum & PAGE_MASK)Cheers,
Miguel
Quoted 32 lines · Miguel Ojeda
Quoted 5 lines · Brendan Shephard
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.This shouldn't be in the commit message. It should instead be placed below the first
---line (the one below the Signed-off-by).Also, I would recommend not replying to the previous version but starting a new thread instead (it is good to provide a lore.kernel.org to the previous version in the change log).
In addition, if possible, it is nice to use
--baseto tell Git to provide the base commit.rust/kernel/page.rs line 30
Quoted 2 lines
rust/kernel/page.rs +2
-0+/// Return Some [`usize`] that is page aligned. Or None in cases where the next multiple of +/// [`PAGE_SIZE`] would overflow a [`usize`]. Missing intra-doc link (this was feedback in v1). In addition, this reads a bit strangely, and it looks like the first line of the description wasn't removed? That would make the "short description" (the first paragraph) quite long. Please generate the docs to see if it looks good when generated.
More importantly, please add some examples (doctests). They are tested as KUnit tests automatically. For new APIs, we always try to do add examples, and in cases where there are edge cases like here, it clarifies quite a bit, i.e. please provide a representative example of the
Somecase and theNonecase.
Quoted 4 lines
Thanks!
Cheers,
Miguel
This is all really good feedback Miguel, thanks for the pointers. I really like the idea of adding examples. Let me work on that, and then I'll send a V3 as a new thread with references to this one via the lore.kernel.org link.
Quoted 14 lines · Miguel Ojeda
Quoted 8 lines · Alexandre Courbot
Ah, indeed. In that case, can we make the if arms symmetric:
if let Some(sum) = addr.checked_add(PAGE_SIZE - 1) { Some(sum & PAGE_MASK); } else { None }Early return style makes the happy path less indented and is more consistent with the C side. However, here the happy case would be the indented case, so
let elsewould be better:
Quoted 9 lines
let Some(sum) = addr.checked_add(PAGE_SIZE - 1) else { return None; }; Some(sum & PAGE_MASK)Cheers,
Miguel
A wildcard entrant to this conversation. We could do a match instead if you all might prefer that?
match addr.checked_add(PAGE_SIZE - 1) {
Some(v) => Some(v & PAGE_MASK),
None => None,
}
Something about that match syntax doesn't appeal to me though. I think I prefer Miguel's suggestion here where we flip the happy and sad paths. Make the sad path the early return and happy path the default. But I do see at least a couple of match examples here, so it's probably worth a mention to see what you think about it as an alternative?
Alexandre Courbot
reviewerQuoted 25 lines · Brendan Shephard
Quoted 14 lines · Miguel Ojeda
Quoted 8 lines · Alexandre Courbot
Ah, indeed. In that case, can we make the if arms symmetric:
if let Some(sum) = addr.checked_add(PAGE_SIZE - 1) { Some(sum & PAGE_MASK); } else { None }Early return style makes the happy path less indented and is more consistent with the C side. However, here the happy case would be the indented case, so
let elsewould be better:Quoted 9 lines
let Some(sum) = addr.checked_add(PAGE_SIZE - 1) else { return None; }; Some(sum & PAGE_MASK)Cheers,
Miguel
Quoted 7 lines
A wildcard entrant to this conversation. We could do a match instead if you all might prefer that?
match
addr.checked_add(PAGE_SIZE - 1){
Some(v) =>Some(v & PAGE_MASK),
None => None,
}
Clippy will likely suggest to turn this into an if { } else { }, which puts us back to where we come from. Miguel's suggestion of returning early in the failure path looks good to me as well.
Alice Ryhl
maintainerQuoted 30 lines · Alexandre Courbot
Quoted 28 lines · Brendan Shephard
Quoted 14 lines · Miguel Ojeda
Quoted 8 lines · Alexandre Courbot
Ah, indeed. In that case, can we make the if arms symmetric:
if let Some(sum) = addr.checked_add(PAGE_SIZE - 1) { Some(sum & PAGE_MASK); } else { None }Early return style makes the happy path less indented and is more consistent with the C side. However, here the happy case would be the indented case, so
let elsewould be better:Quoted 9 lines
let Some(sum) = addr.checked_add(PAGE_SIZE - 1) else { return None; }; Some(sum & PAGE_MASK)Cheers,
MiguelA wildcard entrant to this conversation. We could do a match instead if you all might prefer that?
Quoted 8 lines
Quoted 4 lines
match
addr.checked_add(PAGE_SIZE - 1){
Some(v) =>Some(v & PAGE_MASK),
None => None,
}Clippy will likely suggest to turn this into an
if { } else { }, which puts us back to where we come from. Miguel's suggestion of returning early in the failure path looks good to me as well.
How about using the question mark operator?
Some(addr.checked_add(PAGE_SIZE - 1)? & PAGE_MASK)
Alexandre Courbot
reviewerQuoted 36 lines · Alice Ryhl
Quoted 35 lines · Alexandre Courbot
Quoted 32 lines · Brendan Shephard
Quoted 14 lines · Miguel Ojeda
Quoted 8 lines · Alexandre Courbot
Ah, indeed. In that case, can we make the if arms symmetric:
if let Some(sum) = addr.checked_add(PAGE_SIZE - 1) { Some(sum & PAGE_MASK); } else { None }Early return style makes the happy path less indented and is more consistent with the C side. However, here the happy case would be the indented case, so
let elsewould be better:Quoted 9 lines
let Some(sum) = addr.checked_add(PAGE_SIZE - 1) else { return None; }; Some(sum & PAGE_MASK)Cheers,
MiguelA wildcard entrant to this conversation. We could do a match instead if you all might prefer that?
match
addr.checked_add(PAGE_SIZE - 1){
Some(v) =>Some(v & PAGE_MASK),
None => None,
}
Quoted 7 lines
Quoted 3 lines
Clippy will likely suggest to turn this into an
if { } else { }, which puts us back to where we come from. Miguel's suggestion of returning early in the failure path looks good to me as well.How about using the question mark operator?
Some(addr.checked_add(PAGE_SIZE - 1)? & PAGE_MASK)
That's unfortunately not usable yet in const contexts:
error: `Try` is not yet stable as a const trait
--> ../rust/kernel/page.rs:35:10
|
35 | Some(addr.checked_add(PAGE_SIZE - 1)? & PAGE_MASK)
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
help: add `#![feature(const_try)]` to the crate attributes to enable