kernel/
lib.rs

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#![feature(coerce_unsized)]
17#![feature(dispatch_from_dyn)]
18#![feature(inline_const)]
19#![feature(lint_reasons)]
20#![feature(unsize)]
21#![feature(used_with_arg)]
22
23// Ensure conditional compilation based on the kernel configuration works;
24// otherwise we may silently break things like initcall handling.
25#[cfg(not(CONFIG_RUST))]
26compile_error!("Missing kernel configuration for conditional compilation");
27
28// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate).
29extern crate self as kernel;
30
31pub use ffi;
32
33pub mod alloc;
34#[cfg(CONFIG_BLOCK)]
35pub mod block;
36mod build_assert;
37pub mod device;
38pub mod error;
39#[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]
40pub mod firmware;
41pub mod init;
42pub mod ioctl;
43#[cfg(CONFIG_KUNIT)]
44pub mod kunit;
45pub mod list;
46#[cfg(CONFIG_NET)]
47pub mod net;
48pub mod page;
49pub mod prelude;
50pub mod print;
51pub mod rbtree;
52pub mod sizes;
53mod static_assert;
54#[doc(hidden)]
55pub mod std_vendor;
56pub mod str;
57pub mod sync;
58pub mod task;
59pub mod time;
60pub mod types;
61pub mod uaccess;
62pub mod workqueue;
63
64#[doc(hidden)]
65pub use bindings;
66pub use macros;
67pub use uapi;
68
69#[doc(hidden)]
70pub use build_error::build_error;
71
72/// Prefix to appear before log messages printed from within the `kernel` crate.
73const __LOG_PREFIX: &[u8] = b"rust_kernel\0";
74
75/// The top level entrypoint to implementing a kernel module.
76///
77/// For any teardown or cleanup operations, your type may implement [`Drop`].
78pub trait Module: Sized + Sync + Send {
79    /// Called at module initialization time.
80    ///
81    /// Use this method to perform whatever setup or registration your module
82    /// should do.
83    ///
84    /// Equivalent to the `module_init` macro in the C API.
85    fn init(module: &'static ThisModule) -> error::Result<Self>;
86}
87
88/// Equivalent to `THIS_MODULE` in the C API.
89///
90/// C header: [`include/linux/init.h`](srctree/include/linux/init.h)
91pub struct ThisModule(*mut bindings::module);
92
93// SAFETY: `THIS_MODULE` may be used from all threads within a module.
94unsafe impl Sync for ThisModule {}
95
96impl ThisModule {
97    /// Creates a [`ThisModule`] given the `THIS_MODULE` pointer.
98    ///
99    /// # Safety
100    ///
101    /// The pointer must be equal to the right `THIS_MODULE`.
102    pub const unsafe fn from_ptr(ptr: *mut bindings::module) -> ThisModule {
103        ThisModule(ptr)
104    }
105
106    /// Access the raw pointer for this module.
107    ///
108    /// It is up to the user to use it correctly.
109    pub const fn as_ptr(&self) -> *mut bindings::module {
110        self.0
111    }
112}
113
114#[cfg(not(any(testlib, test)))]
115#[panic_handler]
116fn panic(info: &core::panic::PanicInfo<'_>) -> ! {
117    pr_emerg!("{}\n", info);
118    // SAFETY: FFI call.
119    unsafe { bindings::BUG() };
120}
121
122/// Produces a pointer to an object from a pointer to one of its fields.
123///
124/// # Safety
125///
126/// The pointer passed to this macro, and the pointer returned by this macro, must both be in
127/// bounds of the same allocation.
128///
129/// # Examples
130///
131/// ```
132/// # use kernel::container_of;
133/// struct Test {
134///     a: u64,
135///     b: u32,
136/// }
137///
138/// let test = Test { a: 10, b: 20 };
139/// let b_ptr = &test.b;
140/// // SAFETY: The pointer points at the `b` field of a `Test`, so the resulting pointer will be
141/// // in-bounds of the same allocation as `b_ptr`.
142/// let test_alias = unsafe { container_of!(b_ptr, Test, b) };
143/// assert!(core::ptr::eq(&test, test_alias));
144/// ```
145#[macro_export]
146macro_rules! container_of {
147    ($ptr:expr, $type:ty, $($f:tt)*) => {{
148        let ptr = $ptr as *const _ as *const u8;
149        let offset: usize = ::core::mem::offset_of!($type, $($f)*);
150        ptr.sub(offset) as *const $type
151    }}
152}
kernel/lib.rs

kernel/
lib.rs
