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                     use kernel::init::PinInit;
 236
 237                     /// The \"Rust loadable module\" mark.
 238                     //
 239                     // This may be best done another way later on, e.g. as a new modinfo
 240                     // key or a new section. For the moment, keep it simple.
 241                     #[cfg(MODULE)]
 242                     #[doc(hidden)]
 243                     #[used]
 244                     static __IS_RUST_MODULE: () = ();
 245
 246                     static mut __MOD: core::mem::MaybeUninit<{type_}> =
 247                         core::mem::MaybeUninit::uninit();
 248
 249                     // Loadable modules need to export the `{{init,cleanup}}_module` identifiers.
 250                     /// # Safety
 251                     ///
 252                     /// This function must not be called after module initialization, because it may be
 253                     /// freed after that completes.
 254                     #[cfg(MODULE)]
 255                     #[doc(hidden)]
 256                     #[no_mangle]
 257                     #[link_section = \".init.text\"]
 258                     pub unsafe extern \"C\" fn init_module() -> kernel::ffi::c_int {{
 259                         // SAFETY: This function is inaccessible to the outside due to the double
 260                         // module wrapping it. It is called exactly once by the C side via its
 261                         // unique name.
 262                         unsafe {{ __init() }}
 263                     }}
 264
 265                     #[cfg(MODULE)]
 266                     #[doc(hidden)]
 267                     #[used]
 268                     #[link_section = \".init.data\"]
 269                     static __UNIQUE_ID___addressable_init_module: unsafe extern \"C\" fn() -> i32 = init_module;
 270
 271                     #[cfg(MODULE)]
 272                     #[doc(hidden)]
 273                     #[no_mangle]
 274                     pub extern \"C\" fn cleanup_module() {{
 275                         // SAFETY:
 276                         // - This function is inaccessible to the outside due to the double
 277                         //   module wrapping it. It is called exactly once by the C side via its
 278                         //   unique name,
 279                         // - furthermore it is only called after `init_module` has returned `0`
 280                         //   (which delegates to `__init`).
 281                         unsafe {{ __exit() }}
 282                     }}
 283
 284                     #[cfg(MODULE)]
 285                     #[doc(hidden)]
 286                     #[used]
 287                     #[link_section = \".exit.data\"]
 288                     static __UNIQUE_ID___addressable_cleanup_module: extern \"C\" fn() = cleanup_module;
 289
 290                     // Built-in modules are initialized through an initcall pointer
 291                     // and the identifiers need to be unique.
 292                     #[cfg(not(MODULE))]
 293                     #[cfg(not(CONFIG_HAVE_ARCH_PREL32_RELOCATIONS))]
 294                     #[doc(hidden)]
 295                     #[link_section = \"{initcall_section}\"]
 296                     #[used]
 297                     pub static __{name}_initcall: extern \"C\" fn() -> kernel::ffi::c_int = __{name}_init;
 298
 299                     #[cfg(not(MODULE))]
 300                     #[cfg(CONFIG_HAVE_ARCH_PREL32_RELOCATIONS)]
 301                     core::arch::global_asm!(
 302                         r#\".section \"{initcall_section}\", \"a\"
 303                         __{name}_initcall:
 304                             .long   __{name}_init - .
 305                             .previous
 306                         \"#
 307                     );
 308
 309                     #[cfg(not(MODULE))]
 310                     #[doc(hidden)]
 311                     #[no_mangle]
 312                     pub extern \"C\" fn __{name}_init() -> kernel::ffi::c_int {{
 313                         // SAFETY: This function is inaccessible to the outside due to the double
 314                         // module wrapping it. It is called exactly once by the C side via its
 315                         // placement above in the initcall section.
 316                         unsafe {{ __init() }}
 317                     }}
 318
 319                     #[cfg(not(MODULE))]
 320                     #[doc(hidden)]
 321                     #[no_mangle]
 322                     pub extern \"C\" fn __{name}_exit() {{
 323                         // SAFETY:
 324                         // - This function is inaccessible to the outside due to the double
 325                         //   module wrapping it. It is called exactly once by the C side via its
 326                         //   unique name,
 327                         // - furthermore it is only called after `__{name}_init` has returned `0`
 328                         //   (which delegates to `__init`).
 329                         unsafe {{ __exit() }}
 330                     }}
 331
 332                     /// # Safety
 333                     ///
 334                     /// This function must only be called once.
 335                     unsafe fn __init() -> kernel::ffi::c_int {{
 336                         let initer =
 337                             <{type_} as kernel::InPlaceModule>::init(&super::super::THIS_MODULE);
 338                         // SAFETY: No data race, since `__MOD` can only be accessed by this module
 339                         // and there only `__init` and `__exit` access it. These functions are only
 340                         // called once and `__exit` cannot be called before or during `__init`.
 341                         match unsafe {{ initer.__pinned_init(__MOD.as_mut_ptr()) }} {{
 342                             Ok(m) => 0,
 343                             Err(e) => e.to_errno(),
 344                         }}
 345                     }}
 346
 347                     /// # Safety
 348                     ///
 349                     /// This function must
 350                     /// - only be called once,
 351                     /// - be called after `__init` has been called and returned `0`.
 352                     unsafe fn __exit() {{
 353                         // SAFETY: No data race, since `__MOD` can only be accessed by this module
 354                         // and there only `__init` and `__exit` access it. These functions are only
 355                         // called once and `__init` was already called.
 356                         unsafe {{
 357                             // Invokes `drop()` on `__MOD`, which should be used for cleanup.
 358                             __MOD.assume_init_drop();
 359                         }}
 360                     }}
 361
 362                     {modinfo}
 363                 }}
 364             }}
 365         ",
 366         type_ = info.type_,
 367         name = info.name,
 368         modinfo = modinfo.buffer,
 369         initcall_section = ".initcall6.init"
 370     )
 371     .parse()
 372     .expect("Error parsing formatted string into token stream.")
 373 }