projects/linux·blob v6.14 · refs

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