From bff6dc7b8c1e18921c36b51eaad76d46d674f466 Mon Sep 17 00:00:00 2001 From: Patrick Rudolph Date: Fri, 29 Mar 2019 18:29:21 +0100 Subject: [PATCH] Documentation: Add coreboot architecture Describe the coreboot stages, given a short introduction what is done and add a chart for coreboot's vs EDK II bootflow as well as the source for the SVG. TODO: Describe stages in detail in a separate commit. Change-Id: I98cb61b1d0d29ac9d03f5ef3644d51a8e14bad74 Signed-off-by: Patrick Rudolph Reviewed-on: https://review.coreboot.org/c/coreboot/+/32123 Tested-by: build bot (Jenkins) Reviewed-by: Paul Menzel Reviewed-by: Werner Zeh --- Documentation/getting_started/architecture.md | 105 +++++++++++ .../comparision_coreboot_uefi.dia | Bin 0 -> 3405 bytes .../comparision_coreboot_uefi.svg | 176 ++++++++++++++++++ Documentation/getting_started/index.md | 1 + 4 files changed, 282 insertions(+) create mode 100644 Documentation/getting_started/architecture.md create mode 100644 Documentation/getting_started/comparision_coreboot_uefi.dia create mode 100644 Documentation/getting_started/comparision_coreboot_uefi.svg diff --git a/Documentation/getting_started/architecture.md b/Documentation/getting_started/architecture.md new file mode 100644 index 0000000000..6ef63594cf --- /dev/null +++ b/Documentation/getting_started/architecture.md @@ -0,0 +1,105 @@ +# coreboot architecture + +## Overwiew +![][architecture] + +[architecture]: comparision_coreboot_uefi.svg + +## Stages +coreboot consists of multiple stages that are compiled as separate binaries and +are inserted into the CBFS with custom compression. The bootblock usually doesn't +have compression while the ramstage and payload are compressed with LZMA. + +Each stage loads the next stage a given address (possibly decompressing it). + +Some stages are relocatable and can be placed anywhere in DRAM. Those stages are +usually cached in CBMEM for faster loading times on ACPI S3 resume. + +Supported stage compressions: +* none +* LZ4 +* LZMA + +## bootblock +The bootblock is the first stage executed after CPU reset. It is written in +assembly language and its main task is to set up everything for a C-environment: + +Common tasks: + +* Cache-As-RAM for heap and stack +* Set stack pointer +* Clear memory for BSS +* Decompress and load the next stage + +On x86 platforms that includes: + +* Microcode updates +* Timer init +* Switching from 16-bit real-mode to 32-bit protected mode + +The bootblock loads the romstage or the verstage if verified boot is enabled. + +### Cache-As-Ram +The *Cache-As-Ram*, also called Non-Eviction mode, or *CAR* allows to use the +CPU cache like regular SRAM. This is particullary usefull for high level +languages like `C`, which need RAM for heap and stack. + +The CAR needs to be activated using vendor specific CPU instructions. + +The following stages run when Cache-As-Ram is active: +* bootblock +* romstage +* verstage +* postcar + +## verstage +The verstage is where the root-of-trust starts. It's assumed that +it cannot be overwritten in-field (together with the public key) and +it starts at the very beginning of the boot process. +The verstage installs a hook to verify a file before it's loaded from +CBFS or a partition before it's accessed. + +The verified boot mechanism allows trusted in-field firmware updates +combined with a fail-safe recovery mode. + +## romstage +The romstage initializes the DRAM and prepares everything for device init. + +Common tasks: + +* Early device init +* DRAM init + +## postcar +To leave the CAR setup and run code from regular DRAM the postcar-stage tears +down CAR and loads the ramstage. Compared to other stages it's minimal in size. + +## ramstage + +The ramstage does the main device init: + +* PCI device init +* On-chip device init +* TPM init (if not done by verstage) +* Graphics init (optional) +* CPU init (like set up SMM) + +After initialization tables are written to inform the payload or operating system +about the current hardware existance and state. That includes: + +* ACPI tables (x86 specific) +* SMBIOS tables (x86 specific) +* coreboot tables +* devicetree updates (ARM specific) + +It also does hardware and firmware lockdown: +* Write-protection of boot media +* Lock security related registers +* Lock SMM mode (x86 specific) + +## payload +The payload is the software that is run after coreboot is done. It resides in +the CBFS and there's no possibility to choose it at runtime. + +For more details have a look at [payloads](../payloads.md). + diff --git a/Documentation/getting_started/comparision_coreboot_uefi.dia b/Documentation/getting_started/comparision_coreboot_uefi.dia new file mode 100644 index 0000000000000000000000000000000000000000..19c491fa7e662000703c07b116c307f3636de40e GIT binary patch literal 3405 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 + + + + + + + + + + + + + Platform Initialization Firmware Phases + + + EDK II - stages + + + time + + + coreboot - stages + + + + + + Security + (SEC) + + + + + + + Pre-EFI + Initialization Environment + (PEI) + + + + + + + Driver Execution + Environment + (DXE) + + + + + + + Boot Device Selection + (BDS) + + + + + + + bootblock + + + + + + + romstage + + + + + + + verstage + (optional) + + + + + + + postcar + (x86 only) + + + + + + + ramstage + + + + + + + SMM + (x86 only) + + + + + + + payload + + + + + + + Assembly + + + + + + + Cache-As-RAM + + + + + + + DRAM + + + + + + + + + + + C + + + + + + + ADA SPARK (x86 only) + + + + coreboot + source languages + + + code/heap + memory location + + + + + + + + BL31 + (ARM only) + + + + Power on + + + + + + + diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md index 8f2a58e1c5..52d873ece2 100644 --- a/Documentation/getting_started/index.md +++ b/Documentation/getting_started/index.md @@ -1,5 +1,6 @@ # Getting Started +* [coreboot architecture](architecture.md) * [Build System](build_system.md) * [Submodules](submodules.md) * [Kconfig](kconfig.md)