1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Contains structures and functions dedicated to the parsing, building and patching of firmwares 4 //! to be loaded into a given execution unit. 5 6 use core::marker::PhantomData; 7 use core::ops::Deref; 8 9 use kernel::{ 10 device, 11 firmware, 12 prelude::*, 13 str::CString, 14 transmute::FromBytes, // 15 }; 16 17 use crate::{ 18 falcon::{ 19 FalconDmaLoadTarget, 20 FalconFirmware, // 21 }, 22 gpu, 23 num::{ 24 FromSafeCast, 25 IntoSafeCast, // 26 }, 27 }; 28 29 pub(crate) mod booter; 30 pub(crate) mod fwsec; 31 pub(crate) mod gsp; 32 pub(crate) mod riscv; 33 34 pub(crate) const FIRMWARE_VERSION: &str = "570.144"; 35 36 /// Requests the GPU firmware `name` suitable for `chipset`, with version `ver`. 37 fn request_firmware( 38 dev: &device::Device, 39 chipset: gpu::Chipset, 40 name: &str, 41 ver: &str, 42 ) -> Result<firmware::Firmware> { 43 let chip_name = chipset.name(); 44 45 CString::try_from_fmt(fmt!("nvidia/{chip_name}/gsp/{name}-{ver}.bin")) 46 .and_then(|path| firmware::Firmware::request(&path, dev)) 47 } 48 49 /// Structure used to describe some firmwares, notably FWSEC-FRTS. 50 #[repr(C)] 51 #[derive(Debug, Clone, FromBytes)] 52 pub(crate) struct FalconUCodeDescV2 { 53 /// Header defined by 'NV_BIT_FALCON_UCODE_DESC_HEADER_VDESC*' in OpenRM. 54 hdr: u32, 55 /// Stored size of the ucode after the header, compressed or uncompressed 56 stored_size: u32, 57 /// Uncompressed size of the ucode. If store_size == uncompressed_size, then the ucode 58 /// is not compressed. 59 pub(crate) uncompressed_size: u32, 60 /// Code entry point 61 pub(crate) virtual_entry: u32, 62 /// Offset after the code segment at which the Application Interface Table headers are located. 63 pub(crate) interface_offset: u32, 64 /// Base address at which to load the code segment into 'IMEM'. 65 pub(crate) imem_phys_base: u32, 66 /// Size in bytes of the code to copy into 'IMEM' (includes both secure and non-secure 67 /// segments). 68 pub(crate) imem_load_size: u32, 69 /// Virtual 'IMEM' address (i.e. 'tag') at which the code should start. 70 pub(crate) imem_virt_base: u32, 71 /// Virtual address of secure IMEM segment. 72 pub(crate) imem_sec_base: u32, 73 /// Size of secure IMEM segment. 74 pub(crate) imem_sec_size: u32, 75 /// Offset into stored (uncompressed) image at which DMEM begins. 76 pub(crate) dmem_offset: u32, 77 /// Base address at which to load the data segment into 'DMEM'. 78 pub(crate) dmem_phys_base: u32, 79 /// Size in bytes of the data to copy into 'DMEM'. 80 pub(crate) dmem_load_size: u32, 81 /// "Alternate" Size of data to load into IMEM. 82 pub(crate) alt_imem_load_size: u32, 83 /// "Alternate" Size of data to load into DMEM. 84 pub(crate) alt_dmem_load_size: u32, 85 } 86 87 /// Structure used to describe some firmwares, notably FWSEC-FRTS. 88 #[repr(C)] 89 #[derive(Debug, Clone)] 90 pub(crate) struct FalconUCodeDescV3 { 91 /// Header defined by `NV_BIT_FALCON_UCODE_DESC_HEADER_VDESC*` in OpenRM. 92 hdr: u32, 93 /// Stored size of the ucode after the header. 94 stored_size: u32, 95 /// Offset in `DMEM` at which the signature is expected to be found. 96 pub(crate) pkc_data_offset: u32, 97 /// Offset after the code segment at which the app headers are located. 98 pub(crate) interface_offset: u32, 99 /// Base address at which to load the code segment into `IMEM`. 100 pub(crate) imem_phys_base: u32, 101 /// Size in bytes of the code to copy into `IMEM`. 102 pub(crate) imem_load_size: u32, 103 /// Virtual `IMEM` address (i.e. `tag`) at which the code should start. 104 pub(crate) imem_virt_base: u32, 105 /// Base address at which to load the data segment into `DMEM`. 106 pub(crate) dmem_phys_base: u32, 107 /// Size in bytes of the data to copy into `DMEM`. 108 pub(crate) dmem_load_size: u32, 109 /// Mask of the falcon engines on which this firmware can run. 110 pub(crate) engine_id_mask: u16, 111 /// ID of the ucode used to infer a fuse register to validate the signature. 112 pub(crate) ucode_id: u8, 113 /// Number of signatures in this firmware. 114 pub(crate) signature_count: u8, 115 /// Versions of the signatures, used to infer a valid signature to use. 116 pub(crate) signature_versions: u16, 117 _reserved: u16, 118 } 119 120 // SAFETY: all bit patterns are valid for this type, and it doesn't use 121 // interior mutability. 122 unsafe impl FromBytes for FalconUCodeDescV3 {} 123 124 /// Enum wrapping the different versions of Falcon microcode descriptors. 125 /// 126 /// This allows handling both V2 and V3 descriptor formats through a 127 /// unified type, providing version-agnostic access to firmware metadata 128 /// via the [`FalconUCodeDescriptor`] trait. 129 #[derive(Debug, Clone)] 130 pub(crate) enum FalconUCodeDesc { 131 V2(FalconUCodeDescV2), 132 V3(FalconUCodeDescV3), 133 } 134 135 impl Deref for FalconUCodeDesc { 136 type Target = dyn FalconUCodeDescriptor; 137 138 fn deref(&self) -> &Self::Target { 139 match self { 140 FalconUCodeDesc::V2(v2) => v2, 141 FalconUCodeDesc::V3(v3) => v3, 142 } 143 } 144 } 145 146 /// Trait providing a common interface for accessing Falcon microcode descriptor fields. 147 /// 148 /// This trait abstracts over the different descriptor versions ([`FalconUCodeDescV2`] and 149 /// [`FalconUCodeDescV3`]), allowing code to work with firmware metadata without needing to 150 /// know the specific descriptor version. Fields not present return zero. 151 pub(crate) trait FalconUCodeDescriptor { 152 fn hdr(&self) -> u32; 153 fn imem_load_size(&self) -> u32; 154 fn interface_offset(&self) -> u32; 155 fn dmem_load_size(&self) -> u32; 156 fn pkc_data_offset(&self) -> u32; 157 fn engine_id_mask(&self) -> u16; 158 fn ucode_id(&self) -> u8; 159 fn signature_count(&self) -> u8; 160 fn signature_versions(&self) -> u16; 161 162 /// Returns the size in bytes of the header. 163 fn size(&self) -> usize { 164 let hdr = self.hdr(); 165 166 const HDR_SIZE_SHIFT: u32 = 16; 167 const HDR_SIZE_MASK: u32 = 0xffff0000; 168 ((hdr & HDR_SIZE_MASK) >> HDR_SIZE_SHIFT).into_safe_cast() 169 } 170 171 fn imem_sec_load_params(&self) -> FalconDmaLoadTarget; 172 fn imem_ns_load_params(&self) -> Option<FalconDmaLoadTarget>; 173 fn dmem_load_params(&self) -> FalconDmaLoadTarget; 174 } 175 176 impl FalconUCodeDescriptor for FalconUCodeDescV2 { 177 fn hdr(&self) -> u32 { 178 self.hdr 179 } 180 fn imem_load_size(&self) -> u32 { 181 self.imem_load_size 182 } 183 fn interface_offset(&self) -> u32 { 184 self.interface_offset 185 } 186 fn dmem_load_size(&self) -> u32 { 187 self.dmem_load_size 188 } 189 fn pkc_data_offset(&self) -> u32 { 190 0 191 } 192 fn engine_id_mask(&self) -> u16 { 193 0 194 } 195 fn ucode_id(&self) -> u8 { 196 0 197 } 198 fn signature_count(&self) -> u8 { 199 0 200 } 201 fn signature_versions(&self) -> u16 { 202 0 203 } 204 205 fn imem_sec_load_params(&self) -> FalconDmaLoadTarget { 206 // `imem_sec_base` is the *virtual* start address of the secure IMEM segment, so subtract 207 // `imem_virt_base` to get its physical offset. 208 let imem_sec_start = self.imem_sec_base.saturating_sub(self.imem_virt_base); 209 210 FalconDmaLoadTarget { 211 src_start: imem_sec_start, 212 dst_start: self.imem_phys_base.saturating_add(imem_sec_start), 213 len: self.imem_sec_size, 214 } 215 } 216 217 fn imem_ns_load_params(&self) -> Option<FalconDmaLoadTarget> { 218 Some(FalconDmaLoadTarget { 219 // Non-secure code always starts at offset 0. 220 src_start: 0, 221 dst_start: self.imem_phys_base, 222 // `imem_load_size` includes the size of the secure segment, so subtract it to 223 // get the correct amount of data to copy. 224 len: self.imem_load_size.saturating_sub(self.imem_sec_size), 225 }) 226 } 227 228 fn dmem_load_params(&self) -> FalconDmaLoadTarget { 229 FalconDmaLoadTarget { 230 src_start: self.dmem_offset, 231 dst_start: self.dmem_phys_base, 232 len: self.dmem_load_size, 233 } 234 } 235 } 236 237 impl FalconUCodeDescriptor for FalconUCodeDescV3 { 238 fn hdr(&self) -> u32 { 239 self.hdr 240 } 241 fn imem_load_size(&self) -> u32 { 242 self.imem_load_size 243 } 244 fn interface_offset(&self) -> u32 { 245 self.interface_offset 246 } 247 fn dmem_load_size(&self) -> u32 { 248 self.dmem_load_size 249 } 250 fn pkc_data_offset(&self) -> u32 { 251 self.pkc_data_offset 252 } 253 fn engine_id_mask(&self) -> u16 { 254 self.engine_id_mask 255 } 256 fn ucode_id(&self) -> u8 { 257 self.ucode_id 258 } 259 fn signature_count(&self) -> u8 { 260 self.signature_count 261 } 262 fn signature_versions(&self) -> u16 { 263 self.signature_versions 264 } 265 266 fn imem_sec_load_params(&self) -> FalconDmaLoadTarget { 267 FalconDmaLoadTarget { 268 // IMEM segment always starts at offset 0. 269 src_start: 0, 270 dst_start: self.imem_phys_base, 271 len: self.imem_load_size, 272 } 273 } 274 275 fn imem_ns_load_params(&self) -> Option<FalconDmaLoadTarget> { 276 // Not used on V3 platforms 277 None 278 } 279 280 fn dmem_load_params(&self) -> FalconDmaLoadTarget { 281 FalconDmaLoadTarget { 282 // DMEM segment starts right after the IMEM one. 283 src_start: self.imem_load_size, 284 dst_start: self.dmem_phys_base, 285 len: self.dmem_load_size, 286 } 287 } 288 } 289 290 /// Trait implemented by types defining the signed state of a firmware. 291 trait SignedState {} 292 293 /// Type indicating that the firmware must be signed before it can be used. 294 struct Unsigned; 295 impl SignedState for Unsigned {} 296 297 /// Type indicating that the firmware is signed and ready to be loaded. 298 struct Signed; 299 impl SignedState for Signed {} 300 301 /// Microcode to be loaded into a specific falcon. 302 /// 303 /// This is module-local and meant for sub-modules to use internally. 304 /// 305 /// After construction, a firmware is [`Unsigned`], and must generally be patched with a signature 306 /// before it can be loaded (with an exception for development hardware). The 307 /// [`Self::patch_signature`] and [`Self::no_patch_signature`] methods are used to transition the 308 /// firmware to its [`Signed`] state. 309 // TODO: Consider replacing this with a coherent memory object once `CoherentAllocation` supports 310 // temporary CPU-exclusive access to the object without unsafe methods. 311 struct FirmwareObject<F: FalconFirmware, S: SignedState>(KVVec<u8>, PhantomData<(F, S)>); 312 313 /// Trait for signatures to be patched directly into a given firmware. 314 /// 315 /// This is module-local and meant for sub-modules to use internally. 316 trait FirmwareSignature<F: FalconFirmware>: AsRef<[u8]> {} 317 318 impl<F: FalconFirmware> FirmwareObject<F, Unsigned> { 319 /// Patches the firmware at offset `signature_start` with `signature`. 320 fn patch_signature<S: FirmwareSignature<F>>( 321 mut self, 322 signature: &S, 323 signature_start: usize, 324 ) -> Result<FirmwareObject<F, Signed>> { 325 let signature_bytes = signature.as_ref(); 326 let signature_end = signature_start 327 .checked_add(signature_bytes.len()) 328 .ok_or(EOVERFLOW)?; 329 let dst = self 330 .0 331 .get_mut(signature_start..signature_end) 332 .ok_or(EINVAL)?; 333 334 // PANIC: `dst` and `signature_bytes` have the same length. 335 dst.copy_from_slice(signature_bytes); 336 337 Ok(FirmwareObject(self.0, PhantomData)) 338 } 339 340 /// Mark the firmware as signed without patching it. 341 /// 342 /// This method is used to explicitly confirm that we do not need to sign the firmware, while 343 /// allowing us to continue as if it was. This is typically only needed for development 344 /// hardware. 345 fn no_patch_signature(self) -> FirmwareObject<F, Signed> { 346 FirmwareObject(self.0, PhantomData) 347 } 348 } 349 350 /// Header common to most firmware files. 351 #[repr(C)] 352 #[derive(Debug, Clone)] 353 struct BinHdr { 354 /// Magic number, must be `0x10de`. 355 bin_magic: u32, 356 /// Version of the header. 357 bin_ver: u32, 358 /// Size in bytes of the binary (to be ignored). 359 bin_size: u32, 360 /// Offset of the start of the application-specific header. 361 header_offset: u32, 362 /// Offset of the start of the data payload. 363 data_offset: u32, 364 /// Size in bytes of the data payload. 365 data_size: u32, 366 } 367 368 // SAFETY: all bit patterns are valid for this type, and it doesn't use interior mutability. 369 unsafe impl FromBytes for BinHdr {} 370 371 // A firmware blob starting with a `BinHdr`. 372 struct BinFirmware<'a> { 373 hdr: BinHdr, 374 fw: &'a [u8], 375 } 376 377 impl<'a> BinFirmware<'a> { 378 /// Interpret `fw` as a firmware image starting with a [`BinHdr`], and returns the 379 /// corresponding [`BinFirmware`] that can be used to extract its payload. 380 fn new(fw: &'a firmware::Firmware) -> Result<Self> { 381 const BIN_MAGIC: u32 = 0x10de; 382 let fw = fw.data(); 383 384 fw.get(0..size_of::<BinHdr>()) 385 // Extract header. 386 .and_then(BinHdr::from_bytes_copy) 387 // Validate header. 388 .and_then(|hdr| { 389 if hdr.bin_magic == BIN_MAGIC { 390 Some(hdr) 391 } else { 392 None 393 } 394 }) 395 .map(|hdr| Self { hdr, fw }) 396 .ok_or(EINVAL) 397 } 398 399 /// Returns the data payload of the firmware, or `None` if the data range is out of bounds of 400 /// the firmware image. 401 fn data(&self) -> Option<&[u8]> { 402 let fw_start = usize::from_safe_cast(self.hdr.data_offset); 403 let fw_size = usize::from_safe_cast(self.hdr.data_size); 404 let fw_end = fw_start.checked_add(fw_size)?; 405 406 self.fw.get(fw_start..fw_end) 407 } 408 } 409 410 pub(crate) struct ModInfoBuilder<const N: usize>(firmware::ModInfoBuilder<N>); 411 412 impl<const N: usize> ModInfoBuilder<N> { 413 const fn make_entry_file(self, chipset: &str, fw: &str) -> Self { 414 ModInfoBuilder( 415 self.0 416 .new_entry() 417 .push("nvidia/") 418 .push(chipset) 419 .push("/gsp/") 420 .push(fw) 421 .push("-") 422 .push(FIRMWARE_VERSION) 423 .push(".bin"), 424 ) 425 } 426 427 const fn make_entry_chipset(self, chipset: gpu::Chipset) -> Self { 428 let name = chipset.name(); 429 430 let this = self 431 .make_entry_file(name, "booter_load") 432 .make_entry_file(name, "booter_unload") 433 .make_entry_file(name, "bootloader") 434 .make_entry_file(name, "gsp"); 435 436 if chipset.needs_fwsec_bootloader() { 437 this.make_entry_file(name, "gen_bootloader") 438 } else { 439 this 440 } 441 } 442 443 pub(crate) const fn create( 444 module_name: &'static core::ffi::CStr, 445 ) -> firmware::ModInfoBuilder<N> { 446 let mut this = Self(firmware::ModInfoBuilder::new(module_name)); 447 let mut i = 0; 448 449 while i < gpu::Chipset::ALL.len() { 450 this = this.make_entry_chipset(gpu::Chipset::ALL[i]); 451 i += 1; 452 } 453 454 this.0 455 } 456 } 457 458 /// Ad-hoc and temporary module to extract sections from ELF images. 459 /// 460 /// Some firmware images are currently packaged as ELF files, where sections names are used as keys 461 /// to specific and related bits of data. Future firmware versions are scheduled to move away from 462 /// that scheme before nova-core becomes stable, which means this module will eventually be 463 /// removed. 464 mod elf { 465 use core::mem::size_of; 466 467 use kernel::{ 468 bindings, 469 str::CStr, 470 transmute::FromBytes, // 471 }; 472 473 /// Newtype to provide a [`FromBytes`] implementation. 474 #[repr(transparent)] 475 struct Elf64Hdr(bindings::elf64_hdr); 476 // SAFETY: all bit patterns are valid for this type, and it doesn't use interior mutability. 477 unsafe impl FromBytes for Elf64Hdr {} 478 479 #[repr(transparent)] 480 struct Elf64SHdr(bindings::elf64_shdr); 481 // SAFETY: all bit patterns are valid for this type, and it doesn't use interior mutability. 482 unsafe impl FromBytes for Elf64SHdr {} 483 484 /// Returns a NULL-terminated string from the ELF image at `offset`. 485 fn elf_str(elf: &[u8], offset: u64) -> Option<&str> { 486 let idx = usize::try_from(offset).ok()?; 487 let bytes = elf.get(idx..)?; 488 CStr::from_bytes_until_nul(bytes).ok()?.to_str().ok() 489 } 490 491 /// Tries to extract section with name `name` from the ELF64 image `elf`, and returns it. 492 pub(super) fn elf64_section<'a, 'b>(elf: &'a [u8], name: &'b str) -> Option<&'a [u8]> { 493 let hdr = &elf 494 .get(0..size_of::<bindings::elf64_hdr>()) 495 .and_then(Elf64Hdr::from_bytes)? 496 .0; 497 498 // Get all the section headers. 499 let mut shdr = { 500 let shdr_num = usize::from(hdr.e_shnum); 501 let shdr_start = usize::try_from(hdr.e_shoff).ok()?; 502 let shdr_end = shdr_num 503 .checked_mul(size_of::<Elf64SHdr>()) 504 .and_then(|v| v.checked_add(shdr_start))?; 505 506 elf.get(shdr_start..shdr_end) 507 .map(|slice| slice.chunks_exact(size_of::<Elf64SHdr>()))? 508 }; 509 510 // Get the strings table. 511 let strhdr = shdr 512 .clone() 513 .nth(usize::from(hdr.e_shstrndx)) 514 .and_then(Elf64SHdr::from_bytes)?; 515 516 // Find the section which name matches `name` and return it. 517 shdr.find_map(|sh| { 518 let hdr = Elf64SHdr::from_bytes(sh)?; 519 let name_offset = strhdr.0.sh_offset.checked_add(u64::from(hdr.0.sh_name))?; 520 let section_name = elf_str(elf, name_offset)?; 521 522 if section_name != name { 523 return None; 524 } 525 526 let start = usize::try_from(hdr.0.sh_offset).ok()?; 527 let end = usize::try_from(hdr.0.sh_size) 528 .ok() 529 .and_then(|sh_size| start.checked_add(sh_size))?; 530 531 elf.get(start..end) 532 }) 533 } 534 } 535