projects/linux·blob master · refs

383 lines · 12.4 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! Firmware abstraction
4//!
5//! C header: [`include/linux/firmware.h`](srctree/include/linux/firmware.h)
6
7use crate::{
8 bindings,
9 device::Device,
10 error::to_result,
11 ffi,
12 prelude::*,
13 str::{CStr, CStrExt as _},
14};
15use core::ptr::NonNull;
16
17/// # Invariants
18///
19/// One of the following: `bindings::request_firmware`, `bindings::firmware_request_nowarn`,
20/// `bindings::firmware_request_platform`, `bindings::request_firmware_direct`.
21struct FwFunc(
22 unsafe extern "C" fn(
23 *mut *const bindings::firmware,
24 *const ffi::c_char,
25 *mut bindings::device,
26 ) -> i32,
27);
28
29impl FwFunc {
30 fn request() -> Self {
31 Self(bindings::request_firmware)
32 }
33
34 fn request_nowarn() -> Self {
35 Self(bindings::firmware_request_nowarn)
36 }
37}
38
39/// Abstraction around a C `struct firmware`.
40///
41/// This is a simple abstraction around the C firmware API. Just like with the C API, firmware can
42/// be requested. Once requested the abstraction provides direct access to the firmware buffer as
43/// `&[u8]`. The firmware is released once [`Firmware`] is dropped.
44///
45/// # Invariants
46///
47/// The pointer is valid, and has ownership over the instance of `struct firmware`.
48///
49/// The `Firmware`'s backing buffer is not modified.
50///
51/// # Examples
52///
53/// ```no_run
54/// # use kernel::{device::Device, firmware::Firmware, sync::aref::ARef};
55/// # fn no_run(dev: ARef<Device>) -> Result<(), Error> {
56/// let fw = Firmware::request(c"path/to/firmware.bin", &dev)?;
57/// let blob = fw.data();
58///
59/// # Ok(())
60/// # }
61/// ```
62pub struct Firmware(NonNull<bindings::firmware>);
63
64impl Firmware {
65 fn request_internal(name: &CStr, dev: &Device, func: FwFunc) -> Result<Self> {
66 let mut fw: *mut bindings::firmware = core::ptr::null_mut();
67 let pfw: *mut *mut bindings::firmware = &mut fw;
68 let pfw: *mut *const bindings::firmware = pfw.cast();
69
70 // SAFETY: `pfw` is a valid pointer to a NULL initialized `bindings::firmware` pointer.
71 // `name` and `dev` are valid as by their type invariants.
72 let ret = unsafe { func.0(pfw, name.as_char_ptr(), dev.as_raw()) };
73 if ret != 0 {
74 return Err(Error::from_errno(ret));
75 }
76
77 // SAFETY: `func` not bailing out with a non-zero error code, guarantees that `fw` is a
78 // valid pointer to `bindings::firmware`.
79 Ok(Firmware(unsafe { NonNull::new_unchecked(fw) }))
80 }
81
82 /// Send a firmware request and wait for it. See also `bindings::request_firmware`.
83 pub fn request(name: &CStr, dev: &Device) -> Result<Self> {
84 Self::request_internal(name, dev, FwFunc::request())
85 }
86
87 /// Send a request for an optional firmware module. See also
88 /// `bindings::firmware_request_nowarn`.
89 pub fn request_nowarn(name: &CStr, dev: &Device) -> Result<Self> {
90 Self::request_internal(name, dev, FwFunc::request_nowarn())
91 }
92
93 fn as_raw(&self) -> *mut bindings::firmware {
94 self.0.as_ptr()
95 }
96
97 /// Returns the size of the requested firmware in bytes.
98 pub fn size(&self) -> usize {
99 // SAFETY: `self.as_raw()` is valid by the type invariant.
100 unsafe { (*self.as_raw()).size }
101 }
102
103 /// Returns the requested firmware as `&[u8]`.
104 pub fn data(&self) -> &[u8] {
105 // SAFETY: `self.as_raw()` is valid by the type invariant. Additionally,
106 // `bindings::firmware` guarantees, if successfully requested, that
107 // `bindings::firmware::data` has a size of `bindings::firmware::size` bytes.
108 unsafe { core::slice::from_raw_parts((*self.as_raw()).data, self.size()) }
109 }
110}
111
112impl Drop for Firmware {
113 fn drop(&mut self) {
114 // SAFETY: `self.as_raw()` is valid by the type invariant.
115 unsafe { bindings::release_firmware(self.as_raw()) };
116 }
117}
118
119/// Load firmware directly into the caller-provided `buf`.
120///
121/// On success the firmware image has been copied into `buf`; the caller accesses the data
122/// through `buf` itself.
123///
124/// This is intentionally a stand-alone function rather than a `Firmware` constructor. For
125/// the `into_buf` path, the firmware data lives in the caller's `buf`, not in a
126/// kernel-owned buffer, so returning a `Firmware` would expose `Firmware::data()` as a
127/// second handle aliasing `buf` (and `release_firmware()` does not free `buf` anyway).
128pub fn request_into_buf(name: &CStr, dev: &Device, buf: &mut [u8]) -> Result {
129 // `as_mut_ptr()` on an empty slice returns a non-NULL pointer to
130 // memory which the loader does not own. Passing that pointer with `size == 0`
131 // makes the loader believe that it is buffer it allocated itself, so when
132 // `release_firmware()` is called, it will vfree the pointer and trigger a
133 // bug. Reject empty slices to avoid this situation.
134 if buf.is_empty() {
135 return Err(EINVAL);
136 }
137
138 let mut fw: *const bindings::firmware = core::ptr::null();
139
140 // SAFETY: `&raw mut fw` is a valid pointer to a NULL initialized `bindings::firmware` pointer.
141 // `name` and `dev` are valid as by their type invariants. `buf` is a valid writable
142 // buffer of `buf.len()` bytes.
143 to_result(unsafe {
144 bindings::request_firmware_into_buf(
145 &raw mut fw,
146 name.as_char_ptr(),
147 dev.as_raw(),
148 buf.as_mut_ptr().cast(),
149 buf.len(),
150 )
151 })?;
152
153 // The firmware bytes are now in `buf`, which the caller owns, so we don't need
154 // the kernel to hang on to it any more.
155 // SAFETY: `fw` is a valid pointer returned by `request_firmware_into_buf`.
156 unsafe { bindings::release_firmware(fw) };
157
158 Ok(())
159}
160
161// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, which is safe to be used from
162// any thread.
163unsafe impl Send for Firmware {}
164
165// SAFETY: `Firmware` only holds a pointer to a C `struct firmware`, references to which are safe to
166// be used from any thread.
167unsafe impl Sync for Firmware {}
168
169/// Create firmware .modinfo entries.
170///
171/// This macro is the counterpart of the C macro `MODULE_FIRMWARE()`, but instead of taking a
172/// simple string literals, which is already covered by the `firmware` field of
173/// [`crate::prelude::module!`], it allows the caller to pass a builder type, based on the
174/// [`ModInfoBuilder`], which can create the firmware modinfo strings in a more flexible way.
175///
176/// Drivers should extend the [`ModInfoBuilder`] with their own driver specific builder type.
177///
178/// The `builder` argument must be a type which implements the following function.
179///
180/// `const fn create(module_name: &'static CStr) -> ModInfoBuilder`
181///
182/// `create` should pass the `module_name` to the [`ModInfoBuilder`] and, with the help of
183/// it construct the corresponding firmware modinfo.
184///
185/// Typically, such contracts would be enforced by a trait, however traits do not (yet) support
186/// const functions.
187///
188/// # Examples
189///
190/// ```
191/// # mod module_firmware_test {
192/// # use kernel::firmware;
193/// # use kernel::prelude::*;
194/// #
195/// # struct MyModule;
196/// #
197/// # impl kernel::Module for MyModule {
198/// # fn init(_module: &'static ThisModule) -> Result<Self> {
199/// # Ok(Self)
200/// # }
201/// # }
202/// #
203/// #
204/// struct Builder<const N: usize>;
205///
206/// impl<const N: usize> Builder<N> {
207/// const DIR: &'static str = "vendor/chip/";
208/// const FILES: [&'static str; 3] = [ "foo", "bar", "baz" ];
209///
210/// const fn create(module_name: &'static kernel::str::CStr) -> firmware::ModInfoBuilder<N> {
211/// let mut builder = firmware::ModInfoBuilder::new(module_name);
212///
213/// let mut i = 0;
214/// while i < Self::FILES.len() {
215/// builder = builder.new_entry()
216/// .push(Self::DIR)
217/// .push(Self::FILES[i])
218/// .push(".bin");
219///
220/// i += 1;
221/// }
222///
223/// builder
224/// }
225/// }
226///
227/// module! {
228/// type: MyModule,
229/// name: "module_firmware_test",
230/// authors: ["Rust for Linux"],
231/// description: "module_firmware! test module",
232/// license: "GPL",
233/// }
234///
235/// kernel::module_firmware!(Builder);
236/// # }
237/// ```
238#[macro_export]
239macro_rules! module_firmware {
240 // The argument is the builder type without the const generic, since it's deferred from within
241 // this macro. Hence, we can neither use `expr` nor `ty`.
242 ($($builder:tt)*) => {
243 const _: () = {
244 const __MODULE_FIRMWARE_PREFIX: &'static $crate::str::CStr = if cfg!(MODULE) {
245 c""
246 } else {
247 <LocalModule as $crate::ModuleMetadata>::NAME
248 };
249
250 #[link_section = ".modinfo"]
251 #[used(compiler)]
252 static __MODULE_FIRMWARE: [u8; $($builder)*::create(__MODULE_FIRMWARE_PREFIX)
253 .build_length()] = $($builder)*::create(__MODULE_FIRMWARE_PREFIX).build();
254 };
255 };
256}
257
258/// Builder for firmware module info.
259///
260/// [`ModInfoBuilder`] is a helper component to flexibly compose firmware paths strings for the
261/// .modinfo section in const context.
262///
263/// Therefore the [`ModInfoBuilder`] provides the methods [`ModInfoBuilder::new_entry`] and
264/// [`ModInfoBuilder::push`], where the latter is used to push path components and the former to
265/// mark the beginning of a new path string.
266///
267/// [`ModInfoBuilder`] is meant to be used in combination with [`kernel::module_firmware!`].
268///
269/// The const generic `N` as well as the `module_name` parameter of [`ModInfoBuilder::new`] is an
270/// internal implementation detail and supplied through the above macro.
271pub struct ModInfoBuilder<const N: usize> {
272 buf: [u8; N],
273 n: usize,
274 module_name: &'static CStr,
275}
276
277impl<const N: usize> ModInfoBuilder<N> {
278 /// Create an empty builder instance.
279 pub const fn new(module_name: &'static CStr) -> Self {
280 Self {
281 buf: [0; N],
282 n: 0,
283 module_name,
284 }
285 }
286
287 const fn push_internal(mut self, bytes: &[u8]) -> Self {
288 let mut j = 0;
289
290 if N == 0 {
291 self.n += bytes.len();
292 return self;
293 }
294
295 while j < bytes.len() {
296 if self.n < N {
297 self.buf[self.n] = bytes[j];
298 }
299 self.n += 1;
300 j += 1;
301 }
302 self
303 }
304
305 /// Push an additional path component.
306 ///
307 /// Append path components to the [`ModInfoBuilder`] instance. Paths need to be separated
308 /// with [`ModInfoBuilder::new_entry`].
309 ///
310 /// # Examples
311 ///
312 /// ```
313 /// use kernel::firmware::ModInfoBuilder;
314 ///
315 /// # const DIR: &str = "vendor/chip/";
316 /// # const fn no_run<const N: usize>(builder: ModInfoBuilder<N>) {
317 /// let builder = builder.new_entry()
318 /// .push(DIR)
319 /// .push("foo.bin")
320 /// .new_entry()
321 /// .push(DIR)
322 /// .push("bar.bin");
323 /// # }
324 /// ```
325 pub const fn push(self, s: &str) -> Self {
326 // Check whether there has been an initial call to `next_entry()`.
327 if N != 0 && self.n == 0 {
328 crate::build_error!("Must call next_entry() before push().");
329 }
330
331 self.push_internal(s.as_bytes())
332 }
333
334 const fn push_module_name(self) -> Self {
335 let mut this = self;
336 let module_name = this.module_name;
337
338 if !this.module_name.is_empty() {
339 this = this.push_internal(module_name.to_bytes_with_nul());
340
341 if N != 0 {
342 // Re-use the space taken by the NULL terminator and swap it with the '.' separator.
343 this.buf[this.n - 1] = b'.';
344 }
345 }
346
347 this
348 }
349
350 /// Prepare the [`ModInfoBuilder`] for the next entry.
351 ///
352 /// This method acts as a separator between module firmware path entries.
353 ///
354 /// Must be called before constructing a new entry with subsequent calls to
355 /// [`ModInfoBuilder::push`].
356 ///
357 /// See [`ModInfoBuilder::push`] for an example.
358 pub const fn new_entry(self) -> Self {
359 self.push_internal(b"\0")
360 .push_module_name()
361 .push_internal(b"firmware=")
362 }
363
364 /// Build the byte array.
365 pub const fn build(self) -> [u8; N] {
366 // Add the final NULL terminator.
367 let this = self.push_internal(b"\0");
368
369 if this.n == N {
370 this.buf
371 } else {
372 crate::build_error!("Length mismatch.");
373 }
374 }
375}
376
377impl ModInfoBuilder<0> {
378 /// Return the length of the byte array to build.
379 pub const fn build_length(self) -> usize {
380 // Compensate for the NULL terminator added by `build`.
381 self.n + 1
382 }
383}