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