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