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
337
338
339
340
341
342
343
344
345
346
347
|
<!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>OPAL Specification — skiboot 25e28ea
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="Supported platforms & CPUs" href="platforms-and-cpus.html" />
<link rel="prev" title="Skiboot overview" href="overview.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="platforms-and-cpus.html" title="Supported platforms & CPUs"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="overview.html" title="Skiboot overview"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">skiboot 25e28ea
documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">OPAL Specification</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="opal-specification">
<h1>OPAL Specification<a class="headerlink" href="#opal-specification" title="Permalink to this headline">¶</a></h1>
<p><strong>DRAFT - VERSION 0.0.1 AT BEST.</strong></p>
<p><strong>COMMENTS ARE WELCOME</strong> - and indeed, needed.</p>
<p>If you are reading this, congratulations: you’re now reviewing it!</p>
<p>This document aims to define what it means to be OPAL compliant.</p>
<p>While skiboot is the reference implementation, this documentation should
be complete enough that (given hardware documentation) create another
implementation. It is not recommended that you do this though.</p>
<section id="authors">
<h2>Authors<a class="headerlink" href="#authors" title="Permalink to this headline">¶</a></h2>
<p>Stewart Smith <<a class="reference external" href="mailto:stewart%40linux.ibm.com">stewart<span>@</span>linux<span>.</span>ibm<span>.</span>com</a>> : OPAL Architect, IBM</p>
</section>
<section id="definitions">
<h2>Definitions<a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h2>
<dl class="simple">
<dt>Host processor</dt><dd><p>the main POWER CPU (e.g. the POWER8 CPU)</p>
</dd>
<dt>Host OS</dt><dd><p>the operating system running on the host processor.</p>
</dd>
<dt>OPAL</dt><dd><p>OpenPOWER Abstraction Layer.</p>
</dd>
</dl>
</section>
<section id="what-is-opal">
<h2>What is OPAL?<a class="headerlink" href="#what-is-opal" title="Permalink to this headline">¶</a></h2>
<p>The OpenPower Abstraction Layer (OPAL) is boot and runtime firmware for
POWER systems. There are several components to what makes up a firmware
image for OpenPower machines.</p>
<p>For example, there may be:</p>
<ul class="simple">
<li><p>BMC firmware</p>
<ul>
<li><p>Firmware that runs purely on the BMC.</p></li>
<li><p>On IBM systems that have an FSP rather than a BMC, there is FSP firmware</p></li>
<li><p>While essential to having the machine function, this firmware is not
part of the OPAL Specification.</p></li>
</ul>
</li>
<li><p>HostBoot</p>
<ul>
<li><p>HostBoot ( <a class="reference external" href="https://github.com/open-power/hostboot">https://github.com/open-power/hostboot</a> ) performs all
processor, bus and memory initialization within IBM POWER based systems.</p></li>
</ul>
</li>
<li><p>OCC Firmware</p>
<ul>
<li><p>On Chip Controller ( Firmware for OCC - a PPC405 core inside the IBM
POWER8 in charge of keeping the system thermally and power safe ).</p></li>
</ul>
</li>
<li><p>SkiBoot</p>
<ul>
<li><p>Boot and runtime services.</p></li>
</ul>
</li>
<li><p>A linux kernel and initramfs incorporating petitboot</p>
<ul>
<li><p>The bootloader. This is where a user chooses what OS to boot, and
petitboot will use kexec to switch to the host Operating System
(for example, PowerKVM).</p></li>
</ul>
</li>
</ul>
<p>While all of these components may be absolutely essential to power on,
boot and operate a specific OpenPower POWER8 system, the majority of
the code mentioned above can be thought of as implementation details
and not something that should form part of an OPAL Specification.</p>
<p>For an OPAL system, we assume that the hardware is functioning and any
hardware management that is specific to a platform is performed by OPAL
firmware transparently to the host OS.</p>
<p>The OPAL Specification focus on the interface between firmware and the
Operating System. It does not dictate that any specific pieces of firmware
code be used, although re-inventing the wheel is strongly discouraged.</p>
<p>The OPAL Specification explicitly allows for:</p>
<ul class="simple">
<li><p>A conforming implementation to not use any of the reference implementation
code.</p></li>
<li><p>A conforming implementation to use any 64bit POWER ISA conforming processor,
and not be limited to the IBM POWER8.</p></li>
<li><p>A conforming implementation to be a simulator, emulator or virtual environment</p></li>
<li><p>A host OS other than Linux</p></li>
</ul>
<p>Explicitly not covered in this specification:</p>
<ul class="simple">
<li><p>A 32bit OPAL Specification
There is no reason this couldn’t exist but the current specification is for
64bit POWER systems only.</p></li>
</ul>
</section>
<section id="boot-services">
<h2>Boot Services<a class="headerlink" href="#boot-services" title="Permalink to this headline">¶</a></h2>
<p>An OPAL compliant firmware implementation will load and execute a payload
capable of booting a Host Operating System.</p>
<p>The reference implementation loads a Linux kernel with an initramfs with
a minimal userspace and the petitboot boot loader - collectively referred
to as skiroot.</p>
<p>The OPAL Specification explicitly allows variation in this payload.</p>
<p>A requirement of the payload is that it MUST support loading and booting
an uncompressed vmlinux Linux kernel.
[<strong>TODO</strong>: expand on what this actually means]</p>
<p>An OPAL system MUST pass a device tree to the host kernel.
[<strong>TODO</strong>: expand the details, add device-tree section and spec]</p>
<p>An OPAL system MUST provide the host kernel with enough information to
know how to call OPAL runtime services.
[<strong>TODO</strong>: expand on this. ]</p>
<p>Explicitly not covered by the OPAL Specification:</p>
<ul class="simple">
<li><p>Kernel module ABI for skiroot kernel</p></li>
<li><p>Userspace environment of skiroot</p></li>
<li><p>That skiroot is Linux.</p></li>
</ul>
<p>Explicitly allowed:</p>
<ul class="simple">
<li><p>Replacing the payload with something of equal/similar functionality
(whether replacing skiroot with an implementation of Zork would be compliant
is left as an exercise for the reader)</p></li>
</ul>
</section>
<section id="payload-environment">
<h2>Payload Environment<a class="headerlink" href="#payload-environment" title="Permalink to this headline">¶</a></h2>
<p>The payload is started with:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 17%" />
<col style="width: 83%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Register</p></th>
<th class="head"><p>Value</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>r3</p></td>
<td><p>address of flattened device-tree (fdt)</p></td>
</tr>
<tr class="row-odd"><td><p>r8</p></td>
<td><p>OPAL base</p></td>
</tr>
<tr class="row-even"><td><p>r9</p></td>
<td><p>OPAL entry</p></td>
</tr>
</tbody>
</table>
</section>
<section id="runtime-services">
<h2>Runtime Services<a class="headerlink" href="#runtime-services" title="Permalink to this headline">¶</a></h2>
<p>An OPAL Specification compliant system provides runtime services to the host
Operating System via a standard interface.</p>
<dl class="simple">
<dt>An OPAL call is made by calling opal_entry with:</dt><dd><ul class="simple">
<li><p>r0: OPAL Token</p></li>
<li><p>r2: OPAL Base</p></li>
<li><p>r3..r10: Args (up to 8)</p></li>
</ul>
</dd>
</dl>
<p>The OPAL API is defined in skiboot/doc/opal-api/</p>
<p>Not all OPAL APIs must be supported for a system to be compliant. When
called with an unsupported token, a compliant firmware implementation
MUST fail gracefully and not crash. Reporting a warning that an unsupported
token was called is okay, as compliant host Operating Systems should use
OPAL_CHECK_TOKEN to test for optional functionality.</p>
<p>All parameters to OPAL calls are big endian. Little endian hosts MUST
appropriately convert parameters before passing them to OPAL.</p>
<p>Machine state across OPAL calls:</p>
<ul class="simple">
<li><p>r1 is preserved</p></li>
<li><p>r12 is scratch</p></li>
<li><p>r13 - 31 preserved</p></li>
<li><p>64bit HV real mode</p></li>
<li><p>big endian</p></li>
<li><p>external interrupts disabled</p></li>
</ul>
</section>
<section id="detecting-opal-support">
<h2>Detecting OPAL Support<a class="headerlink" href="#detecting-opal-support" title="Permalink to this headline">¶</a></h2>
<p>A Host OS may need to detect the presence of OPAL as it may support booting
under other platforms. For example, a single Linux kernel can be built to boot
under OPAL and under PowerVM or qemu pseries machine type.</p>
<p>The root node of the device tree MUST have compatible = “ibm,powernv”.
See <a class="reference internal" href="device-tree.html#device-tree"><span class="std std-ref">Device Tree</span></a> for more details.</p>
<p>The presence of the “/ibm,opal” entry in the device tree signifies running
under OPAL. Additionally, the “/ibm,opal” node MUST have a compatibile property
listing “ibm,opal-v3”.</p>
<p>The “/ibm,opal” node MUST have the following properties:</p>
<div class="highlight-dts notranslate"><div class="highlight"><pre><span></span><span class="nc">ibm,opal</span> <span class="p">{</span>
<span class="nf">compatible</span> <span class="o">=</span> <span class="s">"ibm,opal-v3"</span><span class="p">;</span>
<span class="nf">opal-base-address</span> <span class="o">=</span> <span class="p"><>;</span>
<span class="nf">opal-entry-address</span> <span class="o">=</span> <span class="p"><>;</span>
<span class="nf">opal-runtime-size</span> <span class="o">=</span> <span class="p"><>;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>The compatible property MAY have other strings, such as a future “ibm,opal-v4”.
These are reserved for future use.</p>
<p>Some releases of the reference implementation (skiboot) have had compatible
contain “ibm,opal-v2” as well as “ibm,opal-v3”. Host operating systems MUST
NOT rely on “ibm,opal-v2”, this is a relic from early OPAL history.</p>
<p>The “ibm,opal” node MUST have a child node named “firmware”. It MUST contain
the following:</p>
<div class="highlight-dts notranslate"><div class="highlight"><pre><span></span><span class="nc">firmware</span> <span class="p">{</span>
<span class="nf">compatible</span> <span class="o">=</span> <span class="s">"ibm,opal-firmware"</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>It MUST contain one of the following two properties: git-id, version.
The git-id property is deprecated, and version SHOULD be used. These
are informative and MUST NOT be used by the host OS to determine anything
about the firmware environment.</p>
<p>The version property is a textual representation of the OPAL version.
For example, it may be “skiboot-4.1” or other versioning described
in more detail in <a class="reference internal" href="process/versioning.html#versioning"><span class="std std-ref">Versioning Scheme of skiboot</span></a>.</p>
</section>
<section id="opal-log">
<h2>OPAL log<a class="headerlink" href="#opal-log" title="Permalink to this headline">¶</a></h2>
<p>OPAL implementation SHOULD have an in memory log where informational and
error messages are stored. If present it MUST be human readable and text based.
There is a separate facility (Platform Error Logs) for machine readable errors.</p>
<p>A conforming implementation MAY also output the log to a serial port or similar.
An implementation MAY choose to only output certain log messages to a serial
port.</p>
<p>For example, the reference implementation (skiboot) by default filters log
messages so that only higher priority log messages go over the serial port
while more messages go to the in memory buffer.</p>
<p>[TODO: add device-tree bits here]</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="#">OPAL Specification</a><ul>
<li><a class="reference internal" href="#authors">Authors</a></li>
<li><a class="reference internal" href="#definitions">Definitions</a></li>
<li><a class="reference internal" href="#what-is-opal">What is OPAL?</a></li>
<li><a class="reference internal" href="#boot-services">Boot Services</a></li>
<li><a class="reference internal" href="#payload-environment">Payload Environment</a></li>
<li><a class="reference internal" href="#runtime-services">Runtime Services</a></li>
<li><a class="reference internal" href="#detecting-opal-support">Detecting OPAL Support</a></li>
<li><a class="reference internal" href="#opal-log">OPAL log</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="overview.html"
title="previous chapter">Skiboot overview</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="platforms-and-cpus.html"
title="next chapter">Supported platforms & CPUs</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/opal-spec.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="platforms-and-cpus.html" title="Supported platforms & CPUs"
>next</a> |</li>
<li class="right" >
<a href="overview.html" title="Skiboot overview"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">skiboot 25e28ea
documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">OPAL Specification</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>
|
