projects/linux·blob master · refs

312 lines · 8.0 KiB

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