Documentation/soc/amd/family17: Update to match current design

The Picasso no longer intends to implement a hybrid romstage,
opting instead for a more traditional bootblock/romstage/ramstage.
Update the documentation to reflect this.  Clarify additional
details that have come to light since the last revision.

Signed-off-by: Marshall Dawson <marshalldawson3rd@gmail.com>
Change-Id: I6c98c007ddb8a4a05810f19e4215bde719de7bb8
Reviewed-on: https://review.coreboot.org/c/coreboot/+/38713
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Held <felix-coreboot@felixheld.de>

1 files changed, 71 insertions, 46 deletions

diff --git a/Documentation/soc/amd/family17h.md b/Documentation/soc/amd/family17h.md
index 9608b5732544..b917c94526c7 100755
--- a/Documentation/soc/amd/family17h.md
+++ b/Documentation/soc/amd/family17h.md
@@ -14,13 +14,12 @@ 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<sup>2</sup>.
-The Family 17h PSP design guide adds a new BIOS Directory Table, similar to
-the PSP Directory Table.
+To the extent necessary, the role of the AMD Secure Processor (a.k.a.
+Platform Security Processor or PSP) in system initialization is addressed
+here.  The PSP specification<sup>1</sup> is available only with an NDA.
+coreboot relies on util/amdfwtool to build the structures and add various
+other firmware to the final image<sup>2</sup>.  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
@@ -51,8 +50,13 @@ 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
+*   vboot - The generic technology name for verifying/choosing a RW A/B
+or fallback RO path.
+*   verstage - The code (vboot) to verify the firmware contained in the
+writable section of the SPI ROM, traditionally run on the x86 processor,
+and in some cases a separate stage added to coreboot
+*   vboot app - A portion of vboot technology designed and compiled
+to run on the PSP
 *   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
@@ -90,7 +94,8 @@ 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.
+under NDA.  Furthermore, because AGESA's integrated debug services divulge
+NDA information, no debug builds will be released to the general public.
 
 ## Basic Pre-x86 Boot Flow
 
@@ -102,15 +107,15 @@ The following steps occur prior to x86 processor operation.
 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
+    *   Off-chip bootloader attempts to locate vboot app via the RO BIOS
 Directory Table
-    *   If verstage is not found, booting continues with ABLs below
-    *   Verstage initializes, setting up GPIOs, UART if needed,
+    *   If vboot app is not found, booting continues with ABLs below
+    *   vboot app 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
+    *   vboot app verifies the RW sections (as is typically performed by
 the main processor)
-    *   Verstage locates the Embedded Firmware Directory within the
+    *   vboot app 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.
@@ -166,44 +171,61 @@ 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
+## Implementation for coreboot
 
-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.
+Supporting Picasso doesn’t fit perfectly with many of the coreboot
+assumptions about x86 processors.  Changes are introduced primarily
+into arch/x86 to accommodate a processor starting in DRAM and at a
+nontraditional reset vector.
 
-### CAR and bootblock
+### CAR and early stages
 
-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.
+The traditional coreboot bootblock and romstage rely on cache-as-RAM
+and a linker script that positions temporary storage accordingly.  A
+substitute for the DCACHE variables, called EARLYRAM, is introduced.
+Like DCACHE, this allows for a consistent mapping of early regions
+required across multiple stages prior to cbmem coming online.
+Examples are the _preram_cbmem_console and _timestamp.
 
-### Hybrid romstage
+Due to Picasso's unique nature of starting with DRAM already available,
+no early stages run as execute-in-place (XIP).  All post-bootblock
+stages are copied from the BIOS flash into DRAM for faster
+performance, and these regions are marked reserved later in POST.
 
-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.
+Unlike CAR-based systems, and because Picasso does not run early
+stages as XIP, its early stages are not constrained in their use
+of .bss or .data sections.  All stages' .bss is zeroed, and all
+.data sections are fully R/W at load time.
 
-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.
+### bootblock
 
-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.
+Picasso uses a bootblock that mirrors a traditional bootblock as much
+as possible.  Because the image is loaded by the PSP, the bootblock is
+not restricted to the top of the BIOS flash device.  The compressed
+image is added into the PSP's `amdfw.rom` build.
+
+### vboot app and verstage
+
+Development is currently underway for the vboot app, and potentially
+an x86-based verstage companion.  This document shall be updated once
+the design is finalized and functioning.  Support for the PSP honoring
+the presence of the vboot app is available only in certain SKUs.
+
+### romstage and postcar
+
+A traditional romstage is maintained for Picasso.  The primary reason for
+this choice is to remain compatible with coreboot conventions and
+to support the FSP 2.0 driver.  Picasso's romstage uses an
+fsp_memory_init() call to glean the memory map from AGESA.  (See below.)
+fsp_memory_init() brings cbmem online before returning to the caller.
+
+No postcar stage is required or supported.
 
 ## 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.
+Due to the current restriction on publishing AGESA source, a pre-built
+binary solution remains a requirement.  Modifying v9 to conform to the
+existing v5 binaryPI interface was considered 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
@@ -211,12 +233,15 @@ image.  The Intel Firmware Support Package<sup>5</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.
+Picasso's FSP is compatible with rev. 2.0 of the External Architecture
+Specification.  Deviations, e.g., no FSP-T support, shall be published
+in an Integration Guide.
 
 ## 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
+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. [PSP Integration](psp_integration.md)
 3. [https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf](https://www.amd.com/system/files/TechDocs/44065_Arch2008.pdf)