linux/linux
1
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-06-08 00:07:34 +09:00
Code Activity

Rust changes for v6.16

Browse source 
Toolchain and infrastructure:
 
  - KUnit '#[test]'s:
 
    - Support KUnit-mapped 'assert!' macros.
 
      The support that landed last cycle was very basic, and the
      'assert!' macros panicked since they were the standard library
      ones. Now, they are mapped to the KUnit ones in a similar way to
      how is done for doctests, reusing the infrastructure there.
 
      With this, a failing test like:
 
          #[test]
          fn my_first_test() {
              assert_eq!(42, 43);
          }
 
      will report:
 
          # my_first_test: ASSERTION FAILED at rust/kernel/lib.rs:251
          Expected 42 == 43 to be true, but is false
          # my_first_test.speed: normal
          not ok 1 my_first_test
 
    - Support tests with checked 'Result' return types.
 
      The return value of test functions that return a 'Result' will be
      checked, thus one can now easily catch errors when e.g. using the
      '?' operator in tests.
 
      With this, a failing test like:
 
          #[test]
          fn my_test() -> Result {
              f()?;
              Ok(())
          }
 
      will report:
 
          # my_test: ASSERTION FAILED at rust/kernel/lib.rs:321
          Expected is_test_result_ok(my_test()) to be true, but is false
          # my_test.speed: normal
          not ok 1 my_test
 
    - Add 'kunit_tests' to the prelude.
 
  - Clarify the remaining language unstable features in use.
 
  - Compile 'core' with edition 2024 for Rust >= 1.87.
 
  - Workaround 'bindgen' issue with forward references to 'enum' types.
 
  - objtool: relax slice condition to cover more 'noreturn' functions.
 
  - Use absolute paths in macros referencing 'core' and 'kernel' crates.
 
  - Skip '-mno-fdpic' flag for bindgen in GCC 32-bit arm builds.
 
  - Clean some 'doc_markdown' lint hits -- we may enable it later on.
 
 'kernel' crate:
 
  - 'alloc' module:
 
    - 'Box': support for type coercion, e.g. 'Box<T>' to 'Box<dyn U>' if
      'T' implements 'U'.
 
    - 'Vec': implement new methods (prerequisites for nova-core and
      binder): 'truncate', 'resize', 'clear', 'pop',
      'push_within_capacity' (with new error type 'PushError'),
      'drain_all', 'retain', 'remove' (with new error type
      'RemoveError'), insert_within_capacity' (with new error type
      'InsertError').
 
      In addition, simplify 'push' using 'spare_capacity_mut', split
      'set_len' into 'inc_len' and 'dec_len', add type invariant
      'len <= capacity' and simplify 'truncate' using 'dec_len'.
 
  - 'time' module:
 
    - Morph the Rust hrtimer subsystem into the Rust timekeeping
      subsystem, covering delay, sleep, timekeeping, timers. This new
      subsystem has all the relevant timekeeping C maintainers listed in
      the entry.
 
    - Replace 'Ktime' with 'Delta' and 'Instant' types to represent a
      duration of time and a point in time.
 
    - Temporarily add 'Ktime' to 'hrtimer' module to allow 'hrtimer' to
      delay converting to 'Instant' and 'Delta'.
 
  - 'xarray' module:
 
    - Add a Rust abstraction for the 'xarray' data structure. This
      abstraction allows Rust code to leverage the 'xarray' to store
      types that implement 'ForeignOwnable'. This support is a dependency
      for memory backing feature of the Rust null block driver, which is
      waiting to be merged.
 
    - Set up an entry in 'MAINTAINERS' for the XArray Rust support.
      Patches will go to the new Rust XArray tree and then via the Rust
      subsystem tree for now.
 
    - Allow 'ForeignOwnable' to carry information about the pointed-to
      type. This helps asserting alignment requirements for the pointer
      passed to the foreign language.
 
  - 'container_of!': retain pointer mut-ness and add a compile-time check
    of the type of the first parameter ('$field_ptr').
 
  - Support optional message in 'static_assert!'.
 
  - Add C FFI types (e.g. 'c_int') to the prelude.
 
  - 'str' module: simplify KUnit tests 'format!' macro, convert
    'rusttest' tests into KUnit, take advantage of the '-> Result'
    support in KUnit '#[test]'s.
 
  - 'list' module: add examples for 'List', fix path of 'assert_pinned!'
    (so far unused macro rule).
 
  - 'workqueue' module: remove 'HasWork::OFFSET'.
 
  - 'page' module: add 'inline' attribute.
 
 'macros' crate:
 
  - 'module' macro: place 'cleanup_module()' in '.exit.text' section.
 
 'pin-init' crate:
 
  - Add 'Wrapper<T>' trait for creating pin-initializers for wrapper
    structs with a structurally pinned value such as 'UnsafeCell<T>' or
    'MaybeUninit<T>'.
 
  - Add 'MaybeZeroable' derive macro to try to derive 'Zeroable', but
    not error if not all fields implement it. This is needed to derive
    'Zeroable' for all bindgen-generated structs.
 
  - Add 'unsafe fn cast_[pin_]init()' functions to unsafely change the
    initialized type of an initializer. These are utilized by the
    'Wrapper<T>' implementations.
 
  - Add support for visibility in 'Zeroable' derive macro.
 
  - Add support for 'union's in 'Zeroable' derive macro.
 
  - Upstream dev news: streamline CI, fix some bugs. Add new workflows
    to check if the user-space version and the one in the kernel tree
    have diverged. Use the issues tab [1] to track them, which should
    help folks report and diagnose issues w.r.t. 'pin-init' better.
 
      [1] https://github.com/rust-for-linux/pin-init/issues
 
 Documentation:
 
  - Testing: add docs on the new KUnit '#[test]' tests.
 
  - Coding guidelines: explain that '///' vs. '//' applies to private
    items too. Add section on C FFI types.
 
  - Quick Start guide: update Ubuntu instructions and split them into
    "25.04" and "24.04 LTS and older".
 
 And a few other cleanups and improvements.
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCgAdFiEEPjU5OPd5QIZ9jqqOGXyLc2htIW0FAmhBAvYACgkQGXyLc2ht
 IW3qvA/+KRTCYKcI6JyUT9TdhRmaaMsQ0/5j6Kx4CfRQPZTSWsXyBEU75yEIZUQD
 SUGQFwmMAYeAKQD1SumFCRy973VzUO45DyKM+7vuVhKN1ZjnAtv63+31C3UFATlA
 8Tm3GCqQEGKl4IER7xI3D/vpZA5FOv+GotjNieF3O9FpHDCvV/JQScq9I2oXQPCt
 17kRLww/DTfpf4qiLmxmxHn6nCsbecdfEce1kfjk3nNuE6B2tPf+ddYOwunLEvkB
 LA4Cr6T1Cy1ovRQgxg9Pdkl/0Rta0tFcsKt1LqPgjR+n95stsHgAzbyMGuUKoeZx
 u2R2pwlrJt6Xe4CEZgTIRfYWgF81qUzdcPuflcSMDCpH0nTep74A2lIiWUHWZSh4
 LbPh7r90Q8YwGKVJiWqLfHUmQBnmTEm3D2gydSExPKJXSzB4Rbv4w4fPF3dhzMtC
 4+KvmHKIojFkAdTLt+5rkKipJGo/rghvQvaQr9JOu+QO4vfhkesB4pUWC4sZd9A9
 GJBP97ynWAsXGGaeaaSli0b851X+VE/WIDOmPMselbA3rVADChE6HsJnY/wVVeWK
 jupvAhUExSczDPCluGv8T9EVXvv6+fg3bB5pD6R01NNJe6iE/LIDQ5Gj5rg4qahM
 EFzMgPj6hMt5McvWI8q1/ym0bzdeC2/cmaV6E14hvphAZoORUKI=
 =JRqL
 -----END PGP SIGNATURE-----

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

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

   - KUnit '#[test]'s:

      - Support KUnit-mapped 'assert!' macros.

        The support that landed last cycle was very basic, and the
        'assert!' macros panicked since they were the standard library
        ones. Now, they are mapped to the KUnit ones in a similar way to
        how is done for doctests, reusing the infrastructure there.

        With this, a failing test like:

            #[test]
            fn my_first_test() {
                assert_eq!(42, 43);
            }

        will report:

            # my_first_test: ASSERTION FAILED at rust/kernel/lib.rs:251
            Expected 42 == 43 to be true, but is false
            # my_first_test.speed: normal
            not ok 1 my_first_test

      - Support tests with checked 'Result' return types.

        The return value of test functions that return a 'Result' will
        be checked, thus one can now easily catch errors when e.g. using
        the '?' operator in tests.

        With this, a failing test like:

            #[test]
            fn my_test() -> Result {
                f()?;
                Ok(())
            }

        will report:

            # my_test: ASSERTION FAILED at rust/kernel/lib.rs:321
            Expected is_test_result_ok(my_test()) to be true, but is false
            # my_test.speed: normal
            not ok 1 my_test

      - Add 'kunit_tests' to the prelude.

   - Clarify the remaining language unstable features in use.

   - Compile 'core' with edition 2024 for Rust >= 1.87.

   - Workaround 'bindgen' issue with forward references to 'enum' types.

   - objtool: relax slice condition to cover more 'noreturn' functions.

   - Use absolute paths in macros referencing 'core' and 'kernel'
     crates.

   - Skip '-mno-fdpic' flag for bindgen in GCC 32-bit arm builds.

   - Clean some 'doc_markdown' lint hits -- we may enable it later on.

  'kernel' crate:

   - 'alloc' module:

      - 'Box': support for type coercion, e.g. 'Box<T>' to 'Box<dyn U>'
        if 'T' implements 'U'.

      - 'Vec': implement new methods (prerequisites for nova-core and
        binder): 'truncate', 'resize', 'clear', 'pop',
        'push_within_capacity' (with new error type 'PushError'),
        'drain_all', 'retain', 'remove' (with new error type
        'RemoveError'), insert_within_capacity' (with new error type
        'InsertError').

        In addition, simplify 'push' using 'spare_capacity_mut', split
        'set_len' into 'inc_len' and 'dec_len', add type invariant 'len
        <= capacity' and simplify 'truncate' using 'dec_len'.

   - 'time' module:

      - Morph the Rust hrtimer subsystem into the Rust timekeeping
        subsystem, covering delay, sleep, timekeeping, timers. This new
        subsystem has all the relevant timekeeping C maintainers listed
        in the entry.

      - Replace 'Ktime' with 'Delta' and 'Instant' types to represent a
        duration of time and a point in time.

      - Temporarily add 'Ktime' to 'hrtimer' module to allow 'hrtimer'
        to delay converting to 'Instant' and 'Delta'.

   - 'xarray' module:

      - Add a Rust abstraction for the 'xarray' data structure. This
        abstraction allows Rust code to leverage the 'xarray' to store
        types that implement 'ForeignOwnable'. This support is a
        dependency for memory backing feature of the Rust null block
        driver, which is waiting to be merged.

      - Set up an entry in 'MAINTAINERS' for the XArray Rust support.
        Patches will go to the new Rust XArray tree and then via the
        Rust subsystem tree for now.

      - Allow 'ForeignOwnable' to carry information about the pointed-to
        type. This helps asserting alignment requirements for the
        pointer passed to the foreign language.

   - 'container_of!': retain pointer mut-ness and add a compile-time
     check of the type of the first parameter ('$field_ptr').

   - Support optional message in 'static_assert!'.

   - Add C FFI types (e.g. 'c_int') to the prelude.

   - 'str' module: simplify KUnit tests 'format!' macro, convert
     'rusttest' tests into KUnit, take advantage of the '-> Result'
     support in KUnit '#[test]'s.

   - 'list' module: add examples for 'List', fix path of
     'assert_pinned!' (so far unused macro rule).

   - 'workqueue' module: remove 'HasWork::OFFSET'.

   - 'page' module: add 'inline' attribute.

  'macros' crate:

   - 'module' macro: place 'cleanup_module()' in '.exit.text' section.

  'pin-init' crate:

   - Add 'Wrapper<T>' trait for creating pin-initializers for wrapper
     structs with a structurally pinned value such as 'UnsafeCell<T>' or
     'MaybeUninit<T>'.

   - Add 'MaybeZeroable' derive macro to try to derive 'Zeroable', but
     not error if not all fields implement it. This is needed to derive
     'Zeroable' for all bindgen-generated structs.

   - Add 'unsafe fn cast_[pin_]init()' functions to unsafely change the
     initialized type of an initializer. These are utilized by the
     'Wrapper<T>' implementations.

   - Add support for visibility in 'Zeroable' derive macro.

   - Add support for 'union's in 'Zeroable' derive macro.

   - Upstream dev news: streamline CI, fix some bugs. Add new workflows
     to check if the user-space version and the one in the kernel tree
     have diverged. Use the issues tab [1] to track them, which should
     help folks report and diagnose issues w.r.t. 'pin-init' better.

       [1] https://github.com/rust-for-linux/pin-init/issues

  Documentation:

   - Testing: add docs on the new KUnit '#[test]' tests.

   - Coding guidelines: explain that '///' vs. '//' applies to private
     items too. Add section on C FFI types.

   - Quick Start guide: update Ubuntu instructions and split them into
     "25.04" and "24.04 LTS and older".

  And a few other cleanups and improvements"

* tag 'rust-6.16' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux: (78 commits)
  rust: list: Fix typo `much` in arc.rs
  rust: check type of `$ptr` in `container_of!`
  rust: workqueue: remove HasWork::OFFSET
  rust: retain pointer mut-ness in `container_of!`
  Documentation: rust: testing: add docs on the new KUnit `#[test]` tests
  Documentation: rust: rename `#[test]`s to "`rusttest` host tests"
  rust: str: take advantage of the `-> Result` support in KUnit `#[test]`'s
  rust: str: simplify KUnit tests `format!` macro
  rust: str: convert `rusttest` tests into KUnit
  rust: add `kunit_tests` to the prelude
  rust: kunit: support checked `-> Result`s in KUnit `#[test]`s
  rust: kunit: support KUnit-mapped `assert!` macros in `#[test]`s
  rust: make section names plural
  rust: list: fix path of `assert_pinned!`
  rust: compile libcore with edition 2024 for 1.87+
  rust: dma: add missing Markdown code span
  rust: task: add missing Markdown code spans and intra-doc links
  rust: pci: fix docs related to missing Markdown code spans
  rust: alloc: add missing Markdown code span
  rust: alloc: add missing Markdown code spans
  ...
This commit is contained in:
Linus Torvalds 2025-06-04 21:18:37 -07:00
commit ec7714e494
69 changed files with 1980 additions and 394 deletions
Download patch file Download diff file Expand all files Collapse all files

1
.mailmap
View file

@ -135,6 +135,7 @@ Ben Widawsky <bwidawsk@kernel.org> <benjamin.widawsky@intel.com>
Benjamin Poirier <benjamin.poirier@gmail.com> <bpoirier@suse.de>
Benjamin Tissoires <bentiss@kernel.org> <benjamin.tissoires@gmail.com>
Benjamin Tissoires <bentiss@kernel.org> <benjamin.tissoires@redhat.com>
Benno Lossin <lossin@kernel.org> <benno.lossin@proton.me>
Bingwu Zhang <xtex@aosc.io> <xtexchooser@duck.com>
Bingwu Zhang <xtex@aosc.io> <xtex@xtexx.eu.org>
Bjorn Andersson <andersson@kernel.org> <bjorn@kryo.se>

29
Documentation/rust/coding-guidelines.rst
View file

@ -85,6 +85,18 @@ written after the documentation, e.g.:
// ...
}
This applies to both public and private items. This increases consistency with
public items, allows changes to visibility with less changes involved and will
allow us to potentially generate the documentation for private items as well.
In other words, if documentation is written for a private item, then ``///``
should still be used. For instance:
.. code-block:: rust
/// My private function.
// TODO: ...
fn f() {}
One special kind of comments are the ``// SAFETY:`` comments. These must appear
before every ``unsafe`` block, and they explain why the code inside the block is
correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:
@ -191,6 +203,23 @@ or:
/// [`struct mutex`]: srctree/include/linux/mutex.h
C FFI types
-----------
Rust kernel code refers to C types, such as ``int``, using type aliases such as
``c_int``, which are readily available from the ``kernel`` prelude. Please do
not use the aliases from ``core::ffi`` -- they may not map to the correct types.
These aliases should generally be referred directly by their identifier, i.e.
as a single segment path. For instance:
.. code-block:: rust
fn f(p: *const c_char) -> c_int {
// ...
}
Naming
------

44
Documentation/rust/quick-start.rst
View file

@ -90,15 +90,53 @@ they should generally work out of the box, e.g.::
Ubuntu
******
Ubuntu LTS and non-LTS (interim) releases provide recent Rust releases and thus
they should generally work out of the box, e.g.::
25.04
~~~~~
apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 rust-1.80-clippy
The latest Ubuntu releases provide recent Rust releases and thus they should
generally work out of the box, e.g.::
apt install rustc rust-src bindgen rustfmt rust-clippy
In addition, ``RUST_LIB_SRC`` needs to be set, e.g.::
RUST_LIB_SRC=/usr/src/rustc-$(rustc --version | cut -d' ' -f2)/library
For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
24.04 LTS and older
~~~~~~~~~~~~~~~~~~~
Though Ubuntu 24.04 LTS and older versions still provide recent Rust
releases, they require some additional configuration to be set, using
the versioned packages, e.g.::
apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 \
rust-1.80-clippy
ln -s /usr/lib/rust-1.80/bin/rustfmt /usr/bin/rustfmt-1.80
ln -s /usr/lib/rust-1.80/bin/clippy-driver /usr/bin/clippy-driver-1.80
None of these packages set their tools as defaults; therefore they should be
specified explicitly, e.g.::
make LLVM=1 RUSTC=rustc-1.80 RUSTDOC=rustdoc-1.80 RUSTFMT=rustfmt-1.80 \
CLIPPY_DRIVER=clippy-driver-1.80 BINDGEN=bindgen-0.65
Alternatively, modify the ``PATH`` variable to place the Rust 1.80 binaries
first and set ``bindgen`` as the default, e.g.::
PATH=/usr/lib/rust-1.80/bin:$PATH
update-alternatives --install /usr/bin/bindgen bindgen \
/usr/bin/bindgen-0.65 100
update-alternatives --set bindgen /usr/bin/bindgen-0.65
``RUST_LIB_SRC`` needs to be set when using the versioned packages, e.g.::
RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version | cut -d' ' -f2)/library
For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
In addition, ``bindgen-0.65`` is available in newer releases (24.04 LTS and
24.10), but it may not be available in older ones (20.04 LTS and 22.04 LTS),
thus ``bindgen`` may need to be built manually (please see below).

80
Documentation/rust/testing.rst
View file

@ -133,13 +133,85 @@ please see:
The ``#[test]`` tests
---------------------
Additionally, there are the ``#[test]`` tests. These can be run using the
``rusttest`` Make target::
Additionally, there are the ``#[test]`` tests. Like for documentation tests,
these are also fairly similar to what you would expect from userspace, and they
are also mapped to KUnit.
These tests are introduced by the ``kunit_tests`` procedural macro, which takes
the name of the test suite as an argument.
For instance, assume we want to test the function ``f`` from the documentation
tests section. We could write, in the same file where we have our function:
.. code-block:: rust
#[kunit_tests(rust_kernel_mymod)]
mod tests {
use super::*;
#[test]
fn test_f() {
assert_eq!(f(10, 20), 30);
}
}
And if we run it, the kernel log would look like::
KTAP version 1
# Subtest: rust_kernel_mymod
# speed: normal
1..1
# test_f.speed: normal
ok 1 test_f
ok 1 rust_kernel_mymod
Like documentation tests, the ``assert!`` and ``assert_eq!`` macros are mapped
back to KUnit and do not panic. Similarly, the
`? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator>`_
operator is supported, i.e. the test functions may return either nothing (i.e.
the unit type ``()``) or ``Result`` (i.e. any ``Result<T, E>``). For instance:
.. code-block:: rust
#[kunit_tests(rust_kernel_mymod)]
mod tests {
use super::*;
#[test]
fn test_g() -> Result {
let x = g()?;
assert_eq!(x, 30);
Ok(())
}
}
If we run the test and the call to ``g`` fails, then the kernel log would show::
KTAP version 1
# Subtest: rust_kernel_mymod
# speed: normal
1..1
# test_g: ASSERTION FAILED at rust/kernel/lib.rs:335
Expected is_test_result_ok(test_g()) to be true, but is false
# test_g.speed: normal
not ok 1 test_g
not ok 1 rust_kernel_mymod
If a ``#[test]`` test could be useful as an example for the user, then please
use a documentation test instead. Even edge cases of an API, e.g. error or
boundary cases, can be interesting to show in examples.
The ``rusttest`` host tests
---------------------------
These are userspace tests that can be built and run in the host (i.e. the one
that performs the kernel build) using the ``rusttest`` Make target::
make LLVM=1 rusttest
This requires the kernel ``.config``. It runs the ``#[test]`` tests on the host
(currently) and thus is fairly limited in what these tests can test.
This requires the kernel ``.config``.
Currently, they are mostly used for testing the ``macros`` crate's examples.
The Kselftests
--------------

26
MAINTAINERS
View file

