149 lines · rust
1// SPDX-License-Identifier: GPL-2.02 3//! The `kernel` crate.4//!5//! This crate contains the kernel APIs that have been ported or wrapped for6//! 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. kernel9//! 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, then12//! do so first instead of bypassing this crate.13 14#![no_std]15#![feature(coerce_unsized)]16#![feature(dispatch_from_dyn)]17#![feature(new_uninit)]18#![feature(receiver_trait)]19#![feature(unsize)]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))]24compile_error!("Missing kernel configuration for conditional compilation");25 26// Allow proc-macros to refer to `::kernel` inside the `kernel` crate (this crate).27extern crate self as kernel;28 29pub mod alloc;30#[cfg(CONFIG_BLOCK)]31pub mod block;32mod build_assert;33pub mod device;34pub mod error;35#[cfg(CONFIG_RUST_FW_LOADER_ABSTRACTIONS)]36pub mod firmware;37pub mod init;38pub mod ioctl;39#[cfg(CONFIG_KUNIT)]40pub mod kunit;41pub mod list;42#[cfg(CONFIG_NET)]43pub mod net;44pub mod page;45pub mod prelude;46pub mod print;47pub mod rbtree;48pub mod sizes;49mod static_assert;50#[doc(hidden)]51pub mod std_vendor;52pub mod str;53pub mod sync;54pub mod task;55pub mod time;56pub mod types;57pub mod uaccess;58pub mod workqueue;59 60#[doc(hidden)]61pub use bindings;62pub use macros;63pub use uapi;64 65#[doc(hidden)]66pub use build_error::build_error;67 68/// Prefix to appear before log messages printed from within the `kernel` crate.69const __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`].74pub trait Module: Sized + Sync + Send {75 /// Called at module initialization time.76 ///77 /// Use this method to perform whatever setup or registration your module78 /// 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///86/// C header: [`include/linux/export.h`](srctree/include/linux/export.h)87pub struct ThisModule(*mut bindings::module);88 89// SAFETY: `THIS_MODULE` may be used from all threads within a module.90unsafe impl Sync for ThisModule {}91 92impl ThisModule {93 /// Creates a [`ThisModule`] given the `THIS_MODULE` pointer.94 ///95 /// # Safety96 ///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 }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.0107 }108}109 110#[cfg(not(any(testlib, test)))]111#[panic_handler]112fn panic(info: &core::panic::PanicInfo<'_>) -> ! {113 pr_emerg!("{}\n", info);114 // SAFETY: FFI call.115 unsafe { bindings::BUG() };116}117 118/// Produces a pointer to an object from a pointer to one of its fields.119///120/// # Safety121///122/// The pointer passed to this macro, and the pointer returned by this macro, must both be in123/// bounds of the same allocation.124///125/// # Examples126///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 be137/// // 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]142macro_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 $type147 }}148}149