<feed xmlns='http://www.w3.org/2005/Atom'>
<title>user/sven/linux.git/rust/kernel/lib.rs, branch v6.7.9</title>
<subtitle>Linux Kernel
</subtitle>
<id>https://git.stealer.net/cgit.cgi/user/sven/linux.git/atom?h=v6.7.9</id>
<link rel='self' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/atom?h=v6.7.9'/>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/'/>
<updated>2023-09-25T19:46:42Z</updated>
<entry>
<title>rust: workqueue: add helper for defining work_struct fields</title>
<updated>2023-09-25T19:46:42Z</updated>
<author>
<name>Alice Ryhl</name>
<email>aliceryhl@google.com</email>
</author>
<published>2023-08-28T10:48:04Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=7324b88975c525a013ae0db747df97924ce80675'/>
<id>urn:sha1:7324b88975c525a013ae0db747df97924ce80675</id>
<content type='text'>
The main challenge with defining `work_struct` fields is making sure
that the function pointer stored in the `work_struct` is appropriate for
the work item type it is embedded in. It needs to know the offset of the
`work_struct` field being used (even if there are several!) so that it
can do a `container_of`, and it needs to know the type of the work item
so that it can call into the right user-provided code. All of this needs
to happen in a way that provides a safe API to the user, so that users
of the workqueue cannot mix up the function pointers.

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

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

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

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

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

```
struct MyWorkItem {
    work_field: Work&lt;MyWorkItem, 1&gt;,
}

impl_has_work! {
    impl HasWork&lt;MyWorkItem, 1&gt; for MyWorkItem { self.work_field }
}
```

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

Co-developed-by: Gary Guo &lt;gary@garyguo.net&gt;
Signed-off-by: Gary Guo &lt;gary@garyguo.net&gt;
Signed-off-by: Alice Ryhl &lt;aliceryhl@google.com&gt;
Reviewed-by: Benno Lossin &lt;benno.lossin@proton.me&gt;
Reviewed-by: Martin Rodriguez Reboredo &lt;yakoyoku@gmail.com&gt;
Reviewed-by: Andreas Hindborg &lt;a.hindborg@samsung.com&gt;
Reviewed-by: Boqun Feng &lt;boqun.feng@gmail.com&gt;
Signed-off-by: Tejun Heo &lt;tj@kernel.org&gt;
</content>
</entry>
<entry>
<title>rust: workqueue: add low-level workqueue bindings</title>
<updated>2023-09-25T19:46:42Z</updated>
<author>
<name>Alice Ryhl</name>
<email>aliceryhl@google.com</email>
</author>
<published>2023-08-28T10:48:02Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=d4d791d4aac041fde6eeba0a8f9201d728b52373'/>
<id>urn:sha1:d4d791d4aac041fde6eeba0a8f9201d728b52373</id>
<content type='text'>
Define basic low-level bindings to a kernel workqueue. The API defined
here can only be used unsafely. Later commits will provide safe
wrappers.

Co-developed-by: Gary Guo &lt;gary@garyguo.net&gt;
Signed-off-by: Gary Guo &lt;gary@garyguo.net&gt;
Signed-off-by: Alice Ryhl &lt;aliceryhl@google.com&gt;
Reviewed-by: Martin Rodriguez Reboredo &lt;yakoyoku@gmail.com&gt;
Reviewed-by: "Andreas Hindborg (Samsung)" &lt;nmi@metaspace.dk&gt;
Reviewed-by: Benno Lossin &lt;benno.lossin@proton.me&gt;
Reviewed-by: Boqun Feng &lt;boqun.feng@gmail.com&gt;
Signed-off-by: Tejun Heo &lt;tj@kernel.org&gt;
</content>
</entry>
<entry>
<title>rust: sync: add `Arc::{from_raw, into_raw}`</title>
<updated>2023-09-25T19:46:41Z</updated>
<author>
<name>Wedson Almeida Filho</name>
<email>walmeida@microsoft.com</email>
</author>
<published>2023-08-28T10:48:01Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=a8321776ca0b13ec4d4fc817144fe1b3f6ba4625'/>
<id>urn:sha1:a8321776ca0b13ec4d4fc817144fe1b3f6ba4625</id>
<content type='text'>
These methods can be used to turn an `Arc` into a raw pointer and back,
in a way that preserves the metadata for fat pointers.

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