@ -10719,20 +10719,23 @@ F: kernel/time/timer_list.c
F: kernel/time/timer_migration.*
F: tools/testing/selftests/timers/
HIGH-RESOLUTION TIMERS [RUST]
DELAY, SLEEP, TIMEKEEPING, TIMERS [RUST]
M: Andreas Hindborg <a.hindborg@kernel.org>
R: Boqun Feng <boqun.feng@gmail.com>
R: FUJITA Tomonori <fujita.tomonori@gmail.com>
R: Frederic Weisbecker <frederic@kernel.org>
R: Lyude Paul <lyude@redhat.com>
R: Thomas Gleixner <tglx@linutronix.de>
R: Anna-Maria Behnsen <anna-maria@linutronix.de>
R: John Stultz <jstultz@google.com>
R: Stephen Boyd <sboyd@kernel.org>
L: rust-for-linux@vger.kernel.org
S: Supported
W: https://rust-for-linux.com
B: https://github.com/Rust-for-Linux/linux/issues
T: git https://github.com/Rust-for-Linux/linux.git hrtimer-next
F: rust/kernel/time/hrtimer.rs
F: rust/kernel/time/hrtimer/
T: git https://github.com/Rust-for-Linux/linux.git timekeeping-next
F: rust/kernel/time.rs
F: rust/kernel/time/
HIGH-SPEED SCC DRIVER FOR AX.25
L: linux-hams@vger.kernel.org
@ -21588,7 +21591,7 @@ M: Alex Gaynor <alex.gaynor@gmail.com>
R: Boqun Feng <boqun.feng@gmail.com>
R: Gary Guo <gary@garyguo.net>
R: Björn Roy Baron <bjorn3_gh@protonmail.com>
R: Benno Lossin <benno.lossin@proton.me>
R: Benno Lossin <lossin@kernel.org>
R: Andreas Hindborg <a.hindborg@kernel.org>
R: Alice Ryhl <aliceryhl@google.com>
R: Trevor Gross <tmgross@umich.edu>
@ -21618,7 +21621,7 @@ F: rust/kernel/alloc.rs
F: rust/kernel/alloc/
RUST [PIN-INIT]
M: Benno Lossin <benno.lossin@proton.me>
M: Benno Lossin <lossin@kernel.org>
L: rust-for-linux@vger.kernel.org
S: Maintained
W: https://rust-for-linux.com/pin-init
@ -26829,6 +26832,17 @@ F: lib/test_xarray.c
F: lib/xarray.c
F: tools/testing/radix-tree
XARRAY API [RUST]
M: Tamir Duberstein <tamird@gmail.com>
M: Andreas Hindborg <a.hindborg@kernel.org>
L: rust-for-linux@vger.kernel.org
S: Supported
W: https://rust-for-linux.com
B: https://github.com/Rust-for-Linux/linux/issues
C: https://rust-for-linux.zulipchat.com
T: git https://github.com/Rust-for-Linux/linux.git xarray-next
F: rust/kernel/xarray.rs
XBOX DVD IR REMOTE
M: Benjamin Valentin <benpicco@googlemail.com>
S: Maintained

3
init/Kconfig
View file

@ -136,6 +136,9 @@ config LD_CAN_USE_KEEP_IN_OVERLAY
config RUSTC_HAS_COERCE_POINTEE
def_bool RUSTC_VERSION >= 108400
config RUSTC_HAS_SPAN_FILE
def_bool RUSTC_VERSION >= 108800
config RUSTC_HAS_UNNECESSARY_TRANSMUTES
def_bool RUSTC_VERSION >= 108800

19
rust/Makefile
View file

@ -60,6 +60,8 @@ endif
core-cfgs = \
--cfg no_fp_fmt_parse
core-edition := $(if $(call rustc-min-version,108700),2024,2021)
# `rustc` recognizes `--remap-path-prefix` since 1.26.0, but `rustdoc` only
# since Rust 1.81.0. Moreover, `rustdoc` ICEs on out-of-tree builds since Rust
# 1.82.0 (https://github.com/rust-lang/rust/issues/138520). Thus workaround both
@ -106,8 +108,8 @@ rustdoc-macros: $(src)/macros/lib.rs FORCE
# Starting with Rust 1.82.0, skipping `-Wrustdoc::unescaped_backticks` should
# not be needed -- see https://github.com/rust-lang/rust/pull/128307.
rustdoc-core: private skip_flags = -Wrustdoc::unescaped_backticks
rustdoc-core: private rustc_target_flags = $(core-cfgs)
rustdoc-core: private skip_flags = --edition=2021 -Wrustdoc::unescaped_backticks
rustdoc-core: private rustc_target_flags = --edition=$(core-edition) $(core-cfgs)
rustdoc-core: $(RUST_LIB_SRC)/core/src/lib.rs FORCE
+$(call if_changed,rustdoc)
@ -273,7 +275,7 @@ bindgen_skip_c_flags := -mno-fp-ret-in-387 -mpreferred-stack-boundary=% \
-fzero-call-used-regs=% -fno-stack-clash-protection \
-fno-inline-functions-called-once -fsanitize=bounds-strict \
-fstrict-flex-arrays=% -fmin-function-alignment=% \
-fzero-init-padding-bits=% \
-fzero-init-padding-bits=% -mno-fdpic \
--param=% --param asan-%
# Derived from `scripts/Makefile.clang`.
@ -402,7 +404,8 @@ quiet_cmd_rustc_procmacro = $(RUSTC_OR_CLIPPY_QUIET) P $@
-Clink-args='$(call escsq,$(KBUILD_PROCMACROLDFLAGS))' \
--emit=dep-info=$(depfile) --emit=link=$@ --extern proc_macro \
--crate-type proc-macro \
--crate-name $(patsubst lib%.$(libmacros_extension),%,$(notdir $@)) $<
--crate-name $(patsubst lib%.$(libmacros_extension),%,$(notdir $@)) \
@$(objtree)/include/generated/rustc_cfg $<
# Procedural macros can only be used with the `rustc` that compiled it.
$(obj)/$(libmacros_name): $(src)/macros/lib.rs FORCE
@ -416,7 +419,7 @@ quiet_cmd_rustc_library = $(if $(skip_clippy),RUSTC,$(RUSTC_OR_CLIPPY_QUIET)) L
cmd_rustc_library = \
OBJTREE=$(abspath $(objtree)) \
$(if $(skip_clippy),$(RUSTC),$(RUSTC_OR_CLIPPY)) \
$(filter-out $(skip_flags),$(rust_flags) $(rustc_target_flags)) \
$(filter-out $(skip_flags),$(rust_flags)) $(rustc_target_flags) \
--emit=dep-info=$(depfile) --emit=obj=$@ \
--emit=metadata=$(dir $@)$(patsubst %.o,lib%.rmeta,$(notdir $@)) \
--crate-type rlib -L$(objtree)/$(obj) \
@ -427,7 +430,7 @@ quiet_cmd_rustc_library = $(if $(skip_clippy),RUSTC,$(RUSTC_OR_CLIPPY_QUIET)) L
rust-analyzer:
$(Q)MAKEFLAGS= $(srctree)/scripts/generate_rust_analyzer.py \
--cfgs='core=$(core-cfgs)' \
--cfgs='core=$(core-cfgs)' $(core-edition) \
$(realpath $(srctree)) $(realpath $(objtree)) \
$(rustc_sysroot) $(RUST_LIB_SRC) $(if $(KBUILD_EXTMOD),$(srcroot)) \
> rust-project.json
@ -483,9 +486,9 @@ $(obj)/helpers/helpers.o: $(src)/helpers/helpers.c $(recordmcount_source) FORCE
$(obj)/exports.o: private skip_gendwarfksyms = 1
$(obj)/core.o: private skip_clippy = 1
$(obj)/core.o: private skip_flags = -Wunreachable_pub
$(obj)/core.o: private skip_flags = --edition=2021 -Wunreachable_pub
$(obj)/core.o: private rustc_objcopy = $(foreach sym,$(redirect-intrinsics),--redefine-sym $(sym)=__rust$(sym))
$(obj)/core.o: private rustc_target_flags = $(core-cfgs)
$(obj)/core.o: private rustc_target_flags = --edition=$(core-edition) $(core-cfgs)
$(obj)/core.o: $(RUST_LIB_SRC)/core/src/lib.rs \
$(wildcard $(objtree)/include/config/RUSTC_VERSION_TEXT) FORCE
+$(call if_changed_rule,rustc_library)

28
rust/bindings/bindings_helper.h
View file

@ -6,6 +6,28 @@
* Sorted alphabetically.
*/
/*
* First, avoid forward references to `enum` types.
*
* This workarounds a `bindgen` issue with them:
* <https://github.com/rust-lang/rust-bindgen/issues/3179>.
*
* Without this, the generated Rust type may be the wrong one (`i32`) or
* the proper one (typically `c_uint`) depending on how the headers are
* included, which in turn may depend on the particular kernel configuration
* or the architecture.
*
* The alternative would be to use casts and likely an
* `#[allow(clippy::unnecessary_cast)]` in the Rust source files. Instead,
* this approach allows us to keep the correct code in the source files and
* simply remove this section when the issue is fixed upstream and we bump
* the minimum `bindgen` version.
*
* This workaround may not be possible in some cases, depending on how the C
* headers are set up.
*/
#include <linux/hrtimer_types.h>
#include <drm/drm_device.h>
#include <drm/drm_drv.h>
#include <drm/drm_file.h>
@ -48,6 +70,7 @@
#include <linux/tracepoint.h>
#include <linux/wait.h>
#include <linux/workqueue.h>
#include <linux/xarray.h>
#include <trace/events/rust_sample.h>
#if defined(CONFIG_DRM_PANIC_SCREEN_QR_CODE)
@ -67,3 +90,8 @@ const gfp_t RUST_CONST_HELPER___GFP_HIGHMEM = ___GFP_HIGHMEM;
const gfp_t RUST_CONST_HELPER___GFP_NOWARN = ___GFP_NOWARN;
const blk_features_t RUST_CONST_HELPER_BLK_FEAT_ROTATIONAL = BLK_FEAT_ROTATIONAL;
const fop_flags_t RUST_CONST_HELPER_FOP_UNSIGNED_OFFSET = FOP_UNSIGNED_OFFSET;
const xa_mark_t RUST_CONST_HELPER_XA_PRESENT = XA_PRESENT;
const gfp_t RUST_CONST_HELPER_XA_FLAGS_ALLOC = XA_FLAGS_ALLOC;
const gfp_t RUST_CONST_HELPER_XA_FLAGS_ALLOC1 = XA_FLAGS_ALLOC1;

2
rust/ffi.rs
View file

@ -17,7 +17,7 @@ macro_rules! alias {
// Check size compatibility with `core`.
const _: () = assert!(
core::mem::size_of::<$name>() == core::mem::size_of::<core::ffi::$name>()
::core::mem::size_of::<$name>() == ::core::mem::size_of::<::core::ffi::$name>()
);
)*}
}

1
rust/helpers/helpers.c
View file

@ -43,3 +43,4 @@
#include "vmalloc.c"
#include "wait.c"
#include "workqueue.c"
#include "xarray.c"

28
rust/helpers/xarray.c Normal file
View file

@ -0,0 +1,28 @@
// SPDX-License-Identifier: GPL-2.0
#include <linux/xarray.h>
int rust_helper_xa_err(void *entry)
{
return xa_err(entry);
}
void rust_helper_xa_init_flags(struct xarray *xa, gfp_t flags)
{
return xa_init_flags(xa, flags);
}
int rust_helper_xa_trylock(struct xarray *xa)
{
return xa_trylock(xa);
}
void rust_helper_xa_lock(struct xarray *xa)
{
return xa_lock(xa);
}
void rust_helper_xa_unlock(struct xarray *xa)
{
return xa_unlock(xa);
}

4
rust/kernel/alloc.rs
View file

@ -94,10 +94,10 @@ pub mod flags {
///
/// A lower watermark is applied to allow access to "atomic reserves". The current
/// implementation doesn't support NMI and few other strict non-preemptive contexts (e.g.
/// raw_spin_lock). The same applies to [`GFP_NOWAIT`].
/// `raw_spin_lock`). The same applies to [`GFP_NOWAIT`].
pub const GFP_ATOMIC: Flags = Flags(bindings::GFP_ATOMIC);
/// Typical for kernel-internal allocations. The caller requires ZONE_NORMAL or a lower zone
/// Typical for kernel-internal allocations. The caller requires `ZONE_NORMAL` or a lower zone
/// for direct access but can direct reclaim.
pub const GFP_KERNEL: Flags = Flags(bindings::GFP_KERNEL);

2
rust/kernel/alloc/allocator_test.rs
View file

@ -4,7 +4,7 @@
//! of those types (e.g. `CString`) use kernel allocators for instantiation.
//!
//! In order to allow userspace test cases to make use of such types as well, implement the
//! `Cmalloc` allocator within the allocator_test module and type alias all kernel allocators to
//! `Cmalloc` allocator within the `allocator_test` module and type alias all kernel allocators to
//! `Cmalloc`. The `Cmalloc` allocator uses libc's `realloc()` function as allocator backend.
#![allow(missing_docs)]

80
rust/kernel/alloc/kbox.rs
View file

@ -57,12 +57,50 @@ use pin_init::{InPlaceWrite, Init, PinInit, ZeroableOption};
/// assert!(KVBox::<Huge>::new_uninit(GFP_KERNEL).is_ok());
/// ```
///
/// [`Box`]es can also be used to store trait objects by coercing their type:
///
/// ```
/// trait FooTrait {}
///
/// struct FooStruct;
/// impl FooTrait for FooStruct {}
///
/// let _ = KBox::new(FooStruct, GFP_KERNEL)? as KBox<dyn FooTrait>;
/// # Ok::<(), Error>(())
/// ```
///
/// # Invariants
///
/// `self.0` is always properly aligned and either points to memory allocated with `A` or, for
/// zero-sized types, is a dangling, well aligned pointer.
#[repr(transparent)]
pub struct Box<T: ?Sized, A: Allocator>(NonNull<T>, PhantomData<A>);
#[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, derive(core::marker::CoercePointee))]
pub struct Box<#[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, pointee)] T: ?Sized, A: Allocator>(
NonNull<T>,
PhantomData<A>,
);
// This is to allow coercion from `Box<T, A>` to `Box<U, A>` if `T` can be converted to the
// dynamically-sized type (DST) `U`.
#[cfg(not(CONFIG_RUSTC_HAS_COERCE_POINTEE))]
impl<T, U, A> core::ops::CoerceUnsized<Box<U, A>> for Box<T, A>
where
T: ?Sized + core::marker::Unsize<U>,
U: ?Sized,
A: Allocator,
{
}
// This is to allow `Box<U, A>` to be dispatched on when `Box<T, A>` can be coerced into `Box<U,
// A>`.
#[cfg(not(CONFIG_RUSTC_HAS_COERCE_POINTEE))]
impl<T, U, A> core::ops::DispatchFromDyn<Box<U, A>> for Box<T, A>
where
T: ?Sized + core::marker::Unsize<U>,
U: ?Sized,
A: Allocator,
{
}
/// Type alias for [`Box`] with a [`Kmalloc`] allocator.
///
@ -101,7 +139,7 @@ pub type VBox<T> = Box<T, super::allocator::Vmalloc>;
pub type KVBox<T> = Box<T, super::allocator::KVmalloc>;
// SAFETY: All zeros is equivalent to `None` (option layout optimization guarantee:
// https://doc.rust-lang.org/stable/std/option/index.html#representation).
// <https://doc.rust-lang.org/stable/std/option/index.html#representation>).
unsafe impl<T, A: Allocator> ZeroableOption for Box<T, A> {}
// SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`.
@ -360,68 +398,70 @@ where
}
}
impl<T: 'static, A> ForeignOwnable for Box<T, A>
// SAFETY: The `into_foreign` function returns a pointer that is well-aligned.
unsafe impl<T: 'static, A> ForeignOwnable for Box<T, A>
where
A: Allocator,
{
type PointedTo = T;
type Borrowed<'a> = &'a T;
type BorrowedMut<'a> = &'a mut T;
fn into_foreign(self) -> *mut crate::ffi::c_void {
Box::into_raw(self).cast()
fn into_foreign(self) -> *mut Self::PointedTo {
Box::into_raw(self)
}
unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {
unsafe fn from_foreign(ptr: *mut Self::PointedTo) -> Self {
// SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
// call to `Self::into_foreign`.
unsafe { Box::from_raw(ptr.cast()) }
unsafe { Box::from_raw(ptr) }
}
unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> &'a T {
unsafe fn borrow<'a>(ptr: *mut Self::PointedTo) -> &'a T {
// SAFETY: The safety requirements of this method ensure that the object remains alive and
// immutable for the duration of 'a.
unsafe { &*ptr.cast() }
unsafe { &*ptr }
}
unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> &'a mut T {
let ptr = ptr.cast();
unsafe fn borrow_mut<'a>(ptr: *mut Self::PointedTo) -> &'a mut T {
// SAFETY: The safety requirements of this method ensure that the pointer is valid and that
// nothing else will access the value for the duration of 'a.
unsafe { &mut *ptr }
}
}
impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
// SAFETY: The `into_foreign` function returns a pointer that is well-aligned.
unsafe impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
where
A: Allocator,
{
type PointedTo = T;
type Borrowed<'a> = Pin<&'a T>;
type BorrowedMut<'a> = Pin<&'a mut T>;
fn into_foreign(self) -> *mut crate::ffi::c_void {
fn into_foreign(self) -> *mut Self::PointedTo {
// SAFETY: We are still treating the box as pinned.
Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }).cast()
Box::into_raw(unsafe { Pin::into_inner_unchecked(self) })
}
unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {
unsafe fn from_foreign(ptr: *mut Self::PointedTo) -> Self {
// SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
// call to `Self::into_foreign`.
unsafe { Pin::new_unchecked(Box::from_raw(ptr.cast())) }
unsafe { Pin::new_unchecked(Box::from_raw(ptr)) }
}
unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> Pin<&'a T> {
unsafe fn borrow<'a>(ptr: *mut Self::PointedTo) -> Pin<&'a T> {
// SAFETY: The safety requirements for this function ensure that the object is still alive,
// so it is safe to dereference the raw pointer.
// The safety requirements of `from_foreign` also ensure that the object remains alive for
// the lifetime of the returned value.
let r = unsafe { &*ptr.cast() };
let r = unsafe { &*ptr };
// SAFETY: This pointer originates from a `Pin<Box<T>>`.
unsafe { Pin::new_unchecked(r) }
}
unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> Pin<&'a mut T> {
let ptr = ptr.cast();
unsafe fn borrow_mut<'a>(ptr: *mut Self::PointedTo) -> Pin<&'a mut T> {
// SAFETY: The safety requirements for this function ensure that the object is still alive,
// so it is safe to dereference the raw pointer.
// The safety requirements of `from_foreign` also ensure that the object remains alive for

433
rust/kernel/alloc/kvec.rs
View file

@ -2,9 +2,6 @@
//! Implementation of [`Vec`].
// May not be needed in Rust 1.87.0 (pending beta backport).
#![allow(clippy::ptr_eq)]
use super::{
allocator::{KVmalloc, Kmalloc, Vmalloc},
layout::ArrayLayout,
@ -24,6 +21,9 @@ use core::{
slice::SliceIndex,
};
mod errors;
pub use self::errors::{InsertError, PushError, RemoveError};
/// Create a [`KVec`] containing the arguments.
///
/// New memory is allocated with `GFP_KERNEL`.
@ -93,6 +93,8 @@ macro_rules! kvec {
/// without re-allocation. For ZSTs `self.layout`'s capacity is zero. However, it is legal for the
/// backing buffer to be larger than `layout`.
///
/// - `self.len()` is always less than or equal to `self.capacity()`.
///
/// - The `Allocator` type `A` of the vector is the exact same `Allocator` type the backing buffer
/// was allocated with (and must be freed with).
pub struct Vec<T, A: Allocator> {
@ -186,17 +188,38 @@ where
self.len
}
/// Forcefully sets `self.len` to `new_len`.
/// Increments `self.len` by `additional`.
///
/// # Safety
///
/// - `new_len` must be less than or equal to [`Self::capacity`].
/// - If `new_len` is greater than `self.len`, all elements within the interval
/// [`self.len`,`new_len`) must be initialized.
/// - `additional` must be less than or equal to `self.capacity - self.len`.
/// - All elements within the interval [`self.len`,`self.len + additional`) must be initialized.
#[inline]
pub unsafe fn set_len(&mut self, new_len: usize) {
debug_assert!(new_len <= self.capacity());
self.len = new_len;
pub unsafe fn inc_len(&mut self, additional: usize) {
// Guaranteed by the type invariant to never underflow.
debug_assert!(additional <= self.capacity() - self.len());
// INVARIANT: By the safety requirements of this method this represents the exact number of
// elements stored within `self`.
self.len += additional;
}
/// Decreases `self.len` by `count`.
///
/// Returns a mutable slice to the elements forgotten by the vector. It is the caller's
/// responsibility to drop these elements if necessary.
///
/// # Safety
///
/// - `count` must be less than or equal to `self.len`.
unsafe fn dec_len(&mut self, count: usize) -> &mut [T] {
debug_assert!(count <= self.len());
// INVARIANT: We relinquish ownership of the elements within the range `[self.len - count,
// self.len)`, hence the updated value of `set.len` represents the exact number of elements
// stored within `self`.
self.len -= count;
// SAFETY: The memory after `self.len()` is guaranteed to contain `count` initialized
// elements of type `T`.
unsafe { slice::from_raw_parts_mut(self.as_mut_ptr().add(self.len), count) }
}
/// Returns a slice of the entire vector.
@ -262,8 +285,8 @@ where
/// Returns a slice of `MaybeUninit<T>` for the remaining spare capacity of the vector.
pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] {
// SAFETY:
// - `self.len` is smaller than `self.capacity` and hence, the resulting pointer is
// guaranteed to be part of the same allocated object.
// - `self.len` is smaller than `self.capacity` by the type invariant and hence, the
// resulting pointer is guaranteed to be part of the same allocated object.
// - `self.len` can not overflow `isize`.
let ptr = unsafe { self.as_mut_ptr().add(self.len) } as *mut MaybeUninit<T>;
@ -287,24 +310,170 @@ where
/// ```
pub fn push(&mut self, v: T, flags: Flags) -> Result<(), AllocError> {
self.reserve(1, flags)?;
// SAFETY: The call to `reserve` was successful, so the capacity is at least one greater
// than the length.
unsafe { self.push_within_capacity_unchecked(v) };
Ok(())
}
// SAFETY:
// - `self.len` is smaller than `self.capacity` and hence, the resulting pointer is
// guaranteed to be part of the same allocated object.
// - `self.len` can not overflow `isize`.
let ptr = unsafe { self.as_mut_ptr().add(self.len) };
/// Appends an element to the back of the [`Vec`] instance without reallocating.
///
/// Fails if the vector does not have capacity for the new element.
///
/// # Examples
///
/// ```
/// let mut v = KVec::with_capacity(10, GFP_KERNEL)?;
/// for i in 0..10 {
/// v.push_within_capacity(i)?;
/// }
///
/// assert!(v.push_within_capacity(10).is_err());
/// # Ok::<(), Error>(())
/// ```
pub fn push_within_capacity(&mut self, v: T) -> Result<(), PushError<T>> {
if self.len() < self.capacity() {
// SAFETY: The length is less than the capacity.
unsafe { self.push_within_capacity_unchecked(v) };
Ok(())
} else {
Err(PushError(v))
}
}
// SAFETY:
// - `ptr` is properly aligned and valid for writes.
unsafe { core::ptr::write(ptr, v) };
/// Appends an element to the back of the [`Vec`] instance without reallocating.
///
/// # Safety
///
/// The length must be less than the capacity.
unsafe fn push_within_capacity_unchecked(&mut self, v: T) {
let spare = self.spare_capacity_mut();
// SAFETY: By the safety requirements, `spare` is non-empty.
unsafe { spare.get_unchecked_mut(0) }.write(v);
// SAFETY: We just initialised the first spare entry, so it is safe to increase the length
// by 1. We also know that the new length is <= capacity because of the previous call to
// `reserve` above.
unsafe { self.set_len(self.len() + 1) };
// by 1. We also know that the new length is <= capacity because the caller guarantees that
// the length is less than the capacity at the beginning of this function.
unsafe { self.inc_len(1) };
}
/// Inserts an element at the given index in the [`Vec`] instance.
///
/// Fails if the vector does not have capacity for the new element. Panics if the index is out
/// of bounds.
///
/// # Examples
///
/// ```
/// use kernel::alloc::kvec::InsertError;
///
/// let mut v = KVec::with_capacity(5, GFP_KERNEL)?;
/// for i in 0..5 {
/// v.insert_within_capacity(0, i)?;
/// }
///
/// assert!(matches!(v.insert_within_capacity(0, 5), Err(InsertError::OutOfCapacity(_))));
/// assert!(matches!(v.insert_within_capacity(1000, 5), Err(InsertError::IndexOutOfBounds(_))));
/// assert_eq!(v, [4, 3, 2, 1, 0]);
/// # Ok::<(), Error>(())
/// ```
pub fn insert_within_capacity(
&mut self,
index: usize,
element: T,
) -> Result<(), InsertError<T>> {
let len = self.len();
if index > len {
return Err(InsertError::IndexOutOfBounds(element));
}
if len >= self.capacity() {
return Err(InsertError::OutOfCapacity(element));
}
// SAFETY: This is in bounds since `index <= len < capacity`.
let p = unsafe { self.as_mut_ptr().add(index) };
// INVARIANT: This breaks the Vec invariants by making `index` contain an invalid element,
// but we restore the invariants below.
// SAFETY: Both the src and dst ranges end no later than one element after the length.
// Since the length is less than the capacity, both ranges are in bounds of the allocation.
unsafe { ptr::copy(p, p.add(1), len - index) };
// INVARIANT: This restores the Vec invariants.
// SAFETY: The pointer is in-bounds of the allocation.
unsafe { ptr::write(p, element) };
// SAFETY: Index `len` contains a valid element due to the above copy and write.
unsafe { self.inc_len(1) };
Ok(())
}
/// Removes the last element from a vector and returns it, or `None` if it is empty.
///
/// # Examples
///
/// ```
/// let mut v = KVec::new();
/// v.push(1, GFP_KERNEL)?;
/// v.push(2, GFP_KERNEL)?;
/// assert_eq!(&v, &[1, 2]);
///
/// assert_eq!(v.pop(), Some(2));
/// assert_eq!(v.pop(), Some(1));
/// assert_eq!(v.pop(), None);
/// # Ok::<(), Error>(())
/// ```
pub fn pop(&mut self) -> Option<T> {
if self.is_empty() {
return None;
}
let removed: *mut T = {
// SAFETY: We just checked that the length is at least one.
let slice = unsafe { self.dec_len(1) };
// SAFETY: The argument to `dec_len` was 1 so this returns a slice of length 1.
unsafe { slice.get_unchecked_mut(0) }
};
// SAFETY: The guarantees of `dec_len` allow us to take ownership of this value.
Some(unsafe { removed.read() })
}
/// Removes the element at the given index.
///
/// # Examples
///
/// ```
/// let mut v = kernel::kvec![1, 2, 3]?;
/// assert_eq!(v.remove(1)?, 2);
/// assert_eq!(v, [1, 3]);
/// # Ok::<(), Error>(())
/// ```
pub fn remove(&mut self, i: usize) -> Result<T, RemoveError> {
let value = {
let value_ref = self.get(i).ok_or(RemoveError)?;
// INVARIANT: This breaks the invariants by invalidating the value at index `i`, but we
// restore the invariants below.
// SAFETY: The value at index `i` is valid, because otherwise we would have already
// failed with `RemoveError`.
unsafe { ptr::read(value_ref) }
};
// SAFETY: We checked that `i` is in-bounds.
let p = unsafe { self.as_mut_ptr().add(i) };
// INVARIANT: After this call, the invalid value is at the last slot, so the Vec invariants
// are restored after the below call to `dec_len(1)`.
// SAFETY: `p.add(1).add(self.len - i - 1)` is `i+1+len-i-1 == len` elements after the
// beginning of the vector, so this is in-bounds of the vector's allocation.
unsafe { ptr::copy(p.add(1), p, self.len - i - 1) };
// SAFETY: Since the check at the beginning of this call did not fail with `RemoveError`,
// the length is at least one.
unsafe { self.dec_len(1) };
Ok(value)
}
/// Creates a new [`Vec`] instance with at least the given capacity.
///
/// # Examples
@ -398,6 +567,26 @@ where
(ptr, len, capacity)
}
/// Clears the vector, removing all values.
///
/// Note that this method has no effect on the allocated capacity
/// of the vector.
///
/// # Examples
///
/// ```
/// let mut v = kernel::kvec![1, 2, 3]?;
///
/// v.clear();
///
/// assert!(v.is_empty());
/// # Ok::<(), Error>(())
/// ```
#[inline]
pub fn clear(&mut self) {
self.truncate(0);
}
/// Ensures that the capacity exceeds the length by at least `additional` elements.
///
/// # Examples
@ -455,6 +644,80 @@ where
Ok(())
}
/// Shortens the vector, setting the length to `len` and drops the removed values.
/// If `len` is greater than or equal to the current length, this does nothing.
///
/// This has no effect on the capacity and will not allocate.
///
/// # Examples
///
/// ```
/// let mut v = kernel::kvec![1, 2, 3]?;
/// v.truncate(1);
/// assert_eq!(v.len(), 1);
/// assert_eq!(&v, &[1]);
///
/// # Ok::<(), Error>(())
/// ```
pub fn truncate(&mut self, len: usize) {
if let Some(count) = self.len().checked_sub(len) {
// SAFETY: `count` is `self.len() - len` so it is guaranteed to be less than or
// equal to `self.len()`.
let ptr: *mut [T] = unsafe { self.dec_len(count) };
// SAFETY: the contract of `dec_len` guarantees that the elements in `ptr` are
// valid elements whose ownership has been transferred to the caller.
unsafe { ptr::drop_in_place(ptr) };
}
}
/// Takes ownership of all items in this vector without consuming the allocation.
///
/// # Examples
///
/// ```
/// let mut v = kernel::kvec![0, 1, 2, 3]?;
///
/// for (i, j) in v.drain_all().enumerate() {
/// assert_eq!(i, j);
/// }
///
/// assert!(v.capacity() >= 4);
/// # Ok::<(), Error>(())
/// ```
pub fn drain_all(&mut self) -> DrainAll<'_, T> {
// SAFETY: This does not underflow the length.
let elems = unsafe { self.dec_len(self.len()) };
// INVARIANT: The first `len` elements of the spare capacity are valid values, and as we
// just set the length to zero, we may transfer ownership to the `DrainAll` object.
DrainAll {
elements: elems.iter_mut(),
}
}
/// Removes all elements that don't match the provided closure.
///
/// # Examples
///
/// ```
/// let mut v = kernel::kvec![1, 2, 3, 4]?;
/// v.retain(|i| *i % 2 == 0);
/// assert_eq!(v, [2, 4]);
/// # Ok::<(), Error>(())
/// ```
pub fn retain(&mut self, mut f: impl FnMut(&mut T) -> bool) {
let mut num_kept = 0;
let mut next_to_check = 0;
while let Some(to_check) = self.get_mut(next_to_check) {
if f(to_check) {
self.swap(num_kept, next_to_check);
num_kept += 1;
}
next_to_check += 1;
}
self.truncate(num_kept);
}
}
impl<T: Clone, A: Allocator> Vec<T, A> {
@ -478,7 +741,7 @@ impl<T: Clone, A: Allocator> Vec<T, A> {
// SAFETY:
// - `self.len() + n < self.capacity()` due to the call to reserve above,
// - the loop and the line above initialized the next `n` elements.
unsafe { self.set_len(self.len() + n) };
unsafe { self.inc_len(n) };
Ok(())
}
@ -509,7 +772,7 @@ impl<T: Clone, A: Allocator> Vec<T, A> {
// the length by the same number.
// - `self.len() + other.len() <= self.capacity()` is guaranteed by the preceding `reserve`
// call.
unsafe { self.set_len(self.len() + other.len()) };
unsafe { self.inc_len(other.len()) };
Ok(())
}
@ -521,6 +784,33 @@ impl<T: Clone, A: Allocator> Vec<T, A> {
Ok(v)
}
/// Resizes the [`Vec`] so that `len` is equal to `new_len`.
///
/// If `new_len` is smaller than `len`, the `Vec` is [`Vec::truncate`]d.
/// If `new_len` is larger, each new slot is filled with clones of `value`.
///
/// # Examples
///
/// ```
/// let mut v = kernel::kvec![1, 2, 3]?;
/// v.resize(1, 42, GFP_KERNEL)?;
/// assert_eq!(&v, &[1]);
///
/// v.resize(3, 42, GFP_KERNEL)?;
/// assert_eq!(&v, &[1, 42, 42]);
///
/// # Ok::<(), Error>(())
/// ```
pub fn resize(&mut self, new_len: usize, value: T, flags: Flags) -> Result<(), AllocError> {
match new_len.checked_sub(self.len()) {
Some(n) => self.extend_with(n, value, flags),
None => {
self.truncate(new_len);
Ok(())
}
}
}
}
impl<T, A> Drop for Vec<T, A>
@ -760,12 +1050,13 @@ where
unsafe { ptr::copy(ptr, buf.as_ptr(), len) };
ptr = buf.as_ptr();
// SAFETY: `len` is guaranteed to be smaller than `self.layout.len()`.
// SAFETY: `len` is guaranteed to be smaller than `self.layout.len()` by the type
// invariant.
let layout = unsafe { ArrayLayout::<T>::new_unchecked(len) };
// SAFETY: `buf` points to the start of the backing buffer and `len` is guaranteed to be
// smaller than `cap`. Depending on `alloc` this operation may shrink the buffer or leaves
// it as it is.
// SAFETY: `buf` points to the start of the backing buffer and `len` is guaranteed by
// the type invariant to be smaller than `cap`. Depending on `realloc` this operation
// may shrink the buffer or leave it as it is.
ptr = match unsafe {
A::realloc(Some(buf.cast()), layout.into(), old_layout.into(), flags)
} {
@ -914,3 +1205,87 @@ where
}
}
}
/// An iterator that owns all items in a vector, but does not own its allocation.
///
/// # Invariants
///
/// Every `&mut T` returned by the iterator references a `T` that the iterator may take ownership
/// of.
pub struct DrainAll<'vec, T> {
elements: slice::IterMut<'vec, T>,
}
impl<'vec, T> Iterator for DrainAll<'vec, T> {
type Item = T;
fn next(&mut self) -> Option<T> {
let elem: *mut T = self.elements.next()?;
// SAFETY: By the type invariants, we may take ownership of this value.
Some(unsafe { elem.read() })
}
fn size_hint(&self) -> (usize, Option<usize>) {
self.elements.size_hint()
}
}
impl<'vec, T> Drop for DrainAll<'vec, T> {
fn drop(&mut self) {
if core::mem::needs_drop::<T>() {
let iter = core::mem::take(&mut self.elements);
let ptr: *mut [T] = iter.into_slice();
// SAFETY: By the type invariants, we own these values so we may destroy them.
unsafe { ptr::drop_in_place(ptr) };
}
}
}
#[macros::kunit_tests(rust_kvec_kunit)]
mod tests {
use super::*;
use crate::prelude::*;
#[test]
fn test_kvec_retain() {
/// Verify correctness for one specific function.
#[expect(clippy::needless_range_loop)]
fn verify(c: &[bool]) {
let mut vec1: KVec<usize> = KVec::with_capacity(c.len(), GFP_KERNEL).unwrap();
let mut vec2: KVec<usize> = KVec::with_capacity(c.len(), GFP_KERNEL).unwrap();
for i in 0..c.len() {
vec1.push_within_capacity(i).unwrap();
if c[i] {
vec2.push_within_capacity(i).unwrap();
}
}
vec1.retain(|i| c[*i]);
assert_eq!(vec1, vec2);
}
/// Add one to a binary integer represented as a boolean array.
fn add(value: &mut [bool]) {
let mut carry = true;
for v in value {
let new_v = carry != *v;
carry = carry && *v;
*v = new_v;
}
}
// This boolean array represents a function from index to boolean. We check that `retain`
// behaves correctly for all possible boolean arrays of every possible length less than
// ten.
let mut func = KVec::with_capacity(10, GFP_KERNEL).unwrap();
for len in 0..10 {
for _ in 0u32..1u32 << len {
verify(&func);
add(&mut func);
}
func.push_within_capacity(false).unwrap();
}
}
}

61
rust/kernel/alloc/kvec/errors.rs Normal file
View file

@ -0,0 +1,61 @@
// SPDX-License-Identifier: GPL-2.0
//! Errors for the [`Vec`] type.
use core::fmt::{self, Debug, Formatter};
use kernel::prelude::*;
/// Error type for [`Vec::push_within_capacity`].
pub struct PushError<T>(pub T);
impl<T> Debug for PushError<T> {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
write!(f, "Not enough capacity")
}
}
impl<T> From<PushError<T>> for Error {
fn from(_: PushError<T>) -> Error {
// Returning ENOMEM isn't appropriate because the system is not out of memory. The vector
// is just full and we are refusing to resize it.
EINVAL
}
}
/// Error type for [`Vec::remove`].
pub struct RemoveError;
impl Debug for RemoveError {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
write!(f, "Index out of bounds")
}
}
impl From<RemoveError> for Error {
fn from(_: RemoveError) -> Error {
EINVAL
}
}
/// Error type for [`Vec::insert_within_capacity`].
pub enum InsertError<T> {
/// The value could not be inserted because the index is out of bounds.
IndexOutOfBounds(T),
/// The value could not be inserted because the vector is out of capacity.
OutOfCapacity(T),
}
impl<T> Debug for InsertError<T> {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
match self {
InsertError::IndexOutOfBounds(_) => write!(f, "Index out of bounds"),
InsertError::OutOfCapacity(_) => write!(f, "Not enough capacity"),
}
}
}
impl<T> From<InsertError<T>> for Error {
fn from(_: InsertError<T>) -> Error {
EINVAL
}
}

8
rust/kernel/auxiliary.rs
View file

@ -73,7 +73,9 @@ impl<T: Driver + 'static> Adapter<T> {
// Let the `struct auxiliary_device` own a reference of the driver's private data.
// SAFETY: By the type invariant `adev.as_raw` returns a valid pointer to a
// `struct auxiliary_device`.
unsafe { bindings::auxiliary_set_drvdata(adev.as_raw(), data.into_foreign()) };
unsafe {
bindings::auxiliary_set_drvdata(adev.as_raw(), data.into_foreign().cast())
};
}
Err(err) => return Error::to_errno(err),
}
@ -89,7 +91,7 @@ impl<T: Driver + 'static> Adapter<T> {
// SAFETY: `remove_callback` is only ever called after a successful call to
// `probe_callback`, hence it's guaranteed that `ptr` points to a valid and initialized
// `KBox<T>` pointer created through `KBox::into_foreign`.
drop(unsafe { KBox::<T>::from_foreign(ptr) });
drop(unsafe { KBox::<T>::from_foreign(ptr.cast()) });
}
}
@ -234,7 +236,7 @@ impl Device {
extern "C" fn release(dev: *mut bindings::device) {
// SAFETY: By the type invariant `self.0.as_raw` is a pointer to the `struct device`
// embedded in `struct auxiliary_device`.
let adev = unsafe { container_of!(dev, bindings::auxiliary_device, dev) }.cast_mut();
let adev = unsafe { container_of!(dev, bindings::auxiliary_device, dev) };
// SAFETY: `adev` points to the memory that has been allocated in `Registration::new`, via
// `KBox::new(Opaque::<bindings::auxiliary_device>::zeroed(), GFP_KERNEL)`.

2
rust/kernel/block/mq/gen_disk.rs
View file

@ -129,7 +129,7 @@ impl GenDiskBuilder {
get_unique_id: None,
// TODO: Set to THIS_MODULE. Waiting for const_refs_to_static feature to
// be merged (unstable in rustc 1.78 which is staged for linux 6.10)
// https://github.com/rust-lang/rust/issues/119618
// <https://github.com/rust-lang/rust/issues/119618>
owner: core::ptr::null_mut(),
pr_ops: core::ptr::null_mut(),
free_disk: None,

4
rust/kernel/configfs.rs
View file

@ -554,7 +554,7 @@ where
let c_group: *mut bindings::config_group =
// SAFETY: By function safety requirements, `item` is embedded in a
// `config_group`.
unsafe { container_of!(item, bindings::config_group, cg_item) }.cast_mut();
unsafe { container_of!(item, bindings::config_group, cg_item) };
// SAFETY: The function safety requirements for this function satisfy
// the conditions for this call.
@ -588,7 +588,7 @@ where
let c_group: *mut bindings::config_group =
// SAFETY: By function safety requirements, `item` is embedded in a
// `config_group`.
unsafe { container_of!(item, bindings::config_group, cg_item) }.cast_mut();
unsafe { container_of!(item, bindings::config_group, cg_item) };
// SAFETY: The function safety requirements for this function satisfy
// the conditions for this call.

4
rust/kernel/cpufreq.rs
View file

@ -635,7 +635,7 @@ impl Policy {
None
} else {
// SAFETY: The data is earlier set from [`set_data`].
Some(unsafe { T::borrow(self.as_ref().driver_data) })
Some(unsafe { T::borrow(self.as_ref().driver_data.cast()) })
}
}
@ -662,7 +662,7 @@ impl Policy {
let data = Some(
// SAFETY: The data is earlier set by us from [`set_data`]. It is safe to take
// back the ownership of the data from the foreign interface.
unsafe { <T as ForeignOwnable>::from_foreign(self.as_ref().driver_data) },
unsafe { <T as ForeignOwnable>::from_foreign(self.as_ref().driver_data.cast()) },
);
self.as_mut_ref().driver_data = ptr::null_mut();
data

26
rust/kernel/device.rs
View file

@ -345,7 +345,7 @@ macro_rules! impl_device_context_into_aref {
macro_rules! dev_printk {
($method:ident, $dev:expr, $($f:tt)*) => {
{
($dev).$method(core::format_args!($($f)*));
($dev).$method(::core::format_args!($($f)*));
}
}
}
@ -357,9 +357,10 @@ macro_rules! dev_printk {
/// Equivalent to the kernel's `dev_emerg` macro.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -382,9 +383,10 @@ macro_rules! dev_emerg {
/// Equivalent to the kernel's `dev_alert` macro.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -407,9 +409,10 @@ macro_rules! dev_alert {
/// Equivalent to the kernel's `dev_crit` macro.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -432,9 +435,10 @@ macro_rules! dev_crit {
/// Equivalent to the kernel's `dev_err` macro.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -457,9 +461,10 @@ macro_rules! dev_err {
/// Equivalent to the kernel's `dev_warn` macro.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -482,9 +487,10 @@ macro_rules! dev_warn {
/// Equivalent to the kernel's `dev_notice` macro.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -507,9 +513,10 @@ macro_rules! dev_notice {
/// Equivalent to the kernel's `dev_info` macro.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -532,9 +539,10 @@ macro_rules! dev_info {
/// Equivalent to the kernel's `dev_dbg` macro, except that it doesn't support dynamic debug yet.
///
/// Mimics the interface of [`std::print!`]. More information about the syntax is available from
/// [`core::fmt`] and `alloc::format!`.
/// [`core::fmt`] and [`std::format!`].
///
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///

4
rust/kernel/device_id.rs
View file

@ -159,7 +159,7 @@ macro_rules! module_device_table {
"_", line!(),
"_", stringify!($table_name))
]
static $module_table_name: [core::mem::MaybeUninit<u8>; $table_name.raw_ids().size()] =
unsafe { core::mem::transmute_copy($table_name.raw_ids()) };
static $module_table_name: [::core::mem::MaybeUninit<u8>; $table_name.raw_ids().size()] =
unsafe { ::core::mem::transmute_copy($table_name.raw_ids()) };
};
}

2
rust/kernel/dma.rs
View file

@ -94,7 +94,7 @@ pub mod attrs {
pub const DMA_ATTR_ALLOC_SINGLE_PAGES: Attrs = Attrs(bindings::DMA_ATTR_ALLOC_SINGLE_PAGES);
/// This tells the DMA-mapping subsystem to suppress allocation failure reports (similarly to
/// __GFP_NOWARN).
/// `__GFP_NOWARN`).
pub const DMA_ATTR_NO_WARN: Attrs = Attrs(bindings::DMA_ATTR_NO_WARN);
/// Used to indicate that the buffer is fully accessible at an elevated privilege level (and

2
rust/kernel/drm/device.rs
View file

@ -135,6 +135,8 @@ impl<T: drm::Driver> Device<T> {
///
/// `ptr` must be a valid pointer to a `struct device` embedded in `Self`.
unsafe fn from_drm_device(ptr: *const bindings::drm_device) -> *mut Self {
let ptr: *const Opaque<bindings::drm_device> = ptr.cast();
// SAFETY: By the safety requirements of this function `ptr` is a valid pointer to a
// `struct drm_device` embedded in `Self`.
unsafe { crate::container_of!(ptr, Self, dev) }.cast_mut()

6
rust/kernel/drm/gem/mod.rs
View file

@ -125,6 +125,8 @@ impl<T: DriverObject> IntoGEMObject for Object<T> {
}
unsafe fn as_ref<'a>(self_ptr: *mut bindings::drm_gem_object) -> &'a Self {
let self_ptr: *mut Opaque<bindings::drm_gem_object> = self_ptr.cast();
// SAFETY: `obj` is guaranteed to be in an `Object<T>` via the safety contract of this
// function
unsafe { &*crate::container_of!(self_ptr, Object<T>, obj) }
@ -269,8 +271,10 @@ impl<T: DriverObject> Object<T> {
}
extern "C" fn free_callback(obj: *mut bindings::drm_gem_object) {
let ptr: *mut Opaque<bindings::drm_gem_object> = obj.cast();
// SAFETY: All of our objects are of type `Object<T>`.
let this = unsafe { crate::container_of!(obj, Self, obj) }.cast_mut();
let this = unsafe { crate::container_of!(ptr, Self, obj) };
// SAFETY: The C code only ever calls this callback with a valid pointer to a `struct
// drm_gem_object`.

37
rust/kernel/kunit.rs
View file

@ -6,6 +6,7 @@
//!
//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
use crate::prelude::*;
use core::{ffi::c_void, fmt};
/// Prints a KUnit error-level message.
@ -40,8 +41,6 @@ pub fn info(args: fmt::Arguments<'_>) {
}
}
use macros::kunit_tests;
/// Asserts that a boolean expression is `true` at runtime.
///
/// Public but hidden since it should only be used from generated tests.
@ -59,7 +58,7 @@ macro_rules! kunit_assert {
}
static FILE: &'static $crate::str::CStr = $crate::c_str!($file);
static LINE: i32 = core::line!() as i32 - $diff;
static LINE: i32 = ::core::line!() as i32 - $diff;
static CONDITION: &'static $crate::str::CStr = $crate::c_str!(stringify!($condition));
// SAFETY: FFI call without safety requirements.
@ -130,11 +129,11 @@ macro_rules! kunit_assert {
unsafe {
$crate::bindings::__kunit_do_failed_assertion(
kunit_test,
core::ptr::addr_of!(LOCATION.0),
::core::ptr::addr_of!(LOCATION.0),
$crate::bindings::kunit_assert_type_KUNIT_ASSERTION,
core::ptr::addr_of!(ASSERTION.0.assert),
::core::ptr::addr_of!(ASSERTION.0.assert),
Some($crate::bindings::kunit_unary_assert_format),
core::ptr::null(),
::core::ptr::null(),
);
}
@ -164,6 +163,31 @@ macro_rules! kunit_assert_eq {
}};
}
trait TestResult {
fn is_test_result_ok(&self) -> bool;
}
impl TestResult for () {
fn is_test_result_ok(&self) -> bool {
true
}
}
impl<T, E> TestResult for Result<T, E> {
fn is_test_result_ok(&self) -> bool {
self.is_ok()
}
}
/// Returns whether a test result is to be considered OK.
///
/// This will be `assert!`ed from the generated tests.
#[doc(hidden)]
#[expect(private_bounds)]
pub fn is_test_result_ok(t: impl TestResult) -> bool {
t.is_test_result_ok()
}
/// Represents an individual test case.
///
/// The [`kunit_unsafe_test_suite!`] macro expects a NULL-terminated list of valid test cases.
@ -323,7 +347,6 @@ mod tests {
#[test]
fn rust_test_kunit_example_test() {
#![expect(clippy::eq_op)]
assert_eq!(1 + 1, 2);
}

45
rust/kernel/lib.rs
View file

@ -12,20 +12,34 @@
//! do so first instead of bypassing this crate.
#![no_std]
#![feature(arbitrary_self_types)]
#![cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, feature(derive_coerce_pointee))]
#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(coerce_unsized))]
#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(dispatch_from_dyn))]
#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(unsize))]
//
// Please see https://github.com/Rust-for-Linux/linux/issues/2 for details on
// the unstable features in use.
//
// Stable since Rust 1.79.0.
#![feature(inline_const)]
//
// Stable since Rust 1.81.0.
#![feature(lint_reasons)]
// Stable in Rust 1.82
//
// Stable since Rust 1.82.0.
#![feature(raw_ref_op)]
// Stable in Rust 1.83
//
// Stable since Rust 1.83.0.
#![feature(const_maybe_uninit_as_mut_ptr)]
#![feature(const_mut_refs)]
#![feature(const_ptr_write)]
#![feature(const_refs_to_cell)]
//
// Expected to become stable.
#![feature(arbitrary_self_types)]
//
// `feature(derive_coerce_pointee)` is expected to become stable. Before Rust
// 1.84.0, it did not exist, so enable the predecessor features.
#![cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, feature(derive_coerce_pointee))]
#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(coerce_unsized))]
#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(dispatch_from_dyn))]
#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(unsize))]
// Ensure conditional compilation based on the kernel configuration works;
// otherwise we may silently break things like initcall handling.
@ -102,6 +116,7 @@ pub mod transmute;
pub mod types;
pub mod uaccess;
pub mod workqueue;
pub mod xarray;
#[doc(hidden)]
pub use bindings;
@ -204,7 +219,7 @@ fn panic(info: &core::panic::PanicInfo<'_>) -> ! {
/// }
///
/// let test = Test { a: 10, b: 20 };
/// let b_ptr = &test.b;
/// let b_ptr: *const _ = &test.b;
/// // SAFETY: The pointer points at the `b` field of a `Test`, so the resulting pointer will be
/// // in-bounds of the same allocation as `b_ptr`.
/// let test_alias = unsafe { container_of!(b_ptr, Test, b) };
@ -212,13 +227,19 @@ fn panic(info: &core::panic::PanicInfo<'_>) -> ! {
/// ```
#[macro_export]
macro_rules! container_of {
($ptr:expr, $type:ty, $($f:tt)*) => {{
let ptr = $ptr as *const _ as *const u8;
let offset: usize = ::core::mem::offset_of!($type, $($f)*);
ptr.sub(offset) as *const $type
($field_ptr:expr, $Container:ty, $($fields:tt)*) => {{
let offset: usize = ::core::mem::offset_of!($Container, $($fields)*);
let field_ptr = $field_ptr;
let container_ptr = field_ptr.byte_sub(offset).cast::<$Container>();
$crate::assert_same_type(field_ptr, (&raw const (*container_ptr).$($fields)*).cast_mut());
container_ptr
}}
}
/// Helper for [`container_of!`].
#[doc(hidden)]
pub fn assert_same_type<T>(_: T, _: T) {}
/// Helper for `.rs.S` files.
#[doc(hidden)]
#[macro_export]

115
rust/kernel/list.rs
View file

@ -4,9 +4,6 @@
//! A linked list implementation.
// May not be needed in Rust 1.87.0 (pending beta backport).
#![allow(clippy::ptr_eq)]
use crate::sync::ArcBorrow;
use crate::types::Opaque;
use core::iter::{DoubleEndedIterator, FusedIterator};
@ -38,6 +35,114 @@ pub use self::arc_field::{define_list_arc_field_getter, ListArcField};
/// * All prev/next pointers in `ListLinks` fields of items in the list are valid and form a cycle.
/// * For every item in the list, the list owns the associated [`ListArc`] reference and has
/// exclusive access to the `ListLinks` field.
///
/// # Examples
///
/// ```
/// use kernel::list::*;
///
/// #[pin_data]
/// struct BasicItem {
/// value: i32,
/// #[pin]
/// links: ListLinks,
/// }
///
/// impl BasicItem {
/// fn new(value: i32) -> Result<ListArc<Self>> {
/// ListArc::pin_init(try_pin_init!(Self {
/// value,
/// links <- ListLinks::new(),
/// }), GFP_KERNEL)
/// }
/// }
///
/// impl_has_list_links! {
/// impl HasListLinks<0> for BasicItem { self.links }
/// }
/// impl_list_arc_safe! {
/// impl ListArcSafe<0> for BasicItem { untracked; }
/// }
/// impl_list_item! {
/// impl ListItem<0> for BasicItem { using ListLinks; }
/// }
///
/// // Create a new empty list.
/// let mut list = List::new();
/// {
/// assert!(list.is_empty());
/// }
///
/// // Insert 3 elements using `push_back()`.
/// list.push_back(BasicItem::new(15)?);
/// list.push_back(BasicItem::new(10)?);
/// list.push_back(BasicItem::new(30)?);
///
/// // Iterate over the list to verify the nodes were inserted correctly.
/// // [15, 10, 30]
/// {
/// let mut iter = list.iter();
/// assert_eq!(iter.next().unwrap().value, 15);
/// assert_eq!(iter.next().unwrap().value, 10);
/// assert_eq!(iter.next().unwrap().value, 30);
/// assert!(iter.next().is_none());
///
/// // Verify the length of the list.
/// assert_eq!(list.iter().count(), 3);
/// }
///
/// // Pop the items from the list using `pop_back()` and verify the content.
/// {
/// assert_eq!(list.pop_back().unwrap().value, 30);
/// assert_eq!(list.pop_back().unwrap().value, 10);
/// assert_eq!(list.pop_back().unwrap().value, 15);
/// }
///
/// // Insert 3 elements using `push_front()`.
/// list.push_front(BasicItem::new(15)?);
/// list.push_front(BasicItem::new(10)?);
/// list.push_front(BasicItem::new(30)?);
///
/// // Iterate over the list to verify the nodes were inserted correctly.
/// // [30, 10, 15]
/// {
/// let mut iter = list.iter();
/// assert_eq!(iter.next().unwrap().value, 30);
/// assert_eq!(iter.next().unwrap().value, 10);
/// assert_eq!(iter.next().unwrap().value, 15);
/// assert!(iter.next().is_none());
///
/// // Verify the length of the list.
/// assert_eq!(list.iter().count(), 3);
/// }
///
/// // Pop the items from the list using `pop_front()` and verify the content.
/// {
/// assert_eq!(list.pop_front().unwrap().value, 30);
/// assert_eq!(list.pop_front().unwrap().value, 10);
/// }
///
/// // Push `list2` to `list` through `push_all_back()`.
/// // list: [15]
/// // list2: [25, 35]
/// {
/// let mut list2 = List::new();
/// list2.push_back(BasicItem::new(25)?);
/// list2.push_back(BasicItem::new(35)?);
///
/// list.push_all_back(&mut list2);
///
/// // list: [15, 25, 35]
/// // list2: []
/// let mut iter = list.iter();
/// assert_eq!(iter.next().unwrap().value, 15);
/// assert_eq!(iter.next().unwrap().value, 25);
/// assert_eq!(iter.next().unwrap().value, 35);
/// assert!(iter.next().is_none());
/// assert!(list2.is_empty());
/// }
/// # Result::<(), Error>::Ok(())
/// ```
pub struct List<T: ?Sized + ListItem<ID>, const ID: u64 = 0> {
first: *mut ListLinksFields,
_ty: PhantomData<ListArc<T, ID>>,
@ -322,7 +427,7 @@ impl<T: ?Sized + ListItem<ID>, const ID: u64> List<T, ID> {
/// Removes the last item from this list.
pub fn pop_back(&mut self) -> Option<ListArc<T, ID>> {
if self.first.is_null() {
if self.is_empty() {
return None;
}
@ -334,7 +439,7 @@ impl<T: ?Sized + ListItem<ID>, const ID: u64> List<T, ID> {
/// Removes the first item from this list.
pub fn pop_front(&mut self) -> Option<ListArc<T, ID>> {
if self.first.is_null() {
if self.is_empty() {
return None;
}

6
rust/kernel/list/arc.rs
View file

@ -74,7 +74,7 @@ pub unsafe trait TryNewListArc<const ID: u64 = 0>: ListArcSafe<ID> {
///
/// * The `untracked` strategy does not actually keep track of whether a [`ListArc`] exists. When
/// using this strategy, the only way to create a [`ListArc`] is using a [`UniqueArc`].
/// * The `tracked_by` strategy defers the tracking to a field of the struct. The user much specify
/// * The `tracked_by` strategy defers the tracking to a field of the struct. The user must specify
/// which field to defer the tracking to. The field must implement [`ListArcSafe`]. If the field
/// implements [`TryNewListArc`], then the type will also implement [`TryNewListArc`].
///
@ -96,7 +96,7 @@ macro_rules! impl_list_arc_safe {
} $($rest:tt)*) => {
impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&mut Self>) {
$crate::assert_pinned!($t, $field, $fty, inline);
::pin_init::assert_pinned!($t, $field, $fty, inline);
// SAFETY: This field is structurally pinned as per the above assertion.
let field = unsafe {
@ -464,7 +464,7 @@ where
/// A utility for tracking whether a [`ListArc`] exists using an atomic.
///
/// # Invariant
/// # Invariants
///
/// If the boolean is `false`, then there is no [`ListArc`] for this value.
#[repr(transparent)]

12
rust/kernel/miscdevice.rs
View file

@ -217,7 +217,7 @@ impl<T: MiscDevice> MiscdeviceVTable<T> {
// type.
//
// SAFETY: The open call of a file can access the private data.
unsafe { (*raw_file).private_data = ptr.into_foreign() };
unsafe { (*raw_file).private_data = ptr.into_foreign().cast() };
0
}
@ -228,7 +228,7 @@ impl<T: MiscDevice> MiscdeviceVTable<T> {
/// must be associated with a `MiscDeviceRegistration<T>`.
unsafe extern "C" fn release(_inode: *mut bindings::inode, file: *mut bindings::file) -> c_int {
// SAFETY: The release call of a file owns the private data.
let private = unsafe { (*file).private_data };
let private = unsafe { (*file).private_data }.cast();
// SAFETY: The release call of a file owns the private data.
let ptr = unsafe { <T::Ptr as ForeignOwnable>::from_foreign(private) };
@ -253,7 +253,7 @@ impl<T: MiscDevice> MiscdeviceVTable<T> {
// SAFETY: This is a Rust Miscdevice, so we call `into_foreign` in `open` and
// `from_foreign` in `release`, and `fops_mmap` is guaranteed to be called between those
// two operations.
let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private.cast()) };
// SAFETY: The caller provides a vma that is undergoing initial VMA setup.
let area = unsafe { VmaNew::from_raw(vma) };
// SAFETY:
@ -272,7 +272,7 @@ impl<T: MiscDevice> MiscdeviceVTable<T> {
/// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
unsafe extern "C" fn ioctl(file: *mut bindings::file, cmd: c_uint, arg: c_ulong) -> c_long {
// SAFETY: The ioctl call of a file can access the private data.
let private = unsafe { (*file).private_data };
let private = unsafe { (*file).private_data }.cast();
// SAFETY: Ioctl calls can borrow the private data of the file.
let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
@ -297,7 +297,7 @@ impl<T: MiscDevice> MiscdeviceVTable<T> {
arg: c_ulong,
) -> c_long {
// SAFETY: The compat ioctl call of a file can access the private data.
let private = unsafe { (*file).private_data };
let private = unsafe { (*file).private_data }.cast();
// SAFETY: Ioctl calls can borrow the private data of the file.
let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
@ -318,7 +318,7 @@ impl<T: MiscDevice> MiscdeviceVTable<T> {
/// - `seq_file` must be a valid `struct seq_file` that we can write to.
unsafe extern "C" fn show_fdinfo(seq_file: *mut bindings::seq_file, file: *mut bindings::file) {
// SAFETY: The release call of a file owns the private data.
let private = unsafe { (*file).private_data };
let private = unsafe { (*file).private_data }.cast();
// SAFETY: Ioctl calls can borrow the private data of the file.
let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
// SAFETY:

2
rust/kernel/page.rs
View file

@ -69,6 +69,7 @@ impl Page {
/// let page = Page::alloc_page(GFP_KERNEL | __GFP_ZERO)?;
/// # Ok::<(), kernel::alloc::AllocError>(())
/// ```
#[inline]
pub fn alloc_page(flags: Flags) -> Result<Self, AllocError> {
// SAFETY: Depending on the value of `gfp_flags`, this call may sleep. Other than that, it
// is always safe to call this method.
@ -251,6 +252,7 @@ impl Page {
}
impl Drop for Page {
#[inline]
fn drop(&mut self) {
// SAFETY: By the type invariants, we have ownership of the page and can free it.
unsafe { bindings::__free_pages(self.page.as_ptr(), 0) };

17
rust/kernel/pci.rs
View file

@ -89,7 +89,7 @@ impl<T: Driver + 'static> Adapter<T> {
extern "C" fn remove_callback(pdev: *mut bindings::pci_dev) {
// SAFETY: The PCI bus only ever calls the remove callback with a valid pointer to a
// `struct pci_dev`.
let ptr = unsafe { bindings::pci_get_drvdata(pdev) };
let ptr = unsafe { bindings::pci_get_drvdata(pdev) }.cast();
// SAFETY: `remove_callback` is only ever called after a successful call to
// `probe_callback`, hence it's guaranteed that `ptr` points to a valid and initialized
@ -118,7 +118,9 @@ macro_rules! module_pci_driver {
};
}
/// Abstraction for bindings::pci_device_id.
/// Abstraction for the PCI device ID structure ([`struct pci_device_id`]).
///
/// [`struct pci_device_id`]: https://docs.kernel.org/PCI/pci.html#c.pci_device_id
#[repr(transparent)]
#[derive(Clone, Copy)]
pub struct DeviceId(bindings::pci_device_id);
@ -173,7 +175,7 @@ unsafe impl RawDeviceId for DeviceId {
}
}
/// IdTable type for PCI
/// `IdTable` type for PCI.
pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;
/// Create a PCI `IdTable` with its alias for modpost.
@ -224,10 +226,11 @@ macro_rules! pci_device_table {
/// `Adapter` documentation for an example.
pub trait Driver: Send {
/// The type holding information about each device id supported by the driver.
///
/// TODO: Use associated_type_defaults once stabilized:
///
/// type IdInfo: 'static = ();
// TODO: Use `associated_type_defaults` once stabilized:
//
// ```
// type IdInfo: 'static = ();
// ```
type IdInfo: 'static;
/// The table of device ids supported by the driver.

11
rust/kernel/platform.rs
View file

@ -79,7 +79,7 @@ impl<T: Driver + 'static> Adapter<T> {
extern "C" fn remove_callback(pdev: *mut bindings::platform_device) {
// SAFETY: `pdev` is a valid pointer to a `struct platform_device`.
let ptr = unsafe { bindings::platform_get_drvdata(pdev) };
let ptr = unsafe { bindings::platform_get_drvdata(pdev) }.cast();
// SAFETY: `remove_callback` is only ever called after a successful call to
// `probe_callback`, hence it's guaranteed that `ptr` points to a valid and initialized
@ -150,10 +150,11 @@ macro_rules! module_platform_driver {
///```
pub trait Driver: Send {
/// The type holding driver private data about each device id supported by the driver.
///
/// TODO: Use associated_type_defaults once stabilized:
///
/// type IdInfo: 'static = ();
// TODO: Use associated_type_defaults once stabilized:
//
// ```
// type IdInfo: 'static = ();
// ```
type IdInfo: 'static;
/// The table of OF device ids supported by the driver.

7
rust/kernel/prelude.rs
View file

@ -14,10 +14,15 @@
#[doc(no_inline)]
pub use core::pin::Pin;
pub use ::ffi::{
c_char, c_int, c_long, c_longlong, c_schar, c_short, c_uchar, c_uint, c_ulong, c_ulonglong,
c_ushort, c_void,
};
pub use crate::alloc::{flags::*, Box, KBox, KVBox, KVVec, KVec, VBox, VVec, Vec};
#[doc(no_inline)]
pub use macros::{export, module, vtable};
pub use macros::{export, kunit_tests, module, vtable};
pub use pin_init::{init, pin_data, pin_init, pinned_drop, InPlaceWrite, Init, PinInit, Zeroable};

27
rust/kernel/print.rs
View file

@ -198,10 +198,11 @@ macro_rules! print_macro (
/// Equivalent to the kernel's [`pr_emerg`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_emerg`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_emerg
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -222,10 +223,11 @@ macro_rules! pr_emerg (
/// Equivalent to the kernel's [`pr_alert`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_alert`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_alert
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -246,10 +248,11 @@ macro_rules! pr_alert (
/// Equivalent to the kernel's [`pr_crit`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_crit`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_crit
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -270,10 +273,11 @@ macro_rules! pr_crit (
/// Equivalent to the kernel's [`pr_err`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_err`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_err
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -294,10 +298,11 @@ macro_rules! pr_err (
/// Equivalent to the kernel's [`pr_warn`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_warn`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_warn
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -318,10 +323,11 @@ macro_rules! pr_warn (
/// Equivalent to the kernel's [`pr_notice`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_notice`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_notice
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -342,10 +348,11 @@ macro_rules! pr_notice (
/// Equivalent to the kernel's [`pr_info`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_info`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_info
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -368,10 +375,11 @@ macro_rules! pr_info (
/// yet.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_debug`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_debug
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///
@ -395,11 +403,12 @@ macro_rules! pr_debug (
/// Equivalent to the kernel's [`pr_cont`] macro.
///
/// Mimics the interface of [`std::print!`]. See [`core::fmt`] and
/// `alloc::format!` for information about the formatting syntax.
/// [`std::format!`] for information about the formatting syntax.
///
/// [`pr_info!`]: crate::pr_info!
/// [`pr_cont`]: https://docs.kernel.org/core-api/printk-basics.html#c.pr_cont
/// [`std::print!`]: https://doc.rust-lang.org/std/macro.print.html
/// [`std::format!`]: https://doc.rust-lang.org/std/macro.format.html
///
/// # Examples
///

23
rust/kernel/rbtree.rs
View file

@ -424,7 +424,7 @@ where
while !node.is_null() {
// SAFETY: By the type invariant of `Self`, all non-null `rb_node` pointers stored in `self`
// point to the links field of `Node<K, V>` objects.
let this = unsafe { container_of!(node, Node<K, V>, links) }.cast_mut();
let this = unsafe { container_of!(node, Node<K, V>, links) };
// SAFETY: `this` is a non-null node so it is valid by the type invariants.
let this_key = unsafe { &(*this).key };
// SAFETY: `node` is a non-null node so it is valid by the type invariants.
@ -496,7 +496,7 @@ impl<K, V> Drop for RBTree<K, V> {
// but it is not observable. The loop invariant is still maintained.
// SAFETY: `this` is valid per the loop invariant.
unsafe { drop(KBox::from_raw(this.cast_mut())) };
unsafe { drop(KBox::from_raw(this)) };
}
}
}
@ -761,7 +761,7 @@ impl<'a, K, V> Cursor<'a, K, V> {
let next = self.get_neighbor_raw(Direction::Next);
// SAFETY: By the type invariant of `Self`, all non-null `rb_node` pointers stored in `self`
// point to the links field of `Node<K, V>` objects.
let this = unsafe { container_of!(self.current.as_ptr(), Node<K, V>, links) }.cast_mut();
let this = unsafe { container_of!(self.current.as_ptr(), Node<K, V>, links) };
// SAFETY: `this` is valid by the type invariants as described above.
let node = unsafe { KBox::from_raw(this) };
let node = RBTreeNode { node };
@ -806,7 +806,7 @@ impl<'a, K, V> Cursor<'a, K, V> {
unsafe { bindings::rb_erase(neighbor, addr_of_mut!(self.tree.root)) };
// SAFETY: By the type invariant of `Self`, all non-null `rb_node` pointers stored in `self`
// point to the links field of `Node<K, V>` objects.
let this = unsafe { container_of!(neighbor, Node<K, V>, links) }.cast_mut();
let this = unsafe { container_of!(neighbor, Node<K, V>, links) };
// SAFETY: `this` is valid by the type invariants as described above.
let node = unsafe { KBox::from_raw(this) };
return Some(RBTreeNode { node });
@ -912,7 +912,7 @@ impl<'a, K, V> Cursor<'a, K, V> {
unsafe fn to_key_value_raw<'b>(node: NonNull<bindings::rb_node>) -> (&'b K, *mut V) {
// SAFETY: By the type invariant of `Self`, all non-null `rb_node` pointers stored in `self`
// point to the links field of `Node<K, V>` objects.
let this = unsafe { container_of!(node.as_ptr(), Node<K, V>, links) }.cast_mut();
let this = unsafe { container_of!(node.as_ptr(), Node<K, V>, links) };
// SAFETY: The passed `node` is the current node or a non-null neighbor,
// thus `this` is valid by the type invariants.
let k = unsafe { &(*this).key };
@ -1021,7 +1021,7 @@ impl<K, V> Iterator for IterRaw<K, V> {
// SAFETY: By the type invariant of `IterRaw`, `self.next` is a valid node in an `RBTree`,
// and by the type invariant of `RBTree`, all nodes point to the links field of `Node<K, V>` objects.
let cur = unsafe { container_of!(self.next, Node<K, V>, links) }.cast_mut();
let cur = unsafe { container_of!(self.next, Node<K, V>, links) };
// SAFETY: `self.next` is a valid tree node by the type invariants.
self.next = unsafe { bindings::rb_next(self.next) };
@ -1216,7 +1216,7 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
// SAFETY:
// - `self.node_links` is a valid pointer to a node in the tree.
// - We have exclusive access to the underlying tree, and can thus give out a mutable reference.
unsafe { &mut (*(container_of!(self.node_links, Node<K, V>, links).cast_mut())).value }
unsafe { &mut (*(container_of!(self.node_links, Node<K, V>, links))).value }
}
/// Converts the entry into a mutable reference to its value.
@ -1226,7 +1226,7 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
// SAFETY:
// - `self.node_links` is a valid pointer to a node in the tree.
// - This consumes the `&'a mut RBTree<K, V>`, therefore it can give out a mutable reference that lives for `'a`.
unsafe { &mut (*(container_of!(self.node_links, Node<K, V>, links).cast_mut())).value }
unsafe { &mut (*(container_of!(self.node_links, Node<K, V>, links))).value }
}
/// Remove this entry from the [`RBTree`].
@ -1239,9 +1239,7 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
RBTreeNode {
// SAFETY: The node was a node in the tree, but we removed it, so we can convert it
// back into a box.
node: unsafe {
KBox::from_raw(container_of!(self.node_links, Node<K, V>, links).cast_mut())
},
node: unsafe { KBox::from_raw(container_of!(self.node_links, Node<K, V>, links)) },
}
}
@ -1272,8 +1270,7 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
// SAFETY:
// - `self.node_ptr` produces a valid pointer to a node in the tree.
// - Now that we removed this entry from the tree, we can convert the node to a box.
let old_node =
unsafe { KBox::from_raw(container_of!(self.node_links, Node<K, V>, links).cast_mut()) };
let old_node = unsafe { KBox::from_raw(container_of!(self.node_links, Node<K, V>, links)) };
RBTreeNode { node: old_node }
}

9
rust/kernel/static_assert.rs
View file

@ -6,6 +6,10 @@
///
/// Similar to C11 [`_Static_assert`] and C++11 [`static_assert`].
///
/// An optional panic message can be supplied after the expression.
/// Currently only a string literal without formatting is supported
/// due to constness limitations of the [`assert!`] macro.
///
/// The feature may be added to Rust in the future: see [RFC 2790].
///
/// [`_Static_assert`]: https://en.cppreference.com/w/c/language/_Static_assert
@ -25,10 +29,11 @@
/// x + 2
/// }
/// static_assert!(f(40) == 42);
/// static_assert!(f(40) == 42, "f(x) must add 2 to the given input.");
/// ```
#[macro_export]
macro_rules! static_assert {
($condition:expr) => {
const _: () = core::assert!($condition);
($condition:expr $(,$arg:literal)?) => {
const _: () = ::core::assert!($condition $(,$arg)?);
};
}

2
rust/kernel/std_vendor.rs
View file

@ -148,7 +148,7 @@ macro_rules! dbg {
};
($val:expr $(,)?) => {
// Use of `match` here is intentional because it affects the lifetimes
// of temporaries - https://stackoverflow.com/a/48732525/1063961
// of temporaries - <https://stackoverflow.com/a/48732525/1063961>
match $val {
tmp => {
$crate::pr_info!("[{}:{}:{}] {} = {:#?}\n",

82
rust/kernel/str.rs
View file

@ -6,7 +6,7 @@ use crate::alloc::{flags::*, AllocError, KVec};
use core::fmt::{self, Write};
use core::ops::{self, Deref, DerefMut, Index};
use crate::error::{code::*, Error};
use crate::prelude::*;
/// Byte string without UTF-8 validity guarantee.
#[repr(transparent)]
@ -572,30 +572,13 @@ macro_rules! c_str {
}};
}
#[cfg(test)]
#[expect(clippy::items_after_test_module)]
#[kunit_tests(rust_kernel_str)]
mod tests {
use super::*;
struct String(CString);
impl String {
fn from_fmt(args: fmt::Arguments<'_>) -> Self {
String(CString::try_from_fmt(args).unwrap())
}
}
impl Deref for String {
type Target = str;
fn deref(&self) -> &str {
self.0.to_str().unwrap()
}
}
macro_rules! format {
($($f:tt)*) => ({
&*String::from_fmt(kernel::fmt!($($f)*))
CString::try_from_fmt(::kernel::fmt!($($f)*))?.to_str()?
})
}
@ -614,67 +597,72 @@ mod tests {
\\xf0\\xf1\\xf2\\xf3\\xf4\\xf5\\xf6\\xf7\\xf8\\xf9\\xfa\\xfb\\xfc\\xfd\\xfe\\xff";
#[test]
fn test_cstr_to_str() {
fn test_cstr_to_str() -> Result {
let good_bytes = b"\xf0\x9f\xa6\x80\0";
let checked_cstr = CStr::from_bytes_with_nul(good_bytes).unwrap();
let checked_str = checked_cstr.to_str().unwrap();
let checked_cstr = CStr::from_bytes_with_nul(good_bytes)?;
let checked_str = checked_cstr.to_str()?;
assert_eq!(checked_str, "🦀");
Ok(())
}
#[test]
#[should_panic]
fn test_cstr_to_str_panic() {
fn test_cstr_to_str_invalid_utf8() -> Result {
let bad_bytes = b"\xc3\x28\0";
let checked_cstr = CStr::from_bytes_with_nul(bad_bytes).unwrap();
checked_cstr.to_str().unwrap();
let checked_cstr = CStr::from_bytes_with_nul(bad_bytes)?;
assert!(checked_cstr.to_str().is_err());
Ok(())
}
#[test]
fn test_cstr_as_str_unchecked() {
fn test_cstr_as_str_unchecked() -> Result {
let good_bytes = b"\xf0\x9f\x90\xA7\0";
let checked_cstr = CStr::from_bytes_with_nul(good_bytes).unwrap();
let checked_cstr = CStr::from_bytes_with_nul(good_bytes)?;
// SAFETY: The contents come from a string literal which contains valid UTF-8.
let unchecked_str = unsafe { checked_cstr.as_str_unchecked() };
assert_eq!(unchecked_str, "🐧");
Ok(())
}
#[test]
fn test_cstr_display() {
let hello_world = CStr::from_bytes_with_nul(b"hello, world!\0").unwrap();
fn test_cstr_display() -> Result {
let hello_world = CStr::from_bytes_with_nul(b"hello, world!\0")?;
assert_eq!(format!("{hello_world}"), "hello, world!");
let non_printables = CStr::from_bytes_with_nul(b"\x01\x09\x0a\0").unwrap();
let non_printables = CStr::from_bytes_with_nul(b"\x01\x09\x0a\0")?;
assert_eq!(format!("{non_printables}"), "\\x01\\x09\\x0a");
let non_ascii = CStr::from_bytes_with_nul(b"d\xe9j\xe0 vu\0").unwrap();
let non_ascii = CStr::from_bytes_with_nul(b"d\xe9j\xe0 vu\0")?;
assert_eq!(format!("{non_ascii}"), "d\\xe9j\\xe0 vu");
let good_bytes = CStr::from_bytes_with_nul(b"\xf0\x9f\xa6\x80\0").unwrap();
let good_bytes = CStr::from_bytes_with_nul(b"\xf0\x9f\xa6\x80\0")?;
assert_eq!(format!("{good_bytes}"), "\\xf0\\x9f\\xa6\\x80");
Ok(())
}
#[test]
fn test_cstr_display_all_bytes() {
fn test_cstr_display_all_bytes() -> Result {
let mut bytes: [u8; 256] = [0; 256];
// fill `bytes` with [1..=255] + [0]
for i in u8::MIN..=u8::MAX {
bytes[i as usize] = i.wrapping_add(1);
}
let cstr = CStr::from_bytes_with_nul(&bytes).unwrap();
let cstr = CStr::from_bytes_with_nul(&bytes)?;
assert_eq!(format!("{cstr}"), ALL_ASCII_CHARS);
Ok(())
}
#[test]
fn test_cstr_debug() {
let hello_world = CStr::from_bytes_with_nul(b"hello, world!\0").unwrap();
fn test_cstr_debug() -> Result {
let hello_world = CStr::from_bytes_with_nul(b"hello, world!\0")?;
assert_eq!(format!("{hello_world:?}"), "\"hello, world!\"");
let non_printables = CStr::from_bytes_with_nul(b"\x01\x09\x0a\0").unwrap();
let non_printables = CStr::from_bytes_with_nul(b"\x01\x09\x0a\0")?;
assert_eq!(format!("{non_printables:?}"), "\"\\x01\\x09\\x0a\"");
let non_ascii = CStr::from_bytes_with_nul(b"d\xe9j\xe0 vu\0").unwrap();
let non_ascii = CStr::from_bytes_with_nul(b"d\xe9j\xe0 vu\0")?;
assert_eq!(format!("{non_ascii:?}"), "\"d\\xe9j\\xe0 vu\"");
let good_bytes = CStr::from_bytes_with_nul(b"\xf0\x9f\xa6\x80\0").unwrap();
let good_bytes = CStr::from_bytes_with_nul(b"\xf0\x9f\xa6\x80\0")?;
assert_eq!(format!("{good_bytes:?}"), "\"\\xf0\\x9f\\xa6\\x80\"");
Ok(())
}
#[test]
fn test_bstr_display() {
fn test_bstr_display() -> Result {
let hello_world = BStr::from_bytes(b"hello, world!");
assert_eq!(format!("{hello_world}"), "hello, world!");
let escapes = BStr::from_bytes(b"_\t_\n_\r_\\_\'_\"_");
@ -685,10 +673,11 @@ mod tests {
assert_eq!(format!("{non_ascii}"), "d\\xe9j\\xe0 vu");
let good_bytes = BStr::from_bytes(b"\xf0\x9f\xa6\x80");
assert_eq!(format!("{good_bytes}"), "\\xf0\\x9f\\xa6\\x80");
Ok(())
}
#[test]
fn test_bstr_debug() {
fn test_bstr_debug() -> Result {
let hello_world = BStr::from_bytes(b"hello, world!");
assert_eq!(format!("{hello_world:?}"), "\"hello, world!\"");
let escapes = BStr::from_bytes(b"_\t_\n_\r_\\_\'_\"_");
@ -699,6 +688,7 @@ mod tests {
assert_eq!(format!("{non_ascii:?}"), "\"d\\xe9j\\xe0 vu\"");
let good_bytes = BStr::from_bytes(b"\xf0\x9f\xa6\x80");
assert_eq!(format!("{good_bytes:?}"), "\"\\xf0\\x9f\\xa6\\x80\"");
Ok(())
}
}
@ -752,7 +742,7 @@ impl RawFormatter {
/// for the lifetime of the returned [`RawFormatter`].
pub(crate) unsafe fn from_buffer(buf: *mut u8, len: usize) -> Self {
let pos = buf as usize;
// INVARIANT: We ensure that `end` is never less then `buf`, and the safety requirements
// INVARIANT: We ensure that `end` is never less than `buf`, and the safety requirements
// guarantees that the memory region is valid for writes.
Self {
pos,
@ -886,7 +876,7 @@ impl CString {
// SAFETY: The number of bytes that can be written to `f` is bounded by `size`, which is
// `buf`'s capacity. The contents of the buffer have been initialised by writes to `f`.
unsafe { buf.set_len(f.bytes_written()) };
unsafe { buf.inc_len(f.bytes_written()) };
// Check that there are no `NUL` bytes before the end.
// SAFETY: The buffer is valid for read because `f.bytes_written()` is bounded by `size`
@ -944,5 +934,5 @@ impl fmt::Debug for CString {
/// A convenience alias for [`core::format_args`].
#[macro_export]
macro_rules! fmt {
($($f:tt)*) => ( core::format_args!($($f)*) )
($($f:tt)*) => ( ::core::format_args!($($f)*) )
}

25
rust/kernel/sync/arc.rs
View file

@ -135,14 +135,15 @@ pub struct Arc<T: ?Sized> {
// meaningful with respect to dropck - but this may change in the future so this is left here
// out of an abundance of caution.
//
// See https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking
// See <https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking>
// for more detail on the semantics of dropck in the presence of `PhantomData`.
_p: PhantomData<ArcInner<T>>,
}
#[doc(hidden)]
#[pin_data]
#[repr(C)]
struct ArcInner<T: ?Sized> {
pub struct ArcInner<T: ?Sized> {
refcount: Opaque<bindings::refcount_t>,
data: T,
}
@ -371,18 +372,20 @@ impl<T: ?Sized> Arc<T> {
}
}
impl<T: 'static> ForeignOwnable for Arc<T> {
// SAFETY: The `into_foreign` function returns a pointer that is well-aligned.
unsafe impl<T: 'static> ForeignOwnable for Arc<T> {
type PointedTo = ArcInner<T>;
type Borrowed<'a> = ArcBorrow<'a, T>;
type BorrowedMut<'a> = Self::Borrowed<'a>;
fn into_foreign(self) -> *mut crate::ffi::c_void {
ManuallyDrop::new(self).ptr.as_ptr().cast()
fn into_foreign(self) -> *mut Self::PointedTo {
ManuallyDrop::new(self).ptr.as_ptr()
}
unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {
unsafe fn from_foreign(ptr: *mut Self::PointedTo) -> Self {
// SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
// call to `Self::into_foreign`.
let inner = unsafe { NonNull::new_unchecked(ptr.cast::<ArcInner<T>>()) };
let inner = unsafe { NonNull::new_unchecked(ptr) };
// SAFETY: By the safety requirement of this function, we know that `ptr` came from
// a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and
@ -390,17 +393,17 @@ impl<T: 'static> ForeignOwnable for Arc<T> {
unsafe { Self::from_inner(inner) }
}
unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> ArcBorrow<'a, T> {
unsafe fn borrow<'a>(ptr: *mut Self::PointedTo) -> ArcBorrow<'a, T> {
// SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
// call to `Self::into_foreign`.
let inner = unsafe { NonNull::new_unchecked(ptr.cast::<ArcInner<T>>()) };
let inner = unsafe { NonNull::new_unchecked(ptr) };
// SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive
// for the lifetime of the returned value.
unsafe { ArcBorrow::new(inner) }
}
unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> ArcBorrow<'a, T> {
unsafe fn borrow_mut<'a>(ptr: *mut Self::PointedTo) -> ArcBorrow<'a, T> {
// SAFETY: The safety requirements for `borrow_mut` are a superset of the safety
// requirements for `borrow`.
unsafe { Self::borrow(ptr) }
@ -489,7 +492,7 @@ impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Arc<T> {
/// There are no mutable references to the underlying [`Arc`], and it remains valid for the
/// lifetime of the [`ArcBorrow`] instance.
///
/// # Example
/// # Examples
///
/// ```
/// use kernel::sync::{Arc, ArcBorrow};

181
rust/kernel/time.rs
View file

@ -5,14 +5,36 @@
//! This module contains the kernel APIs related to time and timers that
//! have been ported or wrapped for usage by Rust code in the kernel.
//!
//! There are two types in this module:
//!
//! - The [`Instant`] type represents a specific point in time.
//! - The [`Delta`] type represents a span of time.
//!
//! Note that the C side uses `ktime_t` type to represent both. However, timestamp
//! and timedelta are different. To avoid confusion, we use two different types.
//!
//! A [`Instant`] object can be created by calling the [`Instant::now()`] function.
//! It represents a point in time at which the object was created.
//! By calling the [`Instant::elapsed()`] method, a [`Delta`] object representing
//! the elapsed time can be created. The [`Delta`] object can also be created
//! by subtracting two [`Instant`] objects.
//!
//! A [`Delta`] type supports methods to retrieve the duration in various units.
//!
//! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
//! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h).
pub mod hrtimer;
/// The number of nanoseconds per microsecond.
pub const NSEC_PER_USEC: i64 = bindings::NSEC_PER_USEC as i64;
/// The number of nanoseconds per millisecond.
pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64;
/// The number of nanoseconds per second.
pub const NSEC_PER_SEC: i64 = bindings::NSEC_PER_SEC as i64;
/// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
pub type Jiffies = crate::ffi::c_ulong;
@ -27,59 +49,44 @@ pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies {
unsafe { bindings::__msecs_to_jiffies(msecs) }
}
/// A Rust wrapper around a `ktime_t`.
/// A specific point in time.
///
/// # Invariants
///
/// The `inner` value is in the range from 0 to `KTIME_MAX`.
#[repr(transparent)]
#[derive(Copy, Clone)]
pub struct Ktime {
#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord)]
pub struct Instant {
inner: bindings::ktime_t,
}
impl Ktime {
/// Create a `Ktime` from a raw `ktime_t`.
#[inline]
pub fn from_raw(inner: bindings::ktime_t) -> Self {
Self { inner }
}
impl Instant {
/// Get the current time using `CLOCK_MONOTONIC`.
#[inline]
pub fn ktime_get() -> Self {
// SAFETY: It is always safe to call `ktime_get` outside of NMI context.
Self::from_raw(unsafe { bindings::ktime_get() })
}
/// Divide the number of nanoseconds by a compile-time constant.
#[inline]
fn divns_constant<const DIV: i64>(self) -> i64 {
self.to_ns() / DIV
}
/// Returns the number of nanoseconds.
#[inline]
pub fn to_ns(self) -> i64 {
self.inner
}
/// Returns the number of milliseconds.
#[inline]
pub fn to_ms(self) -> i64 {
self.divns_constant::<NSEC_PER_MSEC>()
}
}
/// Returns the number of milliseconds between two ktimes.
#[inline]
pub fn ktime_ms_delta(later: Ktime, earlier: Ktime) -> i64 {
(later - earlier).to_ms()
}
impl core::ops::Sub for Ktime {
type Output = Ktime;
#[inline]
fn sub(self, other: Ktime) -> Ktime {
pub fn now() -> Self {
// INVARIANT: The `ktime_get()` function returns a value in the range
// from 0 to `KTIME_MAX`.
Self {
inner: self.inner - other.inner,
// SAFETY: It is always safe to call `ktime_get()` outside of NMI context.
inner: unsafe { bindings::ktime_get() },
}
}
/// Return the amount of time elapsed since the [`Instant`].
#[inline]
pub fn elapsed(&self) -> Delta {
Self::now() - *self
}
}
impl core::ops::Sub for Instant {
type Output = Delta;
// By the type invariant, it never overflows.
#[inline]
fn sub(self, other: Instant) -> Delta {
Delta {
nanos: self.inner - other.inner,
}
}
}
@ -149,3 +156,85 @@ impl ClockId {
self as bindings::clockid_t
}
}
/// A span of time.
///
/// This struct represents a span of time, with its value stored as nanoseconds.
/// The value can represent any valid i64 value, including negative, zero, and
/// positive numbers.
#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)]
pub struct Delta {
nanos: i64,
}
impl Delta {
/// A span of time equal to zero.
pub const ZERO: Self = Self { nanos: 0 };
/// Create a new [`Delta`] from a number of microseconds.
///
/// The `micros` can range from -9_223_372_036_854_775 to 9_223_372_036_854_775.
/// If `micros` is outside this range, `i64::MIN` is used for negative values,
/// and `i64::MAX` is used for positive values due to saturation.
#[inline]
pub const fn from_micros(micros: i64) -> Self {
Self {
nanos: micros.saturating_mul(NSEC_PER_USEC),
}
}
/// Create a new [`Delta`] from a number of milliseconds.
///
/// The `millis` can range from -9_223_372_036_854 to 9_223_372_036_854.
/// If `millis` is outside this range, `i64::MIN` is used for negative values,
/// and `i64::MAX` is used for positive values due to saturation.
#[inline]
pub const fn from_millis(millis: i64) -> Self {
Self {
nanos: millis.saturating_mul(NSEC_PER_MSEC),
}
}
/// Create a new [`Delta`] from a number of seconds.
///
/// The `secs` can range from -9_223_372_036 to 9_223_372_036.
/// If `secs` is outside this range, `i64::MIN` is used for negative values,
/// and `i64::MAX` is used for positive values due to saturation.
#[inline]
pub const fn from_secs(secs: i64) -> Self {
Self {
nanos: secs.saturating_mul(NSEC_PER_SEC),
}
}
/// Return `true` if the [`Delta`] spans no time.
#[inline]
pub fn is_zero(self) -> bool {
self.as_nanos() == 0
}
/// Return `true` if the [`Delta`] spans a negative amount of time.
#[inline]
pub fn is_negative(self) -> bool {
self.as_nanos() < 0
}
/// Return the number of nanoseconds in the [`Delta`].
#[inline]
pub const fn as_nanos(self) -> i64 {
self.nanos
}
/// Return the smallest number of microseconds greater than or equal
/// to the value in the [`Delta`].
#[inline]
pub const fn as_micros_ceil(self) -> i64 {
self.as_nanos().saturating_add(NSEC_PER_USEC - 1) / NSEC_PER_USEC
}
/// Return the number of milliseconds in the [`Delta`].
#[inline]
pub const fn as_millis(self) -> i64 {
self.as_nanos() / NSEC_PER_MSEC
}
}

24
rust/kernel/time/hrtimer.rs
View file

@ -68,10 +68,26 @@
//! `start` operation.
use super::ClockId;
use crate::{prelude::*, time::Ktime, types::Opaque};
use crate::{prelude::*, types::Opaque};
use core::marker::PhantomData;
use pin_init::PinInit;
/// A Rust wrapper around a `ktime_t`.
// NOTE: Ktime is going to be removed when hrtimer is converted to Instant/Delta.
#[repr(transparent)]
#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord)]
pub struct Ktime {
inner: bindings::ktime_t,
}
impl Ktime {
/// Returns the number of nanoseconds.
#[inline]
pub fn to_ns(self) -> i64 {
self.inner
}
}
/// A timer backed by a C `struct hrtimer`.
///
/// # Invariants
@ -384,11 +400,9 @@ pub unsafe trait HasHrTimer<T> {
#[repr(u32)]
pub enum HrTimerRestart {
/// Timer should not be restarted.
#[allow(clippy::unnecessary_cast)]
NoRestart = bindings::hrtimer_restart_HRTIMER_NORESTART as u32,
NoRestart = bindings::hrtimer_restart_HRTIMER_NORESTART,
/// Timer should be restarted.
#[allow(clippy::unnecessary_cast)]
Restart = bindings::hrtimer_restart_HRTIMER_RESTART as u32,
Restart = bindings::hrtimer_restart_HRTIMER_RESTART,
}
impl HrTimerRestart {

2
rust/kernel/time/hrtimer/arc.rs
View file

@ -5,10 +5,10 @@ use super::HrTimer;
use super::HrTimerCallback;
use super::HrTimerHandle;
use super::HrTimerPointer;
use super::Ktime;
use super::RawHrTimerCallback;
use crate::sync::Arc;
use crate::sync::ArcBorrow;
use crate::time::Ktime;
/// A handle for an `Arc<HasHrTimer<T>>` returned by a call to
/// [`HrTimerPointer::start`].

2
rust/kernel/time/hrtimer/pin.rs
View file

@ -4,9 +4,9 @@ use super::HasHrTimer;
use super::HrTimer;
use super::HrTimerCallback;
use super::HrTimerHandle;
use super::Ktime;
use super::RawHrTimerCallback;
use super::UnsafeHrTimerPointer;
use crate::time::Ktime;
use core::pin::Pin;
/// A handle for a `Pin<&HasHrTimer>`. When the handle exists, the timer might be

4
rust/kernel/time/hrtimer/pin_mut.rs
View file

@ -1,9 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
use super::{
HasHrTimer, HrTimer, HrTimerCallback, HrTimerHandle, RawHrTimerCallback, UnsafeHrTimerPointer,
HasHrTimer, HrTimer, HrTimerCallback, HrTimerHandle, Ktime, RawHrTimerCallback,
UnsafeHrTimerPointer,
};
use crate::time::Ktime;
use core::{marker::PhantomData, pin::Pin, ptr::NonNull};
/// A handle for a `Pin<&mut HasHrTimer>`. When the handle exists, the timer might

2
rust/kernel/time/hrtimer/tbox.rs
View file

@ -5,9 +5,9 @@ use super::HrTimer;
use super::HrTimerCallback;
use super::HrTimerHandle;
use super::HrTimerPointer;
use super::Ktime;
use super::RawHrTimerCallback;
use crate::prelude::*;
use crate::time::Ktime;
use core::ptr::NonNull;
/// A handle for a [`Box<HasHrTimer<T>>`] returned by a call to

46
rust/kernel/types.rs
View file

@ -18,7 +18,19 @@ use pin_init::{PinInit, Zeroable};
///
/// This trait is meant to be used in cases when Rust objects are stored in C objects and
/// eventually "freed" back to Rust.
pub trait ForeignOwnable: Sized {
///
/// # Safety
///
/// Implementers must ensure that [`into_foreign`] returns a pointer which meets the alignment
/// requirements of [`PointedTo`].
///
/// [`into_foreign`]: Self::into_foreign
/// [`PointedTo`]: Self::PointedTo
pub unsafe trait ForeignOwnable: Sized {
/// Type used when the value is foreign-owned. In practical terms only defines the alignment of
/// the pointer.
type PointedTo;
/// Type used to immutably borrow a value that is currently foreign-owned.
type Borrowed<'a>;
@ -27,16 +39,18 @@ pub trait ForeignOwnable: Sized {
/// Converts a Rust-owned object to a foreign-owned one.
///
/// The foreign representation is a pointer to void. There are no guarantees for this pointer.
/// For example, it might be invalid, dangling or pointing to uninitialized memory. Using it in
/// any way except for [`from_foreign`], [`try_from_foreign`], [`borrow`], or [`borrow_mut`] can
/// result in undefined behavior.
/// # Guarantees
///
/// The return value is guaranteed to be well-aligned, but there are no other guarantees for
/// this pointer. For example, it might be null, dangling, or point to uninitialized memory.
/// Using it in any way except for [`ForeignOwnable::from_foreign`], [`ForeignOwnable::borrow`],
/// [`ForeignOwnable::try_from_foreign`] can result in undefined behavior.
///
/// [`from_foreign`]: Self::from_foreign
/// [`try_from_foreign`]: Self::try_from_foreign
/// [`borrow`]: Self::borrow
/// [`borrow_mut`]: Self::borrow_mut
fn into_foreign(self) -> *mut crate::ffi::c_void;
fn into_foreign(self) -> *mut Self::PointedTo;
/// Converts a foreign-owned object back to a Rust-owned one.
///
@ -46,7 +60,7 @@ pub trait ForeignOwnable: Sized {
/// must not be passed to `from_foreign` more than once.
///
/// [`into_foreign`]: Self::into_foreign
unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self;
unsafe fn from_foreign(ptr: *mut Self::PointedTo) -> Self;
/// Tries to convert a foreign-owned object back to a Rust-owned one.
///
@ -58,7 +72,7 @@ pub trait ForeignOwnable: Sized {
/// `ptr` must either be null or satisfy the safety requirements for [`from_foreign`].
///
/// [`from_foreign`]: Self::from_foreign
unsafe fn try_from_foreign(ptr: *mut crate::ffi::c_void) -> Option<Self> {
unsafe fn try_from_foreign(ptr: *mut Self::PointedTo) -> Option<Self> {
if ptr.is_null() {
None
} else {
@ -81,7 +95,7 @@ pub trait ForeignOwnable: Sized {
///
/// [`into_foreign`]: Self::into_foreign
/// [`from_foreign`]: Self::from_foreign
unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> Self::Borrowed<'a>;
unsafe fn borrow<'a>(ptr: *mut Self::PointedTo) -> Self::Borrowed<'a>;
/// Borrows a foreign-owned object mutably.
///
@ -109,21 +123,23 @@ pub trait ForeignOwnable: Sized {
/// [`from_foreign`]: Self::from_foreign
/// [`borrow`]: Self::borrow
/// [`Arc`]: crate::sync::Arc
unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> Self::BorrowedMut<'a>;
unsafe fn borrow_mut<'a>(ptr: *mut Self::PointedTo) -> Self::BorrowedMut<'a>;
}
impl ForeignOwnable for () {
// SAFETY: The `into_foreign` function returns a pointer that is dangling, but well-aligned.
unsafe impl ForeignOwnable for () {
type PointedTo = ();
type Borrowed<'a> = ();
type BorrowedMut<'a> = ();
fn into_foreign(self) -> *mut crate::ffi::c_void {
fn into_foreign(self) -> *mut Self::PointedTo {
core::ptr::NonNull::dangling().as_ptr()
}
unsafe fn from_foreign(_: *mut crate::ffi::c_void) -> Self {}
unsafe fn from_foreign(_: *mut Self::PointedTo) -> Self {}
unsafe fn borrow<'a>(_: *mut crate::ffi::c_void) -> Self::Borrowed<'a> {}
unsafe fn borrow_mut<'a>(_: *mut crate::ffi::c_void) -> Self::BorrowedMut<'a> {}
unsafe fn borrow<'a>(_: *mut Self::PointedTo) -> Self::Borrowed<'a> {}
unsafe fn borrow_mut<'a>(_: *mut Self::PointedTo) -> Self::BorrowedMut<'a> {}
}
/// Runs a cleanup function/closure when dropped.

6
rust/kernel/uaccess.rs
View file

@ -46,10 +46,9 @@ pub type UserPtr = usize;
///
/// ```no_run
/// use kernel::ffi::c_void;
/// use kernel::error::Result;
/// use kernel::uaccess::{UserPtr, UserSlice};
///
/// fn bytes_add_one(uptr: UserPtr, len: usize) -> Result<()> {
/// fn bytes_add_one(uptr: UserPtr, len: usize) -> Result {
/// let (read, mut write) = UserSlice::new(uptr, len).reader_writer();
///
/// let mut buf = KVec::new();
@ -68,7 +67,6 @@ pub type UserPtr = usize;
///
/// ```no_run
/// use kernel::ffi::c_void;
/// use kernel::error::{code::EINVAL, Result};
/// use kernel::uaccess::{UserPtr, UserSlice};
///
/// /// Returns whether the data in this region is valid.
@ -290,7 +288,7 @@ impl UserSliceReader {
// SAFETY: Since the call to `read_raw` was successful, so the next `len` bytes of the
// vector have been initialized.
unsafe { buf.set_len(buf.len() + len) };
unsafe { buf.inc_len(len) };
Ok(())
}
}

50
rust/kernel/workqueue.rs
View file

@ -429,51 +429,28 @@ impl<T: ?Sized, const ID: u64> Work<T, ID> {
///
/// # Safety
///
/// The [`OFFSET`] constant must be the offset of a field in `Self` of type [`Work<T, ID>`]. The
/// methods on this trait must have exactly the behavior that the definitions given below have.
/// The methods [`raw_get_work`] and [`work_container_of`] must return valid pointers and must be
/// true inverses of each other; that is, they must satisfy the following invariants:
/// - `work_container_of(raw_get_work(ptr)) == ptr` for any `ptr: *mut Self`.
/// - `raw_get_work(work_container_of(ptr)) == ptr` for any `ptr: *mut Work<T, ID>`.
///
/// [`impl_has_work!`]: crate::impl_has_work
/// [`OFFSET`]: HasWork::OFFSET
/// [`raw_get_work`]: HasWork::raw_get_work
/// [`work_container_of`]: HasWork::work_container_of
pub unsafe trait HasWork<T, const ID: u64 = 0> {
/// The offset of the [`Work<T, ID>`] field.
const OFFSET: usize;
/// Returns the offset of the [`Work<T, ID>`] field.
///
/// This method exists because the [`OFFSET`] constant cannot be accessed if the type is not
/// [`Sized`].
///
/// [`OFFSET`]: HasWork::OFFSET
#[inline]
fn get_work_offset(&self) -> usize {
Self::OFFSET
}
/// Returns a pointer to the [`Work<T, ID>`] field.
///
/// # Safety
///
/// The provided pointer must point at a valid struct of type `Self`.
#[inline]
unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID> {
// SAFETY: The caller promises that the pointer is valid.
unsafe { (ptr as *mut u8).add(Self::OFFSET) as *mut Work<T, ID> }
}
unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID>;
/// Returns a pointer to the struct containing the [`Work<T, ID>`] field.
///
/// # Safety
///
/// The pointer must point at a [`Work<T, ID>`] field in a struct of type `Self`.
#[inline]
unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self
where
Self: Sized,
{
// SAFETY: The caller promises that the pointer points at a field of the right type in the
// right kind of struct.
unsafe { (ptr as *mut u8).sub(Self::OFFSET) as *mut Self }
}
unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self;
}
/// Used to safely implement the [`HasWork<T, ID>`] trait.
@ -504,8 +481,6 @@ macro_rules! impl_has_work {
// SAFETY: The implementation of `raw_get_work` only compiles if the field has the right
// type.
unsafe impl$(<$($generics)+>)? $crate::workqueue::HasWork<$work_type $(, $id)?> for $self {
const OFFSET: usize = ::core::mem::offset_of!(Self, $field) as usize;
#[inline]
unsafe fn raw_get_work(ptr: *mut Self) -> *mut $crate::workqueue::Work<$work_type $(, $id)?> {
// SAFETY: The caller promises that the pointer is not dangling.
@ -513,6 +488,15 @@ macro_rules! impl_has_work {
::core::ptr::addr_of_mut!((*ptr).$field)
}
}
#[inline]
unsafe fn work_container_of(
ptr: *mut $crate::workqueue::Work<$work_type $(, $id)?>,
) -> *mut Self {
// SAFETY: The caller promises that the pointer points at a field of the right type
// in the right kind of struct.
unsafe { $crate::container_of!(ptr, Self, $field) }
}
}
)*};
}

275
rust/kernel/xarray.rs Normal file
View file

@ -0,0 +1,275 @@
// SPDX-License-Identifier: GPL-2.0
//! XArray abstraction.
//!
//! C header: [`include/linux/xarray.h`](srctree/include/linux/xarray.h)
use crate::{
alloc, bindings, build_assert,
error::{Error, Result},
types::{ForeignOwnable, NotThreadSafe, Opaque},
};
use core::{iter, marker::PhantomData, mem, pin::Pin, ptr::NonNull};
use pin_init::{pin_data, pin_init, pinned_drop, PinInit};
/// An array which efficiently maps sparse integer indices to owned objects.
///
/// This is similar to a [`crate::alloc::kvec::Vec<Option<T>>`], but more efficient when there are
/// holes in the index space, and can be efficiently grown.
///
/// # Invariants
///
/// `self.xa` is always an initialized and valid [`bindings::xarray`] whose entries are either
/// `XA_ZERO_ENTRY` or came from `T::into_foreign`.
///
/// # Examples
///
/// ```rust
/// use kernel::alloc::KBox;
/// use kernel::xarray::{AllocKind, XArray};
///
/// let xa = KBox::pin_init(XArray::new(AllocKind::Alloc1), GFP_KERNEL)?;
///
/// let dead = KBox::new(0xdead, GFP_KERNEL)?;
/// let beef = KBox::new(0xbeef, GFP_KERNEL)?;
///
/// let mut guard = xa.lock();
///
/// assert_eq!(guard.get(0), None);
///
/// assert_eq!(guard.store(0, dead, GFP_KERNEL)?.as_deref(), None);
/// assert_eq!(guard.get(0).copied(), Some(0xdead));
///
/// *guard.get_mut(0).unwrap() = 0xffff;
/// assert_eq!(guard.get(0).copied(), Some(0xffff));
///
/// assert_eq!(guard.store(0, beef, GFP_KERNEL)?.as_deref().copied(), Some(0xffff));
/// assert_eq!(guard.get(0).copied(), Some(0xbeef));
///
/// guard.remove(0);
/// assert_eq!(guard.get(0), None);
///
/// # Ok::<(), Error>(())
/// ```
#[pin_data(PinnedDrop)]
pub struct XArray<T: ForeignOwnable> {
#[pin]
xa: Opaque<bindings::xarray>,
_p: PhantomData<T>,
}
#[pinned_drop]
impl<T: ForeignOwnable> PinnedDrop for XArray<T> {
fn drop(self: Pin<&mut Self>) {
self.iter().for_each(|ptr| {
let ptr = ptr.as_ptr();
// SAFETY: `ptr` came from `T::into_foreign`.
//
// INVARIANT: we own the only reference to the array which is being dropped so the
// broken invariant is not observable on function exit.
drop(unsafe { T::from_foreign(ptr) })
});
// SAFETY: `self.xa` is always valid by the type invariant.
unsafe { bindings::xa_destroy(self.xa.get()) };
}
}
/// Flags passed to [`XArray::new`] to configure the array's allocation tracking behavior.
pub enum AllocKind {
/// Consider the first element to be at index 0.
Alloc,
/// Consider the first element to be at index 1.
Alloc1,
}
impl<T: ForeignOwnable> XArray<T> {
/// Creates a new initializer for this type.
pub fn new(kind: AllocKind) -> impl PinInit<Self> {
let flags = match kind {
AllocKind::Alloc => bindings::XA_FLAGS_ALLOC,
AllocKind::Alloc1 => bindings::XA_FLAGS_ALLOC1,
};
pin_init!(Self {
// SAFETY: `xa` is valid while the closure is called.
//
// INVARIANT: `xa` is initialized here to an empty, valid [`bindings::xarray`].
xa <- Opaque::ffi_init(|xa| unsafe {
bindings::xa_init_flags(xa, flags)
}),
_p: PhantomData,
})
}
fn iter(&self) -> impl Iterator<Item = NonNull<T::PointedTo>> + '_ {
let mut index = 0;
// SAFETY: `self.xa` is always valid by the type invariant.
iter::once(unsafe {
bindings::xa_find(self.xa.get(), &mut index, usize::MAX, bindings::XA_PRESENT)
})
.chain(iter::from_fn(move || {
// SAFETY: `self.xa` is always valid by the type invariant.
Some(unsafe {
bindings::xa_find_after(self.xa.get(), &mut index, usize::MAX, bindings::XA_PRESENT)
})
}))
.map_while(|ptr| NonNull::new(ptr.cast()))
}
/// Attempts to lock the [`XArray`] for exclusive access.
pub fn try_lock(&self) -> Option<Guard<'_, T>> {
// SAFETY: `self.xa` is always valid by the type invariant.
if (unsafe { bindings::xa_trylock(self.xa.get()) } != 0) {
Some(Guard {
xa: self,
_not_send: NotThreadSafe,
})
} else {
None
}
}
/// Locks the [`XArray`] for exclusive access.
pub fn lock(&self) -> Guard<'_, T> {
// SAFETY: `self.xa` is always valid by the type invariant.
unsafe { bindings::xa_lock(self.xa.get()) };
Guard {
xa: self,
_not_send: NotThreadSafe,
}
}
}
/// A lock guard.
///
/// The lock is unlocked when the guard goes out of scope.
#[must_use = "the lock unlocks immediately when the guard is unused"]
pub struct Guard<'a, T: ForeignOwnable> {
xa: &'a XArray<T>,
_not_send: NotThreadSafe,
}
impl<T: ForeignOwnable> Drop for Guard<'_, T> {
fn drop(&mut self) {
// SAFETY:
// - `self.xa.xa` is always valid by the type invariant.
// - The caller holds the lock, so it is safe to unlock it.
unsafe { bindings::xa_unlock(self.xa.xa.get()) };
}
}
/// The error returned by [`store`](Guard::store).
///
/// Contains the underlying error and the value that was not stored.
pub struct StoreError<T> {
/// The error that occurred.
pub error: Error,
/// The value that was not stored.
pub value: T,
}
impl<T> From<StoreError<T>> for Error {
fn from(value: StoreError<T>) -> Self {
value.error
}
}
impl<'a, T: ForeignOwnable> Guard<'a, T> {
fn load<F, U>(&self, index: usize, f: F) -> Option<U>
where
F: FnOnce(NonNull<T::PointedTo>) -> U,
{
// SAFETY: `self.xa.xa` is always valid by the type invariant.
let ptr = unsafe { bindings::xa_load(self.xa.xa.get(), index) };
let ptr = NonNull::new(ptr.cast())?;
Some(f(ptr))
}
/// Provides a reference to the element at the given index.
pub fn get(&self, index: usize) -> Option<T::Borrowed<'_>> {
self.load(index, |ptr| {
// SAFETY: `ptr` came from `T::into_foreign`.
unsafe { T::borrow(ptr.as_ptr()) }
})
}
/// Provides a mutable reference to the element at the given index.
pub fn get_mut(&mut self, index: usize) -> Option<T::BorrowedMut<'_>> {
self.load(index, |ptr| {
// SAFETY: `ptr` came from `T::into_foreign`.
unsafe { T::borrow_mut(ptr.as_ptr()) }
})
}
/// Removes and returns the element at the given index.
pub fn remove(&mut self, index: usize) -> Option<T> {
// SAFETY:
// - `self.xa.xa` is always valid by the type invariant.
// - The caller holds the lock.
let ptr = unsafe { bindings::__xa_erase(self.xa.xa.get(), index) }.cast();
// SAFETY:
// - `ptr` is either NULL or came from `T::into_foreign`.
// - `&mut self` guarantees that the lifetimes of [`T::Borrowed`] and [`T::BorrowedMut`]
// borrowed from `self` have ended.
unsafe { T::try_from_foreign(ptr) }
}
/// Stores an element at the given index.
///
/// May drop the lock if needed to allocate memory, and then reacquire it afterwards.
///
/// On success, returns the element which was previously at the given index.
///
/// On failure, returns the element which was attempted to be stored.
pub fn store(
&mut self,
index: usize,
value: T,
gfp: alloc::Flags,
) -> Result<Option<T>, StoreError<T>> {
build_assert!(
mem::align_of::<T::PointedTo>() >= 4,
"pointers stored in XArray must be 4-byte aligned"
);
let new = value.into_foreign();
let old = {
let new = new.cast();
// SAFETY:
// - `self.xa.xa` is always valid by the type invariant.
// - The caller holds the lock.
//
// INVARIANT: `new` came from `T::into_foreign`.
unsafe { bindings::__xa_store(self.xa.xa.get(), index, new, gfp.as_raw()) }
};
// SAFETY: `__xa_store` returns the old entry at this index on success or `xa_err` if an
// error happened.
let errno = unsafe { bindings::xa_err(old) };
if errno != 0 {
// SAFETY: `new` came from `T::into_foreign` and `__xa_store` does not take
// ownership of the value on error.
let value = unsafe { T::from_foreign(new) };
Err(StoreError {
value,
error: Error::from_errno(errno),
})
} else {
let old = old.cast();
// SAFETY: `ptr` is either NULL or came from `T::into_foreign`.
//
// NB: `XA_ZERO_ENTRY` is never returned by functions belonging to the Normal XArray
// API; such entries present as `NULL`.
Ok(unsafe { T::try_from_foreign(old) })
}
}
}
// SAFETY: `XArray<T>` has no shared mutable state so it is `Send` iff `T` is `Send`.
unsafe impl<T: ForeignOwnable + Send> Send for XArray<T> {}
// SAFETY: `XArray<T>` serialises the interior mutability it provides so it is `Sync` iff `T` is
// `Send`.
unsafe impl<T: ForeignOwnable + Send> Sync for XArray<T> {}

17
rust/macros/helpers.rs
View file

@ -86,3 +86,20 @@ pub(crate) fn function_name(input: TokenStream) -> Option<Ident> {
}
None
}
pub(crate) fn file() -> String {
#[cfg(not(CONFIG_RUSTC_HAS_SPAN_FILE))]
{
proc_macro::Span::call_site()
.source_file()
.path()
.to_string_lossy()
.into_owned()
}
#[cfg(CONFIG_RUSTC_HAS_SPAN_FILE)]
#[allow(clippy::incompatible_msrv)]
{
proc_macro::Span::call_site().file()
}
}

58
rust/macros/kunit.rs
View file

@ -57,8 +57,8 @@ pub(crate) fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream {
}
}
// Add `#[cfg(CONFIG_KUNIT)]` before the module declaration.
let config_kunit = "#[cfg(CONFIG_KUNIT)]".to_owned().parse().unwrap();
// Add `#[cfg(CONFIG_KUNIT="y")]` before the module declaration.
let config_kunit = "#[cfg(CONFIG_KUNIT=\"y\")]".to_owned().parse().unwrap();
tokens.insert(
0,
TokenTree::Group(Group::new(Delimiter::None, config_kunit)),
@ -85,28 +85,52 @@ pub(crate) fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream {
// Looks like:
//
// ```
// unsafe extern "C" fn kunit_rust_wrapper_foo(_test: *mut kernel::bindings::kunit) { foo(); }
// unsafe extern "C" fn kunit_rust_wrapper_bar(_test: *mut kernel::bindings::kunit) { bar(); }
// unsafe extern "C" fn kunit_rust_wrapper_foo(_test: *mut ::kernel::bindings::kunit) { foo(); }
// unsafe extern "C" fn kunit_rust_wrapper_bar(_test: *mut ::kernel::bindings::kunit) { bar(); }
//
// static mut TEST_CASES: [kernel::bindings::kunit_case; 3] = [
// kernel::kunit::kunit_case(kernel::c_str!("foo"), kunit_rust_wrapper_foo),
// kernel::kunit::kunit_case(kernel::c_str!("bar"), kunit_rust_wrapper_bar),
// kernel::kunit::kunit_case_null(),
// static mut TEST_CASES: [::kernel::bindings::kunit_case; 3] = [
// ::kernel::kunit::kunit_case(::kernel::c_str!("foo"), kunit_rust_wrapper_foo),
// ::kernel::kunit::kunit_case(::kernel::c_str!("bar"), kunit_rust_wrapper_bar),
// ::kernel::kunit::kunit_case_null(),
// ];
//
// kernel::kunit_unsafe_test_suite!(kunit_test_suit_name, TEST_CASES);
// ::kernel::kunit_unsafe_test_suite!(kunit_test_suit_name, TEST_CASES);
// ```
let mut kunit_macros = "".to_owned();
let mut test_cases = "".to_owned();
let mut assert_macros = "".to_owned();
let path = crate::helpers::file();
for test in &tests {
let kunit_wrapper_fn_name = format!("kunit_rust_wrapper_{test}");
// An extra `use` is used here to reduce the length of the message.
let kunit_wrapper = format!(
"unsafe extern \"C\" fn {kunit_wrapper_fn_name}(_test: *mut kernel::bindings::kunit) {{ {test}(); }}"
"unsafe extern \"C\" fn {kunit_wrapper_fn_name}(_test: *mut ::kernel::bindings::kunit) {{ use ::kernel::kunit::is_test_result_ok; assert!(is_test_result_ok({test}())); }}",
);
writeln!(kunit_macros, "{kunit_wrapper}").unwrap();
writeln!(
test_cases,
" kernel::kunit::kunit_case(kernel::c_str!(\"{test}\"), {kunit_wrapper_fn_name}),"
" ::kernel::kunit::kunit_case(::kernel::c_str!(\"{test}\"), {kunit_wrapper_fn_name}),"
)
.unwrap();
writeln!(
assert_macros,
r#"
/// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
#[allow(unused)]
macro_rules! assert {{
($cond:expr $(,)?) => {{{{
kernel::kunit_assert!("{test}", "{path}", 0, $cond);
}}}}
}}
/// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
#[allow(unused)]
macro_rules! assert_eq {{
($left:expr, $right:expr $(,)?) => {{{{
kernel::kunit_assert_eq!("{test}", "{path}", 0, $left, $right);
}}}}
}}
"#
)
.unwrap();
}
@ -114,14 +138,14 @@ pub(crate) fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream {
writeln!(kunit_macros).unwrap();
writeln!(
kunit_macros,
"static mut TEST_CASES: [kernel::bindings::kunit_case; {}] = [\n{test_cases} kernel::kunit::kunit_case_null(),\n];",
"static mut TEST_CASES: [::kernel::bindings::kunit_case; {}] = [\n{test_cases} ::kernel::kunit::kunit_case_null(),\n];",
tests.len() + 1
)
.unwrap();
writeln!(
kunit_macros,
"kernel::kunit_unsafe_test_suite!({attr}, TEST_CASES);"
"::kernel::kunit_unsafe_test_suite!({attr}, TEST_CASES);"
)
.unwrap();
@ -147,10 +171,12 @@ pub(crate) fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream {
}
}
let mut new_body = TokenStream::from_iter(new_body);
new_body.extend::<TokenStream>(kunit_macros.parse().unwrap());
let mut final_body = TokenStream::new();
final_body.extend::<TokenStream>(assert_macros.parse().unwrap());
final_body.extend(new_body);
final_body.extend::<TokenStream>(kunit_macros.parse().unwrap());
tokens.push(TokenTree::Group(Group::new(Delimiter::Brace, new_body)));
tokens.push(TokenTree::Group(Group::new(Delimiter::Brace, final_body)));
tokens.into_iter().collect()
}

15
rust/macros/lib.rs
View file

@ -6,6 +6,11 @@
// and thus add a dependency on `include/config/RUSTC_VERSION_TEXT`, which is
// touched by Kconfig when the version string from the compiler changes.
// Stable since Rust 1.88.0 under a different name, `proc_macro_span_file`,
// which was added in Rust 1.88.0. This is why `cfg_attr` is used here, i.e.
// to avoid depending on the full `proc_macro_span` on Rust >= 1.88.0.
#![cfg_attr(not(CONFIG_RUSTC_HAS_SPAN_FILE), feature(proc_macro_span))]
#[macro_use]
mod quote;
mod concat_idents;
@ -263,7 +268,7 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream {
/// literals (lifetimes and documentation strings are not supported). There is a difference in
/// supported modifiers as well.
///
/// # Example
/// # Examples
///
/// ```
/// # const binder_driver_return_protocol_BR_OK: u32 = 0;
@ -283,7 +288,7 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream {
/// # const binder_driver_return_protocol_BR_FAILED_REPLY: u32 = 14;
/// macro_rules! pub_no_prefix {
/// ($prefix:ident, $($newname:ident),+) => {
/// kernel::macros::paste! {
/// ::kernel::macros::paste! {
/// $(pub(crate) const $newname: u32 = [<$prefix $newname>];)+
/// }
/// };
@ -340,7 +345,7 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream {
/// # const binder_driver_return_protocol_BR_FAILED_REPLY: u32 = 14;
/// macro_rules! pub_no_prefix {
/// ($prefix:ident, $($newname:ident),+) => {
/// kernel::macros::paste! {
/// ::kernel::macros::paste! {
/// $(pub(crate) const fn [<$newname:lower:span>]() -> u32 { [<$prefix $newname:span>] })+
/// }
/// };
@ -375,7 +380,7 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream {
/// ```
/// macro_rules! create_numbered_fn {
/// ($name:literal, $val:literal) => {
/// kernel::macros::paste! {
/// ::kernel::macros::paste! {
/// fn [<some_ $name _fn $val>]() -> u32 { $val }
/// }
/// };
@ -402,7 +407,7 @@ pub fn paste(input: TokenStream) -> TokenStream {
/// # Examples
///
/// ```ignore
/// # use macros::kunit_tests;
/// # use kernel::prelude::*;
/// #[kunit_tests(kunit_test_suit_name)]
/// mod tests {
/// #[test]

31
rust/macros/module.rs
View file

@ -217,24 +217,24 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
// SAFETY: `__this_module` is constructed by the kernel at load time and will not be
// freed until the module is unloaded.
#[cfg(MODULE)]
static THIS_MODULE: kernel::ThisModule = unsafe {{
static THIS_MODULE: ::kernel::ThisModule = unsafe {{
extern \"C\" {{
static __this_module: kernel::types::Opaque<kernel::bindings::module>;
static __this_module: ::kernel::types::Opaque<::kernel::bindings::module>;
}}
kernel::ThisModule::from_ptr(__this_module.get())
::kernel::ThisModule::from_ptr(__this_module.get())
}};
#[cfg(not(MODULE))]
static THIS_MODULE: kernel::ThisModule = unsafe {{
kernel::ThisModule::from_ptr(core::ptr::null_mut())
static THIS_MODULE: ::kernel::ThisModule = unsafe {{
::kernel::ThisModule::from_ptr(::core::ptr::null_mut())
}};
/// The `LocalModule` type is the type of the module created by `module!`,
/// `module_pci_driver!`, `module_platform_driver!`, etc.
type LocalModule = {type_};
impl kernel::ModuleMetadata for {type_} {{
const NAME: &'static kernel::str::CStr = kernel::c_str!(\"{name}\");
impl ::kernel::ModuleMetadata for {type_} {{
const NAME: &'static ::kernel::str::CStr = ::kernel::c_str!(\"{name}\");
}}
// Double nested modules, since then nobody can access the public items inside.
@ -252,8 +252,8 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
#[used]
static __IS_RUST_MODULE: () = ();
static mut __MOD: core::mem::MaybeUninit<{type_}> =
core::mem::MaybeUninit::uninit();
static mut __MOD: ::core::mem::MaybeUninit<{type_}> =
::core::mem::MaybeUninit::uninit();
// Loadable modules need to export the `{{init,cleanup}}_module` identifiers.
/// # Safety
@ -264,7 +264,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
#[doc(hidden)]
#[no_mangle]
#[link_section = \".init.text\"]
pub unsafe extern \"C\" fn init_module() -> kernel::ffi::c_int {{
pub unsafe extern \"C\" fn init_module() -> ::kernel::ffi::c_int {{
// SAFETY: This function is inaccessible to the outside due to the double
// module wrapping it. It is called exactly once by the C side via its
// unique name.
@ -280,6 +280,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
#[cfg(MODULE)]
#[doc(hidden)]
#[no_mangle]
#[link_section = \".exit.text\"]
pub extern \"C\" fn cleanup_module() {{
// SAFETY:
// - This function is inaccessible to the outside due to the double
@ -304,11 +305,11 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
#[link_section = \"{initcall_section}\"]
#[used]
pub static __{ident}_initcall: extern \"C\" fn() ->
kernel::ffi::c_int = __{ident}_init;
::kernel::ffi::c_int = __{ident}_init;
#[cfg(not(MODULE))]
#[cfg(CONFIG_HAVE_ARCH_PREL32_RELOCATIONS)]
core::arch::global_asm!(
::core::arch::global_asm!(
r#\".section \"{initcall_section}\", \"a\"
__{ident}_initcall:
.long __{ident}_init - .
@ -319,7 +320,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
#[cfg(not(MODULE))]
#[doc(hidden)]
#[no_mangle]
pub extern \"C\" fn __{ident}_init() -> kernel::ffi::c_int {{
pub extern \"C\" fn __{ident}_init() -> ::kernel::ffi::c_int {{
// SAFETY: This function is inaccessible to the outside due to the double
// module wrapping it. It is called exactly once by the C side via its
// placement above in the initcall section.
@ -342,9 +343,9 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream {
/// # Safety
///
/// This function must only be called once.
unsafe fn __init() -> kernel::ffi::c_int {{
unsafe fn __init() -> ::kernel::ffi::c_int {{
let initer =
<{type_} as kernel::InPlaceModule>::init(&super::super::THIS_MODULE);
<{type_} as ::kernel::InPlaceModule>::init(&super::super::THIS_MODULE);
// SAFETY: No data race, since `__MOD` can only be accessed by this module
// and there only `__init` and `__exit` access it. These functions are only
// called once and `__exit` cannot be called before or during `__init`.

14
rust/pin-init/README.md
View file

@ -40,6 +40,12 @@ However, using the crate on stable compilers is possible by disabling `alloc`. I
will require the `std` feature, because stable compilers have neither `Box` nor `Arc` in no-std
mode.
### Nightly needed for `unsafe-pinned` feature
This feature enables the `Wrapper` implementation on the unstable `core::pin::UnsafePinned` type.
This requires the [`unsafe_pinned` unstable feature](https://github.com/rust-lang/rust/issues/125735)
and therefore a nightly compiler. Note that this feature is not enabled by default.
## Overview
To initialize a `struct` with an in-place constructor you will need two things:
@ -216,13 +222,15 @@ the `kernel` crate. The [`sync`] module is a good starting point.
[`sync`]: https://rust.docs.kernel.org/kernel/sync/index.html
[pinning]: https://doc.rust-lang.org/std/pin/index.html
[structurally pinned fields]: https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field
[structurally pinned fields]: https://doc.rust-lang.org/std/pin/index.html#projections-and-structural-pinning
[stack]: https://docs.rs/pin-init/latest/pin_init/macro.stack_pin_init.html
[`Arc<T>`]: https://doc.rust-lang.org/stable/alloc/sync/struct.Arc.html
[`Box<T>`]: https://doc.rust-lang.org/stable/alloc/boxed/struct.Box.html
[`impl PinInit<Foo>`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html
[`impl PinInit<T, E>`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html
[`impl Init<T, E>`]: https://docs.rs/pin-init/latest/pin_init/trait.Init.html
[Rust-for-Linux]: https://rust-for-linux.com/
<!-- cargo-rdme end -->
<!-- These links are not picked up by cargo-rdme, since they are behind cfgs... -->
[`Arc<T>`]: https://doc.rust-lang.org/stable/alloc/sync/struct.Arc.html
[`Box<T>`]: https://doc.rust-lang.org/stable/alloc/boxed/struct.Box.html

1
rust/pin-init/examples/linked_list.rs
View file

@ -2,6 +2,7 @@
#![allow(clippy::undocumented_unsafe_blocks)]
#![cfg_attr(feature = "alloc", feature(allocator_api))]
#![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))]
use core::{
cell::Cell,

1
rust/pin-init/examples/mutex.rs
View file

@ -2,6 +2,7 @@
#![allow(clippy::undocumented_unsafe_blocks)]
#![cfg_attr(feature = "alloc", feature(allocator_api))]
#![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))]
#![allow(clippy::missing_safety_doc)]
use core::{

4
rust/pin-init/examples/pthread_mutex.rs
View file

@ -3,6 +3,8 @@
// inspired by <https://github.com/nbdd0121/pin-init/blob/trunk/examples/pthread_mutex.rs>
#![allow(clippy::undocumented_unsafe_blocks)]
#![cfg_attr(feature = "alloc", feature(allocator_api))]
#![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))]
#[cfg(not(windows))]
mod pthread_mtx {
#[cfg(feature = "alloc")]
@ -40,7 +42,7 @@ mod pthread_mtx {
#[derive(Debug)]
pub enum Error {
#[expect(dead_code)]
#[allow(dead_code)]
IO(std::io::Error),
Alloc,
}

1
rust/pin-init/examples/static_init.rs
View file

@ -2,6 +2,7 @@
#![allow(clippy::undocumented_unsafe_blocks)]
#![cfg_attr(feature = "alloc", feature(allocator_api))]
#![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))]
use core::{
cell::{Cell, UnsafeCell},

6
rust/pin-init/internal/src/lib.rs
View file

@ -22,6 +22,7 @@ use proc_macro::TokenStream;
#[cfg(kernel)]
#[path = "../../../macros/quote.rs"]
#[macro_use]
#[cfg_attr(not(kernel), rustfmt::skip)]
mod quote;
#[cfg(not(kernel))]
#[macro_use]
@ -46,3 +47,8 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
pub fn derive_zeroable(input: TokenStream) -> TokenStream {
zeroable::derive(input.into()).into()
}
#[proc_macro_derive(MaybeZeroable)]
pub fn maybe_derive_zeroable(input: TokenStream) -> TokenStream {
zeroable::maybe_derive(input.into()).into()
}

27
rust/pin-init/internal/src/zeroable.rs
View file

@ -6,7 +6,14 @@ use proc_macro2 as proc_macro;
use crate::helpers::{parse_generics, Generics};
use proc_macro::{TokenStream, TokenTree};
pub(crate) fn derive(input: TokenStream) -> TokenStream {
pub(crate) fn parse_zeroable_derive_input(
input: TokenStream,
) -> (
Vec<TokenTree>,
Vec<TokenTree>,
Vec<TokenTree>,
Option<TokenTree>,
) {
let (
Generics {
impl_generics,
@ -64,6 +71,11 @@ pub(crate) fn derive(input: TokenStream) -> TokenStream {
if in_generic && !inserted {
new_impl_generics.extend(quote! { : ::pin_init::Zeroable });
}
(rest, new_impl_generics, ty_generics, last)
}
pub(crate) fn derive(input: TokenStream) -> TokenStream {
let (rest, new_impl_generics, ty_generics, last) = parse_zeroable_derive_input(input);
quote! {
::pin_init::__derive_zeroable!(
parse_input:
@ -74,3 +86,16 @@ pub(crate) fn derive(input: TokenStream) -> TokenStream {
);
}
}
pub(crate) fn maybe_derive(input: TokenStream) -> TokenStream {
let (rest, new_impl_generics, ty_generics, last) = parse_zeroable_derive_input(input);
quote! {
::pin_init::__maybe_derive_zeroable!(
parse_input:
@sig(#(#rest)*),
@impl_generics(#(#new_impl_generics)*),
@ty_generics(#(#ty_generics)*),
@body(#last),
);
}
}

144
rust/pin-init/src/lib.rs
View file

@ -32,6 +32,12 @@
//! will require the `std` feature, because stable compilers have neither `Box` nor `Arc` in no-std
//! mode.
//!
//! ## Nightly needed for `unsafe-pinned` feature
//!
//! This feature enables the `Wrapper` implementation on the unstable `core::pin::UnsafePinned` type.
//! This requires the [`unsafe_pinned` unstable feature](https://github.com/rust-lang/rust/issues/125735)
//! and therefore a nightly compiler. Note that this feature is not enabled by default.
//!
//! # Overview
//!
//! To initialize a `struct` with an in-place constructor you will need two things:
@ -241,7 +247,7 @@
//! [`sync`]: https://rust.docs.kernel.org/kernel/sync/index.html
//! [pinning]: https://doc.rust-lang.org/std/pin/index.html
//! [structurally pinned fields]:
//! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field
//! https://doc.rust-lang.org/std/pin/index.html#projections-and-structural-pinning
//! [stack]: crate::stack_pin_init
#![cfg_attr(
kernel,
@ -269,6 +275,10 @@
#![forbid(missing_docs, unsafe_op_in_unsafe_fn)]
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(feature = "alloc", feature(allocator_api))]
#![cfg_attr(
all(feature = "unsafe-pinned", CONFIG_RUSTC_HAS_UNSAFE_PINNED),
feature(unsafe_pinned)
)]
use core::{
cell::UnsafeCell,
@ -385,9 +395,10 @@ pub use ::pin_init_internal::pin_data;
/// ```
pub use ::pin_init_internal::pinned_drop;
/// Derives the [`Zeroable`] trait for the given struct.
/// Derives the [`Zeroable`] trait for the given `struct` or `union`.
///
/// This can only be used for structs where every field implements the [`Zeroable`] trait.
/// This can only be used for `struct`s/`union`s where every field implements the [`Zeroable`]
/// trait.
///
/// # Examples
///
@ -396,13 +407,54 @@ pub use ::pin_init_internal::pinned_drop;
///
/// #[derive(Zeroable)]
/// pub struct DriverData {
/// id: i64,
/// pub(crate) id: i64,
/// buf_ptr: *mut u8,
/// len: usize,
/// }
/// ```
///
/// ```
/// use pin_init::Zeroable;
///
/// #[derive(Zeroable)]
/// pub union SignCast {
/// signed: i64,
/// unsigned: u64,
/// }
/// ```
pub use ::pin_init_internal::Zeroable;
/// Derives the [`Zeroable`] trait for the given `struct` or `union` if all fields implement
/// [`Zeroable`].
///
/// Contrary to the derive macro named [`macro@Zeroable`], this one silently fails when a field
/// doesn't implement [`Zeroable`].
///
/// # Examples
///
/// ```
/// use pin_init::MaybeZeroable;
///
/// // implmements `Zeroable`
/// #[derive(MaybeZeroable)]
/// pub struct DriverData {
/// pub(crate) id: i64,
/// buf_ptr: *mut u8,
/// len: usize,
/// }
///
/// // does not implmement `Zeroable`
/// #[derive(MaybeZeroable)]
/// pub struct DriverData2 {
/// pub(crate) id: i64,
/// buf_ptr: *mut u8,
/// len: usize,
/// // this field doesn't implement `Zeroable`
/// other_data: &'static i32,
/// }
/// ```
pub use ::pin_init_internal::MaybeZeroable;
/// Initialize and pin a type directly on the stack.
///
/// # Examples
@ -1216,6 +1268,38 @@ pub const unsafe fn init_from_closure<T: ?Sized, E>(
__internal::InitClosure(f, PhantomData)
}
/// Changes the to be initialized type.
///
/// # Safety
///
/// - `*mut U` must be castable to `*mut T` and any value of type `T` written through such a
/// pointer must result in a valid `U`.
#[expect(clippy::let_and_return)]
pub const unsafe fn cast_pin_init<T, U, E>(init: impl PinInit<T, E>) -> impl PinInit<U, E> {
// SAFETY: initialization delegated to a valid initializer. Cast is valid by function safety
// requirements.
let res = unsafe { pin_init_from_closure(|ptr: *mut U| init.__pinned_init(ptr.cast::<T>())) };
// FIXME: remove the let statement once the nightly-MSRV allows it (1.78 otherwise encounters a
// cycle when computing the type returned by this function)
res
}
/// Changes the to be initialized type.
///
/// # Safety
///
/// - `*mut U` must be castable to `*mut T` and any value of type `T` written through such a
/// pointer must result in a valid `U`.
#[expect(clippy::let_and_return)]
pub const unsafe fn cast_init<T, U, E>(init: impl Init<T, E>) -> impl Init<U, E> {
// SAFETY: initialization delegated to a valid initializer. Cast is valid by function safety
// requirements.
let res = unsafe { init_from_closure(|ptr: *mut U| init.__init(ptr.cast::<T>())) };
// FIXME: remove the let statement once the nightly-MSRV allows it (1.78 otherwise encounters a
// cycle when computing the type returned by this function)
res
}
/// An initializer that leaves the memory uninitialized.
///
/// The initializer is a no-op. The `slot` memory is not changed.
@ -1481,3 +1565,55 @@ macro_rules! impl_tuple_zeroable {
}
impl_tuple_zeroable!(A, B, C, D, E, F, G, H, I, J);
/// This trait allows creating an instance of `Self` which contains exactly one
/// [structurally pinned value](https://doc.rust-lang.org/std/pin/index.html#projections-and-structural-pinning).
///
/// This is useful when using wrapper `struct`s like [`UnsafeCell`] or with new-type `struct`s.
///
/// # Examples
///
/// ```
/// # use core::cell::UnsafeCell;
/// # use pin_init::{pin_data, pin_init, Wrapper};
///
/// #[pin_data]
/// struct Foo {}
///
/// #[pin_data]
/// struct Bar {
/// #[pin]
/// content: UnsafeCell<Foo>
/// };
///
/// let foo_initializer = pin_init!(Foo{});
/// let initializer = pin_init!(Bar {
/// content <- UnsafeCell::pin_init(foo_initializer)
/// });
/// ```
pub trait Wrapper<T> {
/// Creates an pin-initializer for a [`Self`] containing `T` from the `value_init` initializer.
fn pin_init<E>(value_init: impl PinInit<T, E>) -> impl PinInit<Self, E>;
}
impl<T> Wrapper<T> for UnsafeCell<T> {
fn pin_init<E>(value_init: impl PinInit<T, E>) -> impl PinInit<Self, E> {
// SAFETY: `UnsafeCell<T>` has a compatible layout to `T`.
unsafe { cast_pin_init(value_init) }
}
}
impl<T> Wrapper<T> for MaybeUninit<T> {
fn pin_init<E>(value_init: impl PinInit<T, E>) -> impl PinInit<Self, E> {
// SAFETY: `MaybeUninit<T>` has a compatible layout to `T`.
unsafe { cast_pin_init(value_init) }
}
}
#[cfg(all(feature = "unsafe-pinned", CONFIG_RUSTC_HAS_UNSAFE_PINNED))]
impl<T> Wrapper<T> for core::pin::UnsafePinned<T> {
fn pin_init<E>(init: impl PinInit<T, E>) -> impl PinInit<Self, E> {
// SAFETY: `UnsafePinned<T>` has a compatible layout to `T`.
unsafe { cast_pin_init(init) }
}
}

91
rust/pin-init/src/macros.rs
View file

@ -1393,7 +1393,37 @@ macro_rules! __derive_zeroable {
@body({
$(
$(#[$($field_attr:tt)*])*
$field:ident : $field_ty:ty
$field_vis:vis $field:ident : $field_ty:ty
),* $(,)?
}),
) => {
// SAFETY: Every field type implements `Zeroable` and padding bytes may be zero.
#[automatically_derived]
unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*>
where
$($($whr)*)?
{}
const _: () = {
fn assert_zeroable<T: ?::core::marker::Sized + $crate::Zeroable>() {}
fn ensure_zeroable<$($impl_generics)*>()
where $($($whr)*)?
{
$(assert_zeroable::<$field_ty>();)*
}
};
};
(parse_input:
@sig(
$(#[$($struct_attr:tt)*])*
$vis:vis union $name:ident
$(where $($whr:tt)*)?
),
@impl_generics($($impl_generics:tt)*),
@ty_generics($($ty_generics:tt)*),
@body({
$(
$(#[$($field_attr:tt)*])*
$field_vis:vis $field:ident : $field_ty:ty
),* $(,)?
}),
) => {
@ -1413,3 +1443,62 @@ macro_rules! __derive_zeroable {
};
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __maybe_derive_zeroable {
(parse_input:
@sig(
$(#[$($struct_attr:tt)*])*
$vis:vis struct $name:ident
$(where $($whr:tt)*)?
),
@impl_generics($($impl_generics:tt)*),
@ty_generics($($ty_generics:tt)*),
@body({
$(
$(#[$($field_attr:tt)*])*
$field_vis:vis $field:ident : $field_ty:ty
),* $(,)?
}),
) => {
// SAFETY: Every field type implements `Zeroable` and padding bytes may be zero.
#[automatically_derived]
unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*>
where
$(
// the `for<'__dummy>` HRTB makes this not error without the `trivial_bounds`
// feature <https://github.com/rust-lang/rust/issues/48214#issuecomment-2557829956>.
$field_ty: for<'__dummy> $crate::Zeroable,
)*
$($($whr)*)?
{}
};
(parse_input:
@sig(
$(#[$($struct_attr:tt)*])*
$vis:vis union $name:ident
$(where $($whr:tt)*)?
),
@impl_generics($($impl_generics:tt)*),
@ty_generics($($ty_generics:tt)*),
@body({
$(
$(#[$($field_attr:tt)*])*
$field_vis:vis $field:ident : $field_ty:ty
),* $(,)?
}),
) => {
// SAFETY: Every field type implements `Zeroable` and padding bytes may be zero.
#[automatically_derived]
unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*>
where
$(
// the `for<'__dummy>` HRTB makes this not error without the `trivial_bounds`
// feature <https://github.com/rust-lang/rust/issues/48214#issuecomment-2557829956>.
$field_ty: for<'__dummy> $crate::Zeroable,
)*
$($($whr)*)?
{}
};
}

9
scripts/Makefile.build
View file

@ -222,6 +222,15 @@ $(obj)/%.lst: $(obj)/%.c FORCE
# Compile Rust sources (.rs)
# ---------------------------------------------------------------------------
# The features in this list are the ones allowed for non-`rust/` code.
#
# - Stable since Rust 1.81.0: `feature(lint_reasons)`.
# - Stable since Rust 1.82.0: `feature(asm_const)`, `feature(raw_ref_op)`.
# - Stable since Rust 1.87.0: `feature(asm_goto)`.
# - Expected to become stable: `feature(arbitrary_self_types)`.
#
# Please see https://github.com/Rust-for-Linux/linux/issues/2 for details on
# the unstable features in use.
rust_allowed_features := asm_const,asm_goto,arbitrary_self_types,lint_reasons,raw_ref_op
# `--out-dir` is required to avoid temporaries being created by `rustc` in the

13
scripts/generate_rust_analyzer.py
View file

@ -19,7 +19,7 @@ def args_crates_cfgs(cfgs):
return crates_cfgs
def generate_crates(srctree, objtree, sysroot_src, external_src, cfgs):
def generate_crates(srctree, objtree, sysroot_src, external_src, cfgs, core_edition):
# Generate the configuration list.
cfg = []
with open(objtree / "include" / "generated" / "rustc_cfg") as fd:
@ -35,7 +35,7 @@ def generate_crates(srctree, objtree, sysroot_src, external_src, cfgs):
crates_indexes = {}
crates_cfgs = args_crates_cfgs(cfgs)
def append_crate(display_name, root_module, deps, cfg=[], is_workspace_member=True, is_proc_macro=False):
def append_crate(display_name, root_module, deps, cfg=[], is_workspace_member=True, is_proc_macro=False, edition="2021"):
crate = {
"display_name": display_name,
"root_module": str(root_module),
@ -43,7 +43,7 @@ def generate_crates(srctree, objtree, sysroot_src, external_src, cfgs):
"is_proc_macro": is_proc_macro,
"deps": [{"crate": crates_indexes[dep], "name": dep} for dep in deps],
"cfg": cfg,
"edition": "2021",
"edition": edition,
"env": {
"RUST_MODFILE": "This is only for rust-analyzer"
}
@ -61,6 +61,7 @@ def generate_crates(srctree, objtree, sysroot_src, external_src, cfgs):
display_name,
deps,
cfg=[],
edition="2021",
):
append_crate(
display_name,
@ -68,12 +69,13 @@ def generate_crates(srctree, objtree, sysroot_src, external_src, cfgs):
deps,
cfg,
is_workspace_member=False,
edition=edition,
)
# NB: sysroot crates reexport items from one another so setting up our transitive dependencies
# here is important for ensuring that rust-analyzer can resolve symbols. The sources of truth
# for this dependency graph are `(sysroot_src / crate / "Cargo.toml" for crate in crates)`.
append_sysroot_crate("core", [], cfg=crates_cfgs.get("core", []))
append_sysroot_crate("core", [], cfg=crates_cfgs.get("core", []), edition=core_edition)
append_sysroot_crate("alloc", ["core"])
append_sysroot_crate("std", ["alloc", "core"])
append_sysroot_crate("proc_macro", ["core", "std"])
@ -177,6 +179,7 @@ def main():
parser = argparse.ArgumentParser()
parser.add_argument('--verbose', '-v', action='store_true')
parser.add_argument('--cfgs', action='append', default=[])
parser.add_argument("core_edition")
parser.add_argument("srctree", type=pathlib.Path)
parser.add_argument("objtree", type=pathlib.Path)
parser.add_argument("sysroot", type=pathlib.Path)
@ -193,7 +196,7 @@ def main():
assert args.sysroot in args.sysroot_src.parents
rust_project = {
"crates": generate_crates(args.srctree, args.objtree, args.sysroot_src, args.exttree, args.cfgs),
"crates": generate_crates(args.srctree, args.objtree, args.sysroot_src, args.exttree, args.cfgs, args.core_edition),
"sysroot": str(args.sysroot),
}

4
scripts/generate_rust_target.rs
View file

@ -209,7 +209,7 @@ fn main() {
// target feature of the same name plus the other two target features in
// `clang/lib/Driver/ToolChains/Arch/X86.cpp`. These should be eventually enabled via
// `-Ctarget-feature` when `rustc` starts recognizing them (or via a new dedicated
// flag); see https://github.com/rust-lang/rust/issues/116852.
// flag); see <https://github.com/rust-lang/rust/issues/116852>.
features += ",+retpoline-external-thunk";
features += ",+retpoline-indirect-branches";
features += ",+retpoline-indirect-calls";
@ -218,7 +218,7 @@ fn main() {
// The kernel uses `-mharden-sls=all`, which Clang maps to both these target features in
// `clang/lib/Driver/ToolChains/Arch/X86.cpp`. These should be eventually enabled via
// `-Ctarget-feature` when `rustc` starts recognizing them (or via a new dedicated
// flag); see https://github.com/rust-lang/rust/issues/116851.
// flag); see <https://github.com/rust-lang/rust/issues/116851>.
features += ",+harden-sls-ijmp";
features += ",+harden-sls-ret";
}

8
scripts/rustdoc_test_builder.rs
View file

@ -28,7 +28,7 @@ fn main() {
//
// ```
// fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_28_0() {
// fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_37_0() -> Result<(), impl core::fmt::Debug> {
// fn main() { #[allow(non_snake_case)] fn _doctest_main_rust_kernel_file_rs_37_0() -> Result<(), impl ::core::fmt::Debug> {
// ```
//
// It should be unlikely that doctest code matches such lines (when code is formatted properly).
@ -49,8 +49,10 @@ fn main() {
// Qualify `Result` to avoid the collision with our own `Result` coming from the prelude.
let body = body.replace(
&format!("{rustdoc_function_name}() -> Result<(), impl core::fmt::Debug> {{"),
&format!("{rustdoc_function_name}() -> core::result::Result<(), impl core::fmt::Debug> {{"),
&format!("{rustdoc_function_name}() -> Result<(), impl ::core::fmt::Debug> {{"),
&format!(
"{rustdoc_function_name}() -> ::core::result::Result<(), impl ::core::fmt::Debug> {{"
),
);
// For tests that get generated with `Result`, like above, `rustdoc` generates an `unwrap()` on

16
scripts/rustdoc_test_gen.rs
View file

@ -167,12 +167,14 @@ fn main() {
rust_tests,
r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
#[no_mangle]
pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
pub extern "C" fn {kunit_name}(__kunit_test: *mut ::kernel::bindings::kunit) {{
/// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
#[allow(unused)]
macro_rules! assert {{
($cond:expr $(,)?) => {{{{
kernel::kunit_assert!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $cond);
::kernel::kunit_assert!(
"{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $cond
);
}}}}
}}
@ -180,13 +182,15 @@ pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
#[allow(unused)]
macro_rules! assert_eq {{
($left:expr, $right:expr $(,)?) => {{{{
kernel::kunit_assert_eq!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right);
::kernel::kunit_assert_eq!(
"{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right
);
}}}}
}}
// Many tests need the prelude, so provide it by default.
#[allow(unused)]
use kernel::prelude::*;
use ::kernel::prelude::*;
// Unconditionally print the location of the original doctest (i.e. rather than the location in
// the generated file) so that developers can easily map the test back to the source code.
@ -197,11 +201,11 @@ pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
// This follows the syntax for declaring test metadata in the proposed KTAP v2 spec, which may
// be used for the proposed KUnit test attributes API. Thus hopefully this will make migration
// easier later on.
kernel::kunit::info(format_args!(" # {kunit_name}.location: {real_path}:{line}\n"));
::kernel::kunit::info(format_args!(" # {kunit_name}.location: {real_path}:{line}\n"));
/// The anchor where the test code body starts.
#[allow(unused)]
static __DOCTEST_ANCHOR: i32 = core::line!() as i32 + {body_offset} + 1;
static __DOCTEST_ANCHOR: i32 = ::core::line!() as i32 + {body_offset} + 1;
{{
{body}
main();

3
tools/objtool/check.c
View file

@ -230,7 +230,8 @@ static bool is_rust_noreturn(const struct symbol *func)
str_ends_with(func->name, "_7___rustc17rust_begin_unwind") ||
strstr(func->name, "_4core9panicking13assert_failed") ||
strstr(func->name, "_4core9panicking11panic_const24panic_const_") ||
(strstr(func->name, "_4core5slice5index24slice_") &&
(strstr(func->name, "_4core5slice5index") &&
strstr(func->name, "slice_") &&
str_ends_with(func->name, "_fail"));
}