rust/macros/lib.rs

   1 // SPDX-License-Identifier: GPL-2.0
   2
   3 //! Crate for all kernel procedural macros.
   4
   5 mod helpers;
   6 mod module;
   7
   8 use proc_macro::TokenStream;
   9
  10 /// Declares a kernel module.
  11 ///
  12 /// The `type` argument should be a type which implements the [`Module`]
  13 /// trait. Also accepts various forms of kernel metadata.
  14 ///
  15 /// C header: [`include/linux/moduleparam.h`](../../../include/linux/moduleparam.h)
  16 ///
  17 /// [`Module`]: ../kernel/trait.Module.html
  18 ///
  19 /// # Examples
  20 ///
  21 /// ```ignore
  22 /// use kernel::prelude::*;
  23 ///
  24 /// module!{
  25 ///     type: MyModule,
  26 ///     name: b"my_kernel_module",
  27 ///     author: b"Rust for Linux Contributors",
  28 ///     description: b"My very own kernel module!",
  29 ///     license: b"GPL",
  30 ///     params: {
  31 ///        my_i32: i32 {
  32 ///            default: 42,
  33 ///            permissions: 0o000,
  34 ///            description: b"Example of i32",
  35 ///        },
  36 ///        writeable_i32: i32 {
  37 ///            default: 42,
  38 ///            permissions: 0o644,
  39 ///            description: b"Example of i32",
  40 ///        },
  41 ///    },
  42 /// }
  43 ///
  44 /// struct MyModule;
  45 ///
  46 /// impl kernel::Module for MyModule {
  47 ///     fn init() -> Result<Self> {
  48 ///         // If the parameter is writeable, then the kparam lock must be
  49 ///         // taken to read the parameter:
  50 ///         {
  51 ///             let lock = THIS_MODULE.kernel_param_lock();
  52 ///             pr_info!("i32 param is:  {}\n", writeable_i32.read(&lock));
  53 ///         }
  54 ///         // If the parameter is read only, it can be read without locking
  55 ///         // the kernel parameters:
  56 ///         pr_info!("i32 param is:  {}\n", my_i32.read());
  57 ///         Ok(Self)
  58 ///     }
  59 /// }
  60 /// ```
  61 ///
  62 /// # Supported argument types
  63 ///   - `type`: type which implements the [`Module`] trait (required).
  64 ///   - `name`: byte array of the name of the kernel module (required).
  65 ///   - `author`: byte array of the author of the kernel module.
  66 ///   - `description`: byte array of the description of the kernel module.
  67 ///   - `license`: byte array of the license of the kernel module (required).
  68 ///   - `alias`: byte array of alias name of the kernel module.
  69 #[proc_macro]
  70 pub fn module(ts: TokenStream) -> TokenStream {
  71     module::module(ts)
  72 }