diff options
Diffstat (limited to 'Documentation/soc/amd')
| -rwxr-xr-x | Documentation/soc/amd/family17h.md | 224 | ||||
| -rw-r--r-- | Documentation/soc/amd/index.md | 8 |
2 files changed, 232 insertions, 0 deletions
diff --git a/Documentation/soc/amd/family17h.md b/Documentation/soc/amd/family17h.md new file mode 100755 index 0000000000..dc3de13ffe --- /dev/null +++ b/Documentation/soc/amd/family17h.md @@ -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) + diff --git a/Documentation/soc/amd/index.md b/Documentation/soc/amd/index.md new file mode 100644 index 0000000000..7945b488f5 --- /dev/null +++ b/Documentation/soc/amd/index.md @@ -0,0 +1,8 @@ +# AMD SOC-specific documentation + +This section contains documentation about coreboot on specific AMD SOCs. + +## Technology + +- [Family 17h](family17h.md) + |