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
|
OPAL Specification
==================
**DRAFT - VERSION 0.0.1 AT BEST.**
**COMMENTS ARE WELCOME** - and indeed, needed.
If you are reading this, congratulations: you're now reviewing it!
This document aims to define what it means to be OPAL compliant.
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.
Authors
-------
Stewart Smith <stewart@linux.vnet.ibm.com> : OPAL Architect, IBM
Definitions
-----------
Host processor - the main POWER CPU (e.g. the POWER8 CPU)
Host OS - the operating system running on the host processor.
OPAL - OpenPOWER Abstraction Layer.
What is OPAL?
-------------
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.
For example, there may be:
* BMC firmware
* Firmware that runs purely on the BMC.
* On IBM systems that have an FSP rather than a BMC, there is FSP firmware
* While essential to having the machine function, this firmware is not
part of the OPAL Specification.
* HostBoot
* HostBoot ( https://github.com/open-power/hostboot ) performs all
processor, bus and memory initialization within IBM POWER based systems.
* OCC Firmware
* On Chip Controller ( Firmware for OCC - a PPC405 core inside the IBM
POWER8 in charge of keeping the system thermally and power safe ).
* SkiBoot
* Boot and runtime services.
* A linux kernel and initramfs incorporating petitboot
* 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).
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.
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.
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.
The OPAL Specification explicitly allows for:
* A conforming implementation to not use any of the reference implementation
code.
* A conforming implementation to use any 64bit POWER ISA conforming processor,
and not be limited to the IBM POWER8.
* A conforming implementation to be a simulator, emulator or virtual environment
* A host OS other than Linux
Explicitly not covered in this specification:
* A 32bit OPAL Specification
There is no reason this couldn't exist but the current specification is for
64bit POWER systems only.
Boot Services
-------------
An OPAL compliant firmware implementation will load and execute a payload
capable of booting a Host Operating System.
The reference implementation loads a Linux kernel with an initramfs with
a minimal userspace and the petitboot boot loader - collectively referred
to as skiroot.
The OPAL Specification explicitly allows variation in this payload.
A requirement of the payload is that it MUST support loading and booting
an uncompressed vmlinux Linux kernel.
[**TODO**: expand on what this actually means]
An OPAL system MUST pass a device tree to the host kernel.
[**TODO**: expand the details, add device-tree section and spec]
An OPAL system MUST provide the host kernel with enough information to
know how to call OPAL runtime services.
[**TODO**: expand on this. ]
Explicitly not covered by the OPAL Specification:
* Kernel module ABI for skiroot kernel
* Userspace environment of skiroot
* That skiroot is Linux.
Explicitly allowed:
* 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)
Payload Environment
-------------------
The payload is started with:
======== =====
Register Value
======== =====
r3 address of flattened device-tree (fdt)
r8 OPAL base
r9 OPAL entry
======== =====
Runtime Services
----------------
An OPAL Specification compliant system provides runtime services to the host
Operating System via a standard interface.
An OPAL call is made by calling opal_entry with:
* r0: OPAL Token
* r2: OPAL Base
* r3..r10: Args (up to 8)
The OPAL API is defined in skiboot/doc/opal-api/
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.
All parameters to OPAL calls are big endian. Little endian hosts MUST
appropriately convert parameters before passing them to OPAL.
Machine state across OPAL calls:
* r1 is preserved
* r12 is scratch
* r13 - 31 preserved
* 64bit HV real mode
* big endian
* external interrupts disabled
Detecting OPAL Support
----------------------
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.
The root node of the device tree MUST have compatible = "ibm,powernv".
See :ref:`device-tree` for more details.
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".
The "/ibm,opal" node MUST have the following properties:
.. code-block:: dts
ibm,opal {
compatible = "ibm,opal-v3";
opal-base-address = <>;
opal-entry-address = <>;
opal-runtime-size = <>;
};
The compatible property MAY have other strings, such as a future "ibm,opal-v4".
These are reserved for future use.
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.
The "ibm,opal" node MUST have a child node named "firmware". It MUST contain
the following:
.. code-block:: dts
firmware {
compatible = "ibm,opal-firmware";
};
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.
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 :ref:`versioning`.
OPAL log
--------
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.
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.
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.
[TODO: add device-tree bits here]
|
