projects/linux·blob v6.16 · refs

279 lines · 7.8 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! The `kernel` crate.
4//!
5//! This crate contains the kernel APIs that have been ported or wrapped for
6//! usage by Rust code in the kernel and is shared by all of them.
7//!
8//! In other words, all the rest of the Rust code in the kernel (e.g. kernel
9//! modules written in Rust) depends on [`core`] and this crate.
10//!
11//! If you need a kernel C API that is not ported or wrapped yet here, then
12//! do so first instead of bypassing this crate.
13
14#![no_std]
15//
16// Please see https://github.com/Rust-for-Linux/linux/issues/2 for details on
17// the unstable features in use.
18//
19// Stable since Rust 1.79.0.
20#![feature(inline_const)]
21//
22// Stable since Rust 1.81.0.
23#![feature(lint_reasons)]
24//
25// Stable since Rust 1.82.0.
26#![feature(raw_ref_op)]
27//
28// Stable since Rust 1.83.0.
29#![feature(const_maybe_uninit_as_mut_ptr)]
30#![feature(const_mut_refs)]
31#![feature(const_ptr_write)]
32#![feature(const_refs_to_cell)]
33//
34// Expected to become stable.
35#![feature(arbitrary_self_types)]
36//
37// To be determined.
38#![feature(used_with_arg)]
39//
40// `feature(derive_coerce_pointee)` is expected to become stable. Before Rust
41// 1.84.0, it did not exist, so enable the predecessor features.
42#![cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, feature(derive_coerce_pointee))]
43#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(coerce_unsized))]
44#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(dispatch_from_dyn))]
45#![cfg_attr(not(CONFIG_RUSTC_HAS_COERCE_POINTEE), feature(unsize))]
46
47// Ensure conditional compilation based on the kernel configuration works;
48// otherwise we may silently break things like initcall handling.
49#[cfg(not(CONFIG_RUST))]
50compile_error!("Missing kernel configuration for conditional compilation");
51
52// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate).
53extern crate self as kernel;
54
55pub use ffi;
56
57pub mod alloc;
58#[cfg(CONFIG_AUXILIARY_BUS)]
59pub mod auxiliary;
60#[cfg(CONFIG_BLOCK)]
61pub mod block;
62#[doc(hidden)]
63pub mod build_assert;
64pub mod clk;
65#[cfg(CONFIG_CONFIGFS_FS)]
66pub mod configfs;
67pub mod cpu;
68#[cfg(CONFIG_CPU_FREQ)]
69pub mod cpufreq;
70pub mod cpumask;
71pub mod cred;
72pub mod device;
73pub mod device_id;
74pub mod devres;
75pub mod dma;
76pub mod driver;
77#[cfg(CONFIG_DRM = "y")]
78pub mod drm;
79pub mod error;
80pub mod faux;
81#[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]
82pub mod firmware;
83pub mod fs;
84pub mod init;
85pub mod io;
86pub mod ioctl;
87pub mod jump_label;
88#[cfg(CONFIG_KUNIT)]
89pub mod kunit;
90pub mod list;
91pub mod miscdevice;
92pub mod mm;
93#[cfg(CONFIG_NET)]
94pub mod net;
95pub mod of;
96#[cfg(CONFIG_PM_OPP)]
97pub mod opp;
98pub mod page;
99#[cfg(CONFIG_PCI)]
100pub mod pci;
101pub mod pid_namespace;
102pub mod platform;
103pub mod prelude;
104pub mod print;
105pub mod rbtree;
106pub mod revocable;
107pub mod security;
108pub mod seq_file;
109pub mod sizes;
110mod static_assert;
111#[doc(hidden)]
112pub mod std_vendor;
113pub mod str;
114pub mod sync;
115pub mod task;
116pub mod time;
117pub mod tracepoint;
118pub mod transmute;
119pub mod types;
120pub mod uaccess;
121pub mod workqueue;
122pub mod xarray;
123
124#[doc(hidden)]
125pub use bindings;
126pub use macros;
127pub use uapi;
128
129/// Prefix to appear before log messages printed from within the `kernel` crate.
130const __LOG_PREFIX: &[u8] = b"rust_kernel\0";
131
132/// The top level entrypoint to implementing a kernel module.
133///
134/// For any teardown or cleanup operations, your type may implement [`Drop`].
135pub trait Module: Sized + Sync + Send {
136 /// Called at module initialization time.
137 ///
138 /// Use this method to perform whatever setup or registration your module
139 /// should do.
140 ///
141 /// Equivalent to the `module_init` macro in the C API.
142 fn init(module: &'static ThisModule) -> error::Result<Self>;
143}
144
145/// A module that is pinned and initialised in-place.
146pub trait InPlaceModule: Sync + Send {
147 /// Creates an initialiser for the module.
148 ///
149 /// It is called when the module is loaded.
150 fn init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, error::Error>;
151}
152
153impl<T: Module> InPlaceModule for T {
154 fn init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, error::Error> {
155 let initer = move |slot: *mut Self| {
156 let m = <Self as Module>::init(module)?;
157
158 // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
159 unsafe { slot.write(m) };
160 Ok(())
161 };
162
163 // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
164 unsafe { pin_init::pin_init_from_closure(initer) }
165 }
166}
167
168/// Metadata attached to a [`Module`] or [`InPlaceModule`].
169pub trait ModuleMetadata {
170 /// The name of the module as specified in the `module!` macro.
171 const NAME: &'static crate::str::CStr;
172}
173
174/// Equivalent to `THIS_MODULE` in the C API.
175///
176/// C header: [`include/linux/init.h`](srctree/include/linux/init.h)
177pub struct ThisModule(*mut bindings::module);
178
179// SAFETY: `THIS_MODULE` may be used from all threads within a module.
180unsafe impl Sync for ThisModule {}
181
182impl ThisModule {
183 /// Creates a [`ThisModule`] given the `THIS_MODULE` pointer.
184 ///
185 /// # Safety
186 ///
187 /// The pointer must be equal to the right `THIS_MODULE`.
188 pub const unsafe fn from_ptr(ptr: *mut bindings::module) -> ThisModule {
189 ThisModule(ptr)
190 }
191
192 /// Access the raw pointer for this module.
193 ///
194 /// It is up to the user to use it correctly.
195 pub const fn as_ptr(&self) -> *mut bindings::module {
196 self.0
197 }
198}
199
200#[cfg(not(any(testlib, test)))]
201#[panic_handler]
202fn panic(info: &core::panic::PanicInfo<'_>) -> ! {
203 pr_emerg!("{}\n", info);
204 // SAFETY: FFI call.
205 unsafe { bindings::BUG() };
206}
207
208/// Produces a pointer to an object from a pointer to one of its fields.
209///
210/// # Safety
211///
212/// The pointer passed to this macro, and the pointer returned by this macro, must both be in
213/// bounds of the same allocation.
214///
215/// # Examples
216///
217/// ```
218/// # use kernel::container_of;
219/// struct Test {
220/// a: u64,
221/// b: u32,
222/// }
223///
224/// let test = Test { a: 10, b: 20 };
225/// let b_ptr: *const _ = &test.b;
226/// // SAFETY: The pointer points at the `b` field of a `Test`, so the resulting pointer will be
227/// // in-bounds of the same allocation as `b_ptr`.
228/// let test_alias = unsafe { container_of!(b_ptr, Test, b) };
229/// assert!(core::ptr::eq(&test, test_alias));
230/// ```
231#[macro_export]
232macro_rules! container_of {
233 ($field_ptr:expr, $Container:ty, $($fields:tt)*) => {{
234 let offset: usize = ::core::mem::offset_of!($Container, $($fields)*);
235 let field_ptr = $field_ptr;
236 let container_ptr = field_ptr.byte_sub(offset).cast::<$Container>();
237 $crate::assert_same_type(field_ptr, (&raw const (*container_ptr).$($fields)*).cast_mut());
238 container_ptr
239 }}
240}
241
242/// Helper for [`container_of!`].
243#[doc(hidden)]
244pub fn assert_same_type<T>(_: T, _: T) {}
245
246/// Helper for `.rs.S` files.
247#[doc(hidden)]
248#[macro_export]
249macro_rules! concat_literals {
250 ($( $asm:literal )* ) => {
251 ::core::concat!($($asm),*)
252 };
253}
254
255/// Wrapper around `asm!` configured for use in the kernel.
256///
257/// Uses a semicolon to avoid parsing ambiguities, even though this does not match native `asm!`
258/// syntax.
259// For x86, `asm!` uses intel syntax by default, but we want to use at&t syntax in the kernel.
260#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
261#[macro_export]
262macro_rules! asm {
263 ($($asm:expr),* ; $($rest:tt)*) => {
264 ::core::arch::asm!( $($asm)*, options(att_syntax), $($rest)* )
265 };
266}
267
268/// Wrapper around `asm!` configured for use in the kernel.
269///
270/// Uses a semicolon to avoid parsing ambiguities, even though this does not match native `asm!`
271/// syntax.
272// For non-x86 arches we just pass through to `asm!`.
273#[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
274#[macro_export]
275macro_rules! asm {
276 ($($asm:expr),* ; $($rest:tt)*) => {
277 ::core::arch::asm!( $($asm)*, $($rest)* )
278 };
279}