Nouveau - Mar 2025 - [PATCH v5 2/5] rust: firmware: introduce `firmware::ModInfoBuilder`

The `firmware` field of the `module!` only accepts literal strings,
which is due to the fact that it is implemented as a proc macro.

Some drivers require a lot of firmware files (such as nova-core) and
hence benefit from more flexibility composing firmware path strings.

The `firmware::ModInfoBuilder` is a helper component to flexibly compose
firmware path strings for the .modinfo section in const context.

It is meant to be used in combination with `kernel::module_firmware!`,
which is introduced in a subsequent patch.

Co-developed-by: Alice Ryhl <aliceryhl at google.com>
Signed-off-by: Alice Ryhl <aliceryhl at google.com>
Signed-off-by: Danilo Krummrich <dakr at kernel.org>
---
 rust/kernel/firmware.rs | 98 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/rust/kernel/firmware.rs b/rust/kernel/firmware.rs
index c5162fdc95ff..6e6972d94597 100644
--- a/rust/kernel/firmware.rs
+++ b/rust/kernel/firmware.rs
@@ -115,3 +115,101 @@ unsafe impl Send for Firmware {}
 // SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references
to which are safe to
 // be used from any thread.
 unsafe impl Sync for Firmware {}
+
+/// Builder for firmware module info.
+///
+/// [`ModInfoBuilder`] is a helper component to flexibly compose firmware paths
strings for the
+/// .modinfo section in const context.
+///
+/// It is meant to be used in combination with [`kernel::module_firmware!`].
+///
+/// For more details and an example, see [`kernel::module_firmware!`].
+pub struct ModInfoBuilder<const N: usize> {
+    buf: [u8; N],
+    n: usize,
+    module_name: &'static CStr,
+}
+
+impl<const N: usize> ModInfoBuilder<N> {
+    /// Create an empty builder instance.
+    pub const fn new(module_name: &'static CStr) -> Self {
+        Self {
+            buf: [0; N],
+            n: 0,
+            module_name,
+        }
+    }
+
+    const fn push_internal(mut self, bytes: &[u8]) -> Self {
+        let mut j = 0;
+
+        if N == 0 {
+            self.n += bytes.len();
+            return self;
+        }
+
+        while j < bytes.len() {
+            if self.n < N {
+                self.buf[self.n] = bytes[j];
+            }
+            self.n += 1;
+            j += 1;
+        }
+        self
+    }
+
+    /// Push an additional path component.
+    ///
+    /// After a new [`ModInfoBuilder`] instance has been created,
[`ModInfoBuilder::prepare`] must
+    /// be called before adding path components.
+    pub const fn push(self, s: &str) -> Self {
+        if N != 0 && self.n == 0 {
+            crate::build_error!("Must call prepare() before
push().");
+        }
+
+        self.push_internal(s.as_bytes())
+    }
+
+    const fn prepare_module_name(self) -> Self {
+        let mut this = self;
+        let module_name = this.module_name;
+
+        if !this.module_name.is_empty() {
+            this = this.push_internal(module_name.as_bytes_with_nul());
+
+            if N != 0 {
+                // Re-use the space taken by the NULL terminator and swap it
with the '.' separator.
+                this.buf[this.n - 1] = b'.';
+            }
+        }
+
+        this.push_internal(b"firmware=")
+    }
+
+    /// Prepare for the next module info entry.
+    ///
+    /// Must be called before [`ModInfoBuilder::push`] can be called.
+    pub const fn prepare(self) -> Self {
+        self.push_internal(b"\0").prepare_module_name()
+    }
+
+    /// Build the byte array.
+    pub const fn build(self) -> [u8; N] {
+        // Add the final NULL terminator.
+        let this = self.push_internal(b"\0");
+
+        if this.n == N {
+            this.buf
+        } else {
+            crate::build_error!("Length mismatch.");
+        }
+    }
+}
+
+impl ModInfoBuilder<0> {
+    /// Return the length of the byte array to build.
+    pub const fn build_length(self) -> usize {
+        // Compensate for the NULL terminator added by `build`.
+        self.n + 1
+    }
+}
-- 
2.48.1

On Tue, Mar 04, 2025 at 06:34:49PM +0100, Danilo Krummrich
wrote:
> The `firmware` field of the `module!` only accepts literal strings,
> which is due to the fact that it is implemented as a proc macro.
> 
> Some drivers require a lot of firmware files (such as nova-core) and
> hence benefit from more flexibility composing firmware path strings.
> 
> The `firmware::ModInfoBuilder` is a helper component to flexibly compose
> firmware path strings for the .modinfo section in const context.
> 
> It is meant to be used in combination with `kernel::module_firmware!`,
> which is introduced in a subsequent patch.
Ditto.
> 
> Co-developed-by: Alice Ryhl <aliceryhl at google.com>
> Signed-off-by: Alice Ryhl <aliceryhl at google.com>
> Signed-off-by: Danilo Krummrich <dakr at kernel.org>
> ---
>  rust/kernel/firmware.rs | 98 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 98 insertions(+)
> 
> diff --git a/rust/kernel/firmware.rs b/rust/kernel/firmware.rs
> index c5162fdc95ff..6e6972d94597 100644
> --- a/rust/kernel/firmware.rs
> +++ b/rust/kernel/firmware.rs
> @@ -115,3 +115,101 @@ unsafe impl Send for Firmware {}
>  // SAFETY: `Firmware` only holds a pointer to a C `struct firmware`,
references to which are safe to
>  // be used from any thread.
>  unsafe impl Sync for Firmware {}
> +
> +/// Builder for firmware module info.
> +///
> +/// [`ModInfoBuilder`] is a helper component to flexibly compose firmware
paths strings for the
> +/// .modinfo section in const context.
> +///
> +/// It is meant to be used in combination with
[`kernel::module_firmware!`].
> +///
> +/// For more details and an example, see [`kernel::module_firmware!`].
> +pub struct ModInfoBuilder<const N: usize> {
> +    buf: [u8; N],
> +    n: usize,
> +    module_name: &'static CStr,
> +}
> +
> +impl<const N: usize> ModInfoBuilder<N> {
> +    /// Create an empty builder instance.
> +    pub const fn new(module_name: &'static CStr) -> Self {
> +        Self {
> +            buf: [0; N],
> +            n: 0,
> +            module_name,
> +        }
> +    }
> +
> +    const fn push_internal(mut self, bytes: &[u8]) -> Self {
> +        let mut j = 0;
> +
> +        if N == 0 {
> +            self.n += bytes.len();
> +            return self;
> +        }
> +
> +        while j < bytes.len() {
> +            if self.n < N {
> +                self.buf[self.n] = bytes[j];
> +            }
> +            self.n += 1;
> +            j += 1;
> +        }
> +        self
> +    }
> +
> +    /// Push an additional path component.
> +    ///
> +    /// After a new [`ModInfoBuilder`] instance has been created,
[`ModInfoBuilder::prepare`] must
> +    /// be called before adding path components.
> +    pub const fn push(self, s: &str) -> Self {
> +        if N != 0 && self.n == 0 {
> +            crate::build_error!("Must call prepare() before
push().");
> +        }
> +
> +        self.push_internal(s.as_bytes())
> +    }
> +
> +    const fn prepare_module_name(self) -> Self {
> +        let mut this = self;
> +        let module_name = this.module_name;
> +
> +        if !this.module_name.is_empty() {
> +            this = this.push_internal(module_name.as_bytes_with_nul());
> +
> +            if N != 0 {
> +                // Re-use the space taken by the NULL terminator and swap
it with the '.' separator.
> +                this.buf[this.n - 1] = b'.';
> +            }
> +        }
> +
> +        this.push_internal(b"firmware=")
> +    }
> +
> +    /// Prepare for the next module info entry.
> +    ///
> +    /// Must be called before [`ModInfoBuilder::push`] can be called.
> +    pub const fn prepare(self) -> Self {
> +        self.push_internal(b"\0").prepare_module_name()
> +    }
> +
> +    /// Build the byte array.
> +    pub const fn build(self) -> [u8; N] {
> +        // Add the final NULL terminator.
> +        let this = self.push_internal(b"\0");
> +
> +        if this.n == N {
> +            this.buf
> +        } else {
> +            crate::build_error!("Length mismatch.");
> +        }
> +    }
> +}
> +
> +impl ModInfoBuilder<0> {
> +    /// Return the length of the byte array to build.
> +    pub const fn build_length(self) -> usize {
> +        // Compensate for the NULL terminator added by `build`.
> +        self.n + 1
> +    }
> +}
> -- 
> 2.48.1
> 
> 
BR, Jarkko

On Wed, Mar 05, 2025 at 10:30:31PM +0000, Benno Lossin
wrote:
> On Tue Mar 4, 2025 at 6:34 PM CET, Danilo Krummrich wrote:
> > The `firmware` field of the `module!` only accepts literal strings,
> > which is due to the fact that it is implemented as a proc macro.
> >
> > Some drivers require a lot of firmware files (such as nova-core) and
> > hence benefit from more flexibility composing firmware path strings.
> >
> > The `firmware::ModInfoBuilder` is a helper component to flexibly
compose
> > firmware path strings for the .modinfo section in const context.
> >
> > It is meant to be used in combination with `kernel::module_firmware!`,
> > which is introduced in a subsequent patch.
> >
> > Co-developed-by: Alice Ryhl <aliceryhl at google.com>
> > Signed-off-by: Alice Ryhl <aliceryhl at google.com>
> > Signed-off-by: Danilo Krummrich <dakr at kernel.org>
> > ---
> >  rust/kernel/firmware.rs | 98
+++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 98 insertions(+)
> >
> > diff --git a/rust/kernel/firmware.rs b/rust/kernel/firmware.rs
> > index c5162fdc95ff..6e6972d94597 100644
> > --- a/rust/kernel/firmware.rs
> > +++ b/rust/kernel/firmware.rs
> > @@ -115,3 +115,101 @@ unsafe impl Send for Firmware {}
> >  // SAFETY: `Firmware` only holds a pointer to a C `struct firmware`,
references to which are safe to
> >  // be used from any thread.
> >  unsafe impl Sync for Firmware {}
> > +
> > +/// Builder for firmware module info.
> > +///
> > +/// [`ModInfoBuilder`] is a helper component to flexibly compose
firmware paths strings for the
> > +/// .modinfo section in const context.
> > +///
> > +/// It is meant to be used in combination with
[`kernel::module_firmware!`].
> > +///
> > +/// For more details and an example, see
[`kernel::module_firmware!`].
> > +pub struct ModInfoBuilder<const N: usize> {
> > +    buf: [u8; N],
> > +    n: usize,
> > +    module_name: &'static CStr,
> > +}
> > +
> > +impl<const N: usize> ModInfoBuilder<N> {
> > +    /// Create an empty builder instance.
> > +    pub const fn new(module_name: &'static CStr) -> Self {
> > +        Self {
> > +            buf: [0; N],
> > +            n: 0,
> > +            module_name,
> > +        }
> > +    }
> > +
> > +    const fn push_internal(mut self, bytes: &[u8]) -> Self {
> > +        let mut j = 0;
> > +
> > +        if N == 0 {
> > +            self.n += bytes.len();
> > +            return self;
> > +        }
> > +
> > +        while j < bytes.len() {
> > +            if self.n < N {
> > +                self.buf[self.n] = bytes[j];
> > +            }
> > +            self.n += 1;
> > +            j += 1;
> > +        }
> > +        self
> > +    }
> > +
> > +    /// Push an additional path component.
> > +    ///
> > +    /// After a new [`ModInfoBuilder`] instance has been created,
[`ModInfoBuilder::prepare`] must
> > +    /// be called before adding path components.
> > +    pub const fn push(self, s: &str) -> Self {
> > +        if N != 0 && self.n == 0 {
> > +            crate::build_error!("Must call prepare() before
push().");
> 
> This will only prevent the first `prepare` call being missed, right?
Correct, unfortunately there's no way to detect subsequent ones.
> 
> > +        }
> > +
> > +        self.push_internal(s.as_bytes())
> > +    }
> > +
> > +    const fn prepare_module_name(self) -> Self {
> > +        let mut this = self;
> > +        let module_name = this.module_name;
> > +
> > +        if !this.module_name.is_empty() {
> > +            this =
this.push_internal(module_name.as_bytes_with_nul());
> > +
> > +            if N != 0 {
> > +                // Re-use the space taken by the NULL terminator and
swap it with the '.' separator.
> > +                this.buf[this.n - 1] = b'.';
> > +            }
> > +        }
> > +
> > +        this.push_internal(b"firmware=")
> > +    }
> > +
> > +    /// Prepare for the next module info entry.
> > +    ///
> > +    /// Must be called before [`ModInfoBuilder::push`] can be called.
> 
> If you always have to call this before `push`, why not inline it there?
You can push() multiple times to compose the firmware path string (which is the
whole purpose :).

Example from nova-core:

	pub(crate) struct ModInfoBuilder<const N:
usize>(firmware::ModInfoBuilder<N>);
	
	impl<const N: usize> ModInfoBuilder<N> {
	    const fn make_entry_file(self, chipset: &str, fw: &str) -> Self
{
	        let version = "535.113.01";
	
	        ModInfoBuilder(
	            self.0
	                .prepare()
	                .push("nvidia/")
	                .push(chipset)
	                .push("/gsp/")
	                .push(fw)
	                .push("-")
	                .push(version)
	                .push(".bin"),
	        )
	    }
	
	    const fn make_entry_chipset(self, chipset: &str) -> Self {
	        self.make_entry_file(chipset, "booter_load")
	            .make_entry_file(chipset, "booter_unload")
	            .make_entry_file(chipset, "bootloader")
	            .make_entry_file(chipset, "gsp")
	    }
	
	    pub(crate) const fn create(
	        module_name: &'static kernel::str::CStr,
	    ) -> firmware::ModInfoBuilder<N> {
	        let mut this = Self(firmware::ModInfoBuilder::new(module_name));
	        let mut i = 0;
	
	        while i < gpu::Chipset::NAMES.len() {
	            this = this.make_entry_chipset(gpu::Chipset::NAMES[i]);
	            i += 1;
	        }
	
	        this.0
	    }
	}

On Tue Mar 4, 2025 at 6:34 PM CET, Danilo Krummrich
wrote:
> The `firmware` field of the `module!` only accepts literal strings,
> which is due to the fact that it is implemented as a proc macro.
>
> Some drivers require a lot of firmware files (such as nova-core) and
> hence benefit from more flexibility composing firmware path strings.
>
> The `firmware::ModInfoBuilder` is a helper component to flexibly compose
> firmware path strings for the .modinfo section in const context.
>
> It is meant to be used in combination with `kernel::module_firmware!`,
> which is introduced in a subsequent patch.
>
> Co-developed-by: Alice Ryhl <aliceryhl at google.com>
> Signed-off-by: Alice Ryhl <aliceryhl at google.com>
> Signed-off-by: Danilo Krummrich <dakr at kernel.org>
> ---
>  rust/kernel/firmware.rs | 98 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 98 insertions(+)
>
> diff --git a/rust/kernel/firmware.rs b/rust/kernel/firmware.rs
> index c5162fdc95ff..6e6972d94597 100644
> --- a/rust/kernel/firmware.rs
> +++ b/rust/kernel/firmware.rs
> @@ -115,3 +115,101 @@ unsafe impl Send for Firmware {}
>  // SAFETY: `Firmware` only holds a pointer to a C `struct firmware`,
references to which are safe to
>  // be used from any thread.
>  unsafe impl Sync for Firmware {}
> +
> +/// Builder for firmware module info.
> +///
> +/// [`ModInfoBuilder`] is a helper component to flexibly compose firmware
paths strings for the
> +/// .modinfo section in const context.
> +///
> +/// It is meant to be used in combination with
[`kernel::module_firmware!`].
> +///
> +/// For more details and an example, see [`kernel::module_firmware!`].
> +pub struct ModInfoBuilder<const N: usize> {
> +    buf: [u8; N],
> +    n: usize,
> +    module_name: &'static CStr,
> +}
> +
> +impl<const N: usize> ModInfoBuilder<N> {
> +    /// Create an empty builder instance.
> +    pub const fn new(module_name: &'static CStr) -> Self {
> +        Self {
> +            buf: [0; N],
> +            n: 0,
> +            module_name,
> +        }
> +    }
> +
> +    const fn push_internal(mut self, bytes: &[u8]) -> Self {
> +        let mut j = 0;
> +
> +        if N == 0 {
> +            self.n += bytes.len();
> +            return self;
> +        }
> +
> +        while j < bytes.len() {
> +            if self.n < N {
> +                self.buf[self.n] = bytes[j];
> +            }
> +            self.n += 1;
> +            j += 1;
> +        }
> +        self
> +    }
> +
> +    /// Push an additional path component.
> +    ///
> +    /// After a new [`ModInfoBuilder`] instance has been created,
[`ModInfoBuilder::prepare`] must
> +    /// be called before adding path components.
> +    pub const fn push(self, s: &str) -> Self {
> +        if N != 0 && self.n == 0 {
> +            crate::build_error!("Must call prepare() before
push().");
This will only prevent the first `prepare` call being missed, right?
> +        }
> +
> +        self.push_internal(s.as_bytes())
> +    }
> +
> +    const fn prepare_module_name(self) -> Self {
> +        let mut this = self;
> +        let module_name = this.module_name;
> +
> +        if !this.module_name.is_empty() {
> +            this = this.push_internal(module_name.as_bytes_with_nul());
> +
> +            if N != 0 {
> +                // Re-use the space taken by the NULL terminator and swap
it with the '.' separator.
> +                this.buf[this.n - 1] = b'.';
> +            }
> +        }
> +
> +        this.push_internal(b"firmware=")
> +    }
> +
> +    /// Prepare for the next module info entry.
> +    ///
> +    /// Must be called before [`ModInfoBuilder::push`] can be called.
If you always have to call this before `push`, why not inline it there?

---
Cheers,
Benno
> +    pub const fn prepare(self) -> Self {
> +        self.push_internal(b"\0").prepare_module_name()
> +    }
> +
> +    /// Build the byte array.
> +    pub const fn build(self) -> [u8; N] {
> +        // Add the final NULL terminator.
> +        let this = self.push_internal(b"\0");
> +
> +        if this.n == N {
> +            this.buf
> +        } else {
> +            crate::build_error!("Length mismatch.");
> +        }
> +    }
> +}
> +
> +impl ModInfoBuilder<0> {
> +    /// Return the length of the byte array to build.
> +    pub const fn build_length(self) -> usize {
> +        // Compensate for the NULL terminator added by `build`.
> +        self.n + 1
> +    }
> +}
> --
> 2.48.1