doc: update skiboot overview

Updates for P9, xz compressed and STB wrapped payloads amongst
a great many other things.

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

1 files changed, 90 insertions, 51 deletions

diff --git a/doc/overview.rst b/doc/overview.rst
index 003be021..2d09e058 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -7,37 +7,75 @@ it provides some runtime services to the OS (typically Linux).
 Source layout
 -------------
 
-========= ===================================
-Directory Content
-========= ===================================
-asm/	  small amount, mainly entry points
-ccan/	  bits from CCAN
-core/	  common code among machines.
-doc/	  not enough here
-external/ tools to run external of sapphire.
-hdata/	  all stuff going to/from FSP
-hw/ 	  drivers for things & fsp things.
-include/  headers!
-libc/ 	  tiny libc, from SLOF
-libfdt/   straight device tree lib
-libpore/  to manipulate PORE engine.
-========= ===================================
-
-We have a spinlock implementation in asm/lock.S
-Entry points are detailed in asm/head.S
-The main C entry point is in core/init.c: main_cpu_entry()
+========== ===================================================
+Directory  Content
+========== ===================================================
+asm/	   small amount, mainly entry points
+ccan/	   bits from CCAN_
+core/	   common code among machines.
+doc/	   not enough here
+external/  tools and userspace components
+hdata/	   Parses HDAT from Hostboot/FSP into Device Tree
+hw/ 	   drivers for things & fsp things.
+include/   headers!
+libc/ 	   tiny libc, originally from SLOF_
+libfdt/    Manipulate flattened device trees
+libflash/  Lib for talking to flash and parsing FFS structs
+libpore/   to manipulate PORE [#]_ engine.
+libstb/    See :ref:`stb-overview`
+libxz/     The xz_embedded_ library
+opal-ci/   Some scripts to help Continuous Integration testing
+platforms/ Platform (machine/BMC) specific code
+test/      Test scripts and binaries
+========== ===================================================
+
+.. _CCAN: https://ccodearchive.net/
+.. _SLOF: https://github.com/aik/SLOF/
+.. _xz_embedded: https://tukaani.org/xz/embedded.html
+
+.. [#] Power On Reset Engine. Used to bring cores out of deep sleep states.
+       For POWER9, this also includes the `p9_stop_api` which manipulates
+       the low level microcode to-reinit certain SPRs on transition out of
+       a state losing STOP state.
+
+We have a spinlock implementation in `asm/lock.S`__
+Entry points are detailed in `asm/head.S`__
+The main C entry point is in `core/init.c`__: `main_cpu_entry()`__
+
+.. _lock_S: https://github.com/open-power/skiboot/blob/v5.8/asm/lock.S
+.. _head_S: https://github.com/open-power/skiboot/blob/v5.8/asm/head.S
+.. _core_init_c: https://github.com/open-power/skiboot/blob/v5.8/core/init.c
+.. _main_cpu_entry: https://github.com/open-power/skiboot/blob/v5.8/core/init.c#L785
+
+__ lock_S_
+__ head_S_
+__ core_init_c_
+__ main_cpu_entry_
 
 Binaries
 --------
 The following binaries are built:
 
-=========== ============================================
-File        Purpose
-=========== ============================================
-skiboot.lid is the actual lid. objdump out
-skiboot.elf is the elf binary of it, lid comes from this
-skiboot.map plain map of symbols
-=========== ============================================
+==================== =================================================
+File                 Purpose
+==================== =================================================
+skiboot.lid          Binary for flashing onto systems [#]_
+skiboot.lid.stb      Secure and Trusted Boot container wrapped skiboot
+*skiboot.lid.xz*     XZ compressed binary [#]_
+*skiboot.lid.xz.stb* STB container wrapped XZ compressed skiboot [#]_
+skiboot.elf          is the elf binary of it, lid comes from this
+skiboot.map          plain map of symbols
+==================== =================================================
+
+.. [#] Practically speaking, this is just IBM FSP based systems now. Since
+       the `skiboot.lid` size is now greater than 1MB, which is the size of
+       the default `PAYLOAD` PNOR partition size on OpenPOWER systems, you
+       will want the `skiboot.lid.xz` or `skiboot.lid.xz.stb` instead.
+.. [#] On OpenPOWER systems, hostboot will read and decompress XZ
+       compressed payloads. This shortens boot time (less data to read),
+       adds a checksum over the `PAYLOAD` and saves valuable PNOR space.
+       If in doubt, use this payload.
+.. [#] If a secure boot system, use this payload.
 
 Booting
 -------
@@ -48,12 +86,22 @@ on each other. We choose a master thread, putting everybody else into a
 spinloop.
 
 Essentially, we do this by doing an atomic fetch and inc and whoever gets 0
-gets to be the master.
-
-When we enter skiboot we also get a memory location in a register which
-is the location of a device tree for the system. We flatten out the device
-tree, turning offsets into real pointers and manipulating it where needed.
-We re-flatten the device tree before booting the OS (Linux).
+gets to be the main thread. The main thread will then distribute tasks to
+secondary threads as needed. We do not (currently) do anything fancy like
+context switching or scheduling.
+
+When entering skiboot, we enter with one of two data structures describing
+the system as initialized by Hostboot. There may be a flattened device tree
+(see https://devicetree.org/ ), or a HDAT structure. While Device Tree
+is an industry standard, HDAT comes from IBM POWER. On POWER8, skiboot would
+get HDAT and a mini-devicetree from an FSP or purely a Device Tree on OpenPOWER
+systems. On POWER9, it's just HDAT everywhere (that isn't a simulator).
+The HDAT specification is currently not public. It is purely an interface
+between Hostboot and skiboot, and is only exposed anywhere else for debugging
+purposes.
+
+During boot, skiboot will add a lot to the device tree, manipulating what
+may already be there before exporting this new device tree out to the OS.
 
 The main entry point is main_cpu_entry() in core/init.c, this is a carefully
 ordered init of things. The sequence is relatively well documented there.
@@ -61,31 +109,22 @@ ordered init of things. The sequence is relatively well documented there.
 OS interface
 ------------
 
-Skiboot maintains its own stack for each CPU. We do not have an ABI like
-"may use X stack on OS stack", we entirely keep to our own stack space.
-The OS (Linux) calling skiboot will never use any OS stack space and the OS
-does not need to call skiboot with a valid stack.
-
-We define an array of stacks, one for each CPU. On entry to skiboot,
-we can find out stack by multiplying our CPU number by the stack size and
-adding that to the address of the stack area.
+OPAL (skiboot) is exclusively called through OPAL calls. The OS has complete
+controll of *when* OPAL code is executed. The design of all OPAL APIs is that
+we do not block in OPAL, so as not to introduce jitter.
 
-At the bottom of each stack area is a per CPU data structure, which we
-can get to by chopping off the LSBs of the stack pointer.
+Skiboot maintains its own stack for each CPU, the running OS does not need
+to donate or reserve any of its stack space.
 
-The OPAL interface is a generic message queue. The Linux side of things
-can be found in linux/arch/powerpc/platform/powernv/
+With the OPAL API calls and device tree bindings we have the OPAL ABI.
 
 Interrupts
 ----------
 
-We don't handle interrupts in skiboot.
-
-In the future we may have to change to process machine check interrupts
-during boot.
-
-We do not have timer interrupts.
-
+We don't directly handle interrupts in skiboot. The OS is in complete control,
+and any interrupts we need to process are first received by the OS. The
+:ref:`opal-handle-interrupt` call is made by the OS for OPAL to do what's
+needed.
 
 Memory
 ------