From 67f9c312b0a7f4bc869376d2a68308e673235954 Mon Sep 17 00:00:00 2001 From: Aswin Unnikrishnan Date: Sun, 12 May 2024 11:23:20 +0000 Subject: rust: add example for `alias` argument in `module` macro documentation Add example for `alias` argument supported by `module` macro. `alias` accepts an array of alternate names for the module as string. Reviewed-by: Alice Ryhl Signed-off-by: Aswin Unnikrishnan Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20240512112324.8514-1-aswinunni01@gmail.com Signed-off-by: Miguel Ojeda --- rust/macros/lib.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'rust/macros/lib.rs') diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 520eae5fd792..aa89b41fa10e 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -35,6 +35,7 @@ use proc_macro::TokenStream; /// author: "Rust for Linux Contributors", /// description: "My very own kernel module!", /// license: "GPL", +/// alias: ["alternate_module_name"], /// } /// /// struct MyModule; -- cgit v1.2.3-70-g09d2 From 63249a070eb5187d5caec995d171b53e374a0741 Mon Sep 17 00:00:00 2001 From: Aswin Unnikrishnan Date: Sun, 12 May 2024 11:23:21 +0000 Subject: rust: fix datatype in docs for `module` macro arguments Remove the mention of byte array as datatype for `module` macro arguments since the arguments are defined as string, and `alias` is a string array. Signed-off-by: Aswin Unnikrishnan Reviewed-by: Vincenzo Palazzo Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20240512112324.8514-2-aswinunni01@gmail.com Signed-off-by: Miguel Ojeda --- rust/macros/lib.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'rust/macros/lib.rs') diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index aa89b41fa10e..5214e07367c5 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -58,11 +58,11 @@ use proc_macro::TokenStream; /// /// # Supported argument types /// - `type`: type which implements the [`Module`] trait (required). -/// - `name`: byte array of the name of the kernel module (required). -/// - `author`: byte array of the author of the kernel module. -/// - `description`: byte array of the description of the kernel module. -/// - `license`: byte array of the license of the kernel module (required). -/// - `alias`: byte array of alias name of the kernel module. +/// - `name`: ASCII string literal of the name of the kernel module (required). +/// - `author`: string literal of the author of the kernel module. +/// - `description`: string literal of the description of the kernel module. +/// - `license`: ASCII string literal of the license of the kernel module (required). +/// - `alias`: array of ASCII string literals of the alias names of the kernel module. #[proc_macro] pub fn module(ts: TokenStream) -> TokenStream { module::module(ts) -- cgit v1.2.3-70-g09d2 From 549d3c2ffbea44fe123a67983fd8b15ab6989d8d Mon Sep 17 00:00:00 2001 From: FUJITA Tomonori Date: Wed, 1 May 2024 21:35:48 +0900 Subject: rust: add 'firmware' field support to module! macro This adds 'firmware' field support to module! macro, corresponds to MODULE_FIRMWARE macro. You can specify the file names of binary firmware that the kernel module requires. The information is embedded in the modinfo section of the kernel module. For example, a tool to build an initramfs uses this information to put the firmware files into the initramfs image. Signed-off-by: FUJITA Tomonori Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20240501123548.51769-1-fujita.tomonori@gmail.com Signed-off-by: Miguel Ojeda --- rust/macros/lib.rs | 32 ++++++++++++++++++++++++++++++++ rust/macros/module.rs | 18 ++++++++++++++++-- 2 files changed, 48 insertions(+), 2 deletions(-) (limited to 'rust/macros/lib.rs') diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 5214e07367c5..6dcc72aff111 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -56,6 +56,36 @@ use proc_macro::TokenStream; /// } /// ``` /// +/// ## Firmware +/// +/// The following example shows how to declare a kernel module that needs +/// to load binary firmware files. You need to specify the file names of +/// the firmware in the `firmware` field. The information is embedded +/// in the `modinfo` section of the kernel module. For example, a tool to +/// build an initramfs uses this information to put the firmware files into +/// the initramfs image. +/// +/// ```ignore +/// use kernel::prelude::*; +/// +/// module!{ +/// type: MyDeviceDriverModule, +/// name: "my_device_driver_module", +/// author: "Rust for Linux Contributors", +/// description: "My device driver requires firmware", +/// license: "GPL", +/// firmware: ["my_device_firmware1.bin", "my_device_firmware2.bin"], +/// } +/// +/// struct MyDeviceDriverModule; +/// +/// impl kernel::Module for MyDeviceDriverModule { +/// fn init() -> Result { +/// Ok(Self) +/// } +/// } +/// ``` +/// /// # Supported argument types /// - `type`: type which implements the [`Module`] trait (required). /// - `name`: ASCII string literal of the name of the kernel module (required). @@ -63,6 +93,8 @@ use proc_macro::TokenStream; /// - `description`: string literal of the description of the kernel module. /// - `license`: ASCII string literal of the license of the kernel module (required). /// - `alias`: array of ASCII string literals of the alias names of the kernel module. +/// - `firmware`: array of ASCII string literals of the firmware files of +/// the kernel module. #[proc_macro] pub fn module(ts: TokenStream) -> TokenStream { module::module(ts) diff --git a/rust/macros/module.rs b/rust/macros/module.rs index acd0393b5095..411dc103d82e 100644 --- a/rust/macros/module.rs +++ b/rust/macros/module.rs @@ -97,14 +97,22 @@ struct ModuleInfo { author: Option, description: Option, alias: Option>, + firmware: Option>, } impl ModuleInfo { fn parse(it: &mut token_stream::IntoIter) -> Self { let mut info = ModuleInfo::default(); - const EXPECTED_KEYS: &[&str] = - &["type", "name", "author", "description", "license", "alias"]; + const EXPECTED_KEYS: &[&str] = &[ + "type", + "name", + "author", + "description", + "license", + "alias", + "firmware", + ]; const REQUIRED_KEYS: &[&str] = &["type", "name", "license"]; let mut seen_keys = Vec::new(); @@ -131,6 +139,7 @@ impl ModuleInfo { "description" => info.description = Some(expect_string(it)), "license" => info.license = expect_string_ascii(it), "alias" => info.alias = Some(expect_string_array(it)), + "firmware" => info.firmware = Some(expect_string_array(it)), _ => panic!( "Unknown key \"{}\". Valid keys are: {:?}.", key, EXPECTED_KEYS @@ -186,6 +195,11 @@ pub(crate) fn module(ts: TokenStream) -> TokenStream { modinfo.emit("alias", &alias); } } + if let Some(firmware) = info.firmware { + for fw in firmware { + modinfo.emit("firmware", &fw); + } + } // Built-in modules also export the `file` modinfo string. let file = -- cgit v1.2.3-70-g09d2 From e516211f615fb54ce3429870eefc17469ae289b8 Mon Sep 17 00:00:00 2001 From: Miguel Ojeda Date: Tue, 9 Jul 2024 18:05:56 +0200 Subject: rust: macros: indent list item in `paste!`'s docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A new style lint, `doc_lazy_continuation` [1], has been introduced in the upcoming Rust 1.80 (currently in beta), which detects missing indentation in code documentation. We have one such case: error: doc list item missing indentation --> rust/macros/lib.rs:315:5 | 315 | /// default the span of the `[< >]` group is used. | ^ | = help: if this is supposed to be its own paragraph, add a blank line = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation = note: `-D clippy::doc-lazy-continuation` implied by `-D clippy::style` = help: to override `-D clippy::style` add `#[allow(clippy::doc_lazy_continuation)]` help: indent this line | 315 | /// default the span of the `[< >]` group is used. | ++ While the rendering of the docs by `rustdoc` is not affected, we apply this kind of indentation elsewhere since it looks better. Thus clean it up. Link: https://rust-lang.github.io/rust-clippy/master/index.html#/doc_lazy_continuation [1] Reviewed-by: Björn Roy Baron Reviewed-by: Finn Behrens Tested-by: Benno Lossin Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20240709160615.998336-2-ojeda@kernel.org Signed-off-by: Miguel Ojeda --- rust/macros/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'rust/macros/lib.rs') diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs index 6dcc72aff111..159e75292970 100644 --- a/rust/macros/lib.rs +++ b/rust/macros/lib.rs @@ -345,7 +345,7 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream { /// /// Currently supported modifiers are: /// * `span`: change the span of concatenated identifier to the span of the specified token. By -/// default the span of the `[< >]` group is used. +/// default the span of the `[< >]` group is used. /// * `lower`: change the identifier to lower case. /// * `upper`: change the identifier to upper case. /// -- cgit v1.2.3-70-g09d2