1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
|
# 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.
```eval_rst
+--------------+---------------+------------------+----------------------------+
| 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
```eval_rst
+--------------+---------------+------------------+----------------------------+
| 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
```eval_rst
+--------------+---------------+------------------+----------------------------+
| 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 | 62 | Location: Physical Address |
| Value | | | of SPIROM location where |
| | | | corresponding PSP entry |
| | | | located. |
| | | | |
| | | | Value: 62-bit value for the|
| | | | PSP Entry |
+--------------+---------------+------------------+----------------------------+
| Address Mode | 0x0F[7:6] | 2 | 00: x86 Physical address |
| | | | 01: offset from start of |
| | | | BIOS (flash offset) |
| | | | 02: offset from start of |
| | | | directory header |
| | | | 03: offset from start of |
| | | | partition |
+--------------+---------------+------------------+----------------------------+
```
### 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.
**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.
**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.
### 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
```eval_rst
+--------------+---------------+------------------+----------------------------+
| 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
```eval_rst
+--------------+---------------+------------------+----------------------------+
| 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 |
+--------------+---------------+------------------+----------------------------+
| RomId | 0x03[4:3] | 2 | Which SPI device the |
| | | | content is placed in |
+--------------+---------------+------------------+----------------------------+
| Writeable | 0x03[5] | 1 | Region is writable or read |
| | | | only |
+--------------+---------------+------------------+----------------------------+
| Reserved | 0x03[7:6] | 2 | Reserved - Set to zero |
+--------------+---------------+------------------+----------------------------+
| Size | 0x04 | 32 | Memory Region Size |
+--------------+---------------+------------------+----------------------------+
| Source | 0x08 | 62 | Physical Address of SPIROM |
| Address | | | location where the data for|
| | | | the corresponding entry is |
| | | | located |
+--------------+---------------+------------------+----------------------------+
| Entry Address| 0x0F[7:6] | 2 | Same as Entry Address Mode |
| Mode | | | in PSP directory table |
| | | | entry fields |
+--------------+---------------+------------------+----------------------------+
| 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
|