Link: https://github.com/rust-lang/rust/issues/81513 [1]
Link: https://github.com/rust-lang/rust/issues/96283 [2]
Signed-off-by: Wedson Almeida Filho &lt;walmeida@microsoft.com&gt;
Co-developed-by: Alice Ryhl &lt;aliceryhl@google.com&gt;
Signed-off-by: Alice Ryhl &lt;aliceryhl@google.com&gt;
Reviewed-by: Gary Guo &lt;gary@garyguo.net&gt;
Reviewed-by: Martin Rodriguez Reboredo &lt;yakoyoku@gmail.com&gt;
Reviewed-by: Benno Lossin &lt;benno.lossin@proton.me&gt;
Reviewed-by: Andreas Hindborg &lt;a.hindborg@samsung.com&gt;
Reviewed-by: Boqun Feng &lt;boqun.feng@gmail.com&gt;
Signed-off-by: Tejun Heo &lt;tj@kernel.org&gt;
</content>
</entry>
<entry>
<title>Merge tag 'rust-6.6' of https://github.com/Rust-for-Linux/linux</title>
<updated>2023-08-29T15:19:46Z</updated>
<author>
<name>Linus Torvalds</name>
<email>torvalds@linux-foundation.org</email>
</author>
<published>2023-08-29T15:19:46Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=a031fe8d1d32898582e36ccbffa9847d16f67aa2'/>
<id>urn:sha1:a031fe8d1d32898582e36ccbffa9847d16f67aa2</id>
<content type='text'>
Pull rust updates from Miguel Ojeda:
 "In terms of lines, most changes this time are on the pinned-init API
  and infrastructure. While we have a Rust version upgrade, and thus a
  bunch of changes from the vendored 'alloc' crate as usual, this time
  those do not account for many lines.

  Toolchain and infrastructure:

   - Upgrade to Rust 1.71.1. This is the second such upgrade, which is a
     smaller jump compared to the last time.

     This version allows us to remove the '__rust_*' allocator functions
     -- the compiler now generates them as expected, thus now our
     'KernelAllocator' is used.

     It also introduces the 'offset_of!' macro in the standard library
     (as an unstable feature) which we will need soon. So far, we were
     using a declarative macro as a prerequisite in some not-yet-landed
     patch series, which did not support sub-fields (i.e. nested
     structs):

         #[repr(C)]
         struct S {
             a: u16,
             b: (u8, u8),
         }

         assert_eq!(offset_of!(S, b.1), 3);

   - Upgrade to bindgen 0.65.1. This is the first time we upgrade its
     version.

     Given it is a fairly big jump, it comes with a fair number of
     improvements/changes that affect us, such as a fix needed to
     support LLVM 16 as well as proper support for '__noreturn' C
     functions, which are now mapped to return the '!' type in Rust:

         void __noreturn f(void); // C
         pub fn f() -&gt; !;         // Rust

   - 'scripts/rust_is_available.sh' improvements and fixes.

     This series takes care of all the issues known so far and adds a
     few new checks to cover for even more cases, plus adds some more
     help texts. All this together will hopefully make problematic
     setups easier to identify and to be solved by users building the
     kernel.

     In addition, it adds a test suite which covers all branches of the
     shell script, as well as tests for the issues found so far.

   - Support rust-analyzer for out-of-tree modules too.

   - Give 'cfg's to rust-analyzer for the 'core' and 'alloc' crates.

   - Drop 'scripts/is_rust_module.sh' since it is not needed anymore.

  Macros crate:

   - New 'paste!' proc macro.

     This macro is a more flexible version of 'concat_idents!': it
     allows the resulting identifier to be used to declare new items and
     it allows to transform the identifiers before concatenating them,
     e.g.

         let x_1 = 42;
         paste!(let [&lt;x _2&gt;] = [&lt;x _1&gt;];);
         assert!(x_1 == x_2);

     The macro is then used for several of the pinned-init API changes
     in this pull.

  Pinned-init API:

   - Make '#[pin_data]' compatible with conditional compilation of
     fields, allowing to write code like:

         #[pin_data]
         pub struct Foo {
             #[cfg(CONFIG_BAR)]
             a: Bar,
             #[cfg(not(CONFIG_BAR))]
             a: Baz,
         }

   - New '#[derive(Zeroable)]' proc macro for the 'Zeroable' trait,
     which allows 'unsafe' implementations for structs where every field
     implements the 'Zeroable' trait, e.g.:

         #[derive(Zeroable)]
         pub struct DriverData {
             id: i64,
             buf_ptr: *mut u8,
             len: usize,
         }

   - Add '..Zeroable::zeroed()' syntax to the 'pin_init!' macro for
     zeroing all other fields, e.g.:

         pin_init!(Buf {
             buf: [1; 64],
             ..Zeroable::zeroed()
         });

   - New '{,pin_}init_array_from_fn()' functions to create array
     initializers given a generator function, e.g.:

         let b: Box&lt;[usize; 1_000]&gt; = Box::init::&lt;Error&gt;(
             init_array_from_fn(|i| i)
         ).unwrap();

         assert_eq!(b.len(), 1_000);
         assert_eq!(b[123], 123);

   - New '{,pin_}chain' methods for '{,Pin}Init&lt;T, E&gt;' that allow to
     execute a closure on the value directly after initialization, e.g.:

         let foo = init!(Foo {
             buf &lt;- init::zeroed()
         }).chain(|foo| {
             foo.setup();
             Ok(())
         });

   - Support arbitrary paths in init macros, instead of just identifiers
     and generic types.

   - Implement the 'Zeroable' trait for the 'UnsafeCell&lt;T&gt;' and
     'Opaque&lt;T&gt;' types.

   - Make initializer values inaccessible after initialization.

   - Make guards in the init macros hygienic.

  'allocator' module:

   - Use 'krealloc_aligned()' in 'KernelAllocator::alloc' preventing
     misaligned allocations when the Rust 1.71.1 upgrade is applied
     later in this pull.

     The equivalent fix for the previous compiler version (where
     'KernelAllocator' is not yet used) was merged into 6.5 already,
     which added the 'krealloc_aligned()' function used here.

   - Implement 'KernelAllocator::{realloc, alloc_zeroed}' for
     performance, using 'krealloc_aligned()' too, which forwards the
     call to the C API.

  'types' module:

   - Make 'Opaque' be '!Unpin', removing the need to add a
     'PhantomPinned' field to Rust structs that contain C structs which
     must not be moved.

   - Make 'Opaque' use 'UnsafeCell' as the outer type, rather than
     inner.

  Documentation:

   - Suggest obtaining the source code of the Rust's 'core' library
     using the tarball instead of the repository.

  MAINTAINERS:

   - Andreas and Alice, from Samsung and Google respectively, are
     joining as reviewers of the "RUST" entry.

  As well as a few other minor changes and cleanups"

