Error improvements
Miguel Ojeda
maintainercover Error improvements
A couple improvements from the past that I rebased prompted by the discussion at [1].
Miguel Ojeda (3):
rust: error: improve Error::from_errno documentation
rust: error: improve to_result documentation
rust: error: replace WARN_ON_ONCE comment with debug_assert!
rust/kernel/error.rs | 62 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 57 insertions(+), 5 deletions(-)
--
2.51.0
Miguel Ojeda
maintainerPATCH 1/3 rust: error: improve `Error::from_errno` documentation
This constructor is public since commit 5ed147473458 ("rust: error:
make conversion functions public"), and we will refer to it from the documentation of to_result in a later commit.
Thus improve its documentation, including adding examples.
--- rust/kernel/error.rs | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-)
rust/kernel/error.rs +17 -2
@@ -101,8 +101,23 @@ macro_rules! declare_err {impl Error {/// Creates an [`Error`] from a kernel error code. /// -/// It is a bug to pass an out-of-range `errno`. `EINVAL` would -/// be returned in such a case. +/// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`). +/// +/// It is a bug to pass an out-of-range `errno`. [`code::EINVAL`] is returned in such a case. +/// +/// # Examples +/// +/// ``` +/// assert_eq!(Error::from_errno(-1), EPERM); +/// assert_eq!(Error::from_errno(-2), ENOENT); +/// ``` +/// +/// The following calls are considered a bug: +/// +/// ``` +/// assert_eq!(Error::from_errno(0), EINVAL); +/// assert_eq!(Error::from_errno(-1000000), EINVAL); +/// ``` pub fn from_errno (errno:crate ::ffi::c_int ) ->Error {if let Some (error) =Self ::try_from_errno (errno) { error
Signature · 1 line
2.51.0
Re: [PATCH 1/3] rust: error: improve `Error::from_errno` documentation
Quoted 7 lines · Miguel Ojeda
This constructor is public since commit
5ed147473458("rust: error:
make conversion functions public"), and we will refer to it from the documentation ofto_resultin a later commit.Thus improve its documentation, including adding examples.
Signed-off-by Miguel Ojeda <[email protected]>
This reads very smoothly!
Quoted 13 lines
--- rust/kernel/error.rs | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-)rust/kernel/error.rs +0
-1@@ -101,8 +101,23 @@ macro_rules! declare_err {impl Error {/// Creates an [`Error`] from a kernel error code. /// -/// It is a bug to pass an out-of-range `errno`. `EINVAL` would
rust/kernel/error.rs macro_rules! declare_err { · line 112
Quoted 10 lines
rust/kernel/error.rs +9
-1-/// be returned in such a case. +/// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`). +/// +/// It is a bug to pass an out-of-range `errno`. [`code::EINVAL`] is returned in such a case. +/// +/// # Examples +/// +/// ``` +/// assert_eq!(Error::from_errno(-1), EPERM); +/// assert_eq!(Error::from_errno(-2), ENOENT);
Small nit: this leaves a tiny chance of misunderstanding that this function actually expects literal negative integers. How about using e.g. bindings::EPERM instead of -1?
Re: [PATCH 1/3] rust: error: improve `Error::from_errno` documentation
Quoted 4 lines · Alexandre Courbot
Small nit: this leaves a tiny chance of misunderstanding that this function actually expects literal negative integers. How about using e.g.
bindings::EPERMinstead of-1?
Sounds good -- or perhaps EPERM.to_errno()?
Thanks!
Cheers,
Miguel
Alexandre Courbot
reviewerRe: [PATCH 1/3] rust: error: improve `Error::from_errno` documentation
Quoted 7 lines · Miguel Ojeda
Quoted 4 lines · Alexandre Courbot
Small nit: this leaves a tiny chance of misunderstanding that this function actually expects literal negative integers. How about using e.g.
bindings::EPERMinstead of-1?Sounds good -- or perhaps
EPERM.to_errno()?
Looking good to me!
Re: [PATCH 1/3] rust: error: improve `Error::from_errno` documentation
In reply to Miguel OjedaQuoted 7 lines · Miguel Ojeda
This constructor is public since commit
5ed147473458("rust: error:
make conversion functions public"), and we will refer to it from the documentation ofto_resultin a later commit.Thus improve its documentation, including adding examples.
Signed-off-by Miguel Ojeda <[email protected]>
---
Cheers,
Benno
Quoted 3 lines
--- rust/kernel/error.rs | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-)
Miguel Ojeda
maintainerPATCH 2/3 rust: error: improve `to_result` documentation
In reply to Miguel OjedaCore functions like to_result should have good documentation.
Thus improve it, including adding an example of how to perform early returns with it.
--- rust/kernel/error.rs | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-)
rust/kernel/error.rs +37 -2
@@ -390,8 +390,43 @@ fn from(e: core::convert::Infallible) -> Error {/// [Rust documentation]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html pub type Result <T = (),E =Error > = core::result::Result <T ,E >; -/// Converts an integer as returned by a C kernel function to an error if it's negative, and -/// `Ok(())` otherwise. +/// Converts an integer as returned by a C kernel function to a [`Result`]. +/// +/// If the integer is negative, an [`Err`] with an [`Error`] as given by [`Error::from_errno`] is +/// returned. This means the integer must be `>= -MAX_ERRNO`. +/// +/// Otherwise, it returns [`Ok`]. +/// +/// It is a bug to pass an out-of-range negative integer. `Err(EINVAL)` is returned in such a case. +/// +/// # Examples +/// +/// This function may be used to easily perform early returns with the [`?`] operator when working +/// with C APIs within Rust abstractions: +/// +/// ``` +/// # use kernel::error::to_result; +/// # mod bindings { +/// # #![expect(clippy::missing_safety_doc)] +/// # use kernel::prelude::*; +/// # pub(super) unsafe fn f1() -> c_int { 0 } +/// # pub(super) unsafe fn f2() -> c_int { EINVAL.to_errno() } +/// # } +/// fn f() -> Result { +/// // SAFETY: ... +/// to_result(unsafe { bindings::f1() })?; +/// +/// // SAFETY: ... +/// to_result(unsafe { bindings::f2() })?; +/// +/// // ... +/// +/// Ok(()) +/// } +/// # assert_eq!(f(), Err(EINVAL)); +/// ``` +/// +/// [`?`]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator pub fn to_result (err:crate ::ffi::c_int ) ->Result {if err <0 {Err (Error ::from_errno (err))
Signature · 1 line
2.51.0
Re: [PATCH 2/3] rust: error: improve `to_result` documentation
Quoted 6 lines · Miguel Ojeda
Core functions like
to_resultshould have good documentation.Thus improve it, including adding an example of how to perform early returns with it.
Signed-off-by Miguel Ojeda <[email protected]>
Re: [PATCH 2/3] rust: error: improve `to_result` documentation
In reply to Miguel OjedaQuoted 6 lines · Miguel Ojeda
Core functions like
to_resultshould have good documentation.Thus improve it, including adding an example of how to perform early returns with it.
Signed-off-by Miguel Ojeda <[email protected]>
---
Cheers,
Benno
Quoted 3 lines
--- rust/kernel/error.rs | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-)
Miguel Ojeda
maintainerPATCH 3/3 rust: error: replace `WARN_ON_ONCE` comment with `debug_assert!`
In reply to Miguel Ojedawarn_on! support landed recently, and we had a very old comment about using it when supported to catch invalid inputs passed to Error::from_errno.
However, the kernel policy is that reaching a WARN_ON by user interactions is a CVE, e.g. [1].
Since from_errno and other functions that use it such as to_result will be used everywhere, sooner or later a caller may pass an invalid value due to a user interaction.
Thus, instead, use a debug assertion -- this assumes hitting one of them is not going to be considered a CVE (which requires CONFIG_RUST_DEBUG_ASSERTIONS=y).
We don't want to potentially panic when testing the examples, thus convert those to a build-test.
--- rust/kernel/error.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
rust/kernel/error.rs +3 -1
@@ -115,18 +115,20 @@ impl Error {/// The following calls are considered a bug: /// /// ``` +/// # fn no_run() { /// assert_eq!(Error::from_errno(0), EINVAL); /// assert_eq!(Error::from_errno(-1000000), EINVAL); +/// # } /// ``` pub fn from_errno (errno:crate ::ffi::c_int ) ->Error {if let Some (error) =Self ::try_from_errno (errno) { error }else { -// TODO: Make it a `WARN_ONCE` once available. crate ::pr_warn!("attempted to create `Error` with out of range `errno`: {}\n" , errno ); +debug_assert! (false ); code::EINVAL } }
Signature · 1 line
2.51.0
Re: [PATCH 3/3] rust: error: replace `WARN_ON_ONCE` comment with `debug_assert!`
Quoted 4 lines · Miguel Ojeda
Thus, instead, use a debug assertion -- this assumes hitting one of them is not going to be considered a CVE (which requires
CONFIG_RUST_DEBUG_ASSERTIONS=y).
Greg: RFC on this -- this is the usual conundrum around WARN. I would like to have an assertion or WARN-like entity for developers that doesn't imply CVEs when hit by user interactions. More generally, to know that such a config option is OK as long as it is labeled clearly a debug one like this one (we can document the CVE bit explicitly if needed).
Thanks!
Cheers,
Miguel
Re: [PATCH 3/3] rust: error: replace `WARN_ON_ONCE` comment with `debug_assert!`
Quoted 6 lines · Miguel Ojeda
Quoted 4 lines · Miguel Ojeda
Thus, instead, use a debug assertion -- this assumes hitting one of them is not going to be considered a CVE (which requires
CONFIG_RUST_DEBUG_ASSERTIONS=y).
Quoted 6 lines
Greg: RFC on this -- this is the usual conundrum around
WARN. I would like to have an assertion orWARN-like entity for developers that doesn't imply CVEs when hit by user interactions. More generally, to know that such a config option is OK as long as it is labeled clearly a debug one like this one (we can document the CVE bit explicitly if needed).
I do not understand, if there is ANY way that a user can trigger a WARN() call, then that is considered a "vulnerability" as far as CVE is concerned and so I need to issue one when it is fixed. This is entirely because the panic-on-warn option could have also been enabled.
If you wish to state that CONFIG_RUST_DEBUG_ASSERTIONS=y should NEVER be used in ANY shipping Linux system, then yes, we can carve out an exception for this (we do that if lockdep is enabled as that should never be in a running system, only a development one). But I thought that some groups wanted to have that option enabled in their running systems to provide additional security overall?
And yes, the fact that enabling an option for safety can actually cause a CVE to be issued is not lost on me as being very odd :)
thanks,
greg k-h
Re: [PATCH 3/3] rust: error: replace `WARN_ON_ONCE` comment with `debug_assert!`
Quoted 5 lines · Greg KH
If you wish to state that
CONFIG_RUST_DEBUG_ASSERTIONS=yshould NEVER be used in ANY shipping Linux system, then yes, we can carve out an exception for this (we do that if lockdep is enabled as that should never be in a running system, only a development one).
The config option is meant for development purposes ("debug"). We don't control all its behavior anyway, because the compiler/stdlib will also add many assertions (e.g. for unsafe preconditions). So, for instance, it could easily have a non-trivial performance impact.
For the same reason, it will also change behavior depending on the compiler version. So, for instance, new assertions in new compiler versions could have an impact that is not seen in previous versions.
Thus, for this particular config option, we cannot guarantee much, and the help text already states "This can be used to enable extra debugging code in development but not in production.".
Having said that, I regularly CI-test our main branches with the option enabled, and it has worked fine so far.
So if a user actually run with such kind of asserts in production, because they really want to crash on anything and everything, I don't see why they couldn't. It may really be that it actually stops an important exploit from going on. Of course, it may also be that it elevates a trivial bug into a denial of service elsewhere, but that risk may be worth it for certain users.
In fact, I would say it is a good thing that certain specialized users run with it enabled, because then it means they may find potential bugs for others, and that makes everyone safer in practice.
But I don't know what exact constraints the CVE system puts on you, so it is hard to assess what the best wording for such an option would be.
As an addendum: the fact that the compiler is involved is a bit tangential -- we could have our own "debug" asserts (or "extra paranoid" asserts) that are independent of the compiler, and we could have a separate config option etc. But, of course, in this case with the compiler/stdlib involved it means it is harder to blanket-recommend for production.
Thanks!
Cheers,
Miguel
Re: [PATCH 3/3] rust: error: replace `WARN_ON_ONCE` comment with `debug_assert!`
Quoted 30 lines · Miguel Ojeda
Quoted 5 lines · Greg KH
If you wish to state that
CONFIG_RUST_DEBUG_ASSERTIONS=yshould NEVER be used in ANY shipping Linux system, then yes, we can carve out an exception for this (we do that if lockdep is enabled as that should never be in a running system, only a development one).The config option is meant for development purposes ("debug"). We don't control all its behavior anyway, because the compiler/stdlib will also add many assertions (e.g. for unsafe preconditions). So, for instance, it could easily have a non-trivial performance impact.
For the same reason, it will also change behavior depending on the compiler version. So, for instance, new assertions in new compiler versions could have an impact that is not seen in previous versions.
Thus, for this particular config option, we cannot guarantee much, and the help text already states "This can be used to enable extra debugging code in development but not in production.".
Having said that, I regularly CI-test our main branches with the option enabled, and it has worked fine so far.
So if a user actually run with such kind of asserts in production, because they really want to crash on anything and everything, I don't see why they couldn't. It may really be that it actually stops an important exploit from going on. Of course, it may also be that it elevates a trivial bug into a denial of service elsewhere, but that risk may be worth it for certain users.
Quoted 7 lines
In fact, I would say it is a good thing that certain specialized users run with it enabled, because then it means they may find potential bugs for others, and that makes everyone safer in practice.
But I don't know what exact constraints the CVE system puts on you, so it is hard to assess what the best wording for such an option would be.
There are no "constraints" only a definition of a vulnerability that we must follow. And for that, any way that a user could cause a reboot or panic, without having root privileges, gets assigned a CVE.
One exception being if lockdep or a few other "debugging only" options are enabled. Those are explicitly stated by their maintainers that they should NEVER be enabled in a real system. For those we do not assign CVEs as they should never be actually triggered by a user.
So I don't know what to recommend here. I strongly advise against adding code to the kernel that can cause users to reboot their boxes if they do something. But hey, if developers want to do that, I'll gladly assign CVEs for when it happens :)
thanks,
greg k-h
Re: [PATCH 3/3] rust: error: replace `WARN_ON_ONCE` comment with `debug_assert!`
Quoted 10 lines · Greg KH
There are no "constraints" only a definition of a vulnerability that we must follow. And for that, any way that a user could cause a reboot or panic, without having root privileges, gets assigned a CVE.
One exception being if lockdep or a few other "debugging only" options are enabled. Those are explicitly stated by their maintainers that they should NEVER be enabled in a real system. For those we do not assign CVEs as they should never be actually triggered by a user.
Quoted 4 lines
So I don't know what to recommend here. I strongly advise against adding code to the kernel that can cause users to reboot their boxes if they do something. But hey, if developers want to do that, I'll gladly assign CVEs for when it happens :)
Sounds good to me, thanks.
These are meant to be debug assertions, so it should be fine. We can be more explicit in the wording of the config option.
Cheers,
Miguel
Miguel Ojeda
AppliedQuoted 3 lines · Miguel Ojeda
rust: error: improve
Error::from_errnodocumentation
rust: error: improveto_resultdocumentation
Applied these two to rust-next since they are straightforward -- thanks everyone!
For the last one, we can discuss it a bit more in Kangrejos.
Cheers,
Miguel