kernel/
lib.rs

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}
kernel/lib.rs

kernel/
lib.rs
