linux-toradex.git/rust/kernel/sync/arc.rs, branch v6.14-rc2

rust: kernel: add improved version of `ForeignOwnable::borrow_mut`

2025-01-13T22:46:07+00:00

Previously, the `ForeignOwnable` trait had a method called `borrow_mut`
that was intended to provide mutable access to the inner value. However,
the method accidentally made it possible to change the address of the
object being modified, which usually isn't what we want. (And when we
want that, it can be done by calling `from_foreign` and `into_foreign`,
like how the old `borrow_mut` was implemented.)

In this patch, we introduce an alternate definition of `borrow_mut` that
solves the previous problem. Conceptually, given a pointer type `P` that
implements `ForeignOwnable`, the `borrow_mut` method gives you the same
kind of access as an `&mut P` would, except that it does not let you
change the pointer `P` itself.

This is analogous to how the existing `borrow` method provides the same
kind of access to the inner value as an `&P`.

Note that for types like `Arc`, having an `&mut Arc` only gives you
immutable access to the inner `T`. This is because mutable references
assume exclusive access, but there might be other handles to the same
reference counted value, so the access isn't exclusive. The `Arc` type
implements this by making `borrow_mut` return the same type as `borrow`.

Signed-off-by: Alice Ryhl 
Reviewed-by: Boqun Feng 
Reviewed-by: Benno Lossin 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Tamir Duberstein 
Acked-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20241120-borrow-mut-v6-6-80dbadd00951@gmail.com
[ Updated to `crate::ffi::`. Reworded title slightly. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: kernel: reorder `ForeignOwnable` items

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

`{into,from}_foreign` before `borrow` is slightly more logical.

This removes an inconsistency with `kbox.rs` which already uses this
ordering.

Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Tamir Duberstein 
Link: https://lore.kernel.org/r/20241120-borrow-mut-v6-5-80dbadd00951@gmail.com
[ Reworded title slightly. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: kernel: change `ForeignOwnable` pointer to mut

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

It is slightly more convenient to operate on mut pointers, and this also
properly conveys the desired ownership semantics of the trait.

Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Tamir Duberstein 
Acked-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20241120-borrow-mut-v6-4-80dbadd00951@gmail.com
[ Reworded title slightly. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: arc: split unsafe block, add missing comment

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

The new SAFETY comment style is taken from existing comments in `deref`
and `drop.

Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Tamir Duberstein 
Link: https://lore.kernel.org/r/20241120-borrow-mut-v6-3-80dbadd00951@gmail.com
Signed-off-by: Miguel Ojeda

rust: types: avoid `as` casts

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

Replace `as` casts with `cast{,_mut}` calls which are a bit safer.

In one instance, remove an unnecessary `as` cast without replacement.

Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Tamir Duberstein 
Acked-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20241120-borrow-mut-v6-2-80dbadd00951@gmail.com
Signed-off-by: Miguel Ojeda

rust: arc: use `NonNull::new_unchecked`

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

There is no need to check (and panic on violations of) the safety
requirements on `ForeignOwnable` functions. Avoiding the check is
consistent with the implementation of `ForeignOwnable` for `Box`.

Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Tamir Duberstein 
Link: https://lore.kernel.org/r/20241120-borrow-mut-v6-1-80dbadd00951@gmail.com
Signed-off-by: Miguel Ojeda

rust: use derive(CoercePointee) on rustc >= 1.84.0

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

The `kernel` crate relies on both `coerce_unsized` and `dispatch_from_dyn`
unstable features.

Alice Ryhl has proposed [1] the introduction of the unstable macro
`SmartPointer` to reduce such dependence, along with a RFC patch [2].
Since Rust 1.81.0 this macro, later renamed to `CoercePointee` in
Rust 1.84.0 [3], has been fully implemented with the naming discussion
resolved.

This feature is now on track to stabilization in the language.
In order to do so, we shall start using this macro in the `kernel` crate
to prove the functionality and utility of the macro as the justification
of its stabilization.

This patch makes this switch in such a way that the crate remains
backward compatible with older Rust compiler versions,
via the new Kconfig option `RUSTC_HAS_COERCE_POINTEE`.

A minimal demonstration example is added to the
`samples/rust/rust_print_main.rs` module.

Link: https://rust-lang.github.io/rfcs/3621-derive-smart-pointer.html [1]
Link: https://lore.kernel.org/all/20240823-derive-smart-pointer-v1-1-53769cd37239@google.com/ [2]
Link: https://github.com/rust-lang/rust/pull/131284 [3]
Signed-off-by: Xiangfei Ding
Reviewed-by: Fiona Behrens
Reviewed-by: Alice Ryhl
Link: https://lore.kernel.org/r/20241203205050.679106-2-dingxiangfei2009@gmail.com
[ Fixed version to 1.84. Renamed option to `RUSTC_HAS_COERCE_POINTEE`
to match `CC_HAS_*` ones. Moved up new config option, closer to the
`CC_HAS_*` ones. Simplified Kconfig line. Fixed typos and slightly
reworded example and commit. Added Link to PR. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: sync: document `PhantomData` in `Arc`

2024-12-17T23:37:21+00:00

Add a comment explaining the relevant semantics of `PhantomData`. This
should help future readers who may, as I did, assume that this field is
redundant at first glance.

Signed-off-by: Tamir Duberstein 
Reviewed-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20241107-simplify-arc-v2-1-7256e638aac1@gmail.com
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: treewide: switch to our kernel `Box` type

2024-10-15T20:56:59+00:00

Now that we got the kernel `Box` type in place, convert all existing
`Box` users to make use of it.

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-13-dakr@kernel.org
Signed-off-by: Miguel Ojeda