rust/macros/lib.rs

   1 // SPDX-License-Identifier: GPL-2.0
   2
   3 //! Crate for all kernel procedural macros.
   4
   5 mod concat_idents;
   6 mod helpers;
   7 mod module;
   8
   9 use proc_macro::TokenStream;
  10
  11 /// Declares a kernel module.
  12 ///
  13 /// The `type` argument should be a type which implements the [`Module`]
  14 /// trait. Also accepts various forms of kernel metadata.
  15 ///
  16 /// C header: [`include/linux/moduleparam.h`](../../../include/linux/moduleparam.h)
  17 ///
  18 /// [`Module`]: ../kernel/trait.Module.html
  19 ///
  20 /// # Examples
  21 ///
  22 /// ```ignore
  23 /// use kernel::prelude::*;
  24 ///
  25 /// module!{
  26 ///     type: MyModule,
  27 ///     name: b"my_kernel_module",
  28 ///     author: b"Rust for Linux Contributors",
  29 ///     description: b"My very own kernel module!",
  30 ///     license: b"GPL",
  31 ///     params: {
  32 ///        my_i32: i32 {
  33 ///            default: 42,
  34 ///            permissions: 0o000,
  35 ///            description: b"Example of i32",
  36 ///        },
  37 ///        writeable_i32: i32 {
  38 ///            default: 42,
  39 ///            permissions: 0o644,
  40 ///            description: b"Example of i32",
  41 ///        },
  42 ///    },
  43 /// }
  44 ///
  45 /// struct MyModule;
  46 ///
  47 /// impl kernel::Module for MyModule {
  48 ///     fn init() -> Result<Self> {
  49 ///         // If the parameter is writeable, then the kparam lock must be
  50 ///         // taken to read the parameter:
  51 ///         {
  52 ///             let lock = THIS_MODULE.kernel_param_lock();
  53 ///             pr_info!("i32 param is:  {}\n", writeable_i32.read(&lock));
  54 ///         }
  55 ///         // If the parameter is read only, it can be read without locking
  56 ///         // the kernel parameters:
  57 ///         pr_info!("i32 param is:  {}\n", my_i32.read());
  58 ///         Ok(Self)
  59 ///     }
  60 /// }
  61 /// ```
  62 ///
  63 /// # Supported argument types
  64 ///   - `type`: type which implements the [`Module`] trait (required).
  65 ///   - `name`: byte array of the name of the kernel module (required).
  66 ///   - `author`: byte array of the author of the kernel module.
  67 ///   - `description`: byte array of the description of the kernel module.
  68 ///   - `license`: byte array of the license of the kernel module (required).
  69 ///   - `alias`: byte array of alias name of the kernel module.
  70 #[proc_macro]
  71 pub fn module(ts: TokenStream) -> TokenStream {
  72     module::module(ts)
  73 }
  74
  75 /// Concatenate two identifiers.
  76 ///
  77 /// This is useful in macros that need to declare or reference items with names
  78 /// starting with a fixed prefix and ending in a user specified name. The resulting
  79 /// identifier has the span of the second argument.
  80 ///
  81 /// # Examples
  82 ///
  83 /// ```ignore
  84 /// use kernel::macro::concat_idents;
  85 ///
  86 /// macro_rules! pub_no_prefix {
  87 ///     ($prefix:ident, $($newname:ident),+) => {
  88 ///         $(pub(crate) const $newname: u32 = kernel::macros::concat_idents!($prefix, $newname);)+
  89 ///     };
  90 /// }
  91 ///
  92 /// pub_no_prefix!(
  93 ///     binder_driver_return_protocol_,
  94 ///     BR_OK,
  95 ///     BR_ERROR,
  96 ///     BR_TRANSACTION,
  97 ///     BR_REPLY,
  98 ///     BR_DEAD_REPLY,
  99 ///     BR_TRANSACTION_COMPLETE,
 100 ///     BR_INCREFS,
 101 ///     BR_ACQUIRE,
 102 ///     BR_RELEASE,
 103 ///     BR_DECREFS,
 104 ///     BR_NOOP,
 105 ///     BR_SPAWN_LOOPER,
 106 ///     BR_DEAD_BINDER,
 107 ///     BR_CLEAR_DEATH_NOTIFICATION_DONE,
 108 ///     BR_FAILED_REPLY
 109 /// );
 110 ///
 111 /// assert_eq!(BR_OK, binder_driver_return_protocol_BR_OK);
 112 /// ```
 113 #[proc_macro]
 114 pub fn concat_idents(ts: TokenStream) -> TokenStream {
 115     concat_idents::concat_idents(ts)
 116 }