summaryrefslogtreecommitdiffstats
path: root/rust
Commit message (Collapse)AuthorAgeFilesLines
* rust: error: `impl Debug` for `Error` with `errname()` integrationGary Guo2023-06-133-0/+47
| | | | | | | | | | | | | | | | | | | | | | Integrate the `Error` type with `errname()` by providing a new `name()` method. Then, implement `Debug` for the type using the new method. [ Miguel: under `CONFIG_SYMBOLIC_ERRNAME=n`, `errname()` is a `static inline`, so added a helper to support that case, like we had in the `rust` branch. Also moved `#include` up and reworded commit message for clarity. ] Co-developed-by: Wedson Almeida Filho <walmeida@microsoft.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Co-developed-by: Sven Van Asbroeck <thesven73@gmail.com> Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com> Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Link: https://lore.kernel.org/r/20230531174450.3733220-1-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: task: add `Send` marker to `Task`Alice Ryhl2023-05-311-2/+8
| | | | | | | | | | | | | | When a type also implements `Sync`, the meaning of `Send` is just "this type may be accessed mutably from threads other than the one it is created on". That's ok for this type. Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Link: https://lore.kernel.org/r/20230531145939.3714886-5-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: specify when `ARef` is thread safeAlice Ryhl2023-05-311-0/+13
| | | | | | | | | | | | | | | | An `ARef` behaves just like the `Arc` when it comes to thread safety, so we can reuse the thread safety comments from `Arc` here. This is necessary because without this change, the Rust compiler will assume that things are not thread safe even though they are. Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Boqun Feng <boqun.feng@gmail.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Link: https://lore.kernel.org/r/20230531145939.3714886-4-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: sync: reword the `Arc` safety comment for `Sync`Alice Ryhl2023-05-311-3/+5
| | | | | | | | | | | | | | | The safety comment on `impl Sync for Arc` references the Send safety comment. This commit avoids that in case the two comments drift apart in the future. Suggested-by: Andreas Hindborg <a.hindborg@samsung.com> Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Boqun Feng <boqun.feng@gmail.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Link: https://lore.kernel.org/r/20230531145939.3714886-3-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: sync: reword the `Arc` safety comment for `Send`Alice Ryhl2023-05-311-2/+2
| | | | | | | | | | | | | | | | The safety comment on `impl Send for Arc` talks about "directly" accessing the value, when it really means "accessing the value with a mutable reference". This commit clarifies that. Suggested-by: Boqun Feng <boqun.feng@gmail.com> Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Boqun Feng <boqun.feng@gmail.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Link: https://lore.kernel.org/r/20230531145939.3714886-2-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: sync: implement `AsRef<T>` for `Arc<T>`Alice Ryhl2023-05-311-0/+6
| | | | | | | | | | | | | | | | | | This trait lets you use `Arc<T>` in code that is generic over smart pointer types. The `AsRef` trait should be implemented on all smart pointers. The standard library also implements it on the ordinary `Arc`. Co-developed-by: Wedson Almeida Filho <walmeida@microsoft.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230517200814.3157916-2-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: sync: add `Arc::ptr_eq`Alice Ryhl2023-05-311-0/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | Add a method for comparing whether two `Arc` pointers reference the same underlying object. This comparison can already be done by getting a reference to the inner values and comparing whether the references have the same address. However, writing `Arc::ptr_eq(a, b)` is generally less error-prone than doing the same check on the references, since you might otherwise accidentally compare the two `&Arc<T>` references instead, which wont work because those are pointers to pointers to the inner value, when you just want to compare the pointers to the inner value. Also, this method might optimize better because getting a reference to the inner value involves offsetting the pointer, which this method does not need to do. Co-developed-by: Wedson Almeida Filho <walmeida@microsoft.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230517200814.3157916-1-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: error: add missing error codesAlice Ryhl2023-05-311-0/+20
| | | | | | | | | | | | | | | | | | This adds the error codes from `include/linux/errno.h` to the list of Rust error constants. These errors were not included originally, because they are not supposed to be visible from userspace. However, they are still a perfectly valid error to use when writing a kernel driver. For example, you might want to return ERESTARTSYS if you receive a signal during a call to `schedule`. This patch inserts an annotation to skip rustfmt on the list of error codes. Without it, three of the error codes are split over several lines, which looks terribly inconsistent. Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Link: https://lore.kernel.org/r/20230504064854.774820-1-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: str: add conversion from `CStr` to `CString`Alice Ryhl2023-05-311-0/+22
| | | | | | | | | | | | | | | | | These methods can be used to copy the data in a temporary c string into a separate allocation, so that it can be accessed later even if the original is deallocated. The API in this change mirrors the standard library API for the `&str` and `String` types. The `ToOwned` trait is not implemented because it assumes that allocations are infallible. Reviewed-by: Benno Lossin <benno.lossin@proton.me> Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230503141016.683634-1-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: error: allow specifying error type on `Result`Alice Ryhl2023-05-311-1/+1
| | | | | | | | | | | | | | | | | | | | Currently, if the `kernel::error::Result` type is in scope (which is often is, since it's in the kernel's prelude), you cannot write `Result<T, SomeOtherErrorType>` when you want to use a different error type than `kernel::error::Error`. To solve this we change the error type from being hard-coded to just being a default generic parameter. This still lets you write `Result<T>` when you just want to use the `Error` error type, but also lets you write `Result<T, SomeOtherErrorType>` when necessary. Signed-off-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Asahi Lina <lina@asahilina.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Gary Guo <gary@garyguo.net> Link: https://lore.kernel.org/r/20230502124015.356001-1-aliceryhl@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: init: update macro expansion example in docsBenno Lossin2023-05-311-37/+48
| | | | | | | | | | | Also improve the explaining comments. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Link: https://lore.kernel.org/r/20230424081112.99890-4-benno.lossin@proton.me Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: macros: replace Self with the concrete type in #[pin_data]Benno Lossin2023-05-311-4/+104
| | | | | | | | | | | | | | | | | | | | | | | | | When using `#[pin_data]` on a struct that used `Self` in the field types, a type error would be emitted when trying to use `pin_init!`. Since an internal type would be referenced by `Self` instead of the defined struct. This patch fixes this issue by replacing all occurrences of `Self` in the `#[pin_data]` macro with the concrete type circumventing the issue. Since rust allows type definitions inside of blocks, which are expressions, the macro also checks for these and emits a compile error when it finds `trait`, `enum`, `union`, `struct` or `impl`. These keywords allow creating new `Self` contexts, which conflicts with the current implementation of replacing every `Self` ident. If these were allowed, some `Self` idents would be replaced incorrectly. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reported-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Gary Guo <gary@garyguo.net> Link: https://lore.kernel.org/r/20230424081112.99890-3-benno.lossin@proton.me [ Added newline in commit message ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: macros: refactor generics parsing of `#[pin_data]` into its own functionBenno Lossin2023-05-312-62/+94
| | | | | | | | | | | | | | Other macros might also want to parse generics. Additionally this makes the code easier to read, as the next commit will introduce more code in `#[pin_data]`. Also add more comments to explain how parsing generics work. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Link: https://lore.kernel.org/r/20230424081112.99890-2-benno.lossin@proton.me Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: macros: fix usage of `#[allow]` in `quote!`Benno Lossin2023-05-311-6/+8
| | | | | | | | | | | | | | When using `quote!` as part of an expression that was not the last one in a function, the `#[allow(clippy::vec_init_then_push)]` attribute would be present on an expression, which is not allowed. This patch refactors that part of the macro to use a statement instead. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Gary Guo <gary@garyguo.net> Link: https://lore.kernel.org/r/20230424081112.99890-1-benno.lossin@proton.me Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: upgrade to Rust 1.68.2Miguel Ojeda2023-05-3119-677/+1270
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 > old.patch git -C linux restore rust/alloc # Apply this patch. git -C linux am rust-upgrade.patch # Get the difference with respect to the new version. git -C rust checkout $(linux/scripts/min-tool-version.sh rustc) git -C linux ls-tree -r --name-only HEAD -- rust/alloc | cut -d/ -f3- | grep -Fv README.md | xargs -IPATH cp rust/library/alloc/src/PATH linux/rust/alloc/PATH git -C linux diff --patch-with-stat --summary -R > new.patch git -C linux restore rust/alloc Now one may check the `new.patch` to take a look at the additions (first approach) or at the difference between those two patches (second approach). For the latter, a side-by-side tool is recommended. Link: https://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 <bjorn3_gh@protonmail.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-By: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Tested-by: Ariel Miculas <amiculas@cisco.com> Tested-by: David Gow <davidgow@google.com> Tested-by: Boqun Feng <boqun.feng@gmail.com> Link: https://lore.kernel.org/r/20230418214347.324156-4-ojeda@kernel.org [ Removed `feature(core_ffi_c)` from `uapi` ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: arc: fix intra-doc link in `Arc<T>::init`Miguel Ojeda2023-05-311-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | `Arc<T>::init` refers to `Arc<T>::pin_init` via an intra-doc link using the text `pin_init`, rather than more explicitly, which makes `rustdoc` point it to the `pin_init!` macro instead. This is required for the compiler upgrade since the newer `rustdoc` would trigger the `broken_intra_doc_links` lint [1], but in this case the macro was not the intended target to begin with, and so the actual fix is to make it point to the right place, regardless of the upgrade. Thus make it more explicit. Fixes: 92c4a1e7e81c ("rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers") Link: https://github.com/rust-lang/rust/issues/106142 [1] Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Björn Roy Baron <bjorn3_gh@protonmail.com> Tested-by: Ariel Miculas <amiculas@cisco.com> Tested-by: David Gow <davidgow@google.com> Tested-by: Boqun Feng <boqun.feng@gmail.com> Link: https://lore.kernel.org/r/20230418214347.324156-3-ojeda@kernel.org Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* rust: alloc: clarify what is the upstream versionMiguel Ojeda2023-05-311-0/+3
| | | | | | | | | | | | | | | | | | It may be unclear for readers which upstream Rust version these files are based on. They may be unaware that they are intended to match the minimum (and only, so far) supported version of Rust in the kernel. Thus clarify it. Reviewed-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Björn Roy Baron <bjorn3_gh@protonmail.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Tested-by: Ariel Miculas <amiculas@cisco.com> Tested-by: David Gow <davidgow@google.com> Tested-by: Boqun Feng <boqun.feng@gmail.com> Link: https://lore.kernel.org/r/20230418214347.324156-2-ojeda@kernel.org Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
* Merge tag 'rust-6.4' of https://github.com/Rust-for-Linux/linuxLinus Torvalds2023-04-3032-23/+4952
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Pull rust updates from Miguel Ojeda "More additions to the Rust core. Importantly, this adds the pin-init API, which will be used by other abstractions, such as the synchronization ones added here too: - pin-init API: a solution for the safe pinned initialization problem. This allows to reduce the need for 'unsafe' code in the kernel when dealing with data structures that require a stable address. Commit 90e53c5e70a6 ("rust: add pin-init API core") contains a nice introduction -- here is an example of how it looks like: #[pin_data] struct Example { #[pin] value: Mutex<u32>, #[pin] value_changed: CondVar, } impl Example { fn new() -> impl PinInit<Self> { pin_init!(Self { value <- new_mutex!(0), value_changed <- new_condvar!(), }) } } // In a `Box`. let b = Box::pin_init(Example::new())?; // In the stack. stack_pin_init!(let s = Example::new()); - 'sync' module: New types 'LockClassKey' ('struct lock_class_key'), 'Lock', 'Guard', 'Mutex' ('struct mutex'), 'SpinLock' ('spinlock_t'), 'LockedBy' and 'CondVar' (uses 'wait_queue_head_t'), plus macros such as 'static_lock_class!' and 'new_spinlock!'. In particular, 'Lock' and 'Guard' are generic implementations that contain code that is common to all locks. Then, different backends (the new 'Backend' trait) are implemented and used to define types like 'Mutex': type Mutex<T> = Lock<T, MutexBackend>; In addition, new methods 'assume_init()', 'init_with()' and 'pin_init_with()' for 'UniqueArc<MaybeUninit<T>>' and 'downcast()' for 'Arc<dyn Any + Send + Sync>'; as well as 'Debug' and 'Display' implementations for 'Arc' and 'UniqueArc'. Reduced stack usage of 'UniqueArc::try_new_uninit()', too. - 'types' module: New trait 'AlwaysRefCounted' and new type 'ARef' (an owned reference to an always-reference-counted object, meant to be used in wrappers for C types that have their own ref counting functions). Moreover, new associated functions 'raw_get()' and 'ffi_init()' for 'Opaque'. - New 'task' module with a new type 'Task' ('struct task_struct'), and a new macro 'current!' to safely get a reference to the current one. - New 'ioctl' module with new '_IOC*' const functions (equivalent to the C macros). - New 'uapi' crate, intended to be accessible by drivers directly. - 'macros' crate: new 'quote!' macro (similar to the one provided in userspace by the 'quote' crate); and the 'module!' macro now allows specifying multiple module aliases. - 'error' module: New associated functions for the 'Error' type, such as 'from_errno()' and new functions such as 'to_result()'. - 'alloc' crate: More fallible 'Vec' methods: 'try_resize` and 'try_extend_from_slice' and the infrastructure (imported from the Rust standard library) they need" * tag 'rust-6.4' of https://github.com/Rust-for-Linux/linux: (44 commits) rust: ioctl: Add ioctl number manipulation functions rust: uapi: Add UAPI crate rust: sync: introduce `CondVar` rust: lock: add `Guard::do_unlocked` rust: sync: introduce `LockedBy` rust: introduce `current` rust: add basic `Task` rust: introduce `ARef` rust: lock: introduce `SpinLock` rust: lock: introduce `Mutex` rust: sync: introduce `Lock` and `Guard` rust: sync: introduce `LockClassKey` MAINTAINERS: add Benno Lossin as Rust reviewer rust: init: broaden the blanket impl of `Init` rust: sync: add functions for initializing `UniqueArc<MaybeUninit<T>>` rust: sync: reduce stack usage of `UniqueArc::try_new_uninit` rust: types: add `Opaque::ffi_init` rust: prelude: add `pin-init` API items to prelude rust: init: add `Zeroable` trait and `init::zeroed` function rust: init: add `stack_pin_init!` macro ...
| * rust: ioctl: Add ioctl number manipulation functionsAsahi Lina2023-04-222-0/+73
| | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <lina@asahilina.net> 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 <ojeda@kernel.org>
| * rust: uapi: Add UAPI crateAsahi Lina2023-04-225-5/+61
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <yakoyoku@gmail.com> Signed-off-by: Asahi Lina <lina@asahilina.net> Link: https://lore.kernel.org/r/20230329-rust-uapi-v2-1-bca5fb4d4a12@asahilina.net Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: sync: introduce `CondVar`Wedson Almeida Filho2023-04-225-1/+184
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This is the traditional condition variable or monitor synchronisation primitive. It is implemented with C's `wait_queue_head_t`. It allows users to release a lock and go to sleep while guaranteeing that notifications won't be missed. This is achieved by enqueuing a wait entry before releasing the lock. Cc: Peter Zijlstra <peterz@infradead.org> Cc: Ingo Molnar <mingo@redhat.com> Cc: Will Deacon <will@kernel.org> Cc: Waiman Long <longman@redhat.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Link: https://lore.kernel.org/r/20230411054543.21278-12-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: lock: add `Guard::do_unlocked`Wedson Almeida Filho2023-04-222-2/+30
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | It releases the lock, executes some function provided by the caller, then reacquires the lock. This is preparation for the implementation of condvars, which will sleep after between unlocking and relocking. We need an explicit `relock` method for primitives like `SpinLock` that have an irqsave variant: we use the guard state to determine if the lock was originally acquired with the regular `lock` function or `lock_irqsave`. Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Link: https://lore.kernel.org/rust-for-linux/20230412121431.41627-1-wedsonaf@gmail.com/ [ Removed the irqsave bits as discussed. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: sync: introduce `LockedBy`Wedson Almeida Filho2023-04-223-1/+159
| | | | | | | | | | | | | | | | | | | | | | | | This allows us to have data protected by a lock despite not being wrapped by it. Access is granted by providing evidence that the lock is held by the caller. Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Link: https://lore.kernel.org/r/20230411054543.21278-13-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: introduce `current`Wedson Almeida Filho2023-04-223-1/+89
| | | | | | | | | | | | | | | | | | | | | | | | This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety. Cc: Ingo Molnar <mingo@redhat.com> Cc: Peter Zijlstra <peterz@infradead.org> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Link: https://lore.kernel.org/r/20230411054543.21278-10-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: add basic `Task`Wedson Almeida Filho2023-04-224-0/+96
| | | | | | | | | | | | | | | | | | | | | | | | | | 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 <mingo@redhat.com> Cc: Peter Zijlstra <peterz@infradead.org> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Link: https://lore.kernel.org/r/20230411054543.21278-9-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: introduce `ARef`Wedson Almeida Filho2023-04-221-0/+107
| | | | | | | | | | | | | | | | | | | | | | | | This is an owned reference to an object that is always ref-counted. This is meant to be used in wrappers for C types that have their own ref counting functions, for example, tasks, files, inodes, dentries, etc. Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Reviewed-by: Gary Guo <gary@garyguo.net> Link: https://lore.kernel.org/r/20230411054543.21278-8-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: lock: introduce `SpinLock`Wedson Almeida Filho2023-04-224-1/+142
| | | | | | | | | | | | | | | | | | | | | | | | | | | | This is the `spinlock_t` lock backend and allows Rust code to use the kernel spinlock idiomatically. Cc: Peter Zijlstra <peterz@infradead.org> Cc: Ingo Molnar <mingo@redhat.com> Cc: Will Deacon <will@kernel.org> Cc: Waiman Long <longman@redhat.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Link: https://lore.kernel.org/r/20230419174426.132207-1-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: lock: introduce `Mutex`Wedson Almeida Filho2023-04-224-0/+128
| | | | | | | | | | | | | | | | | | | | | | | | | | | | This is the `struct mutex` lock backend and allows Rust code to use the kernel mutex idiomatically. Cc: Peter Zijlstra <peterz@infradead.org> Cc: Ingo Molnar <mingo@redhat.com> Cc: Will Deacon <will@kernel.org> Cc: Waiman Long <longman@redhat.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Link: https://lore.kernel.org/r/20230411054543.21278-3-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: sync: introduce `Lock` and `Guard`Wedson Almeida Filho2023-04-222-1/+163
| | | | | | | | | | | | | | | | | | | | | | | | | | They are generic Rust implementations of a lock and a lock guard that contain code that is common to all locks. Different backends will be introduced in subsequent commits. Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Suggested-by: Gary Guo <gary@garyguo.net> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Link: https://lore.kernel.org/r/20230411054543.21278-2-wedsonaf@gmail.com [ Fixed typo. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: sync: introduce `LockClassKey`Wedson Almeida Filho2023-04-211-0/+45
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | It is a wrapper around C's `lock_class_key`, which is used by the synchronisation primitives that are checked with lockdep. This is in preparation for introducing Rust abstractions for these primitives. Cc: Peter Zijlstra <peterz@infradead.org> Cc: Ingo Molnar <mingo@redhat.com> Cc: Will Deacon <will@kernel.org> Cc: Waiman Long <longman@redhat.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Co-developed-by: Boqun Feng <boqun.feng@gmail.com> Signed-off-by: Boqun Feng <boqun.feng@gmail.com> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Benno Lossin <benno.lossin@proton.me> Link: https://lore.kernel.org/r/20230411054543.21278-1-wedsonaf@gmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: init: broaden the blanket impl of `Init`Benno Lossin2023-04-211-2/+2
| | | | | | | | | | | | | | | | | | | | | | This makes it possible to use `T` as a `impl Init<T, E>` for every error type `E` instead of just `Infallible`. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Link: https://lore.kernel.org/r/20230413100157.740697-1-benno.lossin@proton.me Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: sync: add functions for initializing `UniqueArc<MaybeUninit<T>>`Benno Lossin2023-04-121-0/+24
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add two functions `init_with` and `pin_init_with` to `UniqueArc<MaybeUninit<T>>` to initialize the memory of already allocated `UniqueArc`s. This is useful when you want to allocate memory check some condition inside of a context where allocation is forbidden and then conditionally initialize an object. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-16-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: sync: reduce stack usage of `UniqueArc::try_new_uninit`Benno Lossin2023-04-122-4/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | `UniqueArc::try_new_uninit` calls `Arc::try_new(MaybeUninit::uninit())`. This results in the uninitialized memory being placed on the stack, which may be arbitrarily large due to the generic `T` and thus could cause a stack overflow for large types. Change the implementation to use the pin-init API which enables in-place initialization. In particular it avoids having to first construct and then move the uninitialized memory from the stack into the final location. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-15-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: types: add `Opaque::ffi_init`Benno Lossin2023-04-122-0/+29
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This function allows to easily initialize `Opaque` with the pin-init API. `Opaque::ffi_init` takes a closure and returns a pin-initializer. This pin-initiailizer calls the given closure with a pointer to the inner `T`. Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Link: https://lore.kernel.org/r/20230408122429.1103522-14-y86-dev@protonmail.com [ Fixed typo. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: prelude: add `pin-init` API items to preludeBenno Lossin2023-04-121-1/+5
| | | | | | | | | | | | | | | | | | | | | | Add `pin-init` API macros and traits to the prelude. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-13-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: init: add `Zeroable` trait and `init::zeroed` functionBenno Lossin2023-04-121-2/+95
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Add the `Zeroable` trait which marks types that can be initialized by writing `0x00` to every byte of the type. Also add the `init::zeroed` function that creates an initializer for a `Zeroable` type that writes `0x00` to every byte. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-12-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: init: add `stack_pin_init!` macroBenno Lossin2023-04-122-6/+191
| | | | | | | | | | | | | | | | | | | | | | | | | | The `stack_pin_init!` macro allows pin-initializing a value on the stack. It accepts a `impl PinInit<T, E>` to initialize a `T`. It allows propagating any errors via `?` or handling it normally via `match`. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Gary Guo <gary@garyguo.net> Link: https://lore.kernel.org/r/20230408122429.1103522-11-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: init: add `PinnedDrop` trait and macrosBenno Lossin2023-04-125-0/+488
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The `PinnedDrop` trait that facilitates destruction of pinned types. It has to be implemented via the `#[pinned_drop]` macro, since the `drop` function should not be called by normal code, only by other destructors. It also only works on structs that are annotated with `#[pin_data(PinnedDrop)]`. Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-10-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointersBenno Lossin2023-04-122-13/+139
| | | | | | | | | | | | | | | | | | | | | | | | | | The `InPlaceInit` trait that provides two functions, for initializing using `PinInit<T, E>` and `Init<T>`. It is implemented by `Arc<T>`, `UniqueArc<T>` and `Box<T>`. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-9-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: init: add initialization macrosBenno Lossin2023-04-126-7/+1747
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add the following initializer macros: - `#[pin_data]` to annotate structurally pinned fields of structs, needed for `pin_init!` and `try_pin_init!` to select the correct initializer of fields. - `pin_init!` create a pin-initializer for a struct with the `Infallible` error type. - `try_pin_init!` create a pin-initializer for a struct with a custom error type (`kernel::error::Error` is the default). - `init!` create an in-place-initializer for a struct with the `Infallible` error type. - `try_init!` create an in-place-initializer for a struct with a custom error type (`kernel::error::Error` is the default). Also add their needed internal helper traits and structs. Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-8-y86-dev@protonmail.com [ Fixed three typos. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: add pin-init API coreBenno Lossin2023-04-123-0/+226
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This API is used to facilitate safe pinned initialization of structs. It replaces cumbersome `unsafe` manual initialization with elegant safe macro invocations. Due to the size of this change it has been split into six commits: 1. This commit introducing the basic public interface: traits and functions to represent and create initializers. 2. Adds the `#[pin_data]`, `pin_init!`, `try_pin_init!`, `init!` and `try_init!` macros along with their internal types. 3. Adds the `InPlaceInit` trait that allows using an initializer to create an object inside of a `Box<T>` and other smart pointers. 4. Adds the `PinnedDrop` trait and adds macro support for it in the `#[pin_data]` macro. 5. Adds the `stack_pin_init!` macro allowing to pin-initialize a struct on the stack. 6. Adds the `Zeroable` trait and `init::zeroed` function to initialize types that have `0x00` in all bytes as a valid bit pattern. -- In this section the problem that the new pin-init API solves is outlined. This message describes the entirety of the API, not just the parts introduced in this commit. For a more granular explanation and additional information on pinning and this issue, view [1]. Pinning is Rust's way of enforcing the address stability of a value. When a value gets pinned it will be impossible for safe code to move it to another location. This is done by wrapping pointers to said object with `Pin<P>`. This wrapper prevents safe code from creating mutable references to the object, preventing mutable access, which is needed to move the value. `Pin<P>` provides `unsafe` functions to circumvent this and allow modifications regardless. It is then the programmer's responsibility to uphold the pinning guarantee. Many kernel data structures require a stable address, because there are foreign pointers to them which would get invalidated by moving the structure. Since these data structures are usually embedded in structs to use them, this pinning property propagates to the container struct. Resulting in most structs in both Rust and C code needing to be pinned. So if we want to have a `mutex` field in a Rust struct, this struct also needs to be pinned, because a `mutex` contains a `list_head`. Additionally initializing a `list_head` requires already having the final memory location available, because it is initialized by pointing it to itself. But this presents another challenge in Rust: values have to be initialized at all times. There is the `MaybeUninit<T>` wrapper type, which allows handling uninitialized memory, but this requires using the `unsafe` raw pointers and a casting the type to the initialized variant. This problem gets exacerbated when considering encapsulation and the normal safety requirements of Rust code. The fields of the Rust `Mutex<T>` should not be accessible to normal driver code. After all if anyone can modify the fields, there is no way to ensure the invariants of the `Mutex<T>` are upheld. But if the fields are inaccessible, then initialization of a `Mutex<T>` needs to be somehow achieved via a function or a macro. Because the `Mutex<T>` must be pinned in memory, the function cannot return it by value. It also cannot allocate a `Box` to put the `Mutex<T>` into, because that is an unnecessary allocation and indirection which would hurt performance. The solution in the rust tree (e.g. this commit: [2]) that is replaced by this API is to split this function into two parts: 1. A `new` function that returns a partially initialized `Mutex<T>`, 2. An `init` function that requires the `Mutex<T>` to be pinned and that fully initializes the `Mutex<T>`. Both of these functions have to be marked `unsafe`, since a call to `new` needs to be accompanied with a call to `init`, otherwise using the `Mutex<T>` could result in UB. And because calling `init` twice also is not safe. While `Mutex<T>` initialization cannot fail, other structs might also have to allocate memory, which would result in conditional successful initialization requiring even more manual accommodation work. Combine this with the problem of pin-projections -- the way of accessing fields of a pinned struct -- which also have an `unsafe` API, pinned initialization is riddled with `unsafe` resulting in very poor ergonomics. Not only that, but also having to call two functions possibly multiple lines apart makes it very easy to forget it outright or during refactoring. Here is an example of the current way of initializing a struct with two synchronization primitives (see [3] for the full example): struct SharedState { state_changed: CondVar, inner: Mutex<SharedStateInner>, } impl SharedState { fn try_new() -> Result<Arc<Self>> { let mut state = Pin::from(UniqueArc::try_new(Self { // SAFETY: `condvar_init!` is called below. state_changed: unsafe { CondVar::new() }, // SAFETY: `mutex_init!` is called below. inner: unsafe { Mutex::new(SharedStateInner { token_count: 0 }) }, })?); // SAFETY: `state_changed` is pinned when `state` is. let pinned = unsafe { state.as_mut().map_unchecked_mut(|s| &mut s.state_changed) }; kernel::condvar_init!(pinned, "SharedState::state_changed"); // SAFETY: `inner` is pinned when `state` is. let pinned = unsafe { state.as_mut().map_unchecked_mut(|s| &mut s.inner) }; kernel::mutex_init!(pinned, "SharedState::inner"); Ok(state.into()) } } The pin-init API of this patch solves this issue by providing a comprehensive solution comprised of macros and traits. Here is the example from above using the pin-init API: #[pin_data] struct SharedState { #[pin] state_changed: CondVar, #[pin] inner: Mutex<SharedStateInner>, } impl SharedState { fn new() -> impl PinInit<Self> { pin_init!(Self { state_changed <- new_condvar!("SharedState::state_changed"), inner <- new_mutex!( SharedStateInner { token_count: 0 }, "SharedState::inner", ), }) } } Notably the way the macro is used here requires no `unsafe` and thus comes with the usual Rust promise of safe code not introducing any memory violations. Additionally it is now up to the caller of `new()` to decide the memory location of the `SharedState`. They can choose at the moment `Arc<T>`, `Box<T>` or the stack. -- The API has the following architecture: 1. Initializer traits `PinInit<T, E>` and `Init<T, E>` that act like closures. 2. Macros to create these initializer traits safely. 3. Functions to allow manually writing initializers. The initializers (an `impl PinInit<T, E>`) receive a raw pointer pointing to uninitialized memory and their job is to fully initialize a `T` at that location. If initialization fails, they return an error (`E`) by value. This way of initializing cannot be safely exposed to the user, since it relies upon these properties outside of the control of the trait: - the memory location (slot) needs to be valid memory, - if initialization fails, the slot should not be read from, - the value in the slot should be pinned, so it cannot move and the memory cannot be deallocated until the value is dropped. This is why using an initializer is facilitated by another trait that ensures these requirements. These initializers can be created manually by just supplying a closure that fulfills the same safety requirements as `PinInit<T, E>`. But this is an `unsafe` operation. To allow safe initializer creation, the `pin_init!` is provided along with three other variants: `try_pin_init!`, `try_init!` and `init!`. These take a modified struct initializer as a parameter and generate a closure that initializes the fields in sequence. The macros take great care in upholding the safety requirements: - A shadowed struct type is used as the return type of the closure instead of `()`. This is to prevent early returns, as these would prevent full initialization. - To ensure every field is only initialized once, a normal struct initializer is placed in unreachable code. The type checker will emit errors if a field is missing or specified multiple times. - When initializing a field fails, the whole initializer will fail and automatically drop fields that have been initialized earlier. - Only the correct initializer type is allowed for unpinned fields. You cannot use a `impl PinInit<T, E>` to initialize a structurally not pinned field. To ensure the last point, an additional macro `#[pin_data]` is needed. This macro annotates the struct itself and the user specifies structurally pinned and not pinned fields. Because dropping a pinned struct is also not allowed to break the pinning invariants, another macro attribute `#[pinned_drop]` is needed. This macro is introduced in a following commit. These two macros also have mechanisms to ensure the overall safety of the API. Additionally, they utilize a combined proc-macro, declarative macro design: first a proc-macro enables the outer attribute syntax `#[...]` and does some important pre-parsing. Notably this prepares the generics such that the declarative macro can handle them using token trees. Then the actual parsing of the structure and the emission of code is handled by a declarative macro. For pin-projections the crates `pin-project` [4] and `pin-project-lite` [5] had been considered, but were ultimately rejected: - `pin-project` depends on `syn` [6] which is a very big dependency, around 50k lines of code. - `pin-project-lite` is a more reasonable 5k lines of code, but contains a very complex declarative macro to parse generics. On top of that it would require modification that would need to be maintained independently. Link: https://rust-for-linux.com/the-safe-pinned-initialization-problem [1] Link: https://github.com/Rust-for-Linux/linux/tree/0a04dc4ddd671efb87eef54dde0fb38e9074f4be [2] Link: https://github.com/Rust-for-Linux/linux/blob/f509ede33fc10a07eba3da14aa00302bd4b5dddd/samples/rust/rust_miscdev.rs [3] Link: https://crates.io/crates/pin-project [4] Link: https://crates.io/crates/pin-project-lite [5] Link: https://crates.io/crates/syn [6] Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Wedson Almeida Filho <wedsonaf@gmail.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Link: https://lore.kernel.org/r/20230408122429.1103522-7-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: types: add `Opaque::raw_get`Benno Lossin2023-04-121-0/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | This function mirrors `UnsafeCell::raw_get`. It avoids creating a reference and allows solely using raw pointers. The `pin-init` API will be using this, since uninitialized memory requires raw pointers. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Link: https://lore.kernel.org/r/20230408122429.1103522-6-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: sync: change error type of constructor functionsBenno Lossin2023-04-121-4/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | Change the error type of the constructors of `Arc` and `UniqueArc` to be `AllocError` instead of `Error`. This makes the API more clear as to what can go wrong when calling `try_new` or its variants. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Gary Guo <gary@garyguo.net> Link: https://lore.kernel.org/r/20230408122429.1103522-4-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: macros: add `quote!` macroGary Guo2023-04-122-0/+147
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Add the `quote!` macro for creating `TokenStream`s directly via the given Rust tokens. It also supports repetitions using iterators. It will be used by the pin-init API proc-macros to generate code. Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Link: https://lore.kernel.org/r/20230408122429.1103522-3-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: enable the `pin_macro` featureBenno Lossin2023-04-121-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | This feature enables the use of the `pin!` macro for the `stack_pin_init!` macro. This feature is already stabilized in Rust version 1.68. Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Acked-by: Boqun Feng <boqun.feng@gmail.com> Link: https://lore.kernel.org/r/20230408122429.1103522-2-y86-dev@protonmail.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: error: Add from_result() helperWedson Almeida Filho2023-04-121-0/+39
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add a helper function to easily return C result codes from a Rust function that calls functions which return a Result<T>. Lina: Imported from rust-for-linux/rust, originally developed by Wedson as part of file_operations.rs. Added the allow() flags since there is no user in the kernel crate yet and fixed a typo in a comment. Replaced the macro with a function taking a closure, per discussion on the ML. Co-developed-by: Fox Chen <foxhlchen@gmail.com> Signed-off-by: Fox Chen <foxhlchen@gmail.com> Co-developed-by: Miguel Ojeda <ojeda@kernel.org> Signed-off-by: Miguel Ojeda <ojeda@kernel.org> Signed-off-by: Wedson Almeida Filho <wedsonaf@gmail.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Asahi Lina <lina@asahilina.net> Link: https://lore.kernel.org/r/20230224-rust-error-v3-6-03779bddc02b@asahilina.net Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: error: Add a helper to convert a C ERR_PTR to a `Result`Sven Van Asbroeck2023-04-122-1/+61
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Some kernel C API functions return a pointer which embeds an optional `errno`. Callers are supposed to check the returned pointer with `IS_ERR()` and if this returns `true`, retrieve the `errno` using `PTR_ERR()`. Create a Rust helper function to implement the Rust equivalent: transform a `*mut T` to `Result<*mut T>`. Lina: Imported from rust-for-linux/linux, with subsequent refactoring and contributions squashed in and attributed below. Renamed the function to from_err_ptr(). Co-developed-by: Boqun Feng <boqun.feng@gmail.com> Signed-off-by: Boqun Feng <boqun.feng@gmail.com> Co-developed-by: Miguel Ojeda <ojeda@kernel.org> Signed-off-by: Miguel Ojeda <ojeda@kernel.org> Co-developed-by: Fox Chen <foxhlchen@gmail.com> Signed-off-by: Fox Chen <foxhlchen@gmail.com> Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Asahi Lina <lina@asahilina.net> Link: https://lore.kernel.org/r/20230224-rust-error-v3-5-03779bddc02b@asahilina.net [ Add a removal of `#[allow(dead_code)]`. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: error: Add to_result() helperWedson Almeida Filho2023-04-121-1/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add a to_result() helper to convert kernel C return values to a Rust Result, mapping >=0 values to Ok(()) and negative values to Err(...), with Error::from_errno() ensuring that the errno is within range. Lina: Imported from rust-for-linux/rust, originally developed by Wedson as part of the AMBA device driver support. Signed-off-by: Wedson Almeida Filho <wedsonaf@gmail.com> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Asahi Lina <lina@asahilina.net> Link: https://lore.kernel.org/r/20230224-rust-error-v3-4-03779bddc02b@asahilina.net [ Add a removal of `#[allow(dead_code)]`. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: error: Add Error::from_errno{_unchecked}()Miguel Ojeda2023-04-121-0/+32
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add a function to create `Error` values out of a kernel error return, which safely upholds the invariant that the error code is well-formed (negative and greater than -MAX_ERRNO). If a malformed code is passed in, it will be converted to EINVAL. Lina: Imported from rust-for-linux/rust as authored by Miguel and Fox with refactoring from Wedson, renamed from_kernel_errno() to from_errno(). Co-developed-by: Fox Chen <foxhlchen@gmail.com> Signed-off-by: Fox Chen <foxhlchen@gmail.com> Co-developed-by: Wedson Almeida Filho <wedsonaf@gmail.com> Signed-off-by: Wedson Almeida Filho <wedsonaf@gmail.com> Signed-off-by: Miguel Ojeda <ojeda@kernel.org> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Asahi Lina <lina@asahilina.net> Link: https://lore.kernel.org/r/20230224-rust-error-v3-3-03779bddc02b@asahilina.net [ Mark the new associated functions as `#[allow(dead_code)]`. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
| * rust: error: Add Error::to_ptr()Asahi Lina2023-04-122-0/+14
| | | | | | | | | | | | | | | | | | | | | | | | This is the Rust equivalent to ERR_PTR(), for use in C callbacks. Marked as #[allow(dead_code)] for now, since it does not have any consumers yet. Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Signed-off-by: Asahi Lina <lina@asahilina.net> Reviewed-by: Gary Guo <gary@garyguo.net> Link: https://lore.kernel.org/r/20230224-rust-error-v3-2-03779bddc02b@asahilina.net Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-02 15:13:31 +0000