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 dma::DmaObject, 19 falcon::{ 20 FalconFirmware, 21 FalconLoadTarget, // 22 }, 23 gpu, 24 num::{ 25 FromSafeCast, 26 IntoSafeCast, // 27 }, 28 }; 29 30 pub(crate) mod booter; 31 pub(crate) mod fwsec; 32 pub(crate) mod gsp; 33 pub(crate) mod riscv; 34 35 pub(crate) const FIRMWARE_VERSION: &str = "570.144"; 36 37 /// Requests the GPU firmware `name` suitable for `chipset`, with version `ver`. 38 fn request_firmware( 39 dev: &device::Device, 40 chipset: gpu::Chipset, 41 name: &str, 42 ver: &str, 43 ) -> Result<firmware::Firmware> { 44 let chip_name = chipset.name(); 45 46 CString::try_from_fmt(fmt!("nvidia/{chip_name}/gsp/{name}-{ver}.bin")) 47 .and_then(|path| firmware::Firmware::request(&path, dev)) 48 } 49 50 /// Structure used to describe some firmwares, notably FWSEC-FRTS. 51 #[repr(C)] 52 #[derive(Debug, Clone)] 53 pub(crate) struct FalconUCodeDescV2 { 54 /// Header defined by 'NV_BIT_FALCON_UCODE_DESC_HEADER_VDESC*' in OpenRM. 55 hdr: u32, 56 /// Stored size of the ucode after the header, compressed or uncompressed 57 stored_size: u32, 58 /// Uncompressed size of the ucode. If store_size == uncompressed_size, then the ucode 59 /// is not compressed. 60 pub(crate) uncompressed_size: u32, 61 /// Code entry point 62 pub(crate) virtual_entry: u32, 63 /// Offset after the code segment at which the Application Interface Table headers are located. 64 pub(crate) interface_offset: u32, 65 /// Base address at which to load the code segment into 'IMEM'. 66 pub(crate) imem_phys_base: u32, 67 /// Size in bytes of the code to copy into 'IMEM'. 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 // SAFETY: all bit patterns are valid for this type, and it doesn't use interior mutability. 88 unsafe impl FromBytes for FalconUCodeDescV2 {} 89 90 /// Structure used to describe some firmwares, notably FWSEC-FRTS. 91 #[repr(C)] 92 #[derive(Debug, Clone)] 93 pub(crate) struct FalconUCodeDescV3 { 94 /// Header defined by `NV_BIT_FALCON_UCODE_DESC_HEADER_VDESC*` in OpenRM. 95 hdr: u32, 96 /// Stored size of the ucode after the header. 97 stored_size: u32, 98 /// Offset in `DMEM` at which the signature is expected to be found. 99 pub(crate) pkc_data_offset: u32, 100 /// Offset after the code segment at which the app headers are located. 101 pub(crate) interface_offset: u32, 102 /// Base address at which to load the code segment into `IMEM`. 103 pub(crate) imem_phys_base: u32, 104 /// Size in bytes of the code to copy into `IMEM`. 105 pub(crate) imem_load_size: u32, 106 /// Virtual `IMEM` address (i.e. `tag`) at which the code should start. 107 pub(crate) imem_virt_base: u32, 108 /// Base address at which to load the data segment into `DMEM`. 109 pub(crate) dmem_phys_base: u32, 110 /// Size in bytes of the data to copy into `DMEM`. 111 pub(crate) dmem_load_size: u32, 112 /// Mask of the falcon engines on which this firmware can run. 113 pub(crate) engine_id_mask: u16, 114 /// ID of the ucode used to infer a fuse register to validate the signature. 115 pub(crate) ucode_id: u8, 116 /// Number of signatures in this firmware. 117 pub(crate) signature_count: u8, 118 /// Versions of the signatures, used to infer a valid signature to use. 119 pub(crate) signature_versions: u16, 120 _reserved: u16, 121 } 122 123 // SAFETY: all bit patterns are valid for this type, and it doesn't use 124 // interior mutability. 125 unsafe impl FromBytes for FalconUCodeDescV3 {} 126 127 /// Enum wrapping the different versions of Falcon microcode descriptors. 128 /// 129 /// This allows handling both V2 and V3 descriptor formats through a 130 /// unified type, providing version-agnostic access to firmware metadata 131 /// via the [`FalconUCodeDescriptor`] trait. 132 #[derive(Debug, Clone)] 133 pub(crate) enum FalconUCodeDesc { 134 V2(FalconUCodeDescV2), 135 V3(FalconUCodeDescV3), 136 } 137 138 impl Deref for FalconUCodeDesc { 139 type Target = dyn FalconUCodeDescriptor; 140 141 fn deref(&self) -> &Self::Target { 142 match self { 143 FalconUCodeDesc::V2(v2) => v2, 144 FalconUCodeDesc::V3(v3) => v3, 145 } 146 } 147 } 148 149 /// Trait providing a common interface for accessing Falcon microcode descriptor fields. 150 /// 151 /// This trait abstracts over the different descriptor versions ([`FalconUCodeDescV2`] and 152 /// [`FalconUCodeDescV3`]), allowing code to work with firmware metadata without needing to 153 /// know the specific descriptor version. Fields not present return zero. 154 pub(crate) trait FalconUCodeDescriptor { 155 fn hdr(&self) -> u32; 156 fn imem_load_size(&self) -> u32; 157 fn interface_offset(&self) -> u32; 158 fn dmem_load_size(&self) -> u32; 159 fn pkc_data_offset(&self) -> u32; 160 fn engine_id_mask(&self) -> u16; 161 fn ucode_id(&self) -> u8; 162 fn signature_count(&self) -> u8; 163 fn signature_versions(&self) -> u16; 164 165 /// Returns the size in bytes of the header. 166 fn size(&self) -> usize { 167 let hdr = self.hdr(); 168 169 const HDR_SIZE_SHIFT: u32 = 16; 170 const HDR_SIZE_MASK: u32 = 0xffff0000; 171 ((hdr & HDR_SIZE_MASK) >> HDR_SIZE_SHIFT).into_safe_cast() 172 } 173 174 fn imem_sec_load_params(&self) -> FalconLoadTarget; 175 fn imem_ns_load_params(&self) -> Option<FalconLoadTarget>; 176 fn dmem_load_params(&self) -> FalconLoadTarget; 177 } 178 179 impl FalconUCodeDescriptor for FalconUCodeDescV2 { 180 fn hdr(&self) -> u32 { 181 self.hdr 182 } 183 fn imem_load_size(&self) -> u32 { 184 self.imem_load_size 185 } 186 fn interface_offset(&self) -> u32 { 187 self.interface_offset 188 } 189 fn dmem_load_size(&self) -> u32 { 190 self.dmem_load_size 191 } 192 fn pkc_data_offset(&self) -> u32 { 193 0 194 } 195 fn engine_id_mask(&self) -> u16 { 196 0 197 } 198 fn ucode_id(&self) -> u8 { 199 0 200 } 201 fn signature_count(&self) -> u8 { 202 0 203 } 204 fn signature_versions(&self) -> u16 { 205 0 206 } 207 208 fn imem_sec_load_params(&self) -> FalconLoadTarget { 209 FalconLoadTarget { 210 src_start: 0, 211 dst_start: self.imem_sec_base, 212 len: self.imem_sec_size, 213 } 214 } 215 216 fn imem_ns_load_params(&self) -> Option<FalconLoadTarget> { 217 Some(FalconLoadTarget { 218 src_start: 0, 219 dst_start: self.imem_phys_base, 220 len: self.imem_load_size.checked_sub(self.imem_sec_size)?, 221 }) 222 } 223 224 fn dmem_load_params(&self) -> FalconLoadTarget { 225 FalconLoadTarget { 226 src_start: self.dmem_offset, 227 dst_start: self.dmem_phys_base, 228 len: self.dmem_load_size, 229 } 230 } 231 } 232 233 impl FalconUCodeDescriptor for FalconUCodeDescV3 { 234 fn hdr(&self) -> u32 { 235 self.hdr 236 } 237 fn imem_load_size(&self) -> u32 { 238 self.imem_load_size 239 } 240 fn interface_offset(&self) -> u32 { 241 self.interface_offset 242 } 243 fn dmem_load_size(&self) -> u32 { 244 self.dmem_load_size 245 } 246 fn pkc_data_offset(&self) -> u32 { 247 self.pkc_data_offset 248 } 249 fn engine_id_mask(&self) -> u16 { 250 self.engine_id_mask 251 } 252 fn ucode_id(&self) -> u8 { 253 self.ucode_id 254 } 255 fn signature_count(&self) -> u8 { 256 self.signature_count 257 } 258 fn signature_versions(&self) -> u16 { 259 self.signature_versions 260 } 261 262 fn imem_sec_load_params(&self) -> FalconLoadTarget { 263 FalconLoadTarget { 264 src_start: 0, 265 dst_start: self.imem_phys_base, 266 len: self.imem_load_size, 267 } 268 } 269 270 fn imem_ns_load_params(&self) -> Option<FalconLoadTarget> { 271 // Not used on V3 platforms 272 None 273 } 274 275 fn dmem_load_params(&self) -> FalconLoadTarget { 276 FalconLoadTarget { 277 src_start: self.imem_load_size, 278 dst_start: self.dmem_phys_base, 279 len: self.dmem_load_size, 280 } 281 } 282 } 283 284 /// Trait implemented by types defining the signed state of a firmware. 285 trait SignedState {} 286 287 /// Type indicating that the firmware must be signed before it can be used. 288 struct Unsigned; 289 impl SignedState for Unsigned {} 290 291 /// Type indicating that the firmware is signed and ready to be loaded. 292 struct Signed; 293 impl SignedState for Signed {} 294 295 /// A [`DmaObject`] containing a specific microcode ready to be loaded into a falcon. 296 /// 297 /// This is module-local and meant for sub-modules to use internally. 298 /// 299 /// After construction, a firmware is [`Unsigned`], and must generally be patched with a signature 300 /// before it can be loaded (with an exception for development hardware). The 301 /// [`Self::patch_signature`] and [`Self::no_patch_signature`] methods are used to transition the 302 /// firmware to its [`Signed`] state. 303 struct FirmwareDmaObject<F: FalconFirmware, S: SignedState>(DmaObject, PhantomData<(F, S)>); 304 305 /// Trait for signatures to be patched directly into a given firmware. 306 /// 307 /// This is module-local and meant for sub-modules to use internally. 308 trait FirmwareSignature<F: FalconFirmware>: AsRef<[u8]> {} 309 310 impl<F: FalconFirmware> FirmwareDmaObject<F, Unsigned> { 311 /// Patches the firmware at offset `sig_base_img` with `signature`. 312 fn patch_signature<S: FirmwareSignature<F>>( 313 mut self, 314 signature: &S, 315 sig_base_img: usize, 316 ) -> Result<FirmwareDmaObject<F, Signed>> { 317 let signature_bytes = signature.as_ref(); 318 if sig_base_img + signature_bytes.len() > self.0.size() { 319 return Err(EINVAL); 320 } 321 322 // SAFETY: We are the only user of this object, so there cannot be any race. 323 let dst = unsafe { self.0.start_ptr_mut().add(sig_base_img) }; 324 325 // SAFETY: `signature` and `dst` are valid, properly aligned, and do not overlap. 326 unsafe { 327 core::ptr::copy_nonoverlapping(signature_bytes.as_ptr(), dst, signature_bytes.len()) 328 }; 329 330 Ok(FirmwareDmaObject(self.0, PhantomData)) 331 } 332 333 /// Mark the firmware as signed without patching it. 334 /// 335 /// This method is used to explicitly confirm that we do not need to sign the firmware, while 336 /// allowing us to continue as if it was. This is typically only needed for development 337 /// hardware. 338 fn no_patch_signature(self) -> FirmwareDmaObject<F, Signed> { 339 FirmwareDmaObject(self.0, PhantomData) 340 } 341 } 342 343 /// Header common to most firmware files. 344 #[repr(C)] 345 #[derive(Debug, Clone)] 346 struct BinHdr { 347 /// Magic number, must be `0x10de`. 348 bin_magic: u32, 349 /// Version of the header. 350 bin_ver: u32, 351 /// Size in bytes of the binary (to be ignored). 352 bin_size: u32, 353 /// Offset of the start of the application-specific header. 354 header_offset: u32, 355 /// Offset of the start of the data payload. 356 data_offset: u32, 357 /// Size in bytes of the data payload. 358 data_size: u32, 359 } 360 361 // SAFETY: all bit patterns are valid for this type, and it doesn't use interior mutability. 362 unsafe impl FromBytes for BinHdr {} 363 364 // A firmware blob starting with a `BinHdr`. 365 struct BinFirmware<'a> { 366 hdr: BinHdr, 367 fw: &'a [u8], 368 } 369 370 impl<'a> BinFirmware<'a> { 371 /// Interpret `fw` as a firmware image starting with a [`BinHdr`], and returns the 372 /// corresponding [`BinFirmware`] that can be used to extract its payload. 373 fn new(fw: &'a firmware::Firmware) -> Result<Self> { 374 const BIN_MAGIC: u32 = 0x10de; 375 let fw = fw.data(); 376 377 fw.get(0..size_of::<BinHdr>()) 378 // Extract header. 379 .and_then(BinHdr::from_bytes_copy) 380 // Validate header. 381 .and_then(|hdr| { 382 if hdr.bin_magic == BIN_MAGIC { 383 Some(hdr) 384 } else { 385 None 386 } 387 }) 388 .map(|hdr| Self { hdr, fw }) 389 .ok_or(EINVAL) 390 } 391 392 /// Returns the data payload of the firmware, or `None` if the data range is out of bounds of 393 /// the firmware image. 394 fn data(&self) -> Option<&[u8]> { 395 let fw_start = usize::from_safe_cast(self.hdr.data_offset); 396 let fw_size = usize::from_safe_cast(self.hdr.data_size); 397 398 self.fw.get(fw_start..fw_start + fw_size) 399 } 400 } 401 402 pub(crate) struct ModInfoBuilder<const N: usize>(firmware::ModInfoBuilder<N>); 403 404 impl<const N: usize> ModInfoBuilder<N> { 405 const fn make_entry_file(self, chipset: &str, fw: &str) -> Self { 406 ModInfoBuilder( 407 self.0 408 .new_entry() 409 .push("nvidia/") 410 .push(chipset) 411 .push("/gsp/") 412 .push(fw) 413 .push("-") 414 .push(FIRMWARE_VERSION) 415 .push(".bin"), 416 ) 417 } 418 419 const fn make_entry_chipset(self, chipset: &str) -> Self { 420 self.make_entry_file(chipset, "booter_load") 421 .make_entry_file(chipset, "booter_unload") 422 .make_entry_file(chipset, "bootloader") 423 .make_entry_file(chipset, "gsp") 424 } 425 426 pub(crate) const fn create( 427 module_name: &'static kernel::str::CStr, 428 ) -> firmware::ModInfoBuilder<N> { 429 let mut this = Self(firmware::ModInfoBuilder::new(module_name)); 430 let mut i = 0; 431 432 while i < gpu::Chipset::ALL.len() { 433 this = this.make_entry_chipset(gpu::Chipset::ALL[i].name()); 434 i += 1; 435 } 436 437 this.0 438 } 439 } 440