* tag 'rust-6.6' of https://github.com/Rust-for-Linux/linux: (42 commits)
  rust: init: update expanded macro explanation
  rust: init: add `{pin_}chain` functions to `{Pin}Init&lt;T, E&gt;`
  rust: init: make `PinInit&lt;T, E&gt;` a supertrait of `Init&lt;T, E&gt;`
  rust: init: implement `Zeroable` for `UnsafeCell&lt;T&gt;` and `Opaque&lt;T&gt;`
  rust: init: add support for arbitrary paths in init macros
  rust: init: add functions to create array initializers
  rust: init: add `..Zeroable::zeroed()` syntax for zeroing all missing fields
  rust: init: make initializer values inaccessible after initializing
  rust: init: wrap type checking struct initializers in a closure
  rust: init: make guards in the init macros hygienic
  rust: add derive macro for `Zeroable`
  rust: init: make `#[pin_data]` compatible with conditional compilation of fields
  rust: init: consolidate init macros
  docs: rust: clarify what 'rustup override' does
  docs: rust: update instructions for obtaining 'core' source
  docs: rust: add command line to rust-analyzer section
  scripts: generate_rust_analyzer: provide `cfg`s for `core` and `alloc`
  rust: bindgen: upgrade to 0.65.1
  rust: enable `no_mangle_with_rust_abi` Clippy lint
  rust: upgrade to Rust 1.71.1
  ...
