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