Makefile.inc: Remove workaround ACPI warnings
[coreboot.git] / Documentation / soc / amd / psp_integration.md
blobec5e0616fd1db409697fc9a4d312c865bf13161e
1 # AMD Platform Security Processor (PSP) Firmware Integration Guide
3 The following content defines the structures of PSP tables and describes the
4 firmware images integrated into a functioning system.  Further details of
5 each Platform Security Processor (PSP) firmware blob or PSP feature are
6 beyond the scope of this document, and may be found in AMD NDA publications.
8 The current name for the security technology is "AMD Secure Processor".
9 To be consistent with the latest documentation, and because of familiarity
10 with the older name, this document continues with "Platform Security Processor"
11 and "PSP".
13 ## Platform Security Processor (PSP) Overview
15 The Platform Security Processor (PSP) is an on-die, isolated security processor
16 that runs independently from the main x86 cores of the platform.
17 Security-sensitive components run on the PSP without being affected by the
18 commodity or untrusted software running on the x86 cores. The PSP executes
19 its own firmware and shares the SPI flash storage that is used by the
20 system BIOS.
22 ## Embedded Firmware Structure
24 The PSP identifies its important tables by first locating the Embedded Firmware
25 Structure.  It reads specific addresses in the SPI flash, from top to bottom,
26 attempting to identify the signature.  The locations (for clarity, the x86
27 physical addresses) checked are:
28 *   0xfffa0000
29 *   0xfff20000
30 *   0xffe20000
31 *   0xffc20000
32 *   0xff820000
33 *   0xff020000
35 Most coreboot implementations provide flexibility to position the structure in
36 any of the eligible locations.  Below are typical definitions within the
37 structure (for all families combined).  Individual features supported vary by
38 family and model.
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 ```
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.
79 ## PSP Directory Table
81 The PSP Directory Table allows the PSP to find and load various images.  A
82 second level table may be generated to allow updates without the risk of
83 corrupting the primary table.  Certain models support a combo type table,
84 allowing secondary tables to be referenced by device ID.  No coreboot
85 implementations currently use combo tables.
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 +--------------+---------------+------------------+----------------------------+
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 +--------------+---------------+------------------+----------------------------+
138 ### PSP Directory Table Types
140 **0x00**: AMD public key
141 *   Public key used by on-chip bootcode to verify the signature of PSP boot
142     loader firmware.
144 **0x01**: PSP boot loader firmware
145 *   Second stage boot loader firmware to be loaded by on-chip bootcode.
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
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.
162 **0x08**: SMU off-chip firmware
164 **0x12**: SMU off-chip firmware section 2
165 *   Power Management firmware, responsible for system power/clock management.
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.
171 **0x0b**: Soft fuse chain
172 *   Refer to documentation for definitions.  (See External References below.)
174 **0x0c**: PSP trustlet binaries
175 *   Optional file to enable fTPM.
177 **0x13**: PSP Secure Debug unlock debug image
178 *   Secure Debug unlock firmware image, used to unlock the device.
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.
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.
188 **0x24**: Security policy binary
189 *   A security policy is applied to restrict the untrusted access to security
190     sensitive regions.
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.
198 **0x28**: System driver
199 *   Driver executing on top of SecureOS.
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.
207 **0x3a**: Whitelist
208 *   Optional image containing a signed whitelist of one or more serial numbers.
210 **0x40**: Pointer to secondary table
211 *   Pointer to PSP Directory Table level 2.
213 **0x52**: PSP boot loader usermode OEM application
214 *   Supported only in certain SKUs.
216 ### Firmware Version of Binaries
218 Every firmware binary contains 256 bytes of a PSP Header, which includes
219 the firmware version. The version is made up of the four bytes located at
220 offset 0x60 in the binary image.
222 For example, in the PSP BootLoader:
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  ................
241 The PSP BootLoader version is 00.08.01.74.
243 Note that only Firmware binary images have versions.  Key tokens are not
244 versioned, as there will not be multiple keys.  Keys are unique to processor
245 family.
247 ### BIOS Directory Table Entry Types
249 All x86 accessible components (both executable and data blobs) are found via
250 the BIOS Directory Table.  A second level table may be generated to allow for
251 updates without the risk of corrupting the primary table.
253 The 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
261 ### BIOS Directory Table Header
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 +--------------+---------------+------------------+----------------------------+
282 ### BIOS Directory Table Entries
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 +--------------+---------------+------------------+----------------------------+
340 ### BIOS Directory Table Entry Types
342 **0x60**: APCB data
343 *   Source field points to the AGESA PSP Customization Block (APCB) data.
345 **0x68**: Backup copy of APCB data
346 *   Source field points to the backup copy of the AGESA PSP Customization Block
347     (APCB) data.
349 **0x61**: APOB data
350 *   Location field points to the AGESA PSP Output Block (APOB) data.
352 **0x62**: BIOS reset image
353 *   Source field points to BIOS binary image in flash.  Destination points to
354     DRAM.
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.
361 **0x64**: PMU firmware (instruction)
362 *   Source field points to the instruction portion of Phy Microcontroller Unit
363     firmware.
365 **0x65**: PMU firmware (data)
366 *   Source field points to the data portion of Phy Microcontroller Unit
367     firmware.
369 **0x66**: x86 microcode patch
370 *   Source field points to the microcode patch.
372 **0x6a**: MP2 FW config file
373 *   Source field points to the MP2 FW configuration file.
375 **0x70**: Pointer to secondary table
376 *   Pointer to BIOS Directory Table level 2.
378 ## Tools
380 ### amdcompress
382 `cbfstool/amdcompress` is a helper for creating the BIOS Reset Image (BIOS
383 Directory Table type 0x62).  This is the code the PSP uncompresses into DRAM
384 at the location where the x86 begins execution when released from reset.
385 Typical usage is for amdcompress to convert an ELF file’s program section
386 into a zlib compressed image.
388 ### amdfwtool
390 All images requiring PSP functionality rely on the amdfwtool utility.
391 amdfwtool takes image names as command-line arguments, as well as the size of
392 the flash device, and intended location of the Embedded Firmware Structure.
393 Its output is a monolithic image with correctly positioned headers, pointers,
394 structures, and the firmware images added.  The file, typically named
395 `amdfw.rom`, may then be added directly into the coreboot image.
397 ## External Reference
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