1# AMD Platform Security Processor (PSP) Firmware Integration Guide 2 3The following content defines the structures of PSP tables and describes the 4firmware images integrated into a functioning system. Further details of 5each Platform Security Processor (PSP) firmware blob or PSP feature are 6beyond the scope of this document, and may be found in AMD NDA publications. 7 8The current name for the security technology is "AMD Secure Processor". 9To be consistent with the latest documentation, and because of familiarity 10with the older name, this document continues with "Platform Security Processor" 11and "PSP". 12 13## Platform Security Processor (PSP) Overview 14 15The Platform Security Processor (PSP) is an on-die, isolated security processor 16that runs independently from the main x86 cores of the platform. 17Security-sensitive components run on the PSP without being affected by the 18commodity or untrusted software running on the x86 cores. The PSP executes 19its own firmware and shares the SPI flash storage that is used by the 20system BIOS. 21 22## Embedded Firmware Structure 23 24The PSP identifies its important tables by first locating the Embedded Firmware 25Structure. It reads specific addresses in the SPI flash, from top to bottom, 26attempting to identify the signature. The locations (for clarity, the x86 27physical addresses) checked are: 28* 0xfffa0000 29* 0xfff20000 30* 0xffe20000 31* 0xffc20000 32* 0xff820000 33* 0xff020000 34 35Most coreboot implementations provide flexibility to position the structure in 36any of the eligible locations. Below are typical definitions within the 37structure (for all families combined). Individual features supported vary by 38family and model. 39 40```{eval-rst} 41+--------------+---------------+------------------+----------------------------+ 42| Field Name | Offset (Hex) | Size (In Bytes) | Description/Purpose | 43+==============+===============+==================+============================+ 44| Signature | 0x00 | 4 | 0x55aa55aa | 45+--------------+---------------+------------------+----------------------------+ 46| IMC FW | 0x04 | 4 | Integrated Micro | 47| | | | Controller: unsupported | 48| | | | but functional in some | 49| | | | systems | 50+--------------+---------------+------------------+----------------------------+ 51| GbE FW | 0x08 | 4 | Gigabit Ethernet | 52+--------------+---------------+------------------+----------------------------+ 53| xHCI FW | 0x0c | 4 | xHCI firmware | 54+--------------+---------------+------------------+----------------------------+ 55| PSP Dir Tbl | 0x10 | 4 | Pointer to PSP Directory | 56| | | | Table (early devices) | 57+--------------+---------------+------------------+----------------------------+ 58| PSP Dir Tbl | 0x14 | 4 | Pointer to PSP Directory | 59| | | | Table (later devices and | 60| | | | is combo capable) | 61+--------------+---------------+------------------+----------------------------+ 62| BIOS Dir Tbl | 0x18 | 4 | Pointer to BIOS Directory | 63| | | | Table for models n* | 64+--------------+---------------+------------------+----------------------------+ 65| BIOS Dir Tbl | 0x1c | 4 | Pointer to BIOS Directory | 66| | | | Table for models nn | 67+--------------+---------------+------------------+----------------------------+ 68| BIOS Dir Tbl | 0x20 | 4 | Pointer to BIOS Directory | 69| | | | Table for models nnn | 70+--------------+---------------+------------------+----------------------------+ 71| … | | | ... | 72+--------------+---------------+------------------+----------------------------+ 73``` 74 75* The Embedded Firmware Structure may support pointers to multiple generations 76 of devices, e.g. Family 17h Models 00h-0Fh, Family 17h Models 10h-1Fh, etc. 77 Details are specific to the implementation. 78 79## PSP Directory Table 80 81The PSP Directory Table allows the PSP to find and load various images. A 82second level table may be generated to allow updates without the risk of 83corrupting the primary table. Certain models support a combo type table, 84allowing secondary tables to be referenced by device ID. No coreboot 85implementations currently use combo tables. 86 87### PSP Directory Table Header 88```{eval-rst} 89+--------------+---------------+------------------+----------------------------+ 90| Field Name | Offset (Hex) | Size (In Bytes) | Description/Purpose | 91+==============+===============+==================+============================+ 92| PSP Cookie | 0x00 | 4 | PSP cookie "$PSP" to | 93| | | | recognize the header. | 94| | | | Cookie “$PL2” for level 2 | 95+--------------+---------------+------------------+----------------------------+ 96| Checksum | 0x04 | 4 | 32-bit CRC value of header | 97| | | | below this field and | 98| | | | including all entries | 99+--------------+---------------+------------------+----------------------------+ 100| Total Entries| 0x08 | 4 | Number of PSP Directory | 101| | | | entries in the table | 102+--------------+---------------+------------------+----------------------------+ 103| Reserved | 0x0C | 4 | Reserved - Set to zero | 104+--------------+---------------+------------------+----------------------------+ 105``` 106 107### PSP Directory Table Entries 108```{eval-rst} 109+--------------+---------------+------------------+----------------------------+ 110| Field Name | Offset (Hex) | Size (In Bits) | Description/Purpose | 111+==============+===============+==================+============================+ 112| Type | 0x00 | 8 | Entry type (see below) | 113+--------------+---------------+------------------+----------------------------+ 114| Sub Program | 0x01 | 8 | Specifies sub program | 115+--------------+---------------+------------------+----------------------------+ 116| Reserved | 0x02 | 16 | Reserved - set to 0 | 117+--------------+---------------+------------------+----------------------------+ 118| Size | 0x04 | 32 | Size of PSP entry in bytes | 119+--------------+---------------+------------------+----------------------------+ 120| Location / | 0x08 | 62 | Location: Physical Address | 121| Value | | | of SPIROM location where | 122| | | | corresponding PSP entry | 123| | | | located. | 124| | | | | 125| | | | Value: 62-bit value for the| 126| | | | PSP Entry | 127+--------------+---------------+------------------+----------------------------+ 128| Address Mode | 0x0F[7:6] | 2 | 00: x86 Physical address | 129| | | | 01: offset from start of | 130| | | | BIOS (flash offset) | 131| | | | 02: offset from start of | 132| | | | directory header | 133| | | | 03: offset from start of | 134| | | | partition | 135+--------------+---------------+------------------+----------------------------+ 136 137``` 138### PSP Directory Table Types 139 140**0x00**: AMD public key 141* Public key used by on-chip bootcode to verify the signature of PSP boot 142 loader firmware. 143 144**0x01**: PSP boot loader firmware 145* Second stage boot loader firmware to be loaded by on-chip bootcode. 146 147**0x02**: PSP SecureOS firmware 148* Off-chip PSP boot loader will be overwritten in SRAM by the Secure/Trusted 149 OS during initial boot up. 150* PSP SecureOS performs: 151 * Initialization of OS internal structures and instantiates the fTPM as a 152 trusted application 153 * Sets up CPU/BIOS-PSP interface registers 154 * Enters steady state idling and waiting for commands 155 * In steady state, on notification, prepares for S3 state 156 * Verify and loading GFX Firmware 157 158**0x03**: PSP recovery boot loader firmware 159* Recovery PSP boot loader image, loaded by on-chip bootcode in case of 160 failure in loading PSP boot loader. 161 162**0x08**: SMU off-chip firmware 163 164**0x12**: SMU off-chip firmware section 2 165* Power Management firmware, responsible for system power/clock management. 166 167**0x09**: Secure Debug unlock public key 168* Public key token used during Secure Debug unlock process to verify message 169 payload from AMD server. 170 171**0x0b**: Soft fuse chain 172* Refer to documentation for definitions. (See External References below.) 173 174**0x0c**: PSP trustlet binaries 175* Optional file to enable fTPM. 176 177**0x13**: PSP Secure Debug unlock debug image 178* Secure Debug unlock firmware image, used to unlock the device. 179 180**0x21**: Wrapped iKEK 181* Intermediate Key Encryption Key, used to decrypt encrypted firmware images. 182 This is mandatory in order to support encrypted firmware. 183 184**0x22**: PSP Token Unlock data 185* Used to support time-bound Secure Debug unlock during boot. This entry may 186 be omitted if the Token Unlock debug feature is not required. 187 188**0x24**: Security policy binary 189* A security policy is applied to restrict the untrusted access to security 190 sensitive regions. 191 192**0x25**: MP2 firmware 193* The MP2 of the SMU, also known as the Sensor Fusion Integration is used to 194 aggregate the data from various sensors such as accelerometer, gyrometer, 195 ambient light sensor, orientation sensor, etc. This is off-chip firmware 196 for Sensor Fusion Processor (SFP) subsystem of the SMU. 197 198**0x28**: System driver 199* Driver executing on top of SecureOS. 200 201**0x30 - 0x37**: PSP AGESA binaries 202* AGESA Boot Loaders (ABLs) are a set of binary images executed by the PSP. 203 They are responsible for initializing APU silicon components (including but 204 not limited to APU memory interface) on S5, S4 and S3, prior to releasing 205 the main cores from reset. 206 207**0x3a**: Whitelist 208* Optional image containing a signed whitelist of one or more serial numbers. 209 210**0x40**: Pointer to secondary table 211* Pointer to PSP Directory Table level 2. 212 213**0x52**: PSP boot loader usermode OEM application 214* Supported only in certain SKUs. 215 216### Firmware Version of Binaries 217 218Every firmware binary contains 256 bytes of a PSP Header, which includes 219the firmware version. The version is made up of the four bytes located at 220offset 0x60 in the binary image. 221 222For example, in the PSP BootLoader: 223 224 0000000: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 225 0000010: 2450 5331 c0e1 0000 0100 0000 0000 0000 $PS1............ 226 0000020: 5c0a ddb8 b279 4846 e154 aa4c ed7d 414d \....yHF.T.L.}AM 227 0000030: 0100 0000 0000 0000 60bb a67e 1a43 4c6b ........`..~.CLk 228 0000040: 9807 bc8d fdb4 1f40 0000 0000 0000 0000 .......@........ 229 0000050: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 230 0000060: 7401 0800 ffff ffff 0001 0000 c0e3 0000 t............... 231 0000070: 0000 0000 0000 0000 0000 0000 0100 0000 ................ 232 0000080: 4766 9186 9d5f e909 492d 491d d9ee 8e6c Gf..._..I-I....l 233 0000090: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 234 00000a0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 235 00000b0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 236 00000c0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 237 00000d0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 238 00000e0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 239 00000f0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ 240 241The PSP BootLoader version is 00.08.01.74. 242 243Note that only Firmware binary images have versions. Key tokens are not 244versioned, as there will not be multiple keys. Keys are unique to processor 245family. 246 247### BIOS Directory Table Entry Types 248 249All x86 accessible components (both executable and data blobs) are found via 250the BIOS Directory Table. A second level table may be generated to allow for 251updates without the risk of corrupting the primary table. 252 253The BIOS Directory table structure is slightly different from the PSP Directory: 254* Multiple instances of firmware components are allowed for one specific type 255* The type field is further structured to reflect attributes of BIOS 256 components such as "Region Type", "Reset Image", "Copy Image", "Read Only", 257 allowing design flexibility 258* The "Destination Address" field is added for specific entries that are 259 expected to be copied from boot media to specific memory location 260 261### BIOS Directory Table Header 262 263```{eval-rst} 264+--------------+---------------+------------------+----------------------------+ 265| Field Name | Offset (Hex) | Size (In Bytes) | Description/Purpose | 266+==============+===============+==================+============================+ 267| BIOS Cookie | 0x00 | 4 | BIOS cookie "$BHD" to | 268| | | | recognize the header. | 269| | | | Cookie “$BL2” for level 2 | 270+--------------+---------------+------------------+----------------------------+ 271| Checksum | 0x04 | 4 | 32 bit CRC value of header | 272| | | | below this field and | 273| | | | including all entries | 274+--------------+---------------+------------------+----------------------------+ 275| Total Entries| 0x08 | 4 | Number of BIOS Directory | 276| | | | entries in the table | 277+--------------+---------------+------------------+----------------------------+ 278| Reserved | 0x0C | 4 | Reserved - Set to zero | 279+--------------+---------------+------------------+----------------------------+ 280``` 281 282### BIOS Directory Table Entries 283 284```{eval-rst} 285+--------------+---------------+------------------+----------------------------+ 286| Field Name | Offset (Hex) | Size (In Bits) | Description/Purpose | 287+==============+===============+==================+============================+ 288| Type | 0x00 | 8 | Entry type (see below) | 289+--------------+---------------+------------------+----------------------------+ 290| Region Type | 0x01 | 8 | Setup the memory region's | 291| | | | security attribute for the | 292| | | | BIOS entry | 293+--------------+---------------+------------------+----------------------------+ 294| Reset Image | 0x02[0] | 1 | Boolean value to define the| 295| | | | BIOS entry is a reset | 296| | | | binary image | 297+--------------+---------------+------------------+----------------------------+ 298| Copy Image | 0x02[1] | 1 | Define the binary image of | 299| | | | the BIOS entry is for | 300| | | | copying over to the memory | 301| | | | region | 302+--------------+---------------+------------------+----------------------------+ 303| Read Only | 0x02[2] | 1 | Setup the memory region for| 304| | | | the BIOS entry to read only| 305+--------------+---------------+------------------+----------------------------+ 306| Compressed | 0x02[3] | 1 | Compressed using zlib | 307| | | | | 308+--------------+---------------+------------------+----------------------------+ 309| Instance | 0x02[7:4] | 4 | Specify the Instance of an | 310| | | | entry | 311+--------------+---------------+------------------+----------------------------+ 312| SubProgram | 0x03[2:0] | 3 | Specify the SubProgram | 313+--------------+---------------+------------------+----------------------------+ 314| RomId | 0x03[4:3] | 2 | Which SPI device the | 315| | | | content is placed in | 316+--------------+---------------+------------------+----------------------------+ 317| Writeable | 0x03[5] | 1 | Region is writable or read | 318| | | | only | 319+--------------+---------------+------------------+----------------------------+ 320| Reserved | 0x03[7:6] | 2 | Reserved - Set to zero | 321+--------------+---------------+------------------+----------------------------+ 322| Size | 0x04 | 32 | Memory Region Size | 323+--------------+---------------+------------------+----------------------------+ 324| Source | 0x08 | 62 | Physical Address of SPIROM | 325| Address | | | location where the data for| 326| | | | the corresponding entry is | 327| | | | located | 328+--------------+---------------+------------------+----------------------------+ 329| Entry Address| 0x0F[7:6] | 2 | Same as Entry Address Mode | 330| Mode | | | in PSP directory table | 331| | | | entry fields | 332+--------------+---------------+------------------+----------------------------+ 333| Destination | 0x10 | 64 | Destination Address of | 334| Address | | | memory location where the | 335| | | | data for the corresponding | 336| | | | BIOS Entry is copied | 337+--------------+---------------+------------------+----------------------------+ 338``` 339 340### BIOS Directory Table Entry Types 341 342**0x60**: APCB data 343* Source field points to the AGESA PSP Customization Block (APCB) data. 344 345**0x68**: Backup copy of APCB data 346* Source field points to the backup copy of the AGESA PSP Customization Block 347 (APCB) data. 348 349**0x61**: APOB data 350* Location field points to the AGESA PSP Output Block (APOB) data. 351 352**0x62**: BIOS reset image 353* Source field points to BIOS binary image in flash. Destination points to 354 DRAM. 355 356**0x63**: APOB data NV 357* Source field points to the AGESA PSP Output Block (APOB) data NV copy. 358 This data is written by coreboot and replayed by PSP ABLs during S3 resume 359 and in certain S5 boots. 360 361**0x64**: PMU firmware (instruction) 362* Source field points to the instruction portion of Phy Microcontroller Unit 363 firmware. 364 365**0x65**: PMU firmware (data) 366* Source field points to the data portion of Phy Microcontroller Unit 367 firmware. 368 369**0x66**: x86 microcode patch 370* Source field points to the microcode patch. 371 372**0x6a**: MP2 FW config file 373* Source field points to the MP2 FW configuration file. 374 375**0x70**: Pointer to secondary table 376* Pointer to BIOS Directory Table level 2. 377 378## Tools 379 380### amdcompress 381 382`cbfstool/amdcompress` is a helper for creating the BIOS Reset Image (BIOS 383Directory Table type 0x62). This is the code the PSP uncompresses into DRAM 384at the location where the x86 begins execution when released from reset. 385Typical usage is for amdcompress to convert an ELF file’s program section 386into a zlib compressed image. 387 388### amdfwtool 389 390All images requiring PSP functionality rely on the amdfwtool utility. 391amdfwtool takes image names as command-line arguments, as well as the size of 392the flash device, and intended location of the Embedded Firmware Structure. 393Its output is a monolithic image with correctly positioned headers, pointers, 394structures, and the firmware images added. The file, typically named 395`amdfw.rom`, may then be added directly into the coreboot image. 396 397## External Reference 398 399* NDA document #55758: *AMD Platform Security Processor BIOS Architecture 400 Design Guide for AMD Family 17h Processors* 401* NDA document #54267 *AMD Platform Security Processor BIOS Architecture 402 Design Guide*: For all devices earlier than Family 17h 403