Documentation/soc/amd: Add PSP integration information

Change-Id: I05187365158eb5c055be0d4a32f41324d2653f71
Signed-off-by: Marshall Dawson <marshalldawson3rd@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/37847
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Held <felix-coreboot@felixheld.de>

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