1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Falcon microprocessor base support 4 5 use core::ops::Deref; 6 7 use hal::FalconHal; 8 9 use kernel::{ 10 device, 11 dma::DmaAddress, 12 io::poll::read_poll_timeout, 13 prelude::*, 14 sync::aref::ARef, 15 time::{ 16 delay::fsleep, 17 Delta, // 18 }, 19 }; 20 21 use crate::{ 22 dma::DmaObject, 23 driver::Bar0, 24 gpu::Chipset, 25 num::{ 26 FromSafeCast, 27 IntoSafeCast, // 28 }, 29 regs, 30 regs::macros::RegisterBase, // 31 }; 32 33 pub(crate) mod gsp; 34 mod hal; 35 pub(crate) mod sec2; 36 37 // TODO[FPRI]: Replace with `ToPrimitive`. 38 macro_rules! impl_from_enum_to_u8 { 39 ($enum_type:ty) => { 40 impl From<$enum_type> for u8 { 41 fn from(value: $enum_type) -> Self { 42 value as u8 43 } 44 } 45 }; 46 } 47 48 /// Revision number of a falcon core, used in the [`crate::regs::NV_PFALCON_FALCON_HWCFG1`] 49 /// register. 50 #[repr(u8)] 51 #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] 52 pub(crate) enum FalconCoreRev { 53 #[default] 54 Rev1 = 1, 55 Rev2 = 2, 56 Rev3 = 3, 57 Rev4 = 4, 58 Rev5 = 5, 59 Rev6 = 6, 60 Rev7 = 7, 61 } 62 impl_from_enum_to_u8!(FalconCoreRev); 63 64 // TODO[FPRI]: replace with `FromPrimitive`. 65 impl TryFrom<u8> for FalconCoreRev { 66 type Error = Error; 67 68 fn try_from(value: u8) -> Result<Self> { 69 use FalconCoreRev::*; 70 71 let rev = match value { 72 1 => Rev1, 73 2 => Rev2, 74 3 => Rev3, 75 4 => Rev4, 76 5 => Rev5, 77 6 => Rev6, 78 7 => Rev7, 79 _ => return Err(EINVAL), 80 }; 81 82 Ok(rev) 83 } 84 } 85 86 /// Revision subversion number of a falcon core, used in the 87 /// [`crate::regs::NV_PFALCON_FALCON_HWCFG1`] register. 88 #[repr(u8)] 89 #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] 90 pub(crate) enum FalconCoreRevSubversion { 91 #[default] 92 Subversion0 = 0, 93 Subversion1 = 1, 94 Subversion2 = 2, 95 Subversion3 = 3, 96 } 97 impl_from_enum_to_u8!(FalconCoreRevSubversion); 98 99 // TODO[FPRI]: replace with `FromPrimitive`. 100 impl TryFrom<u8> for FalconCoreRevSubversion { 101 type Error = Error; 102 103 fn try_from(value: u8) -> Result<Self> { 104 use FalconCoreRevSubversion::*; 105 106 let sub_version = match value & 0b11 { 107 0 => Subversion0, 108 1 => Subversion1, 109 2 => Subversion2, 110 3 => Subversion3, 111 _ => return Err(EINVAL), 112 }; 113 114 Ok(sub_version) 115 } 116 } 117 118 /// Security model of a falcon core, used in the [`crate::regs::NV_PFALCON_FALCON_HWCFG1`] 119 /// register. 120 #[repr(u8)] 121 #[derive(Debug, Default, Copy, Clone)] 122 /// Security mode of the Falcon microprocessor. 123 /// 124 /// See `falcon.rst` for more details. 125 pub(crate) enum FalconSecurityModel { 126 /// Non-Secure: runs unsigned code without privileges. 127 #[default] 128 None = 0, 129 /// Light-Secured (LS): Runs signed code with some privileges. 130 /// Entry into this mode is only possible from 'Heavy-secure' mode, which verifies the code's 131 /// signature. 132 /// 133 /// Also known as Low-Secure, Privilege Level 2 or PL2. 134 Light = 2, 135 /// Heavy-Secured (HS): Runs signed code with full privileges. 136 /// The code's signature is verified by the Falcon Boot ROM (BROM). 137 /// 138 /// Also known as High-Secure, Privilege Level 3 or PL3. 139 Heavy = 3, 140 } 141 impl_from_enum_to_u8!(FalconSecurityModel); 142 143 // TODO[FPRI]: replace with `FromPrimitive`. 144 impl TryFrom<u8> for FalconSecurityModel { 145 type Error = Error; 146 147 fn try_from(value: u8) -> Result<Self> { 148 use FalconSecurityModel::*; 149 150 let sec_model = match value { 151 0 => None, 152 2 => Light, 153 3 => Heavy, 154 _ => return Err(EINVAL), 155 }; 156 157 Ok(sec_model) 158 } 159 } 160 161 /// Signing algorithm for a given firmware, used in the [`crate::regs::NV_PFALCON2_FALCON_MOD_SEL`] 162 /// register. It is passed to the Falcon Boot ROM (BROM) as a parameter. 163 #[repr(u8)] 164 #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] 165 pub(crate) enum FalconModSelAlgo { 166 /// AES. 167 #[expect(dead_code)] 168 Aes = 0, 169 /// RSA3K. 170 #[default] 171 Rsa3k = 1, 172 } 173 impl_from_enum_to_u8!(FalconModSelAlgo); 174 175 // TODO[FPRI]: replace with `FromPrimitive`. 176 impl TryFrom<u8> for FalconModSelAlgo { 177 type Error = Error; 178 179 fn try_from(value: u8) -> Result<Self> { 180 match value { 181 1 => Ok(FalconModSelAlgo::Rsa3k), 182 _ => Err(EINVAL), 183 } 184 } 185 } 186 187 /// Valid values for the `size` field of the [`crate::regs::NV_PFALCON_FALCON_DMATRFCMD`] register. 188 #[repr(u8)] 189 #[derive(Debug, Default, Copy, Clone, PartialEq, Eq)] 190 pub(crate) enum DmaTrfCmdSize { 191 /// 256 bytes transfer. 192 #[default] 193 Size256B = 0x6, 194 } 195 impl_from_enum_to_u8!(DmaTrfCmdSize); 196 197 // TODO[FPRI]: replace with `FromPrimitive`. 198 impl TryFrom<u8> for DmaTrfCmdSize { 199 type Error = Error; 200 201 fn try_from(value: u8) -> Result<Self> { 202 match value { 203 0x6 => Ok(Self::Size256B), 204 _ => Err(EINVAL), 205 } 206 } 207 } 208 209 /// Currently active core on a dual falcon/riscv (Peregrine) controller. 210 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] 211 pub(crate) enum PeregrineCoreSelect { 212 /// Falcon core is active. 213 #[default] 214 Falcon = 0, 215 /// RISC-V core is active. 216 Riscv = 1, 217 } 218 219 impl From<bool> for PeregrineCoreSelect { 220 fn from(value: bool) -> Self { 221 match value { 222 false => PeregrineCoreSelect::Falcon, 223 true => PeregrineCoreSelect::Riscv, 224 } 225 } 226 } 227 228 impl From<PeregrineCoreSelect> for bool { 229 fn from(value: PeregrineCoreSelect) -> Self { 230 match value { 231 PeregrineCoreSelect::Falcon => false, 232 PeregrineCoreSelect::Riscv => true, 233 } 234 } 235 } 236 237 /// Different types of memory present in a falcon core. 238 #[derive(Debug, Clone, Copy, PartialEq, Eq)] 239 pub(crate) enum FalconMem { 240 /// Instruction Memory. 241 Imem, 242 /// Data Memory. 243 Dmem, 244 } 245 246 /// Defines the Framebuffer Interface (FBIF) aperture type. 247 /// This determines the memory type for external memory access during a DMA transfer, which is 248 /// performed by the Falcon's Framebuffer DMA (FBDMA) engine. See falcon.rst for more details. 249 #[derive(Debug, Clone, Default)] 250 pub(crate) enum FalconFbifTarget { 251 /// VRAM. 252 #[default] 253 /// Local Framebuffer (GPU's VRAM memory). 254 LocalFb = 0, 255 /// Coherent system memory (System DRAM). 256 CoherentSysmem = 1, 257 /// Non-coherent system memory (System DRAM). 258 NoncoherentSysmem = 2, 259 } 260 impl_from_enum_to_u8!(FalconFbifTarget); 261 262 // TODO[FPRI]: replace with `FromPrimitive`. 263 impl TryFrom<u8> for FalconFbifTarget { 264 type Error = Error; 265 266 fn try_from(value: u8) -> Result<Self> { 267 let res = match value { 268 0 => Self::LocalFb, 269 1 => Self::CoherentSysmem, 270 2 => Self::NoncoherentSysmem, 271 _ => return Err(EINVAL), 272 }; 273 274 Ok(res) 275 } 276 } 277 278 /// Type of memory addresses to use. 279 #[derive(Debug, Clone, Default)] 280 pub(crate) enum FalconFbifMemType { 281 /// Virtual memory addresses. 282 #[default] 283 Virtual = 0, 284 /// Physical memory addresses. 285 Physical = 1, 286 } 287 288 /// Conversion from a single-bit register field. 289 impl From<bool> for FalconFbifMemType { 290 fn from(value: bool) -> Self { 291 match value { 292 false => Self::Virtual, 293 true => Self::Physical, 294 } 295 } 296 } 297 298 impl From<FalconFbifMemType> for bool { 299 fn from(value: FalconFbifMemType) -> Self { 300 match value { 301 FalconFbifMemType::Virtual => false, 302 FalconFbifMemType::Physical => true, 303 } 304 } 305 } 306 307 /// Type used to represent the `PFALCON` registers address base for a given falcon engine. 308 pub(crate) struct PFalconBase(()); 309 310 /// Type used to represent the `PFALCON2` registers address base for a given falcon engine. 311 pub(crate) struct PFalcon2Base(()); 312 313 /// Trait defining the parameters of a given Falcon engine. 314 /// 315 /// Each engine provides one base for `PFALCON` and `PFALCON2` registers. The `ID` constant is used 316 /// to identify a given Falcon instance with register I/O methods. 317 pub(crate) trait FalconEngine: 318 Send + Sync + RegisterBase<PFalconBase> + RegisterBase<PFalcon2Base> + Sized 319 { 320 /// Singleton of the engine, used to identify it with register I/O methods. 321 const ID: Self; 322 } 323 324 /// Represents a portion of the firmware to be loaded into a particular memory (e.g. IMEM or DMEM). 325 #[derive(Debug, Clone)] 326 pub(crate) struct FalconLoadTarget { 327 /// Offset from the start of the source object to copy from. 328 pub(crate) src_start: u32, 329 /// Offset from the start of the destination memory to copy into. 330 pub(crate) dst_start: u32, 331 /// Number of bytes to copy. 332 pub(crate) len: u32, 333 } 334 335 /// Parameters for the falcon boot ROM. 336 #[derive(Debug, Clone)] 337 pub(crate) struct FalconBromParams { 338 /// Offset in `DMEM`` of the firmware's signature. 339 pub(crate) pkc_data_offset: u32, 340 /// Mask of engines valid for this firmware. 341 pub(crate) engine_id_mask: u16, 342 /// ID of the ucode used to infer a fuse register to validate the signature. 343 pub(crate) ucode_id: u8, 344 } 345 346 /// Trait for providing load parameters of falcon firmwares. 347 pub(crate) trait FalconLoadParams { 348 /// Returns the load parameters for `IMEM`. 349 fn imem_load_params(&self) -> FalconLoadTarget; 350 351 /// Returns the load parameters for `DMEM`. 352 fn dmem_load_params(&self) -> FalconLoadTarget; 353 354 /// Returns the parameters to write into the BROM registers. 355 fn brom_params(&self) -> FalconBromParams; 356 357 /// Returns the start address of the firmware. 358 fn boot_addr(&self) -> u32; 359 } 360 361 /// Trait for a falcon firmware. 362 /// 363 /// A falcon firmware can be loaded on a given engine, and is presented in the form of a DMA 364 /// object. 365 pub(crate) trait FalconFirmware: FalconLoadParams + Deref<Target = DmaObject> { 366 /// Engine on which this firmware is to be loaded. 367 type Target: FalconEngine; 368 } 369 370 /// Contains the base parameters common to all Falcon instances. 371 pub(crate) struct Falcon<E: FalconEngine> { 372 hal: KBox<dyn FalconHal<E>>, 373 dev: ARef<device::Device>, 374 } 375 376 impl<E: FalconEngine + 'static> Falcon<E> { 377 /// Create a new falcon instance. 378 pub(crate) fn new(dev: &device::Device, chipset: Chipset) -> Result<Self> { 379 Ok(Self { 380 hal: hal::falcon_hal(chipset)?, 381 dev: dev.into(), 382 }) 383 } 384 385 /// Wait for memory scrubbing to complete. 386 fn reset_wait_mem_scrubbing(&self, bar: &Bar0) -> Result { 387 // TIMEOUT: memory scrubbing should complete in less than 20ms. 388 read_poll_timeout( 389 || Ok(regs::NV_PFALCON_FALCON_HWCFG2::read(bar, &E::ID)), 390 |r| r.mem_scrubbing_done(), 391 Delta::ZERO, 392 Delta::from_millis(20), 393 ) 394 .map(|_| ()) 395 } 396 397 /// Reset the falcon engine. 398 fn reset_eng(&self, bar: &Bar0) -> Result { 399 let _ = regs::NV_PFALCON_FALCON_HWCFG2::read(bar, &E::ID); 400 401 // According to OpenRM's `kflcnPreResetWait_GA102` documentation, HW sometimes does not set 402 // RESET_READY so a non-failing timeout is used. 403 let _ = read_poll_timeout( 404 || Ok(regs::NV_PFALCON_FALCON_HWCFG2::read(bar, &E::ID)), 405 |r| r.reset_ready(), 406 Delta::ZERO, 407 Delta::from_micros(150), 408 ); 409 410 regs::NV_PFALCON_FALCON_ENGINE::update(bar, &E::ID, |v| v.set_reset(true)); 411 412 // TIMEOUT: falcon engine should not take more than 10us to reset. 413 fsleep(Delta::from_micros(10)); 414 415 regs::NV_PFALCON_FALCON_ENGINE::update(bar, &E::ID, |v| v.set_reset(false)); 416 417 self.reset_wait_mem_scrubbing(bar)?; 418 419 Ok(()) 420 } 421 422 /// Reset the controller, select the falcon core, and wait for memory scrubbing to complete. 423 pub(crate) fn reset(&self, bar: &Bar0) -> Result { 424 self.reset_eng(bar)?; 425 self.hal.select_core(self, bar)?; 426 self.reset_wait_mem_scrubbing(bar)?; 427 428 regs::NV_PFALCON_FALCON_RM::default() 429 .set_value(regs::NV_PMC_BOOT_0::read(bar).into()) 430 .write(bar, &E::ID); 431 432 Ok(()) 433 } 434 435 /// Perform a DMA write according to `load_offsets` from `dma_handle` into the falcon's 436 /// `target_mem`. 437 /// 438 /// `sec` is set if the loaded firmware is expected to run in secure mode. 439 fn dma_wr<F: FalconFirmware<Target = E>>( 440 &self, 441 bar: &Bar0, 442 fw: &F, 443 target_mem: FalconMem, 444 load_offsets: FalconLoadTarget, 445 sec: bool, 446 ) -> Result { 447 const DMA_LEN: u32 = 256; 448 449 // For IMEM, we want to use the start offset as a virtual address tag for each page, since 450 // code addresses in the firmware (and the boot vector) are virtual. 451 // 452 // For DMEM we can fold the start offset into the DMA handle. 453 let (src_start, dma_start) = match target_mem { 454 FalconMem::Imem => (load_offsets.src_start, fw.dma_handle()), 455 FalconMem::Dmem => ( 456 0, 457 fw.dma_handle_with_offset(load_offsets.src_start.into_safe_cast())?, 458 ), 459 }; 460 if dma_start % DmaAddress::from(DMA_LEN) > 0 { 461 dev_err!( 462 self.dev, 463 "DMA transfer start addresses must be a multiple of {}", 464 DMA_LEN 465 ); 466 return Err(EINVAL); 467 } 468 469 // DMA transfers can only be done in units of 256 bytes. Compute how many such transfers we 470 // need to perform. 471 let num_transfers = load_offsets.len.div_ceil(DMA_LEN); 472 473 // Check that the area we are about to transfer is within the bounds of the DMA object. 474 // Upper limit of transfer is `(num_transfers * DMA_LEN) + load_offsets.src_start`. 475 match num_transfers 476 .checked_mul(DMA_LEN) 477 .and_then(|size| size.checked_add(load_offsets.src_start)) 478 { 479 None => { 480 dev_err!(self.dev, "DMA transfer length overflow"); 481 return Err(EOVERFLOW); 482 } 483 Some(upper_bound) if usize::from_safe_cast(upper_bound) > fw.size() => { 484 dev_err!(self.dev, "DMA transfer goes beyond range of DMA object"); 485 return Err(EINVAL); 486 } 487 Some(_) => (), 488 }; 489 490 // Set up the base source DMA address. 491 492 regs::NV_PFALCON_FALCON_DMATRFBASE::default() 493 // CAST: `as u32` is used on purpose since we do want to strip the upper bits, which 494 // will be written to `NV_PFALCON_FALCON_DMATRFBASE1`. 495 .set_base((dma_start >> 8) as u32) 496 .write(bar, &E::ID); 497 regs::NV_PFALCON_FALCON_DMATRFBASE1::default() 498 // CAST: `as u16` is used on purpose since the remaining bits are guaranteed to fit 499 // within a `u16`. 500 .set_base((dma_start >> 40) as u16) 501 .write(bar, &E::ID); 502 503 let cmd = regs::NV_PFALCON_FALCON_DMATRFCMD::default() 504 .set_size(DmaTrfCmdSize::Size256B) 505 .set_imem(target_mem == FalconMem::Imem) 506 .set_sec(if sec { 1 } else { 0 }); 507 508 for pos in (0..num_transfers).map(|i| i * DMA_LEN) { 509 // Perform a transfer of size `DMA_LEN`. 510 regs::NV_PFALCON_FALCON_DMATRFMOFFS::default() 511 .set_offs(load_offsets.dst_start + pos) 512 .write(bar, &E::ID); 513 regs::NV_PFALCON_FALCON_DMATRFFBOFFS::default() 514 .set_offs(src_start + pos) 515 .write(bar, &E::ID); 516 cmd.write(bar, &E::ID); 517 518 // Wait for the transfer to complete. 519 // TIMEOUT: arbitrarily large value, no DMA transfer to the falcon's small memories 520 // should ever take that long. 521 read_poll_timeout( 522 || Ok(regs::NV_PFALCON_FALCON_DMATRFCMD::read(bar, &E::ID)), 523 |r| r.idle(), 524 Delta::ZERO, 525 Delta::from_secs(2), 526 )?; 527 } 528 529 Ok(()) 530 } 531 532 /// Perform a DMA load into `IMEM` and `DMEM` of `fw`, and prepare the falcon to run it. 533 pub(crate) fn dma_load<F: FalconFirmware<Target = E>>(&self, bar: &Bar0, fw: &F) -> Result { 534 regs::NV_PFALCON_FBIF_CTL::update(bar, &E::ID, |v| v.set_allow_phys_no_ctx(true)); 535 regs::NV_PFALCON_FALCON_DMACTL::default().write(bar, &E::ID); 536 regs::NV_PFALCON_FBIF_TRANSCFG::update(bar, &E::ID, 0, |v| { 537 v.set_target(FalconFbifTarget::CoherentSysmem) 538 .set_mem_type(FalconFbifMemType::Physical) 539 }); 540 541 self.dma_wr(bar, fw, FalconMem::Imem, fw.imem_load_params(), true)?; 542 self.dma_wr(bar, fw, FalconMem::Dmem, fw.dmem_load_params(), true)?; 543 544 self.hal.program_brom(self, bar, &fw.brom_params())?; 545 546 // Set `BootVec` to start of non-secure code. 547 regs::NV_PFALCON_FALCON_BOOTVEC::default() 548 .set_value(fw.boot_addr()) 549 .write(bar, &E::ID); 550 551 Ok(()) 552 } 553 554 /// Runs the loaded firmware and waits for its completion. 555 /// 556 /// `mbox0` and `mbox1` are optional parameters to write into the `MBOX0` and `MBOX1` registers 557 /// prior to running. 558 /// 559 /// Wait up to two seconds for the firmware to complete, and return its exit status read from 560 /// the `MBOX0` and `MBOX1` registers. 561 pub(crate) fn boot( 562 &self, 563 bar: &Bar0, 564 mbox0: Option<u32>, 565 mbox1: Option<u32>, 566 ) -> Result<(u32, u32)> { 567 if let Some(mbox0) = mbox0 { 568 regs::NV_PFALCON_FALCON_MAILBOX0::default() 569 .set_value(mbox0) 570 .write(bar, &E::ID); 571 } 572 573 if let Some(mbox1) = mbox1 { 574 regs::NV_PFALCON_FALCON_MAILBOX1::default() 575 .set_value(mbox1) 576 .write(bar, &E::ID); 577 } 578 579 match regs::NV_PFALCON_FALCON_CPUCTL::read(bar, &E::ID).alias_en() { 580 true => regs::NV_PFALCON_FALCON_CPUCTL_ALIAS::default() 581 .set_startcpu(true) 582 .write(bar, &E::ID), 583 false => regs::NV_PFALCON_FALCON_CPUCTL::default() 584 .set_startcpu(true) 585 .write(bar, &E::ID), 586 } 587 588 // TIMEOUT: arbitrarily large value, firmwares should complete in less than 2 seconds. 589 read_poll_timeout( 590 || Ok(regs::NV_PFALCON_FALCON_CPUCTL::read(bar, &E::ID)), 591 |r| r.halted(), 592 Delta::ZERO, 593 Delta::from_secs(2), 594 )?; 595 596 let (mbox0, mbox1) = ( 597 regs::NV_PFALCON_FALCON_MAILBOX0::read(bar, &E::ID).value(), 598 regs::NV_PFALCON_FALCON_MAILBOX1::read(bar, &E::ID).value(), 599 ); 600 601 Ok((mbox0, mbox1)) 602 } 603 604 /// Returns the fused version of the signature to use in order to run a HS firmware on this 605 /// falcon instance. `engine_id_mask` and `ucode_id` are obtained from the firmware header. 606 pub(crate) fn signature_reg_fuse_version( 607 &self, 608 bar: &Bar0, 609 engine_id_mask: u16, 610 ucode_id: u8, 611 ) -> Result<u32> { 612 self.hal 613 .signature_reg_fuse_version(self, bar, engine_id_mask, ucode_id) 614 } 615 } 616