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 7 use crate::{ 8 bindings, 9 device::Device, 10 error::to_result, 11 ffi, 12 prelude::*, 13 str::{CStr, CStrExt as _}, 14 }; 15 use 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`. 21 struct FwFunc( 22 unsafe extern "C" fn( 23 *mut *const bindings::firmware, 24 *const ffi::c_char, 25 *mut bindings::device, 26 ) -> i32, 27 ); 28 29 impl 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 /// ``` 62 pub struct Firmware(NonNull<bindings::firmware>); 63 64 impl 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 112 impl 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). 128 pub 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. 163 unsafe 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. 167 unsafe 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] 239 macro_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. 271 pub struct ModInfoBuilder<const N: usize> { 272 buf: [u8; N], 273 n: usize, 274 module_name: &'static CStr, 275 } 276 277 impl<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 377 impl 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 } 384