Patrick Rudolph has uploaded this change for review.

View Change

Documentation: Explain SimpleELF

Explain coreboot's SELF format.

Change-Id: Ia217af7d39505393ed9324fbe53b4ca7f3069e2e
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
---
M Documentation/lib/payloads/index.md
A Documentation/lib/payloads/selfboot.md
M Documentation/payloads.md
3 files changed, 44 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/47/33447/1

diff --git a/Documentation/lib/payloads/index.md b/Documentation/lib/payloads/index.md
index 44daef1..b8eca8c 100644
--- a/Documentation/lib/payloads/index.md
+++ b/Documentation/lib/payloads/index.md
@@ -6,6 +6,10 @@
 coreboot supports multiple payloads, depending on the architecture of the
 selected mainboard.
 
+## SimpleELF
+
+- [SimpleELF format](selfboot.md)
+
 ## FIT
 
 - [uImage.FIT support](fit.md)
diff --git a/Documentation/lib/payloads/selfboot.md b/Documentation/lib/payloads/selfboot.md
new file mode 100644
index 0000000..62a4393
--- /dev/null
+++ b/Documentation/lib/payloads/selfboot.md
@@ -0,0 +1,28 @@
+# Simple ELF standard
+
+coreboot is able to use static linked ELF binaries as payload.
+To reduce complexity the ELF binaries are converted to coreboot's SimpleELF
+(SELF) format.
+The payload is therefore split into multiple sections by `cbfstool` at
+build time, each having a unique loading address and possible compression.
+
+## SELF loader
+The SELF loader implementation can be found in `src/lib/selfboot.c`.
+It decompresses the SELF sections and places them in memory.
+
+If the payload overlaps with the loading stage (*RAMSTAGE*) and
+`CONFIG_RELOCATABLE_RAMSTAGE` is selected, the loading stage is moved to another
+location in RAM.
+
+SELF payloads are **never** relocatable and will always be placed at the
+address they specify. If it's not possible to load the payload at the specified
+address, the system won't boot.
+
+### Calling conventions
+The SELF payload is called with a pointer to the coreboot tables as first
+argument.
+
+**Note:** The only exception is made on [RISC-V] which does use the *HARTID*
+and a pointer to the *FDT* as arguments.
+
+[RISC-V]: ../../arch/riscv/index.md
diff --git a/Documentation/payloads.md b/Documentation/payloads.md
index b1eae61..650818e 100644
--- a/Documentation/payloads.md
+++ b/Documentation/payloads.md
@@ -7,6 +7,12 @@
 There is various software in that space that is either explicitly written as
 payload or can be made to work as one.
 
+## ELF
+
+Executable and linking format (ELF) compatible static linked binaries can be
+loaded as payload.
+ELF binaries are loaded through the [SELF] boot mechanism.
+
 ## SeaBIOS
 
 [SeaBIOS](https://www.seabios.org) is an open source implementation of
@@ -14,6 +20,7 @@
 since. While originally written for emulators such as QEMU, it can be made
 to work as a coreboot payload and all the necessary code is in SeaBIOS'
 mainline code.
+SeaBIOS is loaded through the [SELF] boot mechanism.
 
 ## Tianocore
 
@@ -40,3 +47,8 @@
 firmware project drivers that often reinvent the wheel) and the ability to
 define boot policy with familiar tools, no matter if those are shell scripts
 or compiled userland programs written in C, Go or other programming languages.
+
+On x86 platforms Linux is loaded through the [SELF] boot mechanism, by adding a
+*tampoline code* at the start of the kernel.
+
+[SELF]: lib/payloads/selfboot.md

To view, visit change 33447. To unsubscribe, or for help writing mail filters, visit settings.