rust/macros/module.rs

   1 // SPDX-License-Identifier: GPL-2.0
   2
   3 use crate::helpers::*;
   4 use proc_macro::{token_stream, Literal, TokenStream, TokenTree};
   5 use std::fmt::Write;
   6
   7 struct ModInfoBuilder<'a> {
   8     module: &'a str,
   9     counter: usize,
  10     buffer: String,
  11 }
  12
  13 impl<'a> ModInfoBuilder<'a> {
  14     fn new(module: &'a str) -> Self {
  15         ModInfoBuilder {
  16             module,
  17             counter: 0,
  18             buffer: String::new(),
  19         }
  20     }
  21
  22     fn emit_base(&mut self, field: &str, content: &str, builtin: bool) {
  23         let string = if builtin {
  24             // Built-in modules prefix their modinfo strings by `module.`.
  25             format!(
  26                 "{module}.{field}={content}\0",
  27                 module = self.module,
  28                 field = field,
  29                 content = content
  30             )
  31         } else {
  32             // Loadable modules' modinfo strings go as-is.
  33             format!("{field}={content}\0", field = field, content = content)
  34         };
  35
  36         write!(
  37             &mut self.buffer,
  38             "
  39                 {cfg}
  40                 #[doc(hidden)]
  41                 #[link_section = \".modinfo\"]
  42                 #[used]
  43                 pub static __{module}_{counter}: [u8; {length}] = *{string};
  44             ",
  45             cfg = if builtin {
  46                 "#[cfg(not(MODULE))]"
  47             } else {
  48                 "#[cfg(MODULE)]"
  49             },
  50             module = self.module.to_uppercase(),
  51             counter = self.counter,
  52             length = string.len(),
  53             string = Literal::byte_string(string.as_bytes()),
  54         )
  55         .unwrap();
  56
  57         self.counter += 1;
  58     }
  59
  60     fn emit_only_builtin(&mut self, field: &str, content: &str) {
  61         self.emit_base(field, content, true)
  62     }
  63
  64     fn emit_only_loadable(&mut self, field: &str, content: &str) {
  65         self.emit_base(field, content, false)
  66     }
  67
  68     fn emit(&mut self, field: &str, content: &str) {
  69         self.emit_only_builtin(field, content);
  70         self.emit_only_loadable(field, content);
  71     }
  72 }
  73
  74 #[derive(Debug, Default)]
  75 struct ModuleInfo {
  76     type_: String,
  77     license: String,
  78     name: String,
  79     author: Option<String>,
  80     description: Option<String>,
  81     alias: Option<String>,
  82 }
  83
  84 impl ModuleInfo {
  85     fn parse(it: &mut token_stream::IntoIter) -> Self {
  86         let mut info = ModuleInfo::default();
  87
  88         const EXPECTED_KEYS: &[&str] =
  89             &["type", "name", "author", "description", "license", "alias"];
  90         const REQUIRED_KEYS: &[&str] = &["type", "name", "license"];
  91         let mut seen_keys = Vec::new();
  92
  93         loop {
  94             let key = match it.next() {
  95                 Some(TokenTree::Ident(ident)) => ident.to_string(),
  96                 Some(_) => panic!("Expected Ident or end"),
  97                 None => break,
  98             };
  99
 100             if seen_keys.contains(&key) {
 101                 panic!(
 102                     "Duplicated key \"{}\". Keys can only be specified once.",
 103                     key
 104                 );
 105             }
 106
 107             assert_eq!(expect_punct(it), ':');
 108
 109             match key.as_str() {
 110                 "type" => info.type_ = expect_ident(it),
 111                 "name" => info.name = expect_byte_string(it),
 112                 "author" => info.author = Some(expect_byte_string(it)),
 113                 "description" => info.description = Some(expect_byte_string(it)),
 114                 "license" => info.license = expect_byte_string(it),
 115                 "alias" => info.alias = Some(expect_byte_string(it)),
 116                 _ => panic!(
 117                     "Unknown key \"{}\". Valid keys are: {:?}.",
 118                     key, EXPECTED_KEYS
 119                 ),
 120             }
 121
 122             assert_eq!(expect_punct(it), ',');
 123
 124             seen_keys.push(key);
 125         }
 126
 127         expect_end(it);
 128
 129         for key in REQUIRED_KEYS {
 130             if !seen_keys.iter().any(|e| e == key) {
 131                 panic!("Missing required key \"{}\".", key);
 132             }
 133         }
 134
 135         let mut ordered_keys: Vec<&str> = Vec::new();
 136         for key in EXPECTED_KEYS {
 137             if seen_keys.iter().any(|e| e == key) {
 138                 ordered_keys.push(key);
 139             }
 140         }
 141
 142         if seen_keys != ordered_keys {
 143             panic!(
 144                 "Keys are not ordered as expected. Order them like: {:?}.",
 145                 ordered_keys
 146             );
 147         }
 148
 149         info
 150     }
 151 }
 152
 153 pub(crate) fn module(ts: TokenStream) -> TokenStream {
 154     let mut it = ts.into_iter();
 155
 156     let info = ModuleInfo::parse(&mut it);
 157
 158     let mut modinfo = ModInfoBuilder::new(info.name.as_ref());
 159     if let Some(author) = info.author {
 160         modinfo.emit("author", &author);
 161     }
 162     if let Some(description) = info.description {
 163         modinfo.emit("description", &description);
 164     }
 165     modinfo.emit("license", &info.license);
 166     if let Some(alias) = info.alias {
 167         modinfo.emit("alias", &alias);
 168     }
 169
 170     // Built-in modules also export the `file` modinfo string.
 171     let file =
 172         std::env::var("RUST_MODFILE").expect("Unable to fetch RUST_MODFILE environmental variable");
 173     modinfo.emit_only_builtin("file", &file);
 174
 175     format!(
 176         "
 177             /// The module name.
 178             ///
 179             /// Used by the printing macros, e.g. [`info!`].
 180             const __LOG_PREFIX: &[u8] = b\"{name}\\0\";
 181
 182             /// The \"Rust loadable module\" mark, for `scripts/is_rust_module.sh`.
 183             //
 184             // This may be best done another way later on, e.g. as a new modinfo
 185             // key or a new section. For the moment, keep it simple.
 186             #[cfg(MODULE)]
 187             #[doc(hidden)]
 188             #[used]
 189             static __IS_RUST_MODULE: () = ();
 190
 191             static mut __MOD: Option<{type_}> = None;
 192
 193             // SAFETY: `__this_module` is constructed by the kernel at load time and will not be
 194             // freed until the module is unloaded.
 195             #[cfg(MODULE)]
 196             static THIS_MODULE: kernel::ThisModule = unsafe {{
 197                 kernel::ThisModule::from_ptr(&kernel::bindings::__this_module as *const _ as *mut _)
 198             }};
 199             #[cfg(not(MODULE))]
 200             static THIS_MODULE: kernel::ThisModule = unsafe {{
 201                 kernel::ThisModule::from_ptr(core::ptr::null_mut())
 202             }};
 203
 204             // Loadable modules need to export the `{{init,cleanup}}_module` identifiers.
 205             #[cfg(MODULE)]
 206             #[doc(hidden)]
 207             #[no_mangle]
 208             pub extern \"C\" fn init_module() -> core::ffi::c_int {{
 209                 __init()
 210             }}
 211
 212             #[cfg(MODULE)]
 213             #[doc(hidden)]
 214             #[no_mangle]
 215             pub extern \"C\" fn cleanup_module() {{
 216                 __exit()
 217             }}
 218
 219             // Built-in modules are initialized through an initcall pointer
 220             // and the identifiers need to be unique.
 221             #[cfg(not(MODULE))]
 222             #[cfg(not(CONFIG_HAVE_ARCH_PREL32_RELOCATIONS))]
 223             #[doc(hidden)]
 224             #[link_section = \"{initcall_section}\"]
 225             #[used]
 226             pub static __{name}_initcall: extern \"C\" fn() -> core::ffi::c_int = __{name}_init;
 227
 228             #[cfg(not(MODULE))]
 229             #[cfg(CONFIG_HAVE_ARCH_PREL32_RELOCATIONS)]
 230             core::arch::global_asm!(
 231                 r#\".section \"{initcall_section}\", \"a\"
 232                 __{name}_initcall:
 233                     .long   __{name}_init - .
 234                     .previous
 235                 \"#
 236             );
 237
 238             #[cfg(not(MODULE))]
 239             #[doc(hidden)]
 240             #[no_mangle]
 241             pub extern \"C\" fn __{name}_init() -> core::ffi::c_int {{
 242                 __init()
 243             }}
 244
 245             #[cfg(not(MODULE))]
 246             #[doc(hidden)]
 247             #[no_mangle]
 248             pub extern \"C\" fn __{name}_exit() {{
 249                 __exit()
 250             }}
 251
 252             fn __init() -> core::ffi::c_int {{
 253                 match <{type_} as kernel::Module>::init(&THIS_MODULE) {{
 254                     Ok(m) => {{
 255                         unsafe {{
 256                             __MOD = Some(m);
 257                         }}
 258                         return 0;
 259                     }}
 260                     Err(e) => {{
 261                         return e.to_kernel_errno();
 262                     }}
 263                 }}
 264             }}
 265
 266             fn __exit() {{
 267                 unsafe {{
 268                     // Invokes `drop()` on `__MOD`, which should be used for cleanup.
 269                     __MOD = None;
 270                 }}
 271             }}
 272
 273             {modinfo}
 274         ",
 275         type_ = info.type_,
 276         name = info.name,
 277         modinfo = modinfo.buffer,
 278         initcall_section = ".initcall6.init"
 279     )
 280     .parse()
 281     .expect("Error parsing formatted string into token stream.")
 282 }