</content>
</entry>
<entry>
<title>rust: bindgen: upgrade to 0.65.1</title>
<updated>2023-08-14T22:37:22Z</updated>
<author>
<name>Aakash Sen Sharma</name>
<email>aakashsensharma@gmail.com</email>
</author>
<published>2023-06-12T19:43:11Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=08ab786556ff177086ce93b26daf2a58edd10968'/>
<id>urn:sha1:08ab786556ff177086ce93b26daf2a58edd10968</id>
<content type='text'>
In LLVM 16, anonymous items may return names like `(unnamed union at ..)`
rather than empty names [1], which breaks Rust-enabled builds because
bindgen assumed an empty name instead of detecting them via
`clang_Cursor_isAnonymous` [2]:

    $ make rustdoc LLVM=1 CLIPPY=1 -j$(nproc)
      RUSTC L rust/core.o
      BINDGEN rust/bindings/bindings_generated.rs
      BINDGEN rust/bindings/bindings_helpers_generated.rs
      BINDGEN rust/uapi/uapi_generated.rs
    thread 'main' panicked at '"ftrace_branch_data_union_(anonymous_at__/_/include/linux/compiler_types_h_146_2)" is not a valid Ident', .../proc-macro2-1.0.24/src/fallback.rs:693:9
    ...
    thread 'main' panicked at '"ftrace_branch_data_union_(anonymous_at__/_/include/linux/compiler_types_h_146_2)" is not a valid Ident', .../proc-macro2-1.0.24/src/fallback.rs:693:9
    ...

This was fixed in bindgen 0.62.0. Therefore, upgrade bindgen to
a more recent version, 0.65.1, to support LLVM 16.

Since bindgen 0.58.0 changed the `--{white,black}list-*` flags to
`--{allow,block}list-*` [3], update them on our side too.

In addition, bindgen 0.61.0 moved its CLI utility into a binary crate
called `bindgen-cli` [4]. Thus update the installation command in the
Quick Start guide.

Moreover, bindgen 0.61.0 changed the default functionality to bind
`size_t` to `usize` [5] and added the `--no-size_t-is-usize` flag
to not bind `size_t` as `usize`. Then bindgen 0.65.0 removed
the `--size_t-is-usize` flag [6]. Thus stop passing the flag to bindgen.

Finally, bindgen 0.61.0 added support for the `noreturn` attribute (in
its different forms) [7]. Thus remove the infinite loop in our Rust
panic handler after calling `BUG()`, since bindgen now correctly
generates a `BUG()` binding that returns `!` instead of `()`.

