mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-09-29 22:02:02 +00:00
7324b88975
The main challenge with defining `work_struct` fields is making sure
that the function pointer stored in the `work_struct` is appropriate for
the work item type it is embedded in. It needs to know the offset of the
`work_struct` field being used (even if there are several!) so that it
can do a `container_of`, and it needs to know the type of the work item
so that it can call into the right user-provided code. All of this needs
to happen in a way that provides a safe API to the user, so that users
of the workqueue cannot mix up the function pointers.
There are three important pieces that are relevant when doing this:
* The pointer type.
* The work item struct. This is what the pointer points at.
* The `work_struct` field. This is a field of the work item struct.
This patch introduces a separate trait for each piece. The pointer type
is given a `WorkItemPointer` trait, which pointer types need to
implement to be usable with the workqueue. This trait will be
implemented for `Arc` and `Box` in a later patch in this patchset.
Implementing this trait is unsafe because this is where the
`container_of` operation happens, but user-code will not need to
implement it themselves.
The work item struct should then implement the `WorkItem` trait. This
trait is where user-code specifies what they want to happen when a work
item is executed. It also specifies what the correct pointer type is.
Finally, to make the work item struct know the offset of its
`work_struct` field, we use a trait called `HasWork<T, ID>`. If a type
implements this trait, then the type declares that, at the given offset,
there is a field of type `Work<T, ID>`. The trait is marked unsafe
because the OFFSET constant must be correct, but we provide an
`impl_has_work!` macro that can safely implement `HasWork<T>` on a type.
The macro expands to something that only compiles if the specified field
really has the type `Work<T>`. It is used like this:
```
struct MyWorkItem {
work_field: Work<MyWorkItem, 1>,
}
impl_has_work! {
impl HasWork<MyWorkItem, 1> for MyWorkItem { self.work_field }
}
```
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.
Co-developed-by: Gary Guo <gary@garyguo.net>
Signed-off-by: Gary Guo <gary@garyguo.net>
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com>
Reviewed-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Tejun Heo <tj@kernel.org>
101 lines
2.7 KiB
Rust
101 lines
2.7 KiB
Rust
// SPDX-License-Identifier: GPL-2.0
|
|
|
|
//! The `kernel` crate.
|
|
//!
|
|
//! This crate contains the kernel APIs that have been ported or wrapped for
|
|
//! usage by Rust code in the kernel and is shared by all of them.
|
|
//!
|
|
//! In other words, all the rest of the Rust code in the kernel (e.g. kernel
|
|
//! modules written in Rust) depends on [`core`], [`alloc`] and this crate.
|
|
//!
|
|
//! If you need a kernel C API that is not ported or wrapped yet here, then
|
|
//! do so first instead of bypassing this crate.
|
|
|
|
#![no_std]
|
|
#![feature(allocator_api)]
|
|
#![feature(coerce_unsized)]
|
|
#![feature(dispatch_from_dyn)]
|
|
#![feature(new_uninit)]
|
|
#![feature(offset_of)]
|
|
#![feature(ptr_metadata)]
|
|
#![feature(receiver_trait)]
|
|
#![feature(unsize)]
|
|
|
|
// Ensure conditional compilation based on the kernel configuration works;
|
|
// otherwise we may silently break things like initcall handling.
|
|
#[cfg(not(CONFIG_RUST))]
|
|
compile_error!("Missing kernel configuration for conditional compilation");
|
|
|
|
// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate).
|
|
extern crate self as kernel;
|
|
|
|
#[cfg(not(test))]
|
|
#[cfg(not(testlib))]
|
|
mod allocator;
|
|
mod build_assert;
|
|
pub mod error;
|
|
pub mod init;
|
|
pub mod ioctl;
|
|
#[cfg(CONFIG_KUNIT)]
|
|
pub mod kunit;
|
|
pub mod prelude;
|
|
pub mod print;
|
|
mod static_assert;
|
|
#[doc(hidden)]
|
|
pub mod std_vendor;
|
|
pub mod str;
|
|
pub mod sync;
|
|
pub mod task;
|
|
pub mod types;
|
|
pub mod workqueue;
|
|
|
|
#[doc(hidden)]
|
|
pub use bindings;
|
|
pub use macros;
|
|
pub use uapi;
|
|
|
|
#[doc(hidden)]
|
|
pub use build_error::build_error;
|
|
|
|
/// Prefix to appear before log messages printed from within the `kernel` crate.
|
|
const __LOG_PREFIX: &[u8] = b"rust_kernel\0";
|
|
|
|
/// The top level entrypoint to implementing a kernel module.
|
|
///
|
|
/// For any teardown or cleanup operations, your type may implement [`Drop`].
|
|
pub trait Module: Sized + Sync {
|
|
/// Called at module initialization time.
|
|
///
|
|
/// Use this method to perform whatever setup or registration your module
|
|
/// should do.
|
|
///
|
|
/// Equivalent to the `module_init` macro in the C API.
|
|
fn init(module: &'static ThisModule) -> error::Result<Self>;
|
|
}
|
|
|
|
/// Equivalent to `THIS_MODULE` in the C API.
|
|
///
|
|
/// C header: `include/linux/export.h`
|
|
pub struct ThisModule(*mut bindings::module);
|
|
|
|
// SAFETY: `THIS_MODULE` may be used from all threads within a module.
|
|
unsafe impl Sync for ThisModule {}
|
|
|
|
impl ThisModule {
|
|
/// Creates a [`ThisModule`] given the `THIS_MODULE` pointer.
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// The pointer must be equal to the right `THIS_MODULE`.
|
|
pub const unsafe fn from_ptr(ptr: *mut bindings::module) -> ThisModule {
|
|
ThisModule(ptr)
|
|
}
|
|
}
|
|
|
|
#[cfg(not(any(testlib, test)))]
|
|
#[panic_handler]
|
|
fn panic(info: &core::panic::PanicInfo<'_>) -> ! {
|
|
pr_emerg!("{}\n", info);
|
|
// SAFETY: FFI call.
|
|
unsafe { bindings::BUG() };
|
|
}
|