linux.git/rust/kernel/sync/lock.rs, branch v6.12.80

rust: use custom FFI integer types

2025-03-13T12:01:49+00:00

commit d072acda4862f095ec9056979b654cc06a22cc68 upstream.

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 
Signed-off-by: Greg Kroah-Hartman

rust: enable `clippy::undocumented_unsafe_blocks` lint

2025-03-13T12:01:41+00:00

commit db4f72c904cb116e2bf56afdd67fc5167a607a7b upstream.

Checking that we are not missing any `// SAFETY` comments in our `unsafe`
blocks is something we have wanted to do for a long time, as well as
cleaning up the remaining cases that were not documented [1].

Back when Rust for Linux started, this was something that could have
been done via a script, like Rust's `tidy`. Soon after, in Rust 1.58.0,
Clippy implemented the `undocumented_unsafe_blocks` lint [2].

Even though the lint has a few false positives, e.g. in some cases where
attributes appear between the comment and the `unsafe` block [3], there
are workarounds and the lint seems quite usable already.

Thus enable the lint now.

We still have a few cases to clean up, so just allow those for the moment
by writing a `TODO` comment -- some of those may be good candidates for
new contributors.

Link: https://github.com/Rust-for-Linux/linux/issues/351 [1]
Link: https://rust-lang.github.io/rust-clippy/master/#/undocumented_unsafe_blocks [2]
Link: https://github.com/rust-lang/rust-clippy/issues/13189 [3]
Reviewed-by: Alice Ryhl 
Reviewed-by: Trevor Gross 
Tested-by: Gary Guo 
Reviewed-by: Gary Guo 
Link: https://lore.kernel.org/r/20240904204347.168520-5-ojeda@kernel.org
Signed-off-by: Miguel Ojeda 
Signed-off-by: Greg Kroah-Hartman

rust: kernel: remove redundant imports

2024-05-05T17:22:25+00:00

Rust's `unused_imports` lint covers both unused and redundant imports.
In the upcoming 1.78.0, the lint detects more cases of redundant imports
[1], e.g.:

    error: the item `bindings` is imported redundantly
      --> rust/kernel/print.rs:38:9
       |
    38 |     use crate::bindings;
       |         ^^^^^^^^^^^^^^^ the item `bindings` is already defined by prelude

Most cases are `use crate::bindings`, plus a few other items like `Box`.
Thus clean them up.

Note that, in the `bindings` case, the message "defined by prelude"
above means the extern prelude, i.e. the `--extern` flags we pass.

Link: https://github.com/rust-lang/rust/pull/117772 [1]
Reviewed-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20240401212303.537355-3-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

rust: kernel: add doclinks

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

Add doclinks to existing documentation.

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-10-0c8af94ed7de@valentinobst.de
Signed-off-by: Miguel Ojeda

rust: kernel: mark code fragments in docs with backticks

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

Fix places where comments include code fragments that are not enclosed
in backticks.

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-8-0c8af94ed7de@valentinobst.de
Signed-off-by: Miguel Ojeda

rust: kernel: fix multiple typos in documentation

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

Fixes multiple trivial typos in documentation and comments of the
kernel crate.

allocator:
- Fix a trivial list item alignment issue in the last SAFETY comment of
  `krealloc_aligned`.

init:
- Replace 'type' with 'trait' in the doc comments of the `PinInit` and
  `Init` traits.
- Add colons before starting lists.
- Add spaces between the type and equal sign to respect the code
  formatting rules in example code.
- End a sentence with a full stop instead of a colon.

ioctl:
- Replace 'an' with 'a' where appropriate.

str:
- Replace 'Return' with 'Returns' in the doc comment of `bytes_written`
  as the text describes what the function does.

sync/lock:
- Fix a trivial list item alignment issue in the Safety section of the
  `Backend` trait's description.

sync/lock/spinlock:
- The code in this module operates on spinlocks, not mutexes. Thus,
  replace 'mutex' with 'spinlock' in the SAFETY comment of `unlock`.

workqueue:
- Replace "wont" with "won't" in the doc comment of `__enqueue`.

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-1-0c8af94ed7de@valentinobst.de
Signed-off-by: Miguel Ojeda

rust: sync: add `CondVar::wait_timeout`

2024-01-28T19:54:35+00:00

Sleep on a condition variable with a timeout.

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.

Note that it is not enough to avoid jiffies by introducing 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.

Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Tiago Lam 
Reviewed-by: Boqun Feng 
Signed-off-by: Alice Ryhl 
Reviewed-by: Benno Lossin 
Link: https://lore.kernel.org/r/20240108-rb-new-condvar-methods-v4-3-88e0c871cc05@google.com
[ Added `CondVarTimeoutResult` re-export and fixed typo. ]
Signed-off-by: Miguel Ojeda

rust: kernel: remove `#[allow(clippy::new_ret_no_self)]`

2023-10-05T19:16:13+00:00

Clippy triggered a false positive on its `new_ret_no_self` lint
when using the `pin_init!` macro. Since Rust 1.67.0, that does
not happen anymore, since Clippy learnt to not warn about
`-> impl Trait` [1][2].

The kernel nowadays uses Rust 1.72.1, thus remove the `#[allow]`.

Signed-off-by: Gary Guo 
Reviewed-by: Alice Ryhl 
Reviewed-by: Benno Lossin 
Reviewed-by: Finn Behrens 
Reviewed-by: Martin Rodriguez Reboredo 
Link: https://github.com/rust-lang/rust-clippy/issues/7344 [1]
Link: https://github.com/rust-lang/rust-clippy/pull/9733 [2]
Link: https://lore.kernel.org/r/20230923024707.47610-1-gary@garyguo.net
[ Reworded slightly and added a couple `Link`s. ]
Signed-off-by: Miguel Ojeda

rust: lock: Add intra-doc links to the Backend trait

2023-08-07T09:33:33+00:00

Add missing intra-doc links to the Backend trait to make navigating the
documentation easier.

Suggested-by: Benno Lossin 
Link: https://lore.kernel.org/rust-for-linux/94625fe6-b87a-a8f0-5b2a-a8152d5f7436@proton.me/
Link: https://github.com/Rust-for-Linux/linux/issues/1001
Signed-off-by: Ben Gooding 
Link: https://lore.kernel.org/r/20230509202314.8248-1-ben.gooding.dev@gmail.com
Signed-off-by: Miguel Ojeda

rust: sync: introduce `CondVar`

2023-04-21T23:46:45+00:00

This is the traditional condition variable or monitor synchronisation
primitive. It is implemented with C's `wait_queue_head_t`.

It allows users to release a lock and go to sleep while guaranteeing
that notifications won't be missed. This is achieved by enqueuing a wait
entry before releasing the lock.

Cc: Peter Zijlstra 
Cc: Ingo Molnar 
Cc: Will Deacon 
Cc: Waiman Long 
Reviewed-by: Martin Rodriguez Reboredo 
Signed-off-by: Wedson Almeida Filho 
Reviewed-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20230411054543.21278-12-wedsonaf@gmail.com
Signed-off-by: Miguel Ojeda