uefi.md
1 # UEFI Firmware 2 3 The DGX Spark uses UEFI firmware based on EDK2 (TianoCore) with NVIDIA-specific 4 extensions for the TH500 Thor SoC platform. 5 6 ## Firmware Architecture 7 8 ``` 9 ┌────────────────────────────────────────────────────────────────────┐ 10 │ TH500 UEFI Firmware Stack │ 11 ├────────────────────────────────────────────────────────────────────┤ 12 │ │ 13 │ ┌───────────────────────────────────────────────────────────────┐ │ 14 │ │ UEFI Boot Services │ │ 15 │ │ - Boot Manager │ │ 16 │ │ - Device/Protocol Discovery │ │ 17 │ │ - Secure Boot Verification │ │ 18 │ └───────────────────────────────────────────────────────────────┘ │ 19 │ │ │ 20 │ ┌───────────────────────────────────────────────────────────────┐ │ 21 │ │ UEFI Runtime Services │ │ 22 │ │ - Variable Services (GetVariable, SetVariable) │ │ 23 │ │ - Time Services │ │ 24 │ │ - Capsule Update │ │ 25 │ │ - Reset Services │ │ 26 │ └───────────────────────────────────────────────────────────────┘ │ 27 │ │ │ 28 │ ┌───────────────────────────────────────────────────────────────┐ │ 29 │ │ Platform DXE Drivers │ │ 30 │ │ - TH500 PCIe │ │ 31 │ │ - NVMe │ │ 32 │ │ - USB │ │ 33 │ │ - UART/Console │ │ 34 │ │ - GOP (Graphics Output Protocol) │ │ 35 │ └───────────────────────────────────────────────────────────────┘ │ 36 │ │ │ 37 │ ┌───────────────────────────────────────────────────────────────┐ │ 38 │ │ SEC/PEI (Early Init) │ │ 39 │ │ - Memory Controller Init │ │ 40 │ │ - LPDDR5X Training │ │ 41 │ │ - Clock/PLL Setup │ │ 42 │ └───────────────────────────────────────────────────────────────┘ │ 43 │ │ 44 └────────────────────────────────────────────────────────────────────┘ 45 ``` 46 47 ## UEFI Variables 48 49 Key UEFI variables used by DGX Spark: 50 51 ### Secure Boot Variables 52 53 | Variable | GUID | Description | 54 |----------|------|-------------| 55 | `SecureBoot` | `8be4df61-*` | Secure Boot enable state | 56 | `SetupMode` | `8be4df61-*` | Setup vs User mode | 57 | `PK` | `8be4df61-*` | Platform Key | 58 | `KEK` | `8be4df61-*` | Key Exchange Keys | 59 | `db` | `d719b2cb-*` | Authorized signatures | 60 | `dbx` | `d719b2cb-*` | Forbidden signatures | 61 | `MokList` | `605dab50-*` | Machine Owner Keys | 62 63 ### Boot Variables 64 65 | Variable | Description | 66 |----------|-------------| 67 | `BootOrder` | Boot device priority | 68 | `BootCurrent` | Current boot entry | 69 | `Boot0000`-`Boot00XX` | Boot option entries | 70 | `ConIn`, `ConOut` | Console devices | 71 72 ### NVIDIA-Specific Variables 73 74 NVIDIA adds platform-specific variables under their GUID namespace: 75 76 | Variable | Purpose | 77 |----------|---------| 78 | Platform serial | Hardware identification | 79 | Board revision | PCB revision tracking | 80 | Fuse state | Security fuse status | 81 82 ## EFI System Partition 83 84 Mount point: `/boot/efi`\ 85 Filesystem: FAT32 (vfat)\ 86 UUID: `5A81-59A7` 87 88 Expected structure: 89 90 ``` 91 /boot/efi/ 92 └── EFI/ 93 ├── BOOT/ 94 │ └── BOOTAA64.EFI # Fallback bootloader 95 └── ubuntu/ 96 ├── shimaa64.efi # Primary bootloader 97 ├── grubaa64.efi # GRUB 98 └── grub.cfg # GRUB config stub 99 ``` 100 101 ## Capsule Update Support 102 103 The UEFI firmware supports capsule-based updates: 104 105 ```c 106 // Capsule header (from UEFI spec) 107 typedef struct { 108 EFI_GUID CapsuleGuid; 109 UINT32 HeaderSize; 110 UINT32 Flags; 111 UINT32 CapsuleImageSize; 112 } EFI_CAPSULE_HEADER; 113 ``` 114 115 Capsule types: 116 117 - **SoC Firmware** (`socfw.cap`) - Main UEFI + platform firmware 118 - **EC Firmware** (`ec_*.cap`) - Embedded controller 119 - **TPM Firmware** (`tpm.cap`) - TPM microcode 120 - **USB-PD Firmware** (`usbpd.cap`) - USB-PD controller 121 122 ## ACPI Tables 123 124 The UEFI firmware provides ACPI tables for device enumeration: 125 126 | Table | Purpose | 127 |-------|---------| 128 | DSDT | Differentiated System Description Table | 129 | SSDT | Secondary System Description Tables | 130 | MADT | Multiple APIC Description Table | 131 | MCFG | PCI Express configuration | 132 | GTDT | Generic Timer Description Table | 133 | IORT | I/O Remapping Table (ARM SMMU) | 134 | PPTT | Processor Properties Topology Table | 135 136 ## Device Tree Fallback 137 138 On ARM64, the firmware can pass device tree blobs in addition to ACPI: 139 140 ``` 141 CONFIG_EFI_PARAMS_FROM_FDT=y 142 ``` 143 144 The TH500 platform uses both ACPI (primary) and DTB (supplementary) for 145 complete device description. 146 147 ## Console Configuration 148 149 UEFI console setup from kernel config: 150 151 ``` 152 CONFIG_EFI_EARLYCON=y 153 ``` 154 155 Early console UART mapping: 156 157 ``` 158 earlycon=uart,mmio32,0x16A00000 159 ``` 160 161 This provides output during early boot before the kernel's serial driver 162 initializes. 163 164 ## EFI Stub Boot 165 166 The kernel supports direct EFI stub boot: 167 168 ``` 169 CONFIG_EFI_STUB=y 170 CONFIG_EFI_GENERIC_STUB=y 171 CONFIG_EFI_ZBOOT=y 172 ``` 173 174 This allows booting the kernel directly from UEFI without GRUB, though 175 the default configuration uses the full SHIM/GRUB chain for Secure Boot 176 compatibility. 177 178 ## Firmware Update Flow 179 180 ``` 181 fwupdmgr get-updates 182 │ 183 v 184 ┌───────────────────┐ 185 │ Download capsule │ 186 │ from LVFS/NVIDIA │ 187 └─────────┬─────────┘ 188 │ 189 v 190 ┌───────────────────┐ 191 │ Stage capsule in │ 192 │ EFI system part. │ 193 └─────────┬─────────┘ 194 │ 195 v 196 ┌───────────────────┐ 197 │ Reboot with │ 198 │ EFI_CAPSULE_FLAG │ 199 └─────────┬─────────┘ 200 │ 201 v 202 ┌───────────────────┐ 203 │ UEFI processes │ 204 │ capsule on boot │ 205 └─────────┬─────────┘ 206 │ 207 v 208 ┌───────────────────┐ 209 │ Normal boot with │ 210 │ updated firmware │ 211 └───────────────────┘ 212 ``` 213 214 ## EFI Variables Interface 215 216 Linux provides access to UEFI variables via: 217 218 ``` 219 /sys/firmware/efi/efivars/ 220 ``` 221 222 Example: Reading Secure Boot state: 223 224 ```bash 225 cat /sys/firmware/efi/efivars/SecureBoot-8be4df61-93ca-11d2-aa0d-00e098032b8c | hexdump -C 226 ``` 227 228 The `efivarfs` filesystem is mounted automatically: 229 230 ``` 231 CONFIG_EFIVAR_FS=y 232 ``` 233 234 ## Boot Services Memory Map 235 236 The UEFI firmware provides memory map to the kernel: 237 238 | Type | Description | 239 |------|-------------| 240 | EfiConventionalMemory | Usable RAM | 241 | EfiLoaderCode | Bootloader code | 242 | EfiLoaderData | Bootloader data | 243 | EfiBootServicesCode | UEFI boot services | 244 | EfiBootServicesData | UEFI boot data | 245 | EfiRuntimeServicesCode | UEFI runtime code | 246 | EfiRuntimeServicesData | UEFI runtime data | 247 | EfiACPIReclaimMemory | ACPI tables | 248 | EfiACPIMemoryNVS | ACPI NVS | 249 | EfiMemoryMappedIO | Device MMIO | 250 | EfiReservedMemoryType | Reserved | 251 252 The kernel uses `SetVirtualAddressMap()` to establish virtual mappings 253 for runtime services access after ExitBootServices().