diff options
| -rw-r--r-- | Documentation/soc/amd/family15h.md | 1 | ||||
| -rwxr-xr-x | Documentation/soc/amd/family17h.md | 18 | ||||
| -rw-r--r-- | Documentation/soc/amd/index.md | 1 | ||||
| -rwxr-xr-x | Documentation/soc/amd/psp_integration.md | 376 |
4 files changed, 387 insertions, 9 deletions
diff --git a/Documentation/soc/amd/family15h.md b/Documentation/soc/amd/family15h.md index fc41e91de2..5a8f95d601 100644 --- a/Documentation/soc/amd/family15h.md +++ b/Documentation/soc/amd/family15h.md @@ -47,3 +47,4 @@ structure. 3. [Models 30h-3Fh BKDG](https://www.amd.com/system/files/TechDocs/49125_15h_Models_30h-3Fh_BKDG.pdf) 4. [Models 60h-6Fh BKDG](https://www.amd.com/system/files/TechDocs/50742_15h_Models_60h-6Fh_BKDG.pdf) 5. [Models 70h-7Fh BKDG](https://www.amd.com/system/files/TechDocs/55072_AMD_Family_15h_Models_70h-7Fh_BKDG.pdf) +6. [PSP Integration](psp_integration.md) diff --git a/Documentation/soc/amd/family17h.md b/Documentation/soc/amd/family17h.md index dc3de13ffe..9608b57325 100755 --- a/Documentation/soc/amd/family17h.md +++ b/Documentation/soc/amd/family17h.md @@ -18,8 +18,8 @@ To the extent necessary, the role of the Platform Security Processor (a.k.a. PSP) in system initialization is addressed here. AMD has historically required an NDA for access to the PSP specification<sup>1</sup>. coreboot relies on util/amdfwtool to build -the structures and add various other firmware to the final image. The -Family 17h PSP design guide adds a new BIOS Directory Table, similar to +the structures and add various other firmware to the final image<sup>2</sup>. +The Family 17h PSP design guide adds a new BIOS Directory Table, similar to the PSP Directory Table. Support in coreboot for modern AMD products is based on AMD’s @@ -29,12 +29,12 @@ configuring proprietary core logic, assistance with generating ACPI tables, and other features. AGESA for products earlier than Family 17h is known as v5 or -Arch2008<sup>2</sup>. Also note that coreboot currently contains both +Arch2008<sup>3</sup>. Also note that coreboot currently contains both open source AGESA and closed source implementations (binaryPI) compiled from AGESA. The first AMD Family 17h device ported to coreboot is codenamed -“Picasso”<sup>3</sup>, and will be added to soc/amd/picasso. +“Picasso”<sup>4</sup>, and will be added to soc/amd/picasso. ## Additional Definitions @@ -207,7 +207,7 @@ the existing v5 interface impractical. Given the UEFI nature of modern AGESA, and the existing open source work from Intel, Picasso shall support AGESA via an FSP-like prebuilt -image. The Intel Firmware Support Package<sup>4</sup> combines +image. The Intel Firmware Support Package<sup>5</sup> combines reference code with EDK II source to create a modular image with discoverable entry points. coreboot source already contains knowledge of FSP, how to parse it, integrate it, and how to communicate with it. @@ -218,7 +218,7 @@ of FSP, how to parse it, integrate it, and how to communicate with it. for AMD Family 17h Processors” (PID #55758) and “AMD Platform Security Processor BIOS Architecture Design Guide” (PID #54267) for earlier products -2. [https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf](https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf) -3. [https://en.wikichip.org/wiki/amd/cores/picasso](https://en.wikichip.org/wiki/amd/cores/picasso) -4. [https://www.intel.com/content/www/us/en/intelligent-systems/intel-firmware-support-package/intel-fsp-overview.html](https://www.intel.com/content/www/us/en/intelligent-systems/intel-firmware-support-package/intel-fsp-overview.html) - +2. [PSP Integration](psp_integration.md) +3. [https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf](https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf) +4. [https://en.wikichip.org/wiki/amd/cores/picasso](https://en.wikichip.org/wiki/amd/cores/picasso) +5. [https://www.intel.com/content/www/us/en/intelligent-systems/intel-firmware-support-package/intel-fsp-overview.html](https://www.intel.com/content/www/us/en/intelligent-systems/intel-firmware-support-package/intel-fsp-overview.html) diff --git a/Documentation/soc/amd/index.md b/Documentation/soc/amd/index.md index 80413b0937..e4fa6c9337 100644 --- a/Documentation/soc/amd/index.md +++ b/Documentation/soc/amd/index.md @@ -6,6 +6,7 @@ This section contains documentation about coreboot on specific AMD SOCs. - [Family 15h](family15h.md) - [Family 17h](family17h.md) +- [Platform Security Processor Integration](psp_integration.md) ## amd_blobs Repository License diff --git a/Documentation/soc/amd/psp_integration.md b/Documentation/soc/amd/psp_integration.md new file mode 100755 index 0000000000..5f53a39f05 --- /dev/null +++ b/Documentation/soc/amd/psp_integration.md @@ -0,0 +1,376 @@ +# AMD Platform Security Processor (PSP) Firmware Integration Guide + +The following content defines the structures of PSP tables and describes the +firmware images integrated into a functioning system. Further details of +each Platform Security Processor (PSP) firmware blob or PSP feature are +beyond the scope of this document, and may be found in AMD NDA publications. + +The current name for the security technology is "AMD Secure Processor". +To be consistent with the latest documentation, and because of familiarity +with the older name, this document continues with "Platform Security Processor" +and "PSP". + +## Platform Security Processor (PSP) Overview + +The Platform Security Processor (PSP) is an on-die, isolated security processor +that runs independently from the main x86 cores of the platform. +Security-sensitive components run on the PSP without being affected by the +commodity or untrusted software running on the x86 cores. The PSP executes +its own firmware and shares the SPI flash storage that is used by the +system BIOS. + +## Embedded Firmware Structure + +The PSP identifies its important tables by first locating the Embedded Firmware +Structure. It reads specific addresses in the SPI flash, from top to bottom, +attempting to identify the signature. The locations (for clarity, the x86 +physical addresses) checked are: +* 0xfffa0000 +* 0xfff20000 +* 0xffe20000 +* 0xffc20000 +* 0xff820000 +* 0xff020000 + +Most coreboot implementations provide flexibility to position the structure in +any of the eligible locations. Below are typical definitions within the +structure (for all families combined). Individual features supported vary by +family and model. + + +--------------+---------------+------------------+----------------------------+ + | Field Name | Offset (Hex) | Size (In Bytes) | Description/Purpose | + +--------------+---------------+------------------+----------------------------+ + | Signature | 0x00 | 4 | 0x55aa55aa | + |--------------|---------------|------------------|----------------------------| + | IMC FW | 0x04 | 4 | Integrated Micro | + | | | | Controller: unsupported | + | | | | but functional in some | + | | | | systems | + |--------------|---------------|------------------|----------------------------| + | GbE FW | 0x08 | 4 | Gigabit Ethernet | + |--------------|---------------|------------------|----------------------------| + | xHCI FW | 0x0c | 4 | xHCI firmware | + |--------------|---------------|------------------|----------------------------| + | PSP Dir Tbl | 0x10 | 4 | Pointer to PSP Directory | + | | | | Table (early devices) | + |--------------|---------------|------------------|----------------------------| + | PSP Dir Tbl | 0x14 | 4 | Pointer to PSP Directory | + | | | | Table (later devices and | + | | | | is combo capable) | + |--------------|---------------|------------------|----------------------------| + | BIOS Dir Tbl | 0x18 | 4 | Pointer to BIOS Directory | + | | | | Table for models n* | + |--------------|---------------|------------------|----------------------------| + | BIOS Dir Tbl | 0x1c | 4 | Pointer to BIOS Directory | + | | | | Table for models nn | + |--------------|---------------|------------------|----------------------------| + | BIOS Dir Tbl | 0x20 | 4 | Pointer to BIOS Directory | + | | | | Table for models nnn | + |--------------|---------------|------------------|----------------------------| + | … | | | ... | + +--------------+---------------+------------------+----------------------------+ + +* The Embedded Firmware Structure may support pointers to multiple generations + of devices, e.g. Family 17h Models 00h-0Fh, Family 17h Models 10h-1Fh, etc. + Details are specific to the implementation. + +## PSP Directory Table + +The PSP Directory Table allows the PSP to find and load various images. A +second level table may be generated to allow updates without the risk of +corrupting the primary table. Certain models support a combo type table, +allowing secondary tables to be referenced by device ID. No coreboot +implementations currently use combo tables. + +### PSP Directory Table Header + + +--------------+---------------+------------------+----------------------------+ + | Field Name | Offset (Hex) | Size (In Bytes) | Description/Purpose | + +--------------+---------------+------------------+----------------------------+ + | PSP Cookie | 0x00 | 4 | PSP cookie "$PSP" to | + | | | | recognize the header. | + | | | | Cookie “$PL2” for level 2 | + |--------------|---------------|------------------|----------------------------| + | Checksum | 0x04 | 4 | 32-bit CRC value of header | + | | | | below this field and | + | | | | including all entries | + |--------------|---------------|------------------|----------------------------| + | Total Entries| 0x08 | 4 | Number of PSP Directory | + | | | | entries in the table | + |--------------|---------------|------------------|----------------------------| + | Reserved | 0x0C | 4 | Reserved - Set to zero | + +--------------+---------------+------------------+----------------------------+ + +### PSP Directory Table Entries + + +--------------+---------------+------------------+----------------------------+ + | Field Name | Offset (Hex) | Size (In Bits) | Description/Purpose | + +--------------+---------------+------------------+----------------------------+ + | Type | 0x00 | 8 | Entry type (see below) | + |--------------|---------------|------------------|----------------------------| + | Sub Program | 0x01 | 8 | Specifies sub program | + |--------------|---------------|------------------|----------------------------| + | Reserved | 0x02 | 16 | Reserved - set to 0 | + |--------------|---------------|------------------|----------------------------| + | Size | 0x04 | 32 | Size of PSP entry in bytes | + |--------------|---------------|------------------|----------------------------| + | Location / | 0x08 | 64 | Location: Physical Address | + | Value | | | of SPIROM location where | + | | | | corresponding PSP entry | + | | | | located. | + | | | | | + | | | | Value: 64-bit value for the| + | | | | PSP Entry | + +--------------+---------------+------------------+----------------------------+ + +### PSP Directory Table Types + +**0x00**: AMD public key +* Public key used by on-chip bootcode to verify the signature of PSP boot + loader firmware. + +**0x01**: PSP boot loader firmware +* Second stage boot loader firmware to be loaded by on-chip bootcode. + +**0x02**: PSP SecureOS firmware +* Off-chip PSP boot loader will be overwritten in SRAM by the Secure/Trusted + OS during initial boot up. +* PSP SecureOS performs: + * Initialization of OS internal structures and instantiates the fTPM as a + trusted application + * Sets up CPU/BIOS-PSP interface registers + * Enters steady state idling and waiting for commands + * In steady state, on notification, prepares for S3 state + * Verify and loading GFX Firmware + +**0x03**: PSP recovery boot loader firmware +* Recovery PSP boot loader image, loaded by on-chip bootcode in case of + failure in loading PSP boot loader. + +**0x08**: SMU off-chip firmware + +**0x12**: SMU off-chip firmware section 2 +* Power Management firmware, responsible for system power/clock management. + +**0x09**: Secure Debug unlock public key +* Public key token used during Secure Debug unlock process to verify message + payload from AMD server. + +**0x0b**: Soft fuse chain +* Refer to documentation for definitions. (See External References below.) + +**0x0c**: PSP trustlet binaries +* Optional file to enable fTPM. + +**0x13**: PSP Secure Debug unlock debug image +* Secure Debug unlock firmware image, used to unlock the device. + +**0x21**: Wrapped iKEK +* Intermediate Key Encryption Key, used to decrypt encrypted firmware images. + This is mandatory in order to support encrypted firmware. + +**0x24**: Security policy binary +* A security policy is applied to restrict the untrusted access to security + sensitive regions. + +**0x25**: MP2 firmware +* The MP2 of the SMU, also known as the Sensor Fusion Integration is used to + aggregate the data from various sensors such as accelerometer, gyrometer, + ambient light sensor, orientation sensor, etc. This is off-chip firmware + for Sensor Fusion Processor (SFP) subsystem of the SMU. + +**0x28**: System driver +* Driver executing on top of SecureOS. + +**0x30 - 0x37**: PSP AGESA binaries +* AGESA Boot Loaders (ABLs) are a set of binary images executed by the PSP. + They are responsible for initializing APU silicon components (including but + not limited to APU memory interface) on S5, S4 and S3, prior to releasing + the main cores from reset. + +**0x3a**: Whitelist +* Optional image containing a signed whitelist of one or more serial numbers. + +**0x40**: Pointer to secondary table +* Pointer to PSP Directory Table level 2. + +**0x52**: PSP boot loader usermode OEM application +* Supported only in certain SKUs. + +**0x22**: PSP Token Unlock data +* Used to support time-bound Secure Debug unlock during boot. This entry may + be omitted if the Token Unlock debug feature is not required. + +### Firmware Version of Binaries + +Every firmware binary contains 256 bytes of a PSP Header, which includes +the firmware version. The version is made up of the four bytes located at +offset 0x60 in the binary image. + +For example, in the PSP BootLoader: + + 0000000: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 0000010: 2450 5331 c0e1 0000 0100 0000 0000 0000 $PS1............ + 0000020: 5c0a ddb8 b279 4846 e154 aa4c ed7d 414d \....yHF.T.L.}AM + 0000030: 0100 0000 0000 0000 60bb a67e 1a43 4c6b ........`..~.CLk + 0000040: 9807 bc8d fdb4 1f40 0000 0000 0000 0000 .......@........ + 0000050: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 0000060: 7401 0800 ffff ffff 0001 0000 c0e3 0000 t............... + 0000070: 0000 0000 0000 0000 0000 0000 0100 0000 ................ + 0000080: 4766 9186 9d5f e909 492d 491d d9ee 8e6c Gf..._..I-I....l + 0000090: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 00000a0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 00000b0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 00000c0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 00000d0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 00000e0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + 00000f0: 0000 0000 0000 0000 0000 0000 0000 0000 ................ + +The PSP BootLoader version is 00.08.01.74. + +Note that only Firmware binary images have versions. Key tokens are not +versioned, as there will not be multiple keys. Keys are unique to processor +family. + +### BIOS Directory Table Entry Types + +All x86 accessible components (both executable and data blobs) are found via +the BIOS Directory Table. A second level table may be generated to allow for +updates without the risk of corrupting the primary table. + +The BIOS Directory table structure is slightly different from the PSP Directory: +* Multiple instances of firmware components are allowed for one specific type +* The type field is further structured to reflect attributes of BIOS + components such as "Region Type", "Reset Image", "Copy Image", "Read Only", + allowing design flexibility +* The "Destination Address" field is added for specific entries that are + expected to be copied from boot media to specific memory location + +### BIOS Directory Table Header + + +--------------+---------------+------------------+----------------------------+ + | Field Name | Offset (Hex) | Size (In Bytes) | Description/Purpose | + +--------------+---------------+------------------+----------------------------+ + | BIOS Cookie | 0x00 | 4 | BIOS cookie "$BHD" to | + | | | | recognize the header. | + | | | | Cookie “$BL2” for level 2 | + |--------------|---------------|------------------|----------------------------| + | Checksum | 0x04 | 4 | 32 bit CRC value of header | + | | | | below this field and | + | | | | including all entries | + |--------------|---------------|------------------|----------------------------| + | Total Entries| 0x08 | 4 | Number of BIOS Directory | + | | | | entries in the table | + |--------------|---------------|------------------|----------------------------| + | Reserved | 0x0C | 4 | Reserved - Set to zero | + +--------------+---------------+------------------+----------------------------+ + +### BIOS Directory Table Entries + + +--------------+---------------+------------------+----------------------------+ + | Field Name | Offset (Hex) | Size (In Bits) | Description/Purpose | + +--------------+---------------+------------------+----------------------------+ + | Type | 0x00 | 8 | Entry type (see below) | + |--------------|---------------|------------------|----------------------------| + | Region Type | 0x01 | 8 | Setup the memory region's | + | | | | security attribute for the | + | | | | BIOS entry | + |--------------|---------------|------------------|----------------------------| + | Reset Image | 0x02[0] | 1 | Boolean value to define the| + | | | | BIOS entry is a reset | + | | | | binary image | + |--------------|---------------|------------------|----------------------------| + | Copy Image | 0x02[1] | 1 | Define the binary image of | + | | | | the BIOS entry is for | + | | | | copying over to the memory | + | | | | region | + |--------------|---------------|------------------|----------------------------| + | Read Only | 0x02[2] | 1 | Setup the memory region for| + | | | | the BIOS entry to read only| + |--------------|---------------|------------------|----------------------------| + | Compressed | 0x02[3] | 1 | Compressed using zlib | + | | | | | + |--------------|---------------|------------------|----------------------------| + | Instance | 0x02[7:4] | 4 | Specify the Instance of an | + | | | | entry | + |--------------|---------------|------------------|----------------------------| + | SubProgram | 0x03[2:0] | 3 | Specify the SubProgram | + |--------------|---------------|------------------|----------------------------| + | Reserved | 0x03[7:3] | 5 | Reserved - Set to zero | + |--------------|---------------|------------------|----------------------------| + | Size | 0x04 | 32 | Memory Region Size | + |--------------|---------------|------------------|----------------------------| + | Source | 0x08 | 64 | Physical Address of SPIROM | + | Address | | | location where the data for| + | | | | the corresponding entry is | + | | | | located | + |--------------|---------------|------------------|----------------------------| + | Destination | 0x10 | 64 | Destination Address of | + | Address | | | memory location where the | + | | | | data for the corresponding | + | | | | BIOS Entry is copied | + +--------------+---------------+------------------+----------------------------+ + +### BIOS Directory Table Entry Types + +**0x60**: APCB data +* Source field points to the AGESA PSP Customization Block (APCB) data. + +**0x68**: Backup copy of APCB data +* Source field points to the backup copy of the AGESA PSP Customization Block + (APCB) data. + +**0x61**: APOB data +* Location field points to the AGESA PSP Output Block (APOB) data. + +**0x62**: BIOS reset image +* Source field points to BIOS binary image in flash. Destination points to + DRAM. + +**0x63**: APOB data NV +* Source field points to the AGESA PSP Output Block (APOB) data NV copy. + This data is written by coreboot and replayed by PSP ABLs during S3 resume + and in certain S5 boots. + +**0x64**: PMU firmware (instruction) +* Source field points to the instruction portion of Phy Microcontroller Unit + firmware. + +**0x65**: PMU firmware (data) +* Source field points to the data portion of Phy Microcontroller Unit + firmware. + +**0x66**: x86 microcode patch +* Source field points to the microcode patch. + +**0x6a**: MP2 FW config file +* Source field points to the MP2 FW configuration file. + +**0x70**: Pointer to secondary table +* Pointer to BIOS Directory Table level 2. + +## Tools + +### amdcompress + +`cbfstool/amdcompress` is a helper for creating the BIOS Reset Image (BIOS +Directory Table type 0x62). This is the code the PSP uncompresses into DRAM +at the location where the x86 begins execution when released from reset. +Typical usage is for amdcompress to convert an ELF file’s program section +into a zlib compressed image. + +### amdfwtool + +All images requiring PSP functionality rely on the amdfwtool utility. +amdfwtool takes image names as command-line arguments, as well as the size of +the flash device, and intended location of the Embedded Firmware Structure. +Its output is a monolithic image with correctly positioned headers, pointers, +structures, and the firmware images added. The file, typically named +`amdfw.rom`, may then be added directly into the coreboot image. + +## External Reference + +* NDA document #55758: *AMD Platform Security Processor BIOS Architecture + Design Guide for AMD Family 17h Processors* +* NDA document #54267 *AMD Platform Security Processor BIOS Architecture + Design Guide*: For all devices earlier than Family 17h |