From patchwork Mon Sep 25 05:29:15 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stewart Smith X-Patchwork-Id: 818045 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [103.22.144.68]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3y0t1s08PPz9sMN for ; Mon, 25 Sep 2017 15:29:37 +1000 (AEST) Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 3y0t1r5QqmzDsNJ for ; Mon, 25 Sep 2017 15:29:36 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=linux.vnet.ibm.com (client-ip=148.163.156.1; helo=mx0a-001b2d01.pphosted.com; envelope-from=stewart@linux.vnet.ibm.com; receiver=) Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com [148.163.156.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 3y0t1g42JBzDr4N for ; Mon, 25 Sep 2017 15:29:26 +1000 (AEST) Received: from pps.filterd (m0098409.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.21/8.16.0.21) with SMTP id v8P5TCvL137769 for ; Mon, 25 Sep 2017 01:29:24 -0400 Received: from e36.co.us.ibm.com (e36.co.us.ibm.com [32.97.110.154]) by mx0a-001b2d01.pphosted.com with ESMTP id 2d6e5ebc0x-1 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT) for ; Mon, 25 Sep 2017 01:29:23 -0400 Received: from localhost by e36.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Sun, 24 Sep 2017 23:29:23 -0600 Received: from b03cxnp08025.gho.boulder.ibm.com (9.17.130.17) by e36.co.us.ibm.com (192.168.1.136) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Sun, 24 Sep 2017 23:29:20 -0600 Received: from b03ledav005.gho.boulder.ibm.com (b03ledav005.gho.boulder.ibm.com [9.17.130.236]) by b03cxnp08025.gho.boulder.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id v8P5TKLF1049028; Sun, 24 Sep 2017 22:29:20 -0700 Received: from b03ledav005.gho.boulder.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 14FF6BE038; Sun, 24 Sep 2017 23:29:20 -0600 (MDT) Received: from birb.localdomain (unknown [9.185.16.92]) by b03ledav005.gho.boulder.ibm.com (Postfix) with ESMTP id 93DF6BE03A; Sun, 24 Sep 2017 23:29:19 -0600 (MDT) Received: by birb.localdomain (Postfix, from userid 1000) id 1E3FD4F0CAC; Mon, 25 Sep 2017 15:29:16 +1000 (AEST) From: Stewart Smith To: skiboot@lists.ozlabs.org Date: Mon, 25 Sep 2017 15:29:15 +1000 X-Mailer: git-send-email 2.13.5 X-TM-AS-GCONF: 00 x-cbid: 17092505-0020-0000-0000-00000CC1BCAE X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00007788; HX=3.00000241; KW=3.00000007; PH=3.00000004; SC=3.00000231; SDB=6.00921996; UDB=6.00463372; IPR=6.00702138; BA=6.00005602; NDR=6.00000001; ZLA=6.00000005; ZF=6.00000009; ZB=6.00000000; ZP=6.00000000; ZH=6.00000000; ZU=6.00000002; MB=3.00017261; XFM=3.00000015; UTC=2017-09-25 05:29:21 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 17092505-0021-0000-0000-00005E4354D0 Message-Id: <20170925052915.5779-1-stewart@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2017-09-24_07:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 spamscore=0 suspectscore=12 malwarescore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1707230000 definitions=main-1709250088 Subject: [Skiboot] [PATCH] doc: update skiboot overview X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.24 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Updates for P9, xz compressed and STB wrapped payloads amongst a great many other things. Signed-off-by: Stewart Smith --- doc/opal-api/index.rst | 2 + doc/opal-api/opal-handle-interrupt.rst | 2 + doc/overview.rst | 141 +++++++++++++++++++++------------ 3 files changed, 94 insertions(+), 51 deletions(-) diff --git a/doc/opal-api/index.rst b/doc/opal-api/index.rst index f73be2d7ad0a..52106f499a2f 100644 --- a/doc/opal-api/index.rst +++ b/doc/opal-api/index.rst @@ -1,3 +1,5 @@ +.. _opal-api: + ====================== OPAL API Documentation ====================== diff --git a/doc/opal-api/opal-handle-interrupt.rst b/doc/opal-api/opal-handle-interrupt.rst index 36f5d3ade839..73be0e34cfeb 100644 --- a/doc/opal-api/opal-handle-interrupt.rst +++ b/doc/opal-api/opal-handle-interrupt.rst @@ -1,3 +1,5 @@ +.. _opal-handle-interrupt: + OPAL_HANDLE_INTERRUPT ===================== diff --git a/doc/overview.rst b/doc/overview.rst index 003be0219945..2d09e05801de 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 ------