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