From 3e0bc2855b573bcffa2a52955a878f537f5ac0cd Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Thu, 1 Feb 2024 20:06:20 +0100 Subject: workqueue: rust: sync with `WORK_CPU_UNBOUND` change Commit e563d0a7cdc1 ("workqueue: Break up enum definitions and give names to the types") gives a name to the `enum` where `WORK_CPU_UNBOUND` was defined, so `bindgen` changes its output from e.g.: pub type _bindgen_ty_10 = core::ffi::c_uint; pub const WORK_CPU_UNBOUND: _bindgen_ty_10 = 64; to e.g.: pub type wq_misc_consts = core::ffi::c_uint; pub const wq_misc_consts_WORK_CPU_UNBOUND: wq_misc_consts = 64; Thus update Rust's side to match the change (which requires a slight reformat of the code), fixing the build error. Closes: https://lore.kernel.org/rust-for-linux/CANiq72=9PZ89bCAVX0ZV4cqrYSLoZWyn-d_K4KpBMHjwUMdC3A@mail.gmail.com/ Fixes: e563d0a7cdc1 ("workqueue: Break up enum definitions and give names to the types") Signed-off-by: Miguel Ojeda Reviewed-by: Boqun Feng Signed-off-by: Tejun Heo --- rust/kernel/workqueue.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'rust/kernel/workqueue.rs') diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index 498397877376..d00231e18007 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -199,7 +199,11 @@ impl Queue { // stay valid until we call the function pointer in the `work_struct`, so the access is ok. unsafe { w.__enqueue(move |work_ptr| { - bindings::queue_work_on(bindings::WORK_CPU_UNBOUND as _, queue_ptr, work_ptr) + bindings::queue_work_on( + bindings::wq_misc_consts_WORK_CPU_UNBOUND as _, + queue_ptr, + work_ptr, + ) }) } } -- cgit v1.2.3-70-g09d2 From b6cda913bba42e1fdad82df41d906ff603319743 Mon Sep 17 00:00:00 2001 From: Valentin Obst Date: Wed, 31 Jan 2024 21:23:23 +0100 Subject: rust: kernel: fix multiple typos in documentation Fixes multiple trivial typos in documentation and comments of the kernel crate. allocator: - Fix a trivial list item alignment issue in the last SAFETY comment of `krealloc_aligned`. init: - Replace 'type' with 'trait' in the doc comments of the `PinInit` and `Init` traits. - Add colons before starting lists. - Add spaces between the type and equal sign to respect the code formatting rules in example code. - End a sentence with a full stop instead of a colon. ioctl: - Replace 'an' with 'a' where appropriate. str: - Replace 'Return' with 'Returns' in the doc comment of `bytes_written` as the text describes what the function does. sync/lock: - Fix a trivial list item alignment issue in the Safety section of the `Backend` trait's description. sync/lock/spinlock: - The code in this module operates on spinlocks, not mutexes. Thus, replace 'mutex' with 'spinlock' in the SAFETY comment of `unlock`. workqueue: - Replace "wont" with "won't" in the doc comment of `__enqueue`. Signed-off-by: Valentin Obst Reviewed-by: Trevor Gross Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20240131-doc-fixes-v3-v3-1-0c8af94ed7de@valentinobst.de Signed-off-by: Miguel Ojeda --- rust/kernel/allocator.rs | 2 +- rust/kernel/init.rs | 16 ++++++++-------- rust/kernel/ioctl.rs | 4 ++-- rust/kernel/str.rs | 2 +- rust/kernel/sync/lock.rs | 4 ++-- rust/kernel/sync/lock/spinlock.rs | 2 +- rust/kernel/workqueue.rs | 2 +- 7 files changed, 16 insertions(+), 16 deletions(-) (limited to 'rust/kernel/workqueue.rs') diff --git a/rust/kernel/allocator.rs b/rust/kernel/allocator.rs index 4b057e837358..01ad139e19bc 100644 --- a/rust/kernel/allocator.rs +++ b/rust/kernel/allocator.rs @@ -35,7 +35,7 @@ unsafe fn krealloc_aligned(ptr: *mut u8, new_layout: Layout, flags: bindings::gf // - `ptr` is either null or a pointer returned from a previous `k{re}alloc()` by the // function safety requirement. // - `size` is greater than 0 since it's either a `layout.size()` (which cannot be zero - // according to the function safety requirement) or a result from `next_power_of_two()`. + // according to the function safety requirement) or a result from `next_power_of_two()`. unsafe { bindings::krealloc(ptr as *const core::ffi::c_void, size, flags) as *mut u8 } } diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs index 65be9ae57b80..16a99984622c 100644 --- a/rust/kernel/init.rs +++ b/rust/kernel/init.rs @@ -751,10 +751,10 @@ macro_rules! try_init { /// /// # Safety /// -/// When implementing this type you will need to take great care. Also there are probably very few +/// When implementing this trait you will need to take great care. Also there are probably very few /// cases where a manual implementation is necessary. Use [`pin_init_from_closure`] where possible. /// -/// The [`PinInit::__pinned_init`] function +/// The [`PinInit::__pinned_init`] function: /// - returns `Ok(())` if it initialized every field of `slot`, /// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: /// - `slot` can be deallocated without UB occurring, @@ -861,10 +861,10 @@ where /// /// # Safety /// -/// When implementing this type you will need to take great care. Also there are probably very few +/// When implementing this trait you will need to take great care. Also there are probably very few /// cases where a manual implementation is necessary. Use [`init_from_closure`] where possible. /// -/// The [`Init::__init`] function +/// The [`Init::__init`] function: /// - returns `Ok(())` if it initialized every field of `slot`, /// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means: /// - `slot` can be deallocated without UB occurring, @@ -1013,7 +1013,7 @@ pub fn uninit() -> impl Init, E> { /// /// ```rust /// use kernel::{error::Error, init::init_array_from_fn}; -/// let array: Box<[usize; 1_000]>= Box::init::(init_array_from_fn(|i| i)).unwrap(); +/// let array: Box<[usize; 1_000]> = Box::init::(init_array_from_fn(|i| i)).unwrap(); /// assert_eq!(array.len(), 1_000); /// ``` pub fn init_array_from_fn( @@ -1027,7 +1027,7 @@ where // 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: + // 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. @@ -1056,7 +1056,7 @@ where /// /// ```rust /// use kernel::{sync::{Arc, Mutex}, init::pin_init_array_from_fn, new_mutex}; -/// let array: Arc<[Mutex; 1_000]>= +/// let array: Arc<[Mutex; 1_000]> = /// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i))).unwrap(); /// assert_eq!(array.len(), 1_000); /// ``` @@ -1071,7 +1071,7 @@ where // 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: + // 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. diff --git a/rust/kernel/ioctl.rs b/rust/kernel/ioctl.rs index f1d42ab69972..59050e5f5a5a 100644 --- a/rust/kernel/ioctl.rs +++ b/rust/kernel/ioctl.rs @@ -28,13 +28,13 @@ pub const fn _IO(ty: u32, nr: u32) -> u32 { _IOC(uapi::_IOC_NONE, ty, nr, 0) } -/// Build an ioctl number for an read-only ioctl. +/// Build an ioctl number for a read-only ioctl. #[inline(always)] pub const fn _IOR(ty: u32, nr: u32) -> u32 { _IOC(uapi::_IOC_READ, ty, nr, core::mem::size_of::()) } -/// Build an ioctl number for an write-only ioctl. +/// Build an ioctl number for a write-only ioctl. #[inline(always)] pub const fn _IOW(ty: u32, nr: u32) -> u32 { _IOC(uapi::_IOC_WRITE, ty, nr, core::mem::size_of::()) diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index 7d848b83add4..0a8569594fc3 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -449,7 +449,7 @@ impl RawFormatter { self.pos as _ } - /// Return the number of bytes written to the formatter. + /// Returns the number of bytes written to the formatter. pub(crate) fn bytes_written(&self) -> usize { self.pos - self.beg } diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs index 149a5259d431..072b8ef2a0fa 100644 --- a/rust/kernel/sync/lock.rs +++ b/rust/kernel/sync/lock.rs @@ -21,9 +21,9 @@ pub mod spinlock; /// # Safety /// /// - Implementers must ensure that only one thread/CPU may access the protected data once the lock -/// is owned, that is, between calls to `lock` and `unlock`. +/// is owned, that is, between calls to `lock` and `unlock`. /// - Implementers must also ensure that `relock` uses the same locking method as the original -/// lock operation. +/// lock operation. pub unsafe trait Backend { /// The state required by the lock. type State; diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs index 068535ce1b29..e5e0bf621988 100644 --- a/rust/kernel/sync/lock/spinlock.rs +++ b/rust/kernel/sync/lock/spinlock.rs @@ -112,7 +112,7 @@ unsafe impl super::Backend for SpinLockBackend { unsafe fn unlock(ptr: *mut Self::State, _guard_state: &Self::GuardState) { // SAFETY: The safety requirements of this function ensure that `ptr` is valid and that the - // caller is the owner of the mutex. + // caller is the owner of the spinlock. unsafe { bindings::spin_unlock(ptr) } } } diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index 498397877376..8775c34d12a5 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -253,7 +253,7 @@ impl WorkItem for ClosureWork { /// actual value of the id is not important as long as you use different ids for different fields /// of the same struct. (Fields of different structs need not use different ids.) /// -/// Note that the id is used only to select the right method to call during compilation. It wont be +/// Note that the id is used only to select the right method to call during compilation. It won't be /// part of the final executable. /// /// # Safety -- cgit v1.2.3-70-g09d2 From af8b18d7404bfb82aa07a09ad5b53d33ab2955d8 Mon Sep 17 00:00:00 2001 From: Valentin Obst Date: Wed, 31 Jan 2024 21:23:30 +0100 Subject: rust: kernel: mark code fragments in docs with backticks Fix places where comments include code fragments that are not enclosed in backticks. Signed-off-by: Valentin Obst Reviewed-by: Trevor Gross Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20240131-doc-fixes-v3-v3-8-0c8af94ed7de@valentinobst.de Signed-off-by: Miguel Ojeda --- rust/kernel/ioctl.rs | 2 +- rust/kernel/sync/lock.rs | 2 +- rust/kernel/task.rs | 2 +- rust/kernel/workqueue.rs | 9 +++++---- 4 files changed, 8 insertions(+), 7 deletions(-) (limited to 'rust/kernel/workqueue.rs') diff --git a/rust/kernel/ioctl.rs b/rust/kernel/ioctl.rs index 5987ad6d38a7..cfa7d080b531 100644 --- a/rust/kernel/ioctl.rs +++ b/rust/kernel/ioctl.rs @@ -1,6 +1,6 @@ // SPDX-License-Identifier: GPL-2.0 -//! ioctl() number definitions. +//! `ioctl()` number definitions. //! //! C header: [`include/asm-generic/ioctl.h`](srctree/include/asm-generic/ioctl.h) diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs index 072b8ef2a0fa..10ccc0e39147 100644 --- a/rust/kernel/sync/lock.rs +++ b/rust/kernel/sync/lock.rs @@ -28,7 +28,7 @@ pub unsafe trait Backend { /// The state required by the lock. type State; - /// The state required to be kept between lock and unlock. + /// The state required to be kept between `lock` and `unlock`. type GuardState; /// Initialises the lock. diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs index 6726f1056066..ca6e7e31d71c 100644 --- a/rust/kernel/task.rs +++ b/rust/kernel/task.rs @@ -132,7 +132,7 @@ impl Task { /// Returns the group leader of the given task. pub fn group_leader(&self) -> &Task { // SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always - // have a valid group_leader. + // have a valid `group_leader`. let ptr = unsafe { *ptr::addr_of!((*self.0.get()).group_leader) }; // SAFETY: The lifetime of the returned task reference is tied to the lifetime of `self`, diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index 8775c34d12a5..d900dc911149 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -168,7 +168,7 @@ impl Queue { /// # Safety /// /// The caller must ensure that the provided raw pointer is not dangling, that it points at a - /// valid workqueue, and that it remains valid until the end of 'a. + /// valid workqueue, and that it remains valid until the end of `'a`. pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue { // SAFETY: The `Queue` type is `#[repr(transparent)]`, so the pointer cast is valid. The // caller promises that the pointer is not dangling. @@ -414,8 +414,8 @@ impl Work { /// /// # Safety /// -/// The [`OFFSET`] constant must be the offset of a field in Self of type [`Work`]. The methods on -/// this trait must have exactly the behavior that the definitions given below have. +/// The [`OFFSET`] constant must be the offset of a field in `Self` of type [`Work`]. The +/// methods on this trait must have exactly the behavior that the definitions given below have. /// /// [`Work`]: Work /// [`impl_has_work!`]: crate::impl_has_work @@ -428,7 +428,8 @@ pub unsafe trait HasWork { /// Returns the offset of the [`Work`] field. /// - /// This method exists because the [`OFFSET`] constant cannot be accessed if the type is not Sized. + /// This method exists because the [`OFFSET`] constant cannot be accessed if the type is not + /// `Sized`. /// /// [`Work`]: Work /// [`OFFSET`]: HasWork::OFFSET -- cgit v1.2.3-70-g09d2 From 4c799d1dc89b5287f82c7d7bdc5039928980b1bd Mon Sep 17 00:00:00 2001 From: Valentin Obst Date: Wed, 31 Jan 2024 21:23:32 +0100 Subject: rust: kernel: add doclinks Add doclinks to existing documentation. Signed-off-by: Valentin Obst Reviewed-by: Trevor Gross Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20240131-doc-fixes-v3-v3-10-0c8af94ed7de@valentinobst.de Signed-off-by: Miguel Ojeda --- rust/kernel/sync/arc.rs | 6 +++--- rust/kernel/sync/lock.rs | 13 ++++++++++--- rust/kernel/workqueue.rs | 45 +++++++++++++++++++++++++++------------------ 3 files changed, 40 insertions(+), 24 deletions(-) (limited to 'rust/kernel/workqueue.rs') diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs index 6c46b1affca5..936bc549a082 100644 --- a/rust/kernel/sync/arc.rs +++ b/rust/kernel/sync/arc.rs @@ -365,12 +365,12 @@ impl From>> for Arc { /// A borrowed reference to an [`Arc`] instance. /// /// For cases when one doesn't ever need to increment the refcount on the allocation, it is simpler -/// to use just `&T`, which we can trivially get from an `Arc` instance. +/// to use just `&T`, which we can trivially get from an [`Arc`] instance. /// /// However, when one may need to increment the refcount, it is preferable to use an `ArcBorrow` /// over `&Arc` because the latter results in a double-indirection: a pointer (shared reference) -/// to a pointer (`Arc`) to the object (`T`). An [`ArcBorrow`] eliminates this double -/// indirection while still allowing one to increment the refcount and getting an `Arc` when/if +/// to a pointer ([`Arc`]) to the object (`T`). An [`ArcBorrow`] eliminates this double +/// indirection while still allowing one to increment the refcount and getting an [`Arc`] when/if /// needed. /// /// # Invariants diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs index 10ccc0e39147..5b5c8efe427a 100644 --- a/rust/kernel/sync/lock.rs +++ b/rust/kernel/sync/lock.rs @@ -21,14 +21,21 @@ pub mod spinlock; /// # Safety /// /// - Implementers must ensure that only one thread/CPU may access the protected data once the lock -/// is owned, that is, between calls to `lock` and `unlock`. -/// - Implementers must also ensure that `relock` uses the same locking method as the original +/// is owned, that is, between calls to [`lock`] and [`unlock`]. +/// - Implementers must also ensure that [`relock`] uses the same locking method as the original /// lock operation. +/// +/// [`lock`]: Backend::lock +/// [`unlock`]: Backend::unlock +/// [`relock`]: Backend::relock pub unsafe trait Backend { /// The state required by the lock. type State; - /// The state required to be kept between `lock` and `unlock`. + /// The state required to be kept between [`lock`] and [`unlock`]. + /// + /// [`lock`]: Backend::lock + /// [`unlock`]: Backend::unlock type GuardState; /// Initialises the lock. diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index d900dc911149..ed3af3491b47 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -12,19 +12,19 @@ //! //! # The raw API //! -//! The raw API consists of the `RawWorkItem` trait, where the work item needs to provide an +//! The raw API consists of the [`RawWorkItem`] trait, where the work item needs to provide an //! arbitrary function that knows how to enqueue the work item. It should usually not be used //! directly, but if you want to, you can use it without using the pieces from the safe API. //! //! # The safe API //! -//! The safe API is used via the `Work` struct and `WorkItem` traits. Furthermore, it also includes -//! a trait called `WorkItemPointer`, which is usually not used directly by the user. +//! The safe API is used via the [`Work`] struct and [`WorkItem`] traits. Furthermore, it also +//! includes a trait called [`WorkItemPointer`], which is usually not used directly by the user. //! -//! * The `Work` struct is the Rust wrapper for the C `work_struct` type. -//! * The `WorkItem` trait is implemented for structs that can be enqueued to a workqueue. -//! * The `WorkItemPointer` trait is implemented for the pointer type that points at a something -//! that implements `WorkItem`. +//! * The [`Work`] struct is the Rust wrapper for the C `work_struct` type. +//! * The [`WorkItem`] trait is implemented for structs that can be enqueued to a workqueue. +//! * The [`WorkItemPointer`] trait is implemented for the pointer type that points at a something +//! that implements [`WorkItem`]. //! //! ## Example //! @@ -218,7 +218,9 @@ impl Queue { } } -/// A helper type used in `try_spawn`. +/// A helper type used in [`try_spawn`]. +/// +/// [`try_spawn`]: Queue::try_spawn #[pin_data] struct ClosureWork { #[pin] @@ -258,9 +260,11 @@ impl WorkItem for ClosureWork { /// /// # Safety /// -/// Implementers must ensure that any pointers passed to a `queue_work_on` closure by `__enqueue` +/// Implementers must ensure that any pointers passed to a `queue_work_on` closure by [`__enqueue`] /// remain valid for the duration specified in the guarantees section of the documentation for -/// `__enqueue`. +/// [`__enqueue`]. +/// +/// [`__enqueue`]: RawWorkItem::__enqueue pub unsafe trait RawWorkItem { /// The return type of [`Queue::enqueue`]. type EnqueueOutput; @@ -290,10 +294,11 @@ pub unsafe trait RawWorkItem { /// Defines the method that should be called directly when a work item is executed. /// -/// This trait is implemented by `Pin>` and `Arc`, and is mainly intended to be +/// This trait is implemented by `Pin>` and [`Arc`], and is mainly intended to be /// implemented for smart pointer types. For your own structs, you would implement [`WorkItem`] -/// instead. The `run` method on this trait will usually just perform the appropriate -/// `container_of` translation and then call into the `run` method from the [`WorkItem`] trait. +/// instead. The [`run`] method on this trait will usually just perform the appropriate +/// `container_of` translation and then call into the [`run`][WorkItem::run] method from the +/// [`WorkItem`] trait. /// /// This trait is used when the `work_struct` field is defined using the [`Work`] helper. /// @@ -309,8 +314,10 @@ pub unsafe trait WorkItemPointer: RawWorkItem { /// /// # Safety /// - /// The provided `work_struct` pointer must originate from a previous call to `__enqueue` where - /// the `queue_work_on` closure returned true, and the pointer must still be valid. + /// The provided `work_struct` pointer must originate from a previous call to [`__enqueue`] + /// where the `queue_work_on` closure returned true, and the pointer must still be valid. + /// + /// [`__enqueue`]: RawWorkItem::__enqueue unsafe extern "C" fn run(ptr: *mut bindings::work_struct); } @@ -328,12 +335,14 @@ pub trait WorkItem { /// Links for a work item. /// -/// This struct contains a function pointer to the `run` function from the [`WorkItemPointer`] +/// This struct contains a function pointer to the [`run`] function from the [`WorkItemPointer`] /// trait, and defines the linked list pointers necessary to enqueue a work item in a workqueue. /// /// Wraps the kernel's C `struct work_struct`. /// /// This is a helper type used to associate a `work_struct` with the [`WorkItem`] that uses it. +/// +/// [`run`]: WorkItemPointer::run #[repr(transparent)] pub struct Work { work: Opaque, @@ -409,7 +418,7 @@ impl Work { /// } /// ``` /// -/// Note that since the `Work` type is annotated with an id, you can have several `work_struct` +/// Note that since the [`Work`] type is annotated with an id, you can have several `work_struct` /// fields by using a different id for each one. /// /// # Safety @@ -429,7 +438,7 @@ pub unsafe trait HasWork { /// Returns the offset of the [`Work`] field. /// /// This method exists because the [`OFFSET`] constant cannot be accessed if the type is not - /// `Sized`. + /// [`Sized`]. /// /// [`Work`]: Work /// [`OFFSET`]: HasWork::OFFSET -- cgit v1.2.3-70-g09d2 From cd16c41fdefa014c719d9ad04cf88ef5e77edffa Mon Sep 17 00:00:00 2001 From: Valentin Obst Date: Wed, 31 Jan 2024 21:23:33 +0100 Subject: rust: kernel: remove unneeded doclink targets Remove explicit targets for doclinks in cases where rustdoc can determine the correct target by itself. The goal is to reduce unneeded verbosity in the source code. Signed-off-by: Valentin Obst Reviewed-by: Trevor Gross Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20240131-doc-fixes-v3-v3-11-0c8af94ed7de@valentinobst.de Signed-off-by: Miguel Ojeda --- rust/kernel/workqueue.rs | 10 ---------- 1 file changed, 10 deletions(-) (limited to 'rust/kernel/workqueue.rs') diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index ed3af3491b47..73d6fa544ca6 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -426,13 +426,10 @@ impl Work { /// The [`OFFSET`] constant must be the offset of a field in `Self` of type [`Work`]. The /// methods on this trait must have exactly the behavior that the definitions given below have. /// -/// [`Work`]: Work /// [`impl_has_work!`]: crate::impl_has_work /// [`OFFSET`]: HasWork::OFFSET pub unsafe trait HasWork { /// The offset of the [`Work`] field. - /// - /// [`Work`]: Work const OFFSET: usize; /// Returns the offset of the [`Work`] field. @@ -440,7 +437,6 @@ pub unsafe trait HasWork { /// This method exists because the [`OFFSET`] constant cannot be accessed if the type is not /// [`Sized`]. /// - /// [`Work`]: Work /// [`OFFSET`]: HasWork::OFFSET #[inline] fn get_work_offset(&self) -> usize { @@ -452,8 +448,6 @@ pub unsafe trait HasWork { /// # Safety /// /// The provided pointer must point at a valid struct of type `Self`. - /// - /// [`Work`]: Work #[inline] unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work { // SAFETY: The caller promises that the pointer is valid. @@ -465,8 +459,6 @@ pub unsafe trait HasWork { /// # Safety /// /// The pointer must point at a [`Work`] field in a struct of type `Self`. - /// - /// [`Work`]: Work #[inline] unsafe fn work_container_of(ptr: *mut Work) -> *mut Self where @@ -495,8 +487,6 @@ pub unsafe trait HasWork { /// impl HasWork for MyStruct { self.work_field } /// } /// ``` -/// -/// [`HasWork`]: HasWork #[macro_export] macro_rules! impl_has_work { ($(impl$(<$($implarg:ident),*>)? -- cgit v1.2.3-70-g09d2 From e283ee239220908118d66eea46dd8bb6175767b2 Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 29 Jan 2024 14:58:37 +0000 Subject: rust: kernel: add reexports for macros Currently, all macros are reexported with #[macro_export] only, which means that to access `new_work!` from the workqueue, you need to import it from the path `kernel::new_work` instead of importing it from the workqueue module like all other items in the workqueue. By adding reexports of the macros, it becomes possible to import the macros from the correct modules. It's still possible to import the macros from the root, but I don't think we can do anything about that. There is no functional change. This is merely a code cleanliness improvement. Signed-off-by: Alice Ryhl Reviewed-by: Trevor Gross Reviewed-by: Martin Rodriguez Reboredo Tested-by: Boqun Feng Link: https://lore.kernel.org/r/20240129145837.1419880-1-aliceryhl@google.com [ Removed new `use kernel::prelude::*`s, reworded title. ] Signed-off-by: Miguel Ojeda --- rust/kernel/init.rs | 6 +++--- rust/kernel/sync.rs | 5 +++-- rust/kernel/sync/condvar.rs | 4 ++-- rust/kernel/sync/lock/mutex.rs | 3 ++- rust/kernel/sync/lock/spinlock.rs | 3 ++- rust/kernel/workqueue.rs | 14 ++++++-------- 6 files changed, 18 insertions(+), 17 deletions(-) (limited to 'rust/kernel/workqueue.rs') diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs index 16a99984622c..424257284d16 100644 --- a/rust/kernel/init.rs +++ b/rust/kernel/init.rs @@ -36,7 +36,7 @@ //! //! ```rust //! # #![allow(clippy::disallowed_names)] -//! use kernel::{prelude::*, sync::Mutex, new_mutex}; +//! use kernel::sync::{new_mutex, Mutex}; //! # use core::pin::Pin; //! #[pin_data] //! struct Foo { @@ -56,7 +56,7 @@ //! //! ```rust //! # #![allow(clippy::disallowed_names)] -//! # use kernel::{prelude::*, sync::Mutex, new_mutex}; +//! # use kernel::sync::{new_mutex, Mutex}; //! # use core::pin::Pin; //! # #[pin_data] //! # struct Foo { @@ -79,7 +79,7 @@ //! above method only works for types where you can access the fields. //! //! ```rust -//! # use kernel::{new_mutex, sync::{Arc, Mutex}}; +//! # use kernel::sync::{new_mutex, Arc, Mutex}; //! let mtx: Result>> = Arc::pin_init(new_mutex!(42, "example::mtx")); //! ``` //! diff --git a/rust/kernel/sync.rs b/rust/kernel/sync.rs index c1fb10fc64f4..c983f63fd56e 100644 --- a/rust/kernel/sync.rs +++ b/rust/kernel/sync.rs @@ -13,8 +13,9 @@ pub mod lock; mod locked_by; pub use arc::{Arc, ArcBorrow, UniqueArc}; -pub use condvar::{CondVar, CondVarTimeoutResult}; -pub use lock::{mutex::Mutex, spinlock::SpinLock}; +pub use condvar::{new_condvar, CondVar, CondVarTimeoutResult}; +pub use lock::mutex::{new_mutex, Mutex}; +pub use lock::spinlock::{new_spinlock, SpinLock}; pub use locked_by::LockedBy; /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`. diff --git a/rust/kernel/sync/condvar.rs b/rust/kernel/sync/condvar.rs index fa1794972aa0..0c3671caffeb 100644 --- a/rust/kernel/sync/condvar.rs +++ b/rust/kernel/sync/condvar.rs @@ -27,6 +27,7 @@ macro_rules! new_condvar { $crate::sync::CondVar::new($crate::optional_name!($($name)?), $crate::static_lock_class!()) }; } +pub use new_condvar; /// A conditional variable. /// @@ -44,8 +45,7 @@ macro_rules! new_condvar { /// The following is an example of using a condvar with a mutex: /// /// ``` -/// use kernel::sync::{CondVar, Mutex}; -/// use kernel::{new_condvar, new_mutex}; +/// use kernel::sync::{new_condvar, new_mutex, CondVar, Mutex}; /// /// #[pin_data] /// pub struct Example { diff --git a/rust/kernel/sync/lock/mutex.rs b/rust/kernel/sync/lock/mutex.rs index 8c524a3ec45a..ef4c4634d294 100644 --- a/rust/kernel/sync/lock/mutex.rs +++ b/rust/kernel/sync/lock/mutex.rs @@ -17,6 +17,7 @@ macro_rules! new_mutex { $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!()) }; } +pub use new_mutex; /// A mutual exclusion primitive. /// @@ -35,7 +36,7 @@ macro_rules! new_mutex { /// contains an inner struct (`Inner`) that is protected by a mutex. /// /// ``` -/// use kernel::{init::InPlaceInit, init::PinInit, new_mutex, pin_init, sync::Mutex}; +/// use kernel::sync::{new_mutex, Mutex}; /// /// struct Inner { /// a: u32, diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs index e5e0bf621988..0b22c635634f 100644 --- a/rust/kernel/sync/lock/spinlock.rs +++ b/rust/kernel/sync/lock/spinlock.rs @@ -17,6 +17,7 @@ macro_rules! new_spinlock { $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!()) }; } +pub use new_spinlock; /// A spinlock. /// @@ -33,7 +34,7 @@ macro_rules! new_spinlock { /// contains an inner struct (`Inner`) that is protected by a spinlock. /// /// ``` -/// use kernel::{init::InPlaceInit, init::PinInit, new_spinlock, pin_init, sync::SpinLock}; +/// use kernel::sync::{new_spinlock, SpinLock}; /// /// struct Inner { /// a: u32, diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs index 73d6fa544ca6..544f0c51f1b7 100644 --- a/rust/kernel/workqueue.rs +++ b/rust/kernel/workqueue.rs @@ -35,8 +35,7 @@ //! ``` //! use kernel::prelude::*; //! use kernel::sync::Arc; -//! use kernel::workqueue::{self, Work, WorkItem}; -//! use kernel::{impl_has_work, new_work}; +//! use kernel::workqueue::{self, impl_has_work, new_work, Work, WorkItem}; //! //! #[pin_data] //! struct MyStruct { @@ -78,8 +77,7 @@ //! ``` //! use kernel::prelude::*; //! use kernel::sync::Arc; -//! use kernel::workqueue::{self, Work, WorkItem}; -//! use kernel::{impl_has_work, new_work}; +//! use kernel::workqueue::{self, impl_has_work, new_work, Work, WorkItem}; //! //! #[pin_data] //! struct MyStruct { @@ -147,6 +145,7 @@ macro_rules! new_work { $crate::workqueue::Work::new($crate::optional_name!($($name)?), $crate::static_lock_class!()) }; } +pub use new_work; /// A kernel work queue. /// @@ -405,9 +404,8 @@ impl Work { /// like this: /// /// ```no_run -/// use kernel::impl_has_work; /// use kernel::prelude::*; -/// use kernel::workqueue::Work; +/// use kernel::workqueue::{impl_has_work, Work}; /// /// struct MyWorkItem { /// work_field: Work, @@ -475,9 +473,8 @@ pub unsafe trait HasWork { /// # Examples /// /// ``` -/// use kernel::impl_has_work; /// use kernel::sync::Arc; -/// use kernel::workqueue::{self, Work}; +/// use kernel::workqueue::{self, impl_has_work, Work}; /// /// struct MyStruct { /// work_field: Work, @@ -509,6 +506,7 @@ macro_rules! impl_has_work { } )*}; } +pub use impl_has_work; impl_has_work! { impl HasWork for ClosureWork { self.work } -- cgit v1.2.3-70-g09d2