rust/macros/module.rs

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