linux-stable.git/rust/kernel/lib.rs, branch linux-6.9.y

rust: kernel: require `Send` for `Module` implementations

2024-04-22T22:38:43+00:00

The thread that calls the module initialisation code when a module is
loaded is not guaranteed [in fact, it is unlikely] to be the same one
that calls the module cleanup code on module unload, therefore, `Module`
implementations must be `Send` to account for them moving from one
thread to another implicitly.

Signed-off-by: Wedson Almeida Filho 
Reviewed-by: Alice Ryhl 
Reviewed-by: Benno Lossin 
Cc: stable@vger.kernel.org # 6.8.x: df70d04d5697: rust: phy: implement `Send` for `Registration`
Cc: stable@vger.kernel.org
Fixes: 247b365dc8dc ("rust: add `kernel` crate")
Link: https://lore.kernel.org/r/20240328195457.225001-3-wedsonaf@gmail.com
Signed-off-by: Miguel Ojeda

rust: add `container_of!` macro

2024-02-25T18:17:31+00:00

This macro is used to obtain a pointer to an entire struct
when given a pointer to a field in that struct.

Signed-off-by: Wedson Almeida Filho 
Reviewed-by: Alice Ryhl 
Tested-by: Alice Ryhl 
Signed-off-by: Matt Gilbride 
Link: https://lore.kernel.org/r/20240219-b4-rbtree-v2-1-0b113aab330d@google.com
Signed-off-by: Miguel Ojeda

rust: kernel: stop using ptr_metadata feature

2024-02-18T20:22:27+00:00

The `byte_sub` method was stabilized in Rust 1.75.0. By using that
method, we no longer need the unstable `ptr_metadata` feature for
implementing `Arc::from_raw`.

This brings us one step closer towards not using unstable compiler
features.

Reviewed-by: Benno Lossin 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Trevor Gross 
Signed-off-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20240215104601.1267763-1-aliceryhl@google.com
[ Reworded title. ]
Signed-off-by: Miguel Ojeda

rust: kernel: add srctree-relative doclinks

2024-02-18T20:22:27+00:00

Convert existing references to C header files to make use of
Commit bc2e7d5c298a ("rust: support `srctree`-relative links").

Signed-off-by: Valentin Obst 
Reviewed-by: Trevor Gross 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20240131-doc-fixes-v3-v3-4-0c8af94ed7de@valentinobst.de
Signed-off-by: Miguel Ojeda

rust: time: add msecs to jiffies conversion

2024-01-28T18:50:48+00:00

Defines type aliases and conversions for msecs and jiffies.

This is used by Rust Binder for process freezing. There, we want to
sleep until the freeze operation completes, but we want to be able to
abort the process freezing if it doesn't complete within some timeout.
The freeze timeout is supplied in msecs.

Note that we need to convert to jiffies in Binder. It is not enough to
introduce a variant of `CondVar::wait_timeout` that takes the timeout in
msecs because we need to be able to restart the sleep with the remaining
sleep duration if it is interrupted, and if the API takes msecs rather
than jiffies, then that would require a conversion roundtrip jiffies->
msecs->jiffies that is best avoided.

Suggested-by: Boqun Feng 
Reviewed-by: Boqun Feng 
Reviewed-by: Benno Lossin 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Tiago Lam 
Signed-off-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20240108-rb-new-condvar-methods-v4-2-88e0c871cc05@google.com
Signed-off-by: Miguel Ojeda

rust: upgrade to Rust 1.75.0

2024-01-22T14:18:05+00:00

This is the next upgrade to the Rust toolchain, from 1.74.1 to 1.75.0
(i.e. the latest) [1].

See the upgrade policy [2] and the comments on the first upgrade in
commit 3ed03f4da06e ("rust: upgrade to Rust 1.68.2").

# Unstable features

The `const_maybe_uninit_zeroed` unstable feature [3] was stabilized in
Rust 1.75.0, which we were using in the PHYLIB abstractions.

The only unstable features allowed to be used outside the `kernel` crate
are still `new_uninit,offset_of`, though other code to be upstreamed
may increase the list.

Please see [4] for details.

# Other improvements

Rust 1.75.0 stabilized `pointer_byte_offsets` [5] which we could
potentially use as an alternative for `ptr_metadata` in the future.

# Required changes

For this upgrade, no changes were required (i.e. on our side).

# `alloc` upgrade and reviewing

The vast majority of changes are due to our `alloc` fork being upgraded
at once.

There are two kinds of changes to be aware of: the ones coming from
upstream, which we should follow as closely as possible, and the updates
needed in our added fallible APIs to keep them matching the newer
infallible APIs coming from upstream.

Instead of taking a look at the diff of this patch, an alternative
approach is reviewing a diff of the changes between upstream `alloc` and
the kernel's. This allows to easily inspect the kernel additions only,
especially to check if the fallible methods we already have still match
the infallible ones in the new version coming from upstream.

Another approach is reviewing the changes introduced in the additions in
the kernel fork between the two versions. This is useful to spot
potentially unintended changes to our additions.

To apply these approaches, one may follow steps similar to the following
to generate a pair of patches that show the differences between upstream
Rust and the kernel (for the subset of `alloc` we use) before and after
applying this patch:

# Get the difference with respect to the old version.
git -C rust checkout $(linux/scripts/min-tool-version.sh rustc)
git -C linux ls-tree -r --name-only HEAD -- rust/alloc |
cut -d/ -f3- |
grep -Fv README.md |
xargs -IPATH cp rust/library/alloc/src/PATH linux/rust/alloc/PATH
git -C linux diff --patch-with-stat --summary -R > old.patch
git -C linux restore rust/alloc

