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 //
16 // Please see https://github.com/Rust-for-Linux/linux/issues/2 for details on
17 // the unstable features in use.
18 //
19 // Stable since Rust 1.89.0.
20 #![feature(generic_arg_infer)]
21 //
22 // Expected to become stable.
23 #![feature(arbitrary_self_types)]
24 #![feature(derive_coerce_pointee)]
25 //
26 // To be determined.
27 #![feature(used_with_arg)]
28 //
29 // `feature(file_with_nul)` is stable since Rust 1.92.0. Before Rust 1.89.0, it did not exist, so
30 // enable it conditionally.
31 #![cfg_attr(CONFIG_RUSTC_HAS_FILE_WITH_NUL, feature(file_with_nul))]
32
33 // Ensure conditional compilation based on the kernel configuration works;
34 // otherwise we may silently break things like initcall handling.
35 #[cfg(not(CONFIG_RUST))]
36 compile_error!("Missing kernel configuration for conditional compilation");
37
38 // Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate).
39 extern crate self as kernel;
40
41 pub use ffi;
42
43 pub mod acpi;
44 pub mod alloc;
45 #[cfg(CONFIG_AUXILIARY_BUS)]
46 pub mod auxiliary;
47 pub mod bitmap;
48 pub mod bits;
49 #[cfg(CONFIG_BLOCK)]
50 pub mod block;
51 pub mod bug;
52 pub mod build_assert;
53 pub mod clk;
54 #[cfg(CONFIG_CONFIGFS_FS)]
55 pub mod configfs;
56 pub mod cpu;
57 #[cfg(CONFIG_CPU_FREQ)]
58 pub mod cpufreq;
59 pub mod cpumask;
60 pub mod cred;
61 pub mod debugfs;
62 pub mod device;
63 pub mod device_id;
64 pub mod devres;
65 pub mod dma;
66 pub mod driver;
67 #[cfg(CONFIG_DRM = "y")]
68 pub mod drm;
69 pub mod error;
70 pub mod faux;
71 #[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]
72 pub mod firmware;
73 pub mod fmt;
74 pub mod fs;
75 #[cfg(CONFIG_GPU_BUDDY = "y")]
76 pub mod gpu;
77 #[cfg(CONFIG_I2C = "y")]
78 pub mod i2c;
79 pub mod id_pool;
80 #[doc(hidden)]
81 pub mod impl_flags;
82 pub mod init;
83 pub mod interop;
84 pub mod io;
85 pub mod ioctl;
86 pub mod iommu;
87 pub mod iov;
88 pub mod irq;
89 pub mod jump_label;
90 #[cfg(CONFIG_KUNIT)]
91 pub mod kunit;
92 pub mod list;
93 pub mod maple_tree;
94 pub mod miscdevice;
95 pub mod mm;
96 pub mod module_param;
97 #[cfg(CONFIG_NET)]
98 pub mod net;
99 pub mod num;
100 pub mod of;
101 #[cfg(CONFIG_PM_OPP)]
102 pub mod opp;
103 pub mod page;
104 #[cfg(CONFIG_PCI)]
105 pub mod pci;
106 pub mod pid_namespace;
107 pub mod platform;
108 pub mod prelude;
109 pub mod print;
110 pub mod processor;
111 pub mod ptr;
112 #[cfg(CONFIG_RUST_PWM_ABSTRACTIONS)]
113 pub mod pwm;
114 pub mod rbtree;
115 pub mod regulator;
116 pub mod revocable;
117 pub mod safety;
118 pub mod scatterlist;
119 pub mod security;
120 pub mod seq_file;
121 pub mod sizes;
122 #[cfg(CONFIG_SOC_BUS)]
123 pub mod soc;
124 #[doc(hidden)]
125 pub mod std_vendor;
126 pub mod str;
127 pub mod sync;
128 pub mod task;
129 pub mod time;
130 pub mod tracepoint;
131 pub mod transmute;
132 pub mod types;
133 pub mod uaccess;
134 #[cfg(CONFIG_USB = "y")]
135 pub mod usb;
136 pub mod workqueue;
137 pub mod xarray;
138
139 #[doc(hidden)]
140 pub use bindings;
141 pub use macros;
142 pub use uapi;
143
144 /// Prefix to appear before log messages printed from within the `kernel` crate.
145 const __LOG_PREFIX: &[u8] = b"rust_kernel\0";
146
147 /// The top level entrypoint to implementing a kernel module.
148 ///
149 /// For any teardown or cleanup operations, your type may implement [`Drop`].
150 pub trait Module: Sized + Sync + Send {
151 /// Called at module initialization time.
152 ///
153 /// Use this method to perform whatever setup or registration your module
154 /// should do.
155 ///
156 /// Equivalent to the `module_init` macro in the C API.
init(module: &'static ThisModule) -> error::Result<Self>157 fn init(module: &'static ThisModule) -> error::Result<Self>;
158 }
159
160 /// A module that is pinned and initialised in-place.
161 pub trait InPlaceModule: Sync + Send {
162 /// Creates an initialiser for the module.
163 ///
164 /// It is called when the module is loaded.
init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, error::Error>165 fn init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, error::Error>;
166 }
167
168 impl<T: Module> InPlaceModule for T {
init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, error::Error>169 fn init(module: &'static ThisModule) -> impl pin_init::PinInit<Self, error::Error> {
170 let initer = move |slot: *mut Self| {
171 let m = <Self as Module>::init(module)?;
172
173 // SAFETY: `slot` is valid for write per the contract with `pin_init_from_closure`.
174 unsafe { slot.write(m) };
175 Ok(())
176 };
177
178 // SAFETY: On success, `initer` always fully initialises an instance of `Self`.
179 unsafe { pin_init::pin_init_from_closure(initer) }
180 }
181 }
182
183 /// Metadata attached to a [`Module`] or [`InPlaceModule`].
184 pub trait ModuleMetadata {
185 /// The name of the module as specified in the `module!` macro.
186 const NAME: &'static crate::str::CStr;
187 }
188
189 /// Equivalent to `THIS_MODULE` in the C API.
190 ///
191 /// C header: [`include/linux/init.h`](srctree/include/linux/init.h)
192 pub struct ThisModule(*mut bindings::module);
193
194 // SAFETY: `THIS_MODULE` may be used from all threads within a module.
195 unsafe impl Sync for ThisModule {}
196
197 impl ThisModule {
198 /// Creates a [`ThisModule`] given the `THIS_MODULE` pointer.
199 ///
200 /// # Safety
201 ///
202 /// The pointer must be equal to the right `THIS_MODULE`.
from_ptr(ptr: *mut bindings::module) -> ThisModule203 pub const unsafe fn from_ptr(ptr: *mut bindings::module) -> ThisModule {
204 ThisModule(ptr)
205 }
206
207 /// Access the raw pointer for this module.
208 ///
209 /// It is up to the user to use it correctly.
as_ptr(&self) -> *mut bindings::module210 pub const fn as_ptr(&self) -> *mut bindings::module {
211 self.0
212 }
213 }
214
215 #[cfg(not(testlib))]
216 #[panic_handler]
panic(info: &core::panic::PanicInfo<'_>) -> !217 fn panic(info: &core::panic::PanicInfo<'_>) -> ! {
218 pr_emerg!("{}\n", info);
219 // SAFETY: FFI call.
220 unsafe { bindings::BUG() };
221 }
222
223 /// Produces a pointer to an object from a pointer to one of its fields.
224 ///
225 /// If you encounter a type mismatch due to the [`Opaque`] type, then use [`Opaque::cast_into`] or
226 /// [`Opaque::cast_from`] to resolve the mismatch.
227 ///
228 /// [`Opaque`]: crate::types::Opaque
229 /// [`Opaque::cast_into`]: crate::types::Opaque::cast_into
230 /// [`Opaque::cast_from`]: crate::types::Opaque::cast_from
231 ///
232 /// # Safety
233 ///
234 /// The pointer passed to this macro, and the pointer returned by this macro, must both be in
235 /// bounds of the same allocation.
236 ///
237 /// # Examples
238 ///
239 /// ```
240 /// # use kernel::container_of;
241 /// struct Test {
242 /// a: u64,
243 /// b: u32,
244 /// }
245 ///
246 /// let test = Test { a: 10, b: 20 };
247 /// let b_ptr: *const _ = &test.b;
248 /// // SAFETY: The pointer points at the `b` field of a `Test`, so the resulting pointer will be
249 /// // in-bounds of the same allocation as `b_ptr`.
250 /// let test_alias = unsafe { container_of!(b_ptr, Test, b) };
251 /// assert!(core::ptr::eq(&test, test_alias));
252 /// ```
253 #[macro_export]
254 macro_rules! container_of {
255 ($field_ptr:expr, $Container:ty, $($fields:tt)*) => {{
256 let offset: usize = ::core::mem::offset_of!($Container, $($fields)*);
257 let field_ptr = $field_ptr;
258 let container_ptr = field_ptr.byte_sub(offset).cast::<$Container>();
259 $crate::assert_same_type(field_ptr, (&raw const (*container_ptr).$($fields)*).cast_mut());
260 container_ptr
261 }}
262 }
263
264 /// Helper for [`container_of!`].
265 #[doc(hidden)]
assert_same_type<T>(_: T, _: T)266 pub fn assert_same_type<T>(_: T, _: T) {}
267
268 /// Helper for `.rs.S` files.
269 #[doc(hidden)]
270 #[macro_export]
271 macro_rules! concat_literals {
272 ($( $asm:literal )* ) => {
273 ::core::concat!($($asm),*)
274 };
275 }
276
277 /// Wrapper around `asm!` configured for use in the kernel.
278 ///
279 /// Uses a semicolon to avoid parsing ambiguities, even though this does not match native `asm!`
280 /// syntax.
281 // For x86, `asm!` uses intel syntax by default, but we want to use at&t syntax in the kernel.
282 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
283 #[macro_export]
284 macro_rules! asm {
285 ($($asm:expr),* ; $($rest:tt)*) => {
286 ::core::arch::asm!( $($asm)*, options(att_syntax), $($rest)* )
287 };
288 }
289
290 /// Wrapper around `asm!` configured for use in the kernel.
291 ///
292 /// Uses a semicolon to avoid parsing ambiguities, even though this does not match native `asm!`
293 /// syntax.
294 // For non-x86 arches we just pass through to `asm!`.
295 #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
296 #[macro_export]
297 macro_rules! asm {
298 ($($asm:expr),* ; $($rest:tt)*) => {
299 ::core::arch::asm!( $($asm)*, $($rest)* )
300 };
301 }
302
303 /// Gets the C string file name of a [`Location`].
304 ///
305 /// If `Location::file_as_c_str()` is not available, returns a string that warns about it.
306 ///
307 /// [`Location`]: core::panic::Location
308 ///
309 /// # Examples
310 ///
311 /// ```
312 /// # use kernel::file_from_location;
313 ///
314 /// #[track_caller]
315 /// fn foo() {
316 /// let caller = core::panic::Location::caller();
317 ///
318 /// // Output:
319 /// // - A path like "rust/kernel/example.rs" if `file_as_c_str()` is available.
320 /// // - "<Location::file_as_c_str() not supported>" otherwise.
321 /// let caller_file = file_from_location(caller);
322 ///
323 /// // Prints out the message with caller's file name.
324 /// pr_info!("foo() called in file {caller_file:?}\n");
325 ///
326 /// # if cfg!(CONFIG_RUSTC_HAS_FILE_WITH_NUL) {
327 /// # assert_eq!(Ok(caller.file()), caller_file.to_str());
328 /// # }
329 /// }
330 ///
331 /// # foo();
332 /// ```
333 #[inline]
file_from_location<'a>(loc: &'a core::panic::Location<'a>) -> &'a core::ffi::CStr334 pub fn file_from_location<'a>(loc: &'a core::panic::Location<'a>) -> &'a core::ffi::CStr {
335 #[cfg(CONFIG_RUSTC_HAS_FILE_AS_C_STR)]
336 {
337 loc.file_as_c_str()
338 }
339
340 #[cfg(all(CONFIG_RUSTC_HAS_FILE_WITH_NUL, not(CONFIG_RUSTC_HAS_FILE_AS_C_STR)))]
341 {
342 loc.file_with_nul()
343 }
344
345 #[cfg(not(CONFIG_RUSTC_HAS_FILE_WITH_NUL))]
346 {
347 let _ = loc;
348 c"<Location::file_as_c_str() not supported>"
349 }
350 }
351