summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rwxr-xr-xDocumentation/soc/amd/family17h.md117
1 files changed, 71 insertions, 46 deletions
diff --git a/Documentation/soc/amd/family17h.md b/Documentation/soc/amd/family17h.md
index 9608b57325..b917c94526 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)