Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
1// SPDX-License-Identifier: GPL-2.0
2
3//! Crate for all kernel procedural macros.
4
5#[macro_use]
6mod quote;
7mod concat_idents;
8mod helpers;
9mod module;
10mod paste;
11mod pin_data;
12mod pinned_drop;
13mod vtable;
14mod zeroable;
15
16use proc_macro::TokenStream;
17
18/// Declares a kernel module.
19///
20/// The `type` argument should be a type which implements the [`Module`]
21/// trait. Also accepts various forms of kernel metadata.
22///
23/// C header: [`include/linux/moduleparam.h`](srctree/include/linux/moduleparam.h)
24///
25/// [`Module`]: ../kernel/trait.Module.html
26///
27/// # Examples
28///
29/// ```ignore
30/// use kernel::prelude::*;
31///
32/// module!{
33/// type: MyModule,
34/// name: "my_kernel_module",
35/// author: "Rust for Linux Contributors",
36/// description: "My very own kernel module!",
37/// license: "GPL",
38/// alias: ["alternate_module_name"],
39/// }
40///
41/// struct MyModule;
42///
43/// impl kernel::Module for MyModule {
44/// fn init() -> Result<Self> {
45/// // If the parameter is writeable, then the kparam lock must be
46/// // taken to read the parameter:
47/// {
48/// let lock = THIS_MODULE.kernel_param_lock();
49/// pr_info!("i32 param is: {}\n", writeable_i32.read(&lock));
50/// }
51/// // If the parameter is read only, it can be read without locking
52/// // the kernel parameters:
53/// pr_info!("i32 param is: {}\n", my_i32.read());
54/// Ok(Self)
55/// }
56/// }
57/// ```
58///
59/// ## Firmware
60///
61/// The following example shows how to declare a kernel module that needs
62/// to load binary firmware files. You need to specify the file names of
63/// the firmware in the `firmware` field. The information is embedded
64/// in the `modinfo` section of the kernel module. For example, a tool to
65/// build an initramfs uses this information to put the firmware files into
66/// the initramfs image.
67///
68/// ```ignore
69/// use kernel::prelude::*;
70///
71/// module!{
72/// type: MyDeviceDriverModule,
73/// name: "my_device_driver_module",
74/// author: "Rust for Linux Contributors",
75/// description: "My device driver requires firmware",
76/// license: "GPL",
77/// firmware: ["my_device_firmware1.bin", "my_device_firmware2.bin"],
78/// }
79///
80/// struct MyDeviceDriverModule;
81///
82/// impl kernel::Module for MyDeviceDriverModule {
83/// fn init() -> Result<Self> {
84/// Ok(Self)
85/// }
86/// }
87/// ```
88///
89/// # Supported argument types
90/// - `type`: type which implements the [`Module`] trait (required).
91/// - `name`: ASCII string literal of the name of the kernel module (required).
92/// - `author`: string literal of the author of the kernel module.
93/// - `description`: string literal of the description of the kernel module.
94/// - `license`: ASCII string literal of the license of the kernel module (required).
95/// - `alias`: array of ASCII string literals of the alias names of the kernel module.
96/// - `firmware`: array of ASCII string literals of the firmware files of
97/// the kernel module.
98#[proc_macro]
99pub fn module(ts: TokenStream) -> TokenStream {
100 module::module(ts)
101}
102
103/// Declares or implements a vtable trait.
104///
105/// Linux's use of pure vtables is very close to Rust traits, but they differ
106/// in how unimplemented functions are represented. In Rust, traits can provide
107/// default implementation for all non-required methods (and the default
108/// implementation could just return `Error::EINVAL`); Linux typically use C
109/// `NULL` pointers to represent these functions.
110///
111/// This attribute closes that gap. A trait can be annotated with the
112/// `#[vtable]` attribute. Implementers of the trait will then also have to
113/// annotate the trait with `#[vtable]`. This attribute generates a `HAS_*`
114/// associated constant bool for each method in the trait that is set to true if
115/// the implementer has overridden the associated method.
116///
117/// For a trait method to be optional, it must have a default implementation.
118/// This is also the case for traits annotated with `#[vtable]`, but in this
119/// case the default implementation will never be executed. The reason for this
120/// is that the functions will be called through function pointers installed in
121/// C side vtables. When an optional method is not implemented on a `#[vtable]`
122/// trait, a NULL entry is installed in the vtable. Thus the default
123/// implementation is never called. Since these traits are not designed to be
124/// used on the Rust side, it should not be possible to call the default
125/// implementation. This is done to ensure that we call the vtable methods
126/// through the C vtable, and not through the Rust vtable. Therefore, the
127/// default implementation should call `kernel::build_error`, which prevents
128/// calls to this function at compile time:
129///
130/// ```compile_fail
131/// # use kernel::error::VTABLE_DEFAULT_ERROR;
132/// kernel::build_error(VTABLE_DEFAULT_ERROR)
133/// ```
134///
135/// Note that you might need to import [`kernel::error::VTABLE_DEFAULT_ERROR`].
136///
137/// This macro should not be used when all functions are required.
138///
139/// # Examples
140///
141/// ```ignore
142/// use kernel::error::VTABLE_DEFAULT_ERROR;
143/// use kernel::prelude::*;
144///
145/// // Declares a `#[vtable]` trait
146/// #[vtable]
147/// pub trait Operations: Send + Sync + Sized {
148/// fn foo(&self) -> Result<()> {
149/// kernel::build_error(VTABLE_DEFAULT_ERROR)
150/// }
151///
152/// fn bar(&self) -> Result<()> {
153/// kernel::build_error(VTABLE_DEFAULT_ERROR)
154/// }
155/// }
156///
157/// struct Foo;
158///
159/// // Implements the `#[vtable]` trait
160/// #[vtable]
161/// impl Operations for Foo {
162/// fn foo(&self) -> Result<()> {
163/// # Err(EINVAL)
164/// // ...
165/// }
166/// }
167///
168/// assert_eq!(<Foo as Operations>::HAS_FOO, true);
169/// assert_eq!(<Foo as Operations>::HAS_BAR, false);
170/// ```
171///
172/// [`kernel::error::VTABLE_DEFAULT_ERROR`]: ../kernel/error/constant.VTABLE_DEFAULT_ERROR.html
173#[proc_macro_attribute]
174pub fn vtable(attr: TokenStream, ts: TokenStream) -> TokenStream {
175 vtable::vtable(attr, ts)
176}
177
178/// Concatenate two identifiers.
179///
180/// This is useful in macros that need to declare or reference items with names
181/// starting with a fixed prefix and ending in a user specified name. The resulting
182/// identifier has the span of the second argument.
183///
184/// # Examples
185///
186/// ```ignore
187/// use kernel::macro::concat_idents;
188///
189/// macro_rules! pub_no_prefix {
190/// ($prefix:ident, $($newname:ident),+) => {
191/// $(pub(crate) const $newname: u32 = kernel::macros::concat_idents!($prefix, $newname);)+
192/// };
193/// }
194///
195/// pub_no_prefix!(
196/// binder_driver_return_protocol_,
197/// BR_OK,
198/// BR_ERROR,
199/// BR_TRANSACTION,
200/// BR_REPLY,
201/// BR_DEAD_REPLY,
202/// BR_TRANSACTION_COMPLETE,
203/// BR_INCREFS,
204/// BR_ACQUIRE,
205/// BR_RELEASE,
206/// BR_DECREFS,
207/// BR_NOOP,
208/// BR_SPAWN_LOOPER,
209/// BR_DEAD_BINDER,
210/// BR_CLEAR_DEATH_NOTIFICATION_DONE,
211/// BR_FAILED_REPLY
212/// );
213///
214/// assert_eq!(BR_OK, binder_driver_return_protocol_BR_OK);
215/// ```
216#[proc_macro]
217pub fn concat_idents(ts: TokenStream) -> TokenStream {
218 concat_idents::concat_idents(ts)
219}
220
221/// Used to specify the pinning information of the fields of a struct.
222///
223/// This is somewhat similar in purpose as
224/// [pin-project-lite](https://crates.io/crates/pin-project-lite).
225/// Place this macro on a struct definition and then `#[pin]` in front of the attributes of each
226/// field you want to structurally pin.
227///
228/// This macro enables the use of the [`pin_init!`] macro. When pin-initializing a `struct`,
229/// then `#[pin]` directs the type of initializer that is required.
230///
231/// If your `struct` implements `Drop`, then you need to add `PinnedDrop` as arguments to this
232/// macro, and change your `Drop` implementation to `PinnedDrop` annotated with
233/// `#[`[`macro@pinned_drop`]`]`, since dropping pinned values requires extra care.
234///
235/// # Examples
236///
237/// ```rust,ignore
238/// #[pin_data]
239/// struct DriverData {
240/// #[pin]
241/// queue: Mutex<Vec<Command>>,
242/// buf: Box<[u8; 1024 * 1024]>,
243/// }
244/// ```
245///
246/// ```rust,ignore
247/// #[pin_data(PinnedDrop)]
248/// struct DriverData {
249/// #[pin]
250/// queue: Mutex<Vec<Command>>,
251/// buf: Box<[u8; 1024 * 1024]>,
252/// raw_info: *mut Info,
253/// }
254///
255/// #[pinned_drop]
256/// impl PinnedDrop for DriverData {
257/// fn drop(self: Pin<&mut Self>) {
258/// unsafe { bindings::destroy_info(self.raw_info) };
259/// }
260/// }
261/// ```
262///
263/// [`pin_init!`]: ../kernel/macro.pin_init.html
264// ^ cannot use direct link, since `kernel` is not a dependency of `macros`.
265#[proc_macro_attribute]
266pub fn pin_data(inner: TokenStream, item: TokenStream) -> TokenStream {
267 pin_data::pin_data(inner, item)
268}
269
270/// Used to implement `PinnedDrop` safely.
271///
272/// Only works on structs that are annotated via `#[`[`macro@pin_data`]`]`.
273///
274/// # Examples
275///
276/// ```rust,ignore
277/// #[pin_data(PinnedDrop)]
278/// struct DriverData {
279/// #[pin]
280/// queue: Mutex<Vec<Command>>,
281/// buf: Box<[u8; 1024 * 1024]>,
282/// raw_info: *mut Info,
283/// }
284///
285/// #[pinned_drop]
286/// impl PinnedDrop for DriverData {
287/// fn drop(self: Pin<&mut Self>) {
288/// unsafe { bindings::destroy_info(self.raw_info) };
289/// }
290/// }
291/// ```
292#[proc_macro_attribute]
293pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
294 pinned_drop::pinned_drop(args, input)
295}
296
297/// Paste identifiers together.
298///
299/// Within the `paste!` macro, identifiers inside `[<` and `>]` are concatenated together to form a
300/// single identifier.
301///
302/// This is similar to the [`paste`] crate, but with pasting feature limited to identifiers and
303/// literals (lifetimes and documentation strings are not supported). There is a difference in
304/// supported modifiers as well.
305///
306/// # Example
307///
308/// ```ignore
309/// use kernel::macro::paste;
310///
311/// macro_rules! pub_no_prefix {
312/// ($prefix:ident, $($newname:ident),+) => {
313/// paste! {
314/// $(pub(crate) const $newname: u32 = [<$prefix $newname>];)+
315/// }
316/// };
317/// }
318///
319/// pub_no_prefix!(
320/// binder_driver_return_protocol_,
321/// BR_OK,
322/// BR_ERROR,
323/// BR_TRANSACTION,
324/// BR_REPLY,
325/// BR_DEAD_REPLY,
326/// BR_TRANSACTION_COMPLETE,
327/// BR_INCREFS,
328/// BR_ACQUIRE,
329/// BR_RELEASE,
330/// BR_DECREFS,
331/// BR_NOOP,
332/// BR_SPAWN_LOOPER,
333/// BR_DEAD_BINDER,
334/// BR_CLEAR_DEATH_NOTIFICATION_DONE,
335/// BR_FAILED_REPLY
336/// );
337///
338/// assert_eq!(BR_OK, binder_driver_return_protocol_BR_OK);
339/// ```
340///
341/// # Modifiers
342///
343/// For each identifier, it is possible to attach one or multiple modifiers to
344/// it.
345///
346/// Currently supported modifiers are:
347/// * `span`: change the span of concatenated identifier to the span of the specified token. By
348/// default the span of the `[< >]` group is used.
349/// * `lower`: change the identifier to lower case.
350/// * `upper`: change the identifier to upper case.
351///
352/// ```ignore
353/// use kernel::macro::paste;
354///
355/// macro_rules! pub_no_prefix {
356/// ($prefix:ident, $($newname:ident),+) => {
357/// kernel::macros::paste! {
358/// $(pub(crate) const fn [<$newname:lower:span>]: u32 = [<$prefix $newname:span>];)+
359/// }
360/// };
361/// }
362///
363/// pub_no_prefix!(
364/// binder_driver_return_protocol_,
365/// BR_OK,
366/// BR_ERROR,
367/// BR_TRANSACTION,
368/// BR_REPLY,
369/// BR_DEAD_REPLY,
370/// BR_TRANSACTION_COMPLETE,
371/// BR_INCREFS,
372/// BR_ACQUIRE,
373/// BR_RELEASE,
374/// BR_DECREFS,
375/// BR_NOOP,
376/// BR_SPAWN_LOOPER,
377/// BR_DEAD_BINDER,
378/// BR_CLEAR_DEATH_NOTIFICATION_DONE,
379/// BR_FAILED_REPLY
380/// );
381///
382/// assert_eq!(br_ok(), binder_driver_return_protocol_BR_OK);
383/// ```
384///
385/// # Literals
386///
387/// Literals can also be concatenated with other identifiers:
388///
389/// ```ignore
390/// macro_rules! create_numbered_fn {
391/// ($name:literal, $val:literal) => {
392/// kernel::macros::paste! {
393/// fn [<some_ $name _fn $val>]() -> u32 { $val }
394/// }
395/// };
396/// }
397///
398/// create_numbered_fn!("foo", 100);
399///
400/// assert_eq!(some_foo_fn100(), 100)
401/// ```
402///
403/// [`paste`]: https://docs.rs/paste/
404#[proc_macro]
405pub fn paste(input: TokenStream) -> TokenStream {
406 let mut tokens = input.into_iter().collect();
407 paste::expand(&mut tokens);
408 tokens.into_iter().collect()
409}
410
411/// Derives the [`Zeroable`] trait for the given struct.
412///
413/// This can only be used for structs where every field implements the [`Zeroable`] trait.
414///
415/// # Examples
416///
417/// ```rust,ignore
418/// #[derive(Zeroable)]
419/// pub struct DriverData {
420/// id: i64,
421/// buf_ptr: *mut u8,
422/// len: usize,
423/// }
424/// ```
425#[proc_macro_derive(Zeroable)]
426pub fn derive_zeroable(input: TokenStream) -> TokenStream {
427 zeroable::derive(input)
428}