projects/linux·blob v6.15 · refs

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