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     firmware: Option<Vec<String>>,
 101 }
 102
 103 impl ModuleInfo {
 104     fn parse(it: &mut token_stream::IntoIter) -> Self {
 105         let mut info = ModuleInfo::default();
 106
 107         const EXPECTED_KEYS: &[&str] = &[
 108             "type",
 109             "name",
 110             "author",
 111             "description",
 112             "license",
 113             "alias",
 114             "firmware",
 115         ];
 116         const REQUIRED_KEYS: &[&str] = &["type", "name", "license"];
 117         let mut seen_keys = Vec::new();
 118
 119         loop {
 120             let key = match it.next() {
 121                 Some(TokenTree::Ident(ident)) => ident.to_string(),
 122                 Some(_) => panic!("Expected Ident or end"),
 123                 None => break,
 124             };
 125
 126             if seen_keys.contains(&key) {
 127                 panic!(
 128                     "Duplicated key \"{}\". Keys can only be specified once.",
 129                     key
 130                 );
 131             }
 132
 133             assert_eq!(expect_punct(it), ':');
 134
 135             match key.as_str() {
 136                 "type" => info.type_ = expect_ident(it),
 137                 "name" => info.name = expect_string_ascii(it),
 138                 "author" => info.author = Some(expect_string(it)),
 139                 "description" => info.description = Some(expect_string(it)),
 140                 "license" => info.license = expect_string_ascii(it),
 141                 "alias" => info.alias = Some(expect_string_array(it)),
 142                 "firmware" => info.firmware = Some(expect_string_array(it)),
 143                 _ => panic!(
 144                     "Unknown key \"{}\". Valid keys are: {:?}.",
 145                     key, EXPECTED_KEYS
 146                 ),
 147             }
 148
 149             assert_eq!(expect_punct(it), ',');
 150
 151             seen_keys.push(key);
 152         }
 153
 154         expect_end(it);
 155
 156         for key in REQUIRED_KEYS {
 157             if !seen_keys.iter().any(|e| e == key) {
 158                 panic!("Missing required key \"{}\".", key);
 159             }
 160         }
 161
 162         let mut ordered_keys: Vec<&str> = Vec::new();
 163         for key in EXPECTED_KEYS {
 164             if seen_keys.iter().any(|e| e == key) {
 165                 ordered_keys.push(key);
 166             }
 167         }
 168
 169         if seen_keys != ordered_keys {
 170             panic!(
 171                 "Keys are not ordered as expected. Order them like: {:?}.",
 172                 ordered_keys
 173             );
 174         }
 175
 176         info
 177     }
 178 }
 179
 180 pub(crate) fn module(ts: TokenStream) -> TokenStream {
 181     let mut it = ts.into_iter();
 182
 183     let info = ModuleInfo::parse(&mut it);
 184
 185     let mut modinfo = ModInfoBuilder::new(info.name.as_ref());
 186     if let Some(author) = info.author {
 187         modinfo.emit("author", &author);
 188     }
 189     if let Some(description) = info.description {
 190         modinfo.emit("description", &description);
 191     }
 192     modinfo.emit("license", &info.license);
 193     if let Some(aliases) = info.alias {
 194         for alias in aliases {
 195             modinfo.emit("alias", &alias);
 196         }
 197     }
 198     if let Some(firmware) = info.firmware {
 199         for fw in firmware {
 200             modinfo.emit("firmware", &fw);
 201         }
 202     }
 203
 204     // Built-in modules also export the `file` modinfo string.
 205     let file =
 206         std::env::var("RUST_MODFILE").expect("Unable to fetch RUST_MODFILE environmental variable");
 207     modinfo.emit_only_builtin("file", &file);
 208
 209     format!(
 210         "
 211             /// The module name.
 212             ///
 213             /// Used by the printing macros, e.g. [`info!`].
 214             const __LOG_PREFIX: &[u8] = b\"{name}\\0\";
 215
 216             // SAFETY: `__this_module` is constructed by the kernel at load time and will not be
 217             // freed until the module is unloaded.
 218             #[cfg(MODULE)]
 219             static THIS_MODULE: kernel::ThisModule = unsafe {{
 220                 extern \"C\" {{
 221                     static __this_module: kernel::types::Opaque<kernel::bindings::module>;
 222                 }}
 223
 224                 kernel::ThisModule::from_ptr(__this_module.get())
 225             }};
 226             #[cfg(not(MODULE))]
 227             static THIS_MODULE: kernel::ThisModule = unsafe {{
 228                 kernel::ThisModule::from_ptr(core::ptr::null_mut())
 229             }};
 230
 231             // Double nested modules, since then nobody can access the public items inside.
 232             mod __module_init {{
 233                 mod __module_init {{
 234                     use super::super::{type_};
 235
 236                     /// The \"Rust loadable module\" mark.
 237                     //
 238                     // This may be best done another way later on, e.g. as a new modinfo
 239                     // key or a new section. For the moment, keep it simple.
 240                     #[cfg(MODULE)]
 241                     #[doc(hidden)]
 242                     #[used]
 243                     static __IS_RUST_MODULE: () = ();
 244
 245                     static mut __MOD: Option<{type_}> = None;
 246
 247                     // Loadable modules need to export the `{{init,cleanup}}_module` identifiers.
 248                     /// # Safety
 249                     ///
 250                     /// This function must not be called after module initialization, because it may be
 251                     /// freed after that completes.
 252                     #[cfg(MODULE)]
 253                     #[doc(hidden)]
 254                     #[no_mangle]
 255                     #[link_section = \".init.text\"]
 256                     pub unsafe extern \"C\" fn init_module() -> kernel::ffi::c_int {{
 257                         // SAFETY: This function is inaccessible to the outside due to the double
 258                         // module wrapping it. It is called exactly once by the C side via its
 259                         // unique name.
 260                         unsafe {{ __init() }}
 261                     }}
 262
 263                     #[cfg(MODULE)]
 264                     #[doc(hidden)]
 265                     #[used]
 266                     #[link_section = \".init.data\"]
 267                     static __UNIQUE_ID___addressable_init_module: unsafe extern \"C\" fn() -> i32 = init_module;
 268
 269                     #[cfg(MODULE)]
 270                     #[doc(hidden)]
 271                     #[no_mangle]
 272                     pub extern \"C\" fn cleanup_module() {{
 273                         // SAFETY:
 274                         // - This function is inaccessible to the outside due to the double
 275                         //   module wrapping it. It is called exactly once by the C side via its
 276                         //   unique name,
 277                         // - furthermore it is only called after `init_module` has returned `0`
 278                         //   (which delegates to `__init`).
 279                         unsafe {{ __exit() }}
 280                     }}
 281
 282                     #[cfg(MODULE)]
 283                     #[doc(hidden)]
 284                     #[used]
 285                     #[link_section = \".exit.data\"]
 286                     static __UNIQUE_ID___addressable_cleanup_module: extern \"C\" fn() = cleanup_module;
 287
 288                     // Built-in modules are initialized through an initcall pointer
 289                     // and the identifiers need to be unique.
 290                     #[cfg(not(MODULE))]
 291                     #[cfg(not(CONFIG_HAVE_ARCH_PREL32_RELOCATIONS))]
 292                     #[doc(hidden)]
 293                     #[link_section = \"{initcall_section}\"]
 294                     #[used]
 295                     pub static __{name}_initcall: extern \"C\" fn() -> kernel::ffi::c_int = __{name}_init;
 296
 297                     #[cfg(not(MODULE))]
 298                     #[cfg(CONFIG_HAVE_ARCH_PREL32_RELOCATIONS)]
 299                     core::arch::global_asm!(
 300                         r#\".section \"{initcall_section}\", \"a\"
 301                         __{name}_initcall:
 302                             .long   __{name}_init - .
 303                             .previous
 304                         \"#
 305                     );
 306
 307                     #[cfg(not(MODULE))]
 308                     #[doc(hidden)]
 309                     #[no_mangle]
 310                     pub extern \"C\" fn __{name}_init() -> kernel::ffi::c_int {{
 311                         // SAFETY: This function is inaccessible to the outside due to the double
 312                         // module wrapping it. It is called exactly once by the C side via its
 313                         // placement above in the initcall section.
 314                         unsafe {{ __init() }}
 315                     }}
 316
 317                     #[cfg(not(MODULE))]
 318                     #[doc(hidden)]
 319                     #[no_mangle]
 320                     pub extern \"C\" fn __{name}_exit() {{
 321                         // SAFETY:
 322                         // - This function is inaccessible to the outside due to the double
 323                         //   module wrapping it. It is called exactly once by the C side via its
 324                         //   unique name,
 325                         // - furthermore it is only called after `__{name}_init` has returned `0`
 326                         //   (which delegates to `__init`).
 327                         unsafe {{ __exit() }}
 328                     }}
 329
 330                     /// # Safety
 331                     ///
 332                     /// This function must only be called once.
 333                     unsafe fn __init() -> kernel::ffi::c_int {{
 334                         match <{type_} as kernel::Module>::init(&super::super::THIS_MODULE) {{
 335                             Ok(m) => {{
 336                                 // SAFETY: No data race, since `__MOD` can only be accessed by this
 337                                 // module and there only `__init` and `__exit` access it. These
 338                                 // functions are only called once and `__exit` cannot be called
 339                                 // before or during `__init`.
 340                                 unsafe {{
 341                                     __MOD = Some(m);
 342                                 }}
 343                                 return 0;
 344                             }}
 345                             Err(e) => {{
 346                                 return e.to_errno();
 347                             }}
 348                         }}
 349                     }}
 350
 351                     /// # Safety
 352                     ///
 353                     /// This function must
 354                     /// - only be called once,
 355                     /// - be called after `__init` has been called and returned `0`.
 356                     unsafe fn __exit() {{
 357                         // SAFETY: No data race, since `__MOD` can only be accessed by this module
 358                         // and there only `__init` and `__exit` access it. These functions are only
 359                         // called once and `__init` was already called.
 360                         unsafe {{
 361                             // Invokes `drop()` on `__MOD`, which should be used for cleanup.
 362                             __MOD = None;
 363                         }}
 364                     }}
 365
 366                     {modinfo}
 367                 }}
 368             }}
 369         ",
 370         type_ = info.type_,
 371         name = info.name,
 372         modinfo = modinfo.buffer,
 373         initcall_section = ".initcall6.init"
 374     )
 375     .parse()
 376     .expect("Error parsing formatted string into token stream.")
 377 }