1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Skiboot overview — skiboot e6cda17
documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></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 e6cda17
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="Permalink to this headline">¶</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="Permalink to this headline">¶</a></h2>
<table class="docutils align-default">
<colgroup>
<col style="width: 16%" />
<col style="width: 84%" />
</colgroup>
<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">1</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>
<dl class="footnote brackets">
<dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
<dd><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>
</dd>
</dl>
<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="Permalink to this headline">¶</a></h2>
<p>The following binaries are built:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 29%" />
<col style="width: 71%" />
</colgroup>
<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">2</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">3</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">4</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>
<dl class="footnote brackets">
<dt class="label" id="id10"><span class="brackets"><a class="fn-backref" href="#id7">2</a></span></dt>
<dd><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>
</dd>
<dt class="label" id="id11"><span class="brackets"><a class="fn-backref" href="#id8">3</a></span></dt>
<dd><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>
</dd>
<dt class="label" id="id12"><span class="brackets"><a class="fn-backref" href="#id9">4</a></span></dt>
<dd><p>If a secure boot system, use this payload.</p>
</dd>
</dl>
</section>
<section id="booting">
<h2>Booting<a class="headerlink" href="#booting" title="Permalink to this headline">¶</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="Permalink to this headline">¶</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="Permalink to this headline">¶</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="Permalink to this headline">¶</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">
<colgroup>
<col style="width: 18%" />
<col style="width: 82%" />
</colgroup>
<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="Permalink to this headline">¶</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">
<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>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">SkiBoot Documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="opal-spec.html"
title="next chapter">OPAL Specification</a></p>
<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>$('#searchbox').show(0);</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 e6cda17
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> 4.3.2.
</div>
</body>
</html>
|
