Change in ...coreboot[master]: Documentation: Add coreboot architecture

[Patrick Rudolph (Code Review)]

Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/32123

Change subject: Documentation: Add coreboot architecture
......................................................................

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.

TODO: Describe stages and payloads in detail

Change-Id: I98cb61b1d0d29ac9d03f5ef3644d51a8e14bad74
Signed-off-by: Patrick Rudolph 
---
A Documentation/getting_started/architecture.md
A Documentation/getting_started/comparision_coreboot_uefi.svg
M Documentation/getting_started/index.md
3 files changed, 287 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/23/32123/1

diff --git a/Documentation/getting_started/architecture.md b/Documentation/getting_started/architecture.md
new file mode 100644
index 0000000..f8f8b3d
--- /dev/null
+++ b/Documentation/getting_started/architecture.md
@@ -0,0 +1,110 @@
+# coreboot architecture
+
+## Overwiew
+![][architecture]
+
+[architecture]: comparision_coreboot_uefi.svg
+
+## Stages
+The stages are compiled as seperate 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 at 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.
+
+## bootblock
+The bootblock is the first stage executed after CPU reset. It is written in
+assembly language and its main task is to setup 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 actived 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
+that 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 initialized the DRAM and prepares everything for device init.
+
+Common tasks:
+
+* DRAM init
+* Early device 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
+* Graphics init (optional)
+* CPU init (like set up SMM)
+
+After initialization tables are written to inform the payload 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.
+Some payloads, like *SeaBios*, offer to load `secondary payloads` at runtime.
+
+Supported payloads are:
+
+* [SeaBIOS](https://www.seabios.org/SeaBIOS)
+* [Tianocore](https://www.tianocore.org/)
+* [GRUB](https://www.gnu.org/software/grub/)
+* [Depthcharge](https://chromium.googlesource.com/chromiumos/platform/depthcharge/)
+* ELF binaries
+* [UBoot](https://www.denx.de/wiki/U-Boot)
+* [Linux kernel](https://www.kernel.org/)
+* [LinuxBoot](https://www.linuxboot.org/)
+
diff --git a/Documentation/getting_started/comparision_coreboot_uefi.svg b/Documentation/getting_started/comparision_coreboot_uefi.svg
new file mode 100644
index 0000000..3ea2fa6
--- /dev/null
+++ b/Documentation/getting_started/comparision_coreboot_uefi.svg
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="55cm" height="28cm" viewBox="62 37 1088 559" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <g>
+    <rect style="fill: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="242.613" y1="107.463" x2="242.698" y2="492.591"/>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="234.964" y1="477.053" x2="1135.15" y2="478.109"/>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" points="1124.61,485.597 1139.62,478.114 1124.63,470.597 "/>
+  </g>
+  <text font-size="22.5778" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="482.342" y="58.1574">
+    <tspan x="482.342" y="58.1574">Platform Initialization Firmware Phases</tspan>
+  </text>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="98.4514" y="435.714">
+    <tspan x="98.4514" y="435.714">EDK II - stages</tspan>
+  </text>
+  <text font-size="12.8" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="1073.49" y="499.998">
+    <tspan x="1073.49" y="499.998">time</tspan>
+  </text>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="82.8266" y="330.476">
+    <tspan x="82.8266" y="330.476">coreboot - stages</tspan>
+  </text>
+  <g>
+    <rect style="fill: #faff94" x="250.501" y="404.247" width="130.432" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="250.501" y="404.247" width="130.432" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="315.718" y="434.72">
+      <tspan x="315.718" y="434.72">Security</tspan>
+      <tspan x="315.718" y="450.72">(SEC)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #faff94" x="383.033" y="404.781" width="282.702" height="69"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="383.033" y="404.781" width="282.702" height="69"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="524.384" y="427.181">
+      <tspan x="524.384" y="427.181">Pre-EFI</tspan>
+      <tspan x="524.384" y="443.181">Initialization Environment</tspan>
+      <tspan x="524.384" y="459.181">(PEI)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #faff94" x="668.027" y="405.317" width="269.244" height="69"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="668.027" y="405.317" width="269.244" height="69"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="802.649" y="427.717">
+      <tspan x="802.649" y="427.717">Driver Execution</tspan>
+      <tspan x="802.649" y="443.717">Environment</tspan>
+      <tspan x="802.649" y="459.717">(DXE)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #faff94" x="939.541" y="405.727" width="178.75" height="69"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="939.541" y="405.727" width="178.75" height="69"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1028.92" y="436.127">
+      <tspan x="1028.92" y="436.127">Boot Device Selection</tspan>
+      <tspan x="1028.92" y="452.127">(BDS)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="254.747" y="291.309" width="125.314" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="254.747" y="291.309" width="125.314" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="317.404" y="329.782">
+      <tspan x="317.404" y="329.782">bootblock</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="476.354" y="290.735" width="89.65" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="476.354" y="290.735" width="89.65" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="521.179" y="329.209">
+      <tspan x="521.179" y="329.209">romstage</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="382.317" y="291.011" width="92.1" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="382.317" y="291.011" width="92.1" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="428.367" y="321.485">
+      <tspan x="428.367" y="321.485">verstage</tspan>
+      <tspan x="428.367" y="337.485">(optional)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="617.11" y="321.464">
+      <tspan x="617.11" y="321.464">postcar</tspan>
+      <tspan x="617.11" y="337.464">(x86 only)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="667.529" y="281.527" width="168.747" height="37"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.529" y="281.527" width="168.747" height="37"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.903" y="303.927">
+      <tspan x="751.903" y="303.927">ramstage</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="667.84" y="321.487" width="167.519" height="53"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.84" y="321.487" width="167.519" height="53"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.6" y="343.887">
+      <tspan x="751.6" y="343.887">SMM</tspan>
+      <tspan x="751.6" y="359.887">(x86 only)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="941.841" y="283.151" width="171.98" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="941.841" y="283.151" width="171.98" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1027.83" y="321.624">
+      <tspan x="1027.83" y="321.624">payload</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #d8e5e5" x="253.112" y="209.178" width="82.7" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="253.112" y="209.178" width="82.7" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="294.462" y="226.578">
+      <tspan x="294.462" y="226.578">Assembly</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #00c800" x="318.155" y="129.267" width="283.43" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="318.155" y="129.267" width="283.43" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="459.87" y="146.667">
+      <tspan x="459.87" y="146.667">Cache-As-RAM</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #ff8484" x="506.676" y="159.67" width="599.421" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="506.676" y="159.67" width="599.421" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="806.387" y="177.07">
+      <tspan x="806.387" y="177.07">DRAM</tspan>
+    </text>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.046" y1="392.926" x2="1113.82" y2="391.893"/>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="387.045" y="241.637">
+    <tspan x="387.045" y="241.637"></tspan>
+  </text>
+  <g>
+    <rect style="fill: #ffffff" x="337.438" y="209.383" width="618.831" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="337.438" y="209.383" width="618.831" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="646.853" y="226.783">
+      <tspan x="646.853" y="226.783">C</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #f6c7c7" x="667.35" y="238.912" width="170.3" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.35" y="238.912" width="170.3" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="752.5" y="256.312">
+      <tspan x="752.5" y="256.312">ADA SPARK (x86 only)</tspan>
+    </text>
+  </g>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="84.2481" y="233.28">
+    <tspan x="84.2481" y="233.28">coreboot</tspan>
+    <tspan x="84.2481" y="254.446">source languages</tspan>
+  </text>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="86.5008" y="153.786">
+    <tspan x="86.5008" y="153.786">code/heap</tspan>
+    <tspan x="86.5008" y="174.953">memory location </tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.483" y1="273.35" x2="1109.07" y2="273.582"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="176.24" y1="192.463" x2="1109.66" y2="192.132"/>
+  <g>
+    <rect style="fill: #90c9ff" x="838.583" y="281.963" width="100.3" height="53"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="838.583" y="281.963" width="100.3" height="53"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="888.733" y="304.363">
+      <tspan x="888.733" y="304.363">BL31</tspan>
+      <tspan x="888.733" y="320.363">(ARM only)</tspan>
+    </text>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="209.772" y="508.772">
+    <tspan x="209.772" y="508.772">Power on</tspan>
+  </text>
+  <g>
+    <rect style="fill: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
+  </g>
+  <path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" d="M 955.029 209.941 C 967.678,210.1 946.349,230.772 955.598,237.021"/>
+</svg>
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
index 8f2a58e..52d873e 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)

[HAOUAS Elyes (Code Review)]

HAOUAS Elyes has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 1: Code-Review+1

[Patrick Rudolph (Code Review)]

Hello HAOUAS Elyes, Paul Menzel, build bot (Jenkins), Patrick Georgi, Martin Roth,

I'd like you to reexamine a change. Please visit

https://review.coreboot.org/c/coreboot/+/32123

to look at the new patch set (#2).

Change subject: Documentation: Add coreboot architecture
......................................................................

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.

TODO: Describe stages in detail

Change-Id: I98cb61b1d0d29ac9d03f5ef3644d51a8e14bad74
Signed-off-by: Patrick Rudolph 
---
A Documentation/getting_started/architecture.md
A Documentation/getting_started/comparision_coreboot_uefi.svg
M Documentation/getting_started/index.md
3 files changed, 282 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/23/32123/2

[Werner Zeh (Code Review)]

Werner Zeh has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 2:

(10 comments)

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
File Documentation/getting_started/architecture.md:

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 9: ,
no comma needed here

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 9: seperate
separate

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 11: ,
I guess no comma needed here?

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 13: given
a given

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 25: setup
set up

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 47: actived
activated

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 50: * bootblock
            : * romstage
            : * verstage
            : * postcar
Wouldn't it be better to mention the stages here in the order they will be executed?

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 58: starts
it starts

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 66: initialized
initializes

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 83: TPM init
It depends on the bootflow. TPM can be initialized in verstage already.

[Patrick Rudolph (Code Review)]

Hello Werner Zeh, HAOUAS Elyes, Arthur Heymans, Paul Menzel, Philipp Deppenwiese, build bot (Jenkins), Patrick Georgi, Martin Roth,

I'd like you to reexamine a change. Please visit

https://review.coreboot.org/c/coreboot/+/32123

to look at the new patch set (#3).

Change subject: Documentation: Add coreboot architecture
......................................................................

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.

TODO: Describe stages in detail in a separate commit.

Change-Id: I98cb61b1d0d29ac9d03f5ef3644d51a8e14bad74
Signed-off-by: Patrick Rudolph 
---
A Documentation/getting_started/architecture.md
A Documentation/getting_started/comparision_coreboot_uefi.svg
M Documentation/getting_started/index.md
3 files changed, 282 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/23/32123/3

[Patrick Rudolph (Code Review)]

Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 3:

(10 comments)

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
File Documentation/getting_started/architecture.md:

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 9: ,
> no comma needed here

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 9: seperate
> separate

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 11: ,
> I guess no comma needed here?

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 13: given
> a given

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 25: setup
> set up

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 47: actived
> activated

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 50: * bootblock
            : * romstage
            : * verstage
            : * postcar
> Wouldn't it be better to mention the stages here in the order they will be executed?

No, as verstage is optional and might run at end of romstage, at end of bootblock or between bootblock and romstage, depending on the platform.

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 58: starts
> it starts

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 66: initialized
> initializes

Done

https://review.coreboot.org/#/c/32123/2/Documentation/getting_started/archit... 
PS2, Line 83: TPM init
> It depends on the bootflow. TPM can be initialized in verstage already.

Done

[Paul Menzel (Code Review)]

Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 3: Code-Review+1

[Paul Menzel (Code Review)]

Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 3: Code-Review+2

How did you create the SVG?

[Patrick Rudolph (Code Review)]

Hello Werner Zeh, HAOUAS Elyes, Arthur Heymans, Paul Menzel, Philipp Deppenwiese, build bot (Jenkins), Patrick Georgi, Martin Roth,

I'd like you to reexamine a change. Please visit

https://review.coreboot.org/c/coreboot/+/32123

to look at the new patch set (#4).

Change subject: Documentation: Add coreboot architecture
......................................................................

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 
---
A Documentation/getting_started/architecture.md
A Documentation/getting_started/comparision_coreboot_uefi.dia
A Documentation/getting_started/comparision_coreboot_uefi.svg
M Documentation/getting_started/index.md
4 files changed, 282 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/23/32123/4

[Paul Menzel (Code Review)]

Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 4: Code-Review+2

[Patrick Rudolph (Code Review)]

Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 4:
> Patch Set 3: Code-Review+2
>
> How did you create the SVG?

Using dia.

[Werner Zeh (Code Review)]

Werner Zeh has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

Patch Set 4: Code-Review+2

[Patrick Georgi (Code Review)]

Patrick Georgi has submitted this change and it was merged. ( https://review.coreboot.org/c/coreboot/+/32123 )

Change subject: Documentation: Add coreboot architecture
......................................................................

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 
---
A Documentation/getting_started/architecture.md
A Documentation/getting_started/comparision_coreboot_uefi.dia
A Documentation/getting_started/comparision_coreboot_uefi.svg
M Documentation/getting_started/index.md
4 files changed, 282 insertions(+), 0 deletions(-)

Approvals:
  build bot (Jenkins): Verified
  Paul Menzel: Looks good to me, approved
  Werner Zeh: Looks good to me, approved

diff --git a/Documentation/getting_started/architecture.md b/Documentation/getting_started/architecture.md
new file mode 100644
index 0000000..6ef6359
--- /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 0000000..19c491f
--- /dev/null
+++ b/Documentation/getting_started/comparision_coreboot_uefi.dia
Binary files differ
diff --git a/Documentation/getting_started/comparision_coreboot_uefi.svg b/Documentation/getting_started/comparision_coreboot_uefi.svg
new file mode 100644
index 0000000..3ea2fa6
--- /dev/null
+++ b/Documentation/getting_started/comparision_coreboot_uefi.svg
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="55cm" height="28cm" viewBox="62 37 1088 559" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <g>
+    <rect style="fill: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="242.613" y1="107.463" x2="242.698" y2="492.591"/>
+  <g>
+    <line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="234.964" y1="477.053" x2="1135.15" y2="478.109"/>
+    <polyline style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" points="1124.61,485.597 1139.62,478.114 1124.63,470.597 "/>
+  </g>
+  <text font-size="22.5778" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="482.342" y="58.1574">
+    <tspan x="482.342" y="58.1574">Platform Initialization Firmware Phases</tspan>
+  </text>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="98.4514" y="435.714">
+    <tspan x="98.4514" y="435.714">EDK II - stages</tspan>
+  </text>
+  <text font-size="12.8" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="1073.49" y="499.998">
+    <tspan x="1073.49" y="499.998">time</tspan>
+  </text>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="82.8266" y="330.476">
+    <tspan x="82.8266" y="330.476">coreboot - stages</tspan>
+  </text>
+  <g>
+    <rect style="fill: #faff94" x="250.501" y="404.247" width="130.432" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="250.501" y="404.247" width="130.432" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="315.718" y="434.72">
+      <tspan x="315.718" y="434.72">Security</tspan>
+      <tspan x="315.718" y="450.72">(SEC)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #faff94" x="383.033" y="404.781" width="282.702" height="69"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="383.033" y="404.781" width="282.702" height="69"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="524.384" y="427.181">
+      <tspan x="524.384" y="427.181">Pre-EFI</tspan>
+      <tspan x="524.384" y="443.181">Initialization Environment</tspan>
+      <tspan x="524.384" y="459.181">(PEI)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #faff94" x="668.027" y="405.317" width="269.244" height="69"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="668.027" y="405.317" width="269.244" height="69"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="802.649" y="427.717">
+      <tspan x="802.649" y="427.717">Driver Execution</tspan>
+      <tspan x="802.649" y="443.717">Environment</tspan>
+      <tspan x="802.649" y="459.717">(DXE)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #faff94" x="939.541" y="405.727" width="178.75" height="69"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="939.541" y="405.727" width="178.75" height="69"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1028.92" y="436.127">
+      <tspan x="1028.92" y="436.127">Boot Device Selection</tspan>
+      <tspan x="1028.92" y="452.127">(BDS)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="254.747" y="291.309" width="125.314" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="254.747" y="291.309" width="125.314" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="317.404" y="329.782">
+      <tspan x="317.404" y="329.782">bootblock</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="476.354" y="290.735" width="89.65" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="476.354" y="290.735" width="89.65" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="521.179" y="329.209">
+      <tspan x="521.179" y="329.209">romstage</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="382.317" y="291.011" width="92.1" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="382.317" y="291.011" width="92.1" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="428.367" y="321.485">
+      <tspan x="428.367" y="321.485">verstage</tspan>
+      <tspan x="428.367" y="337.485">(optional)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="617.11" y="321.464">
+      <tspan x="617.11" y="321.464">postcar</tspan>
+      <tspan x="617.11" y="337.464">(x86 only)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="667.529" y="281.527" width="168.747" height="37"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.529" y="281.527" width="168.747" height="37"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.903" y="303.927">
+      <tspan x="751.903" y="303.927">ramstage</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="667.84" y="321.487" width="167.519" height="53"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.84" y="321.487" width="167.519" height="53"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.6" y="343.887">
+      <tspan x="751.6" y="343.887">SMM</tspan>
+      <tspan x="751.6" y="359.887">(x86 only)</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #90c9ff" x="941.841" y="283.151" width="171.98" height="69.1471"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="941.841" y="283.151" width="171.98" height="69.1471"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1027.83" y="321.624">
+      <tspan x="1027.83" y="321.624">payload</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #d8e5e5" x="253.112" y="209.178" width="82.7" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="253.112" y="209.178" width="82.7" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="294.462" y="226.578">
+      <tspan x="294.462" y="226.578">Assembly</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #00c800" x="318.155" y="129.267" width="283.43" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="318.155" y="129.267" width="283.43" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="459.87" y="146.667">
+      <tspan x="459.87" y="146.667">Cache-As-RAM</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #ff8484" x="506.676" y="159.67" width="599.421" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="506.676" y="159.67" width="599.421" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="806.387" y="177.07">
+      <tspan x="806.387" y="177.07">DRAM</tspan>
+    </text>
+  </g>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.046" y1="392.926" x2="1113.82" y2="391.893"/>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="387.045" y="241.637">
+    <tspan x="387.045" y="241.637"></tspan>
+  </text>
+  <g>
+    <rect style="fill: #ffffff" x="337.438" y="209.383" width="618.831" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="337.438" y="209.383" width="618.831" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="646.853" y="226.783">
+      <tspan x="646.853" y="226.783">C</tspan>
+    </text>
+  </g>
+  <g>
+    <rect style="fill: #f6c7c7" x="667.35" y="238.912" width="170.3" height="27"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.35" y="238.912" width="170.3" height="27"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="752.5" y="256.312">
+      <tspan x="752.5" y="256.312">ADA SPARK (x86 only)</tspan>
+    </text>
+  </g>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="84.2481" y="233.28">
+    <tspan x="84.2481" y="233.28">coreboot</tspan>
+    <tspan x="84.2481" y="254.446">source languages</tspan>
+  </text>
+  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="86.5008" y="153.786">
+    <tspan x="86.5008" y="153.786">code/heap</tspan>
+    <tspan x="86.5008" y="174.953">memory location </tspan>
+  </text>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.483" y1="273.35" x2="1109.07" y2="273.582"/>
+  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="176.24" y1="192.463" x2="1109.66" y2="192.132"/>
+  <g>
+    <rect style="fill: #90c9ff" x="838.583" y="281.963" width="100.3" height="53"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="838.583" y="281.963" width="100.3" height="53"/>
+    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="888.733" y="304.363">
+      <tspan x="888.733" y="304.363">BL31</tspan>
+      <tspan x="888.733" y="320.363">(ARM only)</tspan>
+    </text>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="209.772" y="508.772">
+    <tspan x="209.772" y="508.772">Power on</tspan>
+  </text>
+  <g>
+    <rect style="fill: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
+  </g>
+  <path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" d="M 955.029 209.941 C 967.678,210.1 946.349,230.772 955.598,237.021"/>
+</svg>
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
index 8f2a58e..52d873e 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)