linux-toradex.git/rust/kernel/error.rs, branch v6.15-rc5

Merge tag 'rust-6.15' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux

2025-03-31T00:03:26+00:00

Pull Rust updates from Miguel Ojeda:
"Toolchain and infrastructure:

- Extract the 'pin-init' API from the 'kernel' crate and make it into
a standalone crate.

In order to do this, the contents are rearranged so that they can
easily be kept in sync with the version maintained out-of-tree that
other projects have started to use too (or plan to, like QEMU).

This will reduce the maintenance burden for Benno, who will now
have his own sub-tree, and will simplify future expected changes
like the move to use 'syn' to simplify the implementation.

- Add '#[test]'-like support based on KUnit.

We already had doctests support based on KUnit, which takes the
examples in our Rust documentation and runs them under KUnit.

Now, we are adding the beginning of the support for "normal" tests,
similar to those the '#[test]' tests in userspace Rust. For
instance:

#[kunit_tests(my_suite)]
mod tests {
#[test]
fn my_test() {
assert_eq!(1 + 1, 2);
}
}

Unlike with doctests, the 'assert*!'s do not map to the KUnit
assertion APIs yet.

- Check Rust signatures at compile time for functions called from C
by name.

In particular, introduce a new '#[export]' macro that can be placed
in the Rust function definition. It will ensure that the function
declaration on the C side matches the signature on the Rust
function:

#[export]
pub unsafe extern "C" fn my_function(a: u8, b: i32) -> usize {
// ...
}

The macro essentially forces the compiler to compare the types of
the actual Rust function and the 'bindgen'-processed C signature.

These cases are rare so far. In the future, we may consider
introducing another tool, 'cbindgen', to generate C headers
automatically. Even then, having these functions explicitly marked
may be a good idea anyway.

- Enable the 'raw_ref_op' Rust feature: it is already stable, and
allows us to use the new '&raw' syntax, avoiding a couple macros.
After everyone has migrated, we will disallow the macros.

- Pass the correct target to 'bindgen' on Usermode Linux.

- Fix 'rusttest' build in macOS.

'kernel' crate:

- New 'hrtimer' module: add support for setting up intrusive timers
without allocating when starting the timer. Add support for
'Pin>', 'Arc<_>', 'Pin<&_>' and 'Pin<&mut _>' as pointer
types for use with timer callbacks. Add support for setting clock
source and timer mode.

- New 'dma' module: add a simple DMA coherent allocator abstraction
and a test sample driver.

- 'list' module: make the linked list 'Cursor' point between
elements, rather than at an element, which is more convenient to us
and allows for cursors to empty lists; and document it with
examples of how to perform common operations with the provided
methods.

- 'str' module: implement a few traits for 'BStr' as well as the
'strip_prefix()' method.

- 'sync' module: add 'Arc::as_ptr'.

- 'alloc' module: add 'Box::into_pin'.

- 'error' module: extend the 'Result' documentation, including a few
examples on different ways of handling errors, a warning about
using methods that may panic, and links to external documentation.

'macros' crate:

- 'module' macro: add the 'authors' key to support multiple authors.
The original key will be kept until everyone has migrated.

Documentation:

- Add error handling sections.

MAINTAINERS:

- Add Danilo Krummrich as reviewer of the Rust "subsystem".

- Add 'RUST [PIN-INIT]' entry with Benno Lossin as maintainer. It has
its own sub-tree.

- Add sub-tree for 'RUST [ALLOC]'.

- Add 'DMA MAPPING HELPERS DEVICE DRIVER API [RUST]' entry with
Abdiel Janulgue as primary maintainer. It will go through the
sub-tree of the 'RUST [ALLOC]' entry.

- Add 'HIGH-RESOLUTION TIMERS [RUST]' entry with Andreas Hindborg as
maintainer. It has its own sub-tree.

And a few other cleanups and improvements"

* tag 'rust-6.15' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux: (71 commits)
rust: dma: add `Send` implementation for `CoherentAllocation`
rust: macros: fix `make rusttest` build on macOS
rust: block: refactor to use `&raw mut`
rust: enable `raw_ref_op` feature
rust: uaccess: name the correct function
rust: rbtree: fix comments referring to Box instead of KBox
rust: hrtimer: add maintainer entry
rust: hrtimer: add clocksource selection through `ClockId`
rust: hrtimer: add `HrTimerMode`
rust: hrtimer: implement `HrTimerPointer` for `Pin>`
rust: alloc: add `Box::into_pin`
rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&mut T>`
rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&T>`
rust: hrtimer: add `hrtimer::ScopedHrTimerPointer`
rust: hrtimer: add `UnsafeHrTimerPointer`
rust: hrtimer: allow timer restart from timer handler
rust: str: implement `strip_prefix` for `BStr`
rust: str: implement `AsRef` for `[u8]` and `BStr`
rust: str: implement `Index` for `BStr`
rust: str: implement `PartialEq` for `BStr`
...

rust: error: Add EOVERFLOW

2025-03-20T20:44:46+00:00

Trivial addition for missing EOVERFLOW error. This is used by a
subsequent patch that might require returning EOVERFLOW as a result
of `checked_mul`.

Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Abdiel Janulgue 
Acked-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20250317185345.2608976-2-abdiel.janulgue@gmail.com
Signed-off-by: Miguel Ojeda

rust: error: extend the Result documentation

2025-03-16T19:54:08+00:00

Extend the Result documentation by some guidelines and examples how
to handle Result error cases gracefully. And how to not handle them.

While at it fix one missing `Result` link in the existing documentation.

