1# AMD Family 17h in coreboot 2 3## Abstract 4 5Beginning with Family 17h products (a.k.a. “Zen” cores), AMD 6changed their paradigm for initializing the system and this requires 7major modifications to the execution flow of coreboot. This file 8discusses the new boot flow, and challenges, and the tradeoffs of the 9initial port into coreboot. 10 11## Introduction 12 13Family 17h products are x86-based designs. This documentation assumes 14familiarity with x86, its reset state and its early initialization 15requirements. 16 17To the extent necessary, the role of the AMD Secure Processor (a.k.a. 18Platform Security Processor or PSP) in system initialization is addressed 19here. The PSP specification<sup>1</sup> is available only with an NDA. 20coreboot relies on util/amdfwtool to build the structures and add various 21other firmware to the final image<sup>2</sup>. The Family 17h PSP design 22guide adds a new BIOS Directory Table, similar to the PSP Directory Table. 23 24Support in coreboot for modern AMD products is based on AMD’s 25reference code: AMD Generic Encapsulated Software Architecture 26(AGESA<sup>TM</sup>). AGESA contains the technology for enabling DRAM, 27configuring proprietary core logic, assistance with generating ACPI 28tables, and other features. 29 30AGESA for products earlier than Family 17h is known as v5 or 31Arch2008<sup>3</sup>. Also note that coreboot currently contains both 32open source AGESA and closed source implementations (binaryPI) compiled 33from AGESA. 34 35The first AMD Family 17h device ported to coreboot is codenamed 36“Picasso”<sup>4</sup>, and will be added to soc/amd/picasso. 37 38## Additional Definitions 39 40* PSP, Platform Security Processor: Onboard ARM processor that runs 41alongside the main x86 processor; may be viewed as analogous to the 42Intel<sup>R</sup> Management Engine 43* FCH, Fusion Control Hub, the logical southbridge within the SOC 44* ABL - AGESA Bootloader - Processor initialization code that runs on 45the PSP 46* PSP Directory Table - A structured list of pointers to PSP firmware 47and other controller binaries 48* BIOS Directory Table - A structured list of pointers to BIOS 49related firmware images 50* Embedded Firmware Structure - Signature and pointers used by the 51PSP to locate the PSP Directory Table and BIOS Directory Table; these 52items are generated during coreboot build and are located in the SPI ROM 53* vboot - The generic technology name for verifying/choosing a RW A/B 54or fallback RO path. 55* verstage - The code (vboot) to verify the firmware contained in the 56writable section of the SPI ROM, traditionally run on the x86 processor, 57and in some cases a separate stage added to coreboot 58* vboot app - A portion of vboot technology designed and compiled 59to run on the PSP 60* APCB - AMD PSP Customization Block - A binary containing PSP and 61system configuration preferences (analogous to v5 BUILDOPT_ options), 62and generated by APCBTool to be added to coreboot/utils later 63* APOB - AGESA PSP Output Buffer - A buffer in main memory for 64storing AGESA BootLoader output. There are no plans for this to be 65parsed by coreboot 66 67## Problem Statements 68 69AMD has ported early AGESA features to the PSP, which now discovers, 70enables and trains DRAM. Unlike any other x86 device in coreboot, a 71Picasso system has DRAM online prior to the first instruction fetch. 72 73Cache-as-RAM (CAR) is no longer a supportable feature in AMD hardware. 74Early code expecting CAR behavior <span 75style="text-decoration:underline;">must</span> account for writes 76escaping the L2 cache and going to DRAM. 77 78Without any practical need for CAR, or DRAM initialization, coreboot 79should arguably skip bootblock and romstage, and possibly use ramstage 80as the BIOS image. This approach presents a number of challenges: 81 82* At the entry of ramstage, x86 processors are in flat protected 83mode. Picasso’s initial state is nearly identical to any other x86 84at reset, except its CS shadow register’s base and limit put its 85execution within DRAM, not at 0xfffffff0. Picasso requires initial 86programming and entry into protected mode prior to ramstage. 87* coreboot expects cbmem initialization during romstage. 88 89AGESA supporting Picasso is now at v9. Unlike Arch2008, which defines 90granular entry points for easy inclusion to a legacy BIOS, v9 is 91rewritten for compilation into a UEFI. The source follows UEFI 92standards, i.e. assumes the presence of UEFI phases, implements 93dependency expressions, much functionality is rewritten as libraries, 94etc. It would, in no way, fit into the v5 model used in coreboot. 95 96* For the foreseeable future, AGESA source will distributed only 97under NDA. Furthermore, because AGESA's integrated debug services divulge 98NDA information, no debug builds will be released to the general public. 99 100## Basic Pre-x86 Boot Flow 101 102The following steps occur prior to x86 processor operation. 103 104* System power on 105* PSP executes immutable on-chip boot ROM 106* PSP locates the Embedded Firmware Table and PSP Directory Table in 107the SPI ROM 108* PSP verifies and executes the PSP off-chip bootloader 109* ChromeOS systems: 110 * Off-chip bootloader attempts to locate vboot app via the RO BIOS 111Directory Table 112 * If vboot app is not found, booting continues with ABLs below 113 * vboot app initializes, setting up GPIOs, UART if needed, 114communication path to the EC, and the SPI controller for direct access 115to the flash device. 116 * vboot app verifies the RW sections (as is typically performed by 117the main processor) 118 * vboot app locates the Embedded Firmware Directory within the 119verified FMAP section and passes a pointer to the PSP bootloader. If 120the verification fails, it passes a pointer to the RO header to the 121bootloader. 122* PSP parses the PSP Directory Table to find the ABLs and executes 123them 124* An ABL parses the APCB for system configuration preferences 125* An ABL initializes system main memory, locates the compressed BIOS 126image in the SPI ROM, and decompresses it into DRAM 127* An ABL writes the APOB to DRAM for consumption by the x86-based 128AGESA 129* PSP releases the x86 processor from reset. The x86 core fetches 130and executes instructions from the reset vector 131 132## Picasso Reset Vector and First Instructions 133 134As mentioned above, prior to releasing the x86 main core from reset, 135the PSP decompresses a BIOS image into DRAM. The PSP uses a specific 136BIOS Directory Table entry type to determine the source address (in 137flash), the destination address (in DRAM), and the destination size. 138The decompressed image is at the top of the destination region. The 139PSP then 140 141Calculates the x86 reset vector as 142 143 reset_vector = dest_addr + dest_size - 0x10 144 145Sets x86 CS descriptor shadow register to 146 147 base = dest_addr + dest_size - 0x10000 148 limit = 0xffff 149 150Like all x86 devices, the main core is allowed to begin executing 151instructions with 152 153 CS:IP = 0xf000:0xfff0 154 155For example, assume the BIOS Directory Table indicates 156 157 destination = 0x9b00000 158 size = 0x300000 159 160… then the BIOS image is placed at the topmost position the region 1610x9b00000-0x9dfffff and 162 163 reset_vector = 0x9dffff0 164 CS_shdw_base = 0x9df0000 165 CS:IP = 0xf000:0xfff0 166 167Although the x86 behaves as though it began executing at 0xfffffff0 168i.e. 0xf000:0xfff0, the initial GDT load must use the physical address 169of the table and not the typical CS-centric address. And, the first 170jump to protected mode must jump to the physical address in DRAM. Any 171code that is position-dependent must be linked to run at the final 172destination. 173 174## Implementation for coreboot 175 176Supporting Picasso doesn’t fit perfectly with many of the coreboot 177assumptions about x86 processors. Changes are introduced primarily 178into arch/x86 to accommodate a processor starting in DRAM and at a 179nontraditional reset vector. 180 181### CAR and early stages 182 183The traditional coreboot bootblock and romstage rely on cache-as-RAM 184and a linker script that positions temporary storage accordingly. A 185substitute for the DCACHE variables, called EARLYRAM, is introduced. 186Like DCACHE, this allows for a consistent mapping of early regions 187required across multiple stages prior to cbmem coming online. 188Examples are the _preram_cbmem_console and _timestamp. 189 190Due to Picasso's unique nature of starting with DRAM already available, 191no early stages run as execute-in-place (XIP). All post-bootblock 192stages are copied from the BIOS flash into DRAM for faster 193performance, and these regions are marked reserved later in POST. 194 195Unlike CAR-based systems, and because Picasso does not run early 196stages as XIP, its early stages are not constrained in their use 197of .bss or .data sections. All stages' .bss is zeroed, and all 198.data sections are fully R/W at load time. 199 200### bootblock 201 202Picasso uses a bootblock that mirrors a traditional bootblock as much 203as possible. Because the image is loaded by the PSP, the bootblock is 204not restricted to the top of the BIOS flash device. The compressed 205image is added into the PSP's `amdfw.rom` build. 206 207### vboot app and verstage 208 209Development is currently underway for the vboot app, and potentially 210an x86-based verstage companion. This document shall be updated once 211the design is finalized and functioning. Support for the PSP honoring 212the presence of the vboot app is available only in certain SKUs. 213 214### romstage and postcar 215 216A traditional romstage is maintained for Picasso. The primary reason for 217this choice is to remain compatible with coreboot conventions and 218to support the FSP 2.0 driver. Picasso's romstage uses an 219fsp_memory_init() call to glean the memory map from AGESA. (See below.) 220fsp_memory_init() brings cbmem online before returning to the caller. 221 222No postcar stage is required or supported. 223 224## AGESA v9 on Picasso 225 226Due to the current restriction on publishing AGESA source, a pre-built 227binary solution remains a requirement. Modifying v9 to conform to the 228existing v5 binaryPI interface was considered impractical. 229 230Given the UEFI nature of modern AGESA, and the existing open source 231work from Intel, Picasso shall support AGESA via an FSP-like prebuilt 232image. The Intel Firmware Support Package<sup>5</sup> combines 233reference code with EDK II source to create a modular image with 234discoverable entry points. coreboot source already contains knowledge 235of FSP, how to parse it, integrate it, and how to communicate with it. 236Picasso's FSP is compatible with rev. 2.0 of the External Architecture 237Specification. Deviations, e.g., no FSP-T support, shall be published 238in an Integration Guide. 239 240## APCB setup 241 242APCBs are used to provide the PSP with SPD information and optionally a set of 243GPIOs to use for selecting which SPD to load. A list of APCB files should be 244specified in `APCB_SOURCES`. 245 246### Generating APCBs 247If you have a template APCB file, the `apcb_edit` tool can be used to inject the 248SPD and GPIOs used to select the correct slot. 249 250## Footnotes 251 2521. *AMD Platform Security Processor BIOS Architecture Design Guide 253for AMD Family 17h Processors* (PID #55758) and *AMD Platform 254Security Processor BIOS Architecture Design Guide* (PID #54267) for 255earlier products 2562. [PSP Integration](psp_integration.md) 2573. [https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf](https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf) 2584. [https://en.wikichip.org/wiki/amd/cores/picasso](https://en.wikichip.org/wiki/amd/cores/picasso) 2595. [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) 260