summaryrefslogtreecommitdiff
path: root/Documentation/soc/amd
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/soc/amd')
-rwxr-xr-xDocumentation/soc/amd/family17h.md224
-rw-r--r--Documentation/soc/amd/index.md8
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)
+