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))]
31 compile_error!("Missing kernel configuration for conditional compilation");
32
33 // Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate).
34 extern crate self as kernel;
35
36 pub use ffi;
37
38 pub mod alloc;
39 #[cfg(CONFIG_BLOCK)]
40 pub mod block;
41 #[doc(hidden)]
42 pub mod build_assert;
43 pub mod cred;
44 pub mod device;
45 pub mod device_id;
46 pub mod devres;
47 pub mod driver;
48 pub mod error;
49 pub mod faux;
50 #[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]
51 pub mod firmware;
52 pub mod fs;
53 pub mod init;
54 pub mod io;
55 pub mod ioctl;
56 pub mod jump_label;
57 #[cfg(CONFIG_KUNIT)]
58 pub mod kunit;
59 pub mod list;
60 pub mod miscdevice;
61 #[cfg(CONFIG_NET)]
62 pub mod net;
63 pub mod of;
64 pub mod page;
65 #[cfg(CONFIG_PCI)]
66 pub mod pci;
67 pub mod pid_namespace;
68 pub mod platform;
69 pub mod prelude;
70 pub mod print;
71 pub mod rbtree;
72 pub mod revocable;
73 pub mod security;
74 pub mod seq_file;
75 pub mod sizes;
76 mod static_assert;
77 #[doc(hidden)]
78 pub mod std_vendor;
79 pub mod str;
80 pub mod sync;
81 pub mod task;
82 pub mod time;
83 pub mod tracepoint;
84 pub mod transmute;
85 pub mod types;
86 pub mod uaccess;
87 pub mod workqueue;
88
89 #[doc(hidden)]
90 pub use bindings;
91 pub use macros;
92 pub use uapi;
93
94 /// Prefix to appear before log messages printed from within the `kernel` crate.
95 const __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`].
100 pub 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.
init(module: &'static ThisModule) -> error::Result<Self>107 fn init(module: &'static ThisModule) -> error::Result<Self>;
108 }
109
110 /// A module that is pinned and initialised in-place.
111 pub trait InPlaceModule: Sync + Send {
112 /// Creates an initialiser for the module.
113 ///
114 /// It is called when the module is loaded.
init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>115 fn init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>;
116 }
117
118 impl<T: Module> InPlaceModule for T {
init(module: &'static ThisModule) -> impl init::PinInit<Self, error::Error>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`].
134 pub 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)
142 pub struct ThisModule(*mut bindings::module);
143
144 // SAFETY: `THIS_MODULE` may be used from all threads within a module.
145 unsafe impl Sync for ThisModule {}
146
147 impl 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`.
from_ptr(ptr: *mut bindings::module) -> ThisModule153 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.
as_ptr(&self) -> *mut bindings::module160 pub const fn as_ptr(&self) -> *mut bindings::module {
161 self.0
162 }
163 }
164
165 #[cfg(not(any(testlib, test)))]
166 #[panic_handler]
panic(info: &core::panic::PanicInfo<'_>) -> !167 fn 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]
197 macro_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]
208 macro_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]
221 macro_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]
234 macro_rules! asm {
235 ($($asm:expr),* ; $($rest:tt)*) => {
236 ::core::arch::asm!( $($asm)*, $($rest)* )
237 };
238 }
239