Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation/soc/amd: Add Family 17h
Begin a directory for AMD soc devices and add an explanation of how Family 17h works. Newer AMD systems use a unique paradign for initializing the x86 processors. Change-Id: I7bd8649996add80747f6a60b9dfd35a94a560be1 Signed-off-by: Marshall Dawson <marshalldawson3rd@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/33399 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Martin Roth <martinroth@google.com>
- Loading branch information
1 parent
24f73d4
commit a2455b2
Showing
3 changed files
with
233 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,224 @@ | ||
# AMD Family 17h in coreboot | ||
|
||
## Abstract | ||
|
||
Beginning with Family 17h products (a.k.a. “Zen” cores), AMD | ||
changed their paradigm for initializing the system and this requires | ||
major modifications to the execution flow of coreboot. This file | ||
discusses the new boot flow, and challenges, and the tradeoffs of the | ||
initial port into coreboot. | ||
|
||
## Introduction | ||
|
||
Family 17h products are x86-based designs. This documentation assumes | ||
familiarity with x86, its reset state and its early initialization | ||
requirements. | ||
|
||
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 PSP Directory Table. | ||
|
||
Support in coreboot for modern AMD products is based on AMD’s | ||
reference code: AMD Generic Encapsulated Software Architecture | ||
(AGESA<sup>TM</sup>). AGESA contains the technology for enabling DRAM, | ||
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 | ||
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. | ||
|
||
## Additional Definitions | ||
|
||
* PSP, Platform Security Processor: Onboard ARM processor that runs | ||
alongside the main x86 processor; may be viewed as analogous to the | ||
Intel<sup>R</sup> Management Engine | ||
* FCH, Fusion Control Hub, the logical southbridge within the SOC | ||
* ABL - AGESA Bootloader - Processor initialization code that runs on | ||
the PSP | ||
* PSP Directory Table - A structured list of pointers to PSP firmware | ||
and other controller binaries | ||
* BIOS Directory Table - A structured list of pointers to BIOS | ||
related firmware images | ||
* Embedded Firmware Structure - Signature and pointers used by the | ||
PSP to locate the PSP Directory Table and BIOS Directory Table; these | ||
items are generated during coreboot build and are located in the SPI ROM | ||
* Verstage - The code to verify the firmware contained in the | ||
writable section of the SPI ROM | ||
* APCB - AMD PSP Customization Block - A binary containing PSP and | ||
system configuration preferences (analogous to v5 BUILDOPT_ options), | ||
and generated by APCBTool to be added to coreboot/utils later | ||
* APOB - AGESA PSP Output Buffer - A buffer in main memory for | ||
storing AGESA BootLoader output. There are no plans for this to be | ||
parsed by coreboot | ||
|
||
## Problem Statements | ||
|
||
AMD has ported early AGESA features to the PSP, which now discovers, | ||
enables and trains DRAM. Unlike any other x86 device in coreboot, a | ||
Picasso system has DRAM online prior to the first instruction fetch. | ||
|
||
Cache-as-RAM (CAR) is no longer a supportable feature in AMD hardware. | ||
Early code expecting CAR behavior <span | ||
style="text-decoration:underline;">must</span> account for writes | ||
escaping the L2 cache and going to DRAM. | ||
|
||
Without any practical need for CAR, or DRAM initialization, coreboot | ||
should arguably skip bootblock and romstage, and possibly use ramstage | ||
as the BIOS image. This approach presents a number of challenges: | ||
|
||
* At the entry of ramstage, x86 processors are in flat protected | ||
mode. Picasso’s initial state is nearly identical to any other x86 | ||
at reset, except its CS shadow register’s base and limit put its | ||
execution within DRAM, not at 0xfffffff0. Picasso requires initial | ||
programming and entry into protected mode prior to ramstage. | ||
* coreboot expects cbmem initialization during romstage. | ||
|
||
AGESA supporting Picasso is now at v9. Unlike Arch2008, which defines | ||
granular entry points for easy inclusion to a legacy BIOS, v9 is | ||
rewritten for compilation into a UEFI. The source follows UEFI | ||
standards, i.e. assumes the presence of UEFI phases, implements | ||
dependency expressions, much functionality is rewritten as libraries, | ||
etc. It would, in no way, fit into the v5 model used in coreboot. | ||
|
||
* For the foreseeable future, AGESA source will distributed only | ||
under NDA. | ||
|
||
## Basic Pre-x86 Boot Flow | ||
|
||
The following steps occur prior to x86 processor operation. | ||
|
||
* System power on | ||
* PSP executes immutable on-chip boot ROM | ||
* PSP locates the Embedded Firmware Table and PSP Directory Table in | ||
the SPI ROM | ||
* PSP verifies and executes the PSP off-chip bootloader | ||
* ChromeOS systems: | ||
* Off-chip bootloader attempts to locate verstage via the RO BIOS | ||
Directory Table | ||
* If verstage is not found, booting continues with ABLs below | ||
* Verstage initializes, setting up GPIOs, UART if needed, | ||
communication path to the EC, and the SPI controller for direct access | ||
to the flash device. | ||
* Verstage verifies the RW sections (as is typically performed by | ||
the main processor) | ||
* Verstage locates the Embedded Firmware Directory within the | ||
verified FMAP section and passes a pointer to the PSP bootloader. If | ||
the verification fails, it passes a pointer to the RO header to the | ||
bootloader. | ||
* PSP parses the PSP Directory Table to find the ABLs and executes | ||
them | ||
* An ABL parses the APCB for system configuration preferences | ||
* An ABL initializes system main memory, locates the compressed BIOS | ||
image in the SPI ROM, and decompresses it into DRAM | ||
* An ABL writes the APOB to DRAM for consumption by the x86-based | ||
AGESA | ||
* PSP releases the x86 processor from reset. The x86 core fetches | ||
and executes instructions from the reset vector | ||
|
||
## Picasso Reset Vector and First Instructions | ||
|
||
As mentioned above, prior to releasing the x86 main core from reset, | ||
the PSP decompresses a BIOS image into DRAM. The PSP uses a specific | ||
BIOS Directory Table entry type to determine the source address (in | ||
flash), the destination address (in DRAM), and the destination size. | ||
The decompressed image is at the top of the destination region. The | ||
PSP then | ||
|
||
Calculates the x86 reset vector as | ||
|
||
reset_vector = dest_addr + dest_size - 0x10 | ||
|
||
Sets x86 CS descriptor shadow register to | ||
|
||
base = dest_addr + dest_size - 0x10000 | ||
limit = 0xffff | ||
|
||
Like all x86 devices, the main core is allowed to begin executing | ||
instructions with | ||
|
||
CS:IP = 0xf000:0xfff0 | ||
|
||
For example, assume the BIOS Directory Table indicates | ||
|
||
destination = 0x9b00000 | ||
size = 0x300000 | ||
|
||
… then the BIOS image is placed at the topmost position the region | ||
0x9b00000-0x9dfffff and | ||
|
||
reset_vector = 0x9dffff0 | ||
CS_shdw_base = 0x9df0000 | ||
CS:IP = 0xf000:0xfff0 | ||
|
||
Although the x86 behaves as though it began executing at 0xfffffff0 | ||
i.e. 0xf000:0xfff0, the initial GDT load must use the physical address | ||
of the table and not the typical CS-centric address. And, the first | ||
jump to protected mode must jump to the physical address in DRAM. Any | ||
code that is position-dependent must be linked to run at the final | ||
destination. | ||
|
||
## Initial coreboot Implementation | ||
|
||
Supporting Picasso doesn’t fit well with many of the coreboot | ||
assumptions. Initial porting shall attempt to fit within existing | ||
coreboot paradigms and make minimal changes to common code. | ||
|
||
### CAR and bootblock | ||
|
||
The coreboot bootblock contains features Picasso doesn’t require or | ||
can’t use, and is assumed to execute in an unusable location. | ||
Picasso’s requirement for bootblock in coreboot will be eliminated. | ||
|
||
### Hybrid romstage | ||
|
||
Picasso’s x86 reset state doesn’t meet the coreboot expectations | ||
for jumping directly to ramstage. The primary feature of romstage is | ||
also not needed, however there are other important features that are | ||
typically in romstage that Picasso does need. | ||
|
||
The romstage architecture is designed around the presence of CAR. | ||
Several features implement ROMSTAGE_CBMEM_INIT_HOOK, expecting to move | ||
data from CAR to cbmem. The hybrid romstage consumes DRAM for the | ||
purpose of implementing the expected CAR storage. This region as well | ||
as the DRAM where romstage is decompressed must be reserved and | ||
unavailable to the OS. | ||
|
||
The initial Picasso port implements a hybrid romstage that contains the | ||
first instruction fetched at the reset vector. It minimally configures | ||
flat protected mode, initializes cbmem, then loads the next stage. | ||
Future work will consider breaking the dependencies mentioned above | ||
and/or potentially loading ramstage directly from the PSP. | ||
|
||
## AGESA v9 on Picasso | ||
|
||
Due to the current inability to publish AGESA source, a pre-built | ||
binary solution remains a requirement. The rewrite from v5 to v9 for | ||
direct inclusion into UEFI source makes modifying it for conforming to | ||
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 | ||
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. | ||
|
||
## Footnotes | ||
|
||
1. “AMD Platform Security Processor BIOS Architecture Design Guide | ||
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) | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
# AMD SOC-specific documentation | ||
|
||
This section contains documentation about coreboot on specific AMD SOCs. | ||
|
||
## Technology | ||
|
||
- [Family 17h](family17h.md) | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters