rust: firmware: introduce `firmware::ModInfoBuilder`

// 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.

///

/// Therefore the [`ModInfoBuilder`] provides the methods [`ModInfoBuilder::new_entry`] and

/// [`ModInfoBuilder::push`], where the latter is used to push path components and the former to

/// mark the beginning of a new path string.

///

/// [`ModInfoBuilder`] is meant to be used in combination with `kernel::module_firmware!`.

///

/// The const generic `N` as well as the `module_name` parameter of [`ModInfoBuilder::new`] is an

/// internal implementation detail and supplied through the above macro.

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.

    ///

    /// Append path components to the [`ModInfoBuilder`] instance. Paths need to be separated

    /// with [`ModInfoBuilder::new_entry`].

    ///

    /// # Example

    ///

    /// ```

    /// use kernel::firmware::ModInfoBuilder;

    ///

    /// # const DIR: &str = "vendor/chip/";

    /// # const fn no_run<const N: usize>(builder: ModInfoBuilder<N>) {

    /// let builder = builder.new_entry()

    ///     .push(DIR)

    ///     .push("foo.bin")

    ///     .new_entry()

    ///     .push(DIR)

    ///     .push("bar.bin");

    /// # }

    /// ```

    pub const fn push(self, s: &str) -> Self {

        // Check whether there has been an initial call to `next_entry()`.

        if N != 0 && self.n == 0 {

            crate::build_error!("Must call next_entry() before push().");

        }

        self.push_internal(s.as_bytes())

    }

    const fn push_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

    }

    /// Prepare the [`ModInfoBuilder`] for the next entry.

    ///

    /// This method acts as a separator between module firmware path entries.

    ///

    /// Must be called before constructing a new entry with subsequent calls to

    /// [`ModInfoBuilder::push`].

    ///

    /// See [`ModInfoBuilder::push`] for an example.

    pub const fn new_entry(self) -> Self {

        self.push_internal(b"\0")

            .push_module_name()

            .push_internal(b"firmware=")

    }

    /// 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

    }

}