686 lines · rust
1// SPDX-License-Identifier: GPL-2.02 3//! Work queues.4//!5//! This file has two components: The raw work item API, and the safe work item API.6//!7//! One pattern that is used in both APIs is the `ID` const generic, which exists to allow a single8//! type to define multiple `work_struct` fields. This is done by choosing an id for each field,9//! and using that id to specify which field you wish to use. (The actual value doesn't matter, as10//! long as you use different values for different fields of the same struct.) Since these IDs are11//! generic, they are used only at compile-time, so they shouldn't exist in the final binary.12//!13//! # The raw API14//!15//! The raw API consists of the [`RawWorkItem`] trait, where the work item needs to provide an16//! arbitrary function that knows how to enqueue the work item. It should usually not be used17//! directly, but if you want to, you can use it without using the pieces from the safe API.18//!19//! # The safe API20//!21//! The safe API is used via the [`Work`] struct and [`WorkItem`] traits. Furthermore, it also22//! includes a trait called [`WorkItemPointer`], which is usually not used directly by the user.23//!24//! * The [`Work`] struct is the Rust wrapper for the C `work_struct` type.25//! * The [`WorkItem`] trait is implemented for structs that can be enqueued to a workqueue.26//! * The [`WorkItemPointer`] trait is implemented for the pointer type that points at a something27//! that implements [`WorkItem`].28//!29//! ## Example30//!31//! This example defines a struct that holds an integer and can be scheduled on the workqueue. When32//! the struct is executed, it will print the integer. Since there is only one `work_struct` field,33//! we do not need to specify ids for the fields.34//!35//! ```36//! use kernel::sync::Arc;37//! use kernel::workqueue::{self, impl_has_work, new_work, Work, WorkItem};38//!39//! #[pin_data]40//! struct MyStruct {41//! value: i32,42//! #[pin]43//! work: Work<MyStruct>,44//! }45//!46//! impl_has_work! {47//! impl HasWork<Self> for MyStruct { self.work }48//! }49//!50//! impl MyStruct {51//! fn new(value: i32) -> Result<Arc<Self>> {52//! Arc::pin_init(pin_init!(MyStruct {53//! value,54//! work <- new_work!("MyStruct::work"),55//! }), GFP_KERNEL)56//! }57//! }58//!59//! impl WorkItem for MyStruct {60//! type Pointer = Arc<MyStruct>;61//!62//! fn run(this: Arc<MyStruct>) {63//! pr_info!("The value is: {}", this.value);64//! }65//! }66//!67//! /// This method will enqueue the struct for execution on the system workqueue, where its value68//! /// will be printed.69//! fn print_later(val: Arc<MyStruct>) {70//! let _ = workqueue::system().enqueue(val);71//! }72//! ```73//!74//! The following example shows how multiple `work_struct` fields can be used:75//!76//! ```77//! use kernel::sync::Arc;78//! use kernel::workqueue::{self, impl_has_work, new_work, Work, WorkItem};79//!80//! #[pin_data]81//! struct MyStruct {82//! value_1: i32,83//! value_2: i32,84//! #[pin]85//! work_1: Work<MyStruct, 1>,86//! #[pin]87//! work_2: Work<MyStruct, 2>,88//! }89//!90//! impl_has_work! {91//! impl HasWork<Self, 1> for MyStruct { self.work_1 }92//! impl HasWork<Self, 2> for MyStruct { self.work_2 }93//! }94//!95//! impl MyStruct {96//! fn new(value_1: i32, value_2: i32) -> Result<Arc<Self>> {97//! Arc::pin_init(pin_init!(MyStruct {98//! value_1,99//! value_2,100//! work_1 <- new_work!("MyStruct::work_1"),101//! work_2 <- new_work!("MyStruct::work_2"),102//! }), GFP_KERNEL)103//! }104//! }105//!106//! impl WorkItem<1> for MyStruct {107//! type Pointer = Arc<MyStruct>;108//!109//! fn run(this: Arc<MyStruct>) {110//! pr_info!("The value is: {}", this.value_1);111//! }112//! }113//!114//! impl WorkItem<2> for MyStruct {115//! type Pointer = Arc<MyStruct>;116//!117//! fn run(this: Arc<MyStruct>) {118//! pr_info!("The second value is: {}", this.value_2);119//! }120//! }121//!122//! fn print_1_later(val: Arc<MyStruct>) {123//! let _ = workqueue::system().enqueue::<Arc<MyStruct>, 1>(val);124//! }125//!126//! fn print_2_later(val: Arc<MyStruct>) {127//! let _ = workqueue::system().enqueue::<Arc<MyStruct>, 2>(val);128//! }129//! ```130//!131//! C header: [`include/linux/workqueue.h`](srctree/include/linux/workqueue.h)132 133use crate::alloc::{AllocError, Flags};134use crate::{prelude::*, sync::Arc, sync::LockClassKey, types::Opaque};135use core::marker::PhantomData;136 137/// Creates a [`Work`] initialiser with the given name and a newly-created lock class.138#[macro_export]139macro_rules! new_work {140 ($($name:literal)?) => {141 $crate::workqueue::Work::new($crate::optional_name!($($name)?), $crate::static_lock_class!())142 };143}144pub use new_work;145 146/// A kernel work queue.147///148/// Wraps the kernel's C `struct workqueue_struct`.149///150/// It allows work items to be queued to run on thread pools managed by the kernel. Several are151/// always available, for example, `system`, `system_highpri`, `system_long`, etc.152#[repr(transparent)]153pub struct Queue(Opaque<bindings::workqueue_struct>);154 155// SAFETY: Accesses to workqueues used by [`Queue`] are thread-safe.156unsafe impl Send for Queue {}157// SAFETY: Accesses to workqueues used by [`Queue`] are thread-safe.158unsafe impl Sync for Queue {}159 160impl Queue {161 /// Use the provided `struct workqueue_struct` with Rust.162 ///163 /// # Safety164 ///165 /// The caller must ensure that the provided raw pointer is not dangling, that it points at a166 /// valid workqueue, and that it remains valid until the end of `'a`.167 pub unsafe fn from_raw<'a>(ptr: *const bindings::workqueue_struct) -> &'a Queue {168 // SAFETY: The `Queue` type is `#[repr(transparent)]`, so the pointer cast is valid. The169 // caller promises that the pointer is not dangling.170 unsafe { &*(ptr as *const Queue) }171 }172 173 /// Enqueues a work item.174 ///175 /// This may fail if the work item is already enqueued in a workqueue.176 ///177 /// The work item will be submitted using `WORK_CPU_UNBOUND`.178 pub fn enqueue<W, const ID: u64>(&self, w: W) -> W::EnqueueOutput179 where180 W: RawWorkItem<ID> + Send + 'static,181 {182 let queue_ptr = self.0.get();183 184 // SAFETY: We only return `false` if the `work_struct` is already in a workqueue. The other185 // `__enqueue` requirements are not relevant since `W` is `Send` and static.186 //187 // The call to `bindings::queue_work_on` will dereference the provided raw pointer, which188 // is ok because `__enqueue` guarantees that the pointer is valid for the duration of this189 // closure.190 //191 // Furthermore, if the C workqueue code accesses the pointer after this call to192 // `__enqueue`, then the work item was successfully enqueued, and `bindings::queue_work_on`193 // will have returned true. In this case, `__enqueue` promises that the raw pointer will194 // stay valid until we call the function pointer in the `work_struct`, so the access is ok.195 unsafe {196 w.__enqueue(move |work_ptr| {197 bindings::queue_work_on(198 bindings::wq_misc_consts_WORK_CPU_UNBOUND as _,199 queue_ptr,200 work_ptr,201 )202 })203 }204 }205 206 /// Tries to spawn the given function or closure as a work item.207 ///208 /// This method can fail because it allocates memory to store the work item.209 pub fn try_spawn<T: 'static + Send + FnOnce()>(210 &self,211 flags: Flags,212 func: T,213 ) -> Result<(), AllocError> {214 let init = pin_init!(ClosureWork {215 work <- new_work!("Queue::try_spawn"),216 func: Some(func),217 });218 219 self.enqueue(Box::pin_init(init, flags).map_err(|_| AllocError)?);220 Ok(())221 }222}223 224/// A helper type used in [`try_spawn`].225///226/// [`try_spawn`]: Queue::try_spawn227#[pin_data]228struct ClosureWork<T> {229 #[pin]230 work: Work<ClosureWork<T>>,231 func: Option<T>,232}233 234impl<T> ClosureWork<T> {235 fn project(self: Pin<&mut Self>) -> &mut Option<T> {236 // SAFETY: The `func` field is not structurally pinned.237 unsafe { &mut self.get_unchecked_mut().func }238 }239}240 241impl<T: FnOnce()> WorkItem for ClosureWork<T> {242 type Pointer = Pin<Box<Self>>;243 244 fn run(mut this: Pin<Box<Self>>) {245 if let Some(func) = this.as_mut().project().take() {246 (func)()247 }248 }249}250 251/// A raw work item.252///253/// This is the low-level trait that is designed for being as general as possible.254///255/// The `ID` parameter to this trait exists so that a single type can provide multiple256/// implementations of this trait. For example, if a struct has multiple `work_struct` fields, then257/// you will implement this trait once for each field, using a different id for each field. The258/// actual value of the id is not important as long as you use different ids for different fields259/// of the same struct. (Fields of different structs need not use different ids.)260///261/// Note that the id is used only to select the right method to call during compilation. It won't be262/// part of the final executable.263///264/// # Safety265///266/// Implementers must ensure that any pointers passed to a `queue_work_on` closure by [`__enqueue`]267/// remain valid for the duration specified in the guarantees section of the documentation for268/// [`__enqueue`].269///270/// [`__enqueue`]: RawWorkItem::__enqueue271pub unsafe trait RawWorkItem<const ID: u64> {272 /// The return type of [`Queue::enqueue`].273 type EnqueueOutput;274 275 /// Enqueues this work item on a queue using the provided `queue_work_on` method.276 ///277 /// # Guarantees278 ///279 /// If this method calls the provided closure, then the raw pointer is guaranteed to point at a280 /// valid `work_struct` for the duration of the call to the closure. If the closure returns281 /// true, then it is further guaranteed that the pointer remains valid until someone calls the282 /// function pointer stored in the `work_struct`.283 ///284 /// # Safety285 ///286 /// The provided closure may only return `false` if the `work_struct` is already in a workqueue.287 ///288 /// If the work item type is annotated with any lifetimes, then you must not call the function289 /// pointer after any such lifetime expires. (Never calling the function pointer is okay.)290 ///291 /// If the work item type is not [`Send`], then the function pointer must be called on the same292 /// thread as the call to `__enqueue`.293 unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput294 where295 F: FnOnce(*mut bindings::work_struct) -> bool;296}297 298/// Defines the method that should be called directly when a work item is executed.299///300/// This trait is implemented by `Pin<Box<T>>` and [`Arc<T>`], and is mainly intended to be301/// implemented for smart pointer types. For your own structs, you would implement [`WorkItem`]302/// instead. The [`run`] method on this trait will usually just perform the appropriate303/// `container_of` translation and then call into the [`run`][WorkItem::run] method from the304/// [`WorkItem`] trait.305///306/// This trait is used when the `work_struct` field is defined using the [`Work`] helper.307///308/// # Safety309///310/// Implementers must ensure that [`__enqueue`] uses a `work_struct` initialized with the [`run`]311/// method of this trait as the function pointer.312///313/// [`__enqueue`]: RawWorkItem::__enqueue314/// [`run`]: WorkItemPointer::run315pub unsafe trait WorkItemPointer<const ID: u64>: RawWorkItem<ID> {316 /// Run this work item.317 ///318 /// # Safety319 ///320 /// The provided `work_struct` pointer must originate from a previous call to [`__enqueue`]321 /// where the `queue_work_on` closure returned true, and the pointer must still be valid.322 ///323 /// [`__enqueue`]: RawWorkItem::__enqueue324 unsafe extern "C" fn run(ptr: *mut bindings::work_struct);325}326 327/// Defines the method that should be called when this work item is executed.328///329/// This trait is used when the `work_struct` field is defined using the [`Work`] helper.330pub trait WorkItem<const ID: u64 = 0> {331 /// The pointer type that this struct is wrapped in. This will typically be `Arc<Self>` or332 /// `Pin<Box<Self>>`.333 type Pointer: WorkItemPointer<ID>;334 335 /// The method that should be called when this work item is executed.336 fn run(this: Self::Pointer);337}338 339/// Links for a work item.340///341/// This struct contains a function pointer to the [`run`] function from the [`WorkItemPointer`]342/// trait, and defines the linked list pointers necessary to enqueue a work item in a workqueue.343///344/// Wraps the kernel's C `struct work_struct`.345///346/// This is a helper type used to associate a `work_struct` with the [`WorkItem`] that uses it.347///348/// [`run`]: WorkItemPointer::run349#[pin_data]350#[repr(transparent)]351pub struct Work<T: ?Sized, const ID: u64 = 0> {352 #[pin]353 work: Opaque<bindings::work_struct>,354 _inner: PhantomData<T>,355}356 357// SAFETY: Kernel work items are usable from any thread.358//359// We do not need to constrain `T` since the work item does not actually contain a `T`.360unsafe impl<T: ?Sized, const ID: u64> Send for Work<T, ID> {}361// SAFETY: Kernel work items are usable from any thread.362//363// We do not need to constrain `T` since the work item does not actually contain a `T`.364unsafe impl<T: ?Sized, const ID: u64> Sync for Work<T, ID> {}365 366impl<T: ?Sized, const ID: u64> Work<T, ID> {367 /// Creates a new instance of [`Work`].368 #[inline]369 #[allow(clippy::new_ret_no_self)]370 pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self>371 where372 T: WorkItem<ID>,373 {374 pin_init!(Self {375 work <- Opaque::ffi_init(|slot| {376 // SAFETY: The `WorkItemPointer` implementation promises that `run` can be used as377 // the work item function.378 unsafe {379 bindings::init_work_with_key(380 slot,381 Some(T::Pointer::run),382 false,383 name.as_char_ptr(),384 key.as_ptr(),385 )386 }387 }),388 _inner: PhantomData,389 })390 }391 392 /// Get a pointer to the inner `work_struct`.393 ///394 /// # Safety395 ///396 /// The provided pointer must not be dangling and must be properly aligned. (But the memory397 /// need not be initialized.)398 #[inline]399 pub unsafe fn raw_get(ptr: *const Self) -> *mut bindings::work_struct {400 // SAFETY: The caller promises that the pointer is aligned and not dangling.401 //402 // A pointer cast would also be ok due to `#[repr(transparent)]`. We use `addr_of!` so that403 // the compiler does not complain that the `work` field is unused.404 unsafe { Opaque::raw_get(core::ptr::addr_of!((*ptr).work)) }405 }406}407 408/// Declares that a type has a [`Work<T, ID>`] field.409///410/// The intended way of using this trait is via the [`impl_has_work!`] macro. You can use the macro411/// like this:412///413/// ```no_run414/// use kernel::workqueue::{impl_has_work, Work};415///416/// struct MyWorkItem {417/// work_field: Work<MyWorkItem, 1>,418/// }419///420/// impl_has_work! {421/// impl HasWork<MyWorkItem, 1> for MyWorkItem { self.work_field }422/// }423/// ```424///425/// Note that since the [`Work`] type is annotated with an id, you can have several `work_struct`426/// fields by using a different id for each one.427///428/// # Safety429///430/// The [`OFFSET`] constant must be the offset of a field in `Self` of type [`Work<T, ID>`]. The431/// methods on this trait must have exactly the behavior that the definitions given below have.432///433/// [`impl_has_work!`]: crate::impl_has_work434/// [`OFFSET`]: HasWork::OFFSET435pub unsafe trait HasWork<T, const ID: u64 = 0> {436 /// The offset of the [`Work<T, ID>`] field.437 const OFFSET: usize;438 439 /// Returns the offset of the [`Work<T, ID>`] field.440 ///441 /// This method exists because the [`OFFSET`] constant cannot be accessed if the type is not442 /// [`Sized`].443 ///444 /// [`OFFSET`]: HasWork::OFFSET445 #[inline]446 fn get_work_offset(&self) -> usize {447 Self::OFFSET448 }449 450 /// Returns a pointer to the [`Work<T, ID>`] field.451 ///452 /// # Safety453 ///454 /// The provided pointer must point at a valid struct of type `Self`.455 #[inline]456 unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<T, ID> {457 // SAFETY: The caller promises that the pointer is valid.458 unsafe { (ptr as *mut u8).add(Self::OFFSET) as *mut Work<T, ID> }459 }460 461 /// Returns a pointer to the struct containing the [`Work<T, ID>`] field.462 ///463 /// # Safety464 ///465 /// The pointer must point at a [`Work<T, ID>`] field in a struct of type `Self`.466 #[inline]467 unsafe fn work_container_of(ptr: *mut Work<T, ID>) -> *mut Self468 where469 Self: Sized,470 {471 // SAFETY: The caller promises that the pointer points at a field of the right type in the472 // right kind of struct.473 unsafe { (ptr as *mut u8).sub(Self::OFFSET) as *mut Self }474 }475}476 477/// Used to safely implement the [`HasWork<T, ID>`] trait.478///479/// # Examples480///481/// ```482/// use kernel::sync::Arc;483/// use kernel::workqueue::{self, impl_has_work, Work};484///485/// struct MyStruct<'a, T, const N: usize> {486/// work_field: Work<MyStruct<'a, T, N>, 17>,487/// f: fn(&'a [T; N]),488/// }489///490/// impl_has_work! {491/// impl{'a, T, const N: usize} HasWork<MyStruct<'a, T, N>, 17>492/// for MyStruct<'a, T, N> { self.work_field }493/// }494/// ```495#[macro_export]496macro_rules! impl_has_work {497 ($(impl$({$($generics:tt)*})?498 HasWork<$work_type:ty $(, $id:tt)?>499 for $self:ty500 { self.$field:ident }501 )*) => {$(502 // SAFETY: The implementation of `raw_get_work` only compiles if the field has the right503 // type.504 unsafe impl$(<$($generics)+>)? $crate::workqueue::HasWork<$work_type $(, $id)?> for $self {505 const OFFSET: usize = ::core::mem::offset_of!(Self, $field) as usize;506 507 #[inline]508 unsafe fn raw_get_work(ptr: *mut Self) -> *mut $crate::workqueue::Work<$work_type $(, $id)?> {509 // SAFETY: The caller promises that the pointer is not dangling.510 unsafe {511 ::core::ptr::addr_of_mut!((*ptr).$field)512 }513 }514 }515 )*};516}517pub use impl_has_work;518 519impl_has_work! {520 impl{T} HasWork<Self> for ClosureWork<T> { self.work }521}522 523unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Arc<T>524where525 T: WorkItem<ID, Pointer = Self>,526 T: HasWork<T, ID>,527{528 unsafe extern "C" fn run(ptr: *mut bindings::work_struct) {529 // SAFETY: The `__enqueue` method always uses a `work_struct` stored in a `Work<T, ID>`.530 let ptr = ptr as *mut Work<T, ID>;531 // SAFETY: This computes the pointer that `__enqueue` got from `Arc::into_raw`.532 let ptr = unsafe { T::work_container_of(ptr) };533 // SAFETY: This pointer comes from `Arc::into_raw` and we've been given back ownership.534 let arc = unsafe { Arc::from_raw(ptr) };535 536 T::run(arc)537 }538}539 540unsafe impl<T, const ID: u64> RawWorkItem<ID> for Arc<T>541where542 T: WorkItem<ID, Pointer = Self>,543 T: HasWork<T, ID>,544{545 type EnqueueOutput = Result<(), Self>;546 547 unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput548 where549 F: FnOnce(*mut bindings::work_struct) -> bool,550 {551 // Casting between const and mut is not a problem as long as the pointer is a raw pointer.552 let ptr = Arc::into_raw(self).cast_mut();553 554 // SAFETY: Pointers into an `Arc` point at a valid value.555 let work_ptr = unsafe { T::raw_get_work(ptr) };556 // SAFETY: `raw_get_work` returns a pointer to a valid value.557 let work_ptr = unsafe { Work::raw_get(work_ptr) };558 559 if queue_work_on(work_ptr) {560 Ok(())561 } else {562 // SAFETY: The work queue has not taken ownership of the pointer.563 Err(unsafe { Arc::from_raw(ptr) })564 }565 }566}567 568unsafe impl<T, const ID: u64> WorkItemPointer<ID> for Pin<Box<T>>569where570 T: WorkItem<ID, Pointer = Self>,571 T: HasWork<T, ID>,572{573 unsafe extern "C" fn run(ptr: *mut bindings::work_struct) {574 // SAFETY: The `__enqueue` method always uses a `work_struct` stored in a `Work<T, ID>`.575 let ptr = ptr as *mut Work<T, ID>;576 // SAFETY: This computes the pointer that `__enqueue` got from `Arc::into_raw`.577 let ptr = unsafe { T::work_container_of(ptr) };578 // SAFETY: This pointer comes from `Arc::into_raw` and we've been given back ownership.579 let boxed = unsafe { Box::from_raw(ptr) };580 // SAFETY: The box was already pinned when it was enqueued.581 let pinned = unsafe { Pin::new_unchecked(boxed) };582 583 T::run(pinned)584 }585}586 587unsafe impl<T, const ID: u64> RawWorkItem<ID> for Pin<Box<T>>588where589 T: WorkItem<ID, Pointer = Self>,590 T: HasWork<T, ID>,591{592 type EnqueueOutput = ();593 594 unsafe fn __enqueue<F>(self, queue_work_on: F) -> Self::EnqueueOutput595 where596 F: FnOnce(*mut bindings::work_struct) -> bool,597 {598 // SAFETY: We're not going to move `self` or any of its fields, so its okay to temporarily599 // remove the `Pin` wrapper.600 let boxed = unsafe { Pin::into_inner_unchecked(self) };601 let ptr = Box::into_raw(boxed);602 603 // SAFETY: Pointers into a `Box` point at a valid value.604 let work_ptr = unsafe { T::raw_get_work(ptr) };605 // SAFETY: `raw_get_work` returns a pointer to a valid value.606 let work_ptr = unsafe { Work::raw_get(work_ptr) };607 608 if !queue_work_on(work_ptr) {609 // SAFETY: This method requires exclusive ownership of the box, so it cannot be in a610 // workqueue.611 unsafe { ::core::hint::unreachable_unchecked() }612 }613 }614}615 616/// Returns the system work queue (`system_wq`).617///618/// It is the one used by `schedule[_delayed]_work[_on]()`. Multi-CPU multi-threaded. There are619/// users which expect relatively short queue flush time.620///621/// Callers shouldn't queue work items which can run for too long.622pub fn system() -> &'static Queue {623 // SAFETY: `system_wq` is a C global, always available.624 unsafe { Queue::from_raw(bindings::system_wq) }625}626 627/// Returns the system high-priority work queue (`system_highpri_wq`).628///629/// It is similar to the one returned by [`system`] but for work items which require higher630/// scheduling priority.631pub fn system_highpri() -> &'static Queue {632 // SAFETY: `system_highpri_wq` is a C global, always available.633 unsafe { Queue::from_raw(bindings::system_highpri_wq) }634}635 636/// Returns the system work queue for potentially long-running work items (`system_long_wq`).637///638/// It is similar to the one returned by [`system`] but may host long running work items. Queue639/// flushing might take relatively long.640pub fn system_long() -> &'static Queue {641 // SAFETY: `system_long_wq` is a C global, always available.642 unsafe { Queue::from_raw(bindings::system_long_wq) }643}644 645/// Returns the system unbound work queue (`system_unbound_wq`).646///647/// Workers are not bound to any specific CPU, not concurrency managed, and all queued work items648/// are executed immediately as long as `max_active` limit is not reached and resources are649/// available.650pub fn system_unbound() -> &'static Queue {651 // SAFETY: `system_unbound_wq` is a C global, always available.652 unsafe { Queue::from_raw(bindings::system_unbound_wq) }653}654 655/// Returns the system freezable work queue (`system_freezable_wq`).656///657/// It is equivalent to the one returned by [`system`] except that it's freezable.658///659/// A freezable workqueue participates in the freeze phase of the system suspend operations. Work660/// items on the workqueue are drained and no new work item starts execution until thawed.661pub fn system_freezable() -> &'static Queue {662 // SAFETY: `system_freezable_wq` is a C global, always available.663 unsafe { Queue::from_raw(bindings::system_freezable_wq) }664}665 666/// Returns the system power-efficient work queue (`system_power_efficient_wq`).667///668/// It is inclined towards saving power and is converted to "unbound" variants if the669/// `workqueue.power_efficient` kernel parameter is specified; otherwise, it is similar to the one670/// returned by [`system`].671pub fn system_power_efficient() -> &'static Queue {672 // SAFETY: `system_power_efficient_wq` is a C global, always available.673 unsafe { Queue::from_raw(bindings::system_power_efficient_wq) }674}675 676/// Returns the system freezable power-efficient work queue (`system_freezable_power_efficient_wq`).677///678/// It is similar to the one returned by [`system_power_efficient`] except that is freezable.679///680/// A freezable workqueue participates in the freeze phase of the system suspend operations. Work681/// items on the workqueue are drained and no new work item starts execution until thawed.682pub fn system_freezable_power_efficient() -> &'static Queue {683 // SAFETY: `system_freezable_power_efficient_wq` is a C global, always available.684 unsafe { Queue::from_raw(bindings::system_freezable_power_efficient_wq) }685}686