Rust pin-init API for pinned initialization of structs
Subsystems (4)
v3 cover Rust pin-init API for pinned initialization of structs
From: Benno Lossin <[email protected]>
This is the third version of the pin-init API. See [1] for v2. This version changes v2 a lot, see the changelog below.
The tree at [2] contains these patches applied on top of 6.3-rc1. The Rust-doc documentation of the pin-init API can be found at [3].
These patches are a long way coming, since I held a presentation on safe pinned initialization at Kangrejos [4]. And my discovery of this problem was almost a year ago [5].
- #1 adds a utility macro quote! for proc-macros. This macro converts the typed characters directly into Rust tokens that are the output of proc-macros. It is used by the pin-init API proc-macros.
- #2 adds the assume_init function to UniqueArc<MaybeUninit<T>> that unsafely assumes the pointee to be initialized and returns a UniqueArc<T>. UniqueArc::write is modified to use this new function. Later patches use it as well.
- #3 adds Opaque::raw_get to access the value inside of an Opaque from a raw pointer only.
- #4-9 introduce the pin-init API. The commit message of #4 details the problem it solves and lays out the overall architecture. The implementation details are fairly complex; however, this is required to provide a safe API for users -- reducing the amount of unsafe code is a key goal of the Rust support in the kernel. An example of the before/after difference from the point of view of users is provided in the commit message. It is a goal to at some point have pin-init as a language feature of Rust. A first step in this direction is the Field Projection RFC [6].
- #10 adds important traits and macros from pin-init to the prelude.
- #11 adds functions for easier initialization of Opaque<T> via FFI and raw pointer initializer functions. This is necessary when writing Rust wrappers and will be used by Wedson's sync module patches.
- #12 improves the UniqueArc::try_new_uninit function by using the pin-init API. The old version first allocated uninitialized memory on the stack and then moved it into the location in the heap. The new version directly allocates this on the heap.
- #13 adds functions for initializing already allocated UniqueArcs, this will be used by the Android Binder driver.
--
Changelog:
v2 -> v3:
- Split the big original commit into six smaller commits.
- Use PinnedDrop in the RawFoo code example.
- Move the init::common::ffi_init functions to Opaque::ffi_init.
- Move all #[doc(hidden)], internal types into the new __internal module.
- Specify safety guarantees and requirements of the initializer macros.
- Add a detailed example of what the expanded code of the various macros looks like.
- Require generics in the initializer macros to use turbofish syntax (::<>).
- Refactor the internals of the initializer macros, this way they have better type inference and generic arguments can be omitted more often.
- Replace init::from_value with a blanket impl of the initializer traits for ordinary objects.
- Add initializing functions for already allocated UniqueArcs.
- Add Opaque::manual_init functions akin to ffi_init, but they take an extern "Rust" fn instead.
- Documentation and inline comment improvements.
v1 -> v2:
- split the common module and UniqueArc::assume_init into their own commits
- change the generics syntax of pin_init! to reflect normal struct generic syntax
- replace PinnedDrop::__ensure_no_unsafe_op_in_drop with an only unsafely creatable token
- hide StackInit<T> in the docs, because it is internal API
- improve macro internals of pin_init! according to Gary's review
- add check for PhantomPinned fields without a #[pin] attribute in #[pin_data], as those fields will not have the intended effect
- add docs to quote.rs
[1] https://lore.kernel.org/rust-for-linux/[email protected]/T/#t
[2] https://github.com/y86-dev/linux.git patch/pinned-init-v3
[3] https://rust-for-linux.github.io/docs/pinned-init/kernel/init
[4] https://kangrejos.com
[5] https://github.com/Rust-for-Linux/linux/issues/772
[6] https://github.com/rust-lang/rfcs/pull/3318
Benno Lossin (12):
rust: sync: add assume_init to UniqueArc
rust: types: add Opaque::raw_get
rust: add pin-init API core
rust: init: add initialization macros
rust: init/sync: add InPlaceInit trait to pin-initialize smart
pointers
rust: init: add PinnedDrop trait and macros
rust: init: add stack_pin_init! macro
rust: init: add Zeroable trait and init::zeroed function
rust: prelude: add pin-init API items to prelude
rust: types: add common init-helper functions for Opaque
rust: sync: reduce stack usage of UniqueArc::try_new_uninit
rust: sync: add functions for initializing UniqueArc<MaybeUninit<T>>
Gary Guo (1):
rust: macros: add quote! macro
rust/kernel/init.rs | 1330 ++++++++++++++++++++++++++++++++ rust/kernel/init/__internal.rs | 195 +++++ rust/kernel/init/macros.rs | 970 +++++++++++++++++++++++ rust/kernel/lib.rs | 6 + rust/kernel/prelude.rs | 6 +- rust/kernel/sync/arc.rs | 74 +- rust/kernel/types.rs | 55 ++ rust/macros/lib.rs | 80 ++ rust/macros/pin_data.rs | 79 ++ rust/macros/pinned_drop.rs | 49 ++ rust/macros/quote.rs | 143 ++++ scripts/Makefile.build | 2 +- 12 files changed, 2984 insertions(+), 5 deletions(-) create mode 100644 rust/kernel/init.rs create mode 100644 rust/kernel/init/__internal.rs create mode 100644 rust/kernel/init/macros.rs create mode 100644 rust/macros/pin_data.rs create mode 100644 rust/macros/pinned_drop.rs create mode 100644 rust/macros/quote.rs
base-commit: fe15c26ee26efa11741a7b632e9f23b01aca4cc6 --
2.39.2
PATCH v3 1/13 rust: macros: add `quote!` macro
From: Gary Guo <[email protected]>
Add the quote! macro for creating TokenStreams 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.
--- rust/macros/lib.rs | 2 + rust/macros/quote.rs | 145 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 rust/macros/quote.rs
rust/macros/lib.rs +2 -0
@@ -2,6 +2,8 @@//! Crate for all kernel procedural macros. +#[macro_use] +mod quote;mod concat_idents;mod helpers;mod module;
rust/macros/quote.rs new file +145 -0
145 lines not on this page · raw message
--
2.39.2
Re: [PATCH v3 01/13] rust: macros: add `quote!` macro
Quoted 73 lines · [email protected] writes:
From: Gary Guo <[email protected]>
Add the
quote!macro for creatingTokenStreams 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 <[email protected]>Signed-off-by Benno Lossin <[email protected]>--- rust/macros/lib.rs | 2 + rust/macros/quote.rs | 145 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 rust/macros/quote.rsrust/macros/lib.rs +2
-0@@ -2,6 +2,8 @@//! Crate for all kernel procedural macros. +#[macro_use] +mod quote;mod concat_idents;mod helpers;mod module;rust/macros/quote.rs new file +39
-0@@ -0,0 +1,145 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{TokenStream ,TokenTree }; + +pub (crate )trait ToTokens { +fn to_tokens (&self, tokens: &mut TokenStream ); +} + +impl <T :ToTokens >ToTokens for Option <T > { +fn to_tokens (&self, tokens: &mut TokenStream ) { +if let Some (v) = self { + v.to_tokens (tokens); + } + } +} + +impl ToTokens for proc_macro::Group { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([TokenTree ::from (self.clone ())]); + } +} + +impl ToTokens for TokenTree { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([self.clone ()]); + } +} + +impl ToTokens for TokenStream { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend (self.clone ()); + } +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// the given span. +/// +/// This is a similar to the +/// [`quote_spanned!`](https://docs.rs/quote/latest/quote/macro.quote_spanned.html) macro from the
rust/macros/quote.rs line 49
Quoted 10 lines
rust/macros/quote.rs new file +10
-0+/// `quote` crate but provides only just enough functionality needed by the current `macros` crate. +#[allow(unused_macros)] +macro_rules! quote_spanned { + ($span:expr => $($tt:tt)*) => { +#[allow(clippy::vec_init_then_push)] + { +let mut tokens =Vec ::new (); +let span = $span; +quote_spanned! (@proc tokensspan $($tt)*); + proc_macro::TokenStream ::from_iter (tokens)
Should this be ::alloc::vec::Vec and::proc_macro::TokenStream::from_iter ?
Best regards,
Andreas
Quoted 96 lines
rust/macros/quote.rs new file +96
-0+ }}; + (@proc $v:ident $span:ident) => {}; + (@proc $v:ident $span:ident #$id:ident $($tt:tt)*) => { + let mut ts = proc_macro::TokenStream::new(); + crate::quote::ToTokens::to_tokens(&$id, &mut ts); + $v.extend(ts.into_iter()); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident #(#$id:ident)* $($tt:tt)*) => { + for token in $id { + let mut ts = proc_macro::TokenStream::new(); + crate::quote::ToTokens::to_tokens(&token, &mut ts); + $v.extend(ts.into_iter()); + } + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ( $($inner:tt)* ) $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Parenthesis, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident [ $($inner:tt)* ] $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Bracket, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident { $($inner:tt)* } $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Brace, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident :: $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Joint)) + ); + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident : $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident , $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(',', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident @ $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new('@', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ! $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new('!', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident $id:ident $($tt:tt)*) => { + $v.push(proc_macro::TokenTree::Ident(proc_macro::Ident::new(stringify!($id), $span))); + quote_spanned!(@proc $v $span $($tt)*); + }; +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// mixed site span ([`Span::mixed_site()`]). +/// +/// This is a similar to the [`quote!`](https://docs.rs/quote/latest/quote/macro.quote.html) macro +/// from the `quote` crate but provides only just enough functionality needed by the current +/// `macros` crate. +/// +/// [`Span::mixed_site()`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.mixed_site +#[allow(unused_macros)] +macro_rules! quote { + ($($tt:tt)*) => { + quote_spanned!(proc_macro::Span::mixed_site() => $($tt)*) + } +}
Re: [PATCH v3 01/13] rust: macros: add `quote!` macro
Quoted 89 lines · Andreas Hindborg
Quoted 73 lines · [email protected] writes:
From: Gary Guo <[email protected]>
Add the
quote!macro for creatingTokenStreams 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 <[email protected]>Signed-off-by Benno Lossin <[email protected]>--- rust/macros/lib.rs | 2 + rust/macros/quote.rs | 145 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 rust/macros/quote.rsrust/macros/lib.rs +2
-0@@ -2,6 +2,8 @@//! Crate for all kernel procedural macros. +#[macro_use] +mod quote;mod concat_idents;mod helpers;mod module;rust/macros/quote.rs new file +39
-0@@ -0,0 +1,145 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{TokenStream ,TokenTree }; + +pub (crate )trait ToTokens { +fn to_tokens (&self, tokens: &mut TokenStream ); +} + +impl <T :ToTokens >ToTokens for Option <T > { +fn to_tokens (&self, tokens: &mut TokenStream ) { +if let Some (v) = self { + v.to_tokens (tokens); + } + } +} + +impl ToTokens for proc_macro::Group { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([TokenTree ::from (self.clone ())]); + } +} + +impl ToTokens for TokenTree { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([self.clone ()]); + } +} + +impl ToTokens for TokenStream { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend (self.clone ()); + } +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// the given span. +/// +/// This is a similar to the +/// [`quote_spanned!`](https://docs.rs/quote/latest/quote/macro.quote_spanned.html) macro from the rust/macros/quote.rs line 49
Quoted 10 lines
rust/macros/quote.rs new file +10
-0+/// `quote` crate but provides only just enough functionality needed by the current `macros` crate. +#[allow(unused_macros)] +macro_rules! quote_spanned { + ($span:expr => $($tt:tt)*) => { +#[allow(clippy::vec_init_then_push)] + { +let mut tokens =Vec ::new (); +let span = $span; +quote_spanned! (@proc tokensspan $($tt)*); + proc_macro::TokenStream ::from_iter (tokens)Should this be
::alloc::vec::Vecand::proc_macro::TokenStream::from_iter?
Quoted 16 lines
Best regards,
AndreasQuoted 13 lines
rust/macros/quote.rs new file +13
-0+ }}; + (@proc $v:ident $span:ident) => {}; + (@proc $v:ident $span:ident #$id:ident $($tt:tt)*) => { + let mut ts = proc_macro::TokenStream::new(); + crate::quote::ToTokens::to_tokens(&$id, &mut ts); + $v.extend(ts.into_iter()); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident #(#$id:ident)* $($tt:tt)*) => { + for token in $id { + let mut ts = proc_macro::TokenStream::new(); + crate::quote::ToTokens::to_tokens(&token, &mut ts); + $v.extend(ts.into_iter());
Also, could this be without into_iter(): $v.extend(ts)?
BR Andreas
Quoted 83 lines
Quoted 83 lines
rust/macros/quote.rs new file +83
-0+ } +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ( $($inner:tt)* ) $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Parenthesis, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident [ $($inner:tt)* ] $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Bracket, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident { $($inner:tt)* } $($tt:tt)*) => { + let mut tokens = Vec::new(); + quote_spanned!(@proc tokens $span $($inner)*); + $v.push(proc_macro::TokenTree::Group(proc_macro::Group::new( + proc_macro::Delimiter::Brace, + proc_macro::TokenStream::from_iter(tokens) + ))); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident :: $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Joint)) + ); + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident : $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(':', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident , $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new(',', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident @ $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new('@', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ! $($tt:tt)*) => { + $v.push( + proc_macro::TokenTree::Punct(proc_macro::Punct::new('!', proc_macro::Spacing::Alone)) + ); + quote_spanned!(@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident $id:ident $($tt:tt)*) => { + $v.push(proc_macro::TokenTree::Ident(proc_macro::Ident::new(stringify!($id), $span))); + quote_spanned!(@proc $v $span $($tt)*); + }; +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// mixed site span ([`Span::mixed_site()`]). +/// +/// This is a similar to the [`quote!`](https://docs.rs/quote/latest/quote/macro.quote.html) macro +/// from the `quote` crate but provides only just enough functionality needed by the current +/// `macros` crate. +/// +/// [`Span::mixed_site()`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.mixed_site +#[allow(unused_macros)] +macro_rules! quote { + ($($tt:tt)*) => { + quote_spanned!(proc_macro::Span::mixed_site() => $($tt)*) + } +}
Gary Guo
maintainerRe: [PATCH v3 01/13] rust: macros: add `quote!` macro
In reply to Andreas HindborgQuoted 89 lines · On Thu, 30 Mar 2023 13:42:29 +0200 Andreas Hindborg <[email protected]> wrote:
Quoted 73 lines · [email protected] writes:
From: Gary Guo <[email protected]>
Add the
quote!macro for creatingTokenStreams 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 <[email protected]>Signed-off-by Benno Lossin <[email protected]>--- rust/macros/lib.rs | 2 + rust/macros/quote.rs | 145 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 rust/macros/quote.rsrust/macros/lib.rs +2
-0@@ -2,6 +2,8 @@//! Crate for all kernel procedural macros. +#[macro_use] +mod quote;mod concat_idents;mod helpers;mod module;rust/macros/quote.rs new file +39
-0@@ -0,0 +1,145 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{TokenStream ,TokenTree }; + +pub (crate )trait ToTokens { +fn to_tokens (&self, tokens: &mut TokenStream ); +} + +impl <T :ToTokens >ToTokens for Option <T > { +fn to_tokens (&self, tokens: &mut TokenStream ) { +if let Some (v) = self { + v.to_tokens (tokens); + } + } +} + +impl ToTokens for proc_macro::Group { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([TokenTree ::from (self.clone ())]); + } +} + +impl ToTokens for TokenTree { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([self.clone ()]); + } +} + +impl ToTokens for TokenStream { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend (self.clone ()); + } +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// the given span. +/// +/// This is a similar to the +/// [`quote_spanned!`](https://docs.rs/quote/latest/quote/macro.quote_spanned.html) macro from the rust/macros/quote.rs line 49
Quoted 10 lines
rust/macros/quote.rs new file +10
-0+/// `quote` crate but provides only just enough functionality needed by the current `macros` crate. +#[allow(unused_macros)] +macro_rules! quote_spanned { + ($span:expr => $($tt:tt)*) => { +#[allow(clippy::vec_init_then_push)] + { +let mut tokens =Vec ::new (); +let span = $span; +quote_spanned! (@proc tokensspan $($tt)*); + proc_macro::TokenStream ::from_iter (tokens)Should this be
::alloc::vec::Vecand::proc_macro::TokenStream::from_iter?
Quoted 2 lines
Best regards,
Andreas
Hi Andres,
This macro is used only internally, so I didn't really bother to fully qualify all the names.
Best,
Gary
Re: [PATCH v3 01/13] rust: macros: add `quote!` macro
In reply to [email protected]Quoted 9 lines · On 3/30/23 00:32, [email protected] wrote:
From: Gary Guo <[email protected]>
Add the
quote!macro for creatingTokenStreams 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 <[email protected]>Signed-off-by Benno Lossin <[email protected]>
Re: [PATCH v3 01/13] rust: macros: add `quote!` macro
In reply to [email protected]Quoted 10 lines · [email protected] writes:
From: Gary Guo <[email protected]>
Add the
quote!macro for creatingTokenStreams 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 <[email protected]>Signed-off-by Benno Lossin <[email protected]>---
Quoted 169 lines
rust/macros/lib.rs | 2 + rust/macros/quote.rs | 145 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 rust/macros/quote.rsrust/macros/lib.rs +2
-0@@ -2,6 +2,8 @@//! Crate for all kernel procedural macros. +#[macro_use] +mod quote;mod concat_idents;mod helpers;mod module;rust/macros/quote.rs new file +145
-0@@ -0,0 +1,145 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{TokenStream ,TokenTree }; + +pub (crate )trait ToTokens { +fn to_tokens (&self, tokens: &mut TokenStream ); +} + +impl <T :ToTokens >ToTokens for Option <T > { +fn to_tokens (&self, tokens: &mut TokenStream ) { +if let Some (v) = self { + v.to_tokens (tokens); + } + } +} + +impl ToTokens for proc_macro::Group { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([TokenTree ::from (self.clone ())]); + } +} + +impl ToTokens for TokenTree { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend ([self.clone ()]); + } +} + +impl ToTokens for TokenStream { +fn to_tokens (&self, tokens: &mut TokenStream ) { + tokens.extend (self.clone ()); + } +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// the given span. +/// +/// This is a similar to the +/// [`quote_spanned!`](https://docs.rs/quote/latest/quote/macro.quote_spanned.html) macro from the +/// `quote` crate but provides only just enough functionality needed by the current `macros` crate. +#[allow(unused_macros)] +macro_rules! quote_spanned { + ($span:expr => $($tt:tt)*) => { +#[allow(clippy::vec_init_then_push)] + { +let mut tokens =Vec ::new (); +let span = $span; +quote_spanned! (@proc tokensspan $($tt)*); + proc_macro::TokenStream ::from_iter (tokens) + }}; + (@proc $v:ident $span:ident) => {}; + (@proc $v:ident $span:ident #$id:ident $($tt:tt)*) => { +let mut ts = proc_macro::TokenStream ::new (); +crate ::quote::ToTokens ::to_tokens (&$id, &mut ts); + $v.extend (ts.into_iter ()); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident #(#$id:ident)* $($tt:tt)*) => { +for tokenin $id { +let mut ts = proc_macro::TokenStream ::new (); +crate ::quote::ToTokens ::to_tokens (&token, &mut ts); + $v.extend (ts.into_iter ()); + } +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ( $($inner:tt)* ) $($tt:tt)*) => { +let mut tokens =Vec ::new (); +quote_spanned! (@proc tokens $span $($inner)*); + $v.push (proc_macro::TokenTree ::Group (proc_macro::Group ::new ( + proc_macro::Delimiter ::Parenthesis , + proc_macro::TokenStream ::from_iter (tokens) + ))); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident [ $($inner:tt)* ] $($tt:tt)*) => { +let mut tokens =Vec ::new (); +quote_spanned! (@proc tokens $span $($inner)*); + $v.push (proc_macro::TokenTree ::Group (proc_macro::Group ::new ( + proc_macro::Delimiter ::Bracket , + proc_macro::TokenStream ::from_iter (tokens) + ))); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident { $($inner:tt)* } $($tt:tt)*) => { +let mut tokens =Vec ::new (); +quote_spanned! (@proc tokens $span $($inner)*); + $v.push (proc_macro::TokenTree ::Group (proc_macro::Group ::new ( + proc_macro::Delimiter ::Brace , + proc_macro::TokenStream ::from_iter (tokens) + ))); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident :: $($tt:tt)*) => { + $v.push ( + proc_macro::TokenTree ::Punct (proc_macro::Punct ::new (':' , proc_macro::Spacing ::Joint )) + ); + $v.push ( + proc_macro::TokenTree ::Punct (proc_macro::Punct ::new (':' , proc_macro::Spacing ::Alone )) + ); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident : $($tt:tt)*) => { + $v.push ( + proc_macro::TokenTree ::Punct (proc_macro::Punct ::new (':' , proc_macro::Spacing ::Alone )) + ); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident , $($tt:tt)*) => { + $v.push ( + proc_macro::TokenTree ::Punct (proc_macro::Punct ::new (',' , proc_macro::Spacing ::Alone )) + ); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident @ $($tt:tt)*) => { + $v.push ( + proc_macro::TokenTree ::Punct (proc_macro::Punct ::new ('@' , proc_macro::Spacing ::Alone )) + ); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident ! $($tt:tt)*) => { + $v.push ( + proc_macro::TokenTree ::Punct (proc_macro::Punct ::new ('!' , proc_macro::Spacing ::Alone )) + ); +quote_spanned! (@proc $v $span $($tt)*); + }; + (@proc $v:ident $span:ident $id:ident $($tt:tt)*) => { + $v.push (proc_macro::TokenTree ::Ident (proc_macro::Ident ::new (stringify! ($id), $span))); +quote_spanned! (@proc $v $span $($tt)*); + }; +} + +/// Converts tokens into [`proc_macro::TokenStream`] and performs variable interpolations with +/// mixed site span ([`Span::mixed_site()`]). +/// +/// This is a similar to the [`quote!`](https://docs.rs/quote/latest/quote/macro.quote.html) macro +/// from the `quote` crate but provides only just enough functionality needed by the current +/// `macros` crate. +/// +/// [`Span::mixed_site()`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.mixed_site +#[allow(unused_macros)] +macro_rules! quote { + ($($tt:tt)*) => { +quote_spanned! (proc_macro::Span ::mixed_site () => $($tt)*) + } +}
PATCH v3 2/13 rust: sync: add `assume_init` to `UniqueArc`
In reply to [email protected]From: Benno Lossin <[email protected]>
Adds the assume_init function to UniqueArc<MaybeUninit<T>> that unsafely assumes the value to be initialized and yields a value of type UniqueArc<T>. This function is used when manually initializing the pointee of an UniqueArc.
--- rust/kernel/sync/arc.rs | 11 +++++++++++ 1 file changed, 11 insertions(+)
rust/kernel/sync/arc.rs +11 -0
@@ -489,6 +489,17 @@ impl<T> UniqueArc<MaybeUninit<T>> {/// Converts a `UniqueArc<MaybeUninit<T>>` into a `UniqueArc<T>` by writing a value into it. pub fn write (mut self, value:T ) ->UniqueArc <T > { self.deref_mut ().write (value); +// SAFETY: We just wrote the value to be initialized. +unsafe { self.assume_init () } + } + +/// Unsafely assume that `self` is initialized. +/// +/// # Safety +/// +/// The caller guarantees that the value behind this pointer has been initialized. It is +/// *immediate* UB to call this when the value is not initialized. +pub unsafe fn assume_init (self) ->UniqueArc <T > {let inner =ManuallyDrop ::new (self).inner.ptr;UniqueArc {// SAFETY: The new `Arc` is taking over `ptr` from `self.inner` (which won't be
--
2.39.2
Re: [PATCH v3 02/13] rust: sync: add `assume_init` to `UniqueArc`
Quoted 9 lines · On Wed, 29 Mar 2023 at 19:33, <[email protected]> wrote:
From: Benno Lossin <[email protected]>
Adds the
assume_initfunction toUniqueArc<MaybeUninit<T>>that unsafely assumes the value to be initialized and yields a value of typeUniqueArc<T>. This function is used when manually initializing the pointee of anUniqueArc.Signed-off-by Benno Lossin <[email protected]>
Re: [PATCH v3 02/13] rust: sync: add `assume_init` to `UniqueArc`
In reply to [email protected]Quoted 9 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
Adds the
assume_initfunction toUniqueArc<MaybeUninit<T>>that unsafely assumes the value to be initialized and yields a value of typeUniqueArc<T>. This function is used when manually initializing the pointee of anUniqueArc.Signed-off-by Benno Lossin <[email protected]>---
Re: [PATCH v3 02/13] rust: sync: add `assume_init` to `UniqueArc`
In reply to [email protected]Quoted 8 lines · On 3/30/23 00:32, [email protected] wrote:
From: Benno Lossin <[email protected]>
Adds the
assume_initfunction toUniqueArc<MaybeUninit<T>>that unsafely assumes the value to be initialized and yields a value of typeUniqueArc<T>. This function is used when manually initializing the pointee of anUniqueArc.Signed-off-by Benno Lossin <[email protected]>
PATCH v3 3/13 rust: types: add `Opaque::raw_get`
In reply to [email protected]From: Benno Lossin <[email protected]>
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.
--- rust/kernel/types.rs | 8 ++++++++ 1 file changed, 8 insertions(+)
rust/kernel/types.rs +8 -0
@@ -238,6 +238,14 @@ impl<T> Opaque<T> {pub fn get (&self) -> *mut T {UnsafeCell ::raw_get (self.0 .as_ptr ()) } + +/// Gets the value behind `this`. +/// +/// This function is useful to get access to the value without creating intermediate +/// references. +pub const fn raw_get (this: *const Self ) -> *mut T { +UnsafeCell ::raw_get (this.cast ::<UnsafeCell <T >>()) + } }/// A sum type that always holds either a value of type `L` or `R`.
--
2.39.2
Re: [PATCH v3 03/13] rust: types: add `Opaque::raw_get`
Quoted 8 lines · On Wed, 29 Mar 2023 22:33:03 +0000 [email protected] wrote:
From: Benno Lossin <[email protected]>
This function mirrors
UnsafeCell::raw_get. It avoids creating a reference and allows solely using raw pointers.
Thepin-initAPI will be using this, since uninitialized memory requires raw pointers.Signed-off-by Benno Lossin <[email protected]>
Quoted 27 lines
--- rust/kernel/types.rs | 8 ++++++++ 1 file changed, 8 insertions(+)rust/kernel/types.rs +8
-1@@ -238,6 +238,14 @@ impl<T> Opaque<T> {pub fn get (&self) -> *mut T {UnsafeCell ::raw_get (self.0 .as_ptr ()) } + +/// Gets the value behind `this`. +/// +/// This function is useful to get access to the value without creating intermediate +/// references. +pub const fn raw_get (this: *const Self ) -> *mut T { +UnsafeCell ::raw_get (this.cast ::<UnsafeCell <T >>()) + } }/// A sum type that always holds either a value of type `L` or `R`. --2.39.2
Re: [PATCH v3 03/13] rust: types: add `Opaque::raw_get`
In reply to [email protected]Quoted 9 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
This function mirrors
UnsafeCell::raw_get. It avoids creating a reference and allows solely using raw pointers.
Thepin-initAPI will be using this, since uninitialized memory requires raw pointers.Signed-off-by Benno Lossin <[email protected]>---
Quoted 22 lines
rust/kernel/types.rs | 8 ++++++++ 1 file changed, 8 insertions(+)rust/kernel/types.rs +8
-0@@ -238,6 +238,14 @@ impl<T> Opaque<T> {pub fn get (&self) -> *mut T {UnsafeCell ::raw_get (self.0 .as_ptr ()) } + +/// Gets the value behind `this`. +/// +/// This function is useful to get access to the value without creating intermediate +/// references. +pub const fn raw_get (this: *const Self ) -> *mut T { +UnsafeCell ::raw_get (this.cast ::<UnsafeCell <T >>()) + } }/// A sum type that always holds either a value of type `L` or `R`.
Re: [PATCH v3 03/13] rust: types: add `Opaque::raw_get`
In reply to [email protected]Quoted 8 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
This function mirrors
UnsafeCell::raw_get. It avoids creating a reference and allows solely using raw pointers.
Thepin-initAPI will be using this, since uninitialized memory requires raw pointers.Signed-off-by Benno Lossin <[email protected]>
PATCH v3 4/13 rust: add pin-init API core
In reply to [email protected]From: Benno Lossin <[email protected]>
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 current solution was 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 [2] 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 [3] and pin-project-lite [4] had been considered, but were ultimately rejected:
- pin-project depends on syn [5] 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.
--- rust/kernel/init.rs | 210 +++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 7 ++ scripts/Makefile.build | 2 +- 3 files changed, 218 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/init.rs
rust/kernel/init.rs new file +210 -0
@@ -0,0 +1,210 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +//! API to safely and fallibly initialize pinned `struct`s using in-place constructors. +//! +//! It also allows in-place initialization of big `struct`s that would otherwise produce a stack +//! overflow. +//! +//! Most `struct`s from the [`sync`] module need to be pinned, because they contain self-referential +//! `struct`s from C. [Pinning][pinning] is Rust's way of ensuring data does not move. +//! +//! # Overview +//! +//! To initialize a `struct` with an in-place constructor you will need two things: +//! - an in-place constructor, +//! - a memory location that can hold your `struct`. +//! +//! To get an in-place constructor there are generally two options: +//! - a custom function/macro returning an in-place constructor provided by someone else, +//! - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer. +//! +//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix. +//! +//! [`sync`]: kernel::sync +//! [pinning]: https://doc.rust-lang.org/std/pin/index.html +//! [structurally pinned fields]: +//! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +//! [`Arc<T>`]: crate::sync::Arc +//! [`impl PinInit<Foo>`]: PinInit +//! [`impl PinInit<T, E>`]: PinInit +//! [`impl Init<T, E>`]: Init +//! [`Opaque`]: kernel::types::Opaque +//! [`pin_data`]: ::macros::pin_data +//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +//! [`Box<T>`]: alloc::boxed::Box + +use core::{convert::Infallible , marker::PhantomData , mem::MaybeUninit }; + +/// A pinned initializer for `T`. +/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`pin_init_from_closure`] where possible. +/// +/// The [`PinInit::__pinned_init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// [`Arc<T>`]: crate::sync::Arc +/// [`Arc::pin_init`]: crate::sync::Arc::pin_init +/// [`UniqueArc<T>`]: kernel::sync::UniqueArc +/// [`Box<T>`]: alloc::boxed::Box +#[must_use = "An initializer must be used in order to create its value." ] +pub unsafe trait PinInit <T : ?Sized ,E =Infallible >:Sized { +/// Initializes `slot`. +/// +/// # Safety +/// +/// - `slot` is a valid pointer to uninitialized memory. +/// - the caller does not touch `slot` when `Err` is returned, they are only permitted to +/// deallocate. +/// - `slot` will not move until it is dropped, i.e. it will be pinned. +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),E >; +} + +/// An initializer for `T`. +/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Because [`PinInit<T, E>`] is a super trait, you can +/// use every function that takes it as well. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`init_from_closure`] where possible. +/// +/// The [`Init::__init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// The `__pinned_init` function from the supertrait [`PinInit`] needs to execute the exact same +/// code as `__init`. +/// +/// Contrary to its supertype [`PinInit<T, E>`] the caller is allowed to +/// move the pointee after initialization. +/// +/// [`Arc<T>`]: crate::sync::Arc +/// [`UniqueArc<T>`]: kernel::sync::UniqueArc +/// [`Box<T>`]: alloc::boxed::Box +#[must_use = "An initializer must be used in order to create its value." ] +pub unsafe trait Init <T : ?Sized ,E =Infallible >:PinInit <T ,E > { +/// Initializes `slot`. +/// +/// # Safety +/// +/// - `slot` is a valid pointer to uninitialized memory. +/// - the caller does not touch `slot` when `Err` is returned, they are only permitted to +/// deallocate. +unsafe fn __init (self, slot: *mut T ) ->Result <(),E >; +} + +type Invariant <T > =PhantomData <fn (*mut T ) -> *mut T >; +// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure <F ,T : ?Sized ,E >(F ,Invariant <(E ,T )>); + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__pinned_init` invariants. +unsafe impl <T : ?Sized ,F ,E >PinInit <T ,E >for InitClosure <F ,T ,E > +where +F :FnOnce (*mut T ) ->Result <(),E >, +{ +#[inline] +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),E > { + (self.0 )(slot) + } +} + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__init` invariants. +unsafe impl <T : ?Sized ,F ,E >Init <T ,E >for InitClosure <F ,T ,E > +where +F :FnOnce (*mut T ) ->Result <(),E >, +{ +#[inline] +unsafe fn __init (self, slot: *mut T ) ->Result <(),E > { + (self.0 )(slot) + } +} + +/// Creates a new [`PinInit<T, E>`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - may assume that the `slot` does not move if `T: !Unpin`, +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn pin_init_from_closure <T : ?Sized ,E >( + f:impl FnOnce (*mut T ) ->Result <(),E >, +) ->impl PinInit <T ,E > { +InitClosure (f,PhantomData ) +} + +/// Creates a new [`Init<T, E>`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - the `slot` may move after initialization. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn init_from_closure <T : ?Sized ,E >( + f:impl FnOnce (*mut T ) ->Result <(),E >, +) ->impl Init <T ,E > { +InitClosure (f,PhantomData ) +} + +/// An initializer that leaves the memory uninitialized. +/// +/// The initializer is a no-op. The `slot` memory is not changed. +#[inline] +pub fn uninit <T >() ->impl Init <MaybeUninit <T >> { +// SAFETY: The memory is allowed to be uninitialized. +unsafe {init_from_closure (|_|Ok (())) } +} + +// SAFETY: Every type can be initialized by-value. +unsafe impl <T >PinInit <T >for T { +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),Infallible > { +unsafe { slot.write (self) }; +Ok (()) + } +} + +// SAFETY: Every type can be initialized by-value. +unsafe impl <T >Init <T >for T { +unsafe fn __init (self, slot: *mut T ) ->Result <(),Infallible > { +unsafe { slot.write (self) }; +Ok (()) + } +}
rust/kernel/lib.rs +7 -0
@@ -16,7 +16,9 @@#![feature(coerce_unsized)] #![feature(core_ffi_c)] #![feature(dispatch_from_dyn)] +#![feature(explicit_generic_args_with_impl_trait)] #![feature(generic_associated_types)] +#![feature(new_uninit)] #![feature(receiver_trait)] #![feature(unsize)]
@@ -25,11 +27,16 @@#[cfg(not( CONFIG_RUST ))] compile_error! ("Missing kernel configuration for conditional compilation" ); +#[allow(unused_extern_crates)] +// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate). +extern crate selfas kernel; +#[cfg(not(test))] #[cfg(not(testlib))] mod allocator;mod build_assert;pub mod error; +pub mod init;pub mod prelude;pub mod print;mod static_assert;
scripts/Makefile.build +1 -1
@@ -277,7 +277,7 @@ $(obj)/%.lst: $(src)/%.c FORCE # Compile Rust sources (.rs) # --------------------------------------------------------------------------- -rust_allowed_features := core_ffi_c +rust_allowed_features := core_ffi_c,explicit_generic_args_with_impl_trait rust_common_cmd = \ RUST_MODFILE=$(modfile) $(RUSTC_OR_CLIPPY) $(rust_flags) \
--
2.39.2
Re: [PATCH v3 04/13] rust: add pin-init API core
Quoted 263 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
This API is used to facilitate safe pinned initialization of structs. It replaces cumbersome
unsafemanual 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!andtry_init!macros along with their internal types.
3. Adds theInPlaceInittrait that allows using an initializer to create an object inside of aBox<T>and other smart pointers.
4. Adds thePinnedDroptrait and adds macro support for it in the#[pin_data]macro.
5. Adds thestack_pin_init!macro allowing to pin-initialize a struct on the stack.
6. Adds theZeroabletrait andinit::zeroedfunction to initialize types that have0x00in 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>providesunsafefunctions 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
mutexfield in a Rust struct, this struct also needs to be pinned, because amutexcontains alist_head. Additionally initializing alist_headrequires 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 theMaybeUninit<T>wrapper type, which allows handling uninitialized memory, but this requires using theunsaferaw 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 theMutex<T>are upheld. But if the fields are inaccessible, then initialization of aMutex<T>needs to be somehow achieved via a function or a macro. Because theMutex<T>must be pinned in memory, the function cannot return it by value. It also cannot allocate aBoxto put theMutex<T>into, because that is an unnecessary allocation and indirection which would hurt performance.The current solution was to split this function into two parts:
1. A
newfunction that returns a partially initializedMutex<T>,
2. Aninitfunction that requires theMutex<T>to be pinned and that fully initializes theMutex<T>.Both of these functions have to be marked
unsafe, since a call tonewneeds to be accompanied with a call toinit, otherwise using theMutex<T>could result in UB. And because callinginittwice also is not safe. WhileMutex<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
unsafeAPI, pinned initialization is riddled withunsaferesulting 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 [2] 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
unsafeand thus comes with the usual Rust promise of safe code not introducing any memory violations. Additionally it is now up to the caller ofnew()to decide the memory location of theSharedState. They can choose at the momentArc<T>,Box<T>or the stack.--
The API has the following architecture:
1. Initializer traitsPinInit<T, E>andInit<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 aTat 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 anunsafeoperation. To allow safe initializer creation, thepin_init!is provided along with three other variants:try_pin_init!,try_init!andinit!. 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 aimpl 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[3] andpin-project-lite[4] had been considered, but were ultimately rejected:
-pin-projectdepends onsyn[5] which is a very big dependency, around 50k lines of code.
-pin-project-liteis 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://crates.io/crates/pin-project [3]Link https://crates.io/crates/syn [5]Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>--- rust/kernel/init.rs | 210 +++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 7 ++ scripts/Makefile.build | 2 +- 3 files changed, 218 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/init.rsrust/kernel/init.rs new file +30
-0@@ -0,0 +1,210 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +//! API to safely and fallibly initialize pinned `struct`s using in-place constructors. +//! +//! It also allows in-place initialization of big `struct`s that would otherwise produce a stack +//! overflow. +//! +//! Most `struct`s from the [`sync`] module need to be pinned, because they contain self-referential +//! `struct`s from C. [Pinning][pinning] is Rust's way of ensuring data does not move. +//! +//! # Overview +//! +//! To initialize a `struct` with an in-place constructor you will need two things: +//! - an in-place constructor, +//! - a memory location that can hold your `struct`. +//! +//! To get an in-place constructor there are generally two options: +//! - a custom function/macro returning an in-place constructor provided by someone else, +//! - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer. +//! +//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix. +//! +//! [`sync`]: kernel::sync +//! [pinning]: https://doc.rust-lang.org/std/pin/index.html +//! [structurally pinned fields]: +//! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +//! [`Arc<T>`]: crate::sync::Arc +//! [`impl PinInit<Foo>`]: PinInit
rust/kernel/init.rs line 40
Quoted 10 lines
rust/kernel/init.rs new file +10
-0+//! [`impl PinInit<T, E>`]: PinInit +//! [`impl Init<T, E>`]: Init +//! [`Opaque`]: kernel::types::Opaque +//! [`pin_data`]: ::macros::pin_data +//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +//! [`Box<T>`]: alloc::boxed::Box + +use core::{convert::Infallible , marker::PhantomData , mem::MaybeUninit }; + +/// A pinned initializer for `T`.
"An initializer for a pinned T" instead?
BR Andreas
Quoted 214 lines
rust/kernel/init.rs new file +170
-0+/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`pin_init_from_closure`] where possible. +/// +/// The [`PinInit::__pinned_init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// [`Arc<T>`]: crate::sync::Arc +/// [`Arc::pin_init`]: crate::sync::Arc::pin_init +/// [`UniqueArc<T>`]: kernel::sync::UniqueArc +/// [`Box<T>`]: alloc::boxed::Box +#[must_use = "An initializer must be used in order to create its value." ] +pub unsafe trait PinInit <T : ?Sized ,E =Infallible >:Sized { +/// Initializes `slot`. +/// +/// # Safety +/// +/// - `slot` is a valid pointer to uninitialized memory. +/// - the caller does not touch `slot` when `Err` is returned, they are only permitted to +/// deallocate. +/// - `slot` will not move until it is dropped, i.e. it will be pinned. +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),E >; +} + +/// An initializer for `T`. +/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Because [`PinInit<T, E>`] is a super trait, you can +/// use every function that takes it as well. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`init_from_closure`] where possible. +/// +/// The [`Init::__init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// The `__pinned_init` function from the supertrait [`PinInit`] needs to execute the exact same +/// code as `__init`. +/// +/// Contrary to its supertype [`PinInit<T, E>`] the caller is allowed to +/// move the pointee after initialization. +/// +/// [`Arc<T>`]: crate::sync::Arc +/// [`UniqueArc<T>`]: kernel::sync::UniqueArc +/// [`Box<T>`]: alloc::boxed::Box +#[must_use = "An initializer must be used in order to create its value." ] +pub unsafe trait Init <T : ?Sized ,E =Infallible >:PinInit <T ,E > { +/// Initializes `slot`. +/// +/// # Safety +/// +/// - `slot` is a valid pointer to uninitialized memory. +/// - the caller does not touch `slot` when `Err` is returned, they are only permitted to +/// deallocate. +unsafe fn __init (self, slot: *mut T ) ->Result <(),E >; +} + +type Invariant <T > =PhantomData <fn (*mut T ) -> *mut T >; +// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure <F ,T : ?Sized ,E >(F ,Invariant <(E ,T )>); + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__pinned_init` invariants. +unsafe impl <T : ?Sized ,F ,E >PinInit <T ,E >for InitClosure <F ,T ,E > +where +F :FnOnce (*mut T ) ->Result <(),E >, +{ +#[inline] +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),E > { + (self.0 )(slot) + } +} + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__init` invariants. +unsafe impl <T : ?Sized ,F ,E >Init <T ,E >for InitClosure <F ,T ,E > +where +F :FnOnce (*mut T ) ->Result <(),E >, +{ +#[inline] +unsafe fn __init (self, slot: *mut T ) ->Result <(),E > { + (self.0 )(slot) + } +} + +/// Creates a new [`PinInit<T, E>`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - may assume that the `slot` does not move if `T: !Unpin`, +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn pin_init_from_closure <T : ?Sized ,E >( + f:impl FnOnce (*mut T ) ->Result <(),E >, +) ->impl PinInit <T ,E > { +InitClosure (f,PhantomData ) +} + +/// Creates a new [`Init<T, E>`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - the `slot` may move after initialization. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn init_from_closure <T : ?Sized ,E >( + f:impl FnOnce (*mut T ) ->Result <(),E >, +) ->impl Init <T ,E > { +InitClosure (f,PhantomData ) +} + +/// An initializer that leaves the memory uninitialized. +/// +/// The initializer is a no-op. The `slot` memory is not changed. +#[inline] +pub fn uninit <T >() ->impl Init <MaybeUninit <T >> { +// SAFETY: The memory is allowed to be uninitialized. +unsafe {init_from_closure (|_|Ok (())) } +} + +// SAFETY: Every type can be initialized by-value. +unsafe impl <T >PinInit <T >for T { +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),Infallible > { +unsafe { slot.write (self) }; +Ok (()) + } +} + +// SAFETY: Every type can be initialized by-value. +unsafe impl <T >Init <T >for T { +unsafe fn __init (self, slot: *mut T ) ->Result <(),Infallible > { +unsafe { slot.write (self) }; +Ok (()) + } +}rust/kernel/lib.rs +7
-0@@ -16,7 +16,9 @@#![feature(coerce_unsized)] #![feature(core_ffi_c)] #![feature(dispatch_from_dyn)] +#![feature(explicit_generic_args_with_impl_trait)] #![feature(generic_associated_types)] +#![feature(new_uninit)] #![feature(receiver_trait)] #![feature(unsize)] @@ -25,11 +27,16 @@#[cfg(not( CONFIG_RUST ))] compile_error! ("Missing kernel configuration for conditional compilation" ); +#[allow(unused_extern_crates)] +// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate). +extern crate selfas kernel; +#[cfg(not(test))] #[cfg(not(testlib))] mod allocator;mod build_assert;pub mod error; +pub mod init;pub mod prelude;pub mod print;mod static_assert;scripts/Makefile.build +1
-1@@ -277,7 +277,7 @@ $(obj)/%.lst: $(src)/%.c FORCE # Compile Rust sources (.rs) # --------------------------------------------------------------------------- -rust_allowed_features := core_ffi_c +rust_allowed_features := core_ffi_c,explicit_generic_args_with_impl_trait rust_common_cmd = \ RUST_MODFILE=$(modfile) $(RUSTC_OR_CLIPPY) $(rust_flags) \
Re: [PATCH v3 04/13] rust: add pin-init API core
Quoted 6 lines · Andreas Hindborg
Quoted 6 lines
rust/kernel/init.rs new file +6
-0+//! [`Arc<T>`]: crate::sync::Arc +//! [`impl PinInit<Foo>`]: PinInit +//! [`impl PinInit<T, E>`]: PinInit +//! [`impl Init<T, E>`]: Init +//! [`Opaque`]: kernel::types::Opaque +//! [`pin_data`]: ::macros::pin_data
Quoted 8 lines
rust/kernel/init.rs line 40
Quoted 6 lines
rust/kernel/init.rs new file +6
-0+//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +//! [`Box<T>`]: alloc::boxed::Box + +use core::{convert::Infallible , marker::PhantomData , mem::MaybeUninit }; + +/// A pinned initializer for `T`. "An initializer for a pinned
T" instead?
To me this does not really make sense, since the type T cannot be pinned, only an instance can be. But maybe I should use the term pin-initializer instead.
--
Cheers,
Benno
Re: [PATCH v3 04/13] rust: add pin-init API core
Quoted 16 lines · Benno Lossin
Quoted 6 lines · Andreas Hindborg
Quoted 6 lines
rust/kernel/init.rs new file +6
-0+//! [`Arc<T>`]: crate::sync::Arc +//! [`impl PinInit<Foo>`]: PinInit +//! [`impl PinInit<T, E>`]: PinInit +//! [`impl Init<T, E>`]: Init +//! [`Opaque`]: kernel::types::Opaque +//! [`pin_data`]: ::macros::pin_data Quoted 8 lines
rust/kernel/init.rs line 40
Quoted 6 lines
rust/kernel/init.rs new file +6
-0+//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +//! [`Box<T>`]: alloc::boxed::Box + +use core::{convert::Infallible , marker::PhantomData , mem::MaybeUninit }; + +/// A pinned initializer for `T`. "An initializer for a pinned
T" instead?
Quoted 3 lines
To me this does not really make sense, since the type
Tcannot be pinned, only an instance can be. But maybe I should use the termpin-initializerinstead.
I see. Could be "An initializer for a pinned instance of T" then. Just to clarify that the initializer itself is not the thing that is pinned.
Re: [PATCH v3 04/13] rust: add pin-init API core
In reply to [email protected]Quoted 20 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
This API is used to facilitate safe pinned initialization of structs. It replaces cumbersome
unsafemanual 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!andtry_init!macros along with their internal types.
3. Adds theInPlaceInittrait that allows using an initializer to create an object inside of aBox<T>and other smart pointers.
4. Adds thePinnedDroptrait and adds macro support for it inthe `#[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.
Quoted 3 lines
Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>
rust/kernel/init.rs line 23
Quoted 3 lines
rust/kernel/init.rs new file +3
-0+//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix.
Typo: Should be "macros".
Quoted 1 line
+type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;
I think it would make sense to include a link to the nomicon on the documentation for the Invariant type.
E.g. this link: https://doc.rust-lang.org/nomicon/subtyping.html
rust/kernel/init.rs line 123
Quoted 4 lines
rust/kernel/init.rs new file +4
-0+// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure <F ,T : ?Sized ,E >(F ,Invariant <(E ,T )>);
Documentation for a type should use /// rather than //.
I think it would help to call out explicitly in the documentation on this type that it is an implementation detail of the pin_init_from_closure and init_from_closure methods.
Re: [PATCH v3 04/13] rust: add pin-init API core
Quoted 30 lines · Alice Ryhl
Quoted 12 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
This API is used to facilitate safe pinned initialization of structs. It replaces cumbersomeunsafemanual 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!andtry_init!macros along with their internal types.
3. Adds theInPlaceInittrait that allows using an initializer to create an object inside of aBox<T>and other smart pointers.
4. Adds thePinnedDroptrait and adds macro support for it inQuoted 8 lines
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.Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>Reviewed-by Alice Ryhl <[email protected]>rust/kernel/init.rs line 23
Quoted 3 lines
rust/kernel/init.rs new file +3
-0+//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix. Typo: Should be "macros".
Quoted 6 lines
Quoted 1 line
+type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;
I think it would make sense to include a link to the nomicon on the documentation for the Invariant type.
E.g. this link: https://doc.rust-lang.org/nomicon/subtyping.html
That would be nice. I think this also applies: https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns
Quoted 11 lines
rust/kernel/init.rs line 123
Quoted 5 lines
rust/kernel/init.rs new file +4
-0+// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure <F ,T : ?Sized ,E >(F ,Invariant <(E ,T )>);Documentation for a type should use /// rather than //.
I think it would help to call out explicitly in the documentation on this type that it is an implementation detail of the
pin_init_from_closureandinit_from_closuremethods.
Re: [PATCH v3 04/13] rust: add pin-init API core
Quoted 33 lines · Andreas Hindborg
Quoted 30 lines · Alice Ryhl
Quoted 12 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
This API is used to facilitate safe pinned initialization of structs. It replaces cumbersomeunsafemanual 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!andtry_init!macros along with their internal types.
3. Adds theInPlaceInittrait that allows using an initializer to create an object inside of aBox<T>and other smart pointers.
4. Adds thePinnedDroptrait and adds macro support for it inQuoted 8 lines
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.Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>Reviewed-by Alice Ryhl <[email protected]>rust/kernel/init.rs line 23
Quoted 3 lines
rust/kernel/init.rs new file +3
-0+//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix. Typo: Should be "macros".
Quoted 8 lines
Quoted 6 lines
Quoted 1 line
+type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;
I think it would make sense to include a link to the nomicon on the documentation for the Invariant type.
E.g. this link: https://doc.rust-lang.org/nomicon/subtyping.html
That would be nice. I think this also applies: https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns
Yeah I very commonly use that one as well.
Quoted 9 lines
Quoted 9 lines
rust/kernel/init.rs line 123
Quoted 6 lines
rust/kernel/init.rs new file +4
-0+// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure <F ,T : ?Sized ,E >(F ,Invariant <(E ,T )>);Documentation for a type should use /// rather than //.
Quoted 4 lines
Quoted 3 lines
I think it would help to call out explicitly in the documentation on this type that it is an implementation detail of the
pin_init_from_closureandinit_from_closuremethods.
--
Cheers,
Benno
Re: [PATCH v3 04/13] rust: add pin-init API core
In reply to Alice RyhlQuoted 33 lines · Alice Ryhl
Quoted 20 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
This API is used to facilitate safe pinned initialization of structs. It replaces cumbersome
unsafemanual 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!andtry_init!macros along with their internal types.
3. Adds theInPlaceInittrait that allows using an initializer to create an object inside of aBox<T>and other smart pointers.
4. Adds thePinnedDroptrait and adds macro support for it inthe `#[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.Quoted 3 lines
Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>Reviewed-by Alice Ryhl <[email protected]>rust/kernel/init.rs line 23
Quoted 3 lines
rust/kernel/init.rs new file +3
-0+//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix. Typo: Should be "macros".
Quoted 6 lines
Quoted 1 line
+type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;
I think it would make sense to include a link to the nomicon on the documentation for the Invariant type.
E.g. this link: https://doc.rust-lang.org/nomicon/subtyping.html
Sure that is a good idea.
Quoted 10 lines
rust/kernel/init.rs line 123
Quoted 4 lines
rust/kernel/init.rs new file +4
-0+// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure <F ,T : ?Sized ,E >(F ,Invariant <(E ,T )>);Documentation for a type should use /// rather than //.
I think it would help to call out explicitly in the documentation on this type that it is an implementation detail of the
pin_init_from_closureandinit_from_closuremethods.
Yeah, I will also move this into __internal.rs and add the comment.
--
Cheers,
Benno
Re: [PATCH v3 04/13] rust: add pin-init API core
In reply to [email protected]Quoted 246 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
This API is used to facilitate safe pinned initialization of structs. It replaces cumbersome
unsafemanual 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!andtry_init!macros along with their internal types.
3. Adds theInPlaceInittrait that allows using an initializer to create an object inside of aBox<T>and other smart pointers.
4. Adds thePinnedDroptrait and adds macro support for it inthe `#[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>providesunsafefunctions 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
mutexfield in a Rust struct, this struct also needs to be pinned, because amutexcontains alist_head. Additionally initializing alist_headrequires 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 theMaybeUninit<T>wrapper type, which allows handling uninitialized memory, but this requires using theunsaferaw 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 theMutex<T>are upheld. But if the fields are inaccessible, then initialization of aMutex<T>needs to be somehow achieved via a function or a macro. Because theMutex<T>must be pinned in memory, the function cannot return it by value. It also cannot allocate aBoxto put theMutex<T>into, because that is an unnecessary allocation and indirection which would hurt performance.The current solution was to split this function into two parts:
1. A
newfunction that returns a partially initializedMutex<T>,
2. Aninitfunction that requires theMutex<T>to be pinned and that fully initializes theMutex<T>.Both of these functions have to be marked
unsafe, since a call tonewneeds to be accompanied with a call toinit, otherwise using theMutex<T>could result in UB. And because callinginittwice also is not safe. WhileMutex<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
unsafeAPI, pinned initialization is riddled withunsaferesulting 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 [2] 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
unsafeand thus comes with the usual Rust promise of safe code not introducing any memory violations. Additionally it is now up to the caller ofnew()to decide the memory location of theSharedState. They can choose at the momentArc<T>,Box<T>or the stack.--
The API has the following architecture:
1. Initializer traitsPinInit<T, E>andInit<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 aTat 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 anunsafeoperation. To allow safe initializer creation, thepin_init!is provided along with three other variants:try_pin_init!,try_init!andinit!. 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 aimpl 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[3] andpin-project-lite[4] had been considered, but were ultimately rejected:
-pin-projectdepends onsyn[5] which is a very big dependency, around 50k lines of code.
-pin-project-liteis 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://crates.io/crates/pin-project [3]Link https://crates.io/crates/syn [5]Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>--- rust/kernel/init.rs | 210 +++++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 7 ++ scripts/Makefile.build | 2 +- 3 files changed, 218 insertions(+), 1 deletion(-)create mode 100644
rust/kernel/init.rsrust/kernel/init.rs new file +13
-0@@ -0,0 +1,210 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +//! API to safely and fallibly initialize pinned `struct`s using in-place constructors. +//! +//! It also allows in-place initialization of big `struct`s that would otherwise produce a stack +//! overflow. +//! +//! Most `struct`s from the [`sync`] module need to be pinned, because they contain self-referential +//! `struct`s from C. [Pinning][pinning] is Rust's way of ensuring data does not move. +//! +//! # Overview +//! +//! To initialize a `struct` with an in-place constructor you will need two things:
rust/kernel/init.rs line 23
Quoted 10 lines
rust/kernel/init.rs new file +10
-0+//! - an in-place constructor, +//! - a memory location that can hold your `struct`. +//! +//! To get an in-place constructor there are generally two options: +//! - a custom function/macro returning an in-place constructor provided by someone else, +//! - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer. +//! +//! Aside from pinned initialization, this API also supports in-place construction without pinning, +//! the marcos/types/functions are generally named like the pinned variants without the `pin` +//! prefix.
Typo: Should be "macros".
Quoted 86 lines
rust/kernel/init.rs new file +86
-0+//! +//! [`sync`]: kernel::sync +//! [pinning]: https://doc.rust-lang.org/std/pin/index.html +//! [structurally pinned fields]: +//! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +//! [`Arc<T>`]: crate::sync::Arc +//! [`impl PinInit<Foo>`]: PinInit +//! [`impl PinInit<T, E>`]: PinInit +//! [`impl Init<T, E>`]: Init +//! [`Opaque`]: kernel::types::Opaque +//! [`pin_data`]: ::macros::pin_data +//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +//! [`Box<T>`]: alloc::boxed::Box + +use core::{convert::Infallible , marker::PhantomData , mem::MaybeUninit }; + +/// A pinned initializer for `T`. +/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`pin_init_from_closure`] where possible. +/// +/// The [`PinInit::__pinned_init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// [`Arc<T>`]: crate::sync::Arc +/// [`Arc::pin_init`]: crate::sync::Arc::pin_init +/// [`UniqueArc<T>`]: kernel::sync::UniqueArc +/// [`Box<T>`]: alloc::boxed::Box +#[must_use = "An initializer must be used in order to create its value." ] +pub unsafe trait PinInit <T : ?Sized ,E =Infallible >:Sized { +/// Initializes `slot`. +/// +/// # Safety +/// +/// - `slot` is a valid pointer to uninitialized memory. +/// - the caller does not touch `slot` when `Err` is returned, they are only permitted to +/// deallocate. +/// - `slot` will not move until it is dropped, i.e. it will be pinned. +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),E >; +} + +/// An initializer for `T`. +/// +/// To use this initializer, you will need a suitable memory location that can hold a `T`. This can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Because [`PinInit<T, E>`] is a super trait, you can +/// use every function that takes it as well. +/// +/// Also see the [module description](self). +/// +/// # Safety +/// +/// When implementing this type you will need to take great care. Also there are probably very few +/// cases where a manual implementation is necessary. Use [`init_from_closure`] where possible. +/// +/// The [`Init::__init`] function +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +/// +/// The `__pinned_init` function from the supertrait [`PinInit`] needs to execute the exact same +/// code as `__init`. +/// +/// Contrary to its supertype [`PinInit<T, E>`] the caller is allowed to +/// move the pointee after initialization. +/// +/// [`Arc<T>`]: crate::sync::Arc +/// [`UniqueArc<T>`]: kernel::sync::UniqueArc +/// [`Box<T>`]: alloc::boxed::Box +#[must_use = "An initializer must be used in order to create its value." ] +pub unsafe trait Init <T : ?Sized ,E =Infallible >:PinInit <T ,E > { +/// Initializes `slot`.
rust/kernel/init.rs line 119
Quoted 10 lines
rust/kernel/init.rs new file +10
-0+/// +/// # Safety +/// +/// - `slot` is a valid pointer to uninitialized memory. +/// - the caller does not touch `slot` when `Err` is returned, they are only permitted to +/// deallocate. +unsafe fn __init (self, slot: *mut T ) ->Result <(),E >; +} + +type Invariant <T > =PhantomData <fn (*mut T ) -> *mut T >;
I think it would make sense to include a link to the nomicon on the documentation for the Invariant type.
Quoted 139 lines
rust/kernel/init.rs new file +91
-0+// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this +// type, since the closure needs to fulfill the same safety requirement as the +// `__pinned_init`/`__init` functions. +struct InitClosure <F ,T : ?Sized ,E >(F ,Invariant <(E ,T )>); + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__pinned_init` invariants. +unsafe impl <T : ?Sized ,F ,E >PinInit <T ,E >for InitClosure <F ,T ,E > +where +F :FnOnce (*mut T ) ->Result <(),E >, +{ +#[inline] +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),E > { + (self.0 )(slot) + } +} + +// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the +// `__init` invariants. +unsafe impl <T : ?Sized ,F ,E >Init <T ,E >for InitClosure <F ,T ,E > +where +F :FnOnce (*mut T ) ->Result <(),E >, +{ +#[inline] +unsafe fn __init (self, slot: *mut T ) ->Result <(),E > { + (self.0 )(slot) + } +} + +/// Creates a new [`PinInit<T, E>`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - may assume that the `slot` does not move if `T: !Unpin`, +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn pin_init_from_closure <T : ?Sized ,E >( + f:impl FnOnce (*mut T ) ->Result <(),E >, +) ->impl PinInit <T ,E > { +InitClosure (f,PhantomData ) +} + +/// Creates a new [`Init<T, E>`] from the given closure. +/// +/// # Safety +/// +/// The closure: +/// - returns `Ok(())` if it initialized every field of `slot`, +/// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: +/// - `slot` can be deallocated without UB occurring, +/// - `slot` does not need to be dropped, +/// - `slot` is not partially initialized. +/// - the `slot` may move after initialization. +/// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. +#[inline] +pub const unsafe fn init_from_closure <T : ?Sized ,E >( + f:impl FnOnce (*mut T ) ->Result <(),E >, +) ->impl Init <T ,E > { +InitClosure (f,PhantomData ) +} + +/// An initializer that leaves the memory uninitialized. +/// +/// The initializer is a no-op. The `slot` memory is not changed. +#[inline] +pub fn uninit <T >() ->impl Init <MaybeUninit <T >> { +// SAFETY: The memory is allowed to be uninitialized. +unsafe {init_from_closure (|_|Ok (())) } +} + +// SAFETY: Every type can be initialized by-value. +unsafe impl <T >PinInit <T >for T { +unsafe fn __pinned_init (self, slot: *mut T ) ->Result <(),Infallible > { +unsafe { slot.write (self) }; +Ok (()) + } +} + +// SAFETY: Every type can be initialized by-value. +unsafe impl <T >Init <T >for T { +unsafe fn __init (self, slot: *mut T ) ->Result <(),Infallible > { +unsafe { slot.write (self) }; +Ok (()) + } +}rust/kernel/lib.rs +7
-0@@ -16,7 +16,9 @@#![feature(coerce_unsized)] #![feature(core_ffi_c)] #![feature(dispatch_from_dyn)] +#![feature(explicit_generic_args_with_impl_trait)] #![feature(generic_associated_types)] +#![feature(new_uninit)] #![feature(receiver_trait)] #![feature(unsize)] @@ -25,11 +27,16 @@#[cfg(not( CONFIG_RUST ))] compile_error! ("Missing kernel configuration for conditional compilation" ); +#[allow(unused_extern_crates)] +// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate). +extern crate selfas kernel; +#[cfg(not(test))] #[cfg(not(testlib))] mod allocator;mod build_assert;pub mod error; +pub mod init;pub mod prelude;pub mod print;mod static_assert;scripts/Makefile.build +1
-2@@ -277,7 +277,7 @@ $(obj)/%.lst: $(src)/%.c FORCE # Compile Rust sources (.rs) # --------------------------------------------------------------------------- -rust_allowed_features := core_ffi_c +rust_allowed_features := core_ffi_c,explicit_generic_args_with_impl_trait rust_common_cmd = \ RUST_MODFILE=$(modfile) $(RUSTC_OR_CLIPPY) $(rust_flags) \ --2.39.2
Re: [PATCH v3 04/13] rust: add pin-init API core
In reply to [email protected]Quoted 21 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
This API is used to facilitate safe pinned initialization of structs. It replaces cumbersome
unsafemanual 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!andtry_init!macros along with their internal types.
3. Adds theInPlaceInittrait that allows using an initializer to create an object inside of aBox<T>and other smart pointers.
4. Adds thePinnedDroptrait and adds macro support for it in the#[pin_data]macro.
5. Adds thestack_pin_init!macro allowing to pin-initialize a struct on the stack.
6. Adds theZeroabletrait andinit::zeroedfunction to initialize types that have0x00in all bytes as a valid bit pattern.--
<snip>
Quoted 4 lines
Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>---
PATCH v3 5/13 rust: init: add initialization macros
In reply to [email protected]From: Benno Lossin <[email protected]>
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.
--- rust/kernel/init.rs | 816 ++++++++++++++++++++++++++++++++- rust/kernel/init/__internal.rs | 134 ++++++ rust/kernel/init/macros.rs | 707 ++++++++++++++++++++++++++++ rust/macros/lib.rs | 29 ++ rust/macros/pin_data.rs | 79 ++++ rust/macros/quote.rs | 2 - 6 files changed, 1760 insertions(+), 7 deletions(-) create mode 100644 rust/kernel/init/__internal.rs create mode 100644 rust/kernel/init/macros.rs create mode 100644 rust/macros/pin_data.rs
rust/kernel/init.rs +811 -5
@@ -14,7 +14,8 @@//! - an in-place constructor, //! - a memory location that can hold your `struct`. //! -//! To get an in-place constructor there are generally two options: +//! To get an in-place constructor there are generally three options: +//! - directly creating an in-place constructor using the [`pin_init!`] macro, //! - a custom function/macro returning an in-place constructor provided by someone else, //! - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer. //!
@@ -22,6 +23,87 @@//! the marcos/types/functions are generally named like the pinned variants without the `pin` //! prefix. //! +//! # Examples +//! +//! ## Using the [`pin_init!`] macro +//! +//! If you want to use [`PinInit`], then you will have to annotate your `struct` with +//! `#[`[`pin_data`]`]`. It is a macro that uses `#[pin]` as a marker for +//! [structurally pinned fields]. After doing this, you can then create an in-place constructor via +//! [`pin_init!`]. The syntax is almost the same as normal `struct` initializers. The difference is +//! that you need to write `<-` instead of `:` for fields that you want to initialize in-place. +//! +//! ```rust +//! # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +//! use kernel::{prelude::*, sync::Mutex, new_mutex}; +//! # use core::pin::Pin; +//! #[pin_data] +//! struct Foo { +//! #[pin] +//! a: Mutex<usize>, +//! b: u32, +//! } +//! +//! let foo = pin_init!(Foo { +//! a <- new_mutex!(42, "Foo::a"), +//! b: 24, +//! }); +//! ``` +//! +//! `foo` now is of the type [`impl PinInit<Foo>`]. We can now use any smart pointer that we like +//! (or just the stack) to actually initialize a `Foo`: +//! +//! ```rust +//! # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +//! # use kernel::{prelude::*, sync::Mutex, new_mutex}; +//! # use core::pin::Pin; +//! # #[pin_data] +//! # struct Foo { +//! # #[pin] +//! # a: Mutex<usize>, +//! # b: u32, +//! # } +//! # let foo = pin_init!(Foo { +//! # a <- new_mutex!(42, "Foo::a"), +//! # b: 24, +//! # }); +//! let foo: Result<Pin<Box<Foo>>> = Box::pin_init(foo); +//! ``` +//! +//! For more information see the [`pin_init!`] macro. +//! +//! ## Using a custom function/macro that returns an initializer +//! +//! Many types from the kernel supply a function/macro that returns an initializer, because the +//! above method only works for types where you can access the fields. +//! +//! ```rust +//! # use kernel::{new_mutex, sync::{Arc, Mutex}}; +//! let mtx: Result<Arc<Mutex<usize>>> = Arc::pin_init(new_mutex!(42, "example::mtx")); +//! ``` +//! +//! To declare an init macro/function you just return an [`impl PinInit<T, E>`]: +//! +//! ```rust +//! # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +//! # use kernel::{sync::Mutex, prelude::*, new_mutex, init::PinInit, try_pin_init}; +//! #[pin_data] +//! struct DriverData { +//! #[pin] +//! status: Mutex<i32>, +//! buffer: Box<[u8; 1_000_000]>, +//! } +//! +//! impl DriverData { +//! fn new() -> impl PinInit<Self, Error> { +//! try_pin_init!(Self { +//! status <- new_mutex!(0, "DriverData::status"), +//! buffer: Box::init(kernel::init::zeroed())?, +//! }) +//! } +//! } +//! ``` +//! //! [`sync`]: kernel::sync //! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]:
@@ -33,9 +115,735 @@//! [`Opaque`]: kernel::types::Opaque //! [`pin_data`]: ::macros::pin_data //! [`UniqueArc<T>`]: kernel::sync::UniqueArc -//! [`Box<T>`]: alloc::boxed::Box -use core::{convert::Infallible , marker::PhantomData , mem::MaybeUninit }; +use alloc::boxed::Box ; +use core::{cell::Cell , convert::Infallible , marker::PhantomData , mem::MaybeUninit , ptr}; + +#[doc(hidden)] +pub mod __internal; +#[doc(hidden)] +pub mod macros; + +/// Construct an in-place, pinned initializer for `struct`s. +/// +/// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use +/// [`try_pin_init!`]. +/// +/// The syntax is almost identical to that of a normal `struct` initializer: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use core::pin::Pin; +/// #[pin_data] +/// struct Foo { +/// a: usize, +/// b: Bar, +/// } +/// +/// #[pin_data] +/// struct Bar { +/// x: u32, +/// } +/// +/// # fn demo() -> impl PinInit<Foo> { +/// let a = 42; +/// +/// let initializer = pin_init!(Foo { +/// a, +/// b: Bar { +/// x: 64, +/// }, +/// }); +/// # initializer } +/// # Box::pin_init(demo()).unwrap(); +/// ``` +/// +/// Arbitrary Rust expressions can be used to set the value of a variable. +/// +/// The fields are initialized in the order that they appear in the initializer. So it is possible +/// to read already initialized fields using raw pointers. +/// +/// IMPORTANT: You are not allowed to create references to fields of the struct inside of the +/// initializer. +/// +/// # Init-functions +/// +/// When working with this API it is often desired to let others construct your types without +/// giving access to all fields. This is where you would normally write a plain function `new` +/// that would return a new instance of your type. With this API that is also possible. +/// However, there are a few extra things to keep in mind. +/// +/// To create an initializer function, simply declare it like this: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, prelude::*, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo { +/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar { +/// # x: u32, +/// # } +/// +/// impl Foo { +/// fn new() -> impl PinInit<Self> { +/// pin_init!(Self { +/// a: 42, +/// b: Bar { +/// x: 64, +/// }, +/// }) +/// } +/// } +/// ``` +/// +/// Users of `Foo` can now create it like this: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo { +/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar { +/// # x: u32, +/// # } +/// # impl Foo { +/// # fn new() -> impl PinInit<Self> { +/// # pin_init!(Self { +/// # a: 42, +/// # b: Bar { +/// # x: 64, +/// # }, +/// # }) +/// # } +/// # } +/// let foo = Box::pin_init(Foo::new()); +/// ``` +/// +/// They can also easily embed it into their own `struct`s: +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo { +/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar { +/// # x: u32, +/// # } +/// # impl Foo { +/// # fn new() -> impl PinInit<Self> { +/// # pin_init!(Self { +/// # a: 42, +/// # b: Bar { +/// # x: 64, +/// # }, +/// # }) +/// # } +/// # } +/// #[pin_data] +/// struct FooContainer { +/// #[pin] +/// foo1: Foo, +/// #[pin] +/// foo2: Foo, +/// other: u32, +/// } +/// +/// impl FooContainer { +/// fn new(other: u32) -> impl PinInit<Self> { +/// pin_init!(Self { +/// foo1 <- Foo::new(), +/// foo2 <- Foo::new(), +/// other, +/// }) +/// } +/// } +/// ``` +/// +/// Here we see that when using `pin_init!` with `PinInit`, one needs to write `<-` instead of `:`. +/// This signifies that the given field is initialized in-place. As with `struct` initializers, just +/// writing the field (in this case `other`) without `:` or `<-` means `other: other,`. +/// +/// # Syntax +/// +/// As already mentioned in the examples above, inside of `pin_init!` a `struct` initializer with +/// the following modifications is expected: +/// - Fields that you want to initialize in-place have to use `<-` instead of `:`. +/// - In front of the initializer you can write `&this in` to have access to a [`NonNull<Self>`] +/// pointer named `this` inside of the initializer. +/// +/// For instance: +/// +/// ```rust +/// # use kernel::pin_init; +/// # use macros::pin_data; +/// # use core::{ptr::addr_of_mut, marker::PhantomPinned}; +/// #[pin_data] +/// struct Buf { +/// ptr: *mut u8, +/// buf: [u8; 64], +/// #[pin] +/// pin: PhantomPinned, +/// } +/// pin_init!(&this in Buf { +/// buf: [0; 64], +/// ptr: unsafe { addr_of_mut!((*this.as_ptr()).buf).cast() }, +/// pin: PhantomPinned, +/// }); +/// ``` +/// +/// [`try_pin_init!`]: kernel::try_pin_init +/// [`NonNull<Self>`]: core::ptr::NonNull +/// [`Error`]: kernel::error::Error +// For a detailed example of how this macro works, see the module documentation of the hidden +// module `__internal` inside of `init/__internal.rs`. +#[macro_export] +macro_rules! pin_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_pin_init!( + @this ($($this)?), + @typ ($t $(::<$($generics),*>)?), + @fields ($($fields)*), + @error (::core::convert::Infallible ), + ) + }; +} + +/// Construct an in-place, fallible pinned initializer for `struct`s. +/// +/// If the initialization can complete without error (or [`Infallible`]), then use [`pin_init!`]. +/// +/// You can use the `?` operator or use `return Err(err)` inside the initializer to stop +/// initialization and return the error. +/// +/// IMPORTANT: if you have `unsafe` code inside of the initializer you have to ensure that when +/// initialization fails, the memory can be safely deallocated without any further modifications. +/// +/// This macro defaults the error to [`Error`]. +/// +/// The syntax is identical to [`pin_init!`] with the following exception: you can append `? $type` +/// after the `struct` initializer to specify the error type you want to use. +/// +/// # Examples +/// +/// ```rust +/// # #![feature(new_uninit)] +/// use kernel::{init::PinInit, error::Error}; +/// #[pin_data] +/// struct BigBuf { +/// big: Box<[u8; 1024 * 1024 * 1024]>, +/// small: [u8; 1024 * 1024], +/// ptr: *mut u8, +/// } +/// +/// impl BigBuf { +/// fn new() -> impl PinInit<Self, Error> { +/// try_pin_init!(Self { +/// big: { +/// let zero = Box::try_new_zeroed()?; +/// unsafe { zero.assume_init() } +/// }, +/// small: [0; 1024 * 1024], +/// ptr: core::ptr::null_mut(), +/// }? Error) +/// } +/// } +/// ``` +/// +/// [`Error`]: kernel::error::Error +// For a detailed example of how this macro works, see the module documentation of the hidden +// module `__internal` inside of `init/__internal.rs`. +#[macro_export] +macro_rules! try_pin_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_pin_init!( + @this ($($this)?), + @typ ($t $(::<$($generics),*>)? ), + @fields ($($fields)*), + @error ($crate ::error::Error ), + ) + }; + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }? $err:ty) => { + $crate::try_pin_init!( + @this ($($this)?), + @typ ($t $(::<$($generics),*>)? ), + @fields ($($fields)*), + @error ($err), + ) + }; + ( + @this($($this:ident)?), + @typ($t:ident $(::<$($generics:ty),*>)?), + @fields($($fields:tt)*), + @error($err:ty), + ) => {{ +// We do not want to allow arbitrary returns, so we declare this type as the `Ok` return +// type and shadow it later when we insert the arbitrary user code. That way there will be +// no possibility of returning without `unsafe`. +struct __InitOk ; +// Get the pin data from the supplied type. +let data =unsafe { +use $crate::init::__internal::HasPinData ; + $t$(::<$($generics),*>)?::__pin_data () + }; +// Ensure that `data` really is of type `PinData` and help with type inference: +let init = $crate::init::__internal::PinData ::make_closure ::<_ ,__InitOk , $err>( + data, +move |slot| { + { +// Shadow the structure so it cannot be used to return early. +struct __InitOk ; +// Create the `this` so it can be referenced by the user inside of the +// expressions creating the individual fields. + $(let $this =unsafe { ::core::ptr::NonNull ::new_unchecked (slot) };)? +// Initialize every field. + $crate::try_pin_init!(init_slot : + @data(data), + @slot (slot), + @munch_fields ($($fields)*,), + ); +// We use unreachable code to ensure that all fields have been mentioned exactly +// once, this struct initializer will still be type-checked and complain with a +// very natural error message if a field is forgotten/mentioned more than once. +#[allow(unreachable_code, clippy::diverging_sub_expression)] +if false { + $crate::try_pin_init!(make_initializer : + @slot(slot), + @type_name ($t), + @munch_fields ($($fields)*,), + @acc (), + ); + } +// Forget all guards, since initialization was a success. + $crate::try_pin_init!(forget_guards : + @munch_fields($($fields)*,), + ); + } +Ok (__InitOk) + } + ); +let init =move |slot| -> ::core::result::Result <(), $err> { +init (slot).map (|__InitOk| ()) + }; +let init =unsafe { $crate::init::pin_init_from_closure ::<_ , $err>(init) }; + init + }}; + (init_slot: + @data($data:ident), + @slot($slot:ident), + @munch_fields($(,)?), + ) => { +// Endpoint of munching, no fields are left. + }; + (init_slot: + @data($data:ident), + @slot($slot:ident), +// In-place initialization syntax. + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { +let $field = $val; +// Call the initializer. +// +// SAFETY: `slot` is valid, because we are inside of an initializer closure, we +// return when an error/panic occurs. +// We also use the `data` to require the correct trait (`Init` or `PinInit`) for `$field`. +unsafe { $data.$field(::core::ptr::addr_of_mut!((*$slot).$field), $field)? }; +// Create the drop guard. +// +// We only give access to `&DropGuard`, so it cannot be forgotten via safe code. +// +// SAFETY: We forget the guard later when initialization has succeeded. +let $field = &unsafe { + $crate::init::__internal::DropGuard ::new (::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_pin_init!(init_slot : + @data($data), + @slot ($slot), + @munch_fields ($($rest)*), + ); + }; + (init_slot: + @data($data:ident), + @slot($slot:ident), +// Direct value init, this is safe for every field. + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { + $(let $field = $val;)? +// Initialize the field. +// +// SAFETY: The memory at `slot` is uninitialized. +unsafe { ::core::ptr::write (::core::ptr::addr_of_mut!((*$slot).$field), $field) }; +// Create the drop guard: +// +// We only give access to `&DropGuard`, so it cannot be accidentally forgotten. +// +// SAFETY: We forget the guard later when initialization has succeeded. +let $field = &unsafe { + $crate::init::__internal::DropGuard ::new (::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_pin_init!(init_slot : + @data($data), + @slot ($slot), + @munch_fields ($($rest)*), + ); + }; + (make_initializer: + @slot($slot:ident), + @type_name($t:ident), + @munch_fields($(,)?), + @acc($($acc:tt)*), + ) => { +// Endpoint, nothing more to munch, create the initializer. +// Since we are in the `if false` branch, this will never get executed. We abuse `slot` to +// get the correct type inference here: +unsafe { + ::core::ptr::write ($slot, $t { + $($acc)* + }); + } + }; + (make_initializer: + @slot($slot:ident), + @type_name($t:ident), + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_pin_init!(make_initializer : + @slot($slot), + @type_name ($t), + @munch_fields ($($rest)*), + @acc ($($acc)* $field: ::core::panic!(),), + ); + }; + (make_initializer: + @slot($slot:ident), + @type_name($t:ident), + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_pin_init!(make_initializer : + @slot($slot), + @type_name ($t), + @munch_fields ($($rest)*), + @acc ($($acc)* $field: ::core::panic!(),), + ); + }; + (forget_guards: + @munch_fields($(,)?), + ) => { +// Munching finished. + }; + (forget_guards: + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { +unsafe { $crate::init::__internal::DropGuard ::forget ($field) }; + + $crate::try_pin_init!(forget_guards : + @munch_fields($($rest)*), + ); + }; + (forget_guards: + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { +unsafe { $crate::init::__internal::DropGuard ::forget ($field) }; + + $crate::try_pin_init!(forget_guards : + @munch_fields($($rest)*), + ); + }; +} + +/// Construct an in-place initializer for `struct`s. +/// +/// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use +/// [`try_init!`]. +/// +/// The syntax is identical to [`pin_init!`] and its safety caveats also apply: +/// - `unsafe` code must guarantee either full initialization or return an error and allow +/// deallocation of the memory. +/// - the fields are initialized in the order given in the initializer. +/// - no references to fields are allowed to be created inside of the initializer. +/// +/// This initializer is for initializing data in-place that might later be moved. If you want to +/// pin-initialize, use [`pin_init!`]. +/// +/// [`Error`]: kernel::error::Error +// For a detailed example of how this macro works, see the module documentation of the hidden +// module `__internal` inside of `init/__internal.rs`. +#[macro_export] +macro_rules! init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_init!( + @this ($($this)?), + @typ ($t $(::<$($generics),*>)?), + @fields ($($fields)*), + @error (::core::convert::Infallible ), + ) + } +} + +/// Construct an in-place fallible initializer for `struct`s. +/// +/// This macro defaults the error to [`Error`]. If you need [`Infallible`], then use +/// [`init!`]. +/// +/// The syntax is identical to [`try_pin_init!`]. If you want to specify a custom error, +/// append `? $type` after the `struct` initializer. +/// The safety caveats from [`try_pin_init!`] also apply: +/// - `unsafe` code must guarantee either full initialization or return an error and allow +/// deallocation of the memory. +/// - the fields are initialized in the order given in the initializer. +/// - no references to fields are allowed to be created inside of the initializer. +/// +/// # Examples +/// +/// ```rust +/// use kernel::{init::PinInit, error::Error}; +/// struct BigBuf { +/// big: Box<[u8; 1024 * 1024 * 1024]>, +/// small: [u8; 1024 * 1024], +/// } +/// +/// impl BigBuf { +/// fn new() -> impl Init<Self, Error> { +/// try_init!(Self { +/// big: { +/// let zero = Box::try_new_zeroed()?; +/// unsafe { zero.assume_init() } +/// }, +/// small: [0; 1024 * 1024], +/// }? Error) +/// } +/// } +/// ``` +/// +/// [`Error`]: kernel::error::Error +// For a detailed example of how this macro works, see the module documentation of the hidden +// module `__internal` inside of `init/__internal.rs`. +#[macro_export] +macro_rules! try_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::try_init!( + @this ($($this)?), + @typ ($t $(::<$($generics),*>)?), + @fields ($($fields)*), + @error ($crate ::error::Error ), + ) + }; + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }? $err:ty) => { + $crate::try_init!( + @this ($($this)?), + @typ ($t $(::<$($generics),*>)?), + @fields ($($fields)*), + @error ($err), + ) + }; + ( + @this($($this:ident)?), + @typ($t:ident $(::<$($generics:ty),*>)?), + @fields($($fields:tt)*), + @error($err:ty), + ) => {{ +// We do not want to allow arbitrary returns, so we declare this type as the `Ok` return +// type and shadow it later when we insert the arbitrary user code. That way there will be +// no possibility of returning without `unsafe`. +struct __InitOk ; +// Get the init data from the supplied type. +let data =unsafe { +use $crate::init::__internal::HasInitData ; + $t$(::<$($generics),*>)?::__init_data () + }; +// Ensure that `data` really is of type `InitData` and help with type inference: +let init = $crate::init::__internal::InitData ::make_closure ::<_ ,__InitOk , $err>( + data, +move |slot| { + { +// Shadow the structure so it cannot be used to return early. +struct __InitOk ; +// Create the `this` so it can be referenced by the user inside of the +// expressions creating the individual fields. + $(let $this =unsafe { ::core::ptr::NonNull ::new_unchecked (slot) };)? +// Initialize every field. + $crate::try_init!(init_slot : + @slot(slot), + @munch_fields ($($fields)*,), + ); +// We use unreachable code to ensure that all fields have been mentioned exactly +// once, this struct initializer will still be type-checked and complain with a +// very natural error message if a field is forgotten/mentioned more than once. +#[allow(unreachable_code, clippy::diverging_sub_expression)] +if false { + $crate::try_init!(make_initializer : + @slot(slot), + @type_name ($t), + @munch_fields ($($fields)*,), + @acc (), + ); + } +// Forget all guards, since initialization was a success. + $crate::try_init!(forget_guards : + @munch_fields($($fields)*,), + ); + } +Ok (__InitOk) + } + ); +let init =move |slot| -> ::core::result::Result <(), $err> { +init (slot).map (|__InitOk| ()) + }; +let init =unsafe { $crate::init::init_from_closure ::<_ , $err>(init) }; + init + }}; + (init_slot: + @slot($slot:ident), + @munch_fields( $(,)?), + ) => { +// Endpoint of munching, no fields are left. + }; + (init_slot: + @slot($slot:ident), + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { +let $field = $val; +// Call the initializer. +// +// SAFETY: `slot` is valid, because we are inside of an initializer closure, we +// return when an error/panic occurs. +unsafe { + $crate::init::Init ::__init ($field, ::core::ptr::addr_of_mut!((*$slot).$field))?; + } +// Create the drop guard. +// +// We only give access to `&DropGuard`, so it cannot be accidentally forgotten. +// +// SAFETY: We forget the guard later when initialization has succeeded. +let $field = &unsafe { + $crate::init::__internal::DropGuard ::new (::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_init!(init_slot : + @slot($slot), + @munch_fields ($($rest)*), + ); + }; + (init_slot: + @slot($slot:ident), +// Direct value init. + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { + $(let $field = $val;)? +// Call the initializer. +// +// SAFETY: The memory at `slot` is uninitialized. +unsafe { ::core::ptr::write (::core::ptr::addr_of_mut!((*$slot).$field), $field) }; +// Create the drop guard. +// +// We only give access to `&DropGuard`, so it cannot be accidentally forgotten. +// +// SAFETY: We forget the guard later when initialization has succeeded. +let $field = &unsafe { + $crate::init::__internal::DropGuard ::new (::core::ptr::addr_of_mut!((*$slot).$field)) + }; + + $crate::try_init!(init_slot : + @slot($slot), + @munch_fields ($($rest)*), + ); + }; + (make_initializer: + @slot($slot:ident), + @type_name($t:ident), + @munch_fields( $(,)?), + @acc($($acc:tt)*), + ) => { +// Endpoint, nothing more to munch, create the initializer. +// Since we are in the `if false` branch, this will never get executed. We abuse `slot` to +// get the correct type inference here: +unsafe { + ::core::ptr::write ($slot, $t { + $($acc)* + }); + } + }; + (make_initializer: + @slot($slot:ident), + @type_name($t:ident), + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_init!(make_initializer : + @slot($slot), + @type_name ($t), + @munch_fields ($($rest)*), + @acc ($($acc)*$field: ::core::panic!(),), + ); + }; + (make_initializer: + @slot($slot:ident), + @type_name($t:ident), + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + @acc($($acc:tt)*), + ) => { + $crate::try_init!(make_initializer : + @slot($slot), + @type_name ($t), + @munch_fields ($($rest)*), + @acc ($($acc)*$field: ::core::panic!(),), + ); + }; + (forget_guards: + @munch_fields($(,)?), + ) => { +// Munching finished. + }; + (forget_guards: + @munch_fields($field:ident <- $val:expr, $($rest:tt)*), + ) => { +unsafe { $crate::init::__internal::DropGuard ::forget ($field) }; + + $crate::try_init!(forget_guards : + @munch_fields($($rest)*), + ); + }; + (forget_guards: + @munch_fields($field:ident $(: $val:expr)?, $($rest:tt)*), + ) => { +unsafe { $crate::init::__internal::DropGuard ::forget ($field) }; + + $crate::try_init!(forget_guards : + @munch_fields($($rest)*), + ); + }; +}/// A pinned initializer for `T`. ///
@@ -60,7 +868,6 @@ use core::{convert::Infallible, marker::PhantomData, mem::MaybeUninit};/// [`Arc<T>`]: crate::sync::Arc /// [`Arc::pin_init`]: crate::sync::Arc::pin_init /// [`UniqueArc<T>`]: kernel::sync::UniqueArc -/// [`Box<T>`]: alloc::boxed::Box #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait PinInit <T : ?Sized ,E =Infallible >:Sized {/// Initializes `slot`.
@@ -103,7 +910,6 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// /// [`Arc<T>`]: crate::sync::Arc /// [`UniqueArc<T>`]: kernel::sync::UniqueArc -/// [`Box<T>`]: alloc::boxed::Box #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait Init <T : ?Sized ,E =Infallible >:PinInit <T ,E > {/// Initializes `slot`.
rust/kernel/init/__internal.rs new file +134 -0
134 lines not on this page · raw message
rust/kernel/init/macros.rs new file +707 -0
707 lines not on this page · raw message
rust/macros/lib.rs +29 -0
@@ -7,6 +7,7 @@ mod quote;mod concat_idents;mod helpers;mod module; +mod pin_data;mod vtable;use proc_macro::TokenStream ;
@@ -168,3 +169,31 @@ pub fn vtable(attr: TokenStream, ts: TokenStream) -> TokenStream {pub fn concat_idents (ts:TokenStream ) ->TokenStream { concat_idents::concat_idents (ts) } + +/// Used to specify the pinning information of the fields of a struct. +/// +/// This is somewhat similar in purpose as +/// [pin-project-lite](https://crates.io/crates/pin-project-lite). +/// Place this macro on a struct definition and then `#[pin]` in front of the attributes of each +/// field you want to structurally pin. +/// +/// This macro enables the use of the [`pin_init!`] macro. When pin-initializing a `struct`, +/// then `#[pin]` directs the type of intializer that is required. +/// +/// # Examples +/// +/// ```rust,ignore +/// #[pin_data] +/// struct DriverData { +/// #[pin] +/// queue: Mutex<Vec<Command>>, +/// buf: Box<[u8; 1024 * 1024]>, +/// } +/// ``` +/// +/// [`pin_init!`]: ../kernel/macro.pin_init.html +// ^ cannot use direct link, since `kernel` is not a dependency of `macros`. +#[proc_macro_attribute] +pub fn pin_data (inner:TokenStream , item:TokenStream ) ->TokenStream { + pin_data::pin_data (inner, item) +}
rust/macros/pin_data.rs new file +79 -0
79 lines not on this page · raw message
rust/macros/quote.rs +0 -2
@@ -38,7 +38,6 @@ impl ToTokens for TokenStream {/// This is a similar to the /// [`quote_spanned!`](https://docs.rs/quote/latest/quote/macro.quote_spanned.html) macro from the /// `quote` crate but provides only just enough functionality needed by the current `macros` crate. -#[allow(unused_macros)] macro_rules! quote_spanned { ($span:expr => $($tt:tt)*) => {#[allow(clippy::vec_init_then_push)]
@@ -137,7 +136,6 @@ macro_rules! quote_spanned {/// `macros` crate. /// /// [`Span::mixed_site()`]: https://doc.rust-lang.org/proc_macro/struct.Span.html#method.mixed_site -#[allow(unused_macros)] macro_rules! quote { ($($tt:tt)*) => {quote_spanned! (proc_macro::Span ::mixed_site () => $($tt)*)
--
2.39.2
Re: [PATCH v3 05/13] rust: init: add initialization macros
Quoted 15 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
Add the following initializer macros:
-#[pin_data]to annotate structurally pinned fields of structs, needed forpin_init!andtry_pin_init!to select the correct initializer of fields.
-pin_init!create a pin-initializer for a struct with theInfallibleerror type.
-try_pin_init!create a pin-initializer for a struct with a custom error type (kernel::error::Erroris the default).
-init!create an in-place-initializer for a struct with theInfallibleerror type.
-try_init!create an in-place-initializer for a struct with a custom error type (kernel::error::Erroris the default).
Quoted 5 lines
Also add their needed internal helper traits and structs.
Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>
Quoted 6 lines
rust/kernel/init.rs +6
-0+/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, prelude::*, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo {
rust/kernel/init.rs line 194
Quoted 10 lines
rust/kernel/init.rs +10
-0+/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar { +/// # x: u32, +/// # } +/// +/// impl Foo { +/// fn new() -> impl PinInit<Self> {
I would remove the empty line above impl Foo so that the example doesn't start with an empty line when rendered.
Quoted 7 lines
rust/kernel/init.rs +7
-0+/// # Syntax +/// +/// As already mentioned in the examples above, inside of `pin_init!` a `struct` initializer with +/// the following modifications is expected: +/// - Fields that you want to initialize in-place have to use `<-` instead of `:`. +/// - In front of the initializer you can write `&this in` to have access to a [`NonNull<Self>`] +/// pointer named `this` inside of the initializer.
rust/kernel/init.rs line 298
Quoted 10 lines
rust/kernel/init.rs +10
-0+/// +/// For instance: +/// +/// ```rust +/// # use kernel::pin_init; +/// # use macros::pin_data; +/// # use core::{ptr::addr_of_mut, marker::PhantomPinned}; +/// #[pin_data] +/// struct Buf { +/// ptr: *mut u8,
I'd add a comment on the ptr field saying "points at buf".
rust/kernel/init.rs line 362
Quoted 7 lines
rust/kernel/init.rs +7
-0+/// impl BigBuf { +/// fn new() -> impl PinInit<Self, Error> { +/// try_pin_init!(Self { +/// big: { +/// let zero = Box::try_new_zeroed()?; +/// unsafe { zero.assume_init() } +/// },
Is there a reason for not using Box::init(kernel::init::zeroed())? here?
Re: [PATCH v3 05/13] rust: init: add initialization macros
Quoted 35 lines · Alice Ryhl
Quoted 15 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
Add the following initializer macros:
-#[pin_data]to annotate structurally pinned fields of structs, needed forpin_init!andtry_pin_init!to select the correct initializer of fields.
-pin_init!create a pin-initializer for a struct with theInfallibleerror type.
-try_pin_init!create a pin-initializer for a struct with a custom error type (kernel::error::Erroris the default).
-init!create an in-place-initializer for a struct with theInfallibleerror type.
-try_init!create an in-place-initializer for a struct with a custom error type (kernel::error::Erroris the default).Quoted 5 lines
Also add their needed internal helper traits and structs.
Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Quoted 11 lines
rust/kernel/init.rs +11
-0+/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, prelude::*, init::*}; +/// # use core::pin::Pin; +/// # #[pin_data] +/// # struct Foo { +/// # a: usize, +/// # b: Bar, +/// # } +/// # #[pin_data] +/// # struct Bar {
Quoted 8 lines
rust/kernel/init.rs line 194
Quoted 5 lines
rust/kernel/init.rs +5
-0+/// # x: u32, +/// # } +/// +/// impl Foo { +/// fn new() -> impl PinInit<Self> { I would remove the empty line above
impl Fooso that the example doesn't start with an empty line when rendered.
Sure.
Quoted 12 lines
Quoted 12 lines
rust/kernel/init.rs +11
-0+/// # Syntax +/// +/// As already mentioned in the examples above, inside of `pin_init!` a `struct` initializer with +/// the following modifications is expected: +/// - Fields that you want to initialize in-place have to use `<-` instead of `:`. +/// - In front of the initializer you can write `&this in` to have access to a [`NonNull<Self>`] +/// pointer named `this` inside of the initializer. +/// +/// For instance: +/// +/// ```rust
Quoted 8 lines
rust/kernel/init.rs line 298
Quoted 6 lines
rust/kernel/init.rs +6
-0+/// # use kernel::pin_init; +/// # use macros::pin_data; +/// # use core::{ptr::addr_of_mut, marker::PhantomPinned}; +/// #[pin_data] +/// struct Buf { +/// ptr: *mut u8, I'd add a comment on the
ptrfield saying "points atbuf".
Sure.
Quoted 10 lines
rust/kernel/init.rs line 362
Quoted 8 lines
rust/kernel/init.rs +7
-0+/// impl BigBuf { +/// fn new() -> impl PinInit<Self, Error> { +/// try_pin_init!(Self { +/// big: { +/// let zero = Box::try_new_zeroed()?; +/// unsafe { zero.assume_init() } +/// }, Is there a reason for not using
Box::init(kernel::init::zeroed())?here?
No, this was probably designed prior to zeroed, will change it.
--
Cheers,
Benno
Re: [PATCH v3 05/13] rust: init: add initialization macros
In reply to [email protected]Quoted 15 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
Add the following initializer macros:
-#[pin_data]to annotate structurally pinned fields of structs, needed forpin_init!andtry_pin_init!to select the correct initializer of fields.
-pin_init!create a pin-initializer for a struct with theInfallibleerror type.
-try_pin_init!create a pin-initializer for a struct with a custom error type (kernel::error::Erroris the default).
-init!create an in-place-initializer for a struct with theInfallibleerror type.
-try_init!create an in-place-initializer for a struct with a custom error type (kernel::error::Erroris the default).
Quoted 6 lines
Also add their needed internal helper traits and structs.
Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>---
PATCH v3 6/13 rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers
In reply to [email protected]From: Benno Lossin <[email protected]>
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>.
--- rust/kernel/init.rs | 97 +++++++++++++++++++++++++++++++++++------ rust/kernel/sync/arc.rs | 25 ++++++++++- 2 files changed, 108 insertions(+), 14 deletions(-)
rust/kernel/init.rs +84 -13
@@ -114,10 +114,13 @@//! [`impl Init<T, E>`]: Init //! [`Opaque`]: kernel::types::Opaque //! [`pin_data`]: ::macros::pin_data -//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +use crate ::{ + error::{self,Error }, + sync::UniqueArc , +};use alloc::boxed::Box ; -use core::{cell::Cell , convert::Infallible , marker::PhantomData , mem::MaybeUninit , ptr}; +use core::{cell::Cell , convert::Infallible , marker::PhantomData , mem::MaybeUninit , pin::Pin , ptr};#[doc(hidden)] pub mod __internal;
@@ -309,7 +312,6 @@ pub mod macros;/// /// [`try_pin_init!`]: kernel::try_pin_init /// [`NonNull<Self>`]: core::ptr::NonNull -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export]
@@ -366,8 +368,6 @@ macro_rules! pin_init {/// } /// } /// ``` -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export]
@@ -589,8 +589,6 @@ macro_rules! try_pin_init {/// /// This initializer is for initializing data in-place that might later be moved. If you want to /// pin-initialize, use [`pin_init!`]. -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export]
@@ -641,8 +639,6 @@ macro_rules! init {/// } /// } /// ``` -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export]
@@ -848,7 +844,8 @@ macro_rules! try_init {/// A pinned initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::pin_init`] function of a +/// smart pointer like [`Arc<T>`] on this. /// /// Also see the [module description](self). ///
@@ -867,7 +864,6 @@ macro_rules! try_init {/// /// [`Arc<T>`]: crate::sync::Arc /// [`Arc::pin_init`]: crate::sync::Arc::pin_init -/// [`UniqueArc<T>`]: kernel::sync::UniqueArc #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait PinInit <T : ?Sized ,E =Infallible >:Sized {/// Initializes `slot`.
@@ -884,7 +880,8 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Because [`PinInit<T, E>`] is a super trait, you can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::init`] function of a smart +/// pointer like [`Arc<T>`] on this. Because [`PinInit<T, E>`] is a super trait, you can /// use every function that takes it as well. /// /// Also see the [module description](self).
@@ -909,7 +906,6 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// move the pointee after initialization. /// /// [`Arc<T>`]: crate::sync::Arc -/// [`UniqueArc<T>`]: kernel::sync::UniqueArc #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait Init <T : ?Sized ,E =Infallible >:PinInit <T ,E > {/// Initializes `slot`.
@@ -1014,3 +1010,78 @@ unsafe impl<T> Init<T> for T {Ok (()) } } + +/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit <T >:Sized { +/// Use the given initializer to in-place initialize a `T`. +/// +/// If `T: !Unpin` it will not be able to move afterwards. +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >; + +/// Use the given initializer to in-place initialize a `T`. +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >; +} + +impl <T >InPlaceInit <T >for Box <T > { +#[inline] +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >, + { +let mut this =Box ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid and will not be moved because of the `Pin::new_unchecked` +unsafe { init.__pinned_init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe {Pin ::new_unchecked (this.assume_init ()) }) + } + +#[inline] +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >, + { +let mut this =Box ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid +unsafe { init.__init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe { this.assume_init () }) + } +} + +impl <T >InPlaceInit <T >for UniqueArc <T > { +#[inline] +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >, + { +let mut this =UniqueArc ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid and will not be moved because of the `Pin::new_unchecked`. +unsafe { init.__pinned_init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe {Pin ::new_unchecked (this.assume_init ()) }) + } + +#[inline] +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >, + { +let mut this =UniqueArc ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid. +unsafe { init.__init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe { this.assume_init () }) + } +}
rust/kernel/sync/arc.rs +24 -1
@@ -17,7 +17,8 @@use crate ::{ bindings, - error::Result , + error::{Error ,Result }, + init::{InPlaceInit ,Init ,PinInit }, types::{ForeignOwnable ,Opaque }, };use alloc::boxed::Box ;
@@ -163,6 +164,28 @@ impl<T> Arc<T> {// `Arc` object. Ok (unsafe {Self ::from_inner (Box ::leak (inner).into ()) }) } + +/// Use the given initializer to in-place initialize a `T`. +/// +/// If `T: !Unpin` it will not be able to move afterwards. +#[inline] +pub fn pin_init <E >(init:impl PinInit <T ,E >) ->Result <Self > +where +Error :From <E >, + { +UniqueArc ::pin_init (init).map (|u| u.into ()) + } + +/// Use the given initializer to in-place initialize a `T`. +/// +/// This is equivalent to [`pin_init`], since an [`Arc`] is always pinned. +#[inline] +pub fn init <E >(init:impl Init <T ,E >) ->Result <Self > +where +Error :From <E >, + { +UniqueArc ::init (init).map (|u| u.into ()) + } }impl <T : ?Sized >Arc <T > {
--
2.39.2
Gary Guo
maintainerRe: [PATCH v3 06/13] rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers
Quoted 126 lines · On Wed, 29 Mar 2023 22:33:18 +0000 [email protected] wrote:
From: Benno Lossin <[email protected]>
The
InPlaceInittrait that provides two functions, for initializing usingPinInit<T, E>andInit<T>. It is implemented byArc<T>,UniqueArc<T>andBox<T>.Signed-off-by Benno Lossin <[email protected]>--- rust/kernel/init.rs | 97 +++++++++++++++++++++++++++++++++++------ rust/kernel/sync/arc.rs | 25 ++++++++++- 2 files changed, 108 insertions(+), 14 deletions(-)rust/kernel/init.rs +28
-13@@ -114,10 +114,13 @@//! [`impl Init<T, E>`]: Init //! [`Opaque`]: kernel::types::Opaque //! [`pin_data`]: ::macros::pin_data -//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +use crate ::{ + error::{self,Error }, + sync::UniqueArc , +};use alloc::boxed::Box ; -use core::{cell::Cell , convert::Infallible , marker::PhantomData , mem::MaybeUninit , ptr}; +use core::{cell::Cell , convert::Infallible , marker::PhantomData , mem::MaybeUninit , pin::Pin , ptr};#[doc(hidden)] pub mod __internal;@@ -309,7 +312,6 @@ pub mod macros;/// /// [`try_pin_init!`]: kernel::try_pin_init /// [`NonNull<Self>`]: core::ptr::NonNull -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -366,8 +368,6 @@ macro_rules! pin_init {/// } /// } /// ``` -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -589,8 +589,6 @@ macro_rules! try_pin_init {/// /// This initializer is for initializing data in-place that might later be moved. If you want to /// pin-initialize, use [`pin_init!`]. -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -641,8 +639,6 @@ macro_rules! init {/// } /// } /// ``` -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -848,7 +844,8 @@ macro_rules! try_init {/// A pinned initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::pin_init`] function of a +/// smart pointer like [`Arc<T>`] on this. /// /// Also see the [module description](self). /// @@ -867,7 +864,6 @@ macro_rules! try_init {/// /// [`Arc<T>`]: crate::sync::Arc /// [`Arc::pin_init`]: crate::sync::Arc::pin_init -/// [`UniqueArc<T>`]: kernel::sync::UniqueArc #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait PinInit <T : ?Sized ,E =Infallible >:Sized {/// Initializes `slot`. @@ -884,7 +880,8 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Because [`PinInit<T, E>`] is a super trait, you can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::init`] function of a smart +/// pointer like [`Arc<T>`] on this. Because [`PinInit<T, E>`] is a super trait, you can /// use every function that takes it as well. /// /// Also see the [module description](self). @@ -909,7 +906,6 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// move the pointee after initialization. /// /// [`Arc<T>`]: crate::sync::Arc -/// [`UniqueArc<T>`]: kernel::sync::UniqueArc #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait Init <T : ?Sized ,E =Infallible >:PinInit <T ,E > {/// Initializes `slot`. @@ -1014,3 +1010,78 @@ unsafe impl<T> Init<T> for T {Ok (()) } } + +/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit <T >:Sized { +/// Use the given initializer to in-place initialize a `T`. +/// +/// If `T: !Unpin` it will not be able to move afterwards. +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >; + +/// Use the given initializer to in-place initialize a `T`. +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >; +} + +impl <T >InPlaceInit <T >for Box <T > { +#[inline] +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >>
rust/kernel/init.rs unsafe impl<T> Init<T> for T { · line 1041
Quoted 10 lines
rust/kernel/init.rs +10
-0+ where + Error: From<E>, + { +let mut this =Box ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid and will not be moved because of the `Pin::new_unchecked` +unsafe { init.__pinned_init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe {Pin ::new_unchecked (this.assume_init ()) })
This can be either Box::into_pin or just into().
Quoted 16 lines
rust/kernel/init.rs +16
-0+ } + +#[inline] +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >, + { +let mut this =Box ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid +unsafe { init.__init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe { this.assume_init () }) + } +}
Re: [PATCH v3 06/13] rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers
In reply to [email protected]Quoted 8 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
The
InPlaceInittrait that provides two functions, for initializing usingPinInit<T, E>andInit<T>. It is implemented byArc<T>,UniqueArc<T>andBox<T>.Signed-off-by Benno Lossin <[email protected]>---
Quoted 217 lines
rust/kernel/init.rs | 97 +++++++++++++++++++++++++++++++++++------ rust/kernel/sync/arc.rs | 25 ++++++++++- 2 files changed, 108 insertions(+), 14 deletions(-)rust/kernel/init.rs +84
-13@@ -114,10 +114,13 @@//! [`impl Init<T, E>`]: Init //! [`Opaque`]: kernel::types::Opaque //! [`pin_data`]: ::macros::pin_data -//! [`UniqueArc<T>`]: kernel::sync::UniqueArc +use crate ::{ + error::{self,Error }, + sync::UniqueArc , +};use alloc::boxed::Box ; -use core::{cell::Cell , convert::Infallible , marker::PhantomData , mem::MaybeUninit , ptr}; +use core::{cell::Cell , convert::Infallible , marker::PhantomData , mem::MaybeUninit , pin::Pin , ptr};#[doc(hidden)] pub mod __internal;@@ -309,7 +312,6 @@ pub mod macros;/// /// [`try_pin_init!`]: kernel::try_pin_init /// [`NonNull<Self>`]: core::ptr::NonNull -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -366,8 +368,6 @@ macro_rules! pin_init {/// } /// } /// ``` -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -589,8 +589,6 @@ macro_rules! try_pin_init {/// /// This initializer is for initializing data in-place that might later be moved. If you want to /// pin-initialize, use [`pin_init!`]. -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -641,8 +639,6 @@ macro_rules! init {/// } /// } /// ``` -/// -/// [`Error`]: kernel::error::Error // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. #[macro_export] @@ -848,7 +844,8 @@ macro_rules! try_init {/// A pinned initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::pin_init`] function of a +/// smart pointer like [`Arc<T>`] on this. /// /// Also see the [module description](self). /// @@ -867,7 +864,6 @@ macro_rules! try_init {/// /// [`Arc<T>`]: crate::sync::Arc /// [`Arc::pin_init`]: crate::sync::Arc::pin_init -/// [`UniqueArc<T>`]: kernel::sync::UniqueArc #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait PinInit <T : ?Sized ,E =Infallible >:Sized {/// Initializes `slot`. @@ -884,7 +880,8 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Because [`PinInit<T, E>`] is a super trait, you can +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::init`] function of a smart +/// pointer like [`Arc<T>`] on this. Because [`PinInit<T, E>`] is a super trait, you can /// use every function that takes it as well. /// /// Also see the [module description](self). @@ -909,7 +906,6 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// move the pointee after initialization. /// /// [`Arc<T>`]: crate::sync::Arc -/// [`UniqueArc<T>`]: kernel::sync::UniqueArc #[must_use = "An initializer must be used in order to create its value." ] pub unsafe trait Init <T : ?Sized ,E =Infallible >:PinInit <T ,E > {/// Initializes `slot`. @@ -1014,3 +1010,78 @@ unsafe impl<T> Init<T> for T {Ok (()) } } + +/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit <T >:Sized { +/// Use the given initializer to in-place initialize a `T`. +/// +/// If `T: !Unpin` it will not be able to move afterwards. +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >; + +/// Use the given initializer to in-place initialize a `T`. +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >; +} + +impl <T >InPlaceInit <T >for Box <T > { +#[inline] +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >, + { +let mut this =Box ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid and will not be moved because of the `Pin::new_unchecked` +unsafe { init.__pinned_init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe {Pin ::new_unchecked (this.assume_init ()) }) + } + +#[inline] +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >, + { +let mut this =Box ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid +unsafe { init.__init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe { this.assume_init () }) + } +} + +impl <T >InPlaceInit <T >for UniqueArc <T > { +#[inline] +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >, + { +let mut this =UniqueArc ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid and will not be moved because of the `Pin::new_unchecked`. +unsafe { init.__pinned_init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe {Pin ::new_unchecked (this.assume_init ()) }) + } + +#[inline] +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >, + { +let mut this =UniqueArc ::try_new_uninit ()?; +let slot = this.as_mut_ptr (); +// SAFETY: When init errors/panics, slot will get deallocated but not dropped, +// slot is valid. +unsafe { init.__init (slot)? }; +// SAFETY: All fields have been initialized. +Ok (unsafe { this.assume_init () }) + } +}rust/kernel/sync/arc.rs +24
-1@@ -17,7 +17,8 @@use crate ::{ bindings, - error::Result , + error::{Error ,Result }, + init::{InPlaceInit ,Init ,PinInit }, types::{ForeignOwnable ,Opaque }, };use alloc::boxed::Box ;@@ -163,6 +164,28 @@ impl<T> Arc<T> {// `Arc` object. Ok (unsafe {Self ::from_inner (Box ::leak (inner).into ()) }) } + +/// Use the given initializer to in-place initialize a `T`. +/// +/// If `T: !Unpin` it will not be able to move afterwards. +#[inline] +pub fn pin_init <E >(init:impl PinInit <T ,E >) ->Result <Self > +where +Error :From <E >, + { +UniqueArc ::pin_init (init).map (|u| u.into ()) + } + +/// Use the given initializer to in-place initialize a `T`. +/// +/// This is equivalent to [`pin_init`], since an [`Arc`] is always pinned. +#[inline] +pub fn init <E >(init:impl Init <T ,E >) ->Result <Self > +where +Error :From <E >, + { +UniqueArc ::init (init).map (|u| u.into ()) + } }impl <T : ?Sized >Arc <T > {
Re: [PATCH v3 06/13] rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers
In reply to [email protected]Quoted 13 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
The
InPlaceInittrait that provides two functions, for initializing usingPinInit<T, E>andInit<T>. It is implemented byArc<T>,UniqueArc<T>andBox<T>.Signed-off-by Benno Lossin <[email protected]>---
rust/kernel/init.rs +4
-0+/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit <T >:Sized { +/// Use the given initializer to in-place initialize a `T`. +///
rust/kernel/init.rs unsafe impl<T> Init<T> for T { · line 1027
Quoted 10 lines
rust/kernel/init.rs +10
-0+/// If `T: !Unpin` it will not be able to move afterwards. +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >; + +/// Use the given initializer to in-place initialize a `T`. +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >; +}
This definition is potentially rather limiting, because it can only be used with error types that can be converted into a kernel::Error. What do you think of this alternative?
pub trait InPlaceInit<T>: Sized {
fn pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>
where
E: From<AllocError>;
fn init<E>(init: impl Init<T, E>) -> Result<Self, E>
where
E: From<AllocError>;
}Re: [PATCH v3 06/13] rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers
Quoted 29 lines · Alice Ryhl
Quoted 13 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
The
InPlaceInittrait that provides two functions, for initializing usingPinInit<T, E>andInit<T>. It is implemented byArc<T>,UniqueArc<T>andBox<T>.Signed-off-by Benno Lossin <[email protected]>---
rust/kernel/init.rs +4
-0+/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit <T >:Sized { +/// Use the given initializer to in-place initialize a `T`. +/// rust/kernel/init.rs unsafe impl<T> Init<T> for T { · line 1027
Quoted 10 lines
rust/kernel/init.rs +10
-0+/// If `T: !Unpin` it will not be able to move afterwards. +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >; + +/// Use the given initializer to in-place initialize a `T`. +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >; +}This definition is potentially rather limiting, because it can only be used with error types that can be converted into a
kernel::Error. What do you think of this alternative?
Quoted 9 lines
pub trait InPlaceInit<T>: Sized {
fn pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>
where
E: From<AllocError>;
fn init<E>(init: impl Init<T, E>) -> Result<Self, E>
where
E: From<AllocError>;
}I initially implemented it like this, but it required almost always that E is specified, I will try and see if the situation is any different now, but I do not think so. In the user-space version of this API (see [1]) I have four functions, normal variants that return an AllocError and try variants that look exactly like what you suggested. In the kernel, we could make the normal variants as they are now and add the try variants as you described.
[1]: https://docs.rs/pinned-init/0.0.5/pinned_init/trait.InPlaceInit.html
--
Cheers,
Benno
Alice Ryhl
Reviewed-byRe: [PATCH v3 06/13] rust: init/sync: add `InPlaceInit` trait to pin-initialize smart pointers
Quoted 48 lines · Benno Lossin
Quoted 29 lines · Alice Ryhl
Quoted 13 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
The
InPlaceInittrait that provides two functions, for initializing usingPinInit<T, E>andInit<T>. It is implemented byArc<T>,UniqueArc<T>andBox<T>.Signed-off-by Benno Lossin <[email protected]>---
rust/kernel/init.rs +4
-0+/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit <T >:Sized { +/// Use the given initializer to in-place initialize a `T`. +/// rust/kernel/init.rs unsafe impl<T> Init<T> for T { · line 1027
Quoted 10 lines
rust/kernel/init.rs +10
-0+/// If `T: !Unpin` it will not be able to move afterwards. +fn pin_init <E >(init:impl PinInit <T ,E >) -> error::Result <Pin <Self >> +where +Error :From <E >; + +/// Use the given initializer to in-place initialize a `T`. +fn init <E >(init:impl Init <T ,E >) -> error::Result <Self > +where +Error :From <E >; +}This definition is potentially rather limiting, because it can only be used with error types that can be converted into a
kernel::Error. What do you think of this alternative?Quoted 9 lines
pub trait InPlaceInit<T>: Sized { fn pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E> where E: From<AllocError>; fn init<E>(init: impl Init<T, E>) -> Result<Self, E> where E: From<AllocError>; }I initially implemented it like this, but it required almost always that
Eis specified, I will try and see if the situation is any different now, but I do not think so. In the user-space version of this API (see [1]) I have four functions, normal variants that return anAllocErrorandtryvariants that look exactly like what you suggested. In the kernel, we could make the normal variants as they are now and add thetryvariants as you described.
Quoted 5 lines
[1]: https://docs.rs/pinned-init/0.0.5/pinned_init/trait.InPlaceInit.html
--
Cheers,
Benno
Ok, if my alternative causes type inference problems, then let us keep the version you proposed here. We can add more variants later. (Or if you want to add more now, that's also fine.)
PATCH v3 7/13 rust: init: add `PinnedDrop` trait and macros
In reply to [email protected]From: Benno Lossin <[email protected]>
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)].
--- rust/kernel/init.rs | 111 ++++++++++++++ rust/kernel/init/__internal.rs | 15 ++ rust/kernel/init/macros.rs | 263 +++++++++++++++++++++++++++++++++ rust/macros/lib.rs | 49 ++++++ rust/macros/pinned_drop.rs | 49 ++++++ 5 files changed, 487 insertions(+) create mode 100644 rust/macros/pinned_drop.rs
rust/kernel/init.rs +111 -0
@@ -104,6 +104,78 @@//! } //! ``` //! +//! ## Manual creation of an initializer +//! +//! Often when working with primitives the previous approaches are not sufficient. That is where +//! [`pin_init_from_closure()`] comes in. This `unsafe` function allows you to create a +//! [`impl PinInit<T, E>`] directly from a closure. Of course you have to ensure that the closure +//! actually does the initialization in the correct way. Here are the things to look out for +//! (we are calling the parameter to the closure `slot`): +//! - when the closure returns `Ok(())`, then it has completed the initialization successfully, so +//! `slot` now contains a valid bit pattern for the type `T`, +//! - when the closure returns `Err(e)`, then the caller may deallocate the memory at `slot`, so +//! you need to take care to clean up anything if your initialization fails mid-way, +//! - you may assume that `slot` will stay pinned even after the closure returns until `drop` of +//! `slot` gets called. +//! +//! ```rust +//! use kernel::{prelude::*, init}; +//! use core::{ptr::addr_of_mut, marker::PhantomPinned}; +//! # mod bindings { +//! # pub struct foo; +//! # pub unsafe fn init_foo(_ptr: *mut foo) {} +//! # pub unsafe fn destroy_foo(_ptr: *mut foo) {} +//! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 } +//! # } +//! /// # Invariants +//! /// +//! /// `foo` is always initialized +//! #[pin_data(PinnedDrop)] +//! pub struct RawFoo { +//! #[pin] +//! foo: Opaque<bindings::foo>, +//! #[pin] +//! _p: PhantomPinned, +//! } +//! +//! impl RawFoo { +//! pub fn new(flags: u32) -> impl PinInit<Self, Error> { +//! // SAFETY: +//! // - when the closure returns `Ok(())`, then it has successfully initialized and +//! // enabled `foo`, +//! // - when it returns `Err(e)`, then it has cleaned up before +//! unsafe { +//! init::pin_init_from_closure(move |slot: *mut Self| { +//! // `slot` contains uninit memory, avoid creating a reference. +//! let foo = addr_of_mut!((*slot).foo); +//! +//! // Initialize the `foo` +//! bindings::init_foo(Opaque::raw_get(foo)); +//! +//! // Try to enable it. +//! let err = bindings::enable_foo(Opaque::raw_get(foo), flags); +//! if err != 0 { +//! // Enabling has failed, first clean up the foo and then return the error. +//! bindings::destroy_foo(Opaque::raw_get(foo)); +//! return Err(Error::from_kernel_errno(err)); +//! } +//! +//! // All fields of `RawFoo` have been initialized, since `_p` is a ZST. +//! Ok(()) +//! }) +//! } +//! } +//! } +//! +//! #[pinned_drop] +//! impl PinnedDrop for RawFoo { +//! fn drop(self: Pin<&mut Self>) { +//! // SAFETY: Since `foo` is initialized, destroying is safe. +//! unsafe { bindings::destroy_foo(self.foo.get()) }; +//! } +//! } +//! ``` +//! //! [`sync`]: kernel::sync //! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]:
@@ -1085,3 +1157,42 @@ impl<T> InPlaceInit<T> for UniqueArc<T> {Ok (unsafe { this.assume_init () }) } } + +/// Trait facilitating pinned destruction. +/// +/// Use [`pinned_drop`] to implement this trait safely: +/// +/// ```rust +/// # use kernel::sync::Mutex; +/// use kernel::macros::pinned_drop; +/// use core::pin::Pin; +/// #[pin_data(PinnedDrop)] +/// struct Foo { +/// #[pin] +/// mtx: Mutex<usize>, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for Foo { +/// fn drop(self: Pin<&mut Self>) { +/// pr_info!("Foo is being dropped!"); +/// } +/// } +/// ``` +/// +/// # Safety +/// +/// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl. +/// +/// [`pinned_drop`]: kernel::macros::pinned_drop +pub unsafe trait PinnedDrop : __internal::HasPinData { +/// Executes the pinned destructor of this type. +/// +/// While this function is marked safe, it is actually unsafe to call it manually. For this +/// reason it takes an additional parameter. This type can only be constructed by `unsafe` code +/// and thus prevents this function from being called where it should not. +/// +/// This extra parameter will be generated by the `#[pinned_drop]` proc-macro attribute +/// automatically. +fn drop (self:Pin <&mut Self >, only_call_from_drop: __internal::OnlyCallFromDrop ); +}
rust/kernel/init/__internal.rs +15 -0
@@ -132,3 +132,18 @@ impl<T: ?Sized> Drop for DropGuard<T> { } } } + +/// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely +/// created struct. This is needed, because the `drop` function is safe, but should not be called +/// manually. +pub struct OnlyCallFromDrop (()); + +impl OnlyCallFromDrop { +/// # Safety +/// +/// This function should only be called from the [`Drop::drop`] function and only be used to +/// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type. +pub unsafe fn create () ->Self { +Self (()) + } +}
rust/kernel/init/macros.rs +263 -0
287 lines not on this page · raw message
rust/macros/lib.rs +49 -0
70 lines not on this page · raw message
rust/macros/pinned_drop.rs new file +49 -0
49 lines not on this page · raw message
--
2.39.2
Gary Guo
maintainerRe: [PATCH v3 07/13] rust: init: add `PinnedDrop` trait and macros
Quoted 30 lines · On Wed, 29 Mar 2023 22:33:24 +0000 [email protected] wrote:
From: Benno Lossin <[email protected]>
The
PinnedDroptrait that facilitates destruction of pinned types. It has to be implemented via the#[pinned_drop]macro, since thedropfunction 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 <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>--- rust/kernel/init.rs | 111 ++++++++++++++ rust/kernel/init/__internal.rs | 15 ++ rust/kernel/init/macros.rs | 263 +++++++++++++++++++++++++++++++++ rust/macros/lib.rs | 49 ++++++ rust/macros/pinned_drop.rs | 49 ++++++ 5 files changed, 487 insertions(+) create mode 100644 rust/macros/pinned_drop.rsrust/kernel/init/__internal.rs +2
-0@@ -132,3 +132,18 @@ impl<T: ?Sized> Drop for DropGuard<T> { } } } + +/// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely
rust/kernel/init/__internal.rs impl<T: ?Sized> Drop for DropGuard<T> { · line 146
Quoted 10 lines
rust/kernel/init/__internal.rs +10
-0+/// created struct. This is needed, because the `drop` function is safe, but should not be called +/// manually. +pub struct OnlyCallFromDrop (()); + +impl OnlyCallFromDrop { +/// # Safety +/// +/// This function should only be called from the [`Drop::drop`] function and only be used to +/// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type. +pub unsafe fn create () ->Self {
Although this is impl detail and the name doesn't really matter, but I am wondering why this is called create instead of just new.
Quoted 3 lines
rust/kernel/init/__internal.rs +3
-0+Self (()) + } +}
Re: [PATCH v3 07/13] rust: init: add `PinnedDrop` trait and macros
Quoted 38 lines · Gary Guo
Quoted 35 lines · On Wed, 29 Mar 2023 22:33:24 +0000 [email protected] wrote:
From: Benno Lossin <[email protected]>
The
PinnedDroptrait that facilitates destruction of pinned types. It has to be implemented via the#[pinned_drop]macro, since thedropfunction 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 <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>--- rust/kernel/init.rs | 111 ++++++++++++++ rust/kernel/init/__internal.rs | 15 ++ rust/kernel/init/macros.rs | 263 +++++++++++++++++++++++++++++++++ rust/macros/lib.rs | 49 ++++++ rust/macros/pinned_drop.rs | 49 ++++++ 5 files changed, 487 insertions(+)create mode 100644
rust/macros/pinned_drop.rsrust/kernel/init/__internal.rs +7
-0@@ -132,3 +132,18 @@ impl<T: ?Sized> Drop for DropGuard<T> { } } } + +/// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely +/// created struct. This is needed, because the `drop` function is safe, but should not be called +/// manually. +pub struct OnlyCallFromDrop (()); + +impl OnlyCallFromDrop {
Quoted 8 lines
rust/kernel/init/__internal.rs impl<T: ?Sized> Drop for DropGuard<T> { · line 146
Quoted 5 lines
rust/kernel/init/__internal.rs +5
-0+/// # Safety +/// +/// This function should only be called from the [`Drop::drop`] function and only be used to +/// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type. +pub unsafe fn create () ->Self {Although this is impl detail and the name doesn't really matter, but I am wondering why this is called
createinstead of justnew.
Not really a good reason, I associate new() with 'unburdened' creation (i.e. a safe function). Will change this.
--
Cheers,
Benno
Quoted 4 lines
Quoted 4 lines
rust/kernel/init/__internal.rs +3
-0+Self (()) + } +}
Re: [PATCH v3 07/13] rust: init: add `PinnedDrop` trait and macros
In reply to [email protected]Quoted 11 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
The
PinnedDroptrait that facilitates destruction of pinned types. It has to be implemented via the#[pinned_drop]macro, since thedropfunction 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 <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>
I noticed the same thing as Gary with the name create, but otherwise LGTM.
Re: [PATCH v3 07/13] rust: init: add `PinnedDrop` trait and macros
In reply to [email protected]Quoted 8 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
The
PinnedDroptrait that facilitates destruction of pinned types. It has to be implemented via the#[pinned_drop]macro, since thedropfunction should not be called by normal code, only by other destructors. It also only works on structs that are annotated with#[pin_data(PinnedDrop)].
Quoted 4 lines
Co-developed-by Gary Guo <[email protected]>Signed-off-by Gary Guo <[email protected]>Signed-off-by Benno Lossin <[email protected]>---
Quoted 584 lines
rust/kernel/init.rs | 111 ++++++++++++++ rust/kernel/init/__internal.rs | 15 ++ rust/kernel/init/macros.rs | 263 +++++++++++++++++++++++++++++++++ rust/macros/lib.rs | 49 ++++++ rust/macros/pinned_drop.rs | 49 ++++++ 5 files changed, 487 insertions(+) create mode 100644 rust/macros/pinned_drop.rsrust/kernel/init.rs +111
-0@@ -104,6 +104,78 @@//! } //! ``` //! +//! ## Manual creation of an initializer +//! +//! Often when working with primitives the previous approaches are not sufficient. That is where +//! [`pin_init_from_closure()`] comes in. This `unsafe` function allows you to create a +//! [`impl PinInit<T, E>`] directly from a closure. Of course you have to ensure that the closure +//! actually does the initialization in the correct way. Here are the things to look out for +//! (we are calling the parameter to the closure `slot`): +//! - when the closure returns `Ok(())`, then it has completed the initialization successfully, so +//! `slot` now contains a valid bit pattern for the type `T`, +//! - when the closure returns `Err(e)`, then the caller may deallocate the memory at `slot`, so +//! you need to take care to clean up anything if your initialization fails mid-way, +//! - you may assume that `slot` will stay pinned even after the closure returns until `drop` of +//! `slot` gets called. +//! +//! ```rust +//! use kernel::{prelude::*, init}; +//! use core::{ptr::addr_of_mut, marker::PhantomPinned}; +//! # mod bindings { +//! # pub struct foo; +//! # pub unsafe fn init_foo(_ptr: *mut foo) {} +//! # pub unsafe fn destroy_foo(_ptr: *mut foo) {} +//! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 } +//! # } +//! /// # Invariants +//! /// +//! /// `foo` is always initialized +//! #[pin_data(PinnedDrop)] +//! pub struct RawFoo { +//! #[pin] +//! foo: Opaque<bindings::foo>, +//! #[pin] +//! _p: PhantomPinned, +//! } +//! +//! impl RawFoo { +//! pub fn new(flags: u32) -> impl PinInit<Self, Error> { +//! // SAFETY: +//! // - when the closure returns `Ok(())`, then it has successfully initialized and +//! // enabled `foo`, +//! // - when it returns `Err(e)`, then it has cleaned up before +//! unsafe { +//! init::pin_init_from_closure(move |slot: *mut Self| { +//! // `slot` contains uninit memory, avoid creating a reference. +//! let foo = addr_of_mut!((*slot).foo); +//! +//! // Initialize the `foo` +//! bindings::init_foo(Opaque::raw_get(foo)); +//! +//! // Try to enable it. +//! let err = bindings::enable_foo(Opaque::raw_get(foo), flags); +//! if err != 0 { +//! // Enabling has failed, first clean up the foo and then return the error. +//! bindings::destroy_foo(Opaque::raw_get(foo)); +//! return Err(Error::from_kernel_errno(err)); +//! } +//! +//! // All fields of `RawFoo` have been initialized, since `_p` is a ZST. +//! Ok(()) +//! }) +//! } +//! } +//! } +//! +//! #[pinned_drop] +//! impl PinnedDrop for RawFoo { +//! fn drop(self: Pin<&mut Self>) { +//! // SAFETY: Since `foo` is initialized, destroying is safe. +//! unsafe { bindings::destroy_foo(self.foo.get()) }; +//! } +//! } +//! ``` +//! //! [`sync`]: kernel::sync //! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]: @@ -1085,3 +1157,42 @@ impl<T> InPlaceInit<T> for UniqueArc<T> {Ok (unsafe { this.assume_init () }) } } + +/// Trait facilitating pinned destruction. +/// +/// Use [`pinned_drop`] to implement this trait safely: +/// +/// ```rust +/// # use kernel::sync::Mutex; +/// use kernel::macros::pinned_drop; +/// use core::pin::Pin; +/// #[pin_data(PinnedDrop)] +/// struct Foo { +/// #[pin] +/// mtx: Mutex<usize>, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for Foo { +/// fn drop(self: Pin<&mut Self>) { +/// pr_info!("Foo is being dropped!"); +/// } +/// } +/// ``` +/// +/// # Safety +/// +/// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl. +/// +/// [`pinned_drop`]: kernel::macros::pinned_drop +pub unsafe trait PinnedDrop : __internal::HasPinData { +/// Executes the pinned destructor of this type. +/// +/// While this function is marked safe, it is actually unsafe to call it manually. For this +/// reason it takes an additional parameter. This type can only be constructed by `unsafe` code +/// and thus prevents this function from being called where it should not. +/// +/// This extra parameter will be generated by the `#[pinned_drop]` proc-macro attribute +/// automatically. +fn drop (self:Pin <&mut Self >, only_call_from_drop: __internal::OnlyCallFromDrop ); +}rust/kernel/init/__internal.rs +15
-0@@ -132,3 +132,18 @@ impl<T: ?Sized> Drop for DropGuard<T> { } } } + +/// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely +/// created struct. This is needed, because the `drop` function is safe, but should not be called +/// manually. +pub struct OnlyCallFromDrop (()); + +impl OnlyCallFromDrop { +/// # Safety +/// +/// This function should only be called from the [`Drop::drop`] function and only be used to +/// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type. +pub unsafe fn create () ->Self { +Self (()) + } +}rust/kernel/init/macros.rs +263
-0@@ -31,6 +31,26 @@//! pin_init!(Self { t, x: 0 }) //! } //! } +//! +//! #[pin_data(PinnedDrop)] +//! struct Foo { +//! a: usize, +//! #[pin] +//! b: Bar<u32>, +//! } +//! +//! #[pinned_drop] +//! impl PinnedDrop for Foo { +//! fn drop(self: Pin<&mut Self>) { +//! println!("{self:p} is getting dropped."); +//! } +//! } +//! +//! let a = 42; +//! let initializer = pin_init!(Foo { +//! a, +//! b <- Bar::new(36), +//! }); //! ``` //! //! This example includes the most common and important features of the pin-init API. @@ -155,6 +175,14 @@//! #[allow(drop_bounds)] //! impl<T: ::core::ops::Drop> MustNotImplDrop for T {} //! impl<T> MustNotImplDrop for Bar<T> {} +//! // Here comes a convenience check, if one implemented `PinnedDrop`, but forgot to add it to +//! // `#[pin_data]`, then this will error with the same mechanic as above, this is not needed +//! // for safety, but a good sanity check, since no normal code calls `PinnedDrop::drop`. +//! #[allow(non_camel_case_types)] +//! trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {} +//! impl<T: ::pinned_init::PinnedDrop> +//! UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {} +//! impl<T> UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for Bar<T> {} //! }; //! ``` //! @@ -265,6 +293,209 @@//! } //! } //! ``` +//! +//! ## `#[pin_data]` on `Foo` +//! +//! Since we already took a look at `#[pin_data]` on `Bar`, this section will only explain the +//! differences/new things in the expansion of the `Foo` definition: +//! +//! ```rust +//! #[pin_data(PinnedDrop)] +//! struct Foo { +//! a: usize, +//! #[pin] +//! b: Bar<u32>, +//! } +//! ``` +//! +//! This expands to the following code: +//! +//! ```rust +//! struct Foo { +//! a: usize, +//! b: Bar<u32>, +//! } +//! const _: () = { +//! struct __ThePinData { +//! __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>, +//! } +//! impl ::core::clone::Clone for __ThePinData { +//! fn clone(&self) -> Self { +//! *self +//! } +//! } +//! impl ::core::marker::Copy for __ThePinData {} +//! #[allow(dead_code)] +//! impl __ThePinData { +//! unsafe fn b<E>( +//! self, +//! slot: *mut Bar<u32>, +//! // Note that this is `PinInit` instead of `Init`, this is because `b` is +//! // structurally pinned, as marked by the `#[pin]` attribute. +//! init: impl ::pinned_init::PinInit<Bar<u32>, E>, +//! ) -> ::core::result::Result<(), E> { +//! unsafe { ::pinned_init::PinInit::__pinned_init(init, slot) } +//! } +//! unsafe fn a<E>( +//! self, +//! slot: *mut usize, +//! init: impl ::pinned_init::Init<usize, E>, +//! ) -> ::core::result::Result<(), E> { +//! unsafe { ::pinned_init::Init::__init(init, slot) } +//! } +//! } +//! unsafe impl ::pinned_init::__internal::HasPinData for Foo { +//! type PinData = __ThePinData; +//! unsafe fn __pin_data() -> Self::PinData { +//! __ThePinData { +//! __phantom: ::core::marker::PhantomData, +//! } +//! } +//! } +//! unsafe impl ::pinned_init::__internal::PinData for __ThePinData { +//! type Datee = Foo; +//! } +//! #[allow(dead_code)] +//! struct __Unpin<'__pin> { +//! __phantom_pin: ::core::marker::PhantomData<fn(&'__pin ()) -> &'__pin ()>, +//! __phantom: ::core::marker::PhantomData<fn(Foo) -> Foo>, +//! // Since this field is `#[pin]`, it is listed here. +//! b: Bar<u32>, +//! } +//! #[doc(hidden)] +//! impl<'__pin> ::core::marker::Unpin for Foo where __Unpin<'__pin>: ::core::marker::Unpin {} +//! // Since we specified `PinnedDrop` as the argument to `#[pin_data]`, we expect `Foo` to +//! // implement `PinnedDrop`. Thus we do not need to prevent `Drop` implementations like +//! // before, instead we implement it here and delegate to `PinnedDrop`. +//! impl ::core::ops::Drop for Foo { +//! fn drop(&mut self) { +//! // Since we are getting dropped, no one else has a reference to `self` and thus we +//! // can assume that we never move. +//! let pinned = unsafe { ::core::pin::Pin::new_unchecked(self) }; +//! // Create the unsafe token that proves that we are inside of a destructor, this +//! // type is only allowed to be created in a destructor. +//! let token = unsafe { ::pinned_init::__internal::OnlyCallFromDrop::create() }; +//! ::pinned_init::PinnedDrop::drop(pinned, token); +//! } +//! } +//! }; +//! ``` +//! +//! ## `#[pinned_drop]` on `impl PinnedDrop for Foo` +//! +//! This macro is used to implement the `PinnedDrop` trait, since that trait is `unsafe` and has an +//! extra parameter that should not be used at all. The macro hides that parameter. +//! +//! Here is the `PinnedDrop` impl for `Foo`: +//! +//! ```rust +//! #[pinned_drop] +//! impl PinnedDrop for Foo { +//! fn drop(self: Pin<&mut Self>) { +//! println!("{self:p} is getting dropped."); +//! } +//! } +//! ``` +//! +//! This expands to the following code: +//! +//! ```rust +//! // `unsafe`, full path and the token parameter are added, everything else stays the same. +//! unsafe impl ::pinned_init::PinnedDrop for Foo { +//! fn drop(self: Pin<&mut Self>, _: ::pinned_init::__internal::OnlyCallFromDrop) { +//! println!("{self:p} is getting dropped."); +//! } +//! } +//! ``` +//! +//! ## `pin_init!` on `Foo` +//! +//! Since we already took a look at `pin_init!` on `Bar`, this section will only explain the +//! differences/new things in the expansion of `pin_init!` on `Foo`: +//! +//! ```rust +//! let a = 42; +//! let initializer = pin_init!(Foo { +//! a, +//! b <- Bar::new(36), +//! }); +//! ``` +//! +//! This expands to the following code: +//! +//! ```rust +//! let a = 42; +//! let initializer = { +//! struct __InitOk; +//! let data = unsafe { +//! use pinned_init::__internal::HasPinData; +//! Foo::__pin_data() +//! }; +//! let init = ::pinned_init::__internal::PinData::make_closure::< +//! _, +//! __InitOk, +//! ::core::convert::Infallible, +//! >(data, move |slot| { +//! { +//! struct __InitOk; +//! unsafe { ::core::ptr::write(&raw mut (*slot).a, a) }; +//! let a = &unsafe { ::pinned_init::__internal::DropGuard::new(&raw mut (*slot).a) }; +//! let b = Bar::new(36); +//! // Here we use `data` to access the correct field and require that `b` is of type +//! // `PinInit<Bar<u32>, Infallible>`. +//! unsafe { data.b(&raw mut (*slot).b, b)? }; +//! let b = &unsafe { ::pinned_init::__internal::DropGuard::new(&raw mut (*slot).b) }; +//! +//! #[allow(unreachable_code, clippy::diverging_sub_expression)] +//! if false { +//! unsafe { +//! ::core::ptr::write( +//! slot, +//! Foo { +//! a: ::core::panic!(), +//! b: ::core::panic!(), +//! }, +//! ); +//! }; +//! } +//! unsafe { ::pinned_init::__internal::DropGuard::forget(a) }; +//! unsafe { ::pinned_init::__internal::DropGuard::forget(b) }; +//! } +//! Ok(__InitOk) +//! }); +//! let init = move |slot| -> ::core::result::Result<(), ::core::convert::Infallible> { +//! init(slot).map(|__InitOk| ()) +//! }; +//! let init = +//! unsafe { ::pinned_init::pin_init_from_closure::<_, ::core::convert::Infallible>(init) }; +//! init +//! }; +//! ``` + +/// Creates a `unsafe impl<...> PinnedDrop for $type` block. +/// +/// See [`PinnedDrop`] for more information. +#[doc(hidden)] +#[macro_export] +macro_rules! __pinned_drop { + ( + @impl_sig($($impl_sig:tt)*), + @impl_body( + $(#[$($attr:tt)*])* +fn drop($self:ident: $st:ty) { + $($inner:stmt)* + } + ), + ) => { +unsafe $($impl_sig)* { +// Inherit all attributes and the type/ident tokens for the signature. + $(#[$($attr)*])* +fn drop ($self: $st, _: $crate::init::__internal::OnlyCallFromDrop ) { + $($inner)* + } + } + } +}/// This macro first parses the struct definition such that it separates pinned and not pinned /// fields. Afterwards it declares the struct and implement the `PinData` trait safely. @@ -653,6 +884,38 @@ macro_rules! __pin_data {impl <T : ::core::ops::Drop >MustNotImplDrop for T {} impl<$($impl_generics)*> MustNotImplDrop for $name<$($ty_generics)*> where $($whr)* {} +// We also take care to prevent users from writing a useless `PinnedDrop` implementation. +// They might implement `PinnedDrop` correctly for the struct, but forget to give +// `PinnedDrop` as the parameter to `#[pin_data]`. +#[allow(non_camel_case_types)] +trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {} +impl <T : $crate::init::PinnedDrop > +UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {} + impl<$($impl_generics)*> + UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for $name<$($ty_generics)*> + where $($whr)* {} + }; +// When `PinnedDrop` was specified we just implement `Drop` and delegate. + (drop_prevention: + @name($name:ident), + @impl_generics($($impl_generics:tt)*), + @ty_generics($($ty_generics:tt)*), + @where($($whr:tt)*), + @pinned_drop(PinnedDrop), + ) => { + impl<$($impl_generics)*> ::core::ops::Drop for $name<$($ty_generics)*> + where $($whr)* + { +fn drop (&mut self) { +// SAFETY: Since this is a destructor, `self` will not move after this function +// terminates, since it is inaccessible. +let pinned =unsafe { ::core::pin::Pin ::new_unchecked (self) }; +// SAFETY: Since this is a drop function, we can create this token to call the +// pinned destructor of this type. +let token =unsafe { $crate::init::__internal::OnlyCallFromDrop ::create () }; + $crate::init::PinnedDrop ::drop (pinned, token); + } + } };// If some other parameter was specified, we emit a readable error. (drop_prevention:rust/macros/lib.rs +49
-0@@ -8,6 +8,7 @@ mod concat_idents;mod helpers;mod module;mod pin_data; +mod pinned_drop;mod vtable;use proc_macro::TokenStream ;@@ -180,6 +181,10 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream {/// This macro enables the use of the [`pin_init!`] macro. When pin-initializing a `struct`, /// then `#[pin]` directs the type of intializer that is required. /// +/// If your `struct` implements `Drop`, then you need to add `PinnedDrop` as arguments to this +/// macro, and change your `Drop` implementation to `PinnedDrop` annotated with +/// `#[`[`macro@pinned_drop`]`]`, since dropping pinned values requires extra care. +/// /// # Examples /// /// ```rust,ignore @@ -191,9 +196,53 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream {/// } /// ``` /// +/// ```rust,ignore +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex<Vec<Command>>, +/// buf: Box<[u8; 1024 * 1024]>, +/// raw_info: *mut Info, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for DriverData { +/// fn drop(self: Pin<&mut Self>) { +/// unsafe { bindings::destroy_info(self.raw_info) }; +/// } +/// } +/// ``` +/// /// [`pin_init!`]: ../kernel/macro.pin_init.html // ^ cannot use direct link, since `kernel` is not a dependency of `macros`. #[proc_macro_attribute] pub fn pin_data (inner:TokenStream , item:TokenStream ) ->TokenStream { pin_data::pin_data (inner, item) } + +/// Used to implement `PinnedDrop` safely. +/// +/// Only works on structs that are annotated via `#[`[`macro@pin_data`]`]`. +/// +/// # Examples +/// +/// ```rust,ignore +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex<Vec<Command>>, +/// buf: Box<[u8; 1024 * 1024]>, +/// raw_info: *mut Info, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for DriverData { +/// fn drop(self: Pin<&mut Self>) { +/// unsafe { bindings::destroy_info(self.raw_info) }; +/// } +/// } +/// ``` +#[proc_macro_attribute] +pub fn pinned_drop (args:TokenStream , input:TokenStream ) ->TokenStream { + pinned_drop::pinned_drop (args, input) +}rust/macros/pinned_drop.rs new file +49
-0@@ -0,0 +1,49 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use proc_macro::{TokenStream ,TokenTree }; + +pub (crate )fn pinned_drop (_args:TokenStream , input:TokenStream ) ->TokenStream { +let mut toks = input.into_iter ().collect ::<Vec <_ >>(); +assert! (!toks.is_empty ()); +// Ensure that we have an `impl` item. +assert! (matches! (&toks[0 ],TokenTree ::Ident (i)if i.to_string () =="impl" )); +// Ensure that we are implementing `PinnedDrop`. +let mut nesting:usize =0 ; +let mut pinned_drop_idx =None ; +for (i, tt)in toks.iter ().enumerate () { +match tt { +TokenTree ::Punct (p)if p.as_char () =='<' => { + nesting +=1 ; + } +TokenTree ::Punct (p)if p.as_char () =='>' => { + nesting = nesting.checked_sub (1 ).unwrap (); +continue ; + } + _ => {} + } +if i >=1 && nesting ==0 { +// Found the end of the generics, this should be `PinnedDrop`. +assert! ( +matches! (tt,TokenTree ::Ident (i)if i.to_string () =="PinnedDrop" ), +"expected 'PinnedDrop', found: '{:?}'" , + tt + ); + pinned_drop_idx =Some (i); +break ; + } + } +let idx = pinned_drop_idx + .unwrap_or_else (||panic! ("Expected an `impl` block implementing `PinnedDrop`." )); +// Fully qualify the `PinnedDrop`, as to avoid any tampering. + toks.splice (idx..idx,quote! (::kernel::init::)); +// Take the `{}` body and call the declarative macro. +if let Some (TokenTree ::Group (last)) = toks.pop () { +let last = last.stream (); +quote! (::kernel::__pinned_drop! { + @impl_sig (#(#toks)*), + @impl_body (#last), + }) + }else { +TokenStream ::from_iter (toks) + } +}
PATCH v3 8/13 rust: init: add `stack_pin_init!` macro
In reply to [email protected]From: Benno Lossin <[email protected]>
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.
--- rust/kernel/init.rs | 70 +++++++++++++++++++++++++++++++--- rust/kernel/init/__internal.rs | 46 ++++++++++++++++++++++ 2 files changed, 110 insertions(+), 6 deletions(-)
rust/kernel/init.rs +64 -6
@@ -12,7 +12,8 @@//! //! To initialize a `struct` with an in-place constructor you will need two things: //! - an in-place constructor, -//! - a memory location that can hold your `struct`. +//! - a memory location that can hold your `struct` (this can be the [stack], an [`Arc<T>`], +//! [`UniqueArc<T>`], [`Box<T>`] or any other smart pointer that implements [`InPlaceInit`]). //! //! To get an in-place constructor there are generally three options: //! - directly creating an in-place constructor using the [`pin_init!`] macro,
@@ -180,6 +181,7 @@//! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]: //! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +//! [stack]: crate::stack_pin_init //! [`Arc<T>`]: crate::sync::Arc //! [`impl PinInit<Foo>`]: PinInit //! [`impl PinInit<T, E>`]: PinInit
@@ -199,6 +201,62 @@ pub mod __internal;#[doc(hidden)] pub mod macros; +/// Initialize and pin a type directly on the stack. +/// +/// # Examples +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use macros::pin_data; +/// # use core::pin::Pin; +/// #[pin_data] +/// struct Foo { +/// #[pin] +/// a: Mutex<usize>, +/// b: Bar, +/// } +/// +/// #[pin_data] +/// struct Bar { +/// x: u32, +/// } +/// +/// let a = new_mutex!(42, "Foo::a"); +/// +/// stack_pin_init!(let foo =? pin_init!(Foo { +/// a, +/// b: Bar { +/// x: 64, +/// }, +/// })); +/// let foo: Pin<&mut Foo> = foo; +/// # Ok::<(), core::convert::Infallible>(()) +/// ``` +/// +/// # Syntax +/// +/// A normal `let` binding with optional type annotation. The expression is expected to implement +/// [`PinInit`]. Additionally a `?` can be put after the `=`, this will assign `Pin<&mut T>` to the +/// variable instead of `Result<Pin<&mut T>, E>`. +#[macro_export] +macro_rules! stack_pin_init { + (let $var:ident $(: $t:ty)? = $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val) } + }; + }; + (let $var:ident $(: $t:ty)? =? $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val)? } + }; + }; +} +/// Construct an in-place, pinned initializer for `struct`s. /// /// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use
@@ -916,8 +974,8 @@ macro_rules! try_init {/// A pinned initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::pin_init`] function of a -/// smart pointer like [`Arc<T>`] on this. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`] or even the stack (see [`stack_pin_init!`]). Use the +/// [`InPlaceInit::pin_init`] function of a smart pointer like [`Arc<T>`] on this. /// /// Also see the [module description](self). ///
@@ -952,9 +1010,9 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::init`] function of a smart -/// pointer like [`Arc<T>`] on this. Because [`PinInit<T, E>`] is a super trait, you can -/// use every function that takes it as well. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`] or even the stack (see [`stack_pin_init!`]). Use the +/// [`InPlaceInit::init`] function of a smart pointer like [`Arc<T>`] on this. Because +/// [`PinInit<T, E>`] is a super trait, you can use every function that takes it as well. /// /// Also see the [module description](self). ///
rust/kernel/init/__internal.rs +46 -0
52 lines not on this page · raw message
--
2.39.2
Gary Guo
maintainerRe: [PATCH v3 08/13] rust: init: add `stack_pin_init!` macro
Quoted 157 lines · On Wed, 29 Mar 2023 22:33:29 +0000 [email protected] wrote:
From: Benno Lossin <[email protected]>
The
stack_pin_init!macro allows pin-initializing a value on the stack. It accepts aimpl PinInit<T, E>to initialize aT. It allows propagating any errors via?or handling it normally viamatch.Signed-off-by Benno Lossin <[email protected]>--- rust/kernel/init.rs | 70 +++++++++++++++++++++++++++++++--- rust/kernel/init/__internal.rs | 46 ++++++++++++++++++++++ 2 files changed, 110 insertions(+), 6 deletions(-)rust/kernel/init.rs +64
-6@@ -12,7 +12,8 @@//! //! To initialize a `struct` with an in-place constructor you will need two things: //! - an in-place constructor, -//! - a memory location that can hold your `struct`. +//! - a memory location that can hold your `struct` (this can be the [stack], an [`Arc<T>`], +//! [`UniqueArc<T>`], [`Box<T>`] or any other smart pointer that implements [`InPlaceInit`]). //! //! To get an in-place constructor there are generally three options: //! - directly creating an in-place constructor using the [`pin_init!`] macro, @@ -180,6 +181,7 @@//! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]: //! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +//! [stack]: crate::stack_pin_init //! [`Arc<T>`]: crate::sync::Arc //! [`impl PinInit<Foo>`]: PinInit //! [`impl PinInit<T, E>`]: PinInit @@ -199,6 +201,62 @@ pub mod __internal;#[doc(hidden)] pub mod macros; +/// Initialize and pin a type directly on the stack. +/// +/// # Examples +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use macros::pin_data; +/// # use core::pin::Pin; +/// #[pin_data] +/// struct Foo { +/// #[pin] +/// a: Mutex<usize>, +/// b: Bar, +/// } +/// +/// #[pin_data] +/// struct Bar { +/// x: u32, +/// } +/// +/// let a = new_mutex!(42, "Foo::a"); +/// +/// stack_pin_init!(let foo =? pin_init!(Foo { +/// a, +/// b: Bar { +/// x: 64, +/// }, +/// })); +/// let foo: Pin<&mut Foo> = foo; +/// # Ok::<(), core::convert::Infallible>(()) +/// ``` +/// +/// # Syntax +/// +/// A normal `let` binding with optional type annotation. The expression is expected to implement +/// [`PinInit`]. Additionally a `?` can be put after the `=`, this will assign `Pin<&mut T>` to the +/// variable instead of `Result<Pin<&mut T>, E>`. +#[macro_export] +macro_rules! stack_pin_init { + (let $var:ident $(: $t:ty)? = $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val) } + }; + }; + (let $var:ident $(: $t:ty)? =? $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val)? } + }; + }; +} +/// Construct an in-place, pinned initializer for `struct`s. /// /// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use @@ -916,8 +974,8 @@ macro_rules! try_init {/// A pinned initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::pin_init`] function of a -/// smart pointer like [`Arc<T>`] on this. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`] or even the stack (see [`stack_pin_init!`]). Use the +/// [`InPlaceInit::pin_init`] function of a smart pointer like [`Arc<T>`] on this. /// /// Also see the [module description](self). /// @@ -952,9 +1010,9 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::init`] function of a smart -/// pointer like [`Arc<T>`] on this. Because [`PinInit<T, E>`] is a super trait, you can -/// use every function that takes it as well. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`] or even the stack (see [`stack_pin_init!`]). Use the +/// [`InPlaceInit::init`] function of a smart pointer like [`Arc<T>`] on this. Because +/// [`PinInit<T, E>`] is a super trait, you can use every function that takes it as well. /// /// Also see the [module description](self). /// rust/kernel/init/__internal.rs +28
-0@@ -89,6 +89,52 @@ unsafe impl<T: ?Sized> HasInitData for T { } } +/// Stack initializer helper type. Use [`stack_pin_init`] instead of this primitive. +/// +/// # Invariants +/// +/// If `self.1` is true, then `self.0` is initialized. +/// +/// [`stack_pin_init`]: kernel::stack_pin_init +pub struct StackInit <T >(MaybeUninit <T >,bool ); + +impl <T >Drop for StackInit <T > { +#[inline] +fn drop (&mut self) { +if self.1 { +// SAFETY: As we are being dropped, we only call this once. And since `self.1 == true`, +// `self.0` has to be initialized. +unsafe { self.0 .assume_init_drop () }; + } + } +} + +impl <T >StackInit <T > { +/// Creates a new [`StackInit<T>`] that is uninitialized. Use [`stack_pin_init`] instead of this +/// primitive. +/// +/// [`stack_pin_init`]: kernel::stack_pin_init +#[inline] +pub fn uninit () ->Self { +Self (MaybeUninit ::uninit (),false )
rust/kernel/init/__internal.rs unsafe impl<T: ?Sized> HasInitData for T { · line 129
Quoted 10 lines
rust/kernel/init/__internal.rs +10
-0+ } + +/// Initializes the contents and returns the result. +/// +/// # Safety +/// +/// The caller ensures that `self` is on the stack and not accessible in any other way, if this +/// function returns `Ok`. +#[inline] +pub unsafe fn init <E >(&mut self, init:impl PinInit <T ,E >) ->Result <Pin <&mut T >,E > {
Could this be made safe if the signature takes self: Pin<&mut Self> instead?
The std pin! macro is stable in
1.68 so we can just core::pin::pin!(StackInit::uninit()) and then call init on it.
Best,
Gary
Quoted 15 lines
rust/kernel/init/__internal.rs +8
-1+// SAFETY: The memory slot is valid and this type ensures that it will stay pinned. +unsafe { init.__pinned_init (self.0 .as_mut_ptr ())? }; + self.1 =true ; +// SAFETY: The slot is now pinned, since we will never give access to `&mut T`. +Ok (unsafe {Pin ::new_unchecked (self.0 .assume_init_mut ()) }) + } +} +/// When a value of this type is dropped, it drops a `T`. /// /// Can be forgotton to prevent the drop. --2.39.2
Re: [PATCH v3 08/13] rust: init: add `stack_pin_init!` macro
Quoted 22 lines · Gary Guo
Quoted 8 lines
rust/kernel/init/__internal.rs +8
-0+impl <T >StackInit <T > { +/// Creates a new [`StackInit<T>`] that is uninitialized. Use [`stack_pin_init`] instead of this +/// primitive. +/// +/// [`stack_pin_init`]: kernel::stack_pin_init +#[inline] +pub fn uninit () ->Self { +Self (MaybeUninit ::uninit (),false )rust/kernel/init/__internal.rs unsafe impl<T: ?Sized> HasInitData for T { · line 129
Quoted 10 lines
rust/kernel/init/__internal.rs +10
-0+ } + +/// Initializes the contents and returns the result. +/// +/// # Safety +/// +/// The caller ensures that `self` is on the stack and not accessible in any other way, if this +/// function returns `Ok`. +#[inline] +pub unsafe fn init <E >(&mut self, init:impl PinInit <T ,E >) ->Result <Pin <&mut T >,E > {Could this be made safe if the signature takes
self: Pin<&mut Self>instead?
Quoted 6 lines
The std
pin!macro is stable in
1.68 so we can justcore::pin::pin!(StackInit::uninit())and then calliniton it.Best,
Gary
Yeah, I think that would work. If it's marked safe, then it will be possible to call init several times, but this is fine if init transitions the StackInit back into its uninitialized state before attempting to initialize it again.
Re: [PATCH v3 08/13] rust: init: add `stack_pin_init!` macro
In reply to [email protected]Quoted 7 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
The
stack_pin_init!macro allows pin-initializing a value on the stack. It accepts aimpl PinInit<T, E>to initialize aT. It allows propagating any errors via?or handling it normally viamatch.Signed-off-by Benno Lossin <[email protected]>
Quoted 8 lines
---
rust/kernel/init.rs +7
-0+#[macro_export] +macro_rules! stack_pin_init { + (let $var:ident $(: $t:ty)? = $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val) }
rust/kernel/init.rs pub mod __internal; · line 258
Quoted 10 lines
rust/kernel/init.rs +10
-0+ }; + }; + (let $var:ident $(: $t:ty)? =? $val:expr) => { + let mut $var = $crate::init::__internal::StackInit$(::<$t>)?::uninit(); + let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val)? } + }; + }; +}
This will be inconvenient to use if the initializer is infallible and is used inside an infallible function. However, I'm not sure what a better alternative would be. Perhaps we should have three variants?
Also, maybe a <- rather than = would be more consistent?
Anyway, I don't think this should block the PR. We can revisit it later if it becomes a problem.
Re: [PATCH v3 08/13] rust: init: add `stack_pin_init!` macro
Quoted 25 lines · Alice Ryhl
Quoted 7 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
The
stack_pin_init!macro allows pin-initializing a value on the stack. It accepts aimpl PinInit<T, E>to initialize aT. It allows propagating any errors via?or handling it normally viamatch.Signed-off-by Benno Lossin <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Quoted 14 lines
---
rust/kernel/init.rs +13
-0+#[macro_export] +macro_rules! stack_pin_init { + (let $var:ident $(: $t:ty)? = $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val) } + }; + }; + (let $var:ident $(: $t:ty)? =? $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val;
Quoted 8 lines
rust/kernel/init.rs pub mod __internal; · line 258
Quoted 4 lines
rust/kernel/init.rs +4
-0+unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val)? } + }; + }; +}This will be inconvenient to use if the initializer is infallible and is used inside an infallible function. However, I'm not sure what a better alternative would be. Perhaps we should have three variants?
That could be an option, any ideas for the syntax though? Or should it be a different macro like stack_pin_init! and try_stack_pin_init!?
Quoted 1 line
Also, maybe a
<-rather than=would be more consistent?
That is sadly not possible, since <- is not allowed after ty fragments.
Quoted 2 lines
Anyway, I don't think this should block the PR. We can revisit it later if it becomes a problem.
Sure.
--
Cheers,
Benno
Re: [PATCH v3 08/13] rust: init: add `stack_pin_init!` macro
Quoted 35 lines · Benno Lossin
Quoted 25 lines · Alice Ryhl
Quoted 7 lines · On 3/30/23 00:33, [email protected] wrote:
From: Benno Lossin <[email protected]>
The
stack_pin_init!macro allows pin-initializing a value on the stack. It accepts aimpl PinInit<T, E>to initialize aT. It allows propagating any errors via?or handling it normally viamatch.Signed-off-by Benno Lossin <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Quoted 14 lines
---
rust/kernel/init.rs +13
-0+#[macro_export] +macro_rules! stack_pin_init { + (let $var:ident $(: $t:ty)? = $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val) } + }; + }; + (let $var:ident $(: $t:ty)? =? $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val;Quoted 8 lines
rust/kernel/init.rs pub mod __internal; · line 258
Quoted 4 lines
rust/kernel/init.rs +4
-0+unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val)? } + }; + }; +}This will be inconvenient to use if the initializer is infallible and is used inside an infallible function. However, I'm not sure what a better alternative would be. Perhaps we should have three variants?
Quoted 2 lines
That could be an option, any ideas for the syntax though? Or should it be a different macro like
stack_pin_init!andtry_stack_pin_init!?
You've also split up the other macros into a fallible and infallible version, so I think the same would be fine here. Perhaps use stack_pin_try_init! as the name?
Quoted 14 lines
Quoted 1 line
Also, maybe a
<-rather than=would be more consistent?That is sadly not possible, since
<-is not allowed aftertyfragments.Quoted 2 lines
Anyway, I don't think this should block the PR. We can revisit it later if it becomes a problem.
Sure.
--
Cheers,
Benno
Re: [PATCH v3 08/13] rust: init: add `stack_pin_init!` macro
In reply to [email protected]Quoted 8 lines · [email protected] writes:
From: Benno Lossin <[email protected]>
The
stack_pin_init!macro allows pin-initializing a value on the stack. It accepts aimpl PinInit<T, E>to initialize aT. It allows propagating any errors via?or handling it normally viamatch.Signed-off-by Benno Lossin <[email protected]>---
Quoted 170 lines
rust/kernel/init.rs | 70 +++++++++++++++++++++++++++++++--- rust/kernel/init/__internal.rs | 46 ++++++++++++++++++++++ 2 files changed, 110 insertions(+), 6 deletions(-)rust/kernel/init.rs +64
-6@@ -12,7 +12,8 @@//! //! To initialize a `struct` with an in-place constructor you will need two things: //! - an in-place constructor, -//! - a memory location that can hold your `struct`. +//! - a memory location that can hold your `struct` (this can be the [stack], an [`Arc<T>`], +//! [`UniqueArc<T>`], [`Box<T>`] or any other smart pointer that implements [`InPlaceInit`]). //! //! To get an in-place constructor there are generally three options: //! - directly creating an in-place constructor using the [`pin_init!`] macro, @@ -180,6 +181,7 @@//! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]: //! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +//! [stack]: crate::stack_pin_init //! [`Arc<T>`]: crate::sync::Arc //! [`impl PinInit<Foo>`]: PinInit //! [`impl PinInit<T, E>`]: PinInit @@ -199,6 +201,62 @@ pub mod __internal;#[doc(hidden)] pub mod macros; +/// Initialize and pin a type directly on the stack. +/// +/// # Examples +/// +/// ```rust +/// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)] +/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex}; +/// # use macros::pin_data; +/// # use core::pin::Pin; +/// #[pin_data] +/// struct Foo { +/// #[pin] +/// a: Mutex<usize>, +/// b: Bar, +/// } +/// +/// #[pin_data] +/// struct Bar { +/// x: u32, +/// } +/// +/// let a = new_mutex!(42, "Foo::a"); +/// +/// stack_pin_init!(let foo =? pin_init!(Foo { +/// a, +/// b: Bar { +/// x: 64, +/// }, +/// })); +/// let foo: Pin<&mut Foo> = foo; +/// # Ok::<(), core::convert::Infallible>(()) +/// ``` +/// +/// # Syntax +/// +/// A normal `let` binding with optional type annotation. The expression is expected to implement +/// [`PinInit`]. Additionally a `?` can be put after the `=`, this will assign `Pin<&mut T>` to the +/// variable instead of `Result<Pin<&mut T>, E>`. +#[macro_export] +macro_rules! stack_pin_init { + (let $var:ident $(: $t:ty)? = $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val) } + }; + }; + (let $var:ident $(: $t:ty)? =? $val:expr) => { +let mut $var = $crate::init::__internal::StackInit $(::<$t>)?::uninit (); +let mut $var = { +let val = $val; +unsafe { $crate::init::__internal::StackInit ::init (&mut $var, val)? } + }; + }; +} +/// Construct an in-place, pinned initializer for `struct`s. /// /// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use @@ -916,8 +974,8 @@ macro_rules! try_init {/// A pinned initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::pin_init`] function of a -/// smart pointer like [`Arc<T>`] on this. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`] or even the stack (see [`stack_pin_init!`]). Use the +/// [`InPlaceInit::pin_init`] function of a smart pointer like [`Arc<T>`] on this. /// /// Also see the [module description](self). /// @@ -952,9 +1010,9 @@ pub unsafe trait PinInit<T: ?Sized, E = Infallible>: Sized {/// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`]. Use the [`InPlaceInit::init`] function of a smart -/// pointer like [`Arc<T>`] on this. Because [`PinInit<T, E>`] is a super trait, you can -/// use every function that takes it as well. +/// be [`Box<T>`], [`Arc<T>`], [`UniqueArc<T>`] or even the stack (see [`stack_pin_init!`]). Use the +/// [`InPlaceInit::init`] function of a smart pointer like [`Arc<T>`] on this. Because +/// [`PinInit<T, E>`] is a super trait, you can use every function that takes it as well. /// /// Also see the [module description](self). /// rust/kernel/init/__internal.rs +46
-0@@ -89,6 +89,52 @@ unsafe impl<T: ?Sized> HasInitData for T { } } +/// Stack initializer helper type. Use [`stack_pin_init`] instead of this primitive. +/// +/// # Invariants +/// +/// If `self.1` is true, then `self.0` is initialized. +/// +/// [`stack_pin_init`]: kernel::stack_pin_init +pub struct StackInit <T >(MaybeUninit <T >,bool ); + +impl <T >Drop for StackInit <T > { +#[inline] +fn drop (&mut self) { +if self.1 { +// SAFETY: As we are being dropped, we only call this once. And since `self.1 == true`, +// `self.0` has to be initialized. +unsafe { self.0 .assume_init_drop () }; + } + } +} + +impl <T >StackInit <T > { +/// Creates a new [`StackInit<T>`] that is uninitialized. Use [`stack_pin_init`] instead of this +/// primitive. +/// +/// [`stack_pin_init`]: kernel::stack_pin_init +#[inline] +pub fn uninit () ->Self { +Self (MaybeUninit ::uninit (),false ) + } + +/// Initializes the contents and returns the result. +/// +/// # Safety +/// +/// The caller ensures that `self` is on the stack and not accessible in any other way, if this +/// function returns `Ok`. +#[inline] +pub unsafe fn init <E >(&mut self, init:impl PinInit <T ,E >) ->Result <Pin <&mut T >,E > { +// SAFETY: The memory slot is valid and this type ensures that it will stay pinned. +unsafe { init.__pinned_init (self.0 .as_mut_ptr ())? }; + self.1 =true ; +// SAFETY: The slot is now pinned, since we will never give access to `&mut T`. +Ok (unsafe {Pin ::new_unchecked (self.0 .assume_init_mut ()) }) + } +} +/// When a value of this type is dropped, it drops a `T`. /// /// Can be forgotton to prevent the drop.