# Apply this patch.
git -C linux am rust-upgrade.patch

# Get the difference with respect to the new version.
git -C rust checkout $(linux/scripts/min-tool-version.sh rustc)
git -C linux ls-tree -r --name-only HEAD -- rust/alloc |
cut -d/ -f3- |
grep -Fv README.md |
xargs -IPATH cp rust/library/alloc/src/PATH linux/rust/alloc/PATH
git -C linux diff --patch-with-stat --summary -R > new.patch
git -C linux restore rust/alloc

Now one may check the `new.patch` to take a look at the additions (first
approach) or at the difference between those two patches (second
approach). For the latter, a side-by-side tool is recommended.

Link: https://github.com/rust-lang/rust/blob/stable/RELEASES.md#version-1750-2023-12-28 [1]
Link: https://rust-for-linux.com/rust-version-policy [2]
Link: https://github.com/rust-lang/rust/issues/91850 [3]
Link: https://github.com/Rust-for-Linux/linux/issues/2 [4]
Link: https://github.com/rust-lang/rust/issues/96283 [5]
Reviewed-by: Vincenzo Palazzo
Reviewed-by: Martin Rodriguez Reboredo
Tested-by: Boqun Feng
Link: https://lore.kernel.org/r/20231224172128.271447-1-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

rust: core abstractions for network PHY drivers

2023-12-15T09:35:50+00:00

This patch adds abstractions to implement network PHY drivers; the
driver registration and bindings for some of callback functions in
struct phy_driver and many genphy_ functions.

This feature is enabled with CONFIG_RUST_PHYLIB_ABSTRACTIONS=y.

This patch enables unstable const_maybe_uninit_zeroed feature for
kernel crate to enable unsafe code to handle a constant value with
uninitialized data. With the feature, the abstractions can initialize
a phy_driver structure with zero easily; instead of initializing all
the members by hand. It's supposed to be stable in the not so distant
future.

Link: https://github.com/rust-lang/rust/pull/116218

Signed-off-by: FUJITA Tomonori 
Reviewed-by: Andrew Lunn 
Reviewed-by: Alice Ryhl 
Signed-off-by: David S. Miller

rust: workqueue: add helper for defining work_struct fields

2023-09-25T19:46:42+00:00

The main challenge with defining `work_struct` fields is making sure
that the function pointer stored in the `work_struct` is appropriate for
the work item type it is embedded in. It needs to know the offset of the
`work_struct` field being used (even if there are several!) so that it
can do a `container_of`, and it needs to know the type of the work item
so that it can call into the right user-provided code. All of this needs
to happen in a way that provides a safe API to the user, so that users
of the workqueue cannot mix up the function pointers.

There are three important pieces that are relevant when doing this:

 * The pointer type.
 * The work item struct. This is what the pointer points at.
 * The `work_struct` field. This is a field of the work item struct.

This patch introduces a separate trait for each piece. The pointer type
is given a `WorkItemPointer` trait, which pointer types need to
implement to be usable with the workqueue. This trait will be
implemented for `Arc` and `Box` in a later patch in this patchset.
Implementing this trait is unsafe because this is where the
`container_of` operation happens, but user-code will not need to
implement it themselves.

The work item struct should then implement the `WorkItem` trait. This
trait is where user-code specifies what they want to happen when a work
item is executed. It also specifies what the correct pointer type is.

Finally, to make the work item struct know the offset of its
`work_struct` field, we use a trait called `HasWork`. If a type
implements this trait, then the type declares that, at the given offset,
there is a field of type `Work`. The trait is marked unsafe
because the OFFSET constant must be correct, but we provide an
`impl_has_work!` macro that can safely implement `HasWork` on a type.
The macro expands to something that only compiles if the specified field
really has the type `Work`. It is used like this:

```
struct MyWorkItem {
    work_field: Work,
}

impl_has_work! {
    impl HasWork for MyWorkItem { self.work_field }
}
```

Note that since the `Work` type is annotated with an id, you can have
several `work_struct` fields by using a different id for each one.

Co-developed-by: Gary Guo 
Signed-off-by: Gary Guo 
Signed-off-by: Alice Ryhl 
Reviewed-by: Benno Lossin 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Andreas Hindborg 
Reviewed-by: Boqun Feng 
Signed-off-by: Tejun Heo

rust: workqueue: add low-level workqueue bindings

2023-09-25T19:46:42+00:00

Define basic low-level bindings to a kernel workqueue. The API defined
here can only be used unsafely. Later commits will provide safe
wrappers.

Co-developed-by: Gary Guo 
Signed-off-by: Gary Guo 
Signed-off-by: Alice Ryhl 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: "Andreas Hindborg (Samsung)" 
Reviewed-by: Benno Lossin 
Reviewed-by: Boqun Feng 
Signed-off-by: Tejun Heo

rust: sync: add `Arc::{from_raw, into_raw}`

2023-09-25T19:46:41+00:00

These methods can be used to turn an `Arc` into a raw pointer and back,
in a way that preserves the metadata for fat pointers.

This is done using the unstable ptr_metadata feature [1]. However, it
could also be done using the unstable pointer_byte_offsets feature [2],
which is likely to have a shorter path to stabilization than
ptr_metadata.

Link: https://github.com/rust-lang/rust/issues/81513 [1]
Link: https://github.com/rust-lang/rust/issues/96283 [2]
Signed-off-by: Wedson Almeida Filho 
Co-developed-by: Alice Ryhl 
Signed-off-by: Alice Ryhl 
Reviewed-by: Gary Guo 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Benno Lossin 
Reviewed-by: Andreas Hindborg 
Reviewed-by: Boqun Feng 
Signed-off-by: Tejun Heo