From 68bf986c37252eed2e8fa3db07de02bbd47ff97a Mon Sep 17 00:00:00 2001 From: Stewart Smith Date: Wed, 27 Jul 2016 17:43:03 +1000 Subject: rename overview.txt to overview.rst Signed-off-by: Stewart Smith --- doc/overview.rst | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 doc/overview.rst (limited to 'doc/overview.rst') diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 0000000..760f391 --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,116 @@ +skiboot overview +================ + +skiboot is firmware, loaded by the FSP. Along with loading the bootloader, +it provides some runtime services to the OS (typically Linux). + +Source layout +------------- +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() + +Binaries +-------- +The following binaries are built: + +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 + +Booting +------- + +On boot, every thread of execution jumps to a single entry point in skiboot +so we need to do some magic to ensure we init things properly and don't stomp +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 fatten 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). + +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. + +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. + +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. + +The OPAL interface is a generic message queue. The Linux side of things +can be found in linux/arch/powerpc/platform/powernv/opal-*.c + +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. + + +Memory +------ + +We initially occupy a chunk of memory, "heap". We pass to the OS (Linux) +a reservation of what we occupy (including stacks). + +In the source file include/config.h we include a memory map. This is +manually generated, not automatically generated. + +We use CCAN for a bunch of helper code, turning on things like DEBUG_LOCKS +and DEBUG_MALLOC as these are not a performance issue for us, and we like +to be careful. + +In include/config.h there are defines for turning on extra tracing. +OPAL is what we name the interface from skiboot to OS (Linux). + +Each CPU gets a 16k stack, which is probably more than enough. Stack +should be used sparingly though. + +Important memory locations: + +SKIBOOT_BASE - where we sit + +HEAP_BASE, +HEAP_SIZE - the location and size for heap. We reserve 4MB for + initial allocations. + +There is also SKIBOOT_SIZE (manually calculated) and DEVICE_TREE_MAX_SIZE, +which is largely historical. + +Skiboot log +----------- + +There is a circular log buffer that skiboot maintains. This can be +accessed either from the FSP or through /dev/mem or through a debugfs +patch that's currently floating around. -- cgit v1.1