1 // SPDX-License-Identifier: GPL-2.0
11 //! generic, they are used only at compile-time, so they shouldn't exist in the final binary.
36 //! use kernel::sync::Arc;
51 //!     fn new(value: i32) -> Result<Arc<Self>> {
52 //!         Arc::pin_init(pin_init!(MyStruct {
54 //!             work <- new_work!("MyStruct::work"),
60 //!     type Pointer = Arc<MyStruct>;
62 //!     fn run(this: Arc<MyStruct>) {
69 //! fn print_later(val: Arc<MyStruct>) {
78 //! use kernel::sync::Arc;
97 //!     fn new(value_1: i32, value_2: i32) -> Result<Arc<Self>> {
98 //!         Arc::pin_init(pin_init!(MyStruct {
101 //!             work_1 <- new_work!("MyStruct::work_1"),
102 //!             work_2 <- new_work!("MyStruct::work_2"),
108 //!     type Pointer = Arc<MyStruct>;
110 //!     fn run(this: Arc<MyStruct>) {
116 //!     type Pointer = Arc<MyStruct>;
118 //!     fn run(this: Arc<MyStruct>) {
123 //! fn print_1_later(val: Arc<MyStruct>) {
124 //!     let _ = workqueue::system().enqueue::<Arc<MyStruct>, 1>(val);
127 //! fn print_2_later(val: Arc<MyStruct>) {
128 //!     let _ = workqueue::system().enqueue::<Arc<MyStruct>, 2>(val);
137 //! use kernel::sync::Arc;
152 //!     fn new(value: i32) -> Result<Arc<Self>> {
153 //!         Arc::pin_init(
156 //!                 work <- new_delayed_work!("MyStruct::work"),
164 //!     type Pointer = Arc<MyStruct>;
166 //!     fn run(this: Arc<MyStruct>) {
173 //! fn print_later(val: Arc<MyStruct>) {
179 //! fn print_now(val: Arc<MyStruct>) {
192     sync::Arc,
199 /// Creates a [`Work`] initialiser with the given name and a newly-created lock class.
208 /// Creates a [`DelayedWork`] initialiser with the given name and a newly-created lock class.
244 // SAFETY: Accesses to workqueues used by [`Queue`] are thread-safe.
246 // SAFETY: Accesses to workqueues used by [`Queue`] are thread-safe.
256     pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue {  in from_raw()
267     pub fn enqueue<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput  in enqueue()
300     pub fn enqueue_delayed<W, const ID: u64>(&self, w: W, delay: Jiffies) -> W::EnqueueOutput  in enqueue_delayed()
338     ) -> Result<(), AllocError> {  in try_spawn()
340             work <- new_work!("Queue::try_spawn"),  in try_spawn()
371 /// This is the low-level trait that is designed for being as general as possible.
411     unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput  in __enqueue()
413         F: FnOnce(*mut bindings::work_struct) -> bool;  in __enqueue()
428 /// This trait is implemented by `Pin<KBox<T>>` and [`Arc<T>`], and is mainly intended to be
459     /// The pointer type that this struct is wrapped in. This will typically be `Arc<Self>` or
497     pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self>  in new()
502             work <- Opaque::ffi_init(|slot| {  in new()
526     pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {  in raw_get()
559 /// - `work_container_of(raw_get_work(ptr)) == ptr` for any `ptr: *mut Self`.
560 /// - `raw_get_work(work_container_of(ptr)) == ptr` for any `ptr: *mut Work<T, ID>`.
571     unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID>;  in raw_get_work()
578     unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self;  in work_container_of()
586 /// use kernel::sync::Arc;
610 …     unsafe fn raw_get_work(ptr: *mut Self) -> *mut $crate::workqueue::Work<$work_type $(, $id)?> {
620             ) -> *mut Self {
670     ) -> impl PinInit<Self>  in new()
675             dwork <- Opaque::ffi_init(|slot: *mut bindings::delayed_work| {  in new()
689                 // the timer is embedded in a `struct delayed_work`, and only ever scheduled via  in new()
693                         core::ptr::addr_of_mut!((*slot).timer),  in new()
712     pub unsafe fn raw_as_work(ptr: *const Self) -> *mut Work<T, ID> {  in raw_as_work()
739 /// use kernel::sync::Arc;
770             ) -> *mut $crate::workqueue::Work<$work_type $(, $id)?> {
783             ) -> *mut Self {
808 //   - `__enqueue` gets the `work_struct` from the `Work` field, using `T::raw_get_work`.
809 //   - The only safe way to create a `Work` object is through `Work::new`.
810 //   - `Work::new` makes sure that `T::Pointer::run` is passed to `init_work_with_key`.
811 //   - Finally `Work` and `RawWorkItem` guarantee that the correct `Work` field
814 //     implementation of `WorkItemPointer` for `Arc<T>`.
815 unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Arc<T>  implementation
823         // SAFETY: This computes the pointer that `__enqueue` got from `Arc::into_raw`.  in run()
825         // SAFETY: This pointer comes from `Arc::into_raw` and we've been given back ownership.  in run()
826         let arc = unsafe { Arc::from_raw(ptr) };  in run()  localVariable
828         T::run(arc)  in run()
833 // the closure because we get it from an `Arc`, which means that the ref count will be at least 1,
834 // and we don't drop the `Arc` ourselves. If `queue_work_on` returns true, it is further guaranteed
839 unsafe impl<T, const ID: u64> RawWorkItem<ID> for Arc<T>  implementation
846     unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput  in __enqueue()
848         F: FnOnce(*mut bindings::work_struct) -> bool,  in __enqueue()
851         let ptr = Arc::into_raw(self).cast_mut();  in __enqueue()
853         // SAFETY: Pointers into an `Arc` point at a valid value.  in __enqueue()
862             Err(unsafe { Arc::from_raw(ptr) })  in __enqueue()
870 unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Arc<T>  implementation
886         // SAFETY: This computes the pointer that `__enqueue` got from `Arc::into_raw`.  in run()
888         // SAFETY: This pointer comes from `Arc::into_raw` and we've been given back ownership.  in run()
905     unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput  in __enqueue()
907         F: FnOnce(*mut bindings::work_struct) -> bool,  in __enqueue()
939 /// It is the one used by `schedule[_delayed]_work[_on]()`. Multi-CPU multi-threaded. There are
943 pub fn system() -> &'static Queue {  in system()
948 /// Returns the system high-priority work queue (`system_highpri_wq`).
952 pub fn system_highpri() -> &'static Queue {  in system_highpri()
957 /// Returns the system work queue for potentially long-running work items (`system_long_wq`).
961 pub fn system_long() -> &'static Queue {  in system_long()
971 pub fn system_unbound() -> &'static Queue {  in system_unbound()
982 pub fn system_freezable() -> &'static Queue {  in system_freezable()
987 /// Returns the system power-efficient work queue (`system_power_efficient_wq`).
992 pub fn system_power_efficient() -> &'static Queue {  in system_power_efficient()
997 /// Returns the system freezable power-efficient work queue (`system_freezable_power_efficient_wq`).
1003 pub fn system_freezable_power_efficient() -> &'static Queue {  in system_freezable_power_efficient()
1012 pub fn system_bh() -> &'static Queue {  in system_bh()
1017 /// Returns the system bottom halves high-priority work queue (`system_bh_highpri_wq`).
1021 pub fn system_bh_highpri() -> &'static Queue {  in system_bh_highpri()