From c3e4049a681ec86bfe56a05bf6c7ed68ae9cf364 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Wed, 29 Jan 2025 22:59:48 +0100 Subject: [PATCH 01/71] MAINTAINERS: add Danilo Krummrich as Rust reviewer Danilo has been involved with the Rust for Linux project for a year now. He is primarily working on the Nova GPU driver [1][2]. In addition, he has been active in the mailing list and most recently submitted the Device / Driver PCI / Platform series. He is also already a maintainer of `RUST [ALLOC]` as well as several other DRM-related entries. His expertise developing Rust abstractions and APIs for one of the major users of Rust in the kernel will be very useful to have around in the future. Thus add him to the `RUST` entry as reviewer. Link: https://rust-for-linux.com/nova-gpu-driver [1] Link: https://lore.kernel.org/dri-devel/Zfsj0_tb-0-tNrJy@cassiopeiae/ [2] Acked-by: Boqun Feng Acked-by: Alice Ryhl Acked-by: Danilo Krummrich Link: https://lore.kernel.org/r/20250129215948.135486-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index 8e0736dc2ee0..12f2d79ce174 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -20712,6 +20712,7 @@ R: Benno Lossin R: Andreas Hindborg R: Alice Ryhl R: Trevor Gross +R: Danilo Krummrich L: rust-for-linux@vger.kernel.org S: Supported W: https://rust-for-linux.com From 41b6a8122d888299e3e437dae3a36431e6dfd5c9 Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Sun, 5 Jan 2025 19:40:06 +0000 Subject: [PATCH 02/71] rust: alloc: make `ReallocFunc::call` inline This function can be called with different function pointers when different allocator (e.g. Kmalloc, Vmalloc, KVmalloc), however since this function is not polymorphic, only one instance is generated, and function pointers are used. Given that this function is called for any Rust-side allocation/deallocation, performance matters a lot, so making this function inlineable. This is discovered when doing helper inlining work, since it's discovered that even with helpers inlined, rust_helper_ symbols are still present in final vmlinux binary, and it turns out this function is inhibiting the inlining, and introducing indirect function calls. Signed-off-by: Gary Guo Acked-by: Danilo Krummrich Reviewed-by: Boqun Feng Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20250105194054.545201-4-gary@garyguo.net Signed-off-by: Miguel Ojeda --- rust/kernel/alloc/allocator.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/rust/kernel/alloc/allocator.rs b/rust/kernel/alloc/allocator.rs index 439985e29fbc..aa2dfa9dca4c 100644 --- a/rust/kernel/alloc/allocator.rs +++ b/rust/kernel/alloc/allocator.rs @@ -80,6 +80,7 @@ impl ReallocFunc { /// This method has the same guarantees as `Allocator::realloc`. Additionally /// - it accepts any pointer to a valid memory allocation allocated by this function. /// - memory allocated by this function remains valid until it is passed to this function. + #[inline] unsafe fn call( &self, ptr: Option>, From 6ad64bf91728502fe8a4d1419c0a3e4fd323f503 Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Thu, 30 Jan 2025 11:21:38 +0000 Subject: [PATCH 03/71] rust: task: make Pid type alias public The Pid type alias represents the integer type used for pids in the kernel. It's the Rust equivalent to pid_t, and there are various methods on Task that use Pid as the return type. Binder needs to use Pid as the type for function arguments and struct fields in many places. Thus, make the type public so that Binder can access it. Signed-off-by: Alice Ryhl Reviewed-by: Fiona Behrens Link: https://lore.kernel.org/r/20250130-task-pid-pub-v1-1-508808bcfcdc@google.com Signed-off-by: Miguel Ojeda --- rust/kernel/task.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs index 07bc22a7645c..49012e711942 100644 --- a/rust/kernel/task.rs +++ b/rust/kernel/task.rs @@ -106,7 +106,7 @@ unsafe impl Send for Task {} unsafe impl Sync for Task {} /// The type of process identifiers (PIDs). -type Pid = bindings::pid_t; +pub type Pid = bindings::pid_t; /// The type of user identifiers (UIDs). #[derive(Copy, Clone)] From 998c65733b95e8de45cbc10aa8d69652d15fa9d3 Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 10 Feb 2025 09:53:35 +0000 Subject: [PATCH 04/71] rust: list: extract common code for insertion To prepare for a new cursor API that has the ability to insert elements into the list, extract the common code needed for this operation into a new `insert_inner` method. Both `push_back` and `push_front` are updated to use the new function. Reviewed-by: Andreas Hindborg Reviewed-by: Boqun Feng Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20250210-cursor-between-v7-1-36f0215181ed@google.com Signed-off-by: Miguel Ojeda --- rust/kernel/list.rs | 70 +++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 38 deletions(-) diff --git a/rust/kernel/list.rs b/rust/kernel/list.rs index fb93330f4af4..97b3599b7207 100644 --- a/rust/kernel/list.rs +++ b/rust/kernel/list.rs @@ -245,8 +245,20 @@ impl, const ID: u64> List { self.first.is_null() } - /// Add the provided item to the back of the list. - pub fn push_back(&mut self, item: ListArc) { + /// Inserts `item` before `next` in the cycle. + /// + /// Returns a pointer to the newly inserted element. Never changes `self.first` unless the list + /// is empty. + /// + /// # Safety + /// + /// * `next` must be an element in this list or null. + /// * if `next` is null, then the list must be empty. + unsafe fn insert_inner( + &mut self, + item: ListArc, + next: *mut ListLinksFields, + ) -> *mut ListLinksFields { let raw_item = ListArc::into_raw(item); // SAFETY: // * We just got `raw_item` from a `ListArc`, so it's in an `Arc`. @@ -259,16 +271,16 @@ impl, const ID: u64> List { // SAFETY: We have not yet called `post_remove`, so `list_links` is still valid. let item = unsafe { ListLinks::fields(list_links) }; - if self.first.is_null() { - self.first = item; + // Check if the list is empty. + if next.is_null() { // SAFETY: The caller just gave us ownership of these fields. // INVARIANT: A linked list with one item should be cyclic. unsafe { (*item).next = item; (*item).prev = item; } + self.first = item; } else { - let next = self.first; // SAFETY: By the type invariant, this pointer is valid or null. We just checked that // it's not null, so it must be valid. let prev = unsafe { (*next).prev }; @@ -282,45 +294,27 @@ impl, const ID: u64> List { (*next).prev = item; } } + + item + } + + /// Add the provided item to the back of the list. + pub fn push_back(&mut self, item: ListArc) { + // SAFETY: + // * `self.first` is null or in the list. + // * `self.first` is only null if the list is empty. + unsafe { self.insert_inner(item, self.first) }; } /// Add the provided item to the front of the list. pub fn push_front(&mut self, item: ListArc) { - let raw_item = ListArc::into_raw(item); // SAFETY: - // * We just got `raw_item` from a `ListArc`, so it's in an `Arc`. - // * If this requirement is violated, then the previous caller of `prepare_to_insert` - // violated the safety requirement that they can't give up ownership of the `ListArc` - // until they call `post_remove`. - // * We own the `ListArc`. - // * Removing items] from this list is always done using `remove_internal_inner`, which - // calls `post_remove` before giving up ownership. - let list_links = unsafe { T::prepare_to_insert(raw_item) }; - // SAFETY: We have not yet called `post_remove`, so `list_links` is still valid. - let item = unsafe { ListLinks::fields(list_links) }; + // * `self.first` is null or in the list. + // * `self.first` is only null if the list is empty. + let new_elem = unsafe { self.insert_inner(item, self.first) }; - if self.first.is_null() { - // SAFETY: The caller just gave us ownership of these fields. - // INVARIANT: A linked list with one item should be cyclic. - unsafe { - (*item).next = item; - (*item).prev = item; - } - } else { - let next = self.first; - // SAFETY: We just checked that `next` is non-null. - let prev = unsafe { (*next).prev }; - // SAFETY: Pointers in a linked list are never dangling, and the caller just gave us - // ownership of the fields on `item`. - // INVARIANT: This correctly inserts `item` between `prev` and `next`. - unsafe { - (*item).next = next; - (*item).prev = prev; - (*prev).next = item; - (*next).prev = item; - } - } - self.first = item; + // INVARIANT: `new_elem` is in the list because we just inserted it. + self.first = new_elem; } /// Removes the last item from this list. From 52ae96f5187c437a262e0497efff4b02e1ab0eab Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 10 Feb 2025 09:53:36 +0000 Subject: [PATCH 05/71] rust: list: make the cursor point between elements I've been using the linked list cursor for a few different things, and I find it inconvenient to use because all of the functions have signatures along the lines of `Self -> Option`. The root cause of these signatures is that the cursor points *at* an element, rather than *between* two elements. Thus, change the cursor API to point between two elements. This is inspired by the stdlib linked list (well, really by this guy [1]), which also uses cursors that point between elements. The `peek_next` method returns a helper that lets you look at and optionally remove the element, as one common use-case of cursors is to iterate a list to look for an element, then remove that element. For many of the methods, this will reduce how many we need since they now just need a prev/next method, instead of the current state where you may end up needing all of curr/prev/next. Also, if we decide to add a function for splitting a list into two lists at the cursor, then a cursor that points between elements is exactly what makes the most sense. Another advantage is that this means you can now have a cursor into an empty list. Link: https://rust-unofficial.github.io/too-many-lists/sixth-cursors-intro.html [1] Reviewed-by: Andreas Hindborg Reviewed-by: Boqun Feng Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20250210-cursor-between-v7-2-36f0215181ed@google.com Signed-off-by: Miguel Ojeda --- rust/kernel/list.rs | 401 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 347 insertions(+), 54 deletions(-) diff --git a/rust/kernel/list.rs b/rust/kernel/list.rs index 97b3599b7207..c0ed227b8a4f 100644 --- a/rust/kernel/list.rs +++ b/rust/kernel/list.rs @@ -483,17 +483,21 @@ impl, const ID: u64> List { other.first = ptr::null_mut(); } - /// Returns a cursor to the first element of the list. - /// - /// If the list is empty, this returns `None`. - pub fn cursor_front(&mut self) -> Option> { - if self.first.is_null() { - None - } else { - Some(Cursor { - current: self.first, - list: self, - }) + /// Returns a cursor that points before the first element of the list. + pub fn cursor_front(&mut self) -> Cursor<'_, T, ID> { + // INVARIANT: `self.first` is in this list. + Cursor { + next: self.first, + list: self, + } + } + + /// Returns a cursor that points after the last element in the list. + pub fn cursor_back(&mut self) -> Cursor<'_, T, ID> { + // INVARIANT: `next` is allowed to be null. + Cursor { + next: core::ptr::null_mut(), + list: self, } } @@ -573,69 +577,358 @@ impl<'a, T: ?Sized + ListItem, const ID: u64> Iterator for Iter<'a, T, ID> { /// A cursor into a [`List`]. /// +/// A cursor always rests between two elements in the list. This means that a cursor has a previous +/// and next element, but no current element. It also means that it's possible to have a cursor +/// into an empty list. +/// +/// # Examples +/// +/// ``` +/// use kernel::prelude::*; +/// use kernel::list::{List, ListArc, ListLinks}; +/// +/// #[pin_data] +/// struct ListItem { +/// value: u32, +/// #[pin] +/// links: ListLinks, +/// } +/// +/// impl ListItem { +/// fn new(value: u32) -> Result> { +/// ListArc::pin_init(try_pin_init!(Self { +/// value, +/// links <- ListLinks::new(), +/// }), GFP_KERNEL) +/// } +/// } +/// +/// kernel::list::impl_has_list_links! { +/// impl HasListLinks<0> for ListItem { self.links } +/// } +/// kernel::list::impl_list_arc_safe! { +/// impl ListArcSafe<0> for ListItem { untracked; } +/// } +/// kernel::list::impl_list_item! { +/// impl ListItem<0> for ListItem { using ListLinks; } +/// } +/// +/// // Use a cursor to remove the first element with the given value. +/// fn remove_first(list: &mut List, value: u32) -> Option> { +/// let mut cursor = list.cursor_front(); +/// while let Some(next) = cursor.peek_next() { +/// if next.value == value { +/// return Some(next.remove()); +/// } +/// cursor.move_next(); +/// } +/// None +/// } +/// +/// // Use a cursor to remove the last element with the given value. +/// fn remove_last(list: &mut List, value: u32) -> Option> { +/// let mut cursor = list.cursor_back(); +/// while let Some(prev) = cursor.peek_prev() { +/// if prev.value == value { +/// return Some(prev.remove()); +/// } +/// cursor.move_prev(); +/// } +/// None +/// } +/// +/// // Use a cursor to remove all elements with the given value. The removed elements are moved to +/// // a new list. +/// fn remove_all(list: &mut List, value: u32) -> List { +/// let mut out = List::new(); +/// let mut cursor = list.cursor_front(); +/// while let Some(next) = cursor.peek_next() { +/// if next.value == value { +/// out.push_back(next.remove()); +/// } else { +/// cursor.move_next(); +/// } +/// } +/// out +/// } +/// +/// // Use a cursor to insert a value at a specific index. Returns an error if the index is out of +/// // bounds. +/// fn insert_at(list: &mut List, new: ListArc, idx: usize) -> Result { +/// let mut cursor = list.cursor_front(); +/// for _ in 0..idx { +/// if !cursor.move_next() { +/// return Err(EINVAL); +/// } +/// } +/// cursor.insert_next(new); +/// Ok(()) +/// } +/// +/// // Merge two sorted lists into a single sorted list. +/// fn merge_sorted(list: &mut List, merge: List) { +/// let mut cursor = list.cursor_front(); +/// for to_insert in merge { +/// while let Some(next) = cursor.peek_next() { +/// if to_insert.value < next.value { +/// break; +/// } +/// cursor.move_next(); +/// } +/// cursor.insert_prev(to_insert); +/// } +/// } +/// +/// let mut list = List::new(); +/// list.push_back(ListItem::new(14)?); +/// list.push_back(ListItem::new(12)?); +/// list.push_back(ListItem::new(10)?); +/// list.push_back(ListItem::new(12)?); +/// list.push_back(ListItem::new(15)?); +/// list.push_back(ListItem::new(14)?); +/// assert_eq!(remove_all(&mut list, 12).iter().count(), 2); +/// // [14, 10, 15, 14] +/// assert!(remove_first(&mut list, 14).is_some()); +/// // [10, 15, 14] +/// insert_at(&mut list, ListItem::new(12)?, 2)?; +/// // [10, 15, 12, 14] +/// assert!(remove_last(&mut list, 15).is_some()); +/// // [10, 12, 14] +/// +/// let mut list2 = List::new(); +/// list2.push_back(ListItem::new(11)?); +/// list2.push_back(ListItem::new(13)?); +/// merge_sorted(&mut list, list2); +/// +/// let mut items = list.into_iter(); +/// assert_eq!(items.next().unwrap().value, 10); +/// assert_eq!(items.next().unwrap().value, 11); +/// assert_eq!(items.next().unwrap().value, 12); +/// assert_eq!(items.next().unwrap().value, 13); +/// assert_eq!(items.next().unwrap().value, 14); +/// assert!(items.next().is_none()); +/// # Result::<(), Error>::Ok(()) +/// ``` +/// /// # Invariants /// -/// The `current` pointer points a value in `list`. +/// The `next` pointer is null or points a value in `list`. pub struct Cursor<'a, T: ?Sized + ListItem, const ID: u64 = 0> { - current: *mut ListLinksFields, list: &'a mut List, + /// Points at the element after this cursor, or null if the cursor is after the last element. + next: *mut ListLinksFields, } impl<'a, T: ?Sized + ListItem, const ID: u64> Cursor<'a, T, ID> { - /// Access the current element of this cursor. - pub fn current(&self) -> ArcBorrow<'_, T> { - // SAFETY: The `current` pointer points a value in the list. - let me = unsafe { T::view_value(ListLinks::from_fields(self.current)) }; - // SAFETY: - // * All values in a list are stored in an `Arc`. - // * The value cannot be removed from the list for the duration of the lifetime annotated - // on the returned `ArcBorrow`, because removing it from the list would require mutable - // access to the cursor or the list. However, the `ArcBorrow` holds an immutable borrow - // on the cursor, which in turn holds a mutable borrow on the list, so any such - // mutable access requires first releasing the immutable borrow on the cursor. - // * Values in a list never have a `UniqueArc` reference, because the list has a `ListArc` - // reference, and `UniqueArc` references must be unique. - unsafe { ArcBorrow::from_raw(me) } + /// Returns a pointer to the element before the cursor. + /// + /// Returns null if there is no element before the cursor. + fn prev_ptr(&self) -> *mut ListLinksFields { + let mut next = self.next; + let first = self.list.first; + if next == first { + // We are before the first element. + return core::ptr::null_mut(); + } + + if next.is_null() { + // We are after the last element, so we need a pointer to the last element, which is + // the same as `(*first).prev`. + next = first; + } + + // SAFETY: `next` can't be null, because then `first` must also be null, but in that case + // we would have exited at the `next == first` check. Thus, `next` is an element in the + // list, so we can access its `prev` pointer. + unsafe { (*next).prev } } - /// Move the cursor to the next element. - pub fn next(self) -> Option> { - // SAFETY: The `current` field is always in a list. - let next = unsafe { (*self.current).next }; + /// Access the element after this cursor. + pub fn peek_next(&mut self) -> Option> { + if self.next.is_null() { + return None; + } + + // INVARIANT: + // * We just checked that `self.next` is non-null, so it must be in `self.list`. + // * `ptr` is equal to `self.next`. + Some(CursorPeek { + ptr: self.next, + cursor: self, + }) + } + + /// Access the element before this cursor. + pub fn peek_prev(&mut self) -> Option> { + let prev = self.prev_ptr(); + + if prev.is_null() { + return None; + } + + // INVARIANT: + // * We just checked that `prev` is non-null, so it must be in `self.list`. + // * `self.prev_ptr()` never returns `self.next`. + Some(CursorPeek { + ptr: prev, + cursor: self, + }) + } + + /// Move the cursor one element forward. + /// + /// If the cursor is after the last element, then this call does nothing. This call returns + /// `true` if the cursor's position was changed. + pub fn move_next(&mut self) -> bool { + if self.next.is_null() { + return false; + } + + // SAFETY: `self.next` is an element in the list and we borrow the list mutably, so we can + // access the `next` field. + let mut next = unsafe { (*self.next).next }; if next == self.list.first { - None - } else { - // INVARIANT: Since `self.current` is in the `list`, its `next` pointer is also in the - // `list`. - Some(Cursor { - current: next, - list: self.list, - }) + next = core::ptr::null_mut(); } + + // INVARIANT: `next` is either null or the next element after an element in the list. + self.next = next; + true } - /// Move the cursor to the previous element. - pub fn prev(self) -> Option> { - // SAFETY: The `current` field is always in a list. - let prev = unsafe { (*self.current).prev }; + /// Move the cursor one element backwards. + /// + /// If the cursor is before the first element, then this call does nothing. This call returns + /// `true` if the cursor's position was changed. + pub fn move_prev(&mut self) -> bool { + if self.next == self.list.first { + return false; + } + + // INVARIANT: `prev_ptr()` always returns a pointer that is null or in the list. + self.next = self.prev_ptr(); + true + } - if self.current == self.list.first { - None + /// Inserts an element where the cursor is pointing and get a pointer to the new element. + fn insert_inner(&mut self, item: ListArc) -> *mut ListLinksFields { + let ptr = if self.next.is_null() { + self.list.first } else { - // INVARIANT: Since `self.current` is in the `list`, its `prev` pointer is also in the - // `list`. - Some(Cursor { - current: prev, - list: self.list, - }) + self.next + }; + // SAFETY: + // * `ptr` is an element in the list or null. + // * if `ptr` is null, then `self.list.first` is null so the list is empty. + let item = unsafe { self.list.insert_inner(item, ptr) }; + if self.next == self.list.first { + // INVARIANT: We just inserted `item`, so it's a member of list. + self.list.first = item; } + item + } + + /// Insert an element at this cursor's location. + pub fn insert(mut self, item: ListArc) { + // This is identical to `insert_prev`, but consumes the cursor. This is helpful because it + // reduces confusion when the last operation on the cursor is an insertion; in that case, + // you just want to insert the element at the cursor, and it is confusing that the call + // involves the word prev or next. + self.insert_inner(item); + } + + /// Inserts an element after this cursor. + /// + /// After insertion, the new element will be after the cursor. + pub fn insert_next(&mut self, item: ListArc) { + self.next = self.insert_inner(item); } - /// Remove the current element from the list. + /// Inserts an element before this cursor. + /// + /// After insertion, the new element will be before the cursor. + pub fn insert_prev(&mut self, item: ListArc) { + self.insert_inner(item); + } + + /// Remove the next element from the list. + pub fn remove_next(&mut self) -> Option> { + self.peek_next().map(|v| v.remove()) + } + + /// Remove the previous element from the list. + pub fn remove_prev(&mut self) -> Option> { + self.peek_prev().map(|v| v.remove()) + } +} + +/// References the element in the list next to the cursor. +/// +/// # Invariants +/// +/// * `ptr` is an element in `self.cursor.list`. +/// * `ISNEXT == (self.ptr == self.cursor.next)`. +pub struct CursorPeek<'a, 'b, T: ?Sized + ListItem, const ISNEXT: bool, const ID: u64> { + cursor: &'a mut Cursor<'b, T, ID>, + ptr: *mut ListLinksFields, +} + +impl<'a, 'b, T: ?Sized + ListItem, const ISNEXT: bool, const ID: u64> + CursorPeek<'a, 'b, T, ISNEXT, ID> +{ + /// Remove the element from the list. pub fn remove(self) -> ListArc { - // SAFETY: The `current` pointer always points at a member of the list. - unsafe { self.list.remove_internal(self.current) } + if ISNEXT { + self.cursor.move_next(); + } + + // INVARIANT: `self.ptr` is not equal to `self.cursor.next` due to the above `move_next` + // call. + // SAFETY: By the type invariants of `Self`, `next` is not null, so `next` is an element of + // `self.cursor.list` by the type invariants of `Cursor`. + unsafe { self.cursor.list.remove_internal(self.ptr) } + } + + /// Access this value as an [`ArcBorrow`]. + pub fn arc(&self) -> ArcBorrow<'_, T> { + // SAFETY: `self.ptr` points at an element in `self.cursor.list`. + let me = unsafe { T::view_value(ListLinks::from_fields(self.ptr)) }; + // SAFETY: + // * All values in a list are stored in an `Arc`. + // * The value cannot be removed from the list for the duration of the lifetime annotated + // on the returned `ArcBorrow`, because removing it from the list would require mutable + // access to the `CursorPeek`, the `Cursor` or the `List`. However, the `ArcBorrow` holds + // an immutable borrow on the `CursorPeek`, which in turn holds a mutable borrow on the + // `Cursor`, which in turn holds a mutable borrow on the `List`, so any such mutable + // access requires first releasing the immutable borrow on the `CursorPeek`. + // * Values in a list never have a `UniqueArc` reference, because the list has a `ListArc` + // reference, and `UniqueArc` references must be unique. + unsafe { ArcBorrow::from_raw(me) } + } +} + +impl<'a, 'b, T: ?Sized + ListItem, const ISNEXT: bool, const ID: u64> core::ops::Deref + for CursorPeek<'a, 'b, T, ISNEXT, ID> +{ + // If you change the `ptr` field to have type `ArcBorrow<'a, T>`, it might seem like you could + // get rid of the `CursorPeek::arc` method and change the deref target to `ArcBorrow<'a, T>`. + // However, that doesn't work because 'a is too long. You could obtain an `ArcBorrow<'a, T>` + // and then call `CursorPeek::remove` without giving up the `ArcBorrow<'a, T>`, which would be + // unsound. + type Target = T; + + fn deref(&self) -> &T { + // SAFETY: `self.ptr` points at an element in `self.cursor.list`. + let me = unsafe { T::view_value(ListLinks::from_fields(self.ptr)) }; + + // SAFETY: The value cannot be removed from the list for the duration of the lifetime + // annotated on the returned `&T`, because removing it from the list would require mutable + // access to the `CursorPeek`, the `Cursor` or the `List`. However, the `&T` holds an + // immutable borrow on the `CursorPeek`, which in turn holds a mutable borrow on the + // `Cursor`, which in turn holds a mutable borrow on the `List`, so any such mutable access + // requires first releasing the immutable borrow on the `CursorPeek`. + unsafe { &*me } } } From 562cc3cd0c14f7d96572fb9e0674294c5d7099c5 Mon Sep 17 00:00:00 2001 From: Dirk Behme Date: Wed, 15 Jan 2025 07:25:52 +0100 Subject: [PATCH 06/71] docs: rust: Add error handling sections Add error handling sections to the documentation and use it to link to the existing code documentation. This will allow to extend that documentation, use intra-doc links and test the examples. Suggested-by: Miguel Ojeda Link: https://lore.kernel.org/rust-for-linux/CANiq72keOdXy0LFKk9SzYWwSjiD710v=hQO4xi+5E4xNALa6cA@mail.gmail.com/ Signed-off-by: Dirk Behme Link: https://lore.kernel.org/r/20250115062552.1970768-1-dirk.behme@de.bosch.com [ Slightly tweaked wording. - Miguel ] Signed-off-by: Miguel Ojeda --- Documentation/rust/coding-guidelines.rst | 8 ++++++++ Documentation/rust/testing.rst | 7 +++++++ 2 files changed, 15 insertions(+) diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst index a2e326b42410..27f2a7bb5a4a 100644 --- a/Documentation/rust/coding-guidelines.rst +++ b/Documentation/rust/coding-guidelines.rst @@ -373,3 +373,11 @@ triggered due to non-local changes (such as ``dead_code``). For more information about diagnostics in Rust, please see: https://doc.rust-lang.org/stable/reference/attributes/diagnostics.html + +Error handling +-------------- + +For some background and guidelines about Rust for Linux specific error handling, +please see: + + https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust diff --git a/Documentation/rust/testing.rst b/Documentation/rust/testing.rst index 568b71b415a4..c33001726e37 100644 --- a/Documentation/rust/testing.rst +++ b/Documentation/rust/testing.rst @@ -123,6 +123,13 @@ A current limitation is that KUnit does not support assertions in other tasks. Thus, we presently simply print an error to the kernel log if an assertion actually failed. Additionally, doctests are not run for nonpublic functions. +Since these tests are examples, i.e. they are part of the documentation, they +should generally be written like "real code". Thus, for example, instead of +using ``unwrap()`` or ``expect()``, use the ``?`` operator. For more background, +please see: + + https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust + The ``#[test]`` tests --------------------- From fbefae55991f688f5f1615af30fe64823076b072 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 28 Feb 2025 18:05:31 +0100 Subject: [PATCH 07/71] scripts: rust: mention file name in error messages Improve two error messages in the script by mentioning the doctest file path from which the doctest was generated from. This will allow, in case the conversion fails, to get directly the file name triggering the issue, making the bug fixing process faster. Signed-off-by: Guillaume Gomez Link: https://lore.kernel.org/r/20250228170530.950268-2-guillaume1.gomez@gmail.com [ Reworded and removed an unneeded added parameter comma. - Miguel ] Signed-off-by: Miguel Ojeda --- scripts/rustdoc_test_gen.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/rustdoc_test_gen.rs b/scripts/rustdoc_test_gen.rs index 5ebd42ae4a3f..036635fb1621 100644 --- a/scripts/rustdoc_test_gen.rs +++ b/scripts/rustdoc_test_gen.rs @@ -87,8 +87,8 @@ fn find_real_path<'a>(srctree: &Path, valid_paths: &'a mut Vec, file: & assert!( valid_paths.len() > 0, - "No path candidates found. This is likely a bug in the build system, or some files went \ - away while compiling." + "No path candidates found for `{file}`. This is likely a bug in the build system, or some \ + files went away while compiling." ); if valid_paths.len() > 1 { @@ -97,8 +97,8 @@ fn find_real_path<'a>(srctree: &Path, valid_paths: &'a mut Vec, file: & eprintln!(" {path:?}"); } panic!( - "Several path candidates found, please resolve the ambiguity by renaming a file or \ - folder." + "Several path candidates found for `{file}`, please resolve the ambiguity by renaming \ + a file or folder." ); } From cd1ed11a6704638e94ccafe0ba1c3b4a11aab8f3 Mon Sep 17 00:00:00 2001 From: Borys Tyran Date: Fri, 7 Feb 2025 14:25:07 +0000 Subject: [PATCH 08/71] rust: improve lifetimes markup Improve lifetimes markup; e.g. from: /// ... 'a ... to: /// ... `'a` ... This will make lifetimes display as code span with Markdown and make it more consistent with rest of the docs. Link: https://github.com/Rust-for-Linux/linux/issues/1138 Signed-off-by: Borys Tyran Link: https://lore.kernel.org/r/20250207142437.112435-1-borys.tyran@protonmail.com [ Reworded and changed Closes tag to Link. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/fs/file.rs | 4 ++-- rust/kernel/rbtree.rs | 6 +++--- rust/kernel/seq_file.rs | 2 +- rust/kernel/sync/poll.rs | 4 ++-- rust/kernel/types.rs | 6 +++--- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/rust/kernel/fs/file.rs b/rust/kernel/fs/file.rs index e03dbe14d62a..ed57e0137cdb 100644 --- a/rust/kernel/fs/file.rs +++ b/rust/kernel/fs/file.rs @@ -267,7 +267,7 @@ impl LocalFile { /// # Safety /// /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is - /// positive for the duration of 'a. + /// positive for the duration of `'a`. /// * The caller must ensure that if there is an active call to `fdget_pos` that did not take /// the `f_pos_lock` mutex, then that call is on the current thread. #[inline] @@ -341,7 +341,7 @@ impl File { /// # Safety /// /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is - /// positive for the duration of 'a. + /// positive for the duration of `'a`. /// * The caller must ensure that if there are active `fdget_pos` calls on this file, then they /// took the `f_pos_lock` mutex. #[inline] diff --git a/rust/kernel/rbtree.rs b/rust/kernel/rbtree.rs index 0d1e75810664..1ea25c7092fb 100644 --- a/rust/kernel/rbtree.rs +++ b/rust/kernel/rbtree.rs @@ -886,7 +886,7 @@ impl<'a, K, V> Cursor<'a, K, V> { /// # Safety /// /// - `node` must be a valid pointer to a node in an [`RBTree`]. - /// - The caller has immutable access to `node` for the duration of 'b. + /// - The caller has immutable access to `node` for the duration of `'b`. unsafe fn to_key_value<'b>(node: NonNull) -> (&'b K, &'b V) { // SAFETY: the caller guarantees that `node` is a valid pointer in an `RBTree`. let (k, v) = unsafe { Self::to_key_value_raw(node) }; @@ -897,7 +897,7 @@ impl<'a, K, V> Cursor<'a, K, V> { /// # Safety /// /// - `node` must be a valid pointer to a node in an [`RBTree`]. - /// - The caller has mutable access to `node` for the duration of 'b. + /// - The caller has mutable access to `node` for the duration of `'b`. unsafe fn to_key_value_mut<'b>(node: NonNull) -> (&'b K, &'b mut V) { // SAFETY: the caller guarantees that `node` is a valid pointer in an `RBTree`. let (k, v) = unsafe { Self::to_key_value_raw(node) }; @@ -908,7 +908,7 @@ impl<'a, K, V> Cursor<'a, K, V> { /// # Safety /// /// - `node` must be a valid pointer to a node in an [`RBTree`]. - /// - The caller has immutable access to the key for the duration of 'b. + /// - The caller has immutable access to the key for the duration of `'b`. unsafe fn to_key_value_raw<'b>(node: NonNull) -> (&'b K, *mut V) { // SAFETY: By the type invariant of `Self`, all non-null `rb_node` pointers stored in `self` // point to the links field of `Node` objects. diff --git a/rust/kernel/seq_file.rs b/rust/kernel/seq_file.rs index 04947c672979..4c03881a9eba 100644 --- a/rust/kernel/seq_file.rs +++ b/rust/kernel/seq_file.rs @@ -18,7 +18,7 @@ impl SeqFile { /// /// # Safety /// - /// The caller must ensure that for the duration of 'a the following is satisfied: + /// The caller must ensure that for the duration of `'a` the following is satisfied: /// * The pointer points at a valid `struct seq_file`. /// * The `struct seq_file` is not accessed from any other thread. pub unsafe fn from_raw<'a>(ptr: *mut bindings::seq_file) -> &'a SeqFile { diff --git a/rust/kernel/sync/poll.rs b/rust/kernel/sync/poll.rs index d5f17153b424..e105477a3cb1 100644 --- a/rust/kernel/sync/poll.rs +++ b/rust/kernel/sync/poll.rs @@ -43,11 +43,11 @@ impl PollTable { /// /// # Safety /// - /// The caller must ensure that for the duration of 'a, the pointer will point at a valid poll + /// The caller must ensure that for the duration of `'a`, the pointer will point at a valid poll /// table (as defined in the type invariants). /// /// The caller must also ensure that the `poll_table` is only accessed via the returned - /// reference for the duration of 'a. + /// reference for the duration of `'a`. pub unsafe fn from_ptr<'a>(ptr: *mut bindings::poll_table) -> &'a mut PollTable { // SAFETY: The safety requirements guarantee the validity of the dereference, while the // `PollTable` type being transparent makes the cast ok. diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs index 2bbaab83b9d6..9cb573d39c34 100644 --- a/rust/kernel/types.rs +++ b/rust/kernel/types.rs @@ -77,7 +77,7 @@ pub trait ForeignOwnable: Sized { /// /// The provided pointer must have been returned by a previous call to [`into_foreign`], and if /// the pointer is ever passed to [`from_foreign`], then that call must happen after the end of - /// the lifetime 'a. + /// the lifetime `'a`. /// /// [`into_foreign`]: Self::into_foreign /// [`from_foreign`]: Self::from_foreign @@ -100,9 +100,9 @@ pub trait ForeignOwnable: Sized { /// /// The provided pointer must have been returned by a previous call to [`into_foreign`], and if /// the pointer is ever passed to [`from_foreign`], then that call must happen after the end of - /// the lifetime 'a. + /// the lifetime `'a`. /// - /// The lifetime 'a must not overlap with the lifetime of any other call to [`borrow`] or + /// The lifetime `'a` must not overlap with the lifetime of any other call to [`borrow`] or /// `borrow_mut` on the same object. /// /// [`into_foreign`]: Self::into_foreign From 0e123d6420e4bcac1b3bd39986eb0d39332691a8 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Sat, 8 Mar 2025 17:42:58 +0100 Subject: [PATCH 09/71] MAINTAINERS: rust: add tree field for RUST [ALLOC] In the Rust subsystem we are starting to add new subentries which will have their own trees. Those trees will be part of linux-next and will be sent as PRs to be merged into rust-next. Thus do the same for the existing subentry we already have: RUST [ALLOC]. Acked-by: Boqun Feng Acked-by: Danilo Krummrich Link: https://lore.kernel.org/r/20250308164258.811040-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index 12f2d79ce174..007ca67cc830 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -20733,6 +20733,7 @@ RUST [ALLOC] M: Danilo Krummrich L: rust-for-linux@vger.kernel.org S: Maintained +T: git https://github.com/Rust-for-Linux/linux.git alloc-next F: rust/kernel/alloc.rs F: rust/kernel/alloc/ From 901b3290bd4dc35e613d13abd03c129e754dd3dd Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 3 Mar 2025 08:45:12 +0000 Subject: [PATCH 10/71] rust: fix signature of rust_fmt_argument Without this change, the rest of this series will emit the following error message: error[E0308]: `if` and `else` have incompatible types --> /rust/kernel/print.rs:22:22 | 21 | #[export] | --------- expected because of this 22 | unsafe extern "C" fn rust_fmt_argument( | ^^^^^^^^^^^^^^^^^ expected `u8`, found `i8` | = note: expected fn item `unsafe extern "C" fn(*mut u8, *mut u8, *mut c_void) -> *mut u8 {bindings::rust_fmt_argument}` found fn item `unsafe extern "C" fn(*mut i8, *mut i8, *const c_void) -> *mut i8 {print::rust_fmt_argument}` The error may be different depending on the architecture. To fix this, change the void pointer argument to use a const pointer, and change the imports to use crate::ffi instead of core::ffi for integer types. Fixes: 787983da7718 ("vsprintf: add new `%pA` format specifier") Reviewed-by: Tamir Duberstein Acked-by: Greg Kroah-Hartman Signed-off-by: Alice Ryhl Acked-by: Petr Mladek Link: https://lore.kernel.org/r/20250303-export-macro-v3-1-41fbad85a27f@google.com Signed-off-by: Miguel Ojeda --- lib/vsprintf.c | 2 +- rust/kernel/print.rs | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/lib/vsprintf.c b/lib/vsprintf.c index 56fe96319292..a8ac4c4fffcf 100644 --- a/lib/vsprintf.c +++ b/lib/vsprintf.c @@ -2285,7 +2285,7 @@ int __init no_hash_pointers_enable(char *str) early_param("no_hash_pointers", no_hash_pointers_enable); /* Used for Rust formatting ('%pA'). */ -char *rust_fmt_argument(char *buf, char *end, void *ptr); +char *rust_fmt_argument(char *buf, char *end, const void *ptr); /* * Show a '%p' thing. A kernel extension is that the '%p' is followed diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs index b19ee490be58..61ee36c5e5f5 100644 --- a/rust/kernel/print.rs +++ b/rust/kernel/print.rs @@ -6,12 +6,11 @@ //! //! Reference: -use core::{ +use crate::{ ffi::{c_char, c_void}, - fmt, + str::RawFormatter, }; - -use crate::str::RawFormatter; +use core::fmt; // Called from `vsprintf` with format specifier `%pA`. #[expect(clippy::missing_safety_doc)] From 85525eda4f13c496defc46712348fe0711a59b2b Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 3 Mar 2025 08:45:13 +0000 Subject: [PATCH 11/71] rust: macros: support additional tokens in quote! This gives the quote! macro support for the following additional tokens: * The = token. * The _ token. * The # token. (when not followed by an identifier) * Using #my_var with variables of type Ident. Additionally, some type annotations are added to allow cases where groups are empty. For example, quote! does support () in the input, but only when it is *not* empty. When it is empty, there are zero `.push` calls, so the compiler can't infer the item type and also emits a warning about it not needing to be mutable. These additional quote! features are used by a new proc macro that generates code looking like this: const _: () = { if true { ::kernel::bindings::#name } else { #name }; }; where #name has type Ident. Reviewed-by: Andreas Hindborg Reviewed-by: Tamir Duberstein Acked-by: Greg Kroah-Hartman Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20250303-export-macro-v3-2-41fbad85a27f@google.com Signed-off-by: Miguel Ojeda --- rust/macros/quote.rs | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/rust/macros/quote.rs b/rust/macros/quote.rs index 33a199e4f176..31b7ebe504f4 100644 --- a/rust/macros/quote.rs +++ b/rust/macros/quote.rs @@ -20,6 +20,12 @@ impl ToTokens for proc_macro::Group { } } +impl ToTokens for proc_macro::Ident { + 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()]); @@ -40,7 +46,7 @@ impl ToTokens for TokenStream { /// `quote` crate but provides only just enough functionality needed by the current `macros` crate. macro_rules! quote_spanned { ($span:expr => $($tt:tt)*) => {{ - let mut tokens; + let mut tokens: ::std::vec::Vec<::proc_macro::TokenTree>; #[allow(clippy::vec_init_then_push)] { tokens = ::std::vec::Vec::new(); @@ -65,7 +71,8 @@ macro_rules! quote_spanned { quote_spanned!(@proc $v $span $($tt)*); }; (@proc $v:ident $span:ident ( $($inner:tt)* ) $($tt:tt)*) => { - let mut tokens = ::std::vec::Vec::new(); + #[allow(unused_mut)] + let mut tokens = ::std::vec::Vec::<::proc_macro::TokenTree>::new(); quote_spanned!(@proc tokens $span $($inner)*); $v.push(::proc_macro::TokenTree::Group(::proc_macro::Group::new( ::proc_macro::Delimiter::Parenthesis, @@ -136,6 +143,22 @@ macro_rules! quote_spanned { )); 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::Ident(::proc_macro::Ident::new("_", $span))); + 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)*); From 44e333fe464a253f703982f721c7155218f63d1f Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 3 Mar 2025 08:45:14 +0000 Subject: [PATCH 12/71] rust: add #[export] macro Rust has two different tools for generating function declarations to call across the FFI boundary: * bindgen. Generates Rust declarations from a C header. * cbindgen. Generates C headers from Rust declarations. However, we only use bindgen in the kernel. This means that when C code calls a Rust function by name, its signature must be duplicated in both Rust code and a C header, and the signature needs to be kept in sync manually. Introducing cbindgen as a mandatory dependency to build the kernel would be a rather complex and large change, so we do not consider that at this time. Instead, to eliminate this manual checking, introduce a new macro that verifies at compile time that the two function declarations use the same signature. The idea is to run the C declaration through bindgen, and then have rustc verify that the function pointers have the same type. The signature must still be written twice, but at least you can no longer get it wrong. If the signatures don't match, you will get errors that look like this: error[E0308]: `if` and `else` have incompatible types --> /rust/kernel/print.rs:22:22 | 21 | #[export] | --------- expected because of this 22 | unsafe extern "C" fn rust_fmt_argument( | ^^^^^^^^^^^^^^^^^ expected `u8`, found `i8` | = note: expected fn item `unsafe extern "C" fn(*mut u8, *mut u8, *mut c_void) -> *mut u8 {bindings::rust_fmt_argument}` found fn item `unsafe extern "C" fn(*mut i8, *mut i8, *const c_void) -> *mut i8 {print::rust_fmt_argument}` It is unfortunate that the error message starts out by saying "`if` and `else` have incompatible types", but I believe the rest of the error message is reasonably clear and not too confusing. Reviewed-by: Tamir Duberstein Reviewed-by: Andreas Hindborg Acked-by: Greg Kroah-Hartman Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20250303-export-macro-v3-3-41fbad85a27f@google.com Signed-off-by: Miguel Ojeda --- rust/kernel/prelude.rs | 2 +- rust/macros/export.rs | 29 +++++++++++++++++++++++++++++ rust/macros/helpers.rs | 19 ++++++++++++++++++- rust/macros/lib.rs | 24 ++++++++++++++++++++++++ 4 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 rust/macros/export.rs diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index dde2e0649790..889102f5a81e 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -17,7 +17,7 @@ pub use core::pin::Pin; pub use crate::alloc::{flags::*, Box, KBox, KVBox, KVVec, KVec, VBox, VVec, Vec}; #[doc(no_inline)] -pub use macros::{module, pin_data, pinned_drop, vtable, Zeroable}; +pub use macros::{export, module, pin_data, pinned_drop, vtable, Zeroable}; pub use super::{build_assert, build_error}; diff --git a/rust/macros/export.rs b/rust/macros/export.rs new file mode 100644 index 000000000000..a08f6337d5c8 --- /dev/null +++ b/rust/macros/export.rs @@ -0,0 +1,29 @@ +// SPDX-License-Identifier: GPL-2.0 + +use crate::helpers::function_name; +use proc_macro::TokenStream; + +/// Please see [`crate::export`] for documentation. +pub(crate) fn export(_attr: TokenStream, ts: TokenStream) -> TokenStream { + let Some(name) = function_name(ts.clone()) else { + return "::core::compile_error!(\"The #[export] attribute must be used on a function.\");" + .parse::() + .unwrap(); + }; + + // This verifies that the function has the same signature as the declaration generated by + // bindgen. It makes use of the fact that all branches of an if/else must have the same type. + let signature_check = quote!( + const _: () = { + if true { + ::kernel::bindings::#name + } else { + #name + }; + }; + ); + + let no_mangle = quote!(#[no_mangle]); + + TokenStream::from_iter([signature_check, no_mangle, ts]) +} diff --git a/rust/macros/helpers.rs b/rust/macros/helpers.rs index 563dcd2b7ace..3e04f8ecfc74 100644 --- a/rust/macros/helpers.rs +++ b/rust/macros/helpers.rs @@ -1,6 +1,6 @@ // SPDX-License-Identifier: GPL-2.0 -use proc_macro::{token_stream, Group, TokenStream, TokenTree}; +use proc_macro::{token_stream, Group, Ident, TokenStream, TokenTree}; pub(crate) fn try_ident(it: &mut token_stream::IntoIter) -> Option { if let Some(TokenTree::Ident(ident)) = it.next() { @@ -215,3 +215,20 @@ pub(crate) fn parse_generics(input: TokenStream) -> (Generics, Vec) { rest, ) } + +/// Given a function declaration, finds the name of the function. +pub(crate) fn function_name(input: TokenStream) -> Option { + let mut input = input.into_iter(); + while let Some(token) = input.next() { + match token { + TokenTree::Ident(i) if i.to_string() == "fn" => { + if let Some(TokenTree::Ident(i)) = input.next() { + return Some(i); + } + return None; + } + _ => continue, + } + } + None +} diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index d61bc6a56425..a52443a3dbb9 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -9,6 +9,7 @@ #[macro_use] mod quote; mod concat_idents; +mod export; mod helpers; mod module; mod paste; @@ -174,6 +175,29 @@ pub fn vtable(attr: TokenStream, ts: TokenStream) -> TokenStream { vtable::vtable(attr, ts) } +/// Export a function so that C code can call it via a header file. +/// +/// Functions exported using this macro can be called from C code using the declaration in the +/// appropriate header file. It should only be used in cases where C calls the function through a +/// header file; cases where C calls into Rust via a function pointer in a vtable (such as +/// `file_operations`) should not use this macro. +/// +/// This macro has the following effect: +/// +/// * Disables name mangling for this function. +/// * Verifies at compile-time that the function signature matches the declaration in the header +/// file. +/// +/// You must declare the signature of the Rust function in a header file that is included by +/// `rust/bindings/bindings_helper.h`. +/// +/// This macro is *not* the same as the C macros `EXPORT_SYMBOL_*`. All Rust symbols are currently +/// automatically exported with `EXPORT_SYMBOL_GPL`. +#[proc_macro_attribute] +pub fn export(attr: TokenStream, ts: TokenStream) -> TokenStream { + export::export(attr, ts) +} + /// Concatenate two identifiers. /// /// This is useful in macros that need to declare or reference items with names From 92d2873bedf33974b04530215692705185ec6572 Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 3 Mar 2025 08:45:15 +0000 Subject: [PATCH 13/71] print: use new #[export] macro for rust_fmt_argument This moves the rust_fmt_argument function over to use the new #[export] macro, which will verify at compile-time that the function signature matches what is in the header file. Reviewed-by: Andreas Hindborg Reviewed-by: Tamir Duberstein Acked-by: Greg Kroah-Hartman Signed-off-by: Alice Ryhl Acked-by: Petr Mladek Link: https://lore.kernel.org/r/20250303-export-macro-v3-4-41fbad85a27f@google.com [ Removed period as requested by Andy. - Miguel ] Signed-off-by: Miguel Ojeda --- include/linux/sprintf.h | 3 +++ lib/vsprintf.c | 3 --- rust/kernel/print.rs | 3 ++- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/include/linux/sprintf.h b/include/linux/sprintf.h index 33dcbec71925..51cab2def9ec 100644 --- a/include/linux/sprintf.h +++ b/include/linux/sprintf.h @@ -24,4 +24,7 @@ __scanf(2, 0) int vsscanf(const char *, const char *, va_list); extern bool no_hash_pointers; int no_hash_pointers_enable(char *str); +/* Used for Rust formatting ('%pA') */ +char *rust_fmt_argument(char *buf, char *end, const void *ptr); + #endif /* _LINUX_KERNEL_SPRINTF_H */ diff --git a/lib/vsprintf.c b/lib/vsprintf.c index a8ac4c4fffcf..1da61c3e011f 100644 --- a/lib/vsprintf.c +++ b/lib/vsprintf.c @@ -2284,9 +2284,6 @@ int __init no_hash_pointers_enable(char *str) } early_param("no_hash_pointers", no_hash_pointers_enable); -/* Used for Rust formatting ('%pA'). */ -char *rust_fmt_argument(char *buf, char *end, const void *ptr); - /* * Show a '%p' thing. A kernel extension is that the '%p' is followed * by an extra set of alphanumeric characters that are extended format diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs index 61ee36c5e5f5..cf4714242e14 100644 --- a/rust/kernel/print.rs +++ b/rust/kernel/print.rs @@ -8,13 +8,14 @@ use crate::{ ffi::{c_char, c_void}, + prelude::*, str::RawFormatter, }; use core::fmt; // Called from `vsprintf` with format specifier `%pA`. #[expect(clippy::missing_safety_doc)] -#[no_mangle] +#[export] unsafe extern "C" fn rust_fmt_argument( buf: *mut c_char, end: *mut c_char, From fc2f191f850d9a2fb1b78c51d49076e60fb42c49 Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 3 Mar 2025 08:45:16 +0000 Subject: [PATCH 14/71] panic_qr: use new #[export] macro This validates at compile time that the signatures match what is in the header file. It highlights one annoyance with the compile-time check, which is that it can only be used with functions marked unsafe. If the function is not unsafe, then this error is emitted: error[E0308]: `if` and `else` have incompatible types --> /drivers/gpu/drm/drm_panic_qr.rs:987:19 | 986 | #[export] | --------- expected because of this 987 | pub extern "C" fn drm_panic_qr_max_data_size(version: u8, url_len: usize) -> usize { | ^^^^^^^^^^^^^^^^^^^^^^^^^^ expected unsafe fn, found safe fn | = note: expected fn item `unsafe extern "C" fn(_, _) -> _ {kernel::bindings::drm_panic_qr_max_data_size}` found fn item `extern "C" fn(_, _) -> _ {drm_panic_qr_max_data_size}` The signature declarations are moved to a header file so it can be included in the Rust bindings helper, and the extern keyword is removed as it is unnecessary. Reviewed-by: Andreas Hindborg Reviewed-by: Tamir Duberstein Acked-by: Simona Vetter Acked-by: Greg Kroah-Hartman Signed-off-by: Alice Ryhl Reviewed-by: Jocelyn Falempe Link: https://lore.kernel.org/r/20250303-export-macro-v3-5-41fbad85a27f@google.com [ Fixed `rustfmt`. Moved on top the unsafe requirement comment to follow the usual style, and slightly reworded it for clarity. Formatted bindings helper comment. - Miguel ] Signed-off-by: Miguel Ojeda --- drivers/gpu/drm/drm_panic.c | 5 ----- drivers/gpu/drm/drm_panic_qr.rs | 13 +++++++++---- include/drm/drm_panic.h | 7 +++++++ rust/bindings/bindings_helper.h | 5 +++++ 4 files changed, 21 insertions(+), 9 deletions(-) diff --git a/drivers/gpu/drm/drm_panic.c b/drivers/gpu/drm/drm_panic.c index f128d345b16d..dee5301dd729 100644 --- a/drivers/gpu/drm/drm_panic.c +++ b/drivers/gpu/drm/drm_panic.c @@ -486,11 +486,6 @@ static void drm_panic_qr_exit(void) stream.workspace = NULL; } -extern size_t drm_panic_qr_max_data_size(u8 version, size_t url_len); - -extern u8 drm_panic_qr_generate(const char *url, u8 *data, size_t data_len, size_t data_size, - u8 *tmp, size_t tmp_size); - static int drm_panic_get_qr_code_url(u8 **qr_image) { struct kmsg_dump_iter iter; diff --git a/drivers/gpu/drm/drm_panic_qr.rs b/drivers/gpu/drm/drm_panic_qr.rs index bcf248f69252..ecd87e8ffe05 100644 --- a/drivers/gpu/drm/drm_panic_qr.rs +++ b/drivers/gpu/drm/drm_panic_qr.rs @@ -27,7 +27,7 @@ //! * use core::cmp; -use kernel::str::CStr; +use kernel::{prelude::*, str::CStr}; #[derive(Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd)] struct Version(usize); @@ -929,7 +929,7 @@ impl QrImage<'_> { /// * `tmp` must be valid for reading and writing for `tmp_size` bytes. /// /// They must remain valid for the duration of the function call. -#[no_mangle] +#[export] pub unsafe extern "C" fn drm_panic_qr_generate( url: *const kernel::ffi::c_char, data: *mut u8, @@ -980,8 +980,13 @@ pub unsafe extern "C" fn drm_panic_qr_generate( /// * If `url_len` > 0, remove the 2 segments header/length and also count the /// conversion to numeric segments. /// * If `url_len` = 0, only removes 3 bytes for 1 binary segment. -#[no_mangle] -pub extern "C" fn drm_panic_qr_max_data_size(version: u8, url_len: usize) -> usize { +/// +/// # Safety +/// +/// Always safe to call. +// Required to be unsafe due to the `#[export]` annotation. +#[export] +pub unsafe extern "C" fn drm_panic_qr_max_data_size(version: u8, url_len: usize) -> usize { #[expect(clippy::manual_range_contains)] if version < 1 || version > 40 { return 0; diff --git a/include/drm/drm_panic.h b/include/drm/drm_panic.h index f4e1fa9ae607..ff78d00c3da5 100644 --- a/include/drm/drm_panic.h +++ b/include/drm/drm_panic.h @@ -163,4 +163,11 @@ static inline void drm_panic_unlock(struct drm_device *dev, unsigned long flags) #endif +#if defined(CONFIG_DRM_PANIC_SCREEN_QR_CODE) +size_t drm_panic_qr_max_data_size(u8 version, size_t url_len); + +u8 drm_panic_qr_generate(const char *url, u8 *data, size_t data_len, size_t data_size, + u8 *tmp, size_t tmp_size); +#endif + #endif /* __DRM_PANIC_H__ */ diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h index f46cf3bb7069..ae39fc18a8bf 100644 --- a/rust/bindings/bindings_helper.h +++ b/rust/bindings/bindings_helper.h @@ -37,6 +37,11 @@ #include #include +#if defined(CONFIG_DRM_PANIC_SCREEN_QR_CODE) +// Used by `#[export]` in `drivers/gpu/drm/drm_panic_qr.rs`. +#include +#endif + /* `bindgen` gets confused at certain things. */ const size_t RUST_CONST_HELPER_ARCH_SLAB_MINALIGN = ARCH_SLAB_MINALIGN; const size_t RUST_CONST_HELPER_PAGE_SIZE = PAGE_SIZE; From 38559da6afb239e271e709588babe7f98195096b Mon Sep 17 00:00:00 2001 From: Guilherme Giacomo Simoes Date: Sun, 9 Mar 2025 14:57:11 -0300 Subject: [PATCH 15/71] rust: module: introduce `authors` key In the `module!` macro, the `author` field is currently of type `String`. Since modules can have multiple authors, this limitation prevents specifying more than one. Add an `authors` field as `Option>` to allow creating modules with multiple authors, and change the documentation and all current users to use it. Eventually, the single `author` field may be removed. [ The `modinfo` key needs to still be `author`; otherwise, tooling may not work properly, e.g.: $ modinfo --author samples/rust/rust_print.ko Rust for Linux Contributors I have also kept the original `author` field (undocumented), so that we can drop it more easily in a kernel cycle or two. - Miguel ] Suggested-by: Miguel Ojeda Link: https://github.com/Rust-for-Linux/linux/issues/244 Reviewed-by: Charalampos Mitrodimas Reviewed-by: Alice Ryhl Reviewed-by: Andreas Hindborg Signed-off-by: Guilherme Giacomo Simoes Link: https://lore.kernel.org/r/20250309175712.845622-2-trintaeoitogc@gmail.com [ Fixed `modinfo` key. Kept `author` field. Reworded message accordingly. Updated my email. - Miguel ] Signed-off-by: Miguel Ojeda --- drivers/block/rnull.rs | 2 +- drivers/net/phy/ax88796b_rust.rs | 2 +- drivers/net/phy/qt2025.rs | 2 +- rust/kernel/net/phy.rs | 4 ++-- rust/kernel/pci.rs | 2 +- rust/kernel/platform.rs | 2 +- rust/macros/lib.rs | 6 +++--- rust/macros/module.rs | 8 ++++++++ samples/rust/rust_driver_faux.rs | 2 +- samples/rust/rust_driver_pci.rs | 2 +- samples/rust/rust_driver_platform.rs | 2 +- samples/rust/rust_minimal.rs | 2 +- samples/rust/rust_misc_device.rs | 2 +- samples/rust/rust_print_main.rs | 2 +- 14 files changed, 24 insertions(+), 16 deletions(-) diff --git a/drivers/block/rnull.rs b/drivers/block/rnull.rs index ddf3629d8894..d07e76ae2c13 100644 --- a/drivers/block/rnull.rs +++ b/drivers/block/rnull.rs @@ -27,7 +27,7 @@ use kernel::{ module! { type: NullBlkModule, name: "rnull_mod", - author: "Andreas Hindborg", + authors: ["Andreas Hindborg"], description: "Rust implementation of the C null block driver", license: "GPL v2", } diff --git a/drivers/net/phy/ax88796b_rust.rs b/drivers/net/phy/ax88796b_rust.rs index 8c7eb009d9fc..bc73ebccc2aa 100644 --- a/drivers/net/phy/ax88796b_rust.rs +++ b/drivers/net/phy/ax88796b_rust.rs @@ -19,7 +19,7 @@ kernel::module_phy_driver! { DeviceId::new_with_driver::() ], name: "rust_asix_phy", - author: "FUJITA Tomonori ", + authors: ["FUJITA Tomonori "], description: "Rust Asix PHYs driver", license: "GPL", } diff --git a/drivers/net/phy/qt2025.rs b/drivers/net/phy/qt2025.rs index 1ab065798175..520daeb42089 100644 --- a/drivers/net/phy/qt2025.rs +++ b/drivers/net/phy/qt2025.rs @@ -26,7 +26,7 @@ kernel::module_phy_driver! { phy::DeviceId::new_with_driver::(), ], name: "qt2025_phy", - author: "FUJITA Tomonori ", + authors: ["FUJITA Tomonori "], description: "AMCC QT2025 PHY driver", license: "GPL", firmware: ["qt2025-2.0.3.3.fw"], diff --git a/rust/kernel/net/phy.rs b/rust/kernel/net/phy.rs index bb654a28dab3..a59469c785e3 100644 --- a/rust/kernel/net/phy.rs +++ b/rust/kernel/net/phy.rs @@ -790,7 +790,7 @@ impl DeviceMask { /// DeviceId::new_with_driver::() /// ], /// name: "rust_sample_phy", -/// author: "Rust for Linux Contributors", +/// authors: ["Rust for Linux Contributors"], /// description: "Rust sample PHYs driver", /// license: "GPL", /// } @@ -819,7 +819,7 @@ impl DeviceMask { /// module! { /// type: Module, /// name: "rust_sample_phy", -/// author: "Rust for Linux Contributors", +/// authors: ["Rust for Linux Contributors"], /// description: "Rust sample PHYs driver", /// license: "GPL", /// } diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs index 4c98b5b9aa1e..f7b2743828ae 100644 --- a/rust/kernel/pci.rs +++ b/rust/kernel/pci.rs @@ -103,7 +103,7 @@ impl Adapter { /// kernel::module_pci_driver! { /// type: MyDriver, /// name: "Module name", -/// author: "Author name", +/// authors: ["Author name"], /// description: "Description", /// license: "GPL v2", /// } diff --git a/rust/kernel/platform.rs b/rust/kernel/platform.rs index 50e6b0421813..1297f5292ba9 100644 --- a/rust/kernel/platform.rs +++ b/rust/kernel/platform.rs @@ -101,7 +101,7 @@ impl driver::Adapter for Adapter { /// kernel::module_platform_driver! { /// type: MyDriver, /// name: "Module name", -/// author: "Author name", +/// authors: ["Author name"], /// description: "Description", /// license: "GPL v2", /// } diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index a52443a3dbb9..8c7b786377ee 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -37,7 +37,7 @@ use proc_macro::TokenStream; /// module!{ /// type: MyModule, /// name: "my_kernel_module", -/// author: "Rust for Linux Contributors", +/// authors: ["Rust for Linux Contributors"], /// description: "My very own kernel module!", /// license: "GPL", /// alias: ["alternate_module_name"], @@ -70,7 +70,7 @@ use proc_macro::TokenStream; /// module!{ /// type: MyDeviceDriverModule, /// name: "my_device_driver_module", -/// author: "Rust for Linux Contributors", +/// authors: ["Rust for Linux Contributors"], /// description: "My device driver requires firmware", /// license: "GPL", /// firmware: ["my_device_firmware1.bin", "my_device_firmware2.bin"], @@ -89,7 +89,7 @@ use proc_macro::TokenStream; /// # Supported argument types /// - `type`: type which implements the [`Module`] trait (required). /// - `name`: ASCII string literal of the name of the kernel module (required). -/// - `author`: string literal of the author of the kernel module. +/// - `authors`: array of ASCII string literals of the authors of the kernel module. /// - `description`: string literal of the description of the kernel module. /// - `license`: ASCII string literal of the license of the kernel module (required). /// - `alias`: array of ASCII string literals of the alias names of the kernel module. diff --git a/rust/macros/module.rs b/rust/macros/module.rs index cdf94f4982df..42ed16c48b37 100644 --- a/rust/macros/module.rs +++ b/rust/macros/module.rs @@ -95,6 +95,7 @@ struct ModuleInfo { license: String, name: String, author: Option, + authors: Option>, description: Option, alias: Option>, firmware: Option>, @@ -108,6 +109,7 @@ impl ModuleInfo { "type", "name", "author", + "authors", "description", "license", "alias", @@ -136,6 +138,7 @@ impl ModuleInfo { "type" => info.type_ = expect_ident(it), "name" => info.name = expect_string_ascii(it), "author" => info.author = Some(expect_string(it)), + "authors" => info.authors = Some(expect_string_array(it)), "description" => info.description = Some(expect_string(it)), "license" => info.license = expect_string_ascii(it), "alias" => info.alias = Some(expect_string_array(it)), @@ -186,6 +189,11 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream { if let Some(author) = info.author { modinfo.emit("author", &author); } + if let Some(authors) = info.authors { + for author in authors { + modinfo.emit("author", &author); + } + } if let Some(description) = info.description { modinfo.emit("description", &description); } diff --git a/samples/rust/rust_driver_faux.rs b/samples/rust/rust_driver_faux.rs index 048c6cb98b29..378bab4b587d 100644 --- a/samples/rust/rust_driver_faux.rs +++ b/samples/rust/rust_driver_faux.rs @@ -7,7 +7,7 @@ use kernel::{c_str, faux, prelude::*, Module}; module! { type: SampleModule, name: "rust_faux_driver", - author: "Lyude Paul", + authors: ["Lyude Paul"], description: "Rust faux device sample", license: "GPL", } diff --git a/samples/rust/rust_driver_pci.rs b/samples/rust/rust_driver_pci.rs index 1fb6e44f3395..364a0660a743 100644 --- a/samples/rust/rust_driver_pci.rs +++ b/samples/rust/rust_driver_pci.rs @@ -104,7 +104,7 @@ impl Drop for SampleDriver { kernel::module_pci_driver! { type: SampleDriver, name: "rust_driver_pci", - author: "Danilo Krummrich", + authors: ["Danilo Krummrich"], description: "Rust PCI driver", license: "GPL v2", } diff --git a/samples/rust/rust_driver_platform.rs b/samples/rust/rust_driver_platform.rs index 8120609e2940..f7a0f1b29d1d 100644 --- a/samples/rust/rust_driver_platform.rs +++ b/samples/rust/rust_driver_platform.rs @@ -43,7 +43,7 @@ impl Drop for SampleDriver { kernel::module_platform_driver! { type: SampleDriver, name: "rust_driver_platform", - author: "Danilo Krummrich", + authors: ["Danilo Krummrich"], description: "Rust Platform driver", license: "GPL v2", } diff --git a/samples/rust/rust_minimal.rs b/samples/rust/rust_minimal.rs index 4aaf117bf8e3..1fc7a1be6b6d 100644 --- a/samples/rust/rust_minimal.rs +++ b/samples/rust/rust_minimal.rs @@ -7,7 +7,7 @@ use kernel::prelude::*; module! { type: RustMinimal, name: "rust_minimal", - author: "Rust for Linux Contributors", + authors: ["Rust for Linux Contributors"], description: "Rust minimal sample", license: "GPL", } diff --git a/samples/rust/rust_misc_device.rs b/samples/rust/rust_misc_device.rs index 40ad7266c225..d3785e7c0330 100644 --- a/samples/rust/rust_misc_device.rs +++ b/samples/rust/rust_misc_device.rs @@ -116,7 +116,7 @@ const RUST_MISC_DEV_SET_VALUE: u32 = _IOW::('|' as u32, 0x82); module! { type: RustMiscDeviceModule, name: "rust_misc_device", - author: "Lee Jones", + authors: ["Lee Jones"], description: "Rust misc device sample", license: "GPL", } diff --git a/samples/rust/rust_print_main.rs b/samples/rust/rust_print_main.rs index 7e8af5f176a3..8ea95e8c2f36 100644 --- a/samples/rust/rust_print_main.rs +++ b/samples/rust/rust_print_main.rs @@ -8,7 +8,7 @@ use kernel::prelude::*; module! { type: RustPrint, name: "rust_print", - author: "Rust for Linux Contributors", + authors: ["Rust for Linux Contributors"], description: "Rust printing macros sample", license: "GPL", } From ab2ebb7bc9d9af2f50b0ad54deb65e1d0b01bc70 Mon Sep 17 00:00:00 2001 From: Dirk Behme Date: Wed, 5 Mar 2025 06:34:37 +0100 Subject: [PATCH 16/71] rust: types: add intra-doc links for `Opaque` We use intra-doc links wherever possible. Thus add a couple missing ones for `Opaque`. Signed-off-by: Dirk Behme Reviewed-by: Alice Ryhl Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250305053438.1532397-1-dirk.behme@de.bosch.com [ Reworded. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/types.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs index 9cb573d39c34..5801eeb69dc5 100644 --- a/rust/kernel/types.rs +++ b/rust/kernel/types.rs @@ -251,7 +251,7 @@ impl Drop for ScopeGuard { /// Stores an opaque value. /// -/// `Opaque` is meant to be used with FFI objects that are never interpreted by Rust code. +/// [`Opaque`] is meant to be used with FFI objects that are never interpreted by Rust code. /// /// It is used to wrap structs from the C side, like for example `Opaque`. /// It gets rid of all the usual assumptions that Rust has for a value: @@ -266,7 +266,7 @@ impl Drop for ScopeGuard { /// This has to be used for all values that the C side has access to, because it can't be ensured /// that the C side is adhering to the usual constraints that Rust needs. /// -/// Using `Opaque` allows to continue to use references on the Rust side even for values shared +/// Using [`Opaque`] allows to continue to use references on the Rust side even for values shared /// with C. /// /// # Examples From 8a8afe9349fb91b604f10195984348e65d523daf Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:52 +0100 Subject: [PATCH 17/71] rust: hrtimer: introduce hrtimer support Add support for intrusive use of the hrtimer system. For now, only add support for embedding one timer per Rust struct. The hrtimer Rust API is based on the intrusive style pattern introduced by the Rust workqueue API. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Benno Lossin Reviewed-by: Tamir Duberstein Reviewed-by: Lyude Paul Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-1-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time.rs | 2 + rust/kernel/time/hrtimer.rs | 351 ++++++++++++++++++++++++++++++++++++ 2 files changed, 353 insertions(+) create mode 100644 rust/kernel/time/hrtimer.rs diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs index 379c0f5772e5..fab1dadfa589 100644 --- a/rust/kernel/time.rs +++ b/rust/kernel/time.rs @@ -8,6 +8,8 @@ //! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h). //! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h). +pub mod hrtimer; + /// The number of nanoseconds per millisecond. pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64; diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs new file mode 100644 index 000000000000..a3697622fa17 --- /dev/null +++ b/rust/kernel/time/hrtimer.rs @@ -0,0 +1,351 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Intrusive high resolution timers. +//! +//! Allows running timer callbacks without doing allocations at the time of +//! starting the timer. For now, only one timer per type is allowed. +//! +//! # Vocabulary +//! +//! States: +//! +//! - Stopped: initialized but not started, or cancelled, or not restarted. +//! - Started: initialized and started or restarted. +//! - Running: executing the callback. +//! +//! Operations: +//! +//! * Start +//! * Cancel +//! * Restart +//! +//! Events: +//! +//! * Expire +//! +//! ## State Diagram +//! +//! ```text +//! Return NoRestart +//! +---------------------------------------------------------------------+ +//! | | +//! | | +//! | | +//! | Return Restart | +//! | +------------------------+ | +//! | | | | +//! | | | | +//! v v | | +//! +-----------------+ Start +------------------+ +--------+-----+--+ +//! | +---------------->| | | | +//! Init | | | | Expire | | +//! --------->| Stopped | | Started +---------->| Running | +//! | | Cancel | | | | +//! | |<----------------+ | | | +//! +-----------------+ +---------------+--+ +-----------------+ +//! ^ | +//! | | +//! +---------+ +//! Restart +//! ``` +//! +//! +//! A timer is initialized in the **stopped** state. A stopped timer can be +//! **started** by the `start` operation, with an **expiry** time. After the +//! `start` operation, the timer is in the **started** state. When the timer +//! **expires**, the timer enters the **running** state and the handler is +//! executed. After the handler has returned, the timer may enter the +//! **started* or **stopped** state, depending on the return value of the +//! handler. A timer in the **started** or **running** state may be **canceled** +//! by the `cancel` operation. A timer that is cancelled enters the **stopped** +//! state. +//! +//! A `cancel` or `restart` operation on a timer in the **running** state takes +//! effect after the handler has returned and the timer has transitioned +//! out of the **running** state. +//! +//! A `restart` operation on a timer in the **stopped** state is equivalent to a +//! `start` operation. + +use crate::{init::PinInit, prelude::*, time::Ktime, types::Opaque}; +use core::marker::PhantomData; + +/// A timer backed by a C `struct hrtimer`. +/// +/// # Invariants +/// +/// * `self.timer` is initialized by `bindings::hrtimer_setup`. +#[pin_data] +#[repr(C)] +pub struct HrTimer { + #[pin] + timer: Opaque, + _t: PhantomData, +} + +// SAFETY: Ownership of an `HrTimer` can be moved to other threads and +// used/dropped from there. +unsafe impl Send for HrTimer {} + +// SAFETY: Timer operations are locked on the C side, so it is safe to operate +// on a timer from multiple threads. +unsafe impl Sync for HrTimer {} + +impl HrTimer { + /// Return an initializer for a new timer instance. + pub fn new() -> impl PinInit + where + T: HrTimerCallback, + { + pin_init!(Self { + // INVARIANT: We initialize `timer` with `hrtimer_setup` below. + timer <- Opaque::ffi_init(move |place: *mut bindings::hrtimer| { + // SAFETY: By design of `pin_init!`, `place` is a pointer to a + // live allocation. hrtimer_setup will initialize `place` and + // does not require `place` to be initialized prior to the call. + unsafe { + bindings::hrtimer_setup( + place, + Some(T::Pointer::run), + bindings::CLOCK_MONOTONIC as i32, + bindings::hrtimer_mode_HRTIMER_MODE_REL, + ); + } + }), + _t: PhantomData, + }) + } + + /// Get a pointer to the contained `bindings::hrtimer`. + /// + /// This function is useful to get access to the value without creating + /// intermediate references. + /// + /// # Safety + /// + /// `this` must point to a live allocation of at least the size of `Self`. + unsafe fn raw_get(this: *const Self) -> *mut bindings::hrtimer { + // SAFETY: The field projection to `timer` does not go out of bounds, + // because the caller of this function promises that `this` points to an + // allocation of at least the size of `Self`. + unsafe { Opaque::raw_get(core::ptr::addr_of!((*this).timer)) } + } + + /// Cancel an initialized and potentially running timer. + /// + /// If the timer handler is running, this function will block until the + /// handler returns. + /// + /// Note that the timer might be started by a concurrent start operation. If + /// so, the timer might not be in the **stopped** state when this function + /// returns. + /// + /// Users of the `HrTimer` API would not usually call this method directly. + /// Instead they would use the safe [`HrTimerHandle::cancel`] on the handle + /// returned when the timer was started. + /// + /// This function is useful to get access to the value without creating + /// intermediate references. + /// + /// # Safety + /// + /// `this` must point to a valid `Self`. + #[allow(dead_code)] + pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool { + // SAFETY: `this` points to an allocation of at least `HrTimer` size. + let c_timer_ptr = unsafe { HrTimer::raw_get(this) }; + + // If the handler is running, this will wait for the handler to return + // before returning. + // SAFETY: `c_timer_ptr` is initialized and valid. Synchronization is + // handled on the C side. + unsafe { bindings::hrtimer_cancel(c_timer_ptr) != 0 } + } +} + +/// Implemented by pointer types that point to structs that contain a [`HrTimer`]. +/// +/// `Self` must be [`Sync`] because it is passed to timer callbacks in another +/// thread of execution (hard or soft interrupt context). +/// +/// Starting a timer returns a [`HrTimerHandle`] that can be used to manipulate +/// the timer. Note that it is OK to call the start function repeatedly, and +/// that more than one [`HrTimerHandle`] associated with a [`HrTimerPointer`] may +/// exist. A timer can be manipulated through any of the handles, and a handle +/// may represent a cancelled timer. +pub trait HrTimerPointer: Sync + Sized { + /// A handle representing a started or restarted timer. + /// + /// If the timer is running or if the timer callback is executing when the + /// handle is dropped, the drop method of [`HrTimerHandle`] should not return + /// until the timer is stopped and the callback has completed. + /// + /// Note: When implementing this trait, consider that it is not unsafe to + /// leak the handle. + type TimerHandle: HrTimerHandle; + + /// Start the timer with expiry after `expires` time units. If the timer was + /// already running, it is restarted with the new expiry time. + fn start(self, expires: Ktime) -> Self::TimerHandle; +} + +/// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a +/// function to call. +// This is split from `HrTimerPointer` to make it easier to specify trait bounds. +pub trait RawHrTimerCallback { + /// Type of the parameter passed to [`HrTimerCallback::run`]. It may be + /// [`Self`], or a pointer type derived from [`Self`]. + type CallbackTarget<'a>; + + /// Callback to be called from C when timer fires. + /// + /// # Safety + /// + /// Only to be called by C code in the `hrtimer` subsystem. `this` must point + /// to the `bindings::hrtimer` structure that was used to start the timer. + unsafe extern "C" fn run(this: *mut bindings::hrtimer) -> bindings::hrtimer_restart; +} + +/// Implemented by structs that can be the target of a timer callback. +pub trait HrTimerCallback { + /// The type whose [`RawHrTimerCallback::run`] method will be invoked when + /// the timer expires. + type Pointer<'a>: RawHrTimerCallback; + + /// Called by the timer logic when the timer fires. + fn run(this: as RawHrTimerCallback>::CallbackTarget<'_>) + where + Self: Sized; +} + +/// A handle representing a potentially running timer. +/// +/// More than one handle representing the same timer might exist. +/// +/// # Safety +/// +/// When dropped, the timer represented by this handle must be cancelled, if it +/// is running. If the timer handler is running when the handle is dropped, the +/// drop method must wait for the handler to return before returning. +/// +/// Note: One way to satisfy the safety requirement is to call `Self::cancel` in +/// the drop implementation for `Self.` +pub unsafe trait HrTimerHandle { + /// Cancel the timer. If the timer is in the running state, block till the + /// handler has returned. + /// + /// Note that the timer might be started by a concurrent start operation. If + /// so, the timer might not be in the **stopped** state when this function + /// returns. + fn cancel(&mut self) -> bool; +} + +/// Implemented by structs that contain timer nodes. +/// +/// Clients of the timer API would usually safely implement this trait by using +/// the [`crate::impl_has_hr_timer`] macro. +/// +/// # Safety +/// +/// Implementers of this trait must ensure that the implementer has a +/// [`HrTimer`] field and that all trait methods are implemented according to +/// their documentation. All the methods of this trait must operate on the same +/// field. +pub unsafe trait HasHrTimer { + /// Return a pointer to the [`HrTimer`] within `Self`. + /// + /// This function is useful to get access to the value without creating + /// intermediate references. + /// + /// # Safety + /// + /// `this` must be a valid pointer. + unsafe fn raw_get_timer(this: *const Self) -> *const HrTimer; + + /// Return a pointer to the struct that is containing the [`HrTimer`] pointed + /// to by `ptr`. + /// + /// This function is useful to get access to the value without creating + /// intermediate references. + /// + /// # Safety + /// + /// `ptr` must point to a [`HrTimer`] field in a struct of type `Self`. + unsafe fn timer_container_of(ptr: *mut HrTimer) -> *mut Self + where + Self: Sized; + + /// Get pointer to the contained `bindings::hrtimer` struct. + /// + /// This function is useful to get access to the value without creating + /// intermediate references. + /// + /// # Safety + /// + /// `this` must be a valid pointer. + unsafe fn c_timer_ptr(this: *const Self) -> *const bindings::hrtimer { + // SAFETY: `this` is a valid pointer to a `Self`. + let timer_ptr = unsafe { Self::raw_get_timer(this) }; + + // SAFETY: timer_ptr points to an allocation of at least `HrTimer` size. + unsafe { HrTimer::raw_get(timer_ptr) } + } + + /// Start the timer contained in the `Self` pointed to by `self_ptr`. If + /// it is already running it is removed and inserted. + /// + /// # Safety + /// + /// - `this` must point to a valid `Self`. + /// - Caller must ensure that the pointee of `this` lives until the timer + /// fires or is canceled. + unsafe fn start(this: *const Self, expires: Ktime) { + // SAFETY: By function safety requirement, `this` is a valid `Self`. + unsafe { + bindings::hrtimer_start_range_ns( + Self::c_timer_ptr(this).cast_mut(), + expires.to_ns(), + 0, + bindings::hrtimer_mode_HRTIMER_MODE_REL, + ); + } + } +} + +/// Use to implement the [`HasHrTimer`] trait. +/// +/// See [`module`] documentation for an example. +/// +/// [`module`]: crate::time::hrtimer +#[macro_export] +macro_rules! impl_has_hr_timer { + ( + impl$({$($generics:tt)*})? + HasHrTimer<$timer_type:ty> + for $self:ty + { self.$field:ident } + $($rest:tt)* + ) => { + // SAFETY: This implementation of `raw_get_timer` only compiles if the + // field has the right type. + unsafe impl$(<$($generics)*>)? $crate::time::hrtimer::HasHrTimer<$timer_type> for $self { + + #[inline] + unsafe fn raw_get_timer( + this: *const Self, + ) -> *const $crate::time::hrtimer::HrTimer<$timer_type> { + // SAFETY: The caller promises that the pointer is not dangling. + unsafe { ::core::ptr::addr_of!((*this).$field) } + } + + #[inline] + unsafe fn timer_container_of( + ptr: *mut $crate::time::hrtimer::HrTimer<$timer_type>, + ) -> *mut Self { + // SAFETY: As per the safety requirement of this function, `ptr` + // is pointing inside a `$timer_type`. + unsafe { ::kernel::container_of!(ptr, $timer_type, $field).cast_mut() } + } + } + } +} From a0c6fa8b8a59f8901e182fada6ac0e1f65beaa00 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:53 +0100 Subject: [PATCH 18/71] rust: sync: add `Arc::as_ptr` Add a method to get a pointer to the data contained in an `Arc`. Reviewed-by: Lyude Paul Reviewed-by: Alice Ryhl Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-2-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/sync/arc.rs | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index 3cefda7a4372..1dfa75714f9d 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -246,6 +246,15 @@ impl Arc { unsafe { core::ptr::addr_of!((*ptr).data) } } + /// Return a raw pointer to the data in this arc. + pub fn as_ptr(this: &Self) -> *const T { + let ptr = this.ptr.as_ptr(); + + // SAFETY: As `ptr` points to a valid allocation of type `ArcInner`, + // field projection to `data`is within bounds of the allocation. + unsafe { core::ptr::addr_of!((*ptr).data) } + } + /// Recreates an [`Arc`] instance previously deconstructed via [`Arc::into_raw`]. /// /// # Safety @@ -539,11 +548,11 @@ impl ArcBorrow<'_, T> { } /// Creates an [`ArcBorrow`] to an [`Arc`] that has previously been deconstructed with - /// [`Arc::into_raw`]. + /// [`Arc::into_raw`] or [`Arc::as_ptr`]. /// /// # Safety /// - /// * The provided pointer must originate from a call to [`Arc::into_raw`]. + /// * The provided pointer must originate from a call to [`Arc::into_raw`] or [`Arc::as_ptr`]. /// * For the duration of the lifetime annotated on this `ArcBorrow`, the reference count must /// not hit zero. /// * For the duration of the lifetime annotated on this `ArcBorrow`, there must not be a From d7bf4786b5250b0e490a937d1f8a16ee3a54adbe Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:54 +0100 Subject: [PATCH 19/71] rust: hrtimer: implement `HrTimerPointer` for `Arc` Allow the use of intrusive `hrtimer` fields in structs that are managed by an `Arc` by implementing `HrTimerPointer` and `RawTimerCallbck` for `Arc`. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Lyude Paul Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-3-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 4 +- rust/kernel/time/hrtimer/arc.rs | 102 ++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/time/hrtimer/arc.rs diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index a3697622fa17..bfb536f2a490 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -150,7 +150,6 @@ impl HrTimer { /// # Safety /// /// `this` must point to a valid `Self`. - #[allow(dead_code)] pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool { // SAFETY: `this` points to an allocation of at least `HrTimer` size. let c_timer_ptr = unsafe { HrTimer::raw_get(this) }; @@ -349,3 +348,6 @@ macro_rules! impl_has_hr_timer { } } } + +mod arc; +pub use arc::ArcHrTimerHandle; diff --git a/rust/kernel/time/hrtimer/arc.rs b/rust/kernel/time/hrtimer/arc.rs new file mode 100644 index 000000000000..df97fade0aa1 --- /dev/null +++ b/rust/kernel/time/hrtimer/arc.rs @@ -0,0 +1,102 @@ +// SPDX-License-Identifier: GPL-2.0 + +use super::HasHrTimer; +use super::HrTimer; +use super::HrTimerCallback; +use super::HrTimerHandle; +use super::HrTimerPointer; +use super::RawHrTimerCallback; +use crate::sync::Arc; +use crate::sync::ArcBorrow; +use crate::time::Ktime; + +/// A handle for an `Arc>` returned by a call to +/// [`HrTimerPointer::start`]. +pub struct ArcHrTimerHandle +where + T: HasHrTimer, +{ + pub(crate) inner: Arc, +} + +// SAFETY: We implement drop below, and we cancel the timer in the drop +// implementation. +unsafe impl HrTimerHandle for ArcHrTimerHandle +where + T: HasHrTimer, +{ + fn cancel(&mut self) -> bool { + let self_ptr = Arc::as_ptr(&self.inner); + + // SAFETY: As we obtained `self_ptr` from a valid reference above, it + // must point to a valid `T`. + let timer_ptr = unsafe { >::raw_get_timer(self_ptr) }; + + // SAFETY: As `timer_ptr` points into `T` and `T` is valid, `timer_ptr` + // must point to a valid `HrTimer` instance. + unsafe { HrTimer::::raw_cancel(timer_ptr) } + } +} + +impl Drop for ArcHrTimerHandle +where + T: HasHrTimer, +{ + fn drop(&mut self) { + self.cancel(); + } +} + +impl HrTimerPointer for Arc +where + T: 'static, + T: Send + Sync, + T: HasHrTimer, + T: for<'a> HrTimerCallback = Self>, +{ + type TimerHandle = ArcHrTimerHandle; + + fn start(self, expires: Ktime) -> ArcHrTimerHandle { + // SAFETY: + // - We keep `self` alive by wrapping it in a handle below. + // - Since we generate the pointer passed to `start` from a valid + // reference, it is a valid pointer. + unsafe { T::start(Arc::as_ptr(&self), expires) }; + ArcHrTimerHandle { inner: self } + } +} + +impl RawHrTimerCallback for Arc +where + T: 'static, + T: HasHrTimer, + T: for<'a> HrTimerCallback = Self>, +{ + type CallbackTarget<'a> = ArcBorrow<'a, T>; + + unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart { + // `HrTimer` is `repr(C)` + let timer_ptr = ptr.cast::>(); + + // SAFETY: By C API contract `ptr` is the pointer we passed when + // queuing the timer, so it is a `HrTimer` embedded in a `T`. + let data_ptr = unsafe { T::timer_container_of(timer_ptr) }; + + // SAFETY: + // - `data_ptr` is derived form the pointer to the `T` that was used to + // queue the timer. + // - As per the safety requirements of the trait `HrTimerHandle`, the + // `ArcHrTimerHandle` associated with this timer is guaranteed to + // be alive until this method returns. That handle borrows the `T` + // behind `data_ptr` thus guaranteeing the validity of + // the `ArcBorrow` created below. + // - We own one refcount in the `ArcTimerHandle` associated with this + // timer, so it is not possible to get a `UniqueArc` to this + // allocation from other `Arc` clones. + let receiver = unsafe { ArcBorrow::from_raw(data_ptr) }; + + T::run(receiver); + + bindings::hrtimer_restart_HRTIMER_NORESTART + } +} From dc60dd0c688e794fefb6b3de8552b3c9452f812e Mon Sep 17 00:00:00 2001 From: Dirk Behme Date: Wed, 22 Jan 2025 06:47:19 +0100 Subject: [PATCH 20/71] rust: error: extend the Result documentation Extend the Result documentation by some guidelines and examples how to handle Result error cases gracefully. And how to not handle them. While at it fix one missing `Result` link in the existing documentation. [ Moved links out-of-line for improved readability. Fixed `srctree` link. Sorted out-of-line links. Added newlines for consistency with other docs. Applied paragraph break suggestion. Reworded slightly the docs in a couple places. Added Markdown. In addition, added `#[allow(clippy::single_match)` for the first example. It cannot be an `expect` since due to a difference introduced in Rust 1.85.0 when there are comments in the arms of the `match`. Reported it upstream, but it was intended: https://github.com/rust-lang/rust-clippy/issues/14418 Perhaps Clippy will lint about it in the future, but without autofix: https://github.com/rust-lang/rust-clippy/pull/14420 - Miguel ] Link: https://lore.kernel.org/rust-for-linux/CANiq72keOdXy0LFKk9SzYWwSjiD710v=hQO4xi+5E4xNALa6cA@mail.gmail.com/ Signed-off-by: Dirk Behme Reviewed-by: Fiona Behrens Link: https://lore.kernel.org/r/20250122054719.595878-1-dirk.behme@de.bosch.com Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 123 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 122 insertions(+), 1 deletion(-) diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index f6ecf09cb65f..376f6a6ae5e3 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -248,8 +248,129 @@ impl From for Error { /// [`Error`] as its error type. /// /// Note that even if a function does not return anything when it succeeds, -/// it should still be modeled as returning a `Result` rather than +/// it should still be modeled as returning a [`Result`] rather than /// just an [`Error`]. +/// +/// Calling a function that returns [`Result`] forces the caller to handle +/// the returned [`Result`]. +/// +/// This can be done "manually" by using [`match`]. Using [`match`] to decode +/// the [`Result`] is similar to C where all the return value decoding and the +/// error handling is done explicitly by writing handling code for each +/// error to cover. Using [`match`] the error and success handling can be +/// implemented in all detail as required. For example (inspired by +/// [`samples/rust/rust_minimal.rs`]): +/// +/// ``` +/// # #[allow(clippy::single_match)] +/// fn example() -> Result { +/// let mut numbers = KVec::new(); +/// +/// match numbers.push(72, GFP_KERNEL) { +/// Err(e) => { +/// pr_err!("Error pushing 72: {e:?}"); +/// return Err(e.into()); +/// } +/// // Do nothing, continue. +/// Ok(()) => (), +/// } +/// +/// match numbers.push(108, GFP_KERNEL) { +/// Err(e) => { +/// pr_err!("Error pushing 108: {e:?}"); +/// return Err(e.into()); +/// } +/// // Do nothing, continue. +/// Ok(()) => (), +/// } +/// +/// match numbers.push(200, GFP_KERNEL) { +/// Err(e) => { +/// pr_err!("Error pushing 200: {e:?}"); +/// return Err(e.into()); +/// } +/// // Do nothing, continue. +/// Ok(()) => (), +/// } +/// +/// Ok(()) +/// } +/// # example()?; +/// # Ok::<(), Error>(()) +/// ``` +/// +/// An alternative to be more concise is the [`if let`] syntax: +/// +/// ``` +/// fn example() -> Result { +/// let mut numbers = KVec::new(); +/// +/// if let Err(e) = numbers.push(72, GFP_KERNEL) { +/// pr_err!("Error pushing 72: {e:?}"); +/// return Err(e.into()); +/// } +/// +/// if let Err(e) = numbers.push(108, GFP_KERNEL) { +/// pr_err!("Error pushing 108: {e:?}"); +/// return Err(e.into()); +/// } +/// +/// if let Err(e) = numbers.push(200, GFP_KERNEL) { +/// pr_err!("Error pushing 200: {e:?}"); +/// return Err(e.into()); +/// } +/// +/// Ok(()) +/// } +/// # example()?; +/// # Ok::<(), Error>(()) +/// ``` +/// +/// Instead of these verbose [`match`]/[`if let`], the [`?`] operator can +/// be used to handle the [`Result`]. Using the [`?`] operator is often +/// the best choice to handle [`Result`] in a non-verbose way as done in +/// [`samples/rust/rust_minimal.rs`]: +/// +/// ``` +/// fn example() -> Result { +/// let mut numbers = KVec::new(); +/// +/// numbers.push(72, GFP_KERNEL)?; +/// numbers.push(108, GFP_KERNEL)?; +/// numbers.push(200, GFP_KERNEL)?; +/// +/// Ok(()) +/// } +/// # example()?; +/// # Ok::<(), Error>(()) +/// ``` +/// +/// Another possibility is to call [`unwrap()`](Result::unwrap) or +/// [`expect()`](Result::expect). However, use of these functions is +/// *heavily discouraged* in the kernel because they trigger a Rust +/// [`panic!`] if an error happens, which may destabilize the system or +/// entirely break it as a result -- just like the C [`BUG()`] macro. +/// Please see the documentation for the C macro [`BUG()`] for guidance +/// on when to use these functions. +/// +/// Alternatively, depending on the use case, using [`unwrap_or()`], +/// [`unwrap_or_else()`], [`unwrap_or_default()`] or [`unwrap_unchecked()`] +/// might be an option, as well. +/// +/// For even more details, please see the [Rust documentation]. +/// +/// [`match`]: https://doc.rust-lang.org/reference/expressions/match-expr.html +/// [`samples/rust/rust_minimal.rs`]: srctree/samples/rust/rust_minimal.rs +/// [`if let`]: https://doc.rust-lang.org/reference/expressions/if-expr.html#if-let-expressions +/// [`?`]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator +/// [`unwrap()`]: Result::unwrap +/// [`expect()`]: Result::expect +/// [`BUG()`]: https://docs.kernel.org/process/deprecated.html#bug-and-bug-on +/// [`unwrap_or()`]: Result::unwrap_or +/// [`unwrap_or_else()`]: Result::unwrap_or_else +/// [`unwrap_or_default()`]: Result::unwrap_or_default +/// [`unwrap_unchecked()`]: Result::unwrap_unchecked +/// [Rust documentation]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html pub type Result = core::result::Result; /// Converts an integer as returned by a C kernel function to an error if it's negative, and From 206dea39e55968d8f3ad56771507361eb799dfc7 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:03:51 +0000 Subject: [PATCH 21/71] rust: init: disable doctests The build system cannot handle doctests in the kernel crate in files outside of `rust/kernel/`. Subsequent commits will move files out of that directory, but will still compile them as part of the kernel crate. Thus ignore all doctests in the to-be-moved files. Leave tests disabled until they are separated into their own crate and they stop causing breakage. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-2-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/init.rs | 40 ++++++++++++++++++++-------------------- rust/macros/lib.rs | 8 ++++---- 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs index 7fd1ea8265a5..aa8df0595585 100644 --- a/rust/kernel/init.rs +++ b/rust/kernel/init.rs @@ -34,7 +34,7 @@ //! [`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 +//! ```rust,ignore //! # #![expect(clippy::disallowed_names)] //! use kernel::sync::{new_mutex, Mutex}; //! # use core::pin::Pin; @@ -54,7 +54,7 @@ //! `foo` now is of the type [`impl PinInit`]. We can now use any smart pointer that we like //! (or just the stack) to actually initialize a `Foo`: //! -//! ```rust +//! ```rust,ignore //! # #![expect(clippy::disallowed_names)] //! # use kernel::sync::{new_mutex, Mutex}; //! # use core::pin::Pin; @@ -78,7 +78,7 @@ //! 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 +//! ```rust,ignore //! # use kernel::sync::{new_mutex, Arc, Mutex}; //! let mtx: Result>> = //! Arc::pin_init(new_mutex!(42, "example::mtx"), GFP_KERNEL); @@ -86,7 +86,7 @@ //! //! To declare an init macro/function you just return an [`impl PinInit`]: //! -//! ```rust +//! ```rust,ignore //! # use kernel::{sync::Mutex, new_mutex, init::PinInit, try_pin_init}; //! #[pin_data] //! struct DriverData { @@ -119,7 +119,7 @@ //! - you may assume that `slot` will stay pinned even after the closure returns until `drop` of //! `slot` gets called. //! -//! ```rust +//! ```rust,ignore //! # #![expect(unreachable_pub, clippy::disallowed_names)] //! use kernel::{init, types::Opaque}; //! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin}; @@ -236,7 +236,7 @@ pub mod macros; /// /// # Examples /// -/// ```rust +/// ```rust,ignore /// # #![expect(clippy::disallowed_names)] /// # use kernel::{init, macros::pin_data, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex}; /// # use core::pin::Pin; @@ -382,7 +382,7 @@ macro_rules! stack_try_pin_init { /// /// The syntax is almost identical to that of a normal `struct` initializer: /// -/// ```rust +/// ```rust,ignore /// # use kernel::{init, pin_init, macros::pin_data, init::*}; /// # use core::pin::Pin; /// #[pin_data] @@ -426,7 +426,7 @@ macro_rules! stack_try_pin_init { /// /// To create an initializer function, simply declare it like this: /// -/// ```rust +/// ```rust,ignore /// # use kernel::{init, pin_init, init::*}; /// # use core::pin::Pin; /// # #[pin_data] @@ -452,7 +452,7 @@ macro_rules! stack_try_pin_init { /// /// Users of `Foo` can now create it like this: /// -/// ```rust +/// ```rust,ignore /// # #![expect(clippy::disallowed_names)] /// # use kernel::{init, pin_init, macros::pin_data, init::*}; /// # use core::pin::Pin; @@ -480,7 +480,7 @@ macro_rules! stack_try_pin_init { /// /// They can also easily embed it into their own `struct`s: /// -/// ```rust +/// ```rust,ignore /// # use kernel::{init, pin_init, macros::pin_data, init::*}; /// # use core::pin::Pin; /// # #[pin_data] @@ -539,7 +539,7 @@ macro_rules! stack_try_pin_init { /// /// For instance: /// -/// ```rust +/// ```rust,ignore /// # use kernel::{macros::{Zeroable, pin_data}, pin_init}; /// # use core::{ptr::addr_of_mut, marker::PhantomPinned}; /// #[pin_data] @@ -602,7 +602,7 @@ macro_rules! pin_init { /// /// # Examples /// -/// ```rust +/// ```rust,ignore /// use kernel::{init::{self, PinInit}, error::Error}; /// #[pin_data] /// struct BigBuf { @@ -705,7 +705,7 @@ macro_rules! init { /// /// # Examples /// -/// ```rust +/// ```rust,ignore /// use kernel::{alloc::KBox, init::{PinInit, zeroed}, error::Error}; /// struct BigBuf { /// big: KBox<[u8; 1024 * 1024 * 1024]>, @@ -761,7 +761,7 @@ macro_rules! try_init { /// # Example /// /// This will succeed: -/// ``` +/// ```ignore /// use kernel::assert_pinned; /// #[pin_data] /// struct MyStruct { @@ -787,7 +787,7 @@ macro_rules! try_init { /// Some uses of the macro may trigger the `can't use generic parameters from outer item` error. To /// work around this, you may pass the `inline` parameter to the macro. The `inline` parameter can /// only be used when the macro is invoked from a function body. -/// ``` +/// ```ignore /// use kernel::assert_pinned; /// #[pin_data] /// struct Foo { @@ -865,7 +865,7 @@ pub unsafe trait PinInit: Sized { /// /// # Examples /// - /// ```rust + /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] /// use kernel::{types::Opaque, init::pin_init_from_closure}; /// #[repr(C)] @@ -977,7 +977,7 @@ pub unsafe trait Init: PinInit { /// /// # Examples /// - /// ```rust + /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] /// use kernel::{types::Opaque, init::{self, init_from_closure}}; /// struct Foo { @@ -1089,7 +1089,7 @@ pub fn uninit() -> impl Init, E> { /// /// # Examples /// -/// ```rust +/// ```rust,ignore /// use kernel::{alloc::KBox, error::Error, init::init_array_from_fn}; /// let array: KBox<[usize; 1_000]> = /// KBox::init::(init_array_from_fn(|i| i), GFP_KERNEL)?; @@ -1134,7 +1134,7 @@ where /// /// # Examples /// -/// ```rust +/// ```rust,ignore /// use kernel::{sync::{Arc, Mutex}, init::pin_init_array_from_fn, new_mutex}; /// let array: Arc<[Mutex; 1_000]> = /// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL)?; @@ -1323,7 +1323,7 @@ impl InPlaceWrite for UniqueArc> { /// /// Use [`pinned_drop`] to implement this trait safely: /// -/// ```rust +/// ```rust,ignore /// # use kernel::sync::Mutex; /// use kernel::macros::pinned_drop; /// use core::pin::Pin; diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 8c7b786377ee..0bd97c3a4e30 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -272,7 +272,7 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream { /// /// # Examples /// -/// ``` +/// ```ignore /// # #![feature(lint_reasons)] /// # use kernel::prelude::*; /// # use std::{sync::Mutex, process::Command}; @@ -285,7 +285,7 @@ pub fn concat_idents(ts: TokenStream) -> TokenStream { /// } /// ``` /// -/// ``` +/// ```ignore /// # #![feature(lint_reasons)] /// # use kernel::prelude::*; /// # use std::{sync::Mutex, process::Command}; @@ -326,7 +326,7 @@ pub fn pin_data(inner: TokenStream, item: TokenStream) -> TokenStream { /// /// # Examples /// -/// ``` +/// ```ignore /// # #![feature(lint_reasons)] /// # use kernel::prelude::*; /// # use macros::{pin_data, pinned_drop}; @@ -502,7 +502,7 @@ pub fn paste(input: TokenStream) -> TokenStream { /// /// # Examples /// -/// ``` +/// ```ignore /// use kernel::macros::Zeroable; /// /// #[derive(Zeroable)] From fbf8fb328d1bfe3bd17d5c5626cb485a1ca1a50d Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:00 +0000 Subject: [PATCH 22/71] rust: move pin-init API into its own directory In preparation of splitting off the pin-init crate from the kernel crate, move all pin-init API code (including proc-macros) into `rust/pin-init`. Moved modules have their import path adjusted via the `#[path = "..."]` attribute. This allows the files to still be imported in the kernel crate even though the files are in different directories. Code that is moved out of files (but the file itself stays where it is) is imported via the `include!` macro. This also allows the code to be moved while still being part of the kernel crate. Note that this commit moves the generics parsing code out of the GPL-2.0 file `rust/macros/helpers.rs` into the Apache-2.0 OR MIT file `rust/pin_init/internal/src/helpers.rs`. I am the sole author of that code and it already is available with that license at [1]. The same is true for the entry-points of the proc-macros `pin_data`, `pinned_drop` and `derive_zeroable` in `rust/macros/lib.rs` that are moved to `rust/pin_data/internal/src/lib.rs`. Although there are some smaller patches that fix the doctests. Link: https://github.com/Rust-for-Linux/pinned-init [1] Signed-off-by: Benno Lossin Reviewed-by: Andreas Hindborg Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-3-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/lib.rs | 1 + rust/macros/helpers.rs | 148 +----------------- rust/macros/lib.rs | 124 +-------------- rust/pin-init/internal/src/helpers.rs | 147 +++++++++++++++++ rust/pin-init/internal/src/lib.rs | 122 +++++++++++++++ .../internal/src}/pin_data.rs | 0 .../internal/src}/pinned_drop.rs | 0 .../internal/src}/zeroable.rs | 0 .../init => pin-init/src}/__internal.rs | 0 rust/{kernel/init.rs => pin-init/src/lib.rs} | 0 rust/{kernel/init => pin-init/src}/macros.rs | 0 11 files changed, 276 insertions(+), 266 deletions(-) create mode 100644 rust/pin-init/internal/src/helpers.rs create mode 100644 rust/pin-init/internal/src/lib.rs rename rust/{macros => pin-init/internal/src}/pin_data.rs (100%) rename rust/{macros => pin-init/internal/src}/pinned_drop.rs (100%) rename rust/{macros => pin-init/internal/src}/zeroable.rs (100%) rename rust/{kernel/init => pin-init/src}/__internal.rs (100%) rename rust/{kernel/init.rs => pin-init/src/lib.rs} (100%) rename rust/{kernel/init => pin-init/src}/macros.rs (100%) diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 398242f92a96..c1b781371ba3 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -50,6 +50,7 @@ pub mod faux; #[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)] pub mod firmware; pub mod fs; +#[path = "../pin-init/src/lib.rs"] pub mod init; pub mod io; pub mod ioctl; diff --git a/rust/macros/helpers.rs b/rust/macros/helpers.rs index 3e04f8ecfc74..141d8476c197 100644 --- a/rust/macros/helpers.rs +++ b/rust/macros/helpers.rs @@ -70,152 +70,6 @@ pub(crate) fn expect_end(it: &mut token_stream::IntoIter) { } } -/// Parsed generics. -/// -/// See the field documentation for an explanation what each of the fields represents. -/// -/// # Examples -/// -/// ```rust,ignore -/// # let input = todo!(); -/// let (Generics { decl_generics, impl_generics, ty_generics }, rest) = parse_generics(input); -/// quote! { -/// struct Foo<$($decl_generics)*> { -/// // ... -/// } -/// -/// impl<$impl_generics> Foo<$ty_generics> { -/// fn foo() { -/// // ... -/// } -/// } -/// } -/// ``` -pub(crate) struct Generics { - /// The generics with bounds and default values (e.g. `T: Clone, const N: usize = 0`). - /// - /// Use this on type definitions e.g. `struct Foo<$decl_generics> ...` (or `union`/`enum`). - pub(crate) decl_generics: Vec, - /// The generics with bounds (e.g. `T: Clone, const N: usize`). - /// - /// Use this on `impl` blocks e.g. `impl<$impl_generics> Trait for ...`. - pub(crate) impl_generics: Vec, - /// The generics without bounds and without default values (e.g. `T, N`). - /// - /// Use this when you use the type that is declared with these generics e.g. - /// `Foo<$ty_generics>`. - pub(crate) ty_generics: Vec, -} - -/// Parses the given `TokenStream` into `Generics` and the rest. -/// -/// The generics are not present in the rest, but a where clause might remain. -pub(crate) fn parse_generics(input: TokenStream) -> (Generics, Vec) { - // The generics with bounds and default values. - let mut decl_generics = vec![]; - // `impl_generics`, the declared generics with their bounds. - let mut impl_generics = vec![]; - // Only the names of the generics, without any bounds. - let mut ty_generics = vec![]; - // Tokens not related to the generics e.g. the `where` token and definition. - let mut rest = vec![]; - // The current level of `<`. - let mut nesting = 0; - let mut toks = input.into_iter(); - // If we are at the beginning of a generic parameter. - let mut at_start = true; - let mut skip_until_comma = false; - while let Some(tt) = toks.next() { - if nesting == 1 && matches!(&tt, TokenTree::Punct(p) if p.as_char() == '>') { - // Found the end of the generics. - break; - } else if nesting >= 1 { - decl_generics.push(tt.clone()); - } - match tt.clone() { - TokenTree::Punct(p) if p.as_char() == '<' => { - if nesting >= 1 && !skip_until_comma { - // This is inside of the generics and part of some bound. - impl_generics.push(tt); - } - nesting += 1; - } - TokenTree::Punct(p) if p.as_char() == '>' => { - // This is a parsing error, so we just end it here. - if nesting == 0 { - break; - } else { - nesting -= 1; - if nesting >= 1 && !skip_until_comma { - // We are still inside of the generics and part of some bound. - impl_generics.push(tt); - } - } - } - TokenTree::Punct(p) if skip_until_comma && p.as_char() == ',' => { - if nesting == 1 { - impl_generics.push(tt.clone()); - impl_generics.push(tt); - skip_until_comma = false; - } - } - _ if !skip_until_comma => { - match nesting { - // If we haven't entered the generics yet, we still want to keep these tokens. - 0 => rest.push(tt), - 1 => { - // Here depending on the token, it might be a generic variable name. - match tt.clone() { - TokenTree::Ident(i) if at_start && i.to_string() == "const" => { - let Some(name) = toks.next() else { - // Parsing error. - break; - }; - impl_generics.push(tt); - impl_generics.push(name.clone()); - ty_generics.push(name.clone()); - decl_generics.push(name); - at_start = false; - } - TokenTree::Ident(_) if at_start => { - impl_generics.push(tt.clone()); - ty_generics.push(tt); - at_start = false; - } - TokenTree::Punct(p) if p.as_char() == ',' => { - impl_generics.push(tt.clone()); - ty_generics.push(tt); - at_start = true; - } - // Lifetimes begin with `'`. - TokenTree::Punct(p) if p.as_char() == '\'' && at_start => { - impl_generics.push(tt.clone()); - ty_generics.push(tt); - } - // Generics can have default values, we skip these. - TokenTree::Punct(p) if p.as_char() == '=' => { - skip_until_comma = true; - } - _ => impl_generics.push(tt), - } - } - _ => impl_generics.push(tt), - } - } - _ => {} - } - } - rest.extend(toks); - ( - Generics { - impl_generics, - decl_generics, - ty_generics, - }, - rest, - ) -} - /// Given a function declaration, finds the name of the function. pub(crate) fn function_name(input: TokenStream) -> Option { let mut input = input.into_iter(); @@ -232,3 +86,5 @@ pub(crate) fn function_name(input: TokenStream) -> Option { } None } + +include!("../pin-init/internal/src/helpers.rs"); diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 0bd97c3a4e30..ba93dd686e38 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -13,9 +13,12 @@ mod export; mod helpers; mod module; mod paste; +#[path = "../pin-init/internal/src/pin_data.rs"] mod pin_data; +#[path = "../pin-init/internal/src/pinned_drop.rs"] mod pinned_drop; mod vtable; +#[path = "../pin-init/internal/src/zeroable.rs"] mod zeroable; use proc_macro::TokenStream; @@ -256,106 +259,6 @@ 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 initializer 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 -/// -/// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use std::{sync::Mutex, process::Command}; -/// # use kernel::macros::pin_data; -/// #[pin_data] -/// struct DriverData { -/// #[pin] -/// queue: Mutex>, -/// buf: KBox<[u8; 1024 * 1024]>, -/// } -/// ``` -/// -/// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use std::{sync::Mutex, process::Command}; -/// # use core::pin::Pin; -/// # pub struct Info; -/// # mod bindings { -/// # pub unsafe fn destroy_info(_ptr: *mut super::Info) {} -/// # } -/// use kernel::macros::{pin_data, pinned_drop}; -/// -/// #[pin_data(PinnedDrop)] -/// struct DriverData { -/// #[pin] -/// queue: Mutex>, -/// buf: KBox<[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) }; -/// } -/// } -/// # fn main() {} -/// ``` -/// -/// [`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 -/// -/// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use macros::{pin_data, pinned_drop}; -/// # use std::{sync::Mutex, process::Command}; -/// # use core::pin::Pin; -/// # mod bindings { -/// # pub struct Info; -/// # pub unsafe fn destroy_info(_ptr: *mut Info) {} -/// # } -/// #[pin_data(PinnedDrop)] -/// struct DriverData { -/// #[pin] -/// queue: Mutex>, -/// buf: KBox<[u8; 1024 * 1024]>, -/// raw_info: *mut bindings::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) -} - /// Paste identifiers together. /// /// Within the `paste!` macro, identifiers inside `[<` and `>]` are concatenated together to form a @@ -496,23 +399,4 @@ pub fn paste(input: TokenStream) -> TokenStream { tokens.into_iter().collect() } -/// Derives the [`Zeroable`] trait for the given struct. -/// -/// This can only be used for structs where every field implements the [`Zeroable`] trait. -/// -/// # Examples -/// -/// ```ignore -/// use kernel::macros::Zeroable; -/// -/// #[derive(Zeroable)] -/// pub struct DriverData { -/// id: i64, -/// buf_ptr: *mut u8, -/// len: usize, -/// } -/// ``` -#[proc_macro_derive(Zeroable)] -pub fn derive_zeroable(input: TokenStream) -> TokenStream { - zeroable::derive(input) -} +include!("../pin-init/internal/src/lib.rs"); diff --git a/rust/pin-init/internal/src/helpers.rs b/rust/pin-init/internal/src/helpers.rs new file mode 100644 index 000000000000..2f4fc75c014e --- /dev/null +++ b/rust/pin-init/internal/src/helpers.rs @@ -0,0 +1,147 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +/// Parsed generics. +/// +/// See the field documentation for an explanation what each of the fields represents. +/// +/// # Examples +/// +/// ```rust,ignore +/// # let input = todo!(); +/// let (Generics { decl_generics, impl_generics, ty_generics }, rest) = parse_generics(input); +/// quote! { +/// struct Foo<$($decl_generics)*> { +/// // ... +/// } +/// +/// impl<$impl_generics> Foo<$ty_generics> { +/// fn foo() { +/// // ... +/// } +/// } +/// } +/// ``` +pub(crate) struct Generics { + /// The generics with bounds and default values (e.g. `T: Clone, const N: usize = 0`). + /// + /// Use this on type definitions e.g. `struct Foo<$decl_generics> ...` (or `union`/`enum`). + pub(crate) decl_generics: Vec, + /// The generics with bounds (e.g. `T: Clone, const N: usize`). + /// + /// Use this on `impl` blocks e.g. `impl<$impl_generics> Trait for ...`. + pub(crate) impl_generics: Vec, + /// The generics without bounds and without default values (e.g. `T, N`). + /// + /// Use this when you use the type that is declared with these generics e.g. + /// `Foo<$ty_generics>`. + pub(crate) ty_generics: Vec, +} + +/// Parses the given `TokenStream` into `Generics` and the rest. +/// +/// The generics are not present in the rest, but a where clause might remain. +pub(crate) fn parse_generics(input: TokenStream) -> (Generics, Vec) { + // The generics with bounds and default values. + let mut decl_generics = vec![]; + // `impl_generics`, the declared generics with their bounds. + let mut impl_generics = vec![]; + // Only the names of the generics, without any bounds. + let mut ty_generics = vec![]; + // Tokens not related to the generics e.g. the `where` token and definition. + let mut rest = vec![]; + // The current level of `<`. + let mut nesting = 0; + let mut toks = input.into_iter(); + // If we are at the beginning of a generic parameter. + let mut at_start = true; + let mut skip_until_comma = false; + while let Some(tt) = toks.next() { + if nesting == 1 && matches!(&tt, TokenTree::Punct(p) if p.as_char() == '>') { + // Found the end of the generics. + break; + } else if nesting >= 1 { + decl_generics.push(tt.clone()); + } + match tt.clone() { + TokenTree::Punct(p) if p.as_char() == '<' => { + if nesting >= 1 && !skip_until_comma { + // This is inside of the generics and part of some bound. + impl_generics.push(tt); + } + nesting += 1; + } + TokenTree::Punct(p) if p.as_char() == '>' => { + // This is a parsing error, so we just end it here. + if nesting == 0 { + break; + } else { + nesting -= 1; + if nesting >= 1 && !skip_until_comma { + // We are still inside of the generics and part of some bound. + impl_generics.push(tt); + } + } + } + TokenTree::Punct(p) if skip_until_comma && p.as_char() == ',' => { + if nesting == 1 { + impl_generics.push(tt.clone()); + impl_generics.push(tt); + skip_until_comma = false; + } + } + _ if !skip_until_comma => { + match nesting { + // If we haven't entered the generics yet, we still want to keep these tokens. + 0 => rest.push(tt), + 1 => { + // Here depending on the token, it might be a generic variable name. + match tt.clone() { + TokenTree::Ident(i) if at_start && i.to_string() == "const" => { + let Some(name) = toks.next() else { + // Parsing error. + break; + }; + impl_generics.push(tt); + impl_generics.push(name.clone()); + ty_generics.push(name.clone()); + decl_generics.push(name); + at_start = false; + } + TokenTree::Ident(_) if at_start => { + impl_generics.push(tt.clone()); + ty_generics.push(tt); + at_start = false; + } + TokenTree::Punct(p) if p.as_char() == ',' => { + impl_generics.push(tt.clone()); + ty_generics.push(tt); + at_start = true; + } + // Lifetimes begin with `'`. + TokenTree::Punct(p) if p.as_char() == '\'' && at_start => { + impl_generics.push(tt.clone()); + ty_generics.push(tt); + } + // Generics can have default values, we skip these. + TokenTree::Punct(p) if p.as_char() == '=' => { + skip_until_comma = true; + } + _ => impl_generics.push(tt), + } + } + _ => impl_generics.push(tt), + } + } + _ => {} + } + } + rest.extend(toks); + ( + Generics { + impl_generics, + decl_generics, + ty_generics, + }, + rest, + ) +} diff --git a/rust/pin-init/internal/src/lib.rs b/rust/pin-init/internal/src/lib.rs new file mode 100644 index 000000000000..0a2761cc793c --- /dev/null +++ b/rust/pin-init/internal/src/lib.rs @@ -0,0 +1,122 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +/// 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 initializer 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 +/// +/// ```ignore +/// # #![feature(lint_reasons)] +/// # use kernel::prelude::*; +/// # use std::{sync::Mutex, process::Command}; +/// # use kernel::macros::pin_data; +/// #[pin_data] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: KBox<[u8; 1024 * 1024]>, +/// } +/// ``` +/// +/// ```ignore +/// # #![feature(lint_reasons)] +/// # use kernel::prelude::*; +/// # use std::{sync::Mutex, process::Command}; +/// # use core::pin::Pin; +/// # pub struct Info; +/// # mod bindings { +/// # pub unsafe fn destroy_info(_ptr: *mut super::Info) {} +/// # } +/// use kernel::macros::{pin_data, pinned_drop}; +/// +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: KBox<[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) }; +/// } +/// } +/// # fn main() {} +/// ``` +/// +/// [`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 +/// +/// ```ignore +/// # #![feature(lint_reasons)] +/// # use kernel::prelude::*; +/// # use macros::{pin_data, pinned_drop}; +/// # use std::{sync::Mutex, process::Command}; +/// # use core::pin::Pin; +/// # mod bindings { +/// # pub struct Info; +/// # pub unsafe fn destroy_info(_ptr: *mut Info) {} +/// # } +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: KBox<[u8; 1024 * 1024]>, +/// raw_info: *mut bindings::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) +} + +/// Derives the [`Zeroable`] trait for the given struct. +/// +/// This can only be used for structs where every field implements the [`Zeroable`] trait. +/// +/// # Examples +/// +/// ```ignore +/// use kernel::macros::Zeroable; +/// +/// #[derive(Zeroable)] +/// pub struct DriverData { +/// id: i64, +/// buf_ptr: *mut u8, +/// len: usize, +/// } +/// ``` +#[proc_macro_derive(Zeroable)] +pub fn derive_zeroable(input: TokenStream) -> TokenStream { + zeroable::derive(input) +} diff --git a/rust/macros/pin_data.rs b/rust/pin-init/internal/src/pin_data.rs similarity index 100% rename from rust/macros/pin_data.rs rename to rust/pin-init/internal/src/pin_data.rs diff --git a/rust/macros/pinned_drop.rs b/rust/pin-init/internal/src/pinned_drop.rs similarity index 100% rename from rust/macros/pinned_drop.rs rename to rust/pin-init/internal/src/pinned_drop.rs diff --git a/rust/macros/zeroable.rs b/rust/pin-init/internal/src/zeroable.rs similarity index 100% rename from rust/macros/zeroable.rs rename to rust/pin-init/internal/src/zeroable.rs diff --git a/rust/kernel/init/__internal.rs b/rust/pin-init/src/__internal.rs similarity index 100% rename from rust/kernel/init/__internal.rs rename to rust/pin-init/src/__internal.rs diff --git a/rust/kernel/init.rs b/rust/pin-init/src/lib.rs similarity index 100% rename from rust/kernel/init.rs rename to rust/pin-init/src/lib.rs diff --git a/rust/kernel/init/macros.rs b/rust/pin-init/src/macros.rs similarity index 100% rename from rust/kernel/init/macros.rs rename to rust/pin-init/src/macros.rs From 86f7dacadeecb9e6cc3e79571fed790b5147652a Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:07 +0000 Subject: [PATCH 23/71] rust: add extensions to the pin-init crate and move relevant documentation there In preparation of splitting off the pin-init crate from the kernel crate, move all kernel-specific documentation from pin-init back into the kernel crate. Also include an example from the user-space version [1] adapted to the kernel. The new `init.rs` file will also be populated by kernel-specific extensions to the pin-init crate by the next commits. Link: https://github.com/Rust-for-Linux/pin-init/blob/c1417c64c71229f0fd444d75e88f33e3c547c829/src/lib.rs#L161 [1] Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-4-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/init.rs | 135 +++++++++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 3 + rust/pin-init/src/lib.rs | 14 ---- 3 files changed, 138 insertions(+), 14 deletions(-) create mode 100644 rust/kernel/init.rs diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs new file mode 100644 index 000000000000..322dfd9ec347 --- /dev/null +++ b/rust/kernel/init.rs @@ -0,0 +1,135 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Extensions to the [`pin-init`] crate. +//! +//! 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. +//! +//! The [`pin-init`] crate is the way such structs are initialized on the Rust side. Please refer +//! to its documentation to better understand how to use it. Additionally, there are many examples +//! throughout the kernel, such as the types from the [`sync`] module. And the ones presented +//! below. +//! +//! [`sync`]: crate::sync +//! [pinning]: https://doc.rust-lang.org/std/pin/index.html +//! [`pin-init`]: https://rust.docs.kernel.org/pin_init/ +//! +//! # [`Opaque`] +//! +//! For the special case where initializing a field is a single FFI-function call that cannot fail, +//! there exist the helper function [`Opaque::ffi_init`]. This function initialize a single +//! [`Opaque`] field by just delegating to the supplied closure. You can use these in +//! combination with [`pin_init!`]. +//! +//! [`Opaque`]: crate::types::Opaque +//! [`Opaque::ffi_init`]: crate::types::Opaque::ffi_init +//! [`pin_init!`]: crate::pin_init +//! +//! # Examples +//! +//! ## General Examples +//! +//! ```rust,ignore +//! # #![allow(clippy::disallowed_names)] +//! use kernel::types::Opaque; +//! use pin_init::pin_init_from_closure; +//! +//! // assume we have some `raw_foo` type in C: +//! #[repr(C)] +//! struct RawFoo([u8; 16]); +//! extern { +//! fn init_foo(_: *mut RawFoo); +//! } +//! +//! #[pin_data] +//! struct Foo { +//! #[pin] +//! raw: Opaque, +//! } +//! +//! impl Foo { +//! fn setup(self: Pin<&mut Self>) { +//! pr_info!("Setting up foo"); +//! } +//! } +//! +//! let foo = pin_init!(Foo { +//! raw <- unsafe { +//! Opaque::ffi_init(|s| { +//! // note that this cannot fail. +//! init_foo(s); +//! }) +//! }, +//! }).pin_chain(|foo| { +//! foo.setup(); +//! Ok(()) +//! }); +//! ``` +//! +//! ```rust,ignore +//! # #![allow(unreachable_pub, clippy::disallowed_names)] +//! use kernel::{prelude::*, types::Opaque}; +//! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin}; +//! # mod bindings { +//! # #![allow(non_camel_case_types)] +//! # 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 } +//! # } +//! # // `Error::from_errno` is `pub(crate)` in the `kernel` crate, thus provide a workaround. +//! # trait FromErrno { +//! # fn from_errno(errno: core::ffi::c_int) -> Error { +//! # // Dummy error that can be constructed outside the `kernel` crate. +//! # Error::from(core::fmt::Error) +//! # } +//! # } +//! # impl FromErrno for Error {} +//! /// # Invariants +//! /// +//! /// `foo` is always initialized +//! #[pin_data(PinnedDrop)] +//! pub struct RawFoo { +//! #[pin] +//! foo: Opaque, +//! #[pin] +//! _p: PhantomPinned, +//! } +//! +//! impl RawFoo { +//! pub fn new(flags: u32) -> impl PinInit { +//! // 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 { +//! pin_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_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()) }; +//! } +//! } +//! ``` diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index c1b781371ba3..e3933f3dfc0b 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -52,6 +52,9 @@ pub mod firmware; pub mod fs; #[path = "../pin-init/src/lib.rs"] pub mod init; +// momentarily use the name `init_ext` and set the path manually +#[path = "init.rs"] +pub mod init_ext; pub mod io; pub mod ioctl; pub mod jump_label; diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index aa8df0595585..0307a08ccee9 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -5,9 +5,6 @@ //! 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: @@ -188,15 +185,6 @@ //! } //! ``` //! -//! For the special case where initializing a field is a single FFI-function call that cannot fail, -//! there exist the helper function [`Opaque::ffi_init`]. This function initialize a single -//! [`Opaque`] field by just delegating to the supplied closure. You can use these in combination -//! with [`pin_init!`]. -//! -//! For more information on how to use [`pin_init_from_closure()`], take a look at the uses inside -//! the `kernel` crate. The [`sync`] module is a good starting point. -//! -//! [`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 @@ -205,8 +193,6 @@ //! [`impl PinInit`]: PinInit //! [`impl PinInit`]: PinInit //! [`impl Init`]: Init -//! [`Opaque`]: kernel::types::Opaque -//! [`Opaque::ffi_init`]: kernel::types::Opaque::ffi_init //! [`pin_data`]: ::macros::pin_data //! [`pin_init!`]: crate::pin_init! From 4b11798e82d6f340c2afc94c57823b6fbc109fad Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:10 +0000 Subject: [PATCH 24/71] rust: pin-init: move proc-macro documentation into pin-init crate Move the documentation of proc-macros from pin-init-internal into pin-init. This is because documentation can only reference types from dependencies and pin-init-internal cannot have pin-init as a dependency, as that would be cyclic. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-5-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/internal/src/lib.rs | 109 +---------------------------- rust/pin-init/src/lib.rs | 111 ++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 106 deletions(-) diff --git a/rust/pin-init/internal/src/lib.rs b/rust/pin-init/internal/src/lib.rs index 0a2761cc793c..bf66cbee2531 100644 --- a/rust/pin-init/internal/src/lib.rs +++ b/rust/pin-init/internal/src/lib.rs @@ -1,121 +1,18 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT -/// 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 initializer 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 -/// -/// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use std::{sync::Mutex, process::Command}; -/// # use kernel::macros::pin_data; -/// #[pin_data] -/// struct DriverData { -/// #[pin] -/// queue: Mutex>, -/// buf: KBox<[u8; 1024 * 1024]>, -/// } -/// ``` -/// -/// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use std::{sync::Mutex, process::Command}; -/// # use core::pin::Pin; -/// # pub struct Info; -/// # mod bindings { -/// # pub unsafe fn destroy_info(_ptr: *mut super::Info) {} -/// # } -/// use kernel::macros::{pin_data, pinned_drop}; -/// -/// #[pin_data(PinnedDrop)] -/// struct DriverData { -/// #[pin] -/// queue: Mutex>, -/// buf: KBox<[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) }; -/// } -/// } -/// # fn main() {} -/// ``` -/// -/// [`pin_init!`]: ../kernel/macro.pin_init.html -// ^ cannot use direct link, since `kernel` is not a dependency of `macros`. +#[allow(missing_docs)] #[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 -/// -/// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use macros::{pin_data, pinned_drop}; -/// # use std::{sync::Mutex, process::Command}; -/// # use core::pin::Pin; -/// # mod bindings { -/// # pub struct Info; -/// # pub unsafe fn destroy_info(_ptr: *mut Info) {} -/// # } -/// #[pin_data(PinnedDrop)] -/// struct DriverData { -/// #[pin] -/// queue: Mutex>, -/// buf: KBox<[u8; 1024 * 1024]>, -/// raw_info: *mut bindings::Info, -/// } -/// -/// #[pinned_drop] -/// impl PinnedDrop for DriverData { -/// fn drop(self: Pin<&mut Self>) { -/// unsafe { bindings::destroy_info(self.raw_info) }; -/// } -/// } -/// ``` +#[allow(missing_docs)] #[proc_macro_attribute] pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream { pinned_drop::pinned_drop(args, input) } -/// Derives the [`Zeroable`] trait for the given struct. -/// -/// This can only be used for structs where every field implements the [`Zeroable`] trait. -/// -/// # Examples -/// -/// ```ignore -/// use kernel::macros::Zeroable; -/// -/// #[derive(Zeroable)] -/// pub struct DriverData { -/// id: i64, -/// buf_ptr: *mut u8, -/// len: usize, -/// } -/// ``` +#[allow(missing_docs)] #[proc_macro_derive(Zeroable)] pub fn derive_zeroable(input: TokenStream) -> TokenStream { zeroable::derive(input) diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index 0307a08ccee9..df6962460874 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -218,6 +218,117 @@ pub mod __internal; #[doc(hidden)] pub mod macros; +/// 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 initializer 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 +/// +/// ```ignore +/// # #![feature(lint_reasons)] +/// # use kernel::prelude::*; +/// # use std::{sync::Mutex, process::Command}; +/// # use kernel::macros::pin_data; +/// #[pin_data] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: KBox<[u8; 1024 * 1024]>, +/// } +/// ``` +/// +/// ```ignore +/// # #![feature(lint_reasons)] +/// # use kernel::prelude::*; +/// # use std::{sync::Mutex, process::Command}; +/// # use core::pin::Pin; +/// # pub struct Info; +/// # mod bindings { +/// # pub unsafe fn destroy_info(_ptr: *mut super::Info) {} +/// # } +/// use kernel::macros::{pin_data, pinned_drop}; +/// +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: KBox<[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) }; +/// } +/// } +/// # fn main() {} +/// ``` +/// +/// [`pin_init!`]: crate::pin_init +pub use ::macros::pin_data; + +/// Used to implement `PinnedDrop` safely. +/// +/// Only works on structs that are annotated via `#[`[`macro@pin_data`]`]`. +/// +/// # Examples +/// +/// ```ignore +/// # #![feature(lint_reasons)] +/// # use kernel::prelude::*; +/// # use macros::{pin_data, pinned_drop}; +/// # use std::{sync::Mutex, process::Command}; +/// # use core::pin::Pin; +/// # mod bindings { +/// # pub struct Info; +/// # pub unsafe fn destroy_info(_ptr: *mut Info) {} +/// # } +/// #[pin_data(PinnedDrop)] +/// struct DriverData { +/// #[pin] +/// queue: Mutex>, +/// buf: KBox<[u8; 1024 * 1024]>, +/// raw_info: *mut bindings::Info, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for DriverData { +/// fn drop(self: Pin<&mut Self>) { +/// unsafe { bindings::destroy_info(self.raw_info) }; +/// } +/// } +/// ``` +pub use ::macros::pinned_drop; + +/// Derives the [`Zeroable`] trait for the given struct. +/// +/// This can only be used for structs where every field implements the [`Zeroable`] trait. +/// +/// # Examples +/// +/// ```ignore +/// use kernel::macros::Zeroable; +/// +/// #[derive(Zeroable)] +/// pub struct DriverData { +/// id: i64, +/// buf_ptr: *mut u8, +/// len: usize, +/// } +/// ``` +pub use ::macros::Zeroable; + /// Initialize and pin a type directly on the stack. /// /// # Examples From 84837cf6fa541150a3012ea233225a7ecfa8771a Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:18 +0000 Subject: [PATCH 25/71] rust: pin-init: change examples to the user-space version Replace the examples in the documentation by the ones from the user-space version and introduce the standalone examples from the user-space version such as the `CMutex` type. The `CMutex` example from the pinned-init repository [1] is used in several documentation examples in the user-space version instead of the kernel `Mutex` type (as it's not available). In order to split off the pin-init crate, all examples need to be free of kernel-specific types. Link: https://github.com/rust-for-Linux/pinned-init [1] Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-6-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/examples/big_struct_in_place.rs | 39 ++ rust/pin-init/examples/error.rs | 27 ++ rust/pin-init/examples/linked_list.rs | 161 ++++++++ rust/pin-init/examples/mutex.rs | 209 ++++++++++ rust/pin-init/examples/pthread_mutex.rs | 178 +++++++++ rust/pin-init/examples/static_init.rs | 122 ++++++ rust/pin-init/src/lib.rs | 365 +++++++++--------- 7 files changed, 915 insertions(+), 186 deletions(-) create mode 100644 rust/pin-init/examples/big_struct_in_place.rs create mode 100644 rust/pin-init/examples/error.rs create mode 100644 rust/pin-init/examples/linked_list.rs create mode 100644 rust/pin-init/examples/mutex.rs create mode 100644 rust/pin-init/examples/pthread_mutex.rs create mode 100644 rust/pin-init/examples/static_init.rs diff --git a/rust/pin-init/examples/big_struct_in_place.rs b/rust/pin-init/examples/big_struct_in_place.rs new file mode 100644 index 000000000000..30d44a334ffd --- /dev/null +++ b/rust/pin-init/examples/big_struct_in_place.rs @@ -0,0 +1,39 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +use pin_init::*; + +// Struct with size over 1GiB +#[derive(Debug)] +pub struct BigStruct { + buf: [u8; 1024 * 1024 * 1024], + a: u64, + b: u64, + c: u64, + d: u64, + managed_buf: ManagedBuf, +} + +#[derive(Debug)] +pub struct ManagedBuf { + buf: [u8; 1024 * 1024], +} + +impl ManagedBuf { + pub fn new() -> impl Init { + init!(ManagedBuf { buf <- zeroed() }) + } +} + +fn main() { + // we want to initialize the struct in-place, otherwise we would get a stackoverflow + let buf: Box = Box::init(init!(BigStruct { + buf <- zeroed(), + a: 7, + b: 186, + c: 7789, + d: 34, + managed_buf <- ManagedBuf::new(), + })) + .unwrap(); + println!("{}", core::mem::size_of_val(&*buf)); +} diff --git a/rust/pin-init/examples/error.rs b/rust/pin-init/examples/error.rs new file mode 100644 index 000000000000..e0cc258746ce --- /dev/null +++ b/rust/pin-init/examples/error.rs @@ -0,0 +1,27 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +#![cfg_attr(feature = "alloc", feature(allocator_api))] + +use core::convert::Infallible; + +#[cfg(feature = "alloc")] +use std::alloc::AllocError; + +#[derive(Debug)] +pub struct Error; + +impl From for Error { + fn from(e: Infallible) -> Self { + match e {} + } +} + +#[cfg(feature = "alloc")] +impl From for Error { + fn from(_: AllocError) -> Self { + Self + } +} + +#[allow(dead_code)] +fn main() {} diff --git a/rust/pin-init/examples/linked_list.rs b/rust/pin-init/examples/linked_list.rs new file mode 100644 index 000000000000..6d7eb0a0ec0d --- /dev/null +++ b/rust/pin-init/examples/linked_list.rs @@ -0,0 +1,161 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +#![allow(clippy::undocumented_unsafe_blocks)] +#![cfg_attr(feature = "alloc", feature(allocator_api))] + +use core::{ + cell::Cell, + convert::Infallible, + marker::PhantomPinned, + pin::Pin, + ptr::{self, NonNull}, +}; + +use pin_init::*; + +#[expect(unused_attributes)] +mod error; +use error::Error; + +#[pin_data(PinnedDrop)] +#[repr(C)] +#[derive(Debug)] +pub struct ListHead { + next: Link, + prev: Link, + #[pin] + pin: PhantomPinned, +} + +impl ListHead { + #[inline] + pub fn new() -> impl PinInit { + try_pin_init!(&this in Self { + next: unsafe { Link::new_unchecked(this) }, + prev: unsafe { Link::new_unchecked(this) }, + pin: PhantomPinned, + }? Infallible) + } + + #[inline] + pub fn insert_next(list: &ListHead) -> impl PinInit + '_ { + try_pin_init!(&this in Self { + prev: list.next.prev().replace(unsafe { Link::new_unchecked(this)}), + next: list.next.replace(unsafe { Link::new_unchecked(this)}), + pin: PhantomPinned, + }? Infallible) + } + + #[inline] + pub fn insert_prev(list: &ListHead) -> impl PinInit + '_ { + try_pin_init!(&this in Self { + next: list.prev.next().replace(unsafe { Link::new_unchecked(this)}), + prev: list.prev.replace(unsafe { Link::new_unchecked(this)}), + pin: PhantomPinned, + }? Infallible) + } + + #[inline] + pub fn next(&self) -> Option> { + if ptr::eq(self.next.as_ptr(), self) { + None + } else { + Some(unsafe { NonNull::new_unchecked(self.next.as_ptr() as *mut Self) }) + } + } + + #[allow(dead_code)] + pub fn size(&self) -> usize { + let mut size = 1; + let mut cur = self.next.clone(); + while !ptr::eq(self, cur.cur()) { + cur = cur.next().clone(); + size += 1; + } + size + } +} + +#[pinned_drop] +impl PinnedDrop for ListHead { + //#[inline] + fn drop(self: Pin<&mut Self>) { + if !ptr::eq(self.next.as_ptr(), &*self) { + let next = unsafe { &*self.next.as_ptr() }; + let prev = unsafe { &*self.prev.as_ptr() }; + next.prev.set(&self.prev); + prev.next.set(&self.next); + } + } +} + +#[repr(transparent)] +#[derive(Clone, Debug)] +struct Link(Cell>); + +impl Link { + /// # Safety + /// + /// The contents of the pointer should form a consistent circular + /// linked list; for example, a "next" link should be pointed back + /// by the target `ListHead`'s "prev" link and a "prev" link should be + /// pointed back by the target `ListHead`'s "next" link. + #[inline] + unsafe fn new_unchecked(ptr: NonNull) -> Self { + Self(Cell::new(ptr)) + } + + #[inline] + fn next(&self) -> &Link { + unsafe { &(*self.0.get().as_ptr()).next } + } + + #[inline] + fn prev(&self) -> &Link { + unsafe { &(*self.0.get().as_ptr()).prev } + } + + #[allow(dead_code)] + fn cur(&self) -> &ListHead { + unsafe { &*self.0.get().as_ptr() } + } + + #[inline] + fn replace(&self, other: Link) -> Link { + unsafe { Link::new_unchecked(self.0.replace(other.0.get())) } + } + + #[inline] + fn as_ptr(&self) -> *const ListHead { + self.0.get().as_ptr() + } + + #[inline] + fn set(&self, val: &Link) { + self.0.set(val.0.get()); + } +} + +#[allow(dead_code)] +#[cfg_attr(test, test)] +fn main() -> Result<(), Error> { + let a = Box::pin_init(ListHead::new())?; + stack_pin_init!(let b = ListHead::insert_next(&a)); + stack_pin_init!(let c = ListHead::insert_next(&a)); + stack_pin_init!(let d = ListHead::insert_next(&b)); + let e = Box::pin_init(ListHead::insert_next(&b))?; + println!("a ({a:p}): {a:?}"); + println!("b ({b:p}): {b:?}"); + println!("c ({c:p}): {c:?}"); + println!("d ({d:p}): {d:?}"); + println!("e ({e:p}): {e:?}"); + let mut inspect = &*a; + while let Some(next) = inspect.next() { + println!("({inspect:p}): {inspect:?}"); + inspect = unsafe { &*next.as_ptr() }; + if core::ptr::eq(inspect, &*a) { + break; + } + } + Ok(()) +} diff --git a/rust/pin-init/examples/mutex.rs b/rust/pin-init/examples/mutex.rs new file mode 100644 index 000000000000..073bb79341d1 --- /dev/null +++ b/rust/pin-init/examples/mutex.rs @@ -0,0 +1,209 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +#![allow(clippy::undocumented_unsafe_blocks)] +#![cfg_attr(feature = "alloc", feature(allocator_api))] +#![allow(clippy::missing_safety_doc)] + +use core::{ + cell::{Cell, UnsafeCell}, + marker::PhantomPinned, + ops::{Deref, DerefMut}, + pin::Pin, + sync::atomic::{AtomicBool, Ordering}, +}; +use std::{ + sync::Arc, + thread::{self, park, sleep, Builder, Thread}, + time::Duration, +}; + +use pin_init::*; +#[expect(unused_attributes)] +#[path = "./linked_list.rs"] +pub mod linked_list; +use linked_list::*; + +pub struct SpinLock { + inner: AtomicBool, +} + +impl SpinLock { + #[inline] + pub fn acquire(&self) -> SpinLockGuard<'_> { + while self + .inner + .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed) + .is_err() + { + while self.inner.load(Ordering::Relaxed) { + thread::yield_now(); + } + } + SpinLockGuard(self) + } + + #[inline] + #[allow(clippy::new_without_default)] + pub const fn new() -> Self { + Self { + inner: AtomicBool::new(false), + } + } +} + +pub struct SpinLockGuard<'a>(&'a SpinLock); + +impl Drop for SpinLockGuard<'_> { + #[inline] + fn drop(&mut self) { + self.0.inner.store(false, Ordering::Release); + } +} + +#[pin_data] +pub struct CMutex { + #[pin] + wait_list: ListHead, + spin_lock: SpinLock, + locked: Cell, + #[pin] + data: UnsafeCell, +} + +impl CMutex { + #[inline] + pub fn new(val: impl PinInit) -> impl PinInit { + pin_init!(CMutex { + wait_list <- ListHead::new(), + spin_lock: SpinLock::new(), + locked: Cell::new(false), + data <- unsafe { + pin_init_from_closure(|slot: *mut UnsafeCell| { + val.__pinned_init(slot.cast::()) + }) + }, + }) + } + + #[inline] + pub fn lock(&self) -> Pin> { + let mut sguard = self.spin_lock.acquire(); + if self.locked.get() { + stack_pin_init!(let wait_entry = WaitEntry::insert_new(&self.wait_list)); + // println!("wait list length: {}", self.wait_list.size()); + while self.locked.get() { + drop(sguard); + park(); + sguard = self.spin_lock.acquire(); + } + // This does have an effect, as the ListHead inside wait_entry implements Drop! + #[expect(clippy::drop_non_drop)] + drop(wait_entry); + } + self.locked.set(true); + unsafe { + Pin::new_unchecked(CMutexGuard { + mtx: self, + _pin: PhantomPinned, + }) + } + } + + #[allow(dead_code)] + pub fn get_data_mut(self: Pin<&mut Self>) -> &mut T { + // SAFETY: we have an exclusive reference and thus nobody has access to data. + unsafe { &mut *self.data.get() } + } +} + +unsafe impl Send for CMutex {} +unsafe impl Sync for CMutex {} + +pub struct CMutexGuard<'a, T> { + mtx: &'a CMutex, + _pin: PhantomPinned, +} + +impl Drop for CMutexGuard<'_, T> { + #[inline] + fn drop(&mut self) { + let sguard = self.mtx.spin_lock.acquire(); + self.mtx.locked.set(false); + if let Some(list_field) = self.mtx.wait_list.next() { + let wait_entry = list_field.as_ptr().cast::(); + unsafe { (*wait_entry).thread.unpark() }; + } + drop(sguard); + } +} + +impl Deref for CMutexGuard<'_, T> { + type Target = T; + + #[inline] + fn deref(&self) -> &Self::Target { + unsafe { &*self.mtx.data.get() } + } +} + +impl DerefMut for CMutexGuard<'_, T> { + #[inline] + fn deref_mut(&mut self) -> &mut Self::Target { + unsafe { &mut *self.mtx.data.get() } + } +} + +#[pin_data] +#[repr(C)] +struct WaitEntry { + #[pin] + wait_list: ListHead, + thread: Thread, +} + +impl WaitEntry { + #[inline] + fn insert_new(list: &ListHead) -> impl PinInit + '_ { + pin_init!(Self { + thread: thread::current(), + wait_list <- ListHead::insert_prev(list), + }) + } +} + +#[cfg(not(any(feature = "std", feature = "alloc")))] +fn main() {} + +#[allow(dead_code)] +#[cfg_attr(test, test)] +#[cfg(any(feature = "std", feature = "alloc"))] +fn main() { + let mtx: Pin>> = Arc::pin_init(CMutex::new(0)).unwrap(); + let mut handles = vec![]; + let thread_count = 20; + let workload = if cfg!(miri) { 100 } else { 1_000 }; + for i in 0..thread_count { + let mtx = mtx.clone(); + handles.push( + Builder::new() + .name(format!("worker #{i}")) + .spawn(move || { + for _ in 0..workload { + *mtx.lock() += 1; + } + println!("{i} halfway"); + sleep(Duration::from_millis((i as u64) * 10)); + for _ in 0..workload { + *mtx.lock() += 1; + } + println!("{i} finished"); + }) + .expect("should not fail"), + ); + } + for h in handles { + h.join().expect("thread panicked"); + } + println!("{:?}", &*mtx.lock()); + assert_eq!(*mtx.lock(), workload * thread_count * 2); +} diff --git a/rust/pin-init/examples/pthread_mutex.rs b/rust/pin-init/examples/pthread_mutex.rs new file mode 100644 index 000000000000..9164298c44c0 --- /dev/null +++ b/rust/pin-init/examples/pthread_mutex.rs @@ -0,0 +1,178 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +// inspired by https://github.com/nbdd0121/pin-init/blob/trunk/examples/pthread_mutex.rs +#![allow(clippy::undocumented_unsafe_blocks)] +#![cfg_attr(feature = "alloc", feature(allocator_api))] +#[cfg(not(windows))] +mod pthread_mtx { + #[cfg(feature = "alloc")] + use core::alloc::AllocError; + use core::{ + cell::UnsafeCell, + marker::PhantomPinned, + mem::MaybeUninit, + ops::{Deref, DerefMut}, + pin::Pin, + }; + use pin_init::*; + use std::convert::Infallible; + + #[pin_data(PinnedDrop)] + pub struct PThreadMutex { + #[pin] + raw: UnsafeCell, + data: UnsafeCell, + #[pin] + pin: PhantomPinned, + } + + unsafe impl Send for PThreadMutex {} + unsafe impl Sync for PThreadMutex {} + + #[pinned_drop] + impl PinnedDrop for PThreadMutex { + fn drop(self: Pin<&mut Self>) { + unsafe { + libc::pthread_mutex_destroy(self.raw.get()); + } + } + } + + #[derive(Debug)] + pub enum Error { + #[expect(dead_code)] + IO(std::io::Error), + Alloc, + } + + impl From for Error { + fn from(e: Infallible) -> Self { + match e {} + } + } + + #[cfg(feature = "alloc")] + impl From for Error { + fn from(_: AllocError) -> Self { + Self::Alloc + } + } + + impl PThreadMutex { + pub fn new(data: T) -> impl PinInit { + fn init_raw() -> impl PinInit, Error> { + let init = |slot: *mut UnsafeCell| { + // we can cast, because `UnsafeCell` has the same layout as T. + let slot: *mut libc::pthread_mutex_t = slot.cast(); + let mut attr = MaybeUninit::uninit(); + let attr = attr.as_mut_ptr(); + // SAFETY: ptr is valid + let ret = unsafe { libc::pthread_mutexattr_init(attr) }; + if ret != 0 { + return Err(Error::IO(std::io::Error::from_raw_os_error(ret))); + } + // SAFETY: attr is initialized + let ret = unsafe { + libc::pthread_mutexattr_settype(attr, libc::PTHREAD_MUTEX_NORMAL) + }; + if ret != 0 { + // SAFETY: attr is initialized + unsafe { libc::pthread_mutexattr_destroy(attr) }; + return Err(Error::IO(std::io::Error::from_raw_os_error(ret))); + } + // SAFETY: slot is valid + unsafe { slot.write(libc::PTHREAD_MUTEX_INITIALIZER) }; + // SAFETY: attr and slot are valid ptrs and attr is initialized + let ret = unsafe { libc::pthread_mutex_init(slot, attr) }; + // SAFETY: attr was initialized + unsafe { libc::pthread_mutexattr_destroy(attr) }; + if ret != 0 { + return Err(Error::IO(std::io::Error::from_raw_os_error(ret))); + } + Ok(()) + }; + // SAFETY: mutex has been initialized + unsafe { pin_init_from_closure(init) } + } + try_pin_init!(Self { + data: UnsafeCell::new(data), + raw <- init_raw(), + pin: PhantomPinned, + }? Error) + } + + pub fn lock(&self) -> PThreadMutexGuard<'_, T> { + // SAFETY: raw is always initialized + unsafe { libc::pthread_mutex_lock(self.raw.get()) }; + PThreadMutexGuard { mtx: self } + } + } + + pub struct PThreadMutexGuard<'a, T> { + mtx: &'a PThreadMutex, + } + + impl Drop for PThreadMutexGuard<'_, T> { + fn drop(&mut self) { + // SAFETY: raw is always initialized + unsafe { libc::pthread_mutex_unlock(self.mtx.raw.get()) }; + } + } + + impl Deref for PThreadMutexGuard<'_, T> { + type Target = T; + + fn deref(&self) -> &Self::Target { + unsafe { &*self.mtx.data.get() } + } + } + + impl DerefMut for PThreadMutexGuard<'_, T> { + fn deref_mut(&mut self) -> &mut Self::Target { + unsafe { &mut *self.mtx.data.get() } + } + } +} + +#[cfg_attr(test, test)] +fn main() { + #[cfg(all(any(feature = "std", feature = "alloc"), not(windows)))] + { + use core::pin::Pin; + use pin_init::*; + use pthread_mtx::*; + use std::{ + sync::Arc, + thread::{sleep, Builder}, + time::Duration, + }; + let mtx: Pin>> = Arc::try_pin_init(PThreadMutex::new(0)).unwrap(); + let mut handles = vec![]; + let thread_count = 20; + let workload = 1_000_000; + for i in 0..thread_count { + let mtx = mtx.clone(); + handles.push( + Builder::new() + .name(format!("worker #{i}")) + .spawn(move || { + for _ in 0..workload { + *mtx.lock() += 1; + } + println!("{i} halfway"); + sleep(Duration::from_millis((i as u64) * 10)); + for _ in 0..workload { + *mtx.lock() += 1; + } + println!("{i} finished"); + }) + .expect("should not fail"), + ); + } + for h in handles { + h.join().expect("thread panicked"); + } + println!("{:?}", &*mtx.lock()); + assert_eq!(*mtx.lock(), workload * thread_count * 2); + } +} diff --git a/rust/pin-init/examples/static_init.rs b/rust/pin-init/examples/static_init.rs new file mode 100644 index 000000000000..3487d761aa26 --- /dev/null +++ b/rust/pin-init/examples/static_init.rs @@ -0,0 +1,122 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +#![allow(clippy::undocumented_unsafe_blocks)] +#![cfg_attr(feature = "alloc", feature(allocator_api))] + +use core::{ + cell::{Cell, UnsafeCell}, + mem::MaybeUninit, + ops, + pin::Pin, + time::Duration, +}; +use pin_init::*; +use std::{ + sync::Arc, + thread::{sleep, Builder}, +}; + +#[expect(unused_attributes)] +mod mutex; +use mutex::*; + +pub struct StaticInit { + cell: UnsafeCell>, + init: Cell>, + lock: SpinLock, + present: Cell, +} + +unsafe impl Sync for StaticInit {} +unsafe impl Send for StaticInit {} + +impl> StaticInit { + pub const fn new(init: I) -> Self { + Self { + cell: UnsafeCell::new(MaybeUninit::uninit()), + init: Cell::new(Some(init)), + lock: SpinLock::new(), + present: Cell::new(false), + } + } +} + +impl> ops::Deref for StaticInit { + type Target = T; + fn deref(&self) -> &Self::Target { + if self.present.get() { + unsafe { (*self.cell.get()).assume_init_ref() } + } else { + println!("acquire spinlock on static init"); + let _guard = self.lock.acquire(); + println!("rechecking present..."); + std::thread::sleep(std::time::Duration::from_millis(200)); + if self.present.get() { + return unsafe { (*self.cell.get()).assume_init_ref() }; + } + println!("doing init"); + let ptr = self.cell.get().cast::(); + match self.init.take() { + Some(f) => unsafe { f.__pinned_init(ptr).unwrap() }, + None => unsafe { core::hint::unreachable_unchecked() }, + } + self.present.set(true); + unsafe { (*self.cell.get()).assume_init_ref() } + } + } +} + +pub struct CountInit; + +unsafe impl PinInit> for CountInit { + unsafe fn __pinned_init( + self, + slot: *mut CMutex, + ) -> Result<(), core::convert::Infallible> { + let init = CMutex::new(0); + std::thread::sleep(std::time::Duration::from_millis(1000)); + unsafe { init.__pinned_init(slot) } + } +} + +pub static COUNT: StaticInit, CountInit> = StaticInit::new(CountInit); + +#[cfg(not(any(feature = "std", feature = "alloc")))] +fn main() {} + +#[cfg(any(feature = "std", feature = "alloc"))] +fn main() { + let mtx: Pin>> = Arc::pin_init(CMutex::new(0)).unwrap(); + let mut handles = vec![]; + let thread_count = 20; + let workload = 1_000; + for i in 0..thread_count { + let mtx = mtx.clone(); + handles.push( + Builder::new() + .name(format!("worker #{i}")) + .spawn(move || { + for _ in 0..workload { + *COUNT.lock() += 1; + std::thread::sleep(std::time::Duration::from_millis(10)); + *mtx.lock() += 1; + std::thread::sleep(std::time::Duration::from_millis(10)); + *COUNT.lock() += 1; + } + println!("{i} halfway"); + sleep(Duration::from_millis((i as u64) * 10)); + for _ in 0..workload { + std::thread::sleep(std::time::Duration::from_millis(10)); + *mtx.lock() += 1; + } + println!("{i} finished"); + }) + .expect("should not fail"), + ); + } + for h in handles { + h.join().expect("thread panicked"); + } + println!("{:?}, {:?}", &*mtx.lock(), &*COUNT.lock()); + assert_eq!(*mtx.lock(), workload * thread_count * 2); +} diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index df6962460874..fd9e36077e6e 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -33,19 +33,23 @@ //! //! ```rust,ignore //! # #![expect(clippy::disallowed_names)] -//! use kernel::sync::{new_mutex, Mutex}; +//! # #![feature(allocator_api)] +//! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; //! # use core::pin::Pin; +//! use pin_init::*; +//! //! #[pin_data] //! struct Foo { //! #[pin] -//! a: Mutex, +//! a: CMutex, //! b: u32, //! } //! //! let foo = pin_init!(Foo { -//! a <- new_mutex!(42, "Foo::a"), +//! a <- CMutex::new(42), //! b: 24, //! }); +//! # let _ = Box::pin_init(foo); //! ``` //! //! `foo` now is of the type [`impl PinInit`]. We can now use any smart pointer that we like @@ -53,19 +57,23 @@ //! //! ```rust,ignore //! # #![expect(clippy::disallowed_names)] -//! # use kernel::sync::{new_mutex, Mutex}; -//! # use core::pin::Pin; +//! # #![feature(allocator_api)] +//! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +//! # use core::{alloc::AllocError, pin::Pin}; +//! # use pin_init::*; +//! # //! # #[pin_data] //! # struct Foo { //! # #[pin] -//! # a: Mutex, +//! # a: CMutex, //! # b: u32, //! # } +//! # //! # let foo = pin_init!(Foo { -//! # a <- new_mutex!(42, "Foo::a"), +//! # a <- CMutex::new(42), //! # b: 24, //! # }); -//! let foo: Result>> = KBox::pin_init(foo, GFP_KERNEL); +//! let foo: Result>, AllocError> = Box::pin_init(foo); //! ``` //! //! For more information see the [`pin_init!`] macro. @@ -76,28 +84,34 @@ //! above method only works for types where you can access the fields. //! //! ```rust,ignore -//! # use kernel::sync::{new_mutex, Arc, Mutex}; -//! let mtx: Result>> = -//! Arc::pin_init(new_mutex!(42, "example::mtx"), GFP_KERNEL); +//! # #![feature(allocator_api)] +//! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +//! # use pin_init::*; +//! # use std::sync::Arc; +//! # use core::pin::Pin; +//! let mtx: Result>>, _> = Arc::pin_init(CMutex::new(42)); //! ``` //! //! To declare an init macro/function you just return an [`impl PinInit`]: //! //! ```rust,ignore -//! # use kernel::{sync::Mutex, new_mutex, init::PinInit, try_pin_init}; +//! # #![feature(allocator_api)] +//! # use pin_init::*; +//! # #[path = "../examples/error.rs"] mod error; use error::Error; +//! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; //! #[pin_data] //! struct DriverData { //! #[pin] -//! status: Mutex, -//! buffer: KBox<[u8; 1_000_000]>, +//! status: CMutex, +//! buffer: Box<[u8; 1_000_000]>, //! } //! //! impl DriverData { //! fn new() -> impl PinInit { //! try_pin_init!(Self { -//! status <- new_mutex!(0, "DriverData::status"), -//! buffer: KBox::init(kernel::init::zeroed(), GFP_KERNEL)?, -//! }) +//! status <- CMutex::new(0), +//! buffer: Box::init(pin_init::zeroed())?, +//! }? Error) //! } //! } //! ``` @@ -117,60 +131,61 @@ //! `slot` gets called. //! //! ```rust,ignore -//! # #![expect(unreachable_pub, clippy::disallowed_names)] -//! use kernel::{init, types::Opaque}; -//! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin}; -//! # mod bindings { -//! # #![expect(non_camel_case_types)] -//! # #![expect(clippy::missing_safety_doc)] -//! # 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 } -//! # } -//! # // `Error::from_errno` is `pub(crate)` in the `kernel` crate, thus provide a workaround. -//! # trait FromErrno { -//! # fn from_errno(errno: kernel::ffi::c_int) -> Error { -//! # // Dummy error that can be constructed outside the `kernel` crate. -//! # Error::from(core::fmt::Error) -//! # } -//! # } -//! # impl FromErrno for Error {} +//! # #![feature(extern_types)] +//! use pin_init::*; +//! use core::{ +//! ptr::addr_of_mut, +//! marker::PhantomPinned, +//! cell::UnsafeCell, +//! pin::Pin, +//! mem::MaybeUninit, +//! }; +//! mod bindings { +//! extern "C" { +//! pub type foo; +//! pub fn init_foo(ptr: *mut foo); +//! pub fn destroy_foo(ptr: *mut foo); +//! #[must_use = "you must check the error return code"] +//! pub fn enable_foo(ptr: *mut foo, flags: u32) -> i32; +//! } +//! } +//! //! /// # Invariants //! /// //! /// `foo` is always initialized //! #[pin_data(PinnedDrop)] //! pub struct RawFoo { //! #[pin] -//! foo: Opaque, -//! #[pin] //! _p: PhantomPinned, +//! #[pin] +//! foo: UnsafeCell>, //! } //! //! impl RawFoo { -//! pub fn new(flags: u32) -> impl PinInit { +//! pub fn new(flags: u32) -> impl PinInit { //! // 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| { +//! pin_init_from_closure(move |slot: *mut Self| { //! // `slot` contains uninit memory, avoid creating a reference. //! let foo = addr_of_mut!((*slot).foo); +//! let foo = UnsafeCell::raw_get(foo).cast::(); //! //! // Initialize the `foo` -//! bindings::init_foo(Opaque::raw_get(foo)); +//! bindings::init_foo(foo); //! //! // Try to enable it. -//! let err = bindings::enable_foo(Opaque::raw_get(foo), flags); +//! let err = bindings::enable_foo(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_errno(err)); +//! bindings::destroy_foo(foo); +//! Err(err) +//! } else { +//! // All fields of `RawFoo` have been initialized, since `_p` is a ZST. +//! Ok(()) //! } -//! -//! // All fields of `RawFoo` have been initialized, since `_p` is a ZST. -//! Ok(()) //! }) //! } //! } @@ -180,7 +195,7 @@ //! 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()) }; +//! unsafe { bindings::destroy_foo(self.foo.get().cast::()) }; //! } //! } //! ``` @@ -235,35 +250,39 @@ pub mod macros; /// # Examples /// /// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use std::{sync::Mutex, process::Command}; -/// # use kernel::macros::pin_data; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// use pin_init::pin_data; +/// +/// enum Command { +/// /* ... */ +/// } +/// /// #[pin_data] /// struct DriverData { /// #[pin] -/// queue: Mutex>, -/// buf: KBox<[u8; 1024 * 1024]>, +/// queue: CMutex>, +/// buf: Box<[u8; 1024 * 1024]>, /// } /// ``` /// /// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use std::{sync::Mutex, process::Command}; -/// # use core::pin::Pin; -/// # pub struct Info; -/// # mod bindings { -/// # pub unsafe fn destroy_info(_ptr: *mut super::Info) {} -/// # } -/// use kernel::macros::{pin_data, pinned_drop}; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # mod bindings { pub struct info; pub unsafe fn destroy_info(_: *mut info) {} } +/// use core::pin::Pin; +/// use pin_init::{pin_data, pinned_drop, PinnedDrop}; +/// +/// enum Command { +/// /* ... */ +/// } /// /// #[pin_data(PinnedDrop)] /// struct DriverData { /// #[pin] -/// queue: Mutex>, -/// buf: KBox<[u8; 1024 * 1024]>, -/// raw_info: *mut Info, +/// queue: CMutex>, +/// buf: Box<[u8; 1024 * 1024]>, +/// raw_info: *mut bindings::info, /// } /// /// #[pinned_drop] @@ -272,7 +291,6 @@ pub mod macros; /// unsafe { bindings::destroy_info(self.raw_info) }; /// } /// } -/// # fn main() {} /// ``` /// /// [`pin_init!`]: crate::pin_init @@ -285,21 +303,22 @@ pub use ::macros::pin_data; /// # Examples /// /// ```ignore -/// # #![feature(lint_reasons)] -/// # use kernel::prelude::*; -/// # use macros::{pin_data, pinned_drop}; -/// # use std::{sync::Mutex, process::Command}; -/// # use core::pin::Pin; -/// # mod bindings { -/// # pub struct Info; -/// # pub unsafe fn destroy_info(_ptr: *mut Info) {} -/// # } +/// # #![feature(allocator_api)] +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # mod bindings { pub struct info; pub unsafe fn destroy_info(_: *mut info) {} } +/// use core::pin::Pin; +/// use pin_init::{pin_data, pinned_drop, PinnedDrop}; +/// +/// enum Command { +/// /* ... */ +/// } +/// /// #[pin_data(PinnedDrop)] /// struct DriverData { /// #[pin] -/// queue: Mutex>, -/// buf: KBox<[u8; 1024 * 1024]>, -/// raw_info: *mut bindings::Info, +/// queue: CMutex>, +/// buf: Box<[u8; 1024 * 1024]>, +/// raw_info: *mut bindings::info, /// } /// /// #[pinned_drop] @@ -318,7 +337,7 @@ pub use ::macros::pinned_drop; /// # Examples /// /// ```ignore -/// use kernel::macros::Zeroable; +/// use pin_init::Zeroable; /// /// #[derive(Zeroable)] /// pub struct DriverData { @@ -335,12 +354,14 @@ pub use ::macros::Zeroable; /// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{init, macros::pin_data, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex}; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # use pin_init::*; /// # use core::pin::Pin; /// #[pin_data] /// struct Foo { /// #[pin] -/// a: Mutex, +/// a: CMutex, /// b: Bar, /// } /// @@ -350,13 +371,13 @@ pub use ::macros::Zeroable; /// } /// /// stack_pin_init!(let foo = pin_init!(Foo { -/// a <- new_mutex!(42), +/// a <- CMutex::new(42), /// b: Bar { /// x: 64, /// }, /// })); /// let foo: Pin<&mut Foo> = foo; -/// pr_info!("a: {}", &*foo.a.lock()); +/// println!("a: {}", &*foo.a.lock()); /// ``` /// /// # Syntax @@ -387,70 +408,56 @@ macro_rules! stack_pin_init { /// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{ -/// # init, -/// # pin_init, -/// # stack_try_pin_init, -/// # init::*, -/// # sync::Mutex, -/// # new_mutex, -/// # alloc::AllocError, -/// # }; -/// # use macros::pin_data; -/// # use core::pin::Pin; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/error.rs"] mod error; use error::Error; +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # use pin_init::*; /// #[pin_data] /// struct Foo { /// #[pin] -/// a: Mutex, -/// b: KBox, +/// a: CMutex, +/// b: Box, /// } /// /// struct Bar { /// x: u32, /// } /// -/// stack_try_pin_init!(let foo: Result, AllocError> = pin_init!(Foo { -/// a <- new_mutex!(42), -/// b: KBox::new(Bar { +/// stack_try_pin_init!(let foo: Foo = try_pin_init!(Foo { +/// a <- CMutex::new(42), +/// b: Box::try_new(Bar { /// x: 64, -/// }, GFP_KERNEL)?, -/// })); +/// })?, +/// }? Error)); /// let foo = foo.unwrap(); -/// pr_info!("a: {}", &*foo.a.lock()); +/// println!("a: {}", &*foo.a.lock()); /// ``` /// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{ -/// # init, -/// # pin_init, -/// # stack_try_pin_init, -/// # init::*, -/// # sync::Mutex, -/// # new_mutex, -/// # alloc::AllocError, -/// # }; -/// # use macros::pin_data; -/// # use core::pin::Pin; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/error.rs"] mod error; use error::Error; +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # use pin_init::*; /// #[pin_data] /// struct Foo { /// #[pin] -/// a: Mutex, -/// b: KBox, +/// a: CMutex, +/// b: Box, /// } /// /// struct Bar { /// x: u32, /// } /// -/// stack_try_pin_init!(let foo: Pin<&mut Foo> =? pin_init!(Foo { -/// a <- new_mutex!(42), -/// b: KBox::new(Bar { +/// stack_try_pin_init!(let foo: Foo =? try_pin_init!(Foo { +/// a <- CMutex::new(42), +/// b: Box::try_new(Bar { /// x: 64, -/// }, GFP_KERNEL)?, -/// })); -/// pr_info!("a: {}", &*foo.a.lock()); -/// # Ok::<_, AllocError>(()) +/// })?, +/// }? Error)); +/// println!("a: {}", &*foo.a.lock()); +/// # Ok::<_, Error>(()) /// ``` /// /// # Syntax @@ -480,7 +487,7 @@ macro_rules! stack_try_pin_init { /// The syntax is almost identical to that of a normal `struct` initializer: /// /// ```rust,ignore -/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use pin_init::*; /// # use core::pin::Pin; /// #[pin_data] /// struct Foo { @@ -503,7 +510,7 @@ macro_rules! stack_try_pin_init { /// }, /// }); /// # initializer } -/// # KBox::pin_init(demo(), GFP_KERNEL).unwrap(); +/// # Box::pin_init(demo()).unwrap(); /// ``` /// /// Arbitrary Rust expressions can be used to set the value of a variable. @@ -524,7 +531,7 @@ macro_rules! stack_try_pin_init { /// To create an initializer function, simply declare it like this: /// /// ```rust,ignore -/// # use kernel::{init, pin_init, init::*}; +/// # use pin_init::*; /// # use core::pin::Pin; /// # #[pin_data] /// # struct Foo { @@ -551,7 +558,7 @@ macro_rules! stack_try_pin_init { /// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] -/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use pin_init::*; /// # use core::pin::Pin; /// # #[pin_data] /// # struct Foo { @@ -572,13 +579,13 @@ macro_rules! stack_try_pin_init { /// # }) /// # } /// # } -/// let foo = KBox::pin_init(Foo::new(), GFP_KERNEL); +/// let foo = Box::pin_init(Foo::new()); /// ``` /// /// They can also easily embed it into their own `struct`s: /// /// ```rust,ignore -/// # use kernel::{init, pin_init, macros::pin_data, init::*}; +/// # use pin_init::*; /// # use core::pin::Pin; /// # #[pin_data] /// # struct Foo { @@ -637,7 +644,7 @@ macro_rules! stack_try_pin_init { /// For instance: /// /// ```rust,ignore -/// # use kernel::{macros::{Zeroable, pin_data}, pin_init}; +/// # use pin_init::*; /// # use core::{ptr::addr_of_mut, marker::PhantomPinned}; /// #[pin_data] /// #[derive(Zeroable)] @@ -700,10 +707,12 @@ macro_rules! pin_init { /// # Examples /// /// ```rust,ignore -/// use kernel::{init::{self, PinInit}, error::Error}; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/error.rs"] mod error; use error::Error; +/// use pin_init::*; /// #[pin_data] /// struct BigBuf { -/// big: KBox<[u8; 1024 * 1024 * 1024]>, +/// big: Box<[u8; 1024 * 1024 * 1024]>, /// small: [u8; 1024 * 1024], /// ptr: *mut u8, /// } @@ -711,12 +720,13 @@ macro_rules! pin_init { /// impl BigBuf { /// fn new() -> impl PinInit { /// try_pin_init!(Self { -/// big: KBox::init(init::zeroed(), GFP_KERNEL)?, +/// big: Box::init(init::zeroed())?, /// small: [0; 1024 * 1024], /// ptr: core::ptr::null_mut(), /// }? Error) /// } /// } +/// # let _ = Box::pin_init(BigBuf::new()); /// ``` // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. @@ -803,18 +813,20 @@ macro_rules! init { /// # Examples /// /// ```rust,ignore -/// use kernel::{alloc::KBox, init::{PinInit, zeroed}, error::Error}; +/// # #![feature(allocator_api)] +/// # use core::alloc::AllocError; +/// use pin_init::*; /// struct BigBuf { -/// big: KBox<[u8; 1024 * 1024 * 1024]>, +/// big: Box<[u8; 1024 * 1024 * 1024]>, /// small: [u8; 1024 * 1024], /// } /// /// impl BigBuf { -/// fn new() -> impl Init { +/// fn new() -> impl Init { /// try_init!(Self { -/// big: KBox::init(zeroed(), GFP_KERNEL)?, +/// big: Box::init(zeroed())?, /// small: [0; 1024 * 1024], -/// }? Error) +/// }? AllocError) /// } /// } /// ``` @@ -859,7 +871,7 @@ macro_rules! try_init { /// /// This will succeed: /// ```ignore -/// use kernel::assert_pinned; +/// use pin_init::assert_pinned; /// #[pin_data] /// struct MyStruct { /// #[pin] @@ -870,9 +882,8 @@ macro_rules! try_init { /// ``` /// /// This will fail: -// TODO: replace with `compile_fail` when supported. -/// ```ignore -/// use kernel::assert_pinned; +/// ```compile_fail,ignore +/// use pin_init::assert_pinned; /// #[pin_data] /// struct MyStruct { /// some_field: u64, @@ -885,7 +896,7 @@ macro_rules! try_init { /// work around this, you may pass the `inline` parameter to the macro. The `inline` parameter can /// only be used when the macro is invoked from a function body. /// ```ignore -/// use kernel::assert_pinned; +/// use pin_init::assert_pinned; /// #[pin_data] /// struct Foo { /// #[pin] @@ -963,35 +974,13 @@ pub unsafe trait PinInit: Sized { /// # Examples /// /// ```rust,ignore - /// # #![expect(clippy::disallowed_names)] - /// use kernel::{types::Opaque, init::pin_init_from_closure}; - /// #[repr(C)] - /// struct RawFoo([u8; 16]); - /// extern "C" { - /// fn init_foo(_: *mut RawFoo); - /// } - /// - /// #[pin_data] - /// struct Foo { - /// #[pin] - /// raw: Opaque, - /// } - /// - /// impl Foo { - /// fn setup(self: Pin<&mut Self>) { - /// pr_info!("Setting up foo"); - /// } - /// } - /// - /// let foo = pin_init!(Foo { - /// // SAFETY: TODO. - /// raw <- unsafe { - /// Opaque::ffi_init(|s| { - /// init_foo(s); - /// }) - /// }, - /// }).pin_chain(|foo| { - /// foo.setup(); + /// # #![feature(allocator_api)] + /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; + /// # use pin_init::*; + /// let mtx_init = CMutex::new(42); + /// // Make the initializer print the value. + /// let mtx_init = mtx_init.pin_chain(|mtx| { + /// println!("{:?}", mtx.get_data_mut()); /// Ok(()) /// }); /// ``` @@ -1076,7 +1065,7 @@ pub unsafe trait Init: PinInit { /// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] - /// use kernel::{types::Opaque, init::{self, init_from_closure}}; + /// use pin_init::{init_from_closure, zeroed}; /// struct Foo { /// buf: [u8; 1_000_000], /// } @@ -1088,7 +1077,7 @@ pub unsafe trait Init: PinInit { /// } /// /// let foo = init!(Foo { - /// buf <- init::zeroed() + /// buf <- zeroed() /// }).chain(|foo| { /// foo.setup(); /// Ok(()) @@ -1187,11 +1176,10 @@ pub fn uninit() -> impl Init, E> { /// # Examples /// /// ```rust,ignore -/// use kernel::{alloc::KBox, error::Error, init::init_array_from_fn}; -/// let array: KBox<[usize; 1_000]> = -/// KBox::init::(init_array_from_fn(|i| i), GFP_KERNEL)?; +/// # use pin_init::*; +/// use pin_init::init_array_from_fn; +/// let array: Box<[usize; 1_000]> = Box::init(init_array_from_fn(|i| i)).unwrap(); /// assert_eq!(array.len(), 1_000); -/// # Ok::<(), Error>(()) /// ``` pub fn init_array_from_fn( mut make_init: impl FnMut(usize) -> I, @@ -1232,11 +1220,15 @@ where /// # Examples /// /// ```rust,ignore -/// use kernel::{sync::{Arc, Mutex}, init::pin_init_array_from_fn, new_mutex}; -/// let array: Arc<[Mutex; 1_000]> = -/// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL)?; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # use pin_init::*; +/// # use core::pin::Pin; +/// use pin_init::pin_init_array_from_fn; +/// use std::sync::Arc; +/// let array: Pin; 1_000]>> = +/// Arc::pin_init(pin_init_array_from_fn(|i| CMutex::new(i))).unwrap(); /// assert_eq!(array.len(), 1_000); -/// # Ok::<(), Error>(()) /// ``` pub fn pin_init_array_from_fn( mut make_init: impl FnMut(usize) -> I, @@ -1421,19 +1413,20 @@ impl InPlaceWrite for UniqueArc> { /// Use [`pinned_drop`] to implement this trait safely: /// /// ```rust,ignore -/// # use kernel::sync::Mutex; -/// use kernel::macros::pinned_drop; +/// # #![feature(allocator_api)] +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # use pin_init::*; /// use core::pin::Pin; /// #[pin_data(PinnedDrop)] /// struct Foo { /// #[pin] -/// mtx: Mutex, +/// mtx: CMutex, /// } /// /// #[pinned_drop] /// impl PinnedDrop for Foo { /// fn drop(self: Pin<&mut Self>) { -/// pr_info!("Foo is being dropped!"); +/// println!("Foo is being dropped!"); /// } /// } /// ``` From c2ddbdbb8a66f43f881c5fe1b8cd615b6dce5c40 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:25 +0000 Subject: [PATCH 26/71] rust: pin-init: call `try_[pin_]init!` from `[pin_]init!` instead of `__init_internal!` The `[pin_]init!` macros have the same behavior as the `try_[pin_]init!` macros, except that they set the error type to `Infallible`. Instead of calling the primitive `__init_internal!` with the correct parameters, the same can thus be achieved by calling `try_[pin_]init!`. Since this makes it more clear what their behavior is, simplify the implementations of `[pin_]init!`. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-7-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/src/lib.rs | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-) diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index fd9e36077e6e..4df5216b80d7 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -676,16 +676,9 @@ macro_rules! pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::__init_internal!( - @this($($this)?), - @typ($t $(::<$($generics),*>)?), - @fields($($fields)*), - @error(::core::convert::Infallible), - @data(PinData, use_data), - @has_data(HasPinData, __pin_data), - @construct_closure(pin_init_from_closure), - @munch_fields($($fields)*), - ) + $crate::try_pin_init!($(&$this in)? $t $(::<$($generics),*>)? { + $($fields)* + }? ::core::convert::Infallible) }; } @@ -784,16 +777,9 @@ macro_rules! init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::__init_internal!( - @this($($this)?), - @typ($t $(::<$($generics),*>)?), - @fields($($fields)*), - @error(::core::convert::Infallible), - @data(InitData, /*no use_data*/), - @has_data(HasInitData, __init_data), - @construct_closure(init_from_closure), - @munch_fields($($fields)*), - ) + $crate::try_init!($(&$this in)? $t $(::<$($generics),*>)? { + $($fields)* + }? ::core::convert::Infallible) } } From 578eb8b6db13cd923f1ffa80b9e8d32dcc06d35d Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:30 +0000 Subject: [PATCH 27/71] rust: pin-init: move the default error behavior of `try_[pin_]init` Move the ability to just write `try_pin_init!(Foo { a <- a_init })` (note the missing `? Error` at the end) into the kernel crate. Remove this notation from the pin-init crate, since the default when no error is specified is the kernel-internal `Error` type. Instead add two macros in the kernel crate that serve this default and are used instead of the ones from `pin-init`. This is done, because the `Error` type that is used as the default is from the kernel crate and it thus prevents making the pin-init crate standalone. In order to not cause a build error due to a name overlap, the macros in the pin-init crate are renamed, but this change is reverted in a future commit when it is a standalone crate. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-8-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/init.rs | 113 +++++++++++++++++++++++++++++++++++++++ rust/pin-init/src/lib.rs | 55 +++++-------------- 2 files changed, 126 insertions(+), 42 deletions(-) diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs index 322dfd9ec347..d80eccf29100 100644 --- a/rust/kernel/init.rs +++ b/rust/kernel/init.rs @@ -133,3 +133,116 @@ //! } //! } //! ``` + +/// 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::zeroed, error::Error}; +/// struct BigBuf { +/// big: KBox<[u8; 1024 * 1024 * 1024]>, +/// small: [u8; 1024 * 1024], +/// } +/// +/// impl BigBuf { +/// fn new() -> impl Init { +/// try_init!(Self { +/// big: KBox::init(zeroed(), GFP_KERNEL)?, +/// small: [0; 1024 * 1024], +/// }? Error) +/// } +/// } +/// ``` +/// +/// [`Infallible`]: core::convert::Infallible +/// [`init!`]: crate::init! +/// [`try_pin_init!`]: crate::try_pin_init! +/// [`Error`]: crate::error::Error +#[macro_export] +macro_rules! try_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::_try_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + $($fields)* + }? $crate::error::Error) + }; + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }? $err:ty) => { + $crate::_try_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + $($fields)* + }? $err) + }; +} + +/// 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::zeroed, error::Error}; +/// #[pin_data] +/// struct BigBuf { +/// big: KBox<[u8; 1024 * 1024 * 1024]>, +/// small: [u8; 1024 * 1024], +/// ptr: *mut u8, +/// } +/// +/// impl BigBuf { +/// fn new() -> impl PinInit { +/// try_pin_init!(Self { +/// big: KBox::init(zeroed(), GFP_KERNEL)?, +/// small: [0; 1024 * 1024], +/// ptr: core::ptr::null_mut(), +/// }? Error) +/// } +/// } +/// ``` +/// +/// [`Infallible`]: core::convert::Infallible +/// [`pin_init!`]: crate::pin_init +/// [`Error`]: crate::error::Error +#[macro_export] +macro_rules! try_pin_init { + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }) => { + $crate::_try_pin_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + $($fields)* + }? $crate::error::Error) + }; + ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { + $($fields:tt)* + }? $err:ty) => { + $crate::_try_pin_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + $($fields)* + }? $err) + }; +} diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index 4df5216b80d7..d2176c65b109 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -481,7 +481,7 @@ macro_rules! stack_try_pin_init { /// Construct an in-place, pinned initializer for `struct`s. /// -/// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use +/// This macro defaults the error to [`Infallible`]. If you need a different error, then use /// [`try_pin_init!`]. /// /// The syntax is almost identical to that of a normal `struct` initializer: @@ -676,7 +676,7 @@ macro_rules! pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::try_pin_init!($(&$this in)? $t $(::<$($generics),*>)? { + $crate::_try_pin_init!($(&$this in)? $t $(::<$($generics),*>)? { $($fields)* }? ::core::convert::Infallible) }; @@ -692,9 +692,7 @@ macro_rules! pin_init { /// 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` +/// The syntax is identical to [`pin_init!`] with the following exception: you must append `? $type` /// after the `struct` initializer to specify the error type you want to use. /// /// # Examples @@ -724,21 +722,7 @@ macro_rules! pin_init { // 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::__init_internal!( - @this($($this)?), - @typ($t $(::<$($generics),*>)? ), - @fields($($fields)*), - @error($crate::error::Error), - @data(PinData, use_data), - @has_data(HasPinData, __pin_data), - @construct_closure(pin_init_from_closure), - @munch_fields($($fields)*), - ) - }; +macro_rules! _try_pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }? $err:ty) => { @@ -752,12 +736,12 @@ macro_rules! try_pin_init { @construct_closure(pin_init_from_closure), @munch_fields($($fields)*), ) - }; + } } /// Construct an in-place initializer for `struct`s. /// -/// This macro defaults the error to [`Infallible`]. If you need [`Error`], then use +/// This macro defaults the error to [`Infallible`]. If you need a different error, then use /// [`try_init!`]. /// /// The syntax is identical to [`pin_init!`] and its safety caveats also apply: @@ -777,7 +761,7 @@ macro_rules! init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::try_init!($(&$this in)? $t $(::<$($generics),*>)? { + $crate::_try_init!($(&$this in)? $t $(::<$($generics),*>)? { $($fields)* }? ::core::convert::Infallible) } @@ -785,11 +769,11 @@ macro_rules! init { /// Construct an in-place fallible initializer for `struct`s. /// -/// This macro defaults the error to [`Error`]. If you need [`Infallible`], then use +/// If the initialization can complete without error (or [`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 syntax is identical to [`try_pin_init!`]. You need to specify a custom error +/// via `? $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. @@ -816,24 +800,11 @@ macro_rules! init { /// } /// } /// ``` +/// [`try_pin_init!`]: crate::try_pin_init // 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::__init_internal!( - @this($($this)?), - @typ($t $(::<$($generics),*>)?), - @fields($($fields)*), - @error($crate::error::Error), - @data(InitData, /*no use_data*/), - @has_data(HasInitData, __init_data), - @construct_closure(init_from_closure), - @munch_fields($($fields)*), - ) - }; +macro_rules! _try_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }? $err:ty) => { @@ -847,7 +818,7 @@ macro_rules! try_init { @construct_closure(init_from_closure), @munch_fields($($fields)*), ) - }; + } } /// Asserts that a field on a struct using `#[pin_data]` is marked with `#[pin]` ie. that it is From 114ca41fe7922ce85fcac30fa2b06b42b4956520 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:34 +0000 Subject: [PATCH 28/71] rust: pin-init: move `InPlaceInit` and impls of `InPlaceWrite` into the kernel crate In order to make pin-init a standalone crate, move kernel-specific code directly into the kernel crate. This includes the `InPlaceInit` trait, its implementations and the implementations of `InPlaceWrite` for `Arc` and `UniqueArc`. All of these use the kernel's error type which will become unavailable in pin-init. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-9-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/alloc/kbox.rs | 3 +- rust/kernel/init.rs | 55 +++++++++++++++++ rust/kernel/prelude.rs | 3 +- rust/kernel/sync/arc.rs | 65 +++++++++++++++++++- rust/pin-init/src/lib.rs | 125 ++------------------------------------ 5 files changed, 127 insertions(+), 124 deletions(-) diff --git a/rust/kernel/alloc/kbox.rs b/rust/kernel/alloc/kbox.rs index cb4ebea3b074..39a3ea7542da 100644 --- a/rust/kernel/alloc/kbox.rs +++ b/rust/kernel/alloc/kbox.rs @@ -15,7 +15,8 @@ use core::pin::Pin; use core::ptr::NonNull; use core::result::Result; -use crate::init::{InPlaceInit, InPlaceWrite, Init, PinInit}; +use crate::init::{InPlaceWrite, Init, PinInit}; +use crate::init_ext::InPlaceInit; use crate::types::ForeignOwnable; /// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`. diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs index d80eccf29100..d8eb6d7873b7 100644 --- a/rust/kernel/init.rs +++ b/rust/kernel/init.rs @@ -134,6 +134,61 @@ //! } //! ``` +use crate::{ + alloc::{AllocError, Flags}, + error::{self, Error}, + init::{init_from_closure, pin_init_from_closure, Init, PinInit}, +}; + +/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit: Sized { + /// Pinned version of `Self`. + /// + /// If a type already implicitly pins its pointee, `Pin` is unnecessary. In this case use + /// `Self`, otherwise just use `Pin`. + type PinnedSelf; + + /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this + /// type. + /// + /// If `T: !Unpin` it will not be able to move afterwards. + fn try_pin_init(init: impl PinInit, flags: Flags) -> Result + where + E: From; + + /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this + /// type. + /// + /// If `T: !Unpin` it will not be able to move afterwards. + fn pin_init(init: impl PinInit, flags: Flags) -> error::Result + where + Error: From, + { + // SAFETY: We delegate to `init` and only change the error type. + let init = unsafe { + pin_init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e))) + }; + Self::try_pin_init(init, flags) + } + + /// Use the given initializer to in-place initialize a `T`. + fn try_init(init: impl Init, flags: Flags) -> Result + where + E: From; + + /// Use the given initializer to in-place initialize a `T`. + fn init(init: impl Init, flags: Flags) -> error::Result + where + Error: From, + { + // SAFETY: We delegate to `init` and only change the error type. + let init = unsafe { + init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e))) + }; + Self::try_init(init, flags) + } +} + /// Construct an in-place fallible initializer for `struct`s. /// /// This macro defaults the error to [`Error`]. If you need [`Infallible`], then use diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index 889102f5a81e..ab7c07788a28 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -36,6 +36,7 @@ pub use super::error::{code::*, Error, Result}; pub use super::{str::CStr, ThisModule}; -pub use super::init::{InPlaceInit, InPlaceWrite, Init, PinInit}; +pub use super::init::{InPlaceWrite, Init, PinInit}; +pub use super::init_ext::InPlaceInit; pub use super::current; diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index 3cefda7a4372..31c26b692c6d 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -19,7 +19,8 @@ use crate::{ alloc::{AllocError, Flags, KBox}, bindings, - init::{self, InPlaceInit, Init, PinInit}, + init::{self, InPlaceWrite, Init, PinInit}, + init_ext::InPlaceInit, try_init, types::{ForeignOwnable, Opaque}, }; @@ -202,6 +203,26 @@ unsafe impl Send for Arc {} // the reference count reaches zero and `T` is dropped. unsafe impl Sync for Arc {} +impl InPlaceInit for Arc { + type PinnedSelf = Self; + + #[inline] + fn try_pin_init(init: impl PinInit, flags: Flags) -> Result + where + E: From, + { + UniqueArc::try_pin_init(init, flags).map(|u| u.into()) + } + + #[inline] + fn try_init(init: impl Init, flags: Flags) -> Result + where + E: From, + { + UniqueArc::try_init(init, flags).map(|u| u.into()) + } +} + impl Arc { /// Constructs a new reference counted instance of `T`. pub fn new(contents: T, flags: Flags) -> Result { @@ -659,6 +680,48 @@ pub struct UniqueArc { inner: Arc, } +impl InPlaceInit for UniqueArc { + type PinnedSelf = Pin; + + #[inline] + fn try_pin_init(init: impl PinInit, flags: Flags) -> Result + where + E: From, + { + UniqueArc::new_uninit(flags)?.write_pin_init(init) + } + + #[inline] + fn try_init(init: impl Init, flags: Flags) -> Result + where + E: From, + { + UniqueArc::new_uninit(flags)?.write_init(init) + } +} + +impl InPlaceWrite for UniqueArc> { + type Initialized = UniqueArc; + + fn write_init(mut self, init: impl Init) -> Result { + let slot = self.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 { self.assume_init() }) + } + + fn write_pin_init(mut self, init: impl PinInit) -> Result, E> { + let slot = self.as_mut_ptr(); + // SAFETY: When init errors/panics, slot will get deallocated but not dropped, + // slot is valid and will not be moved, because we pin it later. + unsafe { init.__pinned_init(slot)? }; + // SAFETY: All fields have been initialized. + Ok(unsafe { self.assume_init() }.into()) + } +} + impl UniqueArc { /// Tries to allocate a new [`UniqueArc`] instance. pub fn new(value: T, flags: Flags) -> Result { diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index d2176c65b109..f88465e0bb76 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -10,7 +10,7 @@ //! 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` (this can be the [stack], an [`Arc`], -//! [`UniqueArc`], [`KBox`] or any other smart pointer that implements [`InPlaceInit`]). +//! [`KBox`] or any other smart pointer that supports this library). //! //! To get an in-place constructor there are generally three options: //! - directly creating an in-place constructor using the [`pin_init!`] macro, @@ -212,10 +212,7 @@ //! [`pin_init!`]: crate::pin_init! use crate::{ - alloc::{AllocError, Flags, KBox}, - error::{self, Error}, - sync::Arc, - sync::UniqueArc, + alloc::KBox, types::{Opaque, ScopeGuard}, }; use core::{ @@ -891,8 +888,7 @@ macro_rules! assert_pinned { /// A pin-initializer for the type `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`KBox`], [`Arc`], [`UniqueArc`] or even the stack (see [`stack_pin_init!`]). Use -/// the [`InPlaceInit::pin_init`] function of a smart pointer like [`Arc`] on this. +/// be [`KBox`], [`Arc`] or even the stack (see [`stack_pin_init!`]). /// /// Also see the [module description](self). /// @@ -910,7 +906,6 @@ macro_rules! assert_pinned { /// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. /// /// [`Arc`]: crate::sync::Arc -/// [`Arc::pin_init`]: crate::sync::Arc::pin_init #[must_use = "An initializer must be used in order to create its value."] pub unsafe trait PinInit: Sized { /// Initializes `slot`. @@ -976,8 +971,7 @@ where /// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`KBox`], [`Arc`], [`UniqueArc`] or even the stack (see [`stack_pin_init!`]). Use -/// the [`InPlaceInit::init`] function of a smart pointer like [`Arc`] on this. Because +/// be [`KBox`], [`Arc`] or even the stack (see [`stack_pin_init!`]). Because /// [`PinInit`] is a super trait, you can use every function that takes it as well. /// /// Also see the [module description](self). @@ -1238,95 +1232,6 @@ unsafe impl PinInit for T { } } -/// Smart pointer that can initialize memory in-place. -pub trait InPlaceInit: Sized { - /// Pinned version of `Self`. - /// - /// If a type already implicitly pins its pointee, `Pin` is unnecessary. In this case use - /// `Self`, otherwise just use `Pin`. - type PinnedSelf; - - /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this - /// type. - /// - /// If `T: !Unpin` it will not be able to move afterwards. - fn try_pin_init(init: impl PinInit, flags: Flags) -> Result - where - E: From; - - /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this - /// type. - /// - /// If `T: !Unpin` it will not be able to move afterwards. - fn pin_init(init: impl PinInit, flags: Flags) -> error::Result - where - Error: From, - { - // SAFETY: We delegate to `init` and only change the error type. - let init = unsafe { - pin_init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e))) - }; - Self::try_pin_init(init, flags) - } - - /// Use the given initializer to in-place initialize a `T`. - fn try_init(init: impl Init, flags: Flags) -> Result - where - E: From; - - /// Use the given initializer to in-place initialize a `T`. - fn init(init: impl Init, flags: Flags) -> error::Result - where - Error: From, - { - // SAFETY: We delegate to `init` and only change the error type. - let init = unsafe { - init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e))) - }; - Self::try_init(init, flags) - } -} - -impl InPlaceInit for Arc { - type PinnedSelf = Self; - - #[inline] - fn try_pin_init(init: impl PinInit, flags: Flags) -> Result - where - E: From, - { - UniqueArc::try_pin_init(init, flags).map(|u| u.into()) - } - - #[inline] - fn try_init(init: impl Init, flags: Flags) -> Result - where - E: From, - { - UniqueArc::try_init(init, flags).map(|u| u.into()) - } -} - -impl InPlaceInit for UniqueArc { - type PinnedSelf = Pin; - - #[inline] - fn try_pin_init(init: impl PinInit, flags: Flags) -> Result - where - E: From, - { - UniqueArc::new_uninit(flags)?.write_pin_init(init) - } - - #[inline] - fn try_init(init: impl Init, flags: Flags) -> Result - where - E: From, - { - UniqueArc::new_uninit(flags)?.write_init(init) - } -} - /// Smart pointer containing uninitialized memory and that can write a value. pub trait InPlaceWrite { /// The type `Self` turns into when the contents are initialized. @@ -1343,28 +1248,6 @@ pub trait InPlaceWrite { fn write_pin_init(self, init: impl PinInit) -> Result, E>; } -impl InPlaceWrite for UniqueArc> { - type Initialized = UniqueArc; - - fn write_init(mut self, init: impl Init) -> Result { - let slot = self.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 { self.assume_init() }) - } - - fn write_pin_init(mut self, init: impl PinInit) -> Result, E> { - let slot = self.as_mut_ptr(); - // SAFETY: When init errors/panics, slot will get deallocated but not dropped, - // slot is valid and will not be moved, because we pin it later. - unsafe { init.__pinned_init(slot)? }; - // SAFETY: All fields have been initialized. - Ok(unsafe { self.assume_init() }.into()) - } -} - /// Trait facilitating pinned destruction. /// /// Use [`pinned_drop`] to implement this trait safely: From 9d29c682f00c3d8dd5727f6a350c4f6ecccc3913 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:38 +0000 Subject: [PATCH 29/71] rust: pin-init: move impl `Zeroable` for `Opaque` and `Option>` into the kernel crate In order to make pin-init a standalone crate, move kernel-specific code directly into the kernel crate. Since `Opaque` and `KBox` are part of the kernel, move their `Zeroable` implementation into the kernel crate. Signed-off-by: Benno Lossin Tested-by: Andreas Hindborg Reviewed-by: Fiona Behrens Link: https://lore.kernel.org/r/20250308110339.2997091-10-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/alloc/kbox.rs | 8 +++++++- rust/kernel/types.rs | 5 ++++- rust/pin-init/src/lib.rs | 8 +------- 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/rust/kernel/alloc/kbox.rs b/rust/kernel/alloc/kbox.rs index 39a3ea7542da..9861433559dc 100644 --- a/rust/kernel/alloc/kbox.rs +++ b/rust/kernel/alloc/kbox.rs @@ -15,7 +15,7 @@ use core::pin::Pin; use core::ptr::NonNull; use core::result::Result; -use crate::init::{InPlaceWrite, Init, PinInit}; +use crate::init::{InPlaceWrite, Init, PinInit, Zeroable}; use crate::init_ext::InPlaceInit; use crate::types::ForeignOwnable; @@ -100,6 +100,12 @@ pub type VBox = Box; /// ``` pub type KVBox = Box; +// SAFETY: All zeros is equivalent to `None` (option layout optimization guarantee). +// +// In this case we are allowed to use `T: ?Sized`, since all zeros is the `None` variant and there +// is no problem with a VTABLE pointer being null. +unsafe impl Zeroable for Option> {} + // SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`. unsafe impl Send for Box where diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs index 5801eeb69dc5..7237b2224680 100644 --- a/rust/kernel/types.rs +++ b/rust/kernel/types.rs @@ -2,7 +2,7 @@ //! Kernel types. -use crate::init::{self, PinInit}; +use crate::init::{self, PinInit, Zeroable}; use core::{ cell::UnsafeCell, marker::{PhantomData, PhantomPinned}, @@ -309,6 +309,9 @@ pub struct Opaque { _pin: PhantomPinned, } +// SAFETY: `Opaque` allows the inner value to be any bit pattern, including all zeros. +unsafe impl Zeroable for Opaque {} + impl Opaque { /// Creates a new opaque value. pub const fn new(value: T) -> Self { diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index f88465e0bb76..aad6486d33fc 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -211,10 +211,7 @@ //! [`pin_data`]: ::macros::pin_data //! [`pin_init!`]: crate::pin_init! -use crate::{ - alloc::KBox, - types::{Opaque, ScopeGuard}, -}; +use crate::{alloc::KBox, types::ScopeGuard}; use core::{ cell::UnsafeCell, convert::Infallible, @@ -1342,8 +1339,6 @@ impl_zeroable! { // SAFETY: Type is allowed to take any value, including all zeros. {} MaybeUninit, - // SAFETY: Type is allowed to take any value, including all zeros. - {} Opaque, // SAFETY: `T: Zeroable` and `UnsafeCell` is `repr(transparent)`. {} UnsafeCell, @@ -1358,7 +1353,6 @@ impl_zeroable! { // // In this case we are allowed to use `T: ?Sized`, since all zeros is the `None` variant. {} Option>, - {} Option>, // SAFETY: `null` pointer is valid. // From 5657c3a9faf6c1243cecc9314244c92bfcd1ecad Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:43 +0000 Subject: [PATCH 30/71] rust: add `ZeroableOption` and implement it instead of `Zeroable` for `Option>` When making pin-init its own crate, `Zeroable` will no longer be defined by the kernel crate and thus implementing it for `Option>` is no longer possible due to the orphan rule. For this reason introduce a new `ZeroableOption` trait that circumvents this problem. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-11-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/alloc/kbox.rs | 4 ++-- rust/pin-init/src/lib.rs | 11 +++++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/rust/kernel/alloc/kbox.rs b/rust/kernel/alloc/kbox.rs index 9861433559dc..07150c038e3f 100644 --- a/rust/kernel/alloc/kbox.rs +++ b/rust/kernel/alloc/kbox.rs @@ -15,7 +15,7 @@ use core::pin::Pin; use core::ptr::NonNull; use core::result::Result; -use crate::init::{InPlaceWrite, Init, PinInit, Zeroable}; +use crate::init::{InPlaceWrite, Init, PinInit, ZeroableOption}; use crate::init_ext::InPlaceInit; use crate::types::ForeignOwnable; @@ -104,7 +104,7 @@ pub type KVBox = Box; // // In this case we are allowed to use `T: ?Sized`, since all zeros is the `None` variant and there // is no problem with a VTABLE pointer being null. -unsafe impl Zeroable for Option> {} +unsafe impl ZeroableOption for Box {} // SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`. unsafe impl Send for Box diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index aad6486d33fc..ca6be982b522 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -1297,6 +1297,17 @@ pub unsafe trait PinnedDrop: __internal::HasPinData { /// ``` pub unsafe trait Zeroable {} +/// Marker trait for types that allow `Option` to be set to all zeroes in order to write +/// `None` to that location. +/// +/// # Safety +/// +/// The implementer needs to ensure that `unsafe impl Zeroable for Option {}` is sound. +pub unsafe trait ZeroableOption {} + +// SAFETY: by the safety requirement of `ZeroableOption`, this is valid. +unsafe impl Zeroable for Option {} + /// Create a new zeroed T. /// /// The returned initializer will write `0x00` to every byte of the given `slot`. From 129e97be8e2856884e01340e4070c003345e1cdc Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:48 +0000 Subject: [PATCH 31/71] rust: pin-init: fix documentation links Before switching to compile the `pin-init` crate directly, change any links that would be invalid to links that are valid both before and after the switch. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-12-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/kernel/sync/condvar.rs | 2 +- rust/pin-init/src/__internal.rs | 4 ++-- rust/pin-init/src/lib.rs | 19 +++++++++++-------- 3 files changed, 14 insertions(+), 11 deletions(-) diff --git a/rust/kernel/sync/condvar.rs b/rust/kernel/sync/condvar.rs index 7df565038d7d..5aa7fa7c7002 100644 --- a/rust/kernel/sync/condvar.rs +++ b/rust/kernel/sync/condvar.rs @@ -37,7 +37,7 @@ pub use new_condvar; /// spuriously. /// /// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such -/// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros. +/// instances is with the [`pin_init`](crate::pin_init!) and [`new_condvar`] macros. /// /// # Examples /// diff --git a/rust/pin-init/src/__internal.rs b/rust/pin-init/src/__internal.rs index 74329cc3262c..0db800819681 100644 --- a/rust/pin-init/src/__internal.rs +++ b/rust/pin-init/src/__internal.rs @@ -135,7 +135,7 @@ unsafe impl HasInitData for T { /// /// If `self.is_init` is true, then `self.value` is initialized. /// -/// [`stack_pin_init`]: kernel::stack_pin_init +/// [`stack_pin_init`]: crate::stack_pin_init pub struct StackInit { value: MaybeUninit, is_init: bool, @@ -156,7 +156,7 @@ impl StackInit { /// Creates a new [`StackInit`] that is uninitialized. Use [`stack_pin_init`] instead of this /// primitive. /// - /// [`stack_pin_init`]: kernel::stack_pin_init + /// [`stack_pin_init`]: crate::stack_pin_init #[inline] pub fn uninit() -> Self { Self { diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index ca6be982b522..47954bc1dc2f 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -10,7 +10,7 @@ //! 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` (this can be the [stack], an [`Arc`], -//! [`KBox`] or any other smart pointer that supports this library). +//! [`Box`] or any other smart pointer that supports this library). //! //! To get an in-place constructor there are generally three options: //! - directly creating an in-place constructor using the [`pin_init!`] macro, @@ -204,7 +204,8 @@ //! [structurally pinned fields]: //! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field //! [stack]: crate::stack_pin_init -//! [`Arc`]: crate::sync::Arc +//! [`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html +//! [`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html //! [`impl PinInit`]: PinInit //! [`impl PinInit`]: PinInit //! [`impl Init`]: Init @@ -661,7 +662,7 @@ macro_rules! stack_try_pin_init { /// }); /// ``` /// -/// [`try_pin_init!`]: kernel::try_pin_init +/// [`try_pin_init!`]: crate::try_pin_init /// [`NonNull`]: core::ptr::NonNull // For a detailed example of how this macro works, see the module documentation of the hidden // module `__internal` inside of `init/__internal.rs`. @@ -885,7 +886,7 @@ macro_rules! assert_pinned { /// A pin-initializer for the type `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`KBox`], [`Arc`] or even the stack (see [`stack_pin_init!`]). +/// be [`Box`], [`Arc`] or even the stack (see [`stack_pin_init!`]). /// /// Also see the [module description](self). /// @@ -902,7 +903,8 @@ macro_rules! assert_pinned { /// - `slot` is not partially initialized. /// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. /// -/// [`Arc`]: crate::sync::Arc +/// [`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html +/// [`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html #[must_use = "An initializer must be used in order to create its value."] pub unsafe trait PinInit: Sized { /// Initializes `slot`. @@ -968,7 +970,7 @@ where /// An initializer for `T`. /// /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can -/// be [`KBox`], [`Arc`] or even the stack (see [`stack_pin_init!`]). Because +/// be [`Box`], [`Arc`] or even the stack (see [`stack_pin_init!`]). Because /// [`PinInit`] is a super trait, you can use every function that takes it as well. /// /// Also see the [module description](self). @@ -992,7 +994,8 @@ where /// Contrary to its supertype [`PinInit`] the caller is allowed to /// move the pointee after initialization. /// -/// [`Arc`]: crate::sync::Arc +/// [`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html +/// [`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html #[must_use = "An initializer must be used in order to create its value."] pub unsafe trait Init: PinInit { /// Initializes `slot`. @@ -1272,7 +1275,7 @@ pub trait InPlaceWrite { /// /// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl. /// -/// [`pinned_drop`]: kernel::macros::pinned_drop +/// [`pinned_drop`]: crate::macros::pinned_drop pub unsafe trait PinnedDrop: __internal::HasPinData { /// Executes the pinned destructor of this type. /// From 31547c988257b3ddd1badb23c166c42b5310735c Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:52 +0000 Subject: [PATCH 32/71] rust: pin-init: remove kernel-crate dependency In order to make pin-init a standalone crate, remove dependencies on kernel-specific code such as `ScopeGuard` and `KBox`. `ScopeGuard` is only used in the `[pin_]init_array_from_fn` functions and can easily be replaced by a primitive construct. `KBox` is only used for type variance of unsized types and can also easily be replaced. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-13-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/src/__internal.rs | 5 +++- rust/pin-init/src/lib.rs | 41 +++++++++++---------------------- 2 files changed, 18 insertions(+), 28 deletions(-) diff --git a/rust/pin-init/src/__internal.rs b/rust/pin-init/src/__internal.rs index 0db800819681..8a53f55e1bbf 100644 --- a/rust/pin-init/src/__internal.rs +++ b/rust/pin-init/src/__internal.rs @@ -11,6 +11,9 @@ use super::*; /// See the [nomicon] for what subtyping is. See also [this table]. /// +/// The reason for not using `PhantomData<*mut T>` is that that type never implements [`Send`] and +/// [`Sync`]. Hence `fn(*mut T) -> *mut T` is used, as that type always implements them. +/// /// [nomicon]: https://doc.rust-lang.org/nomicon/subtyping.html /// [this table]: https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns pub(super) type Invariant = PhantomData *mut T>; @@ -105,7 +108,7 @@ pub unsafe trait InitData: Copy { } } -pub struct AllData(PhantomData) -> KBox>); +pub struct AllData(Invariant); impl Clone for AllData { fn clone(&self) -> Self { diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index 47954bc1dc2f..5f1afd3abb56 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -212,7 +212,6 @@ //! [`pin_data`]: ::macros::pin_data //! [`pin_init!`]: crate::pin_init! -use crate::{alloc::KBox, types::ScopeGuard}; use core::{ cell::UnsafeCell, convert::Infallible, @@ -944,7 +943,7 @@ pub unsafe trait PinInit: Sized { } /// An initializer returned by [`PinInit::pin_chain`]. -pub struct ChainPinInit(I, F, __internal::Invariant<(E, KBox)>); +pub struct ChainPinInit(I, F, __internal::Invariant<(E, T)>); // SAFETY: The `__pinned_init` function is implemented such that it // - returns `Ok(())` on successful initialization, @@ -1043,7 +1042,7 @@ pub unsafe trait Init: PinInit { } /// An initializer returned by [`Init::chain`]. -pub struct ChainInit(I, F, __internal::Invariant<(E, KBox)>); +pub struct ChainInit(I, F, __internal::Invariant<(E, T)>); // SAFETY: The `__init` function is implemented such that it // - returns `Ok(())` on successful initialization, @@ -1140,25 +1139,19 @@ where { let init = move |slot: *mut [T; N]| { let slot = slot.cast::(); - // Counts the number of initialized elements and when dropped drops that many elements from - // `slot`. - let mut init_count = ScopeGuard::new_with_data(0, |i| { - // We now free every element that has been initialized before. - // SAFETY: The loop initialized exactly the values from 0..i and since we - // return `Err` below, the caller will consider the memory at `slot` as - // uninitialized. - unsafe { ptr::drop_in_place(ptr::slice_from_raw_parts_mut(slot, i)) }; - }); for i in 0..N { let init = make_init(i); // SAFETY: Since 0 <= `i` < N, it is still in bounds of `[T; N]`. let ptr = unsafe { slot.add(i) }; // SAFETY: The pointer is derived from `slot` and thus satisfies the `__init` // requirements. - unsafe { init.__init(ptr) }?; - *init_count += 1; + if let Err(e) = unsafe { init.__init(ptr) } { + // SAFETY: The loop has initialized the elements `slot[0..i]` and since we return + // `Err` below, `slot` will be considered uninitialized memory. + unsafe { ptr::drop_in_place(ptr::slice_from_raw_parts_mut(slot, i)) }; + return Err(e); + } } - init_count.dismiss(); Ok(()) }; // SAFETY: The initializer above initializes every element of the array. On failure it drops @@ -1189,25 +1182,19 @@ where { let init = move |slot: *mut [T; N]| { let slot = slot.cast::(); - // Counts the number of initialized elements and when dropped drops that many elements from - // `slot`. - let mut init_count = ScopeGuard::new_with_data(0, |i| { - // We now free every element that has been initialized before. - // SAFETY: The loop initialized exactly the values from 0..i and since we - // return `Err` below, the caller will consider the memory at `slot` as - // uninitialized. - unsafe { ptr::drop_in_place(ptr::slice_from_raw_parts_mut(slot, i)) }; - }); for i in 0..N { let init = make_init(i); // SAFETY: Since 0 <= `i` < N, it is still in bounds of `[T; N]`. let ptr = unsafe { slot.add(i) }; // SAFETY: The pointer is derived from `slot` and thus satisfies the `__init` // requirements. - unsafe { init.__pinned_init(ptr) }?; - *init_count += 1; + if let Err(e) = unsafe { init.__pinned_init(ptr) } { + // SAFETY: The loop has initialized the elements `slot[0..i]` and since we return + // `Err` below, `slot` will be considered uninitialized memory. + unsafe { ptr::drop_in_place(ptr::slice_from_raw_parts_mut(slot, i)) }; + return Err(e); + } } - init_count.dismiss(); Ok(()) }; // SAFETY: The initializer above initializes every element of the array. On failure it drops From b321b9385409800859c2be722c6141909c7221b3 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:04:56 +0000 Subject: [PATCH 33/71] rust: pin-init: change the way the `paste!` macro is called Change the paste macro path from `::kernel::macros::paste!` to use `$crate::init::macros::paste!` instead, which links to `::macros::paste!`. This is because the pin-init crate will be a dependency of the kernel, so it itself cannot have the kernel as a dependency. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-14-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/src/macros.rs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/rust/pin-init/src/macros.rs b/rust/pin-init/src/macros.rs index 1fd146a83241..c45ad6af5ca0 100644 --- a/rust/pin-init/src/macros.rs +++ b/rust/pin-init/src/macros.rs @@ -498,6 +498,8 @@ //! }; //! ``` +pub use ::macros::paste; + /// Creates a `unsafe impl<...> PinnedDrop for $type` block. /// /// See [`PinnedDrop`] for more information. @@ -1134,7 +1136,7 @@ macro_rules! __init_internal { // information that is associated to already parsed fragments, so a path fragment // cannot be used in this position. Doing the retokenization results in valid rust // code. - ::kernel::macros::paste!($t::$get_data()) + $crate::init::macros::paste!($t::$get_data()) }; // Ensure that `data` really is of type `$data` and help with type inference: let init = $crate::init::__internal::$data::make_closure::<_, __InitOk, $err>( @@ -1215,7 +1217,7 @@ macro_rules! __init_internal { // // We rely on macro hygiene to make it impossible for users to access this local variable. // We use `paste!` to create new hygiene for `$field`. - ::kernel::macros::paste! { + $crate::init::macros::paste! { // SAFETY: We forget the guard later when initialization has succeeded. let [< __ $field _guard >] = unsafe { $crate::init::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) @@ -1246,7 +1248,7 @@ macro_rules! __init_internal { // // We rely on macro hygiene to make it impossible for users to access this local variable. // We use `paste!` to create new hygiene for `$field`. - ::kernel::macros::paste! { + $crate::init::macros::paste! { // SAFETY: We forget the guard later when initialization has succeeded. let [< __ $field _guard >] = unsafe { $crate::init::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) @@ -1278,7 +1280,7 @@ macro_rules! __init_internal { // // We rely on macro hygiene to make it impossible for users to access this local variable. // We use `paste!` to create new hygiene for `$field`. - ::kernel::macros::paste! { + $crate::init::macros::paste! { // SAFETY: We forget the guard later when initialization has succeeded. let [< __ $field _guard >] = unsafe { $crate::init::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) @@ -1315,7 +1317,7 @@ macro_rules! __init_internal { // information that is associated to already parsed fragments, so a path fragment // cannot be used in this position. Doing the retokenization results in valid rust // code. - ::kernel::macros::paste!( + $crate::init::macros::paste!( ::core::ptr::write($slot, $t { $($acc)* ..zeroed @@ -1339,7 +1341,7 @@ macro_rules! __init_internal { // information that is associated to already parsed fragments, so a path fragment // cannot be used in this position. Doing the retokenization results in valid rust // code. - ::kernel::macros::paste!( + $crate::init::macros::paste!( ::core::ptr::write($slot, $t { $($acc)* }); From d7659acca7a390b5830f0b67f3aa4a5f9929ab79 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Sat, 8 Mar 2025 11:05:01 +0000 Subject: [PATCH 34/71] rust: add pin-init crate build infrastructure Add infrastructure for moving the initialization API to its own crate. Covers all make targets such as `rust-analyzer` and `rustdoc`. The tests of pin-init are not added to `rusttest`, as they are already tested in the user-space repository [1]. Link: https://github.com/Rust-for-Linux/pin-init [1] Co-developed-by: Benno Lossin Signed-off-by: Benno Lossin Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-15-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/Makefile | 75 +++++++++++++++++++++++------- rust/pin-init/internal/src/_lib.rs | 3 ++ rust/pin-init/internal/src/lib.rs | 4 ++ rust/pin-init/src/_lib.rs | 5 ++ scripts/Makefile.build | 2 +- scripts/generate_rust_analyzer.py | 17 ++++++- 6 files changed, 86 insertions(+), 20 deletions(-) create mode 100644 rust/pin-init/internal/src/_lib.rs create mode 100644 rust/pin-init/src/_lib.rs diff --git a/rust/Makefile b/rust/Makefile index ea3849eb78f6..90310f0620eb 100644 --- a/rust/Makefile +++ b/rust/Makefile @@ -12,7 +12,7 @@ obj-$(CONFIG_RUST) += helpers/helpers.o CFLAGS_REMOVE_helpers/helpers.o = -Wmissing-prototypes -Wmissing-declarations always-$(CONFIG_RUST) += bindings/bindings_generated.rs bindings/bindings_helpers_generated.rs -obj-$(CONFIG_RUST) += bindings.o kernel.o +obj-$(CONFIG_RUST) += bindings.o pin_init.o kernel.o always-$(CONFIG_RUST) += exports_helpers_generated.h \ exports_bindings_generated.h exports_kernel_generated.h @@ -41,7 +41,10 @@ ifdef CONFIG_RUST libmacros_name := $(shell MAKEFLAGS= $(RUSTC) --print file-names --crate-name macros --crate-type proc-macro - TokenStream { diff --git a/rust/pin-init/src/_lib.rs b/rust/pin-init/src/_lib.rs new file mode 100644 index 000000000000..e0918fd8e9e7 --- /dev/null +++ b/rust/pin-init/src/_lib.rs @@ -0,0 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +//! Will be removed in a future commit, only exists to prevent compilation errors. + +#![no_std] diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 993708d11874..08b6380933f5 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -237,7 +237,7 @@ rust_common_cmd = \ -Zallow-features=$(rust_allowed_features) \ -Zcrate-attr=no_std \ -Zcrate-attr='feature($(rust_allowed_features))' \ - -Zunstable-options --extern kernel \ + -Zunstable-options --extern pin_init --extern kernel \ --crate-type rlib -L $(objtree)/rust/ \ --crate-name $(basename $(notdir $@)) \ --sysroot=/dev/null \ diff --git a/scripts/generate_rust_analyzer.py b/scripts/generate_rust_analyzer.py index aa8ea1a4dbe5..a44a4475d11f 100755 --- a/scripts/generate_rust_analyzer.py +++ b/scripts/generate_rust_analyzer.py @@ -93,10 +93,25 @@ def append_crate(display_name, root_module, deps, cfg=[], is_workspace_member=Tr ) crates[-1]["env"]["OBJTREE"] = str(objtree.resolve(True)) + append_crate( + "pin_init_internal", + srctree / "rust" / "pin-init" / "internal" / "src" / "_lib.rs", + [], + cfg=["kernel"], + is_proc_macro=True, + ) + + append_crate( + "pin_init", + srctree / "rust" / "pin-init" / "src" / "_lib.rs", + ["core", "pin_init_internal", "macros"], + cfg=["kernel"], + ) + append_crate( "kernel", srctree / "rust" / "kernel" / "lib.rs", - ["core", "macros", "build_error", "bindings"], + ["core", "macros", "build_error", "bindings", "pin_init"], cfg=cfg, ) crates[-1]["source"] = { From dbd5058ba60c3499b24a7133a4e2e24dba6ea77b Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:09 +0000 Subject: [PATCH 35/71] rust: make pin-init its own crate Rename relative paths inside of the crate to still refer to the same items, also rename paths inside of the kernel crate and adjust the build system to build the crate. [ Remove the `expect` (and thus the `lint_reasons` feature) since the tree now uses `quote!` from `rust/macros/export.rs`. Remove the `TokenStream` import removal, since it is now used as well. In addition, temporarily (i.e. just for this commit) use an `--extern force:alloc` to prevent an unknown `new_uninit` error in the `rustdoc` target. For context, please see a similar case in: https://lore.kernel.org/lkml/20240422090644.525520-1-ojeda@kernel.org/ And adjusted the message above. - Miguel ] Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-16-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/Makefile | 14 +-- rust/kernel/alloc/kbox.rs | 4 +- rust/kernel/block/mq/tag_set.rs | 5 +- rust/kernel/driver.rs | 6 +- rust/kernel/init.rs | 22 +++-- rust/kernel/lib.rs | 10 +- rust/kernel/list.rs | 2 +- rust/kernel/prelude.rs | 9 +- rust/kernel/sync/arc.rs | 7 +- rust/kernel/sync/condvar.rs | 4 +- rust/kernel/sync/lock.rs | 4 +- rust/kernel/sync/lock/mutex.rs | 2 +- rust/kernel/sync/lock/spinlock.rs | 2 +- rust/kernel/types.rs | 10 +- rust/macros/helpers.rs | 2 - rust/macros/lib.rs | 8 -- rust/macros/module.rs | 2 +- rust/macros/quote.rs | 1 + rust/pin-init/internal/src/_lib.rs | 3 - rust/pin-init/internal/src/helpers.rs | 2 + rust/pin-init/internal/src/lib.rs | 16 ++++ rust/pin-init/internal/src/pin_data.rs | 4 +- rust/pin-init/internal/src/pinned_drop.rs | 4 +- rust/pin-init/internal/src/zeroable.rs | 8 +- rust/pin-init/src/_lib.rs | 5 - rust/pin-init/src/lib.rs | 46 +++++---- rust/pin-init/src/macros.rs | 111 +++++++++++----------- scripts/generate_rust_analyzer.py | 4 +- 28 files changed, 164 insertions(+), 153 deletions(-) delete mode 100644 rust/pin-init/internal/src/_lib.rs delete mode 100644 rust/pin-init/src/_lib.rs diff --git a/rust/Makefile b/rust/Makefile index 90310f0620eb..815fbe05ffc8 100644 --- a/rust/Makefile +++ b/rust/Makefile @@ -116,13 +116,13 @@ rustdoc-ffi: $(src)/ffi.rs rustdoc-core FORCE rustdoc-pin_init_internal: private rustdoc_host = yes rustdoc-pin_init_internal: private rustc_target_flags = --cfg kernel \ --extern proc_macro --crate-type proc-macro -rustdoc-pin_init_internal: $(src)/pin-init/internal/src/_lib.rs FORCE +rustdoc-pin_init_internal: $(src)/pin-init/internal/src/lib.rs FORCE +$(call if_changed,rustdoc) rustdoc-pin_init: private rustdoc_host = yes rustdoc-pin_init: private rustc_target_flags = --extern pin_init_internal \ - --extern macros --extern alloc --cfg kernel --cfg feature=\"alloc\" -rustdoc-pin_init: $(src)/pin-init/src/_lib.rs rustdoc-pin_init_internal \ + --extern macros --extern force:alloc --cfg kernel --cfg feature=\"alloc\" +rustdoc-pin_init: $(src)/pin-init/src/lib.rs rustdoc-pin_init_internal \ rustdoc-macros FORCE +$(call if_changed,rustdoc) @@ -158,12 +158,12 @@ rusttestlib-macros: $(src)/macros/lib.rs FORCE rusttestlib-pin_init_internal: private rustc_target_flags = --cfg kernel \ --extern proc_macro rusttestlib-pin_init_internal: private rustc_test_library_proc = yes -rusttestlib-pin_init_internal: $(src)/pin-init/internal/src/_lib.rs FORCE +rusttestlib-pin_init_internal: $(src)/pin-init/internal/src/lib.rs FORCE +$(call if_changed,rustc_test_library) rusttestlib-pin_init: private rustc_target_flags = --extern pin_init_internal \ --extern macros --cfg kernel -rusttestlib-pin_init: $(src)/pin-init/src/_lib.rs rusttestlib-macros \ +rusttestlib-pin_init: $(src)/pin-init/src/lib.rs rusttestlib-macros \ rusttestlib-pin_init_internal $(obj)/$(libpin_init_internal_name) FORCE +$(call if_changed,rustc_test_library) @@ -401,7 +401,7 @@ $(obj)/$(libmacros_name): $(src)/macros/lib.rs FORCE +$(call if_changed_dep,rustc_procmacro) $(obj)/$(libpin_init_internal_name): private rustc_target_flags = --cfg kernel -$(obj)/$(libpin_init_internal_name): $(src)/pin-init/internal/src/_lib.rs FORCE +$(obj)/$(libpin_init_internal_name): $(src)/pin-init/internal/src/lib.rs FORCE +$(call if_changed_dep,rustc_procmacro) quiet_cmd_rustc_library = $(if $(skip_clippy),RUSTC,$(RUSTC_OR_CLIPPY_QUIET)) L $@ @@ -486,7 +486,7 @@ $(obj)/compiler_builtins.o: $(src)/compiler_builtins.rs $(obj)/core.o FORCE $(obj)/pin_init.o: private skip_gendwarfksyms = 1 $(obj)/pin_init.o: private rustc_target_flags = --extern pin_init_internal \ --extern macros --cfg kernel -$(obj)/pin_init.o: $(src)/pin-init/src/_lib.rs $(obj)/compiler_builtins.o \ +$(obj)/pin_init.o: $(src)/pin-init/src/lib.rs $(obj)/compiler_builtins.o \ $(obj)/$(libpin_init_internal_name) $(obj)/$(libmacros_name) FORCE +$(call if_changed_rule,rustc_library) diff --git a/rust/kernel/alloc/kbox.rs b/rust/kernel/alloc/kbox.rs index 07150c038e3f..e6200cd1d06d 100644 --- a/rust/kernel/alloc/kbox.rs +++ b/rust/kernel/alloc/kbox.rs @@ -15,9 +15,9 @@ use core::pin::Pin; use core::ptr::NonNull; use core::result::Result; -use crate::init::{InPlaceWrite, Init, PinInit, ZeroableOption}; -use crate::init_ext::InPlaceInit; +use crate::init::InPlaceInit; use crate::types::ForeignOwnable; +use pin_init::{InPlaceWrite, Init, PinInit, ZeroableOption}; /// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`. /// diff --git a/rust/kernel/block/mq/tag_set.rs b/rust/kernel/block/mq/tag_set.rs index 00ddcc71dfa2..bcf4214ad149 100644 --- a/rust/kernel/block/mq/tag_set.rs +++ b/rust/kernel/block/mq/tag_set.rs @@ -10,12 +10,11 @@ use crate::{ bindings, block::mq::{operations::OperationsVTable, request::RequestDataWrapper, Operations}, error, - prelude::PinInit, - try_pin_init, + prelude::try_pin_init, types::Opaque, }; use core::{convert::TryInto, marker::PhantomData}; -use macros::{pin_data, pinned_drop}; +use pin_init::{pin_data, pinned_drop, PinInit}; /// A wrapper for the C `struct blk_mq_tag_set`. /// diff --git a/rust/kernel/driver.rs b/rust/kernel/driver.rs index 2a16d5e64e6c..ec9166cedfa7 100644 --- a/rust/kernel/driver.rs +++ b/rust/kernel/driver.rs @@ -6,9 +6,9 @@ //! register using the [`Registration`] class. use crate::error::{Error, Result}; -use crate::{device, init::PinInit, of, str::CStr, try_pin_init, types::Opaque, ThisModule}; +use crate::{device, of, str::CStr, try_pin_init, types::Opaque, ThisModule}; use core::pin::Pin; -use macros::{pin_data, pinned_drop}; +use pin_init::{pin_data, pinned_drop, PinInit}; /// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform, /// Amba, etc.) to provide the corresponding subsystem specific implementation to register / @@ -114,7 +114,7 @@ macro_rules! module_driver { impl $crate::InPlaceModule for DriverModule { fn init( module: &'static $crate::ThisModule - ) -> impl $crate::init::PinInit { + ) -> impl ::pin_init::PinInit { $crate::try_pin_init!(Self { _driver <- $crate::driver::Registration::new( ::NAME, diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs index d8eb6d7873b7..32d6e4167650 100644 --- a/rust/kernel/init.rs +++ b/rust/kernel/init.rs @@ -23,7 +23,7 @@ //! //! [`Opaque`]: crate::types::Opaque //! [`Opaque::ffi_init`]: crate::types::Opaque::ffi_init -//! [`pin_init!`]: crate::pin_init +//! [`pin_init!`]: pin_init::pin_init //! //! # Examples //! @@ -137,8 +137,8 @@ use crate::{ alloc::{AllocError, Flags}, error::{self, Error}, - init::{init_from_closure, pin_init_from_closure, Init, PinInit}, }; +use pin_init::{init_from_closure, pin_init_from_closure, Init, PinInit}; /// Smart pointer that can initialize memory in-place. pub trait InPlaceInit: Sized { @@ -205,7 +205,8 @@ pub trait InPlaceInit: Sized { /// # Examples /// /// ```rust -/// use kernel::{init::zeroed, error::Error}; +/// use kernel::error::Error; +/// use pin_init::zeroed; /// struct BigBuf { /// big: KBox<[u8; 1024 * 1024 * 1024]>, /// small: [u8; 1024 * 1024], @@ -222,7 +223,7 @@ pub trait InPlaceInit: Sized { /// ``` /// /// [`Infallible`]: core::convert::Infallible -/// [`init!`]: crate::init! +/// [`init!`]: pin_init::init /// [`try_pin_init!`]: crate::try_pin_init! /// [`Error`]: crate::error::Error #[macro_export] @@ -230,14 +231,14 @@ macro_rules! try_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::_try_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + ::pin_init::try_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { $($fields)* }? $crate::error::Error) }; ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }? $err:ty) => { - $crate::_try_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + ::pin_init::try_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { $($fields)* }? $err) }; @@ -262,7 +263,8 @@ macro_rules! try_init { /// /// ```rust /// # #![feature(new_uninit)] -/// use kernel::{init::zeroed, error::Error}; +/// use kernel::error::Error; +/// use pin_init::zeroed; /// #[pin_data] /// struct BigBuf { /// big: KBox<[u8; 1024 * 1024 * 1024]>, @@ -282,21 +284,21 @@ macro_rules! try_init { /// ``` /// /// [`Infallible`]: core::convert::Infallible -/// [`pin_init!`]: crate::pin_init +/// [`pin_init!`]: pin_init::pin_init /// [`Error`]: crate::error::Error #[macro_export] macro_rules! try_pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::_try_pin_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + ::pin_init::try_pin_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { $($fields)* }? $crate::error::Error) }; ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }? $err:ty) => { - $crate::_try_pin_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { + ::pin_init::try_pin_init!($(&$this in)? $t $(::<$($generics),* $(,)?>)? { $($fields)* }? $err) }; diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index e3933f3dfc0b..c92497c7c655 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -50,11 +50,7 @@ pub mod faux; #[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)] pub mod firmware; pub mod fs; -#[path = "../pin-init/src/lib.rs"] pub mod init; -// momentarily use the name `init_ext` and set the path manually -#[path = "init.rs"] -pub mod init_ext; pub mod io; pub mod ioctl; pub mod jump_label; @@ -116,11 +112,11 @@ pub trait InPlaceModule: Sync + Send { /// Creates an initialiser for the module. /// /// It is called when the module is loaded. - fn init(module: &'static ThisModule) -> impl init::PinInit; + fn init(module: &'static ThisModule) -> impl pin_init::PinInit; } impl InPlaceModule for T { - fn init(module: &'static ThisModule) -> impl init::PinInit { + fn init(module: &'static ThisModule) -> impl pin_init::PinInit { let initer = move |slot: *mut Self| { let m = ::init(module)?; @@ -130,7 +126,7 @@ impl InPlaceModule for T { }; // SAFETY: On success, `initer` always fully initialises an instance of `Self`. - unsafe { init::pin_init_from_closure(initer) } + unsafe { pin_init::pin_init_from_closure(initer) } } } diff --git a/rust/kernel/list.rs b/rust/kernel/list.rs index c0ed227b8a4f..a335c3b1ff5e 100644 --- a/rust/kernel/list.rs +++ b/rust/kernel/list.rs @@ -4,12 +4,12 @@ //! A linked list implementation. -use crate::init::PinInit; use crate::sync::ArcBorrow; use crate::types::Opaque; use core::iter::{DoubleEndedIterator, FusedIterator}; use core::marker::PhantomData; use core::ptr; +use pin_init::PinInit; mod impl_list_item_mod; pub use self::impl_list_item_mod::{ diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs index ab7c07788a28..baa774a351ce 100644 --- a/rust/kernel/prelude.rs +++ b/rust/kernel/prelude.rs @@ -17,7 +17,9 @@ pub use core::pin::Pin; pub use crate::alloc::{flags::*, Box, KBox, KVBox, KVVec, KVec, VBox, VVec, Vec}; #[doc(no_inline)] -pub use macros::{export, module, pin_data, pinned_drop, vtable, Zeroable}; +pub use macros::{export, module, vtable}; + +pub use pin_init::{init, pin_data, pin_init, pinned_drop, InPlaceWrite, Init, PinInit, Zeroable}; pub use super::{build_assert, build_error}; @@ -28,7 +30,7 @@ pub use super::fmt; pub use super::{dev_alert, dev_crit, dev_dbg, dev_emerg, dev_err, dev_info, dev_notice, dev_warn}; pub use super::{pr_alert, pr_crit, pr_debug, pr_emerg, pr_err, pr_info, pr_notice, pr_warn}; -pub use super::{init, pin_init, try_init, try_pin_init}; +pub use super::{try_init, try_pin_init}; pub use super::static_assert; @@ -36,7 +38,6 @@ pub use super::error::{code::*, Error, Result}; pub use super::{str::CStr, ThisModule}; -pub use super::init::{InPlaceWrite, Init, PinInit}; -pub use super::init_ext::InPlaceInit; +pub use super::init::InPlaceInit; pub use super::current; diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index 31c26b692c6d..c64eac8b4235 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -19,8 +19,7 @@ use crate::{ alloc::{AllocError, Flags, KBox}, bindings, - init::{self, InPlaceWrite, Init, PinInit}, - init_ext::InPlaceInit, + init::InPlaceInit, try_init, types::{ForeignOwnable, Opaque}, }; @@ -33,7 +32,7 @@ use core::{ pin::Pin, ptr::NonNull, }; -use macros::pin_data; +use pin_init::{self, pin_data, InPlaceWrite, Init, PinInit}; mod std_vendor; @@ -738,7 +737,7 @@ impl UniqueArc { try_init!(ArcInner { // SAFETY: There are no safety requirements for this FFI call. refcount: Opaque::new(unsafe { bindings::REFCOUNT_INIT(1) }), - data <- init::uninit::(), + data <- pin_init::uninit::(), }? AllocError), flags, )?; diff --git a/rust/kernel/sync/condvar.rs b/rust/kernel/sync/condvar.rs index 5aa7fa7c7002..c2535db9e0f8 100644 --- a/rust/kernel/sync/condvar.rs +++ b/rust/kernel/sync/condvar.rs @@ -8,8 +8,6 @@ use super::{lock::Backend, lock::Guard, LockClassKey}; use crate::{ ffi::{c_int, c_long}, - init::PinInit, - pin_init, str::CStr, task::{MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE, TASK_NORMAL, TASK_UNINTERRUPTIBLE}, time::Jiffies, @@ -17,7 +15,7 @@ use crate::{ }; use core::marker::PhantomPinned; use core::ptr; -use macros::pin_data; +use pin_init::{pin_data, pin_init, PinInit}; /// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class. #[macro_export] diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs index eb80048e0110..7f611b59ac57 100644 --- a/rust/kernel/sync/lock.rs +++ b/rust/kernel/sync/lock.rs @@ -7,13 +7,11 @@ use super::LockClassKey; use crate::{ - init::PinInit, - pin_init, str::CStr, types::{NotThreadSafe, Opaque, ScopeGuard}, }; use core::{cell::UnsafeCell, marker::PhantomPinned}; -use macros::pin_data; +use pin_init::{pin_data, pin_init, PinInit}; pub mod mutex; pub mod spinlock; diff --git a/rust/kernel/sync/lock/mutex.rs b/rust/kernel/sync/lock/mutex.rs index 70cadbc2e8e2..581cee7ab842 100644 --- a/rust/kernel/sync/lock/mutex.rs +++ b/rust/kernel/sync/lock/mutex.rs @@ -26,7 +26,7 @@ pub use new_mutex; /// Since it may block, [`Mutex`] needs to be used with care in atomic contexts. /// /// Instances of [`Mutex`] need a lock class and to be pinned. The recommended way to create such -/// instances is with the [`pin_init`](crate::pin_init) and [`new_mutex`] macros. +/// instances is with the [`pin_init`](pin_init::pin_init) and [`new_mutex`] macros. /// /// # Examples /// diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs index ab2f8d075311..d7be38ccbdc7 100644 --- a/rust/kernel/sync/lock/spinlock.rs +++ b/rust/kernel/sync/lock/spinlock.rs @@ -24,7 +24,7 @@ pub use new_spinlock; /// unlocked, at which point another CPU will be allowed to make progress. /// /// Instances of [`SpinLock`] need a lock class and to be pinned. The recommended way to create such -/// instances is with the [`pin_init`](crate::pin_init) and [`new_spinlock`] macros. +/// instances is with the [`pin_init`](pin_init::pin_init) and [`new_spinlock`] macros. /// /// # Examples /// diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs index 7237b2224680..9d0471afc964 100644 --- a/rust/kernel/types.rs +++ b/rust/kernel/types.rs @@ -2,7 +2,6 @@ //! Kernel types. -use crate::init::{self, PinInit, Zeroable}; use core::{ cell::UnsafeCell, marker::{PhantomData, PhantomPinned}, @@ -10,6 +9,7 @@ use core::{ ops::{Deref, DerefMut}, ptr::NonNull, }; +use pin_init::{PinInit, Zeroable}; /// Used to transfer ownership to and from foreign (non-Rust) languages. /// @@ -336,7 +336,7 @@ impl Opaque { // - `ptr` is a valid pointer to uninitialized memory, // - `slot` is not accessed on error; the call is infallible, // - `slot` is pinned in memory. - let _ = unsafe { init::PinInit::::__pinned_init(slot, ptr) }; + let _ = unsafe { PinInit::::__pinned_init(slot, ptr) }; }) } @@ -352,7 +352,7 @@ impl Opaque { // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully // initialize the `T`. unsafe { - init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| { + pin_init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| { init_func(Self::raw_get(slot)); Ok(()) }) @@ -372,7 +372,9 @@ impl Opaque { ) -> impl PinInit { // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully // initialize the `T`. - unsafe { init::pin_init_from_closure::<_, E>(move |slot| init_func(Self::raw_get(slot))) } + unsafe { + pin_init::pin_init_from_closure::<_, E>(move |slot| init_func(Self::raw_get(slot))) + } } /// Returns a raw pointer to the opaque data. diff --git a/rust/macros/helpers.rs b/rust/macros/helpers.rs index 141d8476c197..a3ee27e29a6f 100644 --- a/rust/macros/helpers.rs +++ b/rust/macros/helpers.rs @@ -86,5 +86,3 @@ pub(crate) fn function_name(input: TokenStream) -> Option { } None } - -include!("../pin-init/internal/src/helpers.rs"); diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index ba93dd686e38..f0f8c9232748 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -13,13 +13,7 @@ mod export; mod helpers; mod module; mod paste; -#[path = "../pin-init/internal/src/pin_data.rs"] -mod pin_data; -#[path = "../pin-init/internal/src/pinned_drop.rs"] -mod pinned_drop; mod vtable; -#[path = "../pin-init/internal/src/zeroable.rs"] -mod zeroable; use proc_macro::TokenStream; @@ -398,5 +392,3 @@ pub fn paste(input: TokenStream) -> TokenStream { paste::expand(&mut tokens); tokens.into_iter().collect() } - -include!("../pin-init/internal/src/lib.rs"); diff --git a/rust/macros/module.rs b/rust/macros/module.rs index 42ed16c48b37..46f20682a7a9 100644 --- a/rust/macros/module.rs +++ b/rust/macros/module.rs @@ -244,7 +244,7 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream { mod __module_init {{ mod __module_init {{ use super::super::{type_}; - use kernel::init::PinInit; + use pin_init::PinInit; /// The \"Rust loadable module\" mark. // diff --git a/rust/macros/quote.rs b/rust/macros/quote.rs index 31b7ebe504f4..92cacc4067c9 100644 --- a/rust/macros/quote.rs +++ b/rust/macros/quote.rs @@ -2,6 +2,7 @@ use proc_macro::{TokenStream, TokenTree}; +#[allow(dead_code)] pub(crate) trait ToTokens { fn to_tokens(&self, tokens: &mut TokenStream); } diff --git a/rust/pin-init/internal/src/_lib.rs b/rust/pin-init/internal/src/_lib.rs deleted file mode 100644 index 0874cf04e4cb..000000000000 --- a/rust/pin-init/internal/src/_lib.rs +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 OR MIT - -//! Will be removed in a future commit, only exists to prevent compilation errors. diff --git a/rust/pin-init/internal/src/helpers.rs b/rust/pin-init/internal/src/helpers.rs index 2f4fc75c014e..78521ba19d0b 100644 --- a/rust/pin-init/internal/src/helpers.rs +++ b/rust/pin-init/internal/src/helpers.rs @@ -1,5 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT +use proc_macro::{TokenStream, TokenTree}; + /// Parsed generics. /// /// See the field documentation for an explanation what each of the fields represents. diff --git a/rust/pin-init/internal/src/lib.rs b/rust/pin-init/internal/src/lib.rs index 3146da5cc47c..c201b8a53915 100644 --- a/rust/pin-init/internal/src/lib.rs +++ b/rust/pin-init/internal/src/lib.rs @@ -4,6 +4,22 @@ // and thus add a dependency on `include/config/RUSTC_VERSION_TEXT`, which is // touched by Kconfig when the version string from the compiler changes. +//! `pin-init` proc macros. + +#![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))] + +use proc_macro::TokenStream; + +#[cfg(kernel)] +#[path = "../../../macros/quote.rs"] +#[macro_use] +mod quote; + +mod helpers; +mod pin_data; +mod pinned_drop; +mod zeroable; + #[allow(missing_docs)] #[proc_macro_attribute] pub fn pin_data(inner: TokenStream, item: TokenStream) -> TokenStream { diff --git a/rust/pin-init/internal/src/pin_data.rs b/rust/pin-init/internal/src/pin_data.rs index 1d4a3547c684..9b974498f4a8 100644 --- a/rust/pin-init/internal/src/pin_data.rs +++ b/rust/pin-init/internal/src/pin_data.rs @@ -5,7 +5,7 @@ use proc_macro::{Group, Punct, Spacing, TokenStream, TokenTree}; pub(crate) fn pin_data(args: TokenStream, input: TokenStream) -> TokenStream { // This proc-macro only does some pre-parsing and then delegates the actual parsing to - // `kernel::__pin_data!`. + // `pin_init::__pin_data!`. let ( Generics { @@ -71,7 +71,7 @@ pub(crate) fn pin_data(args: TokenStream, input: TokenStream) -> TokenStream { .collect::>(); // This should be the body of the struct `{...}`. let last = rest.pop(); - let mut quoted = quote!(::kernel::__pin_data! { + let mut quoted = quote!(::pin_init::__pin_data! { parse_input: @args(#args), @sig(#(#rest)*), diff --git a/rust/pin-init/internal/src/pinned_drop.rs b/rust/pin-init/internal/src/pinned_drop.rs index 88fb72b20660..386f52f73c06 100644 --- a/rust/pin-init/internal/src/pinned_drop.rs +++ b/rust/pin-init/internal/src/pinned_drop.rs @@ -35,11 +35,11 @@ pub(crate) fn pinned_drop(_args: TokenStream, input: TokenStream) -> TokenStream 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::)); + toks.splice(idx..idx, quote!(::pin_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! { + quote!(::pin_init::__pinned_drop! { @impl_sig(#(#toks)*), @impl_body(#last), }) diff --git a/rust/pin-init/internal/src/zeroable.rs b/rust/pin-init/internal/src/zeroable.rs index cfee2cec18d5..0cf6732f27dc 100644 --- a/rust/pin-init/internal/src/zeroable.rs +++ b/rust/pin-init/internal/src/zeroable.rs @@ -27,7 +27,7 @@ pub(crate) fn derive(input: TokenStream) -> TokenStream { // If we find a `,`, then we have finished a generic/constant/lifetime parameter. TokenTree::Punct(p) if nested == 0 && p.as_char() == ',' => { if in_generic && !inserted { - new_impl_generics.extend(quote! { : ::kernel::init::Zeroable }); + new_impl_generics.extend(quote! { : ::pin_init::Zeroable }); } in_generic = true; inserted = false; @@ -41,7 +41,7 @@ pub(crate) fn derive(input: TokenStream) -> TokenStream { TokenTree::Punct(p) if nested == 0 && p.as_char() == ':' => { new_impl_generics.push(tt); if in_generic { - new_impl_generics.extend(quote! { ::kernel::init::Zeroable + }); + new_impl_generics.extend(quote! { ::pin_init::Zeroable + }); inserted = true; } } @@ -59,10 +59,10 @@ pub(crate) fn derive(input: TokenStream) -> TokenStream { } assert_eq!(nested, 0); if in_generic && !inserted { - new_impl_generics.extend(quote! { : ::kernel::init::Zeroable }); + new_impl_generics.extend(quote! { : ::pin_init::Zeroable }); } quote! { - ::kernel::__derive_zeroable!( + ::pin_init::__derive_zeroable!( parse_input: @sig(#(#rest)*), @impl_generics(#(#new_impl_generics)*), diff --git a/rust/pin-init/src/_lib.rs b/rust/pin-init/src/_lib.rs deleted file mode 100644 index e0918fd8e9e7..000000000000 --- a/rust/pin-init/src/_lib.rs +++ /dev/null @@ -1,5 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 OR MIT - -//! Will be removed in a future commit, only exists to prevent compilation errors. - -#![no_std] diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index 5f1afd3abb56..41bfb35c7a2c 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -209,9 +209,21 @@ //! [`impl PinInit`]: PinInit //! [`impl PinInit`]: PinInit //! [`impl Init`]: Init -//! [`pin_data`]: ::macros::pin_data +//! [`pin_data`]: crate::pin_data //! [`pin_init!`]: crate::pin_init! +#![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))] +#![cfg_attr( + all( + any(feature = "alloc", feature = "std"), + not(RUSTC_NEW_UNINIT_IS_STABLE) + ), + feature(new_uninit) +)] +#![forbid(missing_docs, unsafe_op_in_unsafe_fn)] +#![cfg_attr(not(feature = "std"), no_std)] +#![cfg_attr(feature = "alloc", feature(allocator_api))] + use core::{ cell::UnsafeCell, convert::Infallible, @@ -288,7 +300,7 @@ pub mod macros; /// ``` /// /// [`pin_init!`]: crate::pin_init -pub use ::macros::pin_data; +pub use ::pin_init_internal::pin_data; /// Used to implement `PinnedDrop` safely. /// @@ -322,7 +334,7 @@ pub use ::macros::pin_data; /// } /// } /// ``` -pub use ::macros::pinned_drop; +pub use ::pin_init_internal::pinned_drop; /// Derives the [`Zeroable`] trait for the given struct. /// @@ -340,7 +352,7 @@ pub use ::macros::pinned_drop; /// len: usize, /// } /// ``` -pub use ::macros::Zeroable; +pub use ::pin_init_internal::Zeroable; /// Initialize and pin a type directly on the stack. /// @@ -385,8 +397,8 @@ pub use ::macros::Zeroable; macro_rules! stack_pin_init { (let $var:ident $(: $t:ty)? = $val:expr) => { let val = $val; - let mut $var = ::core::pin::pin!($crate::init::__internal::StackInit$(::<$t>)?::uninit()); - let mut $var = match $crate::init::__internal::StackInit::init($var, val) { + let mut $var = ::core::pin::pin!($crate::__internal::StackInit$(::<$t>)?::uninit()); + let mut $var = match $crate::__internal::StackInit::init($var, val) { Ok(res) => res, Err(x) => { let x: ::core::convert::Infallible = x; @@ -463,13 +475,13 @@ macro_rules! stack_pin_init { macro_rules! stack_try_pin_init { (let $var:ident $(: $t:ty)? = $val:expr) => { let val = $val; - let mut $var = ::core::pin::pin!($crate::init::__internal::StackInit$(::<$t>)?::uninit()); - let mut $var = $crate::init::__internal::StackInit::init($var, val); + let mut $var = ::core::pin::pin!($crate::__internal::StackInit$(::<$t>)?::uninit()); + let mut $var = $crate::__internal::StackInit::init($var, val); }; (let $var:ident $(: $t:ty)? =? $val:expr) => { let val = $val; - let mut $var = ::core::pin::pin!($crate::init::__internal::StackInit$(::<$t>)?::uninit()); - let mut $var = $crate::init::__internal::StackInit::init($var, val)?; + let mut $var = ::core::pin::pin!($crate::__internal::StackInit$(::<$t>)?::uninit()); + let mut $var = $crate::__internal::StackInit::init($var, val)?; }; } @@ -670,7 +682,7 @@ macro_rules! pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::_try_pin_init!($(&$this in)? $t $(::<$($generics),*>)? { + $crate::try_pin_init!($(&$this in)? $t $(::<$($generics),*>)? { $($fields)* }? ::core::convert::Infallible) }; @@ -716,7 +728,7 @@ macro_rules! pin_init { // 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 { +macro_rules! try_pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }? $err:ty) => { @@ -755,7 +767,7 @@ macro_rules! init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }) => { - $crate::_try_init!($(&$this in)? $t $(::<$($generics),*>)? { + $crate::try_init!($(&$this in)? $t $(::<$($generics),*>)? { $($fields)* }? ::core::convert::Infallible) } @@ -798,7 +810,7 @@ macro_rules! init { // 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 { +macro_rules! try_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { $($fields:tt)* }? $err:ty) => { @@ -868,8 +880,8 @@ macro_rules! assert_pinned { ($ty:ty, $field:ident, $field_ty:ty, inline) => { let _ = move |ptr: *mut $field_ty| { // SAFETY: This code is unreachable. - let data = unsafe { <$ty as $crate::init::__internal::HasPinData>::__pin_data() }; - let init = $crate::init::__internal::AlwaysFail::<$field_ty>::new(); + let data = unsafe { <$ty as $crate::__internal::HasPinData>::__pin_data() }; + let init = $crate::__internal::AlwaysFail::<$field_ty>::new(); // SAFETY: This code is unreachable. unsafe { data.$field(ptr, init) }.ok(); }; @@ -1262,7 +1274,7 @@ pub trait InPlaceWrite { /// /// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl. /// -/// [`pinned_drop`]: crate::macros::pinned_drop +/// [`pinned_drop`]: crate::pinned_drop pub unsafe trait PinnedDrop: __internal::HasPinData { /// Executes the pinned destructor of this type. /// diff --git a/rust/pin-init/src/macros.rs b/rust/pin-init/src/macros.rs index c45ad6af5ca0..d41c4f198c42 100644 --- a/rust/pin-init/src/macros.rs +++ b/rust/pin-init/src/macros.rs @@ -19,7 +19,7 @@ //! We will look at the following example: //! //! ```rust,ignore -//! # use kernel::init::*; +//! # use pin_init::*; //! # use core::pin::Pin; //! #[pin_data] //! #[repr(C)] @@ -75,7 +75,7 @@ //! Here is the definition of `Bar` from our example: //! //! ```rust,ignore -//! # use kernel::init::*; +//! # use pin_init::*; //! #[pin_data] //! #[repr(C)] //! struct Bar { @@ -121,22 +121,22 @@ //! self, //! slot: *mut T, //! // Since `t` is `#[pin]`, this is `PinInit`. -//! init: impl ::kernel::init::PinInit, +//! init: impl ::pin_init::PinInit, //! ) -> ::core::result::Result<(), E> { -//! unsafe { ::kernel::init::PinInit::__pinned_init(init, slot) } +//! unsafe { ::pin_init::PinInit::__pinned_init(init, slot) } //! } //! pub unsafe fn x( //! self, //! slot: *mut usize, //! // Since `x` is not `#[pin]`, this is `Init`. -//! init: impl ::kernel::init::Init, +//! init: impl ::pin_init::Init, //! ) -> ::core::result::Result<(), E> { -//! unsafe { ::kernel::init::Init::__init(init, slot) } +//! unsafe { ::pin_init::Init::__init(init, slot) } //! } //! } //! // Implement the internal `HasPinData` trait that associates `Bar` with the pin-data struct //! // that we constructed above. -//! unsafe impl ::kernel::init::__internal::HasPinData for Bar { +//! unsafe impl ::pin_init::__internal::HasPinData for Bar { //! type PinData = __ThePinData; //! unsafe fn __pin_data() -> Self::PinData { //! __ThePinData { @@ -147,7 +147,7 @@ //! // Implement the internal `PinData` trait that marks the pin-data struct as a pin-data //! // struct. This is important to ensure that no user can implement a rogue `__pin_data` //! // function without using `unsafe`. -//! unsafe impl ::kernel::init::__internal::PinData for __ThePinData { +//! unsafe impl ::pin_init::__internal::PinData for __ThePinData { //! type Datee = Bar; //! } //! // Now we only want to implement `Unpin` for `Bar` when every structurally pinned field is @@ -191,7 +191,7 @@ //! #[expect(non_camel_case_types)] //! trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {} //! impl< -//! T: ::kernel::init::PinnedDrop, +//! T: ::pin_init::PinnedDrop, //! > UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {} //! impl UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for Bar {} //! }; @@ -227,11 +227,11 @@ //! // - we `use` the `HasPinData` trait in the block, it is only available in that //! // scope. //! let data = unsafe { -//! use ::kernel::init::__internal::HasPinData; +//! use ::pin_init::__internal::HasPinData; //! Self::__pin_data() //! }; //! // Ensure that `data` really is of type `PinData` and help with type inference: -//! let init = ::kernel::init::__internal::PinData::make_closure::< +//! let init = ::pin_init::__internal::PinData::make_closure::< //! _, //! __InitOk, //! ::core::convert::Infallible, @@ -262,7 +262,7 @@ //! } //! // We again create a `DropGuard`. //! let __x_guard = unsafe { -//! ::kernel::init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).x)) +//! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).x)) //! }; //! // Since initialization has successfully completed, we can now forget //! // the guards. This is not `mem::forget`, since we only have @@ -303,7 +303,7 @@ //! }; //! // Construct the initializer. //! let init = unsafe { -//! ::kernel::init::pin_init_from_closure::< +//! ::pin_init::pin_init_from_closure::< //! _, //! ::core::convert::Infallible, //! >(init) @@ -350,19 +350,19 @@ //! unsafe fn b( //! self, //! slot: *mut Bar, -//! init: impl ::kernel::init::PinInit, E>, +//! init: impl ::pin_init::PinInit, E>, //! ) -> ::core::result::Result<(), E> { -//! unsafe { ::kernel::init::PinInit::__pinned_init(init, slot) } +//! unsafe { ::pin_init::PinInit::__pinned_init(init, slot) } //! } //! unsafe fn a( //! self, //! slot: *mut usize, -//! init: impl ::kernel::init::Init, +//! init: impl ::pin_init::Init, //! ) -> ::core::result::Result<(), E> { -//! unsafe { ::kernel::init::Init::__init(init, slot) } +//! unsafe { ::pin_init::Init::__init(init, slot) } //! } //! } -//! unsafe impl ::kernel::init::__internal::HasPinData for Foo { +//! unsafe impl ::pin_init::__internal::HasPinData for Foo { //! type PinData = __ThePinData; //! unsafe fn __pin_data() -> Self::PinData { //! __ThePinData { @@ -370,7 +370,7 @@ //! } //! } //! } -//! unsafe impl ::kernel::init::__internal::PinData for __ThePinData { +//! unsafe impl ::pin_init::__internal::PinData for __ThePinData { //! type Datee = Foo; //! } //! #[allow(dead_code)] @@ -394,8 +394,8 @@ //! 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 { ::kernel::init::__internal::OnlyCallFromDrop::new() }; -//! ::kernel::init::PinnedDrop::drop(pinned, token); +//! let token = unsafe { ::pin_init::__internal::OnlyCallFromDrop::new() }; +//! ::pin_init::PinnedDrop::drop(pinned, token); //! } //! } //! }; @@ -421,8 +421,8 @@ //! //! ```rust,ignore //! // `unsafe`, full path and the token parameter are added, everything else stays the same. -//! unsafe impl ::kernel::init::PinnedDrop for Foo { -//! fn drop(self: Pin<&mut Self>, _: ::kernel::init::__internal::OnlyCallFromDrop) { +//! unsafe impl ::pin_init::PinnedDrop for Foo { +//! fn drop(self: Pin<&mut Self>, _: ::pin_init::__internal::OnlyCallFromDrop) { //! pr_info!("{self:p} is getting dropped."); //! } //! } @@ -448,10 +448,10 @@ //! let initializer = { //! struct __InitOk; //! let data = unsafe { -//! use ::kernel::init::__internal::HasPinData; +//! use ::pin_init::__internal::HasPinData; //! Foo::__pin_data() //! }; -//! let init = ::kernel::init::__internal::PinData::make_closure::< +//! let init = ::pin_init::__internal::PinData::make_closure::< //! _, //! __InitOk, //! ::core::convert::Infallible, @@ -462,12 +462,12 @@ //! unsafe { ::core::ptr::write(::core::addr_of_mut!((*slot).a), a) }; //! } //! let __a_guard = unsafe { -//! ::kernel::init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).a)) +//! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).a)) //! }; //! let init = Bar::new(36); //! unsafe { data.b(::core::addr_of_mut!((*slot).b), b)? }; //! let __b_guard = unsafe { -//! ::kernel::init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).b)) +//! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).b)) //! }; //! ::core::mem::forget(__b_guard); //! ::core::mem::forget(__a_guard); @@ -492,13 +492,16 @@ //! init(slot).map(|__InitOk| ()) //! }; //! let init = unsafe { -//! ::kernel::init::pin_init_from_closure::<_, ::core::convert::Infallible>(init) +//! ::pin_init::pin_init_from_closure::<_, ::core::convert::Infallible>(init) //! }; //! init //! }; //! ``` +#[cfg(kernel)] pub use ::macros::paste; +#[cfg(not(kernel))] +pub use ::paste::paste; /// Creates a `unsafe impl<...> PinnedDrop for $type` block. /// @@ -519,7 +522,7 @@ macro_rules! __pinned_drop { unsafe $($impl_sig)* { // Inherit all attributes and the type/ident tokens for the signature. $(#[$($attr)*])* - fn drop($($sig)*, _: $crate::init::__internal::OnlyCallFromDrop) { + fn drop($($sig)*, _: $crate::__internal::OnlyCallFromDrop) { $($inner)* } } @@ -865,7 +868,7 @@ macro_rules! __pin_data { // SAFETY: We have added the correct projection functions above to `__ThePinData` and // we also use the least restrictive generics possible. unsafe impl<$($impl_generics)*> - $crate::init::__internal::HasPinData for $name<$($ty_generics)*> + $crate::__internal::HasPinData for $name<$($ty_generics)*> where $($whr)* { type PinData = __ThePinData<$($ty_generics)*>; @@ -877,7 +880,7 @@ macro_rules! __pin_data { // SAFETY: TODO. unsafe impl<$($impl_generics)*> - $crate::init::__internal::PinData for __ThePinData<$($ty_generics)*> + $crate::__internal::PinData for __ThePinData<$($ty_generics)*> where $($whr)* { type Datee = $name<$($ty_generics)*>; @@ -936,7 +939,7 @@ macro_rules! __pin_data { // `PinnedDrop` as the parameter to `#[pin_data]`. #[expect(non_camel_case_types)] trait UselessPinnedDropImpl_you_need_to_specify_PinnedDrop {} - impl + impl UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for T {} impl<$($impl_generics)*> UselessPinnedDropImpl_you_need_to_specify_PinnedDrop for $name<$($ty_generics)*> @@ -959,8 +962,8 @@ macro_rules! __pin_data { 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::new() }; - $crate::init::PinnedDrop::drop(pinned, token); + let token = unsafe { $crate::__internal::OnlyCallFromDrop::new() }; + $crate::PinnedDrop::drop(pinned, token); } } }; @@ -1000,10 +1003,10 @@ macro_rules! __pin_data { $pvis unsafe fn $p_field( self, slot: *mut $p_type, - init: impl $crate::init::PinInit<$p_type, E>, + init: impl $crate::PinInit<$p_type, E>, ) -> ::core::result::Result<(), E> { // SAFETY: TODO. - unsafe { $crate::init::PinInit::__pinned_init(init, slot) } + unsafe { $crate::PinInit::__pinned_init(init, slot) } } )* $( @@ -1011,10 +1014,10 @@ macro_rules! __pin_data { $fvis unsafe fn $field( self, slot: *mut $type, - init: impl $crate::init::Init<$type, E>, + init: impl $crate::Init<$type, E>, ) -> ::core::result::Result<(), E> { // SAFETY: TODO. - unsafe { $crate::init::Init::__init(init, slot) } + unsafe { $crate::Init::__init(init, slot) } } )* } @@ -1131,15 +1134,15 @@ macro_rules! __init_internal { // // SAFETY: TODO. let data = unsafe { - use $crate::init::__internal::$has_data; + use $crate::__internal::$has_data; // Here we abuse `paste!` to retokenize `$t`. Declarative macros have some internal // information that is associated to already parsed fragments, so a path fragment // cannot be used in this position. Doing the retokenization results in valid rust // code. - $crate::init::macros::paste!($t::$get_data()) + $crate::macros::paste!($t::$get_data()) }; // Ensure that `data` really is of type `$data` and help with type inference: - let init = $crate::init::__internal::$data::make_closure::<_, __InitOk, $err>( + let init = $crate::__internal::$data::make_closure::<_, __InitOk, $err>( data, move |slot| { { @@ -1149,7 +1152,7 @@ macro_rules! __init_internal { // error when fields are missing (since they will be zeroed). We also have to // check that the type actually implements `Zeroable`. $({ - fn assert_zeroable(_: *mut T) {} + fn assert_zeroable(_: *mut T) {} // Ensure that the struct is indeed `Zeroable`. assert_zeroable(slot); // SAFETY: The type implements `Zeroable` by the check above. @@ -1186,7 +1189,7 @@ macro_rules! __init_internal { init(slot).map(|__InitOk| ()) }; // SAFETY: TODO. - let init = unsafe { $crate::init::$construct_closure::<_, $err>(init) }; + let init = unsafe { $crate::$construct_closure::<_, $err>(init) }; init }}; (init_slot($($use_data:ident)?): @@ -1217,10 +1220,10 @@ macro_rules! __init_internal { // // We rely on macro hygiene to make it impossible for users to access this local variable. // We use `paste!` to create new hygiene for `$field`. - $crate::init::macros::paste! { + $crate::macros::paste! { // SAFETY: We forget the guard later when initialization has succeeded. let [< __ $field _guard >] = unsafe { - $crate::init::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) + $crate::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) }; $crate::__init_internal!(init_slot($use_data): @@ -1243,15 +1246,15 @@ macro_rules! __init_internal { // // SAFETY: `slot` is valid, because we are inside of an initializer closure, we // return when an error/panic occurs. - unsafe { $crate::init::Init::__init(init, ::core::ptr::addr_of_mut!((*$slot).$field))? }; + unsafe { $crate::Init::__init(init, ::core::ptr::addr_of_mut!((*$slot).$field))? }; // Create the drop guard: // // We rely on macro hygiene to make it impossible for users to access this local variable. // We use `paste!` to create new hygiene for `$field`. - $crate::init::macros::paste! { + $crate::macros::paste! { // SAFETY: We forget the guard later when initialization has succeeded. let [< __ $field _guard >] = unsafe { - $crate::init::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) + $crate::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) }; $crate::__init_internal!(init_slot(): @@ -1280,10 +1283,10 @@ macro_rules! __init_internal { // // We rely on macro hygiene to make it impossible for users to access this local variable. // We use `paste!` to create new hygiene for `$field`. - $crate::init::macros::paste! { + $crate::macros::paste! { // SAFETY: We forget the guard later when initialization has succeeded. let [< __ $field _guard >] = unsafe { - $crate::init::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) + $crate::__internal::DropGuard::new(::core::ptr::addr_of_mut!((*$slot).$field)) }; $crate::__init_internal!(init_slot($($use_data)?): @@ -1317,7 +1320,7 @@ macro_rules! __init_internal { // information that is associated to already parsed fragments, so a path fragment // cannot be used in this position. Doing the retokenization results in valid rust // code. - $crate::init::macros::paste!( + $crate::macros::paste!( ::core::ptr::write($slot, $t { $($acc)* ..zeroed @@ -1341,7 +1344,7 @@ macro_rules! __init_internal { // information that is associated to already parsed fragments, so a path fragment // cannot be used in this position. Doing the retokenization results in valid rust // code. - $crate::init::macros::paste!( + $crate::macros::paste!( ::core::ptr::write($slot, $t { $($acc)* }); @@ -1396,12 +1399,12 @@ macro_rules! __derive_zeroable { ) => { // SAFETY: Every field type implements `Zeroable` and padding bytes may be zero. #[automatically_derived] - unsafe impl<$($impl_generics)*> $crate::init::Zeroable for $name<$($ty_generics)*> + unsafe impl<$($impl_generics)*> $crate::Zeroable for $name<$($ty_generics)*> where $($($whr)*)? {} const _: () = { - fn assert_zeroable() {} + fn assert_zeroable() {} fn ensure_zeroable<$($impl_generics)*>() where $($($whr)*)? { diff --git a/scripts/generate_rust_analyzer.py b/scripts/generate_rust_analyzer.py index a44a4475d11f..54228e87e577 100755 --- a/scripts/generate_rust_analyzer.py +++ b/scripts/generate_rust_analyzer.py @@ -95,7 +95,7 @@ def append_crate(display_name, root_module, deps, cfg=[], is_workspace_member=Tr append_crate( "pin_init_internal", - srctree / "rust" / "pin-init" / "internal" / "src" / "_lib.rs", + srctree / "rust" / "pin-init" / "internal" / "src" / "lib.rs", [], cfg=["kernel"], is_proc_macro=True, @@ -103,7 +103,7 @@ def append_crate(display_name, root_module, deps, cfg=[], is_workspace_member=Tr append_crate( "pin_init", - srctree / "rust" / "pin-init" / "src" / "_lib.rs", + srctree / "rust" / "pin-init" / "src" / "lib.rs", ["core", "pin_init_internal", "macros"], cfg=["kernel"], ) From 9b2299af3b92eb5b2c2f87965a5fa24a93e90d06 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:12 +0000 Subject: [PATCH 36/71] rust: pin-init: add `std` and `alloc` support from the user-space version To synchronize the kernel's version of pin-init with the user-space version, introduce support for `std` and `alloc`. While the kernel uses neither, the user-space version has to support both. Thus include the required `#[cfg]`s and additional code. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-17-benno.lossin@proton.me [ Undo the temporary `--extern force:alloc` since now we have contents for `alloc` here. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/Makefile | 2 +- rust/pin-init/src/__internal.rs | 27 ++++++ rust/pin-init/src/alloc.rs | 158 ++++++++++++++++++++++++++++++++ rust/pin-init/src/lib.rs | 41 +++++++-- 4 files changed, 221 insertions(+), 7 deletions(-) create mode 100644 rust/pin-init/src/alloc.rs diff --git a/rust/Makefile b/rust/Makefile index 815fbe05ffc8..e761a8cc3bd5 100644 --- a/rust/Makefile +++ b/rust/Makefile @@ -121,7 +121,7 @@ rustdoc-pin_init_internal: $(src)/pin-init/internal/src/lib.rs FORCE rustdoc-pin_init: private rustdoc_host = yes rustdoc-pin_init: private rustc_target_flags = --extern pin_init_internal \ - --extern macros --extern force:alloc --cfg kernel --cfg feature=\"alloc\" + --extern macros --extern alloc --cfg kernel --cfg feature=\"alloc\" rustdoc-pin_init: $(src)/pin-init/src/lib.rs rustdoc-pin_init_internal \ rustdoc-macros FORCE +$(call if_changed,rustdoc) diff --git a/rust/pin-init/src/__internal.rs b/rust/pin-init/src/__internal.rs index 8a53f55e1bbf..cac293fd4bec 100644 --- a/rust/pin-init/src/__internal.rs +++ b/rust/pin-init/src/__internal.rs @@ -189,6 +189,33 @@ impl StackInit { } } +#[test] +fn stack_init_reuse() { + use ::std::{borrow::ToOwned, println, string::String}; + use core::pin::pin; + + #[derive(Debug)] + struct Foo { + a: usize, + b: String, + } + let mut slot: Pin<&mut StackInit> = pin!(StackInit::uninit()); + let value: Result, core::convert::Infallible> = + slot.as_mut().init(crate::init!(Foo { + a: 42, + b: "Hello".to_owned(), + })); + let value = value.unwrap(); + println!("{value:?}"); + let value: Result, core::convert::Infallible> = + slot.as_mut().init(crate::init!(Foo { + a: 24, + b: "world!".to_owned(), + })); + let value = value.unwrap(); + println!("{value:?}"); +} + /// When a value of this type is dropped, it drops a `T`. /// /// Can be forgotten to prevent the drop. diff --git a/rust/pin-init/src/alloc.rs b/rust/pin-init/src/alloc.rs new file mode 100644 index 000000000000..e16baa3b434e --- /dev/null +++ b/rust/pin-init/src/alloc.rs @@ -0,0 +1,158 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +#[cfg(all(feature = "alloc", not(feature = "std")))] +use alloc::{boxed::Box, sync::Arc}; +#[cfg(feature = "alloc")] +use core::alloc::AllocError; +use core::{mem::MaybeUninit, pin::Pin}; +#[cfg(feature = "std")] +use std::sync::Arc; + +#[cfg(not(feature = "alloc"))] +type AllocError = core::convert::Infallible; + +use crate::{ + init_from_closure, pin_init_from_closure, InPlaceWrite, Init, PinInit, ZeroableOption, +}; + +pub extern crate alloc; + +// SAFETY: All zeros is equivalent to `None` (option layout optimization guarantee). +// +// In this case we are allowed to use `T: ?Sized`, since all zeros is the `None` variant and there +// is no problem with a VTABLE pointer being null. +unsafe impl ZeroableOption for Box {} + +/// Smart pointer that can initialize memory in-place. +pub trait InPlaceInit: Sized { + /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this + /// type. + /// + /// If `T: !Unpin` it will not be able to move afterwards. + fn try_pin_init(init: impl PinInit) -> Result, E> + where + E: From; + + /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this + /// type. + /// + /// If `T: !Unpin` it will not be able to move afterwards. + fn pin_init(init: impl PinInit) -> Result, AllocError> { + // SAFETY: We delegate to `init` and only change the error type. + let init = unsafe { + pin_init_from_closure(|slot| match init.__pinned_init(slot) { + Ok(()) => Ok(()), + Err(i) => match i {}, + }) + }; + Self::try_pin_init(init) + } + + /// Use the given initializer to in-place initialize a `T`. + fn try_init(init: impl Init) -> Result + where + E: From; + + /// Use the given initializer to in-place initialize a `T`. + fn init(init: impl Init) -> Result { + // SAFETY: We delegate to `init` and only change the error type. + let init = unsafe { + init_from_closure(|slot| match init.__init(slot) { + Ok(()) => Ok(()), + Err(i) => match i {}, + }) + }; + Self::try_init(init) + } +} + +#[cfg(feature = "alloc")] +macro_rules! try_new_uninit { + ($type:ident) => { + $type::try_new_uninit()? + }; +} +#[cfg(all(feature = "std", not(feature = "alloc")))] +macro_rules! try_new_uninit { + ($type:ident) => { + $type::new_uninit() + }; +} + +impl InPlaceInit for Box { + #[inline] + fn try_pin_init(init: impl PinInit) -> Result, E> + where + E: From, + { + try_new_uninit!(Box).write_pin_init(init) + } + + #[inline] + fn try_init(init: impl Init) -> Result + where + E: From, + { + try_new_uninit!(Box).write_init(init) + } +} + +impl InPlaceInit for Arc { + #[inline] + fn try_pin_init(init: impl PinInit) -> Result, E> + where + E: From, + { + let mut this = try_new_uninit!(Arc); + let Some(slot) = Arc::get_mut(&mut this) else { + // SAFETY: the Arc has just been created and has no external references + unsafe { core::hint::unreachable_unchecked() } + }; + let slot = slot.as_mut_ptr(); + // SAFETY: When init errors/panics, slot will get deallocated but not dropped, + // slot is valid and will not be moved, because we pin it later. + unsafe { init.__pinned_init(slot)? }; + // SAFETY: All fields have been initialized and this is the only `Arc` to that data. + Ok(unsafe { Pin::new_unchecked(this.assume_init()) }) + } + + #[inline] + fn try_init(init: impl Init) -> Result + where + E: From, + { + let mut this = try_new_uninit!(Arc); + let Some(slot) = Arc::get_mut(&mut this) else { + // SAFETY: the Arc has just been created and has no external references + unsafe { core::hint::unreachable_unchecked() } + }; + let slot = slot.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 InPlaceWrite for Box> { + type Initialized = Box; + + fn write_init(mut self, init: impl Init) -> Result { + let slot = self.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 { self.assume_init() }) + } + + fn write_pin_init(mut self, init: impl PinInit) -> Result, E> { + let slot = self.as_mut_ptr(); + // SAFETY: When init errors/panics, slot will get deallocated but not dropped, + // slot is valid and will not be moved, because we pin it later. + unsafe { init.__pinned_init(slot)? }; + // SAFETY: All fields have been initialized. + Ok(unsafe { self.assume_init() }.into()) + } +} diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index 41bfb35c7a2c..58b77a158c34 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -204,8 +204,16 @@ //! [structurally pinned fields]: //! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field //! [stack]: crate::stack_pin_init -//! [`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html -//! [`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html +#![cfg_attr( + kernel, + doc = "[`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html" +)] +#![cfg_attr( + kernel, + doc = "[`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html" +)] +#![cfg_attr(not(kernel), doc = "[`Arc`]: alloc::alloc::sync::Arc")] +#![cfg_attr(not(kernel), doc = "[`Box`]: alloc::alloc::boxed::Box")] //! [`impl PinInit`]: PinInit //! [`impl PinInit`]: PinInit //! [`impl Init`]: Init @@ -239,6 +247,11 @@ pub mod __internal; #[doc(hidden)] pub mod macros; +#[cfg(any(feature = "std", feature = "alloc"))] +mod alloc; +#[cfg(any(feature = "std", feature = "alloc"))] +pub use alloc::InPlaceInit; + /// Used to specify the pinning information of the fields of a struct. /// /// This is somewhat similar in purpose as @@ -914,8 +927,16 @@ macro_rules! assert_pinned { /// - `slot` is not partially initialized. /// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`. /// -/// [`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html -/// [`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html +#[cfg_attr( + kernel, + doc = "[`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html" +)] +#[cfg_attr( + kernel, + doc = "[`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html" +)] +#[cfg_attr(not(kernel), doc = "[`Arc`]: alloc::alloc::sync::Arc")] +#[cfg_attr(not(kernel), doc = "[`Box`]: alloc::alloc::boxed::Box")] #[must_use = "An initializer must be used in order to create its value."] pub unsafe trait PinInit: Sized { /// Initializes `slot`. @@ -1005,8 +1026,16 @@ where /// Contrary to its supertype [`PinInit`] the caller is allowed to /// move the pointee after initialization. /// -/// [`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html -/// [`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html +#[cfg_attr( + kernel, + doc = "[`Arc`]: https://rust.docs.kernel.org/kernel/sync/struct.Arc.html" +)] +#[cfg_attr( + kernel, + doc = "[`Box`]: https://rust.docs.kernel.org/kernel/alloc/kbox/struct.Box.html" +)] +#[cfg_attr(not(kernel), doc = "[`Arc`]: alloc::alloc::sync::Arc")] +#[cfg_attr(not(kernel), doc = "[`Box`]: alloc::alloc::boxed::Box")] #[must_use = "An initializer must be used in order to create its value."] pub unsafe trait Init: PinInit { /// Initializes `slot`. From 02c01c089d125ccc1ecbf331481e7de6f1f38f4e Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:17 +0000 Subject: [PATCH 37/71] rust: pin-init: synchronize documentation with the user-space version Synchronize documentation and examples with the user-space version. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-18-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/src/__internal.rs | 8 +- rust/pin-init/src/lib.rs | 141 +++++++++++++++++++++++--------- rust/pin-init/src/macros.rs | 20 ++--- 3 files changed, 115 insertions(+), 54 deletions(-) diff --git a/rust/pin-init/src/__internal.rs b/rust/pin-init/src/__internal.rs index cac293fd4bec..7f7744d48575 100644 --- a/rust/pin-init/src/__internal.rs +++ b/rust/pin-init/src/__internal.rs @@ -1,11 +1,9 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT -//! This module contains API-internal items for pin-init. +//! This module contains library internal items. //! -//! These items must not be used outside of -//! - `kernel/init.rs` -//! - `macros/pin_data.rs` -//! - `macros/pinned_drop.rs` +//! These items must not be used outside of this crate and the pin-init-internal crate located at +//! `../internal`. use super::*; diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index 58b77a158c34..a00288133ae3 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -1,10 +1,37 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT -//! API to safely and fallibly initialize pinned `struct`s using in-place constructors. +//! Library to safely and fallibly initialize pinned `struct`s using in-place constructors. +//! +//! [Pinning][pinning] is Rust's way of ensuring data does not move. //! //! It also allows in-place initialization of big `struct`s that would otherwise produce a stack //! overflow. //! +//! This library's main use-case is in [Rust-for-Linux]. Although this version can be used +//! standalone. +//! +//! There are cases when you want to in-place initialize a struct. For example when it is very big +//! and moving it from the stack is not an option, because it is bigger than the stack itself. +//! Another reason would be that you need the address of the object to initialize it. This stands +//! in direct conflict with Rust's normal process of first initializing an object and then moving +//! it into it's final memory location. For more information, see +//! . +//! +//! This library allows you to do in-place initialization safely. +//! +//! ## Nightly Needed for `alloc` feature +//! +//! This library requires the [`allocator_api` unstable feature] when the `alloc` feature is +//! enabled and thus this feature can only be used with a nightly compiler. When enabling the +//! `alloc` feature, the user will be required to activate `allocator_api` as well. +//! +//! [`allocator_api` unstable feature]: https://doc.rust-lang.org/nightly/unstable-book/library-features/allocator-api.html +//! +//! The feature is enabled by default, thus by default `pin-init` will require a nightly compiler. +//! However, using the crate on stable compilers is possible by disabling `alloc`. In practice this +//! will require the `std` feature, because stable compilers have neither `Box` nor `Arc` in no-std +//! mode. +//! //! # Overview //! //! To initialize a `struct` with an in-place constructor you will need two things: @@ -17,12 +44,17 @@ //! - 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 macros/types/functions are generally named like the pinned variants without the `pin` -//! prefix. +//! Aside from pinned initialization, this library also supports in-place construction without +//! pinning, the macros/types/functions are generally named like the pinned variants without the +//! `pin_` prefix. //! //! # Examples //! +//! Throughout the examples we will often make use of the `CMutex` type which can be found in +//! `../examples/mutex.rs`. It is essentially a userland rebuild of the `struct mutex` type from +//! the Linux kernel. It also uses a wait list and a basic spinlock. Importantly the wait list +//! requires it to be pinned to be locked and thus is a prime candidate for using this library. +//! //! ## Using the [`pin_init!`] macro //! //! If you want to use [`PinInit`], then you will have to annotate your `struct` with @@ -36,7 +68,7 @@ //! # #![feature(allocator_api)] //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; //! # use core::pin::Pin; -//! use pin_init::*; +//! use pin_init::{pin_data, pin_init, InPlaceInit}; //! //! #[pin_data] //! struct Foo { @@ -80,8 +112,8 @@ //! //! ## 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. +//! Many types that use this library supply a function/macro that returns an initializer, because +//! the above method only works for types where you can access the fields. //! //! ```rust,ignore //! # #![feature(allocator_api)] @@ -132,7 +164,7 @@ //! //! ```rust,ignore //! # #![feature(extern_types)] -//! use pin_init::*; +//! use pin_init::{pin_data, pinned_drop, PinInit, PinnedDrop, pin_init_from_closure}; //! use core::{ //! ptr::addr_of_mut, //! marker::PhantomPinned, @@ -141,8 +173,11 @@ //! mem::MaybeUninit, //! }; //! mod bindings { +//! #[repr(C)] +//! pub struct foo { +//! /* fields from C ... */ +//! } //! extern "C" { -//! pub type foo; //! pub fn init_foo(ptr: *mut foo); //! pub fn destroy_foo(ptr: *mut foo); //! #[must_use = "you must check the error return code"] @@ -200,6 +235,10 @@ //! } //! ``` //! +//! For more information on how to use [`pin_init_from_closure()`], take a look at the uses inside +//! the `kernel` crate. The [`sync`] module is a good starting point. +//! +//! [`sync`]: https://rust.docs.kernel.org/kernel/sync/index.html //! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]: //! https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field @@ -214,11 +253,10 @@ )] #![cfg_attr(not(kernel), doc = "[`Arc`]: alloc::alloc::sync::Arc")] #![cfg_attr(not(kernel), doc = "[`Box`]: alloc::alloc::boxed::Box")] -//! [`impl PinInit`]: PinInit -//! [`impl PinInit`]: PinInit -//! [`impl Init`]: Init -//! [`pin_data`]: crate::pin_data -//! [`pin_init!`]: crate::pin_init! +//! [`impl PinInit`]: crate::PinInit +//! [`impl PinInit`]: crate::PinInit +//! [`impl Init`]: crate::Init +//! [Rust-for-Linux]: https://rust-for-linux.com/ #![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))] #![cfg_attr( @@ -404,8 +442,6 @@ pub use ::pin_init_internal::Zeroable; /// A normal `let` binding with optional type annotation. The expression is expected to implement /// [`PinInit`]/[`Init`] with the error type [`Infallible`]. If you want to use a different error /// type, then use [`stack_try_pin_init!`]. -/// -/// [`stack_try_pin_init!`]: crate::stack_try_pin_init! #[macro_export] macro_rules! stack_pin_init { (let $var:ident $(: $t:ty)? = $val:expr) => { @@ -542,10 +578,10 @@ macro_rules! stack_try_pin_init { /// /// # 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. +/// When working with this library 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 library 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: /// @@ -674,22 +710,22 @@ macro_rules! stack_try_pin_init { /// #[pin] /// pin: PhantomPinned, /// } -/// pin_init!(&this in Buf { +/// +/// let init = pin_init!(&this in Buf { /// buf: [0; 64], /// // SAFETY: TODO. /// ptr: unsafe { addr_of_mut!((*this.as_ptr()).buf).cast() }, /// pin: PhantomPinned, /// }); -/// pin_init!(Buf { +/// let init = pin_init!(Buf { /// buf: [1; 64], /// ..Zeroable::zeroed() /// }); /// ``` /// -/// [`try_pin_init!`]: crate::try_pin_init /// [`NonNull`]: core::ptr::NonNull // For a detailed example of how this macro works, see the module documentation of the hidden -// module `__internal` inside of `init/__internal.rs`. +// module `macros` inside of `macros.rs`. #[macro_export] macro_rules! pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { @@ -719,7 +755,8 @@ macro_rules! pin_init { /// ```rust,ignore /// # #![feature(allocator_api)] /// # #[path = "../examples/error.rs"] mod error; use error::Error; -/// use pin_init::*; +/// use pin_init::{pin_data, try_pin_init, PinInit, InPlaceInit, zeroed}; +/// /// #[pin_data] /// struct BigBuf { /// big: Box<[u8; 1024 * 1024 * 1024]>, @@ -730,7 +767,7 @@ macro_rules! pin_init { /// impl BigBuf { /// fn new() -> impl PinInit { /// try_pin_init!(Self { -/// big: Box::init(init::zeroed())?, +/// big: Box::init(zeroed())?, /// small: [0; 1024 * 1024], /// ptr: core::ptr::null_mut(), /// }? Error) @@ -739,7 +776,7 @@ macro_rules! pin_init { /// # let _ = Box::pin_init(BigBuf::new()); /// ``` // For a detailed example of how this macro works, see the module documentation of the hidden -// module `__internal` inside of `init/__internal.rs`. +// module `macros` inside of `macros.rs`. #[macro_export] macro_rules! try_pin_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { @@ -772,9 +809,30 @@ 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!`]. /// -/// [`try_init!`]: crate::try_init! +/// # Examples +/// +/// ```rust +/// # #![feature(allocator_api)] +/// # #[path = "../examples/error.rs"] mod error; use error::Error; +/// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; +/// # use pin_init::InPlaceInit; +/// use pin_init::{init, Init, zeroed}; +/// +/// struct BigBuf { +/// small: [u8; 1024 * 1024], +/// } +/// +/// impl BigBuf { +/// fn new() -> impl Init { +/// init!(Self { +/// small <- zeroed(), +/// }) +/// } +/// } +/// # let _ = Box::init(BigBuf::new()); +/// ``` // For a detailed example of how this macro works, see the module documentation of the hidden -// module `__internal` inside of `init/__internal.rs`. +// module `macros` inside of `macros.rs`. #[macro_export] macro_rules! init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { @@ -804,7 +862,9 @@ macro_rules! init { /// ```rust,ignore /// # #![feature(allocator_api)] /// # use core::alloc::AllocError; -/// use pin_init::*; +/// # use pin_init::InPlaceInit; +/// use pin_init::{try_init, Init, zeroed}; +/// /// struct BigBuf { /// big: Box<[u8; 1024 * 1024 * 1024]>, /// small: [u8; 1024 * 1024], @@ -818,10 +878,10 @@ macro_rules! init { /// }? AllocError) /// } /// } +/// # let _ = Box::init(BigBuf::new()); /// ``` -/// [`try_pin_init!`]: crate::try_pin_init // For a detailed example of how this macro works, see the module documentation of the hidden -// module `__internal` inside of `init/__internal.rs`. +// module `macros` inside of `macros.rs`. #[macro_export] macro_rules! try_init { ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? { @@ -847,7 +907,8 @@ macro_rules! try_init { /// /// This will succeed: /// ```ignore -/// use pin_init::assert_pinned; +/// use pin_init::{pin_data, assert_pinned}; +/// /// #[pin_data] /// struct MyStruct { /// #[pin] @@ -859,7 +920,8 @@ macro_rules! try_init { /// /// This will fail: /// ```compile_fail,ignore -/// use pin_init::assert_pinned; +/// use pin_init::{pin_data, assert_pinned}; +/// /// #[pin_data] /// struct MyStruct { /// some_field: u64, @@ -872,7 +934,9 @@ macro_rules! try_init { /// work around this, you may pass the `inline` parameter to the macro. The `inline` parameter can /// only be used when the macro is invoked from a function body. /// ```ignore -/// use pin_init::assert_pinned; +/// # use core::pin::Pin; +/// use pin_init::{pin_data, assert_pinned}; +/// /// #[pin_data] /// struct Foo { /// #[pin] @@ -1056,14 +1120,15 @@ pub unsafe trait Init: PinInit { /// /// ```rust,ignore /// # #![expect(clippy::disallowed_names)] - /// use pin_init::{init_from_closure, zeroed}; + /// use pin_init::{init, zeroed, Init}; + /// /// struct Foo { /// buf: [u8; 1_000_000], /// } /// /// impl Foo { /// fn setup(&mut self) { - /// pr_info!("Setting up foo"); + /// println!("Setting up foo"); /// } /// } /// @@ -1302,8 +1367,6 @@ pub trait InPlaceWrite { /// # Safety /// /// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl. -/// -/// [`pinned_drop`]: crate::pinned_drop pub unsafe trait PinnedDrop: __internal::HasPinData { /// Executes the pinned destructor of this type. /// diff --git a/rust/pin-init/src/macros.rs b/rust/pin-init/src/macros.rs index d41c4f198c42..361623324d5c 100644 --- a/rust/pin-init/src/macros.rs +++ b/rust/pin-init/src/macros.rs @@ -1,8 +1,8 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT //! This module provides the macros that actually implement the proc-macros `pin_data` and -//! `pinned_drop`. It also contains `__init_internal` the implementation of the `{try_}{pin_}init!` -//! macros. +//! `pinned_drop`. It also contains `__init_internal`, the implementation of the +//! `{try_}{pin_}init!` macros. //! //! These macros should never be called directly, since they expect their input to be //! in a certain format which is internal. If used incorrectly, these macros can lead to UB even in @@ -11,16 +11,17 @@ //! This architecture has been chosen because the kernel does not yet have access to `syn` which //! would make matters a lot easier for implementing these as proc-macros. //! +//! Since this library and the kernel implementation should diverge as little as possible, the same +//! approach has been taken here. +//! //! # Macro expansion example //! //! This section is intended for readers trying to understand the macros in this module and the -//! `pin_init!` macros from `init.rs`. +//! `[try_][pin_]init!` macros from `lib.rs`. //! //! We will look at the following example: //! //! ```rust,ignore -//! # use pin_init::*; -//! # use core::pin::Pin; //! #[pin_data] //! #[repr(C)] //! struct Bar { @@ -45,7 +46,7 @@ //! #[pinned_drop] //! impl PinnedDrop for Foo { //! fn drop(self: Pin<&mut Self>) { -//! pr_info!("{self:p} is getting dropped."); +//! println!("{self:p} is getting dropped."); //! } //! } //! @@ -75,7 +76,6 @@ //! Here is the definition of `Bar` from our example: //! //! ```rust,ignore -//! # use pin_init::*; //! #[pin_data] //! #[repr(C)] //! struct Bar { @@ -251,7 +251,7 @@ //! // is an error later. This `DropGuard` will drop the field when it gets //! // dropped and has not yet been forgotten. //! let __t_guard = unsafe { -//! ::pinned_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).t)) +//! ::pin_init::__internal::DropGuard::new(::core::addr_of_mut!((*slot).t)) //! }; //! // Expansion of `x: 0,`: //! // Since this can be an arbitrary expression we cannot place it inside @@ -412,7 +412,7 @@ //! #[pinned_drop] //! impl PinnedDrop for Foo { //! fn drop(self: Pin<&mut Self>) { -//! pr_info!("{self:p} is getting dropped."); +//! println!("{self:p} is getting dropped."); //! } //! } //! ``` @@ -423,7 +423,7 @@ //! // `unsafe`, full path and the token parameter are added, everything else stays the same. //! unsafe impl ::pin_init::PinnedDrop for Foo { //! fn drop(self: Pin<&mut Self>, _: ::pin_init::__internal::OnlyCallFromDrop) { -//! pr_info!("{self:p} is getting dropped."); +//! println!("{self:p} is getting dropped."); //! } //! } //! ``` From 7cb5dee4c8349f8cc3e1ce529df4e18ebe3fed2e Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:22 +0000 Subject: [PATCH 38/71] rust: pin-init: internal: synchronize with user-space version Synchronize the internal macros crate with the user-space version that uses the quote crate [1] instead of a custom `quote!` macro. The imports in the different version are achieved using `cfg` on the kernel config value. This cfg is always set in the kernel and never set in the user-space version. Since the quote crate requires the proc_macro2 crate, imports also need to be adjusted and `.into()` calls have to be inserted. Link: https://crates.io/crates/quote [1] Signed-off-by: Benno Lossin Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Reviewed-by: Fiona Behrens Link: https://lore.kernel.org/r/20250308110339.2997091-19-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/internal/src/helpers.rs | 3 +++ rust/pin-init/internal/src/lib.rs | 16 +++++++++++++--- rust/pin-init/internal/src/pin_data.rs | 3 +++ rust/pin-init/internal/src/pinned_drop.rs | 3 +++ rust/pin-init/internal/src/zeroable.rs | 3 +++ 5 files changed, 25 insertions(+), 3 deletions(-) diff --git a/rust/pin-init/internal/src/helpers.rs b/rust/pin-init/internal/src/helpers.rs index 78521ba19d0b..236f989a50f2 100644 --- a/rust/pin-init/internal/src/helpers.rs +++ b/rust/pin-init/internal/src/helpers.rs @@ -1,5 +1,8 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT +#[cfg(not(kernel))] +use proc_macro2 as proc_macro; + use proc_macro::{TokenStream, TokenTree}; /// Parsed generics. diff --git a/rust/pin-init/internal/src/lib.rs b/rust/pin-init/internal/src/lib.rs index c201b8a53915..30e145f80bc0 100644 --- a/rust/pin-init/internal/src/lib.rs +++ b/rust/pin-init/internal/src/lib.rs @@ -7,6 +7,13 @@ //! `pin-init` proc macros. #![cfg_attr(not(RUSTC_LINT_REASONS_IS_STABLE), feature(lint_reasons))] +// Allow `.into()` to convert +// - `proc_macro2::TokenStream` into `proc_macro::TokenStream` in the user-space version. +// - `proc_macro::TokenStream` into `proc_macro::TokenStream` in the kernel version. +// Clippy warns on this conversion, but it's required by the user-space version. +// +// Remove once we have `proc_macro2` in the kernel. +#![allow(clippy::useless_conversion)] use proc_macro::TokenStream; @@ -14,6 +21,9 @@ use proc_macro::TokenStream; #[path = "../../../macros/quote.rs"] #[macro_use] mod quote; +#[cfg(not(kernel))] +#[macro_use] +extern crate quote; mod helpers; mod pin_data; @@ -23,17 +33,17 @@ mod zeroable; #[allow(missing_docs)] #[proc_macro_attribute] pub fn pin_data(inner: TokenStream, item: TokenStream) -> TokenStream { - pin_data::pin_data(inner, item) + pin_data::pin_data(inner.into(), item.into()).into() } #[allow(missing_docs)] #[proc_macro_attribute] pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream { - pinned_drop::pinned_drop(args, input) + pinned_drop::pinned_drop(args.into(), input.into()).into() } #[allow(missing_docs)] #[proc_macro_derive(Zeroable)] pub fn derive_zeroable(input: TokenStream) -> TokenStream { - zeroable::derive(input) + zeroable::derive(input.into()).into() } diff --git a/rust/pin-init/internal/src/pin_data.rs b/rust/pin-init/internal/src/pin_data.rs index 9b974498f4a8..87d4a7eb1d35 100644 --- a/rust/pin-init/internal/src/pin_data.rs +++ b/rust/pin-init/internal/src/pin_data.rs @@ -1,5 +1,8 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT +#[cfg(not(kernel))] +use proc_macro2 as proc_macro; + use crate::helpers::{parse_generics, Generics}; use proc_macro::{Group, Punct, Spacing, TokenStream, TokenTree}; diff --git a/rust/pin-init/internal/src/pinned_drop.rs b/rust/pin-init/internal/src/pinned_drop.rs index 386f52f73c06..c824dd8b436d 100644 --- a/rust/pin-init/internal/src/pinned_drop.rs +++ b/rust/pin-init/internal/src/pinned_drop.rs @@ -1,5 +1,8 @@ // SPDX-License-Identifier: Apache-2.0 OR MIT +#[cfg(not(kernel))] +use proc_macro2 as proc_macro; + use proc_macro::{TokenStream, TokenTree}; pub(crate) fn pinned_drop(_args: TokenStream, input: TokenStream) -> TokenStream { diff --git a/rust/pin-init/internal/src/zeroable.rs b/rust/pin-init/internal/src/zeroable.rs index 0cf6732f27dc..acc94008c152 100644 --- a/rust/pin-init/internal/src/zeroable.rs +++ b/rust/pin-init/internal/src/zeroable.rs @@ -1,5 +1,8 @@ // SPDX-License-Identifier: GPL-2.0 +#[cfg(not(kernel))] +use proc_macro2 as proc_macro; + use crate::helpers::{parse_generics, Generics}; use proc_macro::{TokenStream, TokenTree}; From a9fa3a9c6e28658cc6018a06310a9327add606ab Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:27 +0000 Subject: [PATCH 39/71] rust: pin-init: miscellaneous synchronization with the user-space version Remove the last differences between the kernel version and the user-space version. Signed-off-by: Benno Lossin Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Reviewed-by: Fiona Behrens Link: https://lore.kernel.org/r/20250308110339.2997091-20-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/internal/src/lib.rs | 5 ++--- rust/pin-init/src/__internal.rs | 2 +- rust/pin-init/src/lib.rs | 2 -- 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/rust/pin-init/internal/src/lib.rs b/rust/pin-init/internal/src/lib.rs index 30e145f80bc0..babe5e878550 100644 --- a/rust/pin-init/internal/src/lib.rs +++ b/rust/pin-init/internal/src/lib.rs @@ -14,6 +14,8 @@ // // Remove once we have `proc_macro2` in the kernel. #![allow(clippy::useless_conversion)] +// Documentation is done in the pin-init crate instead. +#![allow(missing_docs)] use proc_macro::TokenStream; @@ -30,19 +32,16 @@ mod pin_data; mod pinned_drop; mod zeroable; -#[allow(missing_docs)] #[proc_macro_attribute] pub fn pin_data(inner: TokenStream, item: TokenStream) -> TokenStream { pin_data::pin_data(inner.into(), item.into()).into() } -#[allow(missing_docs)] #[proc_macro_attribute] pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream { pinned_drop::pinned_drop(args.into(), input.into()).into() } -#[allow(missing_docs)] #[proc_macro_derive(Zeroable)] pub fn derive_zeroable(input: TokenStream) -> TokenStream { zeroable::derive(input.into()).into() diff --git a/rust/pin-init/src/__internal.rs b/rust/pin-init/src/__internal.rs index 7f7744d48575..557b5948cddc 100644 --- a/rust/pin-init/src/__internal.rs +++ b/rust/pin-init/src/__internal.rs @@ -14,7 +14,7 @@ use super::*; /// /// [nomicon]: https://doc.rust-lang.org/nomicon/subtyping.html /// [this table]: https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns -pub(super) type Invariant = PhantomData *mut T>; +pub(crate) type Invariant = PhantomData *mut T>; /// Module-internal type implementing `PinInit` and `Init`. /// diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index a00288133ae3..45880ffa81bb 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -349,8 +349,6 @@ pub use alloc::InPlaceInit; /// } /// } /// ``` -/// -/// [`pin_init!`]: crate::pin_init pub use ::pin_init_internal::pin_data; /// Used to implement `PinnedDrop` safely. From 2e5f4f3cf27b620ebf0f403fd0dfe680c437600b Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:31 +0000 Subject: [PATCH 40/71] rust: pin-init: add miscellaneous files from the user-space version Add readme and contribution guidelines of the user-space version of pin-init. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-21-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/CONTRIBUTING.md | 72 +++++++++++ rust/pin-init/README.md | 228 ++++++++++++++++++++++++++++++++++ 2 files changed, 300 insertions(+) create mode 100644 rust/pin-init/CONTRIBUTING.md create mode 100644 rust/pin-init/README.md diff --git a/rust/pin-init/CONTRIBUTING.md b/rust/pin-init/CONTRIBUTING.md new file mode 100644 index 000000000000..16c899a7ae0b --- /dev/null +++ b/rust/pin-init/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to `pin-init` + +Thanks for showing interest in contributing to `pin-init`! This document outlines the guidelines for +contributing to `pin-init`. + +All contributions are double-licensed under Apache 2.0 and MIT. You can find the respective licenses +in the `LICENSE-APACHE` and `LICENSE-MIT` files. + +## Non-Code Contributions + +### Bug Reports + +For any type of bug report, please submit an issue using the bug report issue template. + +If the issue is a soundness issue, please privately report it as a security vulnerability via the +GitHub web interface. + +### Feature Requests + +If you have any feature requests, please submit an issue using the feature request issue template. + +### Questions and Getting Help + +You can ask questions in the Discussions page of the GitHub repository. If you're encountering +problems or just have questions related to `pin-init` in the Linux kernel, you can also ask your +questions in the [Rust-for-Linux Zulip](https://rust-for-linux.zulipchat.com/) or see +. + +## Contributing Code + +### Linux Kernel + +`pin-init` is used by the Linux kernel and all commits are synchronized to it. For this reason, the +same requirements for commits apply to `pin-init`. See [the kernel's documentation] for details. The +rest of this document will also cover some of the rules listed there and additional ones. + +[the kernel's documentation]: https://docs.kernel.org/process/submitting-patches.html + +Contributions to `pin-init` ideally go through the [GitHub repository], because that repository runs +a CI with lots of tests not present in the kernel. However, patches are also accepted (though not +preferred). Do note that there are some files that are only present in the GitHub repository such as +tests, licenses and cargo related files. Making changes to them can only happen via GitHub. + +[GitHub repository]: https://github.com/Rust-for-Linux/pin-init + +### Commit Style + +Everything must compile without errors or warnings and all tests must pass after **every commit**. +This is important for bisection and also required by the kernel. + +Each commit should be a single, logically cohesive change. Of course it's best to keep the changes +small and digestible, but logically linked changes should be made in the same commit. For example, +when fixing typos, create a single commit that fixes all of them instead of one commit per typo. + +Commits must have a meaningful commit title. Commits with changes to files in the `internal` +directory should have a title prefixed with `internal:`. The commit message should explain the +change and its rationale. You also have to add your `Signed-off-by` tag, see [Developer's +Certificate of Origin]. This has to be done for both mailing list submissions as well as GitHub +submissions. + +[Developer's Certificate of Origin]: https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + +Any changes made to public APIs must be documented not only in the commit message, but also in the +`CHANGELOG.md` file. This is especially important for breaking changes, as those warrant a major +version bump. + +If you make changes to the top-level crate documentation, you also need to update the `README.md` +via `cargo rdme`. + +Some of these rules can be ignored if the change is done solely to files that are not present in the +kernel version of this library. Those files are documented in the `sync-kernel.sh` script at the +very bottom in the `--exclude` flag given to the `git am` command. diff --git a/rust/pin-init/README.md b/rust/pin-init/README.md new file mode 100644 index 000000000000..3d04796b212b --- /dev/null +++ b/rust/pin-init/README.md @@ -0,0 +1,228 @@ +[![Crates.io](https://img.shields.io/crates/v/pin-init.svg)](https://crates.io/crates/pin-init) +[![Documentation](https://docs.rs/pin-init/badge.svg)](https://docs.rs/pin-init/) +[![Dependency status](https://deps.rs/repo/github/Rust-for-Linux/pin-init/status.svg)](https://deps.rs/repo/github/Rust-for-Linux/pin-init) +![License](https://img.shields.io/crates/l/pin-init) +[![Toolchain](https://img.shields.io/badge/toolchain-nightly-red)](#nightly-only) +![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/Rust-for-Linux/pin-init/test.yml) +# `pin-init` + + + +Library to safely and fallibly initialize pinned `struct`s using in-place constructors. + +[Pinning][pinning] is Rust's way of ensuring data does not move. + +It also allows in-place initialization of big `struct`s that would otherwise produce a stack +overflow. + +This library's main use-case is in [Rust-for-Linux]. Although this version can be used +standalone. + +There are cases when you want to in-place initialize a struct. For example when it is very big +and moving it from the stack is not an option, because it is bigger than the stack itself. +Another reason would be that you need the address of the object to initialize it. This stands +in direct conflict with Rust's normal process of first initializing an object and then moving +it into it's final memory location. For more information, see +. + +This library allows you to do in-place initialization safely. + +### Nightly Needed for `alloc` feature + +This library requires the [`allocator_api` unstable feature] when the `alloc` feature is +enabled and thus this feature can only be used with a nightly compiler. When enabling the +`alloc` feature, the user will be required to activate `allocator_api` as well. + +[`allocator_api` unstable feature]: https://doc.rust-lang.org/nightly/unstable-book/library-features/allocator-api.html + +The feature is enabled by default, thus by default `pin-init` will require a nightly compiler. +However, using the crate on stable compilers is possible by disabling `alloc`. In practice this +will require the `std` feature, because stable compilers have neither `Box` nor `Arc` in no-std +mode. + +## 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` (this can be the [stack], an [`Arc`], + [`Box`] or any other smart pointer that supports this library). + +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. + +Aside from pinned initialization, this library also supports in-place construction without +pinning, the macros/types/functions are generally named like the pinned variants without the +`pin_` prefix. + +## Examples + +Throughout the examples we will often make use of the `CMutex` type which can be found in +`../examples/mutex.rs`. It is essentially a userland rebuild of the `struct mutex` type from +the Linux kernel. It also uses a wait list and a basic spinlock. Importantly the wait list +requires it to be pinned to be locked and thus is a prime candidate for using this library. + +### 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 +use pin_init::{pin_data, pin_init, InPlaceInit}; + +#[pin_data] +struct Foo { + #[pin] + a: CMutex, + b: u32, +} + +let foo = pin_init!(Foo { + a <- CMutex::new(42), + b: 24, +}); +``` + +`foo` now is of the type [`impl PinInit`]. We can now use any smart pointer that we like +(or just the stack) to actually initialize a `Foo`: + +```rust +let foo: Result>, AllocError> = Box::pin_init(foo); +``` + +For more information see the [`pin_init!`] macro. + +### Using a custom function/macro that returns an initializer + +Many types that use this library supply a function/macro that returns an initializer, because +the above method only works for types where you can access the fields. + +```rust +let mtx: Result>>, _> = Arc::pin_init(CMutex::new(42)); +``` + +To declare an init macro/function you just return an [`impl PinInit`]: + +```rust +#[pin_data] +struct DriverData { + #[pin] + status: CMutex, + buffer: Box<[u8; 1_000_000]>, +} + +impl DriverData { + fn new() -> impl PinInit { + try_pin_init!(Self { + status <- CMutex::new(0), + buffer: Box::init(pin_init::zeroed())?, + }? Error) + } +} +``` + +### 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`] 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 pin_init::{pin_data, pinned_drop, PinInit, PinnedDrop, pin_init_from_closure}; +use core::{ + ptr::addr_of_mut, + marker::PhantomPinned, + cell::UnsafeCell, + pin::Pin, + mem::MaybeUninit, +}; +mod bindings { + #[repr(C)] + pub struct foo { + /* fields from C ... */ + } + extern "C" { + pub fn init_foo(ptr: *mut foo); + pub fn destroy_foo(ptr: *mut foo); + #[must_use = "you must check the error return code"] + pub fn enable_foo(ptr: *mut foo, flags: u32) -> i32; + } +} + +/// # Invariants +/// +/// `foo` is always initialized +#[pin_data(PinnedDrop)] +pub struct RawFoo { + #[pin] + _p: PhantomPinned, + #[pin] + foo: UnsafeCell>, +} + +impl RawFoo { + pub fn new(flags: u32) -> impl PinInit { + // 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 { + pin_init_from_closure(move |slot: *mut Self| { + // `slot` contains uninit memory, avoid creating a reference. + let foo = addr_of_mut!((*slot).foo); + let foo = UnsafeCell::raw_get(foo).cast::(); + + // Initialize the `foo` + bindings::init_foo(foo); + + // Try to enable it. + let err = bindings::enable_foo(foo, flags); + if err != 0 { + // Enabling has failed, first clean up the foo and then return the error. + bindings::destroy_foo(foo); + Err(err) + } else { + // 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().cast::()) }; + } +} +``` + +For more information on how to use [`pin_init_from_closure()`], take a look at the uses inside +the `kernel` crate. The [`sync`] module is a good starting point. + +[`sync`]: https://rust.docs.kernel.org/kernel/sync/index.html +[pinning]: https://doc.rust-lang.org/std/pin/index.html +[structurally pinned fields]: https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field +[stack]: https://docs.rs/pin-init/latest/pin_init/macro.stack_pin_init.html +[`Arc`]: https://doc.rust-lang.org/stable/alloc/sync/struct.Arc.html +[`Box`]: https://doc.rust-lang.org/stable/alloc/boxed/struct.Box.html +[`impl PinInit`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html +[`impl PinInit`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html +[`impl Init`]: https://docs.rs/pin-init/latest/pin_init/trait.Init.html +[Rust-for-Linux]: https://rust-for-linux.com/ + + From 1ab10101cd311703d8d53ace36d96c4cfd406a69 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:35 +0000 Subject: [PATCH 41/71] rust: pin-init: re-enable doctests The pin-init crate is now compiled in a standalone fashion, so revert the earlier commit that disabled the doctests in pin-init in order to avoid build errors while transitioning the crate into a standalone version. Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-22-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- rust/pin-init/src/lib.rs | 54 ++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs index 45880ffa81bb..f36b8f8e8730 100644 --- a/rust/pin-init/src/lib.rs +++ b/rust/pin-init/src/lib.rs @@ -63,7 +63,7 @@ //! [`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,ignore +//! ```rust //! # #![expect(clippy::disallowed_names)] //! # #![feature(allocator_api)] //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; @@ -87,7 +87,7 @@ //! `foo` now is of the type [`impl PinInit`]. We can now use any smart pointer that we like //! (or just the stack) to actually initialize a `Foo`: //! -//! ```rust,ignore +//! ```rust //! # #![expect(clippy::disallowed_names)] //! # #![feature(allocator_api)] //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; @@ -115,7 +115,7 @@ //! Many types that use this library supply a function/macro that returns an initializer, because //! the above method only works for types where you can access the fields. //! -//! ```rust,ignore +//! ```rust //! # #![feature(allocator_api)] //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; //! # use pin_init::*; @@ -126,7 +126,7 @@ //! //! To declare an init macro/function you just return an [`impl PinInit`]: //! -//! ```rust,ignore +//! ```rust //! # #![feature(allocator_api)] //! # use pin_init::*; //! # #[path = "../examples/error.rs"] mod error; use error::Error; @@ -162,7 +162,7 @@ //! - you may assume that `slot` will stay pinned even after the closure returns until `drop` of //! `slot` gets called. //! -//! ```rust,ignore +//! ```rust //! # #![feature(extern_types)] //! use pin_init::{pin_data, pinned_drop, PinInit, PinnedDrop, pin_init_from_closure}; //! use core::{ @@ -306,7 +306,7 @@ pub use alloc::InPlaceInit; /// /// # Examples /// -/// ```ignore +/// ``` /// # #![feature(allocator_api)] /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; /// use pin_init::pin_data; @@ -323,7 +323,7 @@ pub use alloc::InPlaceInit; /// } /// ``` /// -/// ```ignore +/// ``` /// # #![feature(allocator_api)] /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; /// # mod bindings { pub struct info; pub unsafe fn destroy_info(_: *mut info) {} } @@ -357,7 +357,7 @@ pub use ::pin_init_internal::pin_data; /// /// # Examples /// -/// ```ignore +/// ``` /// # #![feature(allocator_api)] /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; /// # mod bindings { pub struct info; pub unsafe fn destroy_info(_: *mut info) {} } @@ -391,7 +391,7 @@ pub use ::pin_init_internal::pinned_drop; /// /// # Examples /// -/// ```ignore +/// ``` /// use pin_init::Zeroable; /// /// #[derive(Zeroable)] @@ -407,7 +407,7 @@ pub use ::pin_init_internal::Zeroable; /// /// # Examples /// -/// ```rust,ignore +/// ```rust /// # #![expect(clippy::disallowed_names)] /// # #![feature(allocator_api)] /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; @@ -459,7 +459,7 @@ macro_rules! stack_pin_init { /// /// # Examples /// -/// ```rust,ignore +/// ```rust /// # #![expect(clippy::disallowed_names)] /// # #![feature(allocator_api)] /// # #[path = "../examples/error.rs"] mod error; use error::Error; @@ -486,7 +486,7 @@ macro_rules! stack_pin_init { /// println!("a: {}", &*foo.a.lock()); /// ``` /// -/// ```rust,ignore +/// ```rust /// # #![expect(clippy::disallowed_names)] /// # #![feature(allocator_api)] /// # #[path = "../examples/error.rs"] mod error; use error::Error; @@ -539,7 +539,7 @@ macro_rules! stack_try_pin_init { /// /// The syntax is almost identical to that of a normal `struct` initializer: /// -/// ```rust,ignore +/// ```rust /// # use pin_init::*; /// # use core::pin::Pin; /// #[pin_data] @@ -583,7 +583,7 @@ macro_rules! stack_try_pin_init { /// /// To create an initializer function, simply declare it like this: /// -/// ```rust,ignore +/// ```rust /// # use pin_init::*; /// # use core::pin::Pin; /// # #[pin_data] @@ -609,7 +609,7 @@ macro_rules! stack_try_pin_init { /// /// Users of `Foo` can now create it like this: /// -/// ```rust,ignore +/// ```rust /// # #![expect(clippy::disallowed_names)] /// # use pin_init::*; /// # use core::pin::Pin; @@ -637,7 +637,7 @@ macro_rules! stack_try_pin_init { /// /// They can also easily embed it into their own `struct`s: /// -/// ```rust,ignore +/// ```rust /// # use pin_init::*; /// # use core::pin::Pin; /// # #[pin_data] @@ -696,7 +696,7 @@ macro_rules! stack_try_pin_init { /// /// For instance: /// -/// ```rust,ignore +/// ```rust /// # use pin_init::*; /// # use core::{ptr::addr_of_mut, marker::PhantomPinned}; /// #[pin_data] @@ -750,7 +750,7 @@ macro_rules! pin_init { /// /// # Examples /// -/// ```rust,ignore +/// ```rust /// # #![feature(allocator_api)] /// # #[path = "../examples/error.rs"] mod error; use error::Error; /// use pin_init::{pin_data, try_pin_init, PinInit, InPlaceInit, zeroed}; @@ -857,7 +857,7 @@ macro_rules! init { /// /// # Examples /// -/// ```rust,ignore +/// ```rust /// # #![feature(allocator_api)] /// # use core::alloc::AllocError; /// # use pin_init::InPlaceInit; @@ -904,7 +904,7 @@ macro_rules! try_init { /// # Example /// /// This will succeed: -/// ```ignore +/// ``` /// use pin_init::{pin_data, assert_pinned}; /// /// #[pin_data] @@ -917,7 +917,7 @@ macro_rules! try_init { /// ``` /// /// This will fail: -/// ```compile_fail,ignore +/// ```compile_fail /// use pin_init::{pin_data, assert_pinned}; /// /// #[pin_data] @@ -931,7 +931,7 @@ macro_rules! try_init { /// Some uses of the macro may trigger the `can't use generic parameters from outer item` error. To /// work around this, you may pass the `inline` parameter to the macro. The `inline` parameter can /// only be used when the macro is invoked from a function body. -/// ```ignore +/// ``` /// # use core::pin::Pin; /// use pin_init::{pin_data, assert_pinned}; /// @@ -1018,7 +1018,7 @@ pub unsafe trait PinInit: Sized { /// /// # Examples /// - /// ```rust,ignore + /// ```rust /// # #![feature(allocator_api)] /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; /// # use pin_init::*; @@ -1116,7 +1116,7 @@ pub unsafe trait Init: PinInit { /// /// # Examples /// - /// ```rust,ignore + /// ```rust /// # #![expect(clippy::disallowed_names)] /// use pin_init::{init, zeroed, Init}; /// @@ -1229,7 +1229,7 @@ pub fn uninit() -> impl Init, E> { /// /// # Examples /// -/// ```rust,ignore +/// ```rust /// # use pin_init::*; /// use pin_init::init_array_from_fn; /// let array: Box<[usize; 1_000]> = Box::init(init_array_from_fn(|i| i)).unwrap(); @@ -1267,7 +1267,7 @@ where /// /// # Examples /// -/// ```rust,ignore +/// ```rust /// # #![feature(allocator_api)] /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; /// # use pin_init::*; @@ -1343,7 +1343,7 @@ pub trait InPlaceWrite { /// /// Use [`pinned_drop`] to implement this trait safely: /// -/// ```rust,ignore +/// ```rust /// # #![feature(allocator_api)] /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*; /// # use pin_init::*; From cf25bc61f8aecad9b0c45fe32697e35ea4b13378 Mon Sep 17 00:00:00 2001 From: Benno Lossin Date: Sat, 8 Mar 2025 11:05:39 +0000 Subject: [PATCH 42/71] MAINTAINERS: add entry for the `pin-init` crate Add maintainers entry for the `pin-init` crate. This crate is already being maintained by me, but until now there existed two different versions: the version inside of the kernel tree and a user-space version at [1]. The previous patches synchronized these two versions to reduce the maintenance burden. In order to keep them synchronized from now on, separate the maintenance from other Rust code. Link: https://github.com/Rust-for-Linux/pin-init [1] Signed-off-by: Benno Lossin Link: https://lore.kernel.org/r/20250308110339.2997091-23-benno.lossin@proton.me Signed-off-by: Miguel Ojeda --- MAINTAINERS | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/MAINTAINERS b/MAINTAINERS index 007ca67cc830..72b88f1638a2 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -20737,6 +20737,19 @@ T: git https://github.com/Rust-for-Linux/linux.git alloc-next F: rust/kernel/alloc.rs F: rust/kernel/alloc/ +RUST [PIN-INIT] +M: Benno Lossin +L: rust-for-linux@vger.kernel.org +S: Maintained +W: https://rust-for-linux.com/pin-init +B: https://github.com/Rust-for-Linux/pin-init/issues +C: zulip://rust-for-linux.zulipchat.com +P: rust/pin-init/CONTRIBUTING.md +T: git https://github.com/Rust-for-Linux/linux.git pin-init-next +F: rust/kernel/init.rs +F: rust/pin-init/ +K: \bpin-init\b|pin_init\b|PinInit + RXRPC SOCKETS (AF_RXRPC) M: David Howells M: Marc Dionne From 6b2dab17d6fad9d94faae45b46bef307d8560cdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20Wei=C3=9Fschuh?= Date: Sat, 8 Feb 2025 14:31:14 +0100 Subject: [PATCH 43/71] rust: pass correct target to bindgen on Usermode Linux MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Usermode Linux uses "um" as primary architecture name and the underlying physical architecture is provided in "SUBARCH". Resolve the target architecture flags through that underlying architecture. This is the same pattern as used by scripts/Makefile.clang from which the bindgen flags are derived. [ David says: (...) this is enough to get Rust-for-Linux working with gcc under 64-bit UML on my system. - Miguel ] Signed-off-by: Thomas Weißschuh Reviewed-by: David Gow Acked-by: Johannes Berg Link: https://lore.kernel.org/r/20250208-rust-kunit-v1-1-94a026be6d72@weissschuh.net Signed-off-by: Miguel Ojeda --- rust/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/rust/Makefile b/rust/Makefile index e761a8cc3bd5..b9cc810764e9 100644 --- a/rust/Makefile +++ b/rust/Makefile @@ -274,6 +274,7 @@ bindgen_skip_c_flags := -mno-fp-ret-in-387 -mpreferred-stack-boundary=% \ # Derived from `scripts/Makefile.clang`. BINDGEN_TARGET_x86 := x86_64-linux-gnu BINDGEN_TARGET_arm64 := aarch64-linux-gnu +BINDGEN_TARGET_um := $(BINDGEN_TARGET_$(SUBARCH)) BINDGEN_TARGET := $(BINDGEN_TARGET_$(SRCARCH)) # All warnings are inhibited since GCC builds are very experimental, From fb625227d540ddead4d21813410a116e9452d232 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20Wei=C3=9Fschuh?= Date: Sat, 8 Feb 2025 14:31:15 +0100 Subject: [PATCH 44/71] rust: add kunitconfig MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The kunitconfig file in a directory is used by kunit.py to enable all necessary kernel configurations to run the tests in that subdirectory. Add such a file for rust/. Signed-off-by: Thomas Weißschuh Reviewed-by: David Gow Link: https://lore.kernel.org/r/20250208-rust-kunit-v1-2-94a026be6d72@weissschuh.net Signed-off-by: Miguel Ojeda --- rust/.kunitconfig | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 rust/.kunitconfig diff --git a/rust/.kunitconfig b/rust/.kunitconfig new file mode 100644 index 000000000000..9e72a5ab03c9 --- /dev/null +++ b/rust/.kunitconfig @@ -0,0 +1,3 @@ +CONFIG_KUNIT=y +CONFIG_RUST=y +CONFIG_RUST_KERNEL_DOCTESTS=y From 22097b966f5d2be93b315c791a26d4ed9b37f195 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Exp=C3=B3sito?= Date: Fri, 7 Mar 2025 17:00:56 +0800 Subject: [PATCH 45/71] rust: kunit: add KUnit case and suite macros MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a couple of Rust const functions and macros to allow to develop KUnit tests without relying on generated C code: - The `kunit_unsafe_test_suite!` Rust macro is similar to the `kunit_test_suite` C macro. It requires a NULL-terminated array of test cases (see below). - The `kunit_case` Rust function is similar to the `KUNIT_CASE` C macro. It generates as case from the name and function. - The `kunit_case_null` Rust function generates a NULL test case, which is to be used as delimiter in `kunit_test_suite!`. While these functions and macros can be used on their own, a future patch will introduce another macro to create KUnit tests using a user-space like syntax. Signed-off-by: José Expósito Co-developed-by: Matt Gilbride Signed-off-by: Matt Gilbride Co-developed-by: Miguel Ojeda Signed-off-by: Miguel Ojeda Co-developed-by: David Gow Signed-off-by: David Gow Link: https://lore.kernel.org/r/20250307090103.918788-2-davidgow@google.com [ Applied Markdown in comment. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/kunit.rs | 124 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs index 824da0e9738a..e777a4e03e4b 100644 --- a/rust/kernel/kunit.rs +++ b/rust/kernel/kunit.rs @@ -161,3 +161,127 @@ macro_rules! kunit_assert_eq { $crate::kunit_assert!($name, $file, $diff, $left == $right); }}; } + +/// Represents an individual test case. +/// +/// The [`kunit_unsafe_test_suite!`] macro expects a NULL-terminated list of valid test cases. +/// Use [`kunit_case_null`] to generate such a delimiter. +#[doc(hidden)] +pub const fn kunit_case( + name: &'static kernel::str::CStr, + run_case: unsafe extern "C" fn(*mut kernel::bindings::kunit), +) -> kernel::bindings::kunit_case { + kernel::bindings::kunit_case { + run_case: Some(run_case), + name: name.as_char_ptr(), + attr: kernel::bindings::kunit_attributes { + speed: kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL, + }, + generate_params: None, + status: kernel::bindings::kunit_status_KUNIT_SUCCESS, + module_name: core::ptr::null_mut(), + log: core::ptr::null_mut(), + } +} + +/// Represents the NULL test case delimiter. +/// +/// The [`kunit_unsafe_test_suite!`] macro expects a NULL-terminated list of test cases. This +/// function returns such a delimiter. +#[doc(hidden)] +pub const fn kunit_case_null() -> kernel::bindings::kunit_case { + kernel::bindings::kunit_case { + run_case: None, + name: core::ptr::null_mut(), + generate_params: None, + attr: kernel::bindings::kunit_attributes { + speed: kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL, + }, + status: kernel::bindings::kunit_status_KUNIT_SUCCESS, + module_name: core::ptr::null_mut(), + log: core::ptr::null_mut(), + } +} + +/// Registers a KUnit test suite. +/// +/// # Safety +/// +/// `test_cases` must be a NULL terminated array of valid test cases, +/// whose lifetime is at least that of the test suite (i.e., static). +/// +/// # Examples +/// +/// ```ignore +/// extern "C" fn test_fn(_test: *mut kernel::bindings::kunit) { +/// let actual = 1 + 1; +/// let expected = 2; +/// assert_eq!(actual, expected); +/// } +/// +/// static mut KUNIT_TEST_CASES: [kernel::bindings::kunit_case; 2] = [ +/// kernel::kunit::kunit_case(kernel::c_str!("name"), test_fn), +/// kernel::kunit::kunit_case_null(), +/// ]; +/// kernel::kunit_unsafe_test_suite!(suite_name, KUNIT_TEST_CASES); +/// ``` +#[doc(hidden)] +#[macro_export] +macro_rules! kunit_unsafe_test_suite { + ($name:ident, $test_cases:ident) => { + const _: () = { + const KUNIT_TEST_SUITE_NAME: [::kernel::ffi::c_char; 256] = { + let name_u8 = ::core::stringify!($name).as_bytes(); + let mut ret = [0; 256]; + + if name_u8.len() > 255 { + panic!(concat!( + "The test suite name `", + ::core::stringify!($name), + "` exceeds the maximum length of 255 bytes." + )); + } + + let mut i = 0; + while i < name_u8.len() { + ret[i] = name_u8[i] as ::kernel::ffi::c_char; + i += 1; + } + + ret + }; + + static mut KUNIT_TEST_SUITE: ::kernel::bindings::kunit_suite = + ::kernel::bindings::kunit_suite { + name: KUNIT_TEST_SUITE_NAME, + #[allow(unused_unsafe)] + // SAFETY: `$test_cases` is passed in by the user, and + // (as documented) must be valid for the lifetime of + // the suite (i.e., static). + test_cases: unsafe { + ::core::ptr::addr_of_mut!($test_cases) + .cast::<::kernel::bindings::kunit_case>() + }, + suite_init: None, + suite_exit: None, + init: None, + exit: None, + attr: ::kernel::bindings::kunit_attributes { + speed: ::kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL, + }, + status_comment: [0; 256usize], + debugfs: ::core::ptr::null_mut(), + log: ::core::ptr::null_mut(), + suite_init_err: 0, + is_init: false, + }; + + #[used] + #[allow(unused_unsafe)] + #[cfg_attr(not(target_os = "macos"), link_section = ".kunit_test_suites")] + static mut KUNIT_TEST_SUITE_ENTRY: *const ::kernel::bindings::kunit_suite = + // SAFETY: `KUNIT_TEST_SUITE` is static. + unsafe { ::core::ptr::addr_of_mut!(KUNIT_TEST_SUITE) }; + }; + }; +} From c0010452893e07e032427e88f6b7b4bf7ac42e95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Exp=C3=B3sito?= Date: Fri, 7 Mar 2025 17:00:57 +0800 Subject: [PATCH 46/71] rust: macros: add macro to easily run KUnit tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a new procedural macro (`#[kunit_tests(kunit_test_suit_name)]`) to run KUnit tests using a user-space like syntax. The macro, that should be used on modules, transforms every `#[test]` in a `kunit_case!` and adds a `kunit_unsafe_test_suite!` registering all of them. The only difference with user-space tests is that instead of using `#[cfg(test)]`, `#[kunit_tests(kunit_test_suit_name)]` is used. Note that `#[cfg(CONFIG_KUNIT)]` is added so the test module is not compiled when `CONFIG_KUNIT` is set to `n`. Reviewed-by: David Gow Signed-off-by: José Expósito Co-developed-by: Boqun Feng Signed-off-by: Boqun Feng Co-developed-by: Miguel Ojeda Signed-off-by: Miguel Ojeda Reviewed-by: Tamir Duberstein Signed-off-by: David Gow Link: https://lore.kernel.org/r/20250307090103.918788-3-davidgow@google.com [ Removed spurious (in rendered form) newline in docs. - Miguel ] Signed-off-by: Miguel Ojeda --- MAINTAINERS | 1 + rust/kernel/kunit.rs | 11 +++ rust/macros/kunit.rs | 161 +++++++++++++++++++++++++++++++++++++++++++ rust/macros/lib.rs | 28 ++++++++ 4 files changed, 201 insertions(+) create mode 100644 rust/macros/kunit.rs diff --git a/MAINTAINERS b/MAINTAINERS index 72b88f1638a2..af59c90e6bd6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12679,6 +12679,7 @@ F: Documentation/dev-tools/kunit/ F: include/kunit/ F: lib/kunit/ F: rust/kernel/kunit.rs +F: rust/macros/kunit.rs F: scripts/rustdoc_test_* F: tools/testing/kunit/ diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs index e777a4e03e4b..50cd45912d6e 100644 --- a/rust/kernel/kunit.rs +++ b/rust/kernel/kunit.rs @@ -40,6 +40,8 @@ pub fn info(args: fmt::Arguments<'_>) { } } +use macros::kunit_tests; + /// Asserts that a boolean expression is `true` at runtime. /// /// Public but hidden since it should only be used from generated tests. @@ -285,3 +287,12 @@ macro_rules! kunit_unsafe_test_suite { }; }; } + +#[kunit_tests(rust_kernel_kunit)] +mod tests { + #[test] + fn rust_test_kunit_example_test() { + #![expect(clippy::eq_op)] + assert_eq!(1 + 1, 2); + } +} diff --git a/rust/macros/kunit.rs b/rust/macros/kunit.rs new file mode 100644 index 000000000000..4f553ecf40c0 --- /dev/null +++ b/rust/macros/kunit.rs @@ -0,0 +1,161 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Procedural macro to run KUnit tests using a user-space like syntax. +//! +//! Copyright (c) 2023 José Expósito + +use proc_macro::{Delimiter, Group, TokenStream, TokenTree}; +use std::fmt::Write; + +pub(crate) fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream { + let attr = attr.to_string(); + + if attr.is_empty() { + panic!("Missing test name in `#[kunit_tests(test_name)]` macro") + } + + if attr.len() > 255 { + panic!( + "The test suite name `{}` exceeds the maximum length of 255 bytes", + attr + ) + } + + let mut tokens: Vec<_> = ts.into_iter().collect(); + + // Scan for the `mod` keyword. + tokens + .iter() + .find_map(|token| match token { + TokenTree::Ident(ident) => match ident.to_string().as_str() { + "mod" => Some(true), + _ => None, + }, + _ => None, + }) + .expect("`#[kunit_tests(test_name)]` attribute should only be applied to modules"); + + // Retrieve the main body. The main body should be the last token tree. + let body = match tokens.pop() { + Some(TokenTree::Group(group)) if group.delimiter() == Delimiter::Brace => group, + _ => panic!("Cannot locate main body of module"), + }; + + // Get the functions set as tests. Search for `[test]` -> `fn`. + let mut body_it = body.stream().into_iter(); + let mut tests = Vec::new(); + while let Some(token) = body_it.next() { + match token { + TokenTree::Group(ident) if ident.to_string() == "[test]" => match body_it.next() { + Some(TokenTree::Ident(ident)) if ident.to_string() == "fn" => { + let test_name = match body_it.next() { + Some(TokenTree::Ident(ident)) => ident.to_string(), + _ => continue, + }; + tests.push(test_name); + } + _ => continue, + }, + _ => (), + } + } + + // Add `#[cfg(CONFIG_KUNIT)]` before the module declaration. + let config_kunit = "#[cfg(CONFIG_KUNIT)]".to_owned().parse().unwrap(); + tokens.insert( + 0, + TokenTree::Group(Group::new(Delimiter::None, config_kunit)), + ); + + // Generate the test KUnit test suite and a test case for each `#[test]`. + // The code generated for the following test module: + // + // ``` + // #[kunit_tests(kunit_test_suit_name)] + // mod tests { + // #[test] + // fn foo() { + // assert_eq!(1, 1); + // } + // + // #[test] + // fn bar() { + // assert_eq!(2, 2); + // } + // } + // ``` + // + // Looks like: + // + // ``` + // unsafe extern "C" fn kunit_rust_wrapper_foo(_test: *mut kernel::bindings::kunit) { foo(); } + // unsafe extern "C" fn kunit_rust_wrapper_bar(_test: *mut kernel::bindings::kunit) { bar(); } + // + // static mut TEST_CASES: [kernel::bindings::kunit_case; 3] = [ + // kernel::kunit::kunit_case(kernel::c_str!("foo"), kunit_rust_wrapper_foo), + // kernel::kunit::kunit_case(kernel::c_str!("bar"), kunit_rust_wrapper_bar), + // kernel::kunit::kunit_case_null(), + // ]; + // + // kernel::kunit_unsafe_test_suite!(kunit_test_suit_name, TEST_CASES); + // ``` + let mut kunit_macros = "".to_owned(); + let mut test_cases = "".to_owned(); + for test in &tests { + let kunit_wrapper_fn_name = format!("kunit_rust_wrapper_{}", test); + let kunit_wrapper = format!( + "unsafe extern \"C\" fn {}(_test: *mut kernel::bindings::kunit) {{ {}(); }}", + kunit_wrapper_fn_name, test + ); + writeln!(kunit_macros, "{kunit_wrapper}").unwrap(); + writeln!( + test_cases, + " kernel::kunit::kunit_case(kernel::c_str!(\"{}\"), {}),", + test, kunit_wrapper_fn_name + ) + .unwrap(); + } + + writeln!(kunit_macros).unwrap(); + writeln!( + kunit_macros, + "static mut TEST_CASES: [kernel::bindings::kunit_case; {}] = [\n{test_cases} kernel::kunit::kunit_case_null(),\n];", + tests.len() + 1 + ) + .unwrap(); + + writeln!( + kunit_macros, + "kernel::kunit_unsafe_test_suite!({attr}, TEST_CASES);" + ) + .unwrap(); + + // Remove the `#[test]` macros. + // We do this at a token level, in order to preserve span information. + let mut new_body = vec![]; + let mut body_it = body.stream().into_iter(); + + while let Some(token) = body_it.next() { + match token { + TokenTree::Punct(ref c) if c.as_char() == '#' => match body_it.next() { + Some(TokenTree::Group(group)) if group.to_string() == "[test]" => (), + Some(next) => { + new_body.extend([token, next]); + } + _ => { + new_body.push(token); + } + }, + _ => { + new_body.push(token); + } + } + } + + let mut new_body = TokenStream::from_iter(new_body); + new_body.extend::(kunit_macros.parse().unwrap()); + + tokens.push(TokenTree::Group(Group::new(Delimiter::Brace, new_body))); + + tokens.into_iter().collect() +} diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index f0f8c9232748..9acaa68c974e 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -11,6 +11,7 @@ mod quote; mod concat_idents; mod export; mod helpers; +mod kunit; mod module; mod paste; mod vtable; @@ -392,3 +393,30 @@ pub fn paste(input: TokenStream) -> TokenStream { paste::expand(&mut tokens); tokens.into_iter().collect() } + +/// Registers a KUnit test suite and its test cases using a user-space like syntax. +/// +/// This macro should be used on modules. If `CONFIG_KUNIT` (in `.config`) is `n`, the target module +/// is ignored. +/// +/// # Examples +/// +/// ```ignore +/// # use macros::kunit_tests; +/// #[kunit_tests(kunit_test_suit_name)] +/// mod tests { +/// #[test] +/// fn foo() { +/// assert_eq!(1, 1); +/// } +/// +/// #[test] +/// fn bar() { +/// assert_eq!(2, 2); +/// } +/// } +/// ``` +#[proc_macro_attribute] +pub fn kunit_tests(attr: TokenStream, ts: TokenStream) -> TokenStream { + kunit::kunit_tests(attr, ts) +} From 100af58c8d5822750ef9ba65f5d5ea3367c669de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Exp=C3=B3sito?= Date: Fri, 7 Mar 2025 17:00:58 +0800 Subject: [PATCH 47/71] rust: kunit: allow to know if we are in a test MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In some cases, we need to call test-only code from outside the test case, for example, to mock a function or a module. In order to check whether we are in a test or not, we need to test if `CONFIG_KUNIT` is set. Unfortunately, we cannot rely only on this condition because: - a test could be running in another thread, - some distros compile KUnit in production kernels, so checking at runtime that `current->kunit_test != NULL` is required. Forturately, KUnit provides an optimised check in `kunit_get_current_test()`, which checks CONFIG_KUNIT, a global static key, and then the current thread's running KUnit test. Add a safe wrapper function around this to know whether or not we are in a KUnit test and examples showing how to mock a function and a module. Signed-off-by: José Expósito Co-developed-by: Miguel Ojeda Signed-off-by: Miguel Ojeda Co-developed-by: David Gow Signed-off-by: David Gow Link: https://lore.kernel.org/r/20250307090103.918788-4-davidgow@google.com Signed-off-by: Miguel Ojeda --- rust/kernel/kunit.rs | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs index 50cd45912d6e..1604fb6a5b1b 100644 --- a/rust/kernel/kunit.rs +++ b/rust/kernel/kunit.rs @@ -288,11 +288,47 @@ macro_rules! kunit_unsafe_test_suite { }; } +/// Returns whether we are currently running a KUnit test. +/// +/// In some cases, you need to call test-only code from outside the test case, for example, to +/// create a function mock. This function allows to change behavior depending on whether we are +/// currently running a KUnit test or not. +/// +/// # Examples +/// +/// This example shows how a function can be mocked to return a well-known value while testing: +/// +/// ``` +/// # use kernel::kunit::in_kunit_test; +/// fn fn_mock_example(n: i32) -> i32 { +/// if in_kunit_test() { +/// return 100; +/// } +/// +/// n + 1 +/// } +/// +/// let mock_res = fn_mock_example(5); +/// assert_eq!(mock_res, 100); +/// ``` +pub fn in_kunit_test() -> bool { + // SAFETY: `kunit_get_current_test()` is always safe to call (it has fallbacks for + // when KUnit is not enabled). + !unsafe { bindings::kunit_get_current_test() }.is_null() +} + #[kunit_tests(rust_kernel_kunit)] mod tests { + use super::*; + #[test] fn rust_test_kunit_example_test() { #![expect(clippy::eq_op)] assert_eq!(1 + 1, 2); } + + #[test] + fn rust_test_kunit_in_kunit_test() { + assert!(in_kunit_test()); + } } From e385e94a8bc38ffb1da1a735eb1d7f290c8852f0 Mon Sep 17 00:00:00 2001 From: Abdiel Janulgue Date: Mon, 17 Mar 2025 20:52:08 +0200 Subject: [PATCH 48/71] rust: error: Add EOVERFLOW Trivial addition for missing EOVERFLOW error. This is used by a subsequent patch that might require returning EOVERFLOW as a result of `checked_mul`. Reviewed-by: Alice Ryhl Reviewed-by: Andreas Hindborg Signed-off-by: Abdiel Janulgue Acked-by: Danilo Krummrich Link: https://lore.kernel.org/r/20250317185345.2608976-2-abdiel.janulgue@gmail.com Signed-off-by: Miguel Ojeda --- rust/kernel/error.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs index 376f6a6ae5e3..30014d507ed3 100644 --- a/rust/kernel/error.rs +++ b/rust/kernel/error.rs @@ -64,6 +64,7 @@ pub mod code { declare_err!(EPIPE, "Broken pipe."); declare_err!(EDOM, "Math argument out of domain of func."); declare_err!(ERANGE, "Math result not representable."); + declare_err!(EOVERFLOW, "Value too large for defined data type."); declare_err!(ERESTARTSYS, "Restart the system call."); declare_err!(ERESTARTNOINTR, "System call was interrupted by a signal and will be restarted."); declare_err!(ERESTARTNOHAND, "Restart if no handler."); From ad2907b4e308a93deac93ff408f8bbbcac333905 Mon Sep 17 00:00:00 2001 From: Abdiel Janulgue Date: Mon, 17 Mar 2025 20:52:09 +0200 Subject: [PATCH 49/71] rust: add dma coherent allocator abstraction Add a simple dma coherent allocator rust abstraction. Based on Andreas Hindborg's dma abstractions from the rnvme driver, which was also based on earlier work by Wedson Almeida Filho. Reviewed-by: Alice Ryhl Signed-off-by: Abdiel Janulgue Acked-by: Danilo Krummrich Link: https://lore.kernel.org/r/20250317185345.2608976-3-abdiel.janulgue@gmail.com Nacked-by: Christoph Hellwig [ Removed period. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/bindings/bindings_helper.h | 1 + rust/kernel/dma.rs | 387 ++++++++++++++++++++++++++++++++ rust/kernel/lib.rs | 1 + 3 files changed, 389 insertions(+) create mode 100644 rust/kernel/dma.rs diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h index ae39fc18a8bf..ccb988340df6 100644 --- a/rust/bindings/bindings_helper.h +++ b/rust/bindings/bindings_helper.h @@ -12,6 +12,7 @@ #include #include #include +#include #include #include #include diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs new file mode 100644 index 000000000000..9d00f9c49f47 --- /dev/null +++ b/rust/kernel/dma.rs @@ -0,0 +1,387 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Direct memory access (DMA). +//! +//! C header: [`include/linux/dma-mapping.h`](srctree/include/linux/dma-mapping.h) + +use crate::{ + bindings, build_assert, + device::Device, + error::code::*, + error::Result, + transmute::{AsBytes, FromBytes}, + types::ARef, +}; + +/// Possible attributes associated with a DMA mapping. +/// +/// They can be combined with the operators `|`, `&`, and `!`. +/// +/// Values can be used from the [`attrs`] module. +/// +/// # Examples +/// +/// ``` +/// use kernel::device::Device; +/// use kernel::dma::{attrs::*, CoherentAllocation}; +/// +/// # fn test(dev: &Device) -> Result { +/// let attribs = DMA_ATTR_FORCE_CONTIGUOUS | DMA_ATTR_NO_WARN; +/// let c: CoherentAllocation = +/// CoherentAllocation::alloc_attrs(dev, 4, GFP_KERNEL, attribs)?; +/// # Ok::<(), Error>(()) } +/// ``` +#[derive(Clone, Copy, PartialEq)] +#[repr(transparent)] +pub struct Attrs(u32); + +impl Attrs { + /// Get the raw representation of this attribute. + pub(crate) fn as_raw(self) -> crate::ffi::c_ulong { + self.0 as _ + } + + /// Check whether `flags` is contained in `self`. + pub fn contains(self, flags: Attrs) -> bool { + (self & flags) == flags + } +} + +impl core::ops::BitOr for Attrs { + type Output = Self; + fn bitor(self, rhs: Self) -> Self::Output { + Self(self.0 | rhs.0) + } +} + +impl core::ops::BitAnd for Attrs { + type Output = Self; + fn bitand(self, rhs: Self) -> Self::Output { + Self(self.0 & rhs.0) + } +} + +impl core::ops::Not for Attrs { + type Output = Self; + fn not(self) -> Self::Output { + Self(!self.0) + } +} + +/// DMA mapping attributes. +pub mod attrs { + use super::Attrs; + + /// Specifies that reads and writes to the mapping may be weakly ordered, that is that reads + /// and writes may pass each other. + pub const DMA_ATTR_WEAK_ORDERING: Attrs = Attrs(bindings::DMA_ATTR_WEAK_ORDERING); + + /// Specifies that writes to the mapping may be buffered to improve performance. + pub const DMA_ATTR_WRITE_COMBINE: Attrs = Attrs(bindings::DMA_ATTR_WRITE_COMBINE); + + /// Lets the platform to avoid creating a kernel virtual mapping for the allocated buffer. + pub const DMA_ATTR_NO_KERNEL_MAPPING: Attrs = Attrs(bindings::DMA_ATTR_NO_KERNEL_MAPPING); + + /// Allows platform code to skip synchronization of the CPU cache for the given buffer assuming + /// that it has been already transferred to 'device' domain. + pub const DMA_ATTR_SKIP_CPU_SYNC: Attrs = Attrs(bindings::DMA_ATTR_SKIP_CPU_SYNC); + + /// Forces contiguous allocation of the buffer in physical memory. + pub const DMA_ATTR_FORCE_CONTIGUOUS: Attrs = Attrs(bindings::DMA_ATTR_FORCE_CONTIGUOUS); + + /// This is a hint to the DMA-mapping subsystem that it's probably not worth the time to try + /// to allocate memory to in a way that gives better TLB efficiency. + pub const DMA_ATTR_ALLOC_SINGLE_PAGES: Attrs = Attrs(bindings::DMA_ATTR_ALLOC_SINGLE_PAGES); + + /// This tells the DMA-mapping subsystem to suppress allocation failure reports (similarly to + /// __GFP_NOWARN). + pub const DMA_ATTR_NO_WARN: Attrs = Attrs(bindings::DMA_ATTR_NO_WARN); + + /// Used to indicate that the buffer is fully accessible at an elevated privilege level (and + /// ideally inaccessible or at least read-only at lesser-privileged levels). + pub const DMA_ATTR_PRIVILEGED: Attrs = Attrs(bindings::DMA_ATTR_PRIVILEGED); +} + +/// An abstraction of the `dma_alloc_coherent` API. +/// +/// This is an abstraction around the `dma_alloc_coherent` API which is used to allocate and map +/// large consistent DMA regions. +/// +/// A [`CoherentAllocation`] instance contains a pointer to the allocated region (in the +/// processor's virtual address space) and the device address which can be given to the device +/// as the DMA address base of the region. The region is released once [`CoherentAllocation`] +/// is dropped. +/// +/// # Invariants +/// +/// For the lifetime of an instance of [`CoherentAllocation`], the `cpu_addr` is a valid pointer +/// to an allocated region of consistent memory and `dma_handle` is the DMA address base of +/// the region. +// TODO +// +// DMA allocations potentially carry device resources (e.g.IOMMU mappings), hence for soundness +// reasons DMA allocation would need to be embedded in a `Devres` container, in order to ensure +// that device resources can never survive device unbind. +// +// However, it is neither desirable nor necessary to protect the allocated memory of the DMA +// allocation from surviving device unbind; it would require RCU read side critical sections to +// access the memory, which may require subsequent unnecessary copies. +// +// Hence, find a way to revoke the device resources of a `CoherentAllocation`, but not the +// entire `CoherentAllocation` including the allocated memory itself. +pub struct CoherentAllocation { + dev: ARef, + dma_handle: bindings::dma_addr_t, + count: usize, + cpu_addr: *mut T, + dma_attrs: Attrs, +} + +impl CoherentAllocation { + /// Allocates a region of `size_of:: * count` of consistent memory. + /// + /// # Examples + /// + /// ``` + /// use kernel::device::Device; + /// use kernel::dma::{attrs::*, CoherentAllocation}; + /// + /// # fn test(dev: &Device) -> Result { + /// let c: CoherentAllocation = + /// CoherentAllocation::alloc_attrs(dev, 4, GFP_KERNEL, DMA_ATTR_NO_WARN)?; + /// # Ok::<(), Error>(()) } + /// ``` + pub fn alloc_attrs( + dev: &Device, + count: usize, + gfp_flags: kernel::alloc::Flags, + dma_attrs: Attrs, + ) -> Result> { + build_assert!( + core::mem::size_of::() > 0, + "It doesn't make sense for the allocated type to be a ZST" + ); + + let size = count + .checked_mul(core::mem::size_of::()) + .ok_or(EOVERFLOW)?; + let mut dma_handle = 0; + // SAFETY: Device pointer is guaranteed as valid by the type invariant on `Device`. + let ret = unsafe { + bindings::dma_alloc_attrs( + dev.as_raw(), + size, + &mut dma_handle, + gfp_flags.as_raw(), + dma_attrs.as_raw(), + ) + }; + if ret.is_null() { + return Err(ENOMEM); + } + // INVARIANT: We just successfully allocated a coherent region which is accessible for + // `count` elements, hence the cpu address is valid. We also hold a refcounted reference + // to the device. + Ok(Self { + dev: dev.into(), + dma_handle, + count, + cpu_addr: ret as *mut T, + dma_attrs, + }) + } + + /// Performs the same functionality as [`CoherentAllocation::alloc_attrs`], except the + /// `dma_attrs` is 0 by default. + pub fn alloc_coherent( + dev: &Device, + count: usize, + gfp_flags: kernel::alloc::Flags, + ) -> Result> { + CoherentAllocation::alloc_attrs(dev, count, gfp_flags, Attrs(0)) + } + + /// Returns the base address to the allocated region in the CPU's virtual address space. + pub fn start_ptr(&self) -> *const T { + self.cpu_addr + } + + /// Returns the base address to the allocated region in the CPU's virtual address space as + /// a mutable pointer. + pub fn start_ptr_mut(&mut self) -> *mut T { + self.cpu_addr + } + + /// Returns a DMA handle which may given to the device as the DMA address base of + /// the region. + pub fn dma_handle(&self) -> bindings::dma_addr_t { + self.dma_handle + } + + /// Returns a pointer to an element from the region with bounds checking. `offset` is in + /// units of `T`, not the number of bytes. + /// + /// Public but hidden since it should only be used from [`dma_read`] and [`dma_write`] macros. + #[doc(hidden)] + pub fn item_from_index(&self, offset: usize) -> Result<*mut T> { + if offset >= self.count { + return Err(EINVAL); + } + // SAFETY: + // - The pointer is valid due to type invariant on `CoherentAllocation` + // and we've just checked that the range and index is within bounds. + // - `offset` can't overflow since it is smaller than `self.count` and we've checked + // that `self.count` won't overflow early in the constructor. + Ok(unsafe { self.cpu_addr.add(offset) }) + } + + /// Reads the value of `field` and ensures that its type is [`FromBytes`]. + /// + /// # Safety + /// + /// This must be called from the [`dma_read`] macro which ensures that the `field` pointer is + /// validated beforehand. + /// + /// Public but hidden since it should only be used from [`dma_read`] macro. + #[doc(hidden)] + pub unsafe fn field_read(&self, field: *const F) -> F { + // SAFETY: + // - By the safety requirements field is valid. + // - Using read_volatile() here is not sound as per the usual rules, the usage here is + // a special exception with the following notes in place. When dealing with a potential + // race from a hardware or code outside kernel (e.g. user-space program), we need that + // read on a valid memory is not UB. Currently read_volatile() is used for this, and the + // rationale behind is that it should generate the same code as READ_ONCE() which the + // kernel already relies on to avoid UB on data races. Note that the usage of + // read_volatile() is limited to this particular case, it cannot be used to prevent + // the UB caused by racing between two kernel functions nor do they provide atomicity. + unsafe { field.read_volatile() } + } + + /// Writes a value to `field` and ensures that its type is [`AsBytes`]. + /// + /// # Safety + /// + /// This must be called from the [`dma_write`] macro which ensures that the `field` pointer is + /// validated beforehand. + /// + /// Public but hidden since it should only be used from [`dma_write`] macro. + #[doc(hidden)] + pub unsafe fn field_write(&self, field: *mut F, val: F) { + // SAFETY: + // - By the safety requirements field is valid. + // - Using write_volatile() here is not sound as per the usual rules, the usage here is + // a special exception with the following notes in place. When dealing with a potential + // race from a hardware or code outside kernel (e.g. user-space program), we need that + // write on a valid memory is not UB. Currently write_volatile() is used for this, and the + // rationale behind is that it should generate the same code as WRITE_ONCE() which the + // kernel already relies on to avoid UB on data races. Note that the usage of + // write_volatile() is limited to this particular case, it cannot be used to prevent + // the UB caused by racing between two kernel functions nor do they provide atomicity. + unsafe { field.write_volatile(val) } + } +} + +/// Note that the device configured to do DMA must be halted before this object is dropped. +impl Drop for CoherentAllocation { + fn drop(&mut self) { + let size = self.count * core::mem::size_of::(); + // SAFETY: Device pointer is guaranteed as valid by the type invariant on `Device`. + // The cpu address, and the dma handle are valid due to the type invariants on + // `CoherentAllocation`. + unsafe { + bindings::dma_free_attrs( + self.dev.as_raw(), + size, + self.cpu_addr as _, + self.dma_handle, + self.dma_attrs.as_raw(), + ) + } + } +} + +/// Reads a field of an item from an allocated region of structs. +/// +/// # Examples +/// +/// ``` +/// use kernel::device::Device; +/// use kernel::dma::{attrs::*, CoherentAllocation}; +/// +/// struct MyStruct { field: u32, } +/// +/// // SAFETY: All bit patterns are acceptable values for `MyStruct`. +/// unsafe impl kernel::transmute::FromBytes for MyStruct{}; +/// // SAFETY: Instances of `MyStruct` have no uninitialized portions. +/// unsafe impl kernel::transmute::AsBytes for MyStruct{}; +/// +/// # fn test(alloc: &kernel::dma::CoherentAllocation) -> Result { +/// let whole = kernel::dma_read!(alloc[2]); +/// let field = kernel::dma_read!(alloc[1].field); +/// # Ok::<(), Error>(()) } +/// ``` +#[macro_export] +macro_rules! dma_read { + ($dma:expr, $idx: expr, $($field:tt)*) => {{ + let item = $crate::dma::CoherentAllocation::item_from_index(&$dma, $idx)?; + // SAFETY: `item_from_index` ensures that `item` is always a valid pointer and can be + // dereferenced. The compiler also further validates the expression on whether `field` + // is a member of `item` when expanded by the macro. + unsafe { + let ptr_field = ::core::ptr::addr_of!((*item) $($field)*); + $crate::dma::CoherentAllocation::field_read(&$dma, ptr_field) + } + }}; + ($dma:ident [ $idx:expr ] $($field:tt)* ) => { + $crate::dma_read!($dma, $idx, $($field)*); + }; + ($($dma:ident).* [ $idx:expr ] $($field:tt)* ) => { + $crate::dma_read!($($dma).*, $idx, $($field)*); + }; +} + +/// Writes to a field of an item from an allocated region of structs. +/// +/// # Examples +/// +/// ``` +/// use kernel::device::Device; +/// use kernel::dma::{attrs::*, CoherentAllocation}; +/// +/// struct MyStruct { member: u32, } +/// +/// // SAFETY: All bit patterns are acceptable values for `MyStruct`. +/// unsafe impl kernel::transmute::FromBytes for MyStruct{}; +/// // SAFETY: Instances of `MyStruct` have no uninitialized portions. +/// unsafe impl kernel::transmute::AsBytes for MyStruct{}; +/// +/// # fn test(alloc: &kernel::dma::CoherentAllocation) -> Result { +/// kernel::dma_write!(alloc[2].member = 0xf); +/// kernel::dma_write!(alloc[1] = MyStruct { member: 0xf }); +/// # Ok::<(), Error>(()) } +/// ``` +#[macro_export] +macro_rules! dma_write { + ($dma:ident [ $idx:expr ] $($field:tt)*) => {{ + $crate::dma_write!($dma, $idx, $($field)*); + }}; + ($($dma:ident).* [ $idx:expr ] $($field:tt)* ) => {{ + $crate::dma_write!($($dma).*, $idx, $($field)*); + }}; + ($dma:expr, $idx: expr, = $val:expr) => { + let item = $crate::dma::CoherentAllocation::item_from_index(&$dma, $idx)?; + // SAFETY: `item_from_index` ensures that `item` is always a valid item. + unsafe { $crate::dma::CoherentAllocation::field_write(&$dma, item, $val) } + }; + ($dma:expr, $idx: expr, $(.$field:ident)* = $val:expr) => { + let item = $crate::dma::CoherentAllocation::item_from_index(&$dma, $idx)?; + // SAFETY: `item_from_index` ensures that `item` is always a valid pointer and can be + // dereferenced. The compiler also further validates the expression on whether `field` + // is a member of `item` when expanded by the macro. + unsafe { + let ptr_field = ::core::ptr::addr_of_mut!((*item) $(.$field)*); + $crate::dma::CoherentAllocation::field_write(&$dma, ptr_field, $val) + } + }; +} diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index c92497c7c655..001374a96d66 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -44,6 +44,7 @@ pub mod cred; pub mod device; pub mod device_id; pub mod devres; +pub mod dma; pub mod driver; pub mod error; pub mod faux; From 9901addae63b9033335fb484a5f0c4367322df8b Mon Sep 17 00:00:00 2001 From: Abdiel Janulgue Date: Mon, 17 Mar 2025 20:52:10 +0200 Subject: [PATCH 50/71] samples: rust: add Rust dma test sample driver Add a simple driver to exercise the basics of the Rust DMA coherent allocator bindings. Suggested-by: Danilo Krummrich Signed-off-by: Abdiel Janulgue Acked-by: Danilo Krummrich Link: https://lore.kernel.org/r/20250317185345.2608976-4-abdiel.janulgue@gmail.com [ Renamed Kconfig symbol and moved it up. Migrated to the new `authors` key in `module!`. Fixed module name in description and typo in commit message. - Miguel ] Signed-off-by: Miguel Ojeda --- samples/rust/Kconfig | 11 +++++ samples/rust/Makefile | 1 + samples/rust/rust_dma.rs | 97 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+) create mode 100644 samples/rust/rust_dma.rs diff --git a/samples/rust/Kconfig b/samples/rust/Kconfig index 3b6eae84b297..cad52b7120b5 100644 --- a/samples/rust/Kconfig +++ b/samples/rust/Kconfig @@ -40,6 +40,17 @@ config SAMPLE_RUST_PRINT If unsure, say N. +config SAMPLE_RUST_DMA + tristate "DMA Test Driver" + depends on PCI + help + This option builds the Rust DMA Test driver sample. + + To compile this as a module, choose M here: + the module will be called rust_dma. + + If unsure, say N. + config SAMPLE_RUST_DRIVER_PCI tristate "PCI Driver" depends on PCI diff --git a/samples/rust/Makefile b/samples/rust/Makefile index 0dbc6d90f1ef..c6a2479f7d9c 100644 --- a/samples/rust/Makefile +++ b/samples/rust/Makefile @@ -4,6 +4,7 @@ ccflags-y += -I$(src) # needed for trace events obj-$(CONFIG_SAMPLE_RUST_MINIMAL) += rust_minimal.o obj-$(CONFIG_SAMPLE_RUST_MISC_DEVICE) += rust_misc_device.o obj-$(CONFIG_SAMPLE_RUST_PRINT) += rust_print.o +obj-$(CONFIG_SAMPLE_RUST_DMA) += rust_dma.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_PCI) += rust_driver_pci.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_PLATFORM) += rust_driver_platform.o obj-$(CONFIG_SAMPLE_RUST_DRIVER_FAUX) += rust_driver_faux.o diff --git a/samples/rust/rust_dma.rs b/samples/rust/rust_dma.rs new file mode 100644 index 000000000000..908acd34b8db --- /dev/null +++ b/samples/rust/rust_dma.rs @@ -0,0 +1,97 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Rust DMA api test (based on QEMU's `pci-testdev`). +//! +//! To make this driver probe, QEMU must be run with `-device pci-testdev`. + +use kernel::{bindings, dma::CoherentAllocation, pci, prelude::*}; + +struct DmaSampleDriver { + pdev: pci::Device, + ca: CoherentAllocation, +} + +const TEST_VALUES: [(u32, u32); 5] = [ + (0xa, 0xb), + (0xc, 0xd), + (0xe, 0xf), + (0xab, 0xba), + (0xcd, 0xef), +]; + +struct MyStruct { + h: u32, + b: u32, +} + +impl MyStruct { + fn new(h: u32, b: u32) -> Self { + Self { h, b } + } +} +// SAFETY: All bit patterns are acceptable values for `MyStruct`. +unsafe impl kernel::transmute::AsBytes for MyStruct {} +// SAFETY: Instances of `MyStruct` have no uninitialized portions. +unsafe impl kernel::transmute::FromBytes for MyStruct {} + +kernel::pci_device_table!( + PCI_TABLE, + MODULE_PCI_TABLE, + ::IdInfo, + [( + pci::DeviceId::from_id(bindings::PCI_VENDOR_ID_REDHAT, 0x5), + () + )] +); + +impl pci::Driver for DmaSampleDriver { + type IdInfo = (); + const ID_TABLE: pci::IdTable = &PCI_TABLE; + + fn probe(pdev: &mut pci::Device, _info: &Self::IdInfo) -> Result>> { + dev_info!(pdev.as_ref(), "Probe DMA test driver.\n"); + + let ca: CoherentAllocation = + CoherentAllocation::alloc_coherent(pdev.as_ref(), TEST_VALUES.len(), GFP_KERNEL)?; + + || -> Result { + for (i, value) in TEST_VALUES.into_iter().enumerate() { + kernel::dma_write!(ca[i] = MyStruct::new(value.0, value.1)); + } + + Ok(()) + }()?; + + let drvdata = KBox::new( + Self { + pdev: pdev.clone(), + ca, + }, + GFP_KERNEL, + )?; + + Ok(drvdata.into()) + } +} + +impl Drop for DmaSampleDriver { + fn drop(&mut self) { + dev_info!(self.pdev.as_ref(), "Unload DMA test driver.\n"); + + let _ = || -> Result { + for (i, value) in TEST_VALUES.into_iter().enumerate() { + assert_eq!(kernel::dma_read!(self.ca[i].h), value.0); + assert_eq!(kernel::dma_read!(self.ca[i].b), value.1); + } + Ok(()) + }(); + } +} + +kernel::module_pci_driver! { + type: DmaSampleDriver, + name: "rust_dma", + authors: ["Abdiel Janulgue"], + description: "Rust DMA test", + license: "GPL v2", +} From 3ba83d37615ac66d8f52e745dedf9510e493fe97 Mon Sep 17 00:00:00 2001 From: Abdiel Janulgue Date: Mon, 17 Mar 2025 20:52:11 +0200 Subject: [PATCH 51/71] MAINTAINERS: add entry for Rust dma mapping helpers device driver API Add an entry for the Rust dma mapping helpers abstractions. Nacked-by: Christoph Hellwig Acked-by: Danilo Krummrich Acked-by: Andreas Hindborg Acked-by: Marek Szyprowski Signed-off-by: Abdiel Janulgue Link: https://lore.kernel.org/r/20250317185345.2608976-5-abdiel.janulgue@gmail.com Signed-off-by: Miguel Ojeda --- MAINTAINERS | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/MAINTAINERS b/MAINTAINERS index af59c90e6bd6..cbf84690c495 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6902,6 +6902,19 @@ F: include/linux/dma-mapping.h F: include/linux/swiotlb.h F: kernel/dma/ +DMA MAPPING HELPERS DEVICE DRIVER API [RUST] +M: Abdiel Janulgue +M: Danilo Krummrich +R: Daniel Almeida +R: Robin Murphy +R: Andreas Hindborg +L: rust-for-linux@vger.kernel.org +S: Supported +W: https://rust-for-linux.com +T: git https://github.com/Rust-for-Linux/linux.git alloc-next +F: rust/kernel/dma.rs +F: samples/rust/rust_dma.rs + DMA-BUF HEAPS FRAMEWORK M: Sumit Semwal R: Benjamin Gaignard From 3eff946dfec732ca9e8585bd44f93acc12646d21 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Thu, 27 Feb 2025 15:38:07 +0100 Subject: [PATCH 52/71] rust: str: implement `PartialEq` for `BStr` Implement `PartialEq` for `BStr` by comparing underlying byte slices. Reviewed-by: Alice Ryhl Reviewed-by: Gary Guo Reviewed-by: Daniel Almeida Tested-by: Daniel Almeida Signed-off-by: Andreas Hindborg Reviewed-by: Fiona Behrens Tested-by: Daniel Gomez Link: https://lore.kernel.org/r/20250227-module-params-v3-v8-1-ceeee85d9347@kernel.org Signed-off-by: Miguel Ojeda --- rust/kernel/str.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index 28e2201604d6..002dcddf7c76 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -108,6 +108,12 @@ impl Deref for BStr { } } +impl PartialEq for BStr { + fn eq(&self, other: &Self) -> bool { + self.deref().eq(other.deref()) + } +} + /// Creates a new [`BStr`] from a string literal. /// /// `b_str!` converts the supplied string literal to byte string, so non-ASCII From 50a5ff0a95a54d5a710f1f2547ecf8af12b6b83a Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Thu, 27 Feb 2025 15:38:08 +0100 Subject: [PATCH 53/71] rust: str: implement `Index` for `BStr` The `Index` implementation on `BStr` was lost when we switched `BStr` from a type alias of `[u8]` to a newtype. Add back `Index` by implementing `Index` for `BStr` when `Index` would be implemented for `[u8]`. Reviewed-by: Daniel Almeida Tested-by: Daniel Almeida Reviewed-by: Fiona Behrens Signed-off-by: Andreas Hindborg Reviewed-by: Alice Ryhl Tested-by: Daniel Gomez Link: https://lore.kernel.org/r/20250227-module-params-v3-v8-2-ceeee85d9347@kernel.org Signed-off-by: Miguel Ojeda --- rust/kernel/str.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index 002dcddf7c76..ba6b1a5c4f99 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -114,6 +114,17 @@ impl PartialEq for BStr { } } +impl Index for BStr +where + [u8]: Index, +{ + type Output = Self; + + fn index(&self, index: Idx) -> &Self::Output { + BStr::from_bytes(&self.0[index]) + } +} + /// Creates a new [`BStr`] from a string literal. /// /// `b_str!` converts the supplied string literal to byte string, so non-ASCII From d2e3f7987d03c6abeeb8890540569c87999bdcc1 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Thu, 27 Feb 2025 15:38:09 +0100 Subject: [PATCH 54/71] rust: str: implement `AsRef` for `[u8]` and `BStr` Implement `AsRef` for `[u8]` and `BStr` so these can be used interchangeably for operations on `BStr`. Reviewed-by: Gary Guo Tested-by: Daniel Almeida Reviewed-by: Daniel Almeida Signed-off-by: Andreas Hindborg Reviewed-by: Fiona Behrens Tested-by: Daniel Gomez Link: https://lore.kernel.org/r/20250227-module-params-v3-v8-3-ceeee85d9347@kernel.org Signed-off-by: Miguel Ojeda --- rust/kernel/str.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index ba6b1a5c4f99..c6bd2c69543d 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -125,6 +125,18 @@ where } } +impl AsRef for [u8] { + fn as_ref(&self) -> &BStr { + BStr::from_bytes(self) + } +} + +impl AsRef for BStr { + fn as_ref(&self) -> &BStr { + self + } +} + /// Creates a new [`BStr`] from a string literal. /// /// `b_str!` converts the supplied string literal to byte string, so non-ASCII From 5928642b11cb6aee8f6250c762857e713e7112da Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Thu, 27 Feb 2025 15:38:10 +0100 Subject: [PATCH 55/71] rust: str: implement `strip_prefix` for `BStr` Implement `strip_prefix` for `BStr` by deferring to `slice::strip_prefix` on the underlying `&[u8]`. Reviewed-by: Gary Guo Reviewed-by: Alice Ryhl Reviewed-by: Daniel Almeida Tested-by: Daniel Almeida Signed-off-by: Andreas Hindborg Tested-by: Daniel Gomez Link: https://lore.kernel.org/r/20250227-module-params-v3-v8-4-ceeee85d9347@kernel.org [ Pluralized section name. Hid `use`. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/str.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index c6bd2c69543d..878111cb77bc 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -31,6 +31,23 @@ impl BStr { // SAFETY: `BStr` is transparent to `[u8]`. unsafe { &*(bytes as *const [u8] as *const BStr) } } + + /// Strip a prefix from `self`. Delegates to [`slice::strip_prefix`]. + /// + /// # Examples + /// + /// ``` + /// # use kernel::b_str; + /// assert_eq!(Some(b_str!("bar")), b_str!("foobar").strip_prefix(b_str!("foo"))); + /// assert_eq!(None, b_str!("foobar").strip_prefix(b_str!("bar"))); + /// assert_eq!(Some(b_str!("foobar")), b_str!("foobar").strip_prefix(b_str!(""))); + /// assert_eq!(Some(b_str!("")), b_str!("foobar").strip_prefix(b_str!("foobar"))); + /// ``` + pub fn strip_prefix(&self, pattern: impl AsRef) -> Option<&BStr> { + self.deref() + .strip_prefix(pattern.as_ref().deref()) + .map(Self::from_bytes) + } } impl fmt::Display for BStr { From 94e05a66ea3ebed48e7e1a0dee68d40184386d25 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:55 +0100 Subject: [PATCH 56/71] rust: hrtimer: allow timer restart from timer handler Allow timer handlers to report that they want a timer to be restarted after the timer handler has finished executing. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Benno Lossin Reviewed-by: Tamir Duberstein Reviewed-by: Lyude Paul Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-4-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 20 +++++++++++++++++++- rust/kernel/time/hrtimer/arc.rs | 4 +--- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index bfb536f2a490..bc8f85cededb 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -212,7 +212,7 @@ pub trait HrTimerCallback { type Pointer<'a>: RawHrTimerCallback; /// Called by the timer logic when the timer fires. - fn run(this: as RawHrTimerCallback>::CallbackTarget<'_>) + fn run(this: as RawHrTimerCallback>::CallbackTarget<'_>) -> HrTimerRestart where Self: Sized; } @@ -311,6 +311,24 @@ pub unsafe trait HasHrTimer { } } +/// Restart policy for timers. +#[derive(Copy, Clone, PartialEq, Eq, Debug)] +#[repr(u32)] +pub enum HrTimerRestart { + /// Timer should not be restarted. + #[allow(clippy::unnecessary_cast)] + NoRestart = bindings::hrtimer_restart_HRTIMER_NORESTART as u32, + /// Timer should be restarted. + #[allow(clippy::unnecessary_cast)] + Restart = bindings::hrtimer_restart_HRTIMER_RESTART as u32, +} + +impl HrTimerRestart { + fn into_c(self) -> bindings::hrtimer_restart { + self as bindings::hrtimer_restart + } +} + /// Use to implement the [`HasHrTimer`] trait. /// /// See [`module`] documentation for an example. diff --git a/rust/kernel/time/hrtimer/arc.rs b/rust/kernel/time/hrtimer/arc.rs index df97fade0aa1..4a984d85b4a1 100644 --- a/rust/kernel/time/hrtimer/arc.rs +++ b/rust/kernel/time/hrtimer/arc.rs @@ -95,8 +95,6 @@ where // allocation from other `Arc` clones. let receiver = unsafe { ArcBorrow::from_raw(data_ptr) }; - T::run(receiver); - - bindings::hrtimer_restart_HRTIMER_NORESTART + T::run(receiver).into_c() } } From a6968ce3769660658e5c956987dc9e75b369d4b6 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:56 +0100 Subject: [PATCH 57/71] rust: hrtimer: add `UnsafeHrTimerPointer` Add a trait to allow unsafely queuing stack allocated timers. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Benno Lossin Reviewed-by: Lyude Paul Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-5-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index bc8f85cededb..e1b29cd40397 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -188,6 +188,37 @@ pub trait HrTimerPointer: Sync + Sized { fn start(self, expires: Ktime) -> Self::TimerHandle; } +/// Unsafe version of [`HrTimerPointer`] for situations where leaking the +/// [`HrTimerHandle`] returned by `start` would be unsound. This is the case for +/// stack allocated timers. +/// +/// Typical implementers are pinned references such as [`Pin<&T>`]. +/// +/// # Safety +/// +/// Implementers of this trait must ensure that instances of types implementing +/// [`UnsafeHrTimerPointer`] outlives any associated [`HrTimerPointer::TimerHandle`] +/// instances. +pub unsafe trait UnsafeHrTimerPointer: Sync + Sized { + /// A handle representing a running timer. + /// + /// # Safety + /// + /// If the timer is running, or if the timer callback is executing when the + /// handle is dropped, the drop method of [`Self::TimerHandle`] must not return + /// until the timer is stopped and the callback has completed. + type TimerHandle: HrTimerHandle; + + /// Start the timer after `expires` time units. If the timer was already + /// running, it is restarted at the new expiry time. + /// + /// # Safety + /// + /// Caller promises keep the timer structure alive until the timer is dead. + /// Caller can ensure this by not leaking the returned [`Self::TimerHandle`]. + unsafe fn start(self, expires: Ktime) -> Self::TimerHandle; +} + /// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a /// function to call. // This is split from `HrTimerPointer` to make it easier to specify trait bounds. From f93b0d8360e5e690ca82c3236ba7f7f9d6a6b5e7 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:57 +0100 Subject: [PATCH 58/71] rust: hrtimer: add `hrtimer::ScopedHrTimerPointer` Add the trait `ScopedHrTimerPointer` to allow safe use of stack allocated timers. Safety is achieved by pinning the stack in place while timers are running. Implement the trait for all types that implement `UnsafeHrTimerPointer`. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Benno Lossin Reviewed-by: Lyude Paul Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-6-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index e1b29cd40397..5c35982f9dcb 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -219,6 +219,39 @@ pub unsafe trait UnsafeHrTimerPointer: Sync + Sized { unsafe fn start(self, expires: Ktime) -> Self::TimerHandle; } +/// A trait for stack allocated timers. +/// +/// # Safety +/// +/// Implementers must ensure that `start_scoped` does not return until the +/// timer is dead and the timer handler is not running. +pub unsafe trait ScopedHrTimerPointer { + /// Start the timer to run after `expires` time units and immediately + /// after call `f`. When `f` returns, the timer is cancelled. + fn start_scoped(self, expires: Ktime, f: F) -> T + where + F: FnOnce() -> T; +} + +// SAFETY: By the safety requirement of [`UnsafeHrTimerPointer`], dropping the +// handle returned by [`UnsafeHrTimerPointer::start`] ensures that the timer is +// killed. +unsafe impl ScopedHrTimerPointer for T +where + T: UnsafeHrTimerPointer, +{ + fn start_scoped(self, expires: Ktime, f: F) -> U + where + F: FnOnce() -> U, + { + // SAFETY: We drop the timer handle below before returning. + let handle = unsafe { UnsafeHrTimerPointer::start(self, expires) }; + let t = f(); + drop(handle); + t + } +} + /// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a /// function to call. // This is split from `HrTimerPointer` to make it easier to specify trait bounds. From 582523d9de9a8875df62a08af7443884ff5d9969 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:58 +0100 Subject: [PATCH 59/71] rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&T>` Allow pinned references to structs that contain a `HrTimer` node to be scheduled with the `hrtimer` subsystem. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Lyude Paul Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-7-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 2 + rust/kernel/time/hrtimer/pin.rs | 104 ++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 rust/kernel/time/hrtimer/pin.rs diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index 5c35982f9dcb..16b3c0f09579 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -433,3 +433,5 @@ macro_rules! impl_has_hr_timer { mod arc; pub use arc::ArcHrTimerHandle; +mod pin; +pub use pin::PinHrTimerHandle; diff --git a/rust/kernel/time/hrtimer/pin.rs b/rust/kernel/time/hrtimer/pin.rs new file mode 100644 index 000000000000..f760db265c7b --- /dev/null +++ b/rust/kernel/time/hrtimer/pin.rs @@ -0,0 +1,104 @@ +// SPDX-License-Identifier: GPL-2.0 + +use super::HasHrTimer; +use super::HrTimer; +use super::HrTimerCallback; +use super::HrTimerHandle; +use super::RawHrTimerCallback; +use super::UnsafeHrTimerPointer; +use crate::time::Ktime; +use core::pin::Pin; + +/// A handle for a `Pin<&HasHrTimer>`. When the handle exists, the timer might be +/// running. +pub struct PinHrTimerHandle<'a, T> +where + T: HasHrTimer, +{ + pub(crate) inner: Pin<&'a T>, +} + +// SAFETY: We cancel the timer when the handle is dropped. The implementation of +// the `cancel` method will block if the timer handler is running. +unsafe impl<'a, T> HrTimerHandle for PinHrTimerHandle<'a, T> +where + T: HasHrTimer, +{ + fn cancel(&mut self) -> bool { + let self_ptr: *const T = self.inner.get_ref(); + + // SAFETY: As we got `self_ptr` from a reference above, it must point to + // a valid `T`. + let timer_ptr = unsafe { >::raw_get_timer(self_ptr) }; + + // SAFETY: As `timer_ptr` is derived from a reference, it must point to + // a valid and initialized `HrTimer`. + unsafe { HrTimer::::raw_cancel(timer_ptr) } + } +} + +impl<'a, T> Drop for PinHrTimerHandle<'a, T> +where + T: HasHrTimer, +{ + fn drop(&mut self) { + self.cancel(); + } +} + +// SAFETY: We capture the lifetime of `Self` when we create a `PinHrTimerHandle`, +// so `Self` will outlive the handle. +unsafe impl<'a, T> UnsafeHrTimerPointer for Pin<&'a T> +where + T: Send + Sync, + T: HasHrTimer, + T: HrTimerCallback = Self>, +{ + type TimerHandle = PinHrTimerHandle<'a, T>; + + unsafe fn start(self, expires: Ktime) -> Self::TimerHandle { + // Cast to pointer + let self_ptr: *const T = self.get_ref(); + + // SAFETY: + // - As we derive `self_ptr` from a reference above, it must point to a + // valid `T`. + // - We keep `self` alive by wrapping it in a handle below. + unsafe { T::start(self_ptr, expires) }; + + PinHrTimerHandle { inner: self } + } +} + +impl<'a, T> RawHrTimerCallback for Pin<&'a T> +where + T: HasHrTimer, + T: HrTimerCallback = Self>, +{ + type CallbackTarget<'b> = Self; + + unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart { + // `HrTimer` is `repr(C)` + let timer_ptr = ptr as *mut HrTimer; + + // SAFETY: By the safety requirement of this function, `timer_ptr` + // points to a `HrTimer` contained in an `T`. + let receiver_ptr = unsafe { T::timer_container_of(timer_ptr) }; + + // SAFETY: + // - By the safety requirement of this function, `timer_ptr` + // points to a `HrTimer` contained in an `T`. + // - As per the safety requirements of the trait `HrTimerHandle`, the + // `PinHrTimerHandle` associated with this timer is guaranteed to + // be alive until this method returns. That handle borrows the `T` + // behind `receiver_ptr`, thus guaranteeing the validity of + // the reference created below. + let receiver_ref = unsafe { &*receiver_ptr }; + + // SAFETY: `receiver_ref` only exists as pinned, so it is safe to pin it + // here. + let receiver_pin = unsafe { Pin::new_unchecked(receiver_ref) }; + + T::run(receiver_pin).into_c() + } +} From 042b0c7947d39aeac34b35fb89034ca1345f1fc3 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:18:59 +0100 Subject: [PATCH 60/71] rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&mut T>` Allow pinned mutable references to structs that contain a `HrTimer` node to be scheduled with the `hrtimer` subsystem. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Lyude Paul Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-8-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 2 + rust/kernel/time/hrtimer/pin_mut.rs | 108 ++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 rust/kernel/time/hrtimer/pin_mut.rs diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index 16b3c0f09579..2089170972ef 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -435,3 +435,5 @@ mod arc; pub use arc::ArcHrTimerHandle; mod pin; pub use pin::PinHrTimerHandle; +mod pin_mut; +pub use pin_mut::PinMutHrTimerHandle; diff --git a/rust/kernel/time/hrtimer/pin_mut.rs b/rust/kernel/time/hrtimer/pin_mut.rs new file mode 100644 index 000000000000..90c0351d62e4 --- /dev/null +++ b/rust/kernel/time/hrtimer/pin_mut.rs @@ -0,0 +1,108 @@ +// SPDX-License-Identifier: GPL-2.0 + +use super::{ + HasHrTimer, HrTimer, HrTimerCallback, HrTimerHandle, RawHrTimerCallback, UnsafeHrTimerPointer, +}; +use crate::time::Ktime; +use core::{marker::PhantomData, pin::Pin, ptr::NonNull}; + +/// A handle for a `Pin<&mut HasHrTimer>`. When the handle exists, the timer might +/// be running. +pub struct PinMutHrTimerHandle<'a, T> +where + T: HasHrTimer, +{ + pub(crate) inner: NonNull, + _p: PhantomData<&'a mut T>, +} + +// SAFETY: We cancel the timer when the handle is dropped. The implementation of +// the `cancel` method will block if the timer handler is running. +unsafe impl<'a, T> HrTimerHandle for PinMutHrTimerHandle<'a, T> +where + T: HasHrTimer, +{ + fn cancel(&mut self) -> bool { + let self_ptr = self.inner.as_ptr(); + + // SAFETY: As we got `self_ptr` from a reference above, it must point to + // a valid `T`. + let timer_ptr = unsafe { >::raw_get_timer(self_ptr) }; + + // SAFETY: As `timer_ptr` is derived from a reference, it must point to + // a valid and initialized `HrTimer`. + unsafe { HrTimer::::raw_cancel(timer_ptr) } + } +} + +impl<'a, T> Drop for PinMutHrTimerHandle<'a, T> +where + T: HasHrTimer, +{ + fn drop(&mut self) { + self.cancel(); + } +} + +// SAFETY: We capture the lifetime of `Self` when we create a +// `PinMutHrTimerHandle`, so `Self` will outlive the handle. +unsafe impl<'a, T> UnsafeHrTimerPointer for Pin<&'a mut T> +where + T: Send + Sync, + T: HasHrTimer, + T: HrTimerCallback = Self>, +{ + type TimerHandle = PinMutHrTimerHandle<'a, T>; + + unsafe fn start(mut self, expires: Ktime) -> Self::TimerHandle { + // SAFETY: + // - We promise not to move out of `self`. We only pass `self` + // back to the caller as a `Pin<&mut self>`. + // - The return value of `get_unchecked_mut` is guaranteed not to be null. + let self_ptr = unsafe { NonNull::new_unchecked(self.as_mut().get_unchecked_mut()) }; + + // SAFETY: + // - As we derive `self_ptr` from a reference above, it must point to a + // valid `T`. + // - We keep `self` alive by wrapping it in a handle below. + unsafe { T::start(self_ptr.as_ptr(), expires) }; + + PinMutHrTimerHandle { + inner: self_ptr, + _p: PhantomData, + } + } +} + +impl<'a, T> RawHrTimerCallback for Pin<&'a mut T> +where + T: HasHrTimer, + T: HrTimerCallback = Self>, +{ + type CallbackTarget<'b> = Self; + + unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart { + // `HrTimer` is `repr(C)` + let timer_ptr = ptr as *mut HrTimer; + + // SAFETY: By the safety requirement of this function, `timer_ptr` + // points to a `HrTimer` contained in an `T`. + let receiver_ptr = unsafe { T::timer_container_of(timer_ptr) }; + + // SAFETY: + // - By the safety requirement of this function, `timer_ptr` + // points to a `HrTimer` contained in an `T`. + // - As per the safety requirements of the trait `HrTimerHandle`, the + // `PinMutHrTimerHandle` associated with this timer is guaranteed to + // be alive until this method returns. That handle borrows the `T` + // behind `receiver_ptr` mutably thus guaranteeing the validity of + // the reference created below. + let receiver_ref = unsafe { &mut *receiver_ptr }; + + // SAFETY: `receiver_ref` only exists as pinned, so it is safe to pin it + // here. + let receiver_pin = unsafe { Pin::new_unchecked(receiver_ref) }; + + T::run(receiver_pin).into_c() + } +} From b4fecceee29e2a6453ac746e70c16fe7f70babf9 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:19:00 +0100 Subject: [PATCH 61/71] rust: alloc: add `Box::into_pin` Add an associated function to convert a `Box` into a `Pin>`. Acked-by: Danilo Krummrich Reviewed-by: Benno Lossin Reviewed-by: Lyude Paul Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-9-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/alloc/kbox.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/rust/kernel/alloc/kbox.rs b/rust/kernel/alloc/kbox.rs index cb4ebea3b074..9da4a32e60bc 100644 --- a/rust/kernel/alloc/kbox.rs +++ b/rust/kernel/alloc/kbox.rs @@ -245,6 +245,12 @@ where Ok(Self::new(x, flags)?.into()) } + /// Convert a [`Box`] to a [`Pin>`]. If `T` does not implement + /// [`Unpin`], then `x` will be pinned in memory and can't be moved. + pub fn into_pin(this: Self) -> Pin { + this.into() + } + /// Forgets the contents (does not run the destructor), but keeps the allocation. fn forget_contents(this: Self) -> Box, A> { let ptr = Self::into_raw(this); From 374b60a0134e4b136f6c3d8b3c9eb99b3b104249 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:19:01 +0100 Subject: [PATCH 62/71] rust: hrtimer: implement `HrTimerPointer` for `Pin>` Allow `Pin>` to be the target of a timer callback. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Lyude Paul Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-10-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 3 + rust/kernel/time/hrtimer/tbox.rs | 120 +++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+) create mode 100644 rust/kernel/time/hrtimer/tbox.rs diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index 2089170972ef..cab230fb3e6e 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -437,3 +437,6 @@ mod pin; pub use pin::PinHrTimerHandle; mod pin_mut; pub use pin_mut::PinMutHrTimerHandle; +// `box` is a reserved keyword, so prefix with `t` for timer +mod tbox; +pub use tbox::BoxHrTimerHandle; diff --git a/rust/kernel/time/hrtimer/tbox.rs b/rust/kernel/time/hrtimer/tbox.rs new file mode 100644 index 000000000000..2071cae07234 --- /dev/null +++ b/rust/kernel/time/hrtimer/tbox.rs @@ -0,0 +1,120 @@ +// SPDX-License-Identifier: GPL-2.0 + +use super::HasHrTimer; +use super::HrTimer; +use super::HrTimerCallback; +use super::HrTimerHandle; +use super::HrTimerPointer; +use super::RawHrTimerCallback; +use crate::prelude::*; +use crate::time::Ktime; +use core::ptr::NonNull; + +/// A handle for a [`Box>`] returned by a call to +/// [`HrTimerPointer::start`]. +/// +/// # Invariants +/// +/// - `self.inner` comes from a `Box::into_raw` call. +pub struct BoxHrTimerHandle +where + T: HasHrTimer, + A: crate::alloc::Allocator, +{ + pub(crate) inner: NonNull, + _p: core::marker::PhantomData, +} + +// SAFETY: We implement drop below, and we cancel the timer in the drop +// implementation. +unsafe impl HrTimerHandle for BoxHrTimerHandle +where + T: HasHrTimer, + A: crate::alloc::Allocator, +{ + fn cancel(&mut self) -> bool { + // SAFETY: As we obtained `self.inner` from a valid reference when we + // created `self`, it must point to a valid `T`. + let timer_ptr = unsafe { >::raw_get_timer(self.inner.as_ptr()) }; + + // SAFETY: As `timer_ptr` points into `T` and `T` is valid, `timer_ptr` + // must point to a valid `HrTimer` instance. + unsafe { HrTimer::::raw_cancel(timer_ptr) } + } +} + +impl Drop for BoxHrTimerHandle +where + T: HasHrTimer, + A: crate::alloc::Allocator, +{ + fn drop(&mut self) { + self.cancel(); + // SAFETY: By type invariant, `self.inner` came from a `Box::into_raw` + // call. + drop(unsafe { Box::::from_raw(self.inner.as_ptr()) }) + } +} + +impl HrTimerPointer for Pin> +where + T: 'static, + T: Send + Sync, + T: HasHrTimer, + T: for<'a> HrTimerCallback = Pin>>, + A: crate::alloc::Allocator, +{ + type TimerHandle = BoxHrTimerHandle; + + fn start(self, expires: Ktime) -> Self::TimerHandle { + // SAFETY: + // - We will not move out of this box during timer callback (we pass an + // immutable reference to the callback). + // - `Box::into_raw` is guaranteed to return a valid pointer. + let inner = + unsafe { NonNull::new_unchecked(Box::into_raw(Pin::into_inner_unchecked(self))) }; + + // SAFETY: + // - We keep `self` alive by wrapping it in a handle below. + // - Since we generate the pointer passed to `start` from a valid + // reference, it is a valid pointer. + unsafe { T::start(inner.as_ptr(), expires) }; + + // INVARIANT: `inner` came from `Box::into_raw` above. + BoxHrTimerHandle { + inner, + _p: core::marker::PhantomData, + } + } +} + +impl RawHrTimerCallback for Pin> +where + T: 'static, + T: HasHrTimer, + T: for<'a> HrTimerCallback = Pin>>, + A: crate::alloc::Allocator, +{ + type CallbackTarget<'a> = Pin<&'a mut T>; + + unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart { + // `HrTimer` is `repr(C)` + let timer_ptr = ptr.cast::>(); + + // SAFETY: By C API contract `ptr` is the pointer we passed when + // queuing the timer, so it is a `HrTimer` embedded in a `T`. + let data_ptr = unsafe { T::timer_container_of(timer_ptr) }; + + // SAFETY: + // - As per the safety requirements of the trait `HrTimerHandle`, the + // `BoxHrTimerHandle` associated with this timer is guaranteed to + // be alive until this method returns. That handle owns the `T` + // behind `data_ptr` thus guaranteeing the validity of + // the reference created below. + // - As `data_ptr` comes from a `Pin>`, only pinned references to + // `data_ptr` exist. + let data_mut_ref = unsafe { Pin::new_unchecked(&mut *data_ptr) }; + + T::run(data_mut_ref).into_c() + } +} From bfa3a410bf03ca41a7a58dea1e9c2acac9295bf7 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:19:02 +0100 Subject: [PATCH 63/71] rust: hrtimer: add `HrTimerMode` Allow selection of timer mode by passing a `HrTimerMode` variant to `HrTimer::new`. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Lyude Paul Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-11-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time/hrtimer.rs | 82 +++++++++++++++++++++++++++++++++++-- 1 file changed, 79 insertions(+), 3 deletions(-) diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index cab230fb3e6e..ed5ccdb71064 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -80,6 +80,7 @@ use core::marker::PhantomData; pub struct HrTimer { #[pin] timer: Opaque, + mode: HrTimerMode, _t: PhantomData, } @@ -93,7 +94,7 @@ unsafe impl Sync for HrTimer {} impl HrTimer { /// Return an initializer for a new timer instance. - pub fn new() -> impl PinInit + pub fn new(mode: HrTimerMode) -> impl PinInit where T: HrTimerCallback, { @@ -108,10 +109,11 @@ impl HrTimer { place, Some(T::Pointer::run), bindings::CLOCK_MONOTONIC as i32, - bindings::hrtimer_mode_HRTIMER_MODE_REL, + mode.into_c(), ); } }), + mode: mode, _t: PhantomData, }) } @@ -369,7 +371,7 @@ pub unsafe trait HasHrTimer { Self::c_timer_ptr(this).cast_mut(), expires.to_ns(), 0, - bindings::hrtimer_mode_HRTIMER_MODE_REL, + (*Self::raw_get_timer(this)).mode.into_c(), ); } } @@ -393,6 +395,80 @@ impl HrTimerRestart { } } +/// Operational mode of [`HrTimer`]. +// NOTE: Some of these have the same encoding on the C side, so we keep +// `repr(Rust)` and convert elsewhere. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum HrTimerMode { + /// Timer expires at the given expiration time. + Absolute, + /// Timer expires after the given expiration time interpreted as a duration from now. + Relative, + /// Timer does not move between CPU cores. + Pinned, + /// Timer handler is executed in soft irq context. + Soft, + /// Timer handler is executed in hard irq context. + Hard, + /// Timer expires at the given expiration time. + /// Timer does not move between CPU cores. + AbsolutePinned, + /// Timer expires after the given expiration time interpreted as a duration from now. + /// Timer does not move between CPU cores. + RelativePinned, + /// Timer expires at the given expiration time. + /// Timer handler is executed in soft irq context. + AbsoluteSoft, + /// Timer expires after the given expiration time interpreted as a duration from now. + /// Timer handler is executed in soft irq context. + RelativeSoft, + /// Timer expires at the given expiration time. + /// Timer does not move between CPU cores. + /// Timer handler is executed in soft irq context. + AbsolutePinnedSoft, + /// Timer expires after the given expiration time interpreted as a duration from now. + /// Timer does not move between CPU cores. + /// Timer handler is executed in soft irq context. + RelativePinnedSoft, + /// Timer expires at the given expiration time. + /// Timer handler is executed in hard irq context. + AbsoluteHard, + /// Timer expires after the given expiration time interpreted as a duration from now. + /// Timer handler is executed in hard irq context. + RelativeHard, + /// Timer expires at the given expiration time. + /// Timer does not move between CPU cores. + /// Timer handler is executed in hard irq context. + AbsolutePinnedHard, + /// Timer expires after the given expiration time interpreted as a duration from now. + /// Timer does not move between CPU cores. + /// Timer handler is executed in hard irq context. + RelativePinnedHard, +} + +impl HrTimerMode { + fn into_c(self) -> bindings::hrtimer_mode { + use bindings::*; + match self { + HrTimerMode::Absolute => hrtimer_mode_HRTIMER_MODE_ABS, + HrTimerMode::Relative => hrtimer_mode_HRTIMER_MODE_REL, + HrTimerMode::Pinned => hrtimer_mode_HRTIMER_MODE_PINNED, + HrTimerMode::Soft => hrtimer_mode_HRTIMER_MODE_SOFT, + HrTimerMode::Hard => hrtimer_mode_HRTIMER_MODE_HARD, + HrTimerMode::AbsolutePinned => hrtimer_mode_HRTIMER_MODE_ABS_PINNED, + HrTimerMode::RelativePinned => hrtimer_mode_HRTIMER_MODE_REL_PINNED, + HrTimerMode::AbsoluteSoft => hrtimer_mode_HRTIMER_MODE_ABS_SOFT, + HrTimerMode::RelativeSoft => hrtimer_mode_HRTIMER_MODE_REL_SOFT, + HrTimerMode::AbsolutePinnedSoft => hrtimer_mode_HRTIMER_MODE_ABS_PINNED_SOFT, + HrTimerMode::RelativePinnedSoft => hrtimer_mode_HRTIMER_MODE_REL_PINNED_SOFT, + HrTimerMode::AbsoluteHard => hrtimer_mode_HRTIMER_MODE_ABS_HARD, + HrTimerMode::RelativeHard => hrtimer_mode_HRTIMER_MODE_REL_HARD, + HrTimerMode::AbsolutePinnedHard => hrtimer_mode_HRTIMER_MODE_ABS_PINNED_HARD, + HrTimerMode::RelativePinnedHard => hrtimer_mode_HRTIMER_MODE_REL_PINNED_HARD, + } + } +} + /// Use to implement the [`HasHrTimer`] trait. /// /// See [`module`] documentation for an example. From aa33de03a3d58a8e502ead3ca0d445a4fba22c83 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:19:03 +0100 Subject: [PATCH 64/71] rust: hrtimer: add clocksource selection through `ClockId` Allow selecting a clock source for timers by passing a `ClockId` variant to `HrTimer::new`. Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Lyude Paul Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-12-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- rust/kernel/time.rs | 66 +++++++++++++++++++++++++++++++++++++ rust/kernel/time/hrtimer.rs | 5 +-- 2 files changed, 69 insertions(+), 2 deletions(-) diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs index fab1dadfa589..f509cb0eb71e 100644 --- a/rust/kernel/time.rs +++ b/rust/kernel/time.rs @@ -83,3 +83,69 @@ impl core::ops::Sub for Ktime { } } } + +/// An identifier for a clock. Used when specifying clock sources. +/// +/// +/// Selection of the clock depends on the use case. In some cases the usage of a +/// particular clock is mandatory, e.g. in network protocols, filesystems.In other +/// cases the user of the clock has to decide which clock is best suited for the +/// purpose. In most scenarios clock [`ClockId::Monotonic`] is the best choice as it +/// provides a accurate monotonic notion of time (leap second smearing ignored). +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +#[repr(u32)] +pub enum ClockId { + /// A settable system-wide clock that measures real (i.e., wall-clock) time. + /// + /// Setting this clock requires appropriate privileges. This clock is + /// affected by discontinuous jumps in the system time (e.g., if the system + /// administrator manually changes the clock), and by frequency adjustments + /// performed by NTP and similar applications via adjtime(3), adjtimex(2), + /// clock_adjtime(2), and ntp_adjtime(3). This clock normally counts the + /// number of seconds since 1970-01-01 00:00:00 Coordinated Universal Time + /// (UTC) except that it ignores leap seconds; near a leap second it may be + /// adjusted by leap second smearing to stay roughly in sync with UTC. Leap + /// second smearing applies frequency adjustments to the clock to speed up + /// or slow down the clock to account for the leap second without + /// discontinuities in the clock. If leap second smearing is not applied, + /// the clock will experience discontinuity around leap second adjustment. + RealTime = bindings::CLOCK_REALTIME, + /// A monotonically increasing clock. + /// + /// A nonsettable system-wide clock that represents monotonic time since—as + /// described by POSIX—"some unspecified point in the past". On Linux, that + /// point corresponds to the number of seconds that the system has been + /// running since it was booted. + /// + /// The CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the + /// CLOCK_REAL (e.g., if the system administrator manually changes the + /// clock), but is affected by frequency adjustments. This clock does not + /// count time that the system is suspended. + Monotonic = bindings::CLOCK_MONOTONIC, + /// A monotonic that ticks while system is suspended. + /// + /// A nonsettable system-wide clock that is identical to CLOCK_MONOTONIC, + /// except that it also includes any time that the system is suspended. This + /// allows applications to get a suspend-aware monotonic clock without + /// having to deal with the complications of CLOCK_REALTIME, which may have + /// discontinuities if the time is changed using settimeofday(2) or similar. + BootTime = bindings::CLOCK_BOOTTIME, + /// International Atomic Time. + /// + /// A system-wide clock derived from wall-clock time but counting leap seconds. + /// + /// This clock is coupled to CLOCK_REALTIME and will be set when CLOCK_REALTIME is + /// set, or when the offset to CLOCK_REALTIME is changed via adjtimex(2). This + /// usually happens during boot and **should** not happen during normal operations. + /// However, if NTP or another application adjusts CLOCK_REALTIME by leap second + /// smearing, this clock will not be precise during leap second smearing. + /// + /// The acronym TAI refers to International Atomic Time. + TAI = bindings::CLOCK_TAI, +} + +impl ClockId { + fn into_c(self) -> bindings::clockid_t { + self as bindings::clockid_t + } +} diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs index ed5ccdb71064..4fc49f193125 100644 --- a/rust/kernel/time/hrtimer.rs +++ b/rust/kernel/time/hrtimer.rs @@ -67,6 +67,7 @@ //! A `restart` operation on a timer in the **stopped** state is equivalent to a //! `start` operation. +use super::ClockId; use crate::{init::PinInit, prelude::*, time::Ktime, types::Opaque}; use core::marker::PhantomData; @@ -94,7 +95,7 @@ unsafe impl Sync for HrTimer {} impl HrTimer { /// Return an initializer for a new timer instance. - pub fn new(mode: HrTimerMode) -> impl PinInit + pub fn new(mode: HrTimerMode, clock: ClockId) -> impl PinInit where T: HrTimerCallback, { @@ -108,7 +109,7 @@ impl HrTimer { bindings::hrtimer_setup( place, Some(T::Pointer::run), - bindings::CLOCK_MONOTONIC as i32, + clock.into_c(), mode.into_c(), ); } From 142d93914b8575753f56f0c3571bd81f214b7418 Mon Sep 17 00:00:00 2001 From: Andreas Hindborg Date: Sun, 9 Mar 2025 16:19:04 +0100 Subject: [PATCH 65/71] rust: hrtimer: add maintainer entry Add Andreas Hindborg as maintainer for Rust `hrtimer` abstractions. Also add Boqun Feng as reviewer. Acked-by: Boqun Feng Acked-by: Frederic Weisbecker Acked-by: Thomas Gleixner Reviewed-by: Lyude Paul Link: https://lore.kernel.org/r/20250309-hrtimer-v3-v6-12-rc2-v12-13-73586e2bd5f1@kernel.org Signed-off-by: Andreas Hindborg --- MAINTAINERS | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/MAINTAINERS b/MAINTAINERS index 25c86f47353d..865da0859f3d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -10355,6 +10355,21 @@ F: kernel/time/timer_list.c F: kernel/time/timer_migration.* F: tools/testing/selftests/timers/ +HIGH-RESOLUTION TIMERS [RUST] +M: Andreas Hindborg +R: Boqun Feng +R: Frederic Weisbecker +R: Lyude Paul +R: Thomas Gleixner +R: Anna-Maria Behnsen +L: rust-for-linux@vger.kernel.org +S: Supported +W: https://rust-for-linux.com +B: https://github.com/Rust-for-Linux/linux/issues +T: git https://github.com/Rust-for-Linux/linux.git hrtimer-next +F: rust/kernel/time/hrtimer.rs +F: rust/kernel/time/hrtimer/ + HIGH-SPEED SCC DRIVER FOR AX.25 L: linux-hams@vger.kernel.org S: Orphan From f6be7af44525a005f537ca04f24dc56b391f9a8b Mon Sep 17 00:00:00 2001 From: Charalampos Mitrodimas Date: Sat, 15 Mar 2025 21:48:11 +0000 Subject: [PATCH 66/71] rust: rbtree: fix comments referring to Box instead of KBox Several safety comments in the RBTree implementation still refer to "Box::from_raw" and "Box::into_raw", but the code actually uses KBox. These comments were not updated when the implementation transitioned from using Box to KBox. Fixes: 8373147ce496 ("rust: treewide: switch to our kernel `Box` type") Signed-off-by: Charalampos Mitrodimas Reviewed-by: Benno Lossin Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20250315-rbtree-comment-fixes-v1-1-51f72c420ff0@posteo.net Signed-off-by: Miguel Ojeda --- rust/kernel/rbtree.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rust/kernel/rbtree.rs b/rust/kernel/rbtree.rs index 1ea25c7092fb..5246b2c8a4ff 100644 --- a/rust/kernel/rbtree.rs +++ b/rust/kernel/rbtree.rs @@ -1168,12 +1168,12 @@ impl<'a, K, V> RawVacantEntry<'a, K, V> { fn insert(self, node: RBTreeNode) -> &'a mut V { let node = KBox::into_raw(node.node); - // SAFETY: `node` is valid at least until we call `Box::from_raw`, which only happens when + // SAFETY: `node` is valid at least until we call `KBox::from_raw`, which only happens when // the node is removed or replaced. let node_links = unsafe { addr_of_mut!((*node).links) }; // INVARIANT: We are linking in a new node, which is valid. It remains valid because we - // "forgot" it with `Box::into_raw`. + // "forgot" it with `KBox::into_raw`. // SAFETY: The type invariants of `RawVacantEntry` are exactly the safety requirements of `rb_link_node`. unsafe { bindings::rb_link_node(node_links, self.parent, self.child_field_of_parent) }; @@ -1259,7 +1259,7 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> { fn replace(self, node: RBTreeNode) -> RBTreeNode { let node = KBox::into_raw(node.node); - // SAFETY: `node` is valid at least until we call `Box::from_raw`, which only happens when + // SAFETY: `node` is valid at least until we call `KBox::from_raw`, which only happens when // the node is removed or replaced. let new_node_links = unsafe { addr_of_mut!((*node).links) }; From 4e72a62e8ddd00e50bfe9aec13995fa2079f6486 Mon Sep 17 00:00:00 2001 From: Tamir Duberstein Date: Mon, 17 Mar 2025 07:43:03 -0400 Subject: [PATCH 67/71] rust: uaccess: name the correct function Correctly refer to `reserve` rather than `try_reserve` in a comment. This comment has been incorrect since inception in commit 1b580e7b9ba2 ("rust: uaccess: add userspace pointers"). Fixes: 1b580e7b9ba2 ("rust: uaccess: add userspace pointers") Signed-off-by: Tamir Duberstein Reviewed-by: Alice Ryhl Reviewed-by: Benno Lossin Reviewed-by: Charalampos Mitrodimas Link: https://lore.kernel.org/r/20250317-uaccess-typo-reserve-v1-1-bbfcb45121f3@gmail.com Signed-off-by: Miguel Ojeda --- rust/kernel/uaccess.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rust/kernel/uaccess.rs b/rust/kernel/uaccess.rs index 719b0a48ff55..80a9782b1c6e 100644 --- a/rust/kernel/uaccess.rs +++ b/rust/kernel/uaccess.rs @@ -285,8 +285,7 @@ impl UserSliceReader { let len = self.length; buf.reserve(len, flags)?; - // The call to `try_reserve` was successful, so the spare capacity is at least `len` bytes - // long. + // The call to `reserve` was successful, so the spare capacity is at least `len` bytes long. self.read_raw(&mut buf.spare_capacity_mut()[..len])?; // SAFETY: Since the call to `read_raw` was successful, so the next `len` bytes of the From e1dfaa33fd2d8d7141f2602c4dfa5540403d3c14 Mon Sep 17 00:00:00 2001 From: Antonio Hickey Date: Wed, 19 Mar 2025 22:07:20 -0400 Subject: [PATCH 68/71] rust: enable `raw_ref_op` feature Since Rust 1.82.0 the `raw_ref_op` feature is stable [1]. By enabling this feature we can use `&raw const place` and `&raw mut place` instead of using `addr_of!(place)` and `addr_of_mut!(place)` macros. Allowing us to reduce macro complexity, and improve consistency with existing reference syntax as `&raw const`, `&raw mut` are similar to `&`, `&mut` making it fit more naturally with other existing code. Suggested-by: Benno Lossin Link: https://github.com/Rust-for-Linux/linux/issues/1148 Link: https://blog.rust-lang.org/2024/10/17/Rust-1.82.0.html#native-syntax-for-creating-a-raw-pointer [1] Signed-off-by: Antonio Hickey Reviewed-by: Benno Lossin Reviewed-by: Andreas Hindborg Reviewed-by: Tamir Duberstein Link: https://lore.kernel.org/r/20250320020740.1631171-2-contact@antoniohickey.com [ Removed dashed line change as discussed. Added Link to the explanation of the feature in the Rust 1.82.0 release blog post. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/lib.rs | 2 ++ scripts/Makefile.build | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 001374a96d66..ba0f3b0297b2 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -19,6 +19,8 @@ #![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(unsize))] #![feature(inline_const)] #![feature(lint_reasons)] +// Stable in Rust 1.82 +#![feature(raw_ref_op)] // Stable in Rust 1.83 #![feature(const_maybe_uninit_as_mut_ptr)] #![feature(const_mut_refs)] diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 08b6380933f5..56be83024851 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -226,7 +226,7 @@ $(obj)/%.lst: $(obj)/%.c FORCE # Compile Rust sources (.rs) # --------------------------------------------------------------------------- -rust_allowed_features := asm_const,asm_goto,arbitrary_self_types,lint_reasons +rust_allowed_features := asm_const,asm_goto,arbitrary_self_types,lint_reasons,raw_ref_op # `--out-dir` is required to avoid temporaries being created by `rustc` in the # current working directory, which may be not accessible in the out-of-tree From 2a571248dfa9d1ebac9db4564472b3dec157c99f Mon Sep 17 00:00:00 2001 From: Antonio Hickey Date: Wed, 19 Mar 2025 22:07:35 -0400 Subject: [PATCH 69/71] rust: block: refactor to use `&raw mut` Replace all occurrences (one) of `addr_of_mut!(place)` with `&raw mut place`. This will allow us to reduce macro complexity, and improve consistency with existing reference syntax as `&raw mut` is similar to `&mut` making it fit more naturally with other existing code. Suggested-by: Benno Lossin Link: https://github.com/Rust-for-Linux/linux/issues/1148 Signed-off-by: Antonio Hickey Acked-by: Andreas Hindborg Reviewed-by: Benno Lossin Reviewed-by: Boqun Feng Link: https://lore.kernel.org/r/20250320020740.1631171-17-contact@antoniohickey.com [ Reworded slightly. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/block/mq/request.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rust/kernel/block/mq/request.rs b/rust/kernel/block/mq/request.rs index 7943f43b9575..4a5b7ec914ef 100644 --- a/rust/kernel/block/mq/request.rs +++ b/rust/kernel/block/mq/request.rs @@ -12,7 +12,7 @@ use crate::{ }; use core::{ marker::PhantomData, - ptr::{addr_of_mut, NonNull}, + ptr::NonNull, sync::atomic::{AtomicU64, Ordering}, }; @@ -187,7 +187,7 @@ impl RequestDataWrapper { pub(crate) unsafe fn refcount_ptr(this: *mut Self) -> *mut AtomicU64 { // SAFETY: Because of the safety requirements of this function, the // field projection is safe. - unsafe { addr_of_mut!((*this).refcount) } + unsafe { &raw mut (*this).refcount } } } From a0b539ad369fe434fe488faf92d4ae770a27a90f Mon Sep 17 00:00:00 2001 From: Tamir Duberstein Date: Mon, 10 Feb 2025 09:51:07 -0500 Subject: [PATCH 70/71] rust: macros: fix `make rusttest` build on macOS Do not emit `#[link_section = ".modinfo"]` on macOS (i.e. when building userspace tests); .modinfo is not a legal section specifier in mach-o. Before this change tests failed to compile: ---- ../rust/macros/lib.rs - module (line 66) stdout ---- rustc-LLVM ERROR: Global variable '_ZN8rust_out13__module_init13__module_init27__MY_DEVICE_DRIVER_MODULE_017h141f80536770e0d4E' has an invalid section specifier '.modinfo': mach-o section specifier requires a segment and section separated by a comma. Couldn't compile the test. ---- ../rust/macros/lib.rs - module (line 33) stdout ---- rustc-LLVM ERROR: Global variable '_ZN8rust_out13__module_init13__module_init20__MY_KERNEL_MODULE_017h5d79189564b41e07E' has an invalid section specifier '.modinfo': mach-o section specifier requires a segment and section separated by a comma. Couldn't compile the test. Signed-off-by: Tamir Duberstein Link: https://lore.kernel.org/r/20250210-macros-section-v2-1-3bb9ff44b969@gmail.com Signed-off-by: Miguel Ojeda --- rust/macros/module.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust/macros/module.rs b/rust/macros/module.rs index 46f20682a7a9..8ab4e1f3eb45 100644 --- a/rust/macros/module.rs +++ b/rust/macros/module.rs @@ -56,7 +56,7 @@ impl<'a> ModInfoBuilder<'a> { " {cfg} #[doc(hidden)] - #[link_section = \".modinfo\"] + #[cfg_attr(not(target_os = \"macos\"), link_section = \".modinfo\")] #[used] pub static __{module}_{counter}: [u8; {length}] = *{string}; ", From 28bb48c4cb34f65a9aa602142e76e1426da31293 Mon Sep 17 00:00:00 2001 From: Danilo Krummrich Date: Mon, 24 Mar 2025 18:40:48 +0100 Subject: [PATCH 71/71] rust: dma: add `Send` implementation for `CoherentAllocation` Stephen found a future build failure in linux-next [1]: error[E0277]: `*mut MyStruct` cannot be sent between threads safely --> samples/rust/rust_dma.rs:47:22 | 47 | impl pci::Driver for DmaSampleDriver { | ^^^^^^^^^^^^^^^ `*mut MyStruct` cannot be sent between threads safely It is caused by the interaction between commit 935e1d90bf6f ("rust: pci: require Send for Driver trait implementers") from the driver-core tree, which fixes a missing concurrency requirement, and commit 9901addae63b ("samples: rust: add Rust dma test sample driver") which adds a sample that does not satisfy that requirement. Add a `Send` implementation to `CoherentAllocation`, which allows the sample (and other future users) to satisfy it. Reported-by: Stephen Rothwell Closes: https://lore.kernel.org/linux-next/20250324215702.1515ba92@canb.auug.org.au/ [1] Signed-off-by: Danilo Krummrich Reviewed-by: Boqun Feng Link: https://lore.kernel.org/r/20250324174048.1075597-1-ojeda@kernel.org [ Added number to Closes. Fix typo spotted by Boqun. - Miguel ] Signed-off-by: Miguel Ojeda --- rust/kernel/dma.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/rust/kernel/dma.rs b/rust/kernel/dma.rs index 9d00f9c49f47..8cdc76043ee7 100644 --- a/rust/kernel/dma.rs +++ b/rust/kernel/dma.rs @@ -301,6 +301,10 @@ impl Drop for CoherentAllocation { } } +// SAFETY: It is safe to send a `CoherentAllocation` to another thread if `T` +// can be sent to another thread. +unsafe impl Send for CoherentAllocation {} + /// Reads a field of an item from an allocated region of structs. /// /// # Examples