| <!DOCTYPE html> |
| |
| <html lang="en" data-content_root="./"> |
| <head> |
| <meta charset="utf-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> |
| |
| <title>Skiboot overview — skiboot d365a01 |
| documentation</title> |
| <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" /> |
| <link rel="stylesheet" type="text/css" href="_static/classic.css?v=514cf933" /> |
| |
| <script src="_static/documentation_options.js?v=e1fecbe9"></script> |
| <script src="_static/doctools.js?v=888ff710"></script> |
| <script src="_static/sphinx_highlight.js?v=dc90522c"></script> |
| |
| <link rel="index" title="Index" href="genindex.html" /> |
| <link rel="search" title="Search" href="search.html" /> |
| <link rel="next" title="OPAL Specification" href="opal-spec.html" /> |
| <link rel="prev" title="SkiBoot Documentation" href="index.html" /> |
| </head><body> |
| <div class="related" role="navigation" aria-label="related navigation"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="genindex.html" title="General Index" |
| accesskey="I">index</a></li> |
| <li class="right" > |
| <a href="opal-spec.html" title="OPAL Specification" |
| accesskey="N">next</a> |</li> |
| <li class="right" > |
| <a href="index.html" title="SkiBoot Documentation" |
| accesskey="P">previous</a> |</li> |
| <li class="nav-item nav-item-0"><a href="index.html">skiboot d365a01 |
| documentation</a> »</li> |
| <li class="nav-item nav-item-this"><a href="">Skiboot overview</a></li> |
| </ul> |
| </div> |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body" role="main"> |
| |
| <section id="skiboot-overview"> |
| <h1>Skiboot overview<a class="headerlink" href="#skiboot-overview" title="Link to this heading">¶</a></h1> |
| <p>Skiboot is boot and runtime firmware for OpenPOWER systems. |
| It’s loaded by earlier boot firmware (typically Hostboot). |
| Along with loading the bootloader, it provides some runtime |
| services to the OS (typically Linux).</p> |
| <section id="source-layout"> |
| <h2>Source layout<a class="headerlink" href="#source-layout" title="Link to this heading">¶</a></h2> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>Directory</p></th> |
| <th class="head"><p>Content</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>asm/</p></td> |
| <td><p>small amount, mainly entry points</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>ccan/</p></td> |
| <td><p>bits from <a class="reference external" href="https://ccodearchive.net/">CCAN</a></p></td> |
| </tr> |
| <tr class="row-even"><td><p>core/</p></td> |
| <td><p>common code among machines.</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>doc/</p></td> |
| <td><p>not enough here</p></td> |
| </tr> |
| <tr class="row-even"><td><p>external/</p></td> |
| <td><p>tools and userspace components</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>hdata/</p></td> |
| <td><p>Parses HDAT from Hostboot/FSP into Device Tree</p></td> |
| </tr> |
| <tr class="row-even"><td><p>hw/</p></td> |
| <td><p>drivers for things & fsp things.</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>include/</p></td> |
| <td><p>headers!</p></td> |
| </tr> |
| <tr class="row-even"><td><p>libc/</p></td> |
| <td><p>tiny libc, originally from <a class="reference external" href="https://github.com/aik/SLOF/">SLOF</a></p></td> |
| </tr> |
| <tr class="row-odd"><td><p>libfdt/</p></td> |
| <td><p>Manipulate flattened device trees</p></td> |
| </tr> |
| <tr class="row-even"><td><p>libflash/</p></td> |
| <td><p>Lib for talking to flash and parsing FFS structs</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>libpore/</p></td> |
| <td><p>to manipulate PORE <a class="footnote-reference brackets" href="#id2" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> engine.</p></td> |
| </tr> |
| <tr class="row-even"><td><p>libstb/</p></td> |
| <td><p>See <a class="reference internal" href="stb.html#stb-overview"><span class="std std-ref">Secure and Trusted Boot Library (LibSTB) Documentation</span></a></p></td> |
| </tr> |
| <tr class="row-odd"><td><p>libxz/</p></td> |
| <td><p>The <a class="reference external" href="https://tukaani.org/xz/embedded.html">xz_embedded</a> library</p></td> |
| </tr> |
| <tr class="row-even"><td><p>opal-ci/</p></td> |
| <td><p>Some scripts to help Continuous Integration testing</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>platforms/</p></td> |
| <td><p>Platform (machine/BMC) specific code</p></td> |
| </tr> |
| <tr class="row-even"><td><p>test/</p></td> |
| <td><p>Test scripts and binaries</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <aside class="footnote-list brackets"> |
| <aside class="footnote brackets" id="id2" role="doc-footnote"> |
| <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span> |
| <p>Power On Reset Engine. Used to bring cores out of deep sleep states. |
| For POWER9, this also includes the <cite>p9_stop_api</cite> which manipulates |
| the low level microcode to-reinit certain SPRs on transition out of |
| a state losing STOP state.</p> |
| </aside> |
| </aside> |
| <p>We have a spinlock implementation in <a class="reference external" href="https://github.com/open-power/skiboot/blob/v5.8/asm/lock.S">asm/lock.S</a> |
| Entry points are detailed in <a class="reference external" href="https://github.com/open-power/skiboot/blob/v5.8/asm/head.S">asm/head.S</a> |
| The main C entry point is in <a class="reference external" href="https://github.com/open-power/skiboot/blob/v5.8/core/init.c">core/init.c</a>: <a class="reference external" href="https://github.com/open-power/skiboot/blob/v5.8/core/init.c#L785">main_cpu_entry()</a></p> |
| </section> |
| <section id="binaries"> |
| <h2>Binaries<a class="headerlink" href="#binaries" title="Link to this heading">¶</a></h2> |
| <p>The following binaries are built:</p> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>File</p></th> |
| <th class="head"><p>Purpose</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>skiboot.lid</p></td> |
| <td><p>Binary for flashing onto systems <a class="footnote-reference brackets" href="#id10" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p></td> |
| </tr> |
| <tr class="row-odd"><td><p>skiboot.lid.stb</p></td> |
| <td><p>Secure and Trusted Boot container wrapped skiboot</p></td> |
| </tr> |
| <tr class="row-even"><td><p><em>skiboot.lid.xz</em></p></td> |
| <td><p>XZ compressed binary <a class="footnote-reference brackets" href="#id11" id="id8" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a></p></td> |
| </tr> |
| <tr class="row-odd"><td><p><em>skiboot.lid.xz.stb</em></p></td> |
| <td><p>STB container wrapped XZ compressed skiboot <a class="footnote-reference brackets" href="#id12" id="id9" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a></p></td> |
| </tr> |
| <tr class="row-even"><td><p>skiboot.elf</p></td> |
| <td><p>is the elf binary of it, lid comes from this</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>skiboot.map</p></td> |
| <td><p>plain map of symbols</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <aside class="footnote-list brackets"> |
| <aside class="footnote brackets" id="id10" role="doc-footnote"> |
| <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id7">2</a><span class="fn-bracket">]</span></span> |
| <p>Practically speaking, this is just IBM FSP based systems now. Since |
| the <cite>skiboot.lid</cite> size is now greater than 1MB, which is the size of |
| the default <cite>PAYLOAD</cite> PNOR partition size on OpenPOWER systems, you |
| will want the <cite>skiboot.lid.xz</cite> or <cite>skiboot.lid.xz.stb</cite> instead.</p> |
| </aside> |
| <aside class="footnote brackets" id="id11" role="doc-footnote"> |
| <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">3</a><span class="fn-bracket">]</span></span> |
| <p>On OpenPOWER systems, hostboot will read and decompress XZ |
| compressed payloads. This shortens boot time (less data to read), |
| adds a checksum over the <cite>PAYLOAD</cite> and saves valuable PNOR space. |
| If in doubt, use this payload.</p> |
| </aside> |
| <aside class="footnote brackets" id="id12" role="doc-footnote"> |
| <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id9">4</a><span class="fn-bracket">]</span></span> |
| <p>If a secure boot system, use this payload.</p> |
| </aside> |
| </aside> |
| </section> |
| <section id="booting"> |
| <h2>Booting<a class="headerlink" href="#booting" title="Link to this heading">¶</a></h2> |
| <p>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.</p> |
| <p>Essentially, we do this by doing an atomic fetch and inc and whoever gets 0 |
| 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.</p> |
| <p>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 <a class="reference external" href="https://devicetree.org/">https://devicetree.org/</a> ), 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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| </section> |
| <section id="os-interface"> |
| <h2>OS interface<a class="headerlink" href="#os-interface" title="Link to this heading">¶</a></h2> |
| <p>OPAL (skiboot) is exclusively called through OPAL calls. The OS has complete |
| controll of <em>when</em> OPAL code is executed. The design of all OPAL APIs is that |
| we do not block in OPAL, so as not to introduce jitter.</p> |
| <p>Skiboot maintains its own stack for each CPU, the running OS does not need |
| to donate or reserve any of its stack space.</p> |
| <p>With the OPAL API calls and device tree bindings we have the OPAL ABI.</p> |
| </section> |
| <section id="interrupts"> |
| <h2>Interrupts<a class="headerlink" href="#interrupts" title="Link to this heading">¶</a></h2> |
| <p>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 |
| <a class="reference internal" href="opal-api/opal-handle-interrupt.html#opal-handle-interrupt"><span class="std std-ref">OPAL_HANDLE_INTERRUPT</span></a> call is made by the OS for OPAL to do what’s |
| needed.</p> |
| </section> |
| <section id="memory"> |
| <h2>Memory<a class="headerlink" href="#memory" title="Link to this heading">¶</a></h2> |
| <p>We initially occupy a chunk of memory, “heap”. We pass to the OS (Linux) |
| a reservation of what we occupy (including stacks).</p> |
| <p>In the source file include/mem-map.h we include a memory map. This is |
| manually generated, not automatically generated.</p> |
| <p>We use CCAN for a bunch of helper code, turning on things like DEBUG_LOCKS |
| as these are not a performance issue for us, and we like to be careful.</p> |
| <p>In include/config.h there are defines for turning on extra tracing. |
| OPAL is what we name the interface from skiboot to OS (Linux).</p> |
| <p>Each CPU gets a 16k stack, which is probably more than enough. Stack |
| should be used sparingly though.</p> |
| <p>Important memory locations:</p> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>Location</p></th> |
| <th class="head"><p>What’s there</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>SKIBOOT_BASE</p></td> |
| <td><p>where skiboot lives, of SKIBOOT_SIZE</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>HEAP_BASE</p></td> |
| <td><p>Where skiboot heap starts, of HEAP_SIZE</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <p>There is also SKIBOOT_SIZE (manually calculated) and DEVICE_TREE_MAX_SIZE, |
| which is largely historical.</p> |
| </section> |
| <section id="skiboot-log"> |
| <h2>Skiboot log<a class="headerlink" href="#skiboot-log" title="Link to this heading">¶</a></h2> |
| <p>There is a circular log buffer that skiboot maintains. This can be |
| accessed either from the FSP or through /dev/mem or through the sysfs |
| file /sys/firmware/opal/msglog.</p> |
| </section> |
| </section> |
| |
| |
| <div class="clearer"></div> |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"> |
| <div> |
| <h3><a href="index.html">Table of Contents</a></h3> |
| <ul> |
| <li><a class="reference internal" href="#">Skiboot overview</a><ul> |
| <li><a class="reference internal" href="#source-layout">Source layout</a></li> |
| <li><a class="reference internal" href="#binaries">Binaries</a></li> |
| <li><a class="reference internal" href="#booting">Booting</a></li> |
| <li><a class="reference internal" href="#os-interface">OS interface</a></li> |
| <li><a class="reference internal" href="#interrupts">Interrupts</a></li> |
| <li><a class="reference internal" href="#memory">Memory</a></li> |
| <li><a class="reference internal" href="#skiboot-log">Skiboot log</a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| </div> |
| <div> |
| <h4>Previous topic</h4> |
| <p class="topless"><a href="index.html" |
| title="previous chapter">SkiBoot Documentation</a></p> |
| </div> |
| <div> |
| <h4>Next topic</h4> |
| <p class="topless"><a href="opal-spec.html" |
| title="next chapter">OPAL Specification</a></p> |
| </div> |
| <div role="note" aria-label="source link"> |
| <h3>This Page</h3> |
| <ul class="this-page-menu"> |
| <li><a href="_sources/overview.rst.txt" |
| rel="nofollow">Show Source</a></li> |
| </ul> |
| </div> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3 id="searchlabel">Quick search</h3> |
| <div class="searchformwrapper"> |
| <form class="search" action="search.html" method="get"> |
| <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> |
| <input type="submit" value="Go" /> |
| </form> |
| </div> |
| </div> |
| <script>document.getElementById('searchbox').style.display = "block"</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="related" role="navigation" aria-label="related navigation"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="genindex.html" title="General Index" |
| >index</a></li> |
| <li class="right" > |
| <a href="opal-spec.html" title="OPAL Specification" |
| >next</a> |</li> |
| <li class="right" > |
| <a href="index.html" title="SkiBoot Documentation" |
| >previous</a> |</li> |
| <li class="nav-item nav-item-0"><a href="index.html">skiboot d365a01 |
| documentation</a> »</li> |
| <li class="nav-item nav-item-this"><a href="">Skiboot overview</a></li> |
| </ul> |
| </div> |
| <div class="footer" role="contentinfo"> |
| © Copyright 2016-2017, IBM, others. |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6. |
| </div> |
| </body> |
| </html> |