Link: https://github.com/llvm/llvm-project/commit/19e984ef8f49bc3ccced15621989fa9703b2cd5b [1]
Link: https://github.com/rust-lang/rust-bindgen/pull/2319 [2]
Link: https://github.com/rust-lang/rust-bindgen/pull/1990 [3]
Link: https://github.com/rust-lang/rust-bindgen/pull/2284 [4]
Link: https://github.com/rust-lang/rust-bindgen/commit/cc78b6fdb6e829e5fb8fa1639f2182cb49333569 [5]
Link: https://github.com/rust-lang/rust-bindgen/pull/2408 [6]
Link: https://github.com/rust-lang/rust-bindgen/issues/2094 [7]
Signed-off-by: Aakash Sen Sharma &lt;aakashsensharma@gmail.com&gt;
Closes: https://github.com/Rust-for-Linux/linux/issues/1013
Tested-by: Ariel Miculas &lt;amiculas@cisco.com&gt;
Reviewed-by: Gary Guo &lt;gary@garyguo.net&gt;
Link: https://lore.kernel.org/r/20230612194311.24826-1-aakashsensharma@gmail.com
[ Reworded commit message. Mentioned the `bindgen-cli` binary crate
  change, linked to it and updated the Quick Start guide. Re-added a
  deleted "as" word in a code comment and reflowed comment to respect
  the maximum length. ]
Signed-off-by: Miguel Ojeda &lt;ojeda@kernel.org&gt;
</content>
</entry>
<entry>
<title>rust: support running Rust documentation tests as KUnit ones</title>
<updated>2023-07-19T15:32:53Z</updated>
<author>
<name>Miguel Ojeda</name>
<email>ojeda@kernel.org</email>
</author>
<published>2023-07-18T05:27:51Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=a66d733da8010c732979041cd602cfceab7f587b'/>
<id>urn:sha1:a66d733da8010c732979041cd602cfceab7f587b</id>
<content type='text'>
Rust has documentation tests: these are typically examples of
usage of any item (e.g. function, struct, module...).

They are very convenient because they are just written
alongside the documentation. For instance:

    /// Sums two numbers.
    ///
    /// ```
    /// assert_eq!(mymod::f(10, 20), 30);
    /// ```
    pub fn f(a: i32, b: i32) -&gt; i32 {
        a + b
    }

In userspace, the tests are collected and run via `rustdoc`.
Using the tool as-is would be useful already, since it allows
to compile-test most tests (thus enforcing they are kept
in sync with the code they document) and run those that do not
depend on in-kernel APIs.

However, by transforming the tests into a KUnit test suite,
they can also be run inside the kernel. Moreover, the tests
get to be compiled as other Rust kernel objects instead of
targeting userspace.

On top of that, the integration with KUnit means the Rust
support gets to reuse the existing testing facilities. For
instance, the kernel log would look like:

    KTAP version 1
    1..1
        KTAP version 1
        # Subtest: rust_doctests_kernel
        1..59
        # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
        ok 1 rust_doctest_kernel_build_assert_rs_0
        # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
        ok 2 rust_doctest_kernel_build_assert_rs_1
        # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
        ok 3 rust_doctest_kernel_init_rs_0
        ...
        # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
        ok 59 rust_doctest_kernel_types_rs_2
    # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59
    # Totals: pass:59 fail:0 skip:0 total:59
    ok 1 rust_doctests_kernel

Therefore, add support for running Rust documentation tests
in KUnit. Some other notes about the current implementation
and support follow.

The transformation is performed by a couple scripts written
as Rust hostprogs.

Tests using the `?` operator are also supported as usual, e.g.:

    /// ```
    /// # use kernel::{spawn_work_item, workqueue};
    /// spawn_work_item!(workqueue::system(), || pr_info!("x"))?;
    /// # Ok::&lt;(), Error&gt;(())
    /// ```

The tests are also compiled with Clippy under `CLIPPY=1`, just
like normal code, thus also benefitting from extra linting.

The names of the tests are currently automatically generated.
This allows to reduce the burden for documentation writers,
while keeping them fairly stable for bisection. This is an
improvement over the `rustdoc`-generated names, which include
the line number; but ideally we would like to get `rustdoc` to
provide the Rust item path and a number (for multiple examples
in a single documented Rust item).