[ Moved links out-of-line for improved readability. Fixed `srctree`
  link. Sorted out-of-line links. Added newlines for consistency
  with other docs. Applied paragraph break suggestion. Reworded
  slightly the docs in a couple places. Added Markdown.

  In addition, added `#[allow(clippy::single_match)` for the first
  example. It cannot be an `expect` since due to a difference introduced
  in Rust 1.85.0 when there are comments in the arms of the `match`.
  Reported it upstream, but it was intended:

      https://github.com/rust-lang/rust-clippy/issues/14418

  Perhaps Clippy will lint about it in the future, but without autofix:

      https://github.com/rust-lang/rust-clippy/pull/14420

    - Miguel ]

Link: https://lore.kernel.org/rust-for-linux/CANiq72keOdXy0LFKk9SzYWwSjiD710v=hQO4xi+5E4xNALa6cA@mail.gmail.com/
Signed-off-by: Dirk Behme 
Reviewed-by: Fiona Behrens 
Link: https://lore.kernel.org/r/20250122054719.595878-1-dirk.behme@de.bosch.com
Signed-off-by: Miguel Ojeda

rust: error: add missing newline to pr_warn! calls

2025-03-05T23:42:13+00:00

Added missing newline at the end of pr_warn! usage
so the log is not missed.

Fixes: 6551a7fe0acb ("rust: error: Add Error::from_errno{_unchecked}()")
Reported-by: Miguel Ojeda 
Link: https://github.com/Rust-for-Linux/linux/issues/1139
Signed-off-by: Alban Kurti 
Link: https://lore.kernel.org/r/20250206-printing_fix-v3-2-a85273b501ae@invicto.ai
[ Replaced Closes with Link since it fixes part of the issue. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: error: import `kernel`'s `LayoutError` instead of `core`'s

2025-01-13T22:45:13+00:00

Import the internal (`kernel::alloc`) version of `LayoutError` instead
of the `core::alloc` one.

In particular, this results in switching the type in the existing
`From for Error` implementation.

Acked-by: Danilo Krummrich 
Signed-off-by: Jimmy Ostler 
Link: https://lore.kernel.org/r/fe58a02189e8804a9eabdd01cb1927d4c491d79c.1734674670.git.jtostler1@gmail.com
[ Reworded commit. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: error: modify `from_errno` to use `try_from_errno`

2024-12-17T22:52:06+00:00

Modify the from_errno function to use try_from_errno to
reduce code duplication while still maintaining all existing
behavior and error handling and also reduces unsafe code.

Link: https://github.com/Rust-for-Linux/linux/issues/1125
Suggested-by: Miguel Ojeda 
Co-developed-by: Guilherme Augusto Martins da Silva 
Signed-off-by: Guilherme Augusto Martins da Silva 
Signed-off-by: Daniel Sedlak 
Reviewed-by: Fiona Behrens 
Link: https://lore.kernel.org/r/20241207112445.55502-1-daniel@sedlak.dev
Signed-off-by: Miguel Ojeda

rust: map `long` to `isize` and `char` to `u8`

2024-12-16T20:49:33+00:00

The following FFI types are replaced compared to `core::ffi`:

1. `char` type is now always mapped to `u8`, since kernel uses
   `-funsigned-char` on the C code. `core::ffi` maps it to platform
   default ABI, which can be either signed or unsigned.

2. `long` is now always mapped to `isize`. It's very common in the
   kernel to use `long` to represent a pointer-sized integer, and in
   fact `intptr_t` is a typedef of `long` in the kernel. Enforce this
   mapping rather than mapping to `i32/i64` depending on platform can
   save us a lot of unnecessary casts.

Signed-off-by: Gary Guo 
Reviewed-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20240913213041.395655-5-gary@garyguo.net
[ Moved `uaccess` changes from the next commit, since they were
  irrefutable patterns that Rust >= 1.82.0 warns about. Reworded
  slightly and reformatted a few documentation comments. Rebased on
  top of `rust-next`. Added the removal of two casts to avoid Clippy
  warnings. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: use custom FFI integer types

2024-11-10T22:58:00+00:00

Currently FFI integer types are defined in libcore. This commit creates
the `ffi` crate and asks bindgen to use that crate for FFI integer types
instead of `core::ffi`.

This commit is preparatory and no type changes are made in this commit
yet.

Signed-off-by: Gary Guo 
Link: https://lore.kernel.org/r/20240913213041.395655-4-gary@garyguo.net
[ Added `rustdoc`, `rusttest` and KUnit tests support. Rebased on top of
  `rust-next` (e.g. migrated more `core::ffi` cases). Reworded crate
  docs slightly and formatted. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: error: check for config `test` in `Error::name`

2024-10-15T21:10:32+00:00

Additional to `testlib` also check for `test` in `Error::name`. This is
required by a subsequent patch that (indirectly) uses `Error` in test
cases.

Reviewed-by: Alice Ryhl 
Reviewed-by: Benno Lossin 
Reviewed-by: Gary Guo 
Signed-off-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20241004154149.93856-24-dakr@kernel.org
Signed-off-by: Miguel Ojeda

rust: error: use `core::alloc::LayoutError`

2024-10-15T21:10:32+00:00

Use `core::alloc::LayoutError` instead of `alloc::alloc::LayoutError` in
preparation to get rid of Rust's alloc crate.

Reviewed-by: Alice Ryhl 
Reviewed-by: Benno Lossin 
Reviewed-by: Gary Guo 
Signed-off-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20241004154149.93856-23-dakr@kernel.org
Signed-off-by: Miguel Ojeda