In order for developers to easily see from which original line
a failed doctests came from, a KTAP diagnostic line is printed
to the log, containing the location (file and line) of the
original test (i.e. instead of the location in the generated
Rust file):

    # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150

This line follows the syntax for declaring test metadata in the
proposed KTAP v2 spec [1], which may be used for the proposed
KUnit test attributes API [2]. Thus hopefully this will make
migration easier later on (suggested by David [3]).

The original line in that test attribute is figured out by
providing an anchor (suggested by Boqun [4]). The original file
is found by walking the filesystem, checking directory prefixes
to reduce the amount of combinations to check, and it is only
done once per file. Ambiguities are detected and reported.

A notable difference from KUnit C tests is that the Rust tests
appear to assert using the usual `assert!` and `assert_eq!`
macros from the Rust standard library (`core`). We provide
a custom version that forwards the call to KUnit instead.
Importantly, these macros do not require passing context,
unlike the KUnit C ones (i.e. `struct kunit *`). This makes
them easier to use, and readers of the documentation do not need
to care about which testing framework is used. In addition, it
may allow us to test third-party code more easily in the future.

However, a current limitation is that KUnit does not support
assertions in other tasks. Thus we presently simply print an
error to the kernel log if an assertion actually failed. This
should be revisited to properly fail the test, perhaps saving
the context somewhere else, or letting KUnit handle it.

Link: https://lore.kernel.org/lkml/20230420205734.1288498-1-rmoar@google.com/ [1]
Link: https://lore.kernel.org/linux-kselftest/20230707210947.1208717-1-rmoar@google.com/ [2]
Link: https://lore.kernel.org/rust-for-linux/CABVgOSkOLO-8v6kdAGpmYnZUb+LKOX0CtYCo-Bge7r_2YTuXDQ@mail.gmail.com/ [3]
Link: https://lore.kernel.org/rust-for-linux/ZIps86MbJF%2FiGIzd@boqun-archlinux/ [4]
Signed-off-by: Miguel Ojeda &lt;ojeda@kernel.org&gt;
Reviewed-by: David Gow &lt;davidgow@google.com&gt;
Signed-off-by: Shuah Khan &lt;skhan@linuxfoundation.org&gt;
</content>
</entry>
<entry>
<title>rust: upgrade to Rust 1.68.2</title>
<updated>2023-05-31T15:35:03Z</updated>
<author>
<name>Miguel Ojeda</name>
<email>ojeda@kernel.org</email>
</author>
<published>2023-04-18T21:43:47Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=3ed03f4da06ede71ac53cf25b9441a372e9f2487'/>
<id>urn:sha1:3ed03f4da06ede71ac53cf25b9441a372e9f2487</id>
<content type='text'>
This is the first upgrade to the Rust toolchain since the initial Rust
merge, from 1.62.0 to 1.68.2 (i.e. the latest).

# Context

The kernel currently supports only a single Rust version [1] (rather
than a minimum) given our usage of some "unstable" Rust features [2]
which do not promise backwards compatibility.

The goal is to reach a point where we can declare a minimum version for
the toolchain. For instance, by waiting for some of the features to be
stabilized. Therefore, the first minimum Rust version that the kernel
will support is "in the future".

# Upgrade policy

Given we will eventually need to reach that minimum version, it would be
ideal to upgrade the compiler from time to time to be as close as
possible to that goal and find any issues sooner. In the extreme, we
could upgrade as soon as a new Rust release is out. Of course, upgrading
so often is in stark contrast to what one normally would need for GCC
and LLVM, especially given the release schedule: 6 weeks for Rust vs.
half a year for LLVM and a year for GCC.

Having said that, there is no particular advantage to updating slowly
either: kernel developers in "stable" distributions are unlikely to be
able to use their distribution-provided Rust toolchain for the kernel
anyway [3]. Instead, by routinely upgrading to the latest instead,
kernel developers using Linux distributions that track the latest Rust
release may be able to use those rather than Rust-provided ones,
especially if their package manager allows to pin / hold back /
downgrade the version for some days during windows where the version may
not match. For instance, Arch, Fedora, Gentoo and openSUSE all provide
and track the latest version of Rust as they get released every 6 weeks.

Then, when the minimum version is reached, we will stop upgrading and
decide how wide the window of support will be. For instance, a year of
Rust versions. We will probably want to start small, and then widen it
over time, just like the kernel did originally for LLVM, see commit
3519c4d6e08e ("Documentation: add minimum clang/llvm version").

# Unstable features stabilized

This upgrade allows us to remove the following unstable features since
they were stabilized:

  - `feature(explicit_generic_args_with_impl_trait)` (1.63).
  - `feature(core_ffi_c)` (1.64).
  - `feature(generic_associated_types)` (1.65).
  - `feature(const_ptr_offset_from)` (1.65, *).
  - `feature(bench_black_box)` (1.66, *).
  - `feature(pin_macro)` (1.68).

The ones marked with `*` apply only to our old `rust` branch, not
mainline yet, i.e. only for code that we may potentially upstream.

With this patch applied, the only unstable feature allowed to be used
outside the `kernel` crate is `new_uninit`, though other code to be
upstreamed may increase the list.

Please see [2] for details.

# Other required changes

Since 1.63, `rustdoc` triggers the `broken_intra_doc_links` lint for
links pointing to exported (`#[macro_export]`) `macro_rules`. An issue
was opened upstream [4], but it turns out it is intended behavior. For
the moment, just add an explicit reference for each link. Later we can
revisit this if `rustdoc` removes the compatibility measure.

Nevertheless, this was helpful to discover a link that was pointing to
the wrong place unintentionally. Since that one was actually wrong, it
is fixed in a previous commit independently.

Another change was the addition of `cfg(no_rc)` and `cfg(no_sync)` in
upstream [5], thus remove our original changes for that.

Similarly, upstream now tests that it compiles successfully with
`#[cfg(not(no_global_oom_handling))]` [6], which allow us to get rid
of some changes, such as an `#[allow(dead_code)]`.

In addition, remove another `#[allow(dead_code)]` due to new uses
within the standard library.

Finally, add `try_extend_trusted` and move the code in `spec_extend.rs`
since upstream moved it for the infallible version.

# `alloc` upgrade and reviewing

There are a large amount of changes, but the vast majority of them are
due to our `alloc` fork being upgraded at once.

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

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

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

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

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

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

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

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

Link: https://rust-for-linux.com/rust-version-policy [1]
Link: https://github.com/Rust-for-Linux/linux/issues/2 [2]
Link: https://lore.kernel.org/rust-for-linux/CANiq72mT3bVDKdHgaea-6WiZazd8Mvurqmqegbe5JZxVyLR8Yg@mail.gmail.com/ [3]
Link: https://github.com/rust-lang/rust/issues/106142 [4]
Link: https://github.com/rust-lang/rust/pull/89891 [5]
Link: https://github.com/rust-lang/rust/pull/98652 [6]
Reviewed-by: Björn Roy Baron &lt;bjorn3_gh@protonmail.com&gt;
Reviewed-by: Gary Guo &lt;gary@garyguo.net&gt;
Reviewed-By: Martin Rodriguez Reboredo &lt;yakoyoku@gmail.com&gt;
Tested-by: Ariel Miculas &lt;amiculas@cisco.com&gt;
Tested-by: David Gow &lt;davidgow@google.com&gt;
Tested-by: Boqun Feng &lt;boqun.feng@gmail.com&gt;
Link: https://lore.kernel.org/r/20230418214347.324156-4-ojeda@kernel.org
[ Removed `feature(core_ffi_c)` from `uapi` ]
Signed-off-by: Miguel Ojeda &lt;ojeda@kernel.org&gt;
</content>
</entry>
<entry>
<title>rust: ioctl: Add ioctl number manipulation functions</title>
<updated>2023-04-21T23:46:45Z</updated>
<author>
<name>Asahi Lina</name>
<email>lina@asahilina.net</email>
</author>
<published>2023-04-03T09:33:53Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=ea76e08f4d901a450619831a255e9e0a4c0ed162'/>
<id>urn:sha1:ea76e08f4d901a450619831a255e9e0a4c0ed162</id>
<content type='text'>
Add simple 1:1 wrappers of the C ioctl number manipulation functions.
Since these are macros we cannot bindgen them directly, and since they
should be usable in const context we cannot use helper wrappers, so
we'll have to reimplement them in Rust. Thankfully, the C headers do
declare defines for the relevant bitfield positions, so we don't need
to duplicate that.

Signed-off-by: Asahi Lina &lt;lina@asahilina.net&gt;
Link: https://lore.kernel.org/r/20230329-rust-uapi-v2-2-bca5fb4d4a12@asahilina.net
[ Moved the `#![allow(non_snake_case)]` to the usual place. ]
Signed-off-by: Miguel Ojeda &lt;ojeda@kernel.org&gt;
</content>
</entry>
<entry>
<title>rust: uapi: Add UAPI crate</title>
<updated>2023-04-21T23:46:45Z</updated>
<author>
<name>Asahi Lina</name>
<email>lina@asahilina.net</email>
</author>
<published>2023-04-03T09:33:52Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=4e1746656839ab1e88d76eec4d2fa0b41d585604'/>
<id>urn:sha1:4e1746656839ab1e88d76eec4d2fa0b41d585604</id>
<content type='text'>
This crate mirrors the `bindings` crate, but will contain only UAPI
bindings. Unlike the bindings crate, drivers may directly use this crate
if they have to interface with userspace.

Initially, just bind the generic ioctl stuff.

In the future, we would also like to add additional checks to ensure
that all types exposed by this crate satisfy UAPI-safety guarantees
(that is, they are safely castable to/from a "bag of bits").

[ Miguel: added support for the `rustdoc` and `rusttest` targets,
  since otherwise they fail, and we want to keep them working. ]

Reviewed-by: Martin Rodriguez Reboredo &lt;yakoyoku@gmail.com&gt;
Signed-off-by: Asahi Lina &lt;lina@asahilina.net&gt;
Link: https://lore.kernel.org/r/20230329-rust-uapi-v2-1-bca5fb4d4a12@asahilina.net
Signed-off-by: Miguel Ojeda &lt;ojeda@kernel.org&gt;
</content>
</entry>
<entry>
<title>rust: add basic `Task`</title>
<updated>2023-04-21T22:20:00Z</updated>
<author>
<name>Wedson Almeida Filho</name>
<email>walmeida@microsoft.com</email>
</author>
<published>2023-04-11T05:45:39Z</published>
<link rel='alternate' type='text/html' href='https://git.stealer.net/cgit.cgi/user/sven/linux.git/commit/?id=313c4281bc9dfa98d76a71b16a684af1c52e7751'/>
<id>urn:sha1:313c4281bc9dfa98d76a71b16a684af1c52e7751</id>
<content type='text'>
It is an abstraction for C's `struct task_struct`. It implements
`AlwaysRefCounted`, so the refcount of the wrapped object is managed
safely on the Rust side.

Cc: Ingo Molnar &lt;mingo@redhat.com&gt;
Cc: Peter Zijlstra &lt;peterz@infradead.org&gt;
Reviewed-by: Martin Rodriguez Reboredo &lt;yakoyoku@gmail.com&gt;
Signed-off-by: Wedson Almeida Filho &lt;walmeida@microsoft.com&gt;
Link: https://lore.kernel.org/r/20230411054543.21278-9-wedsonaf@gmail.com
Signed-off-by: Miguel Ojeda &lt;ojeda@kernel.org&gt;
</content>
</entry>
</feed>
