1
Slimline Open Firmware - SLOF
3
Copyright (C) 2004, 2012 IBM Corporation
7
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
8
1.0 Introduction to Open Firmware
9
2.0 Using the source code
11
2.2 Overview of the source code
12
2.4 Extending the Forth engine
16
1.0 Introduction to Slimline Open Firmware
17
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
19
The IEEE Standard 1275-1994 [1], Standard for Boot (Initialization Configura-
20
tion) Firmware, Core Requirements and Practices, was the first non-proprietary
21
open standard for boot firmware that is usable on different processors and
22
buses. Firmware which complies with this standard (also known as Open Firmware)
23
includes a processor-independent device interface that allows add-in devices
24
to identify itself and to supply a single boot driver that can be used,
25
unchanged, on any CPU. In addition, Open Firmware includes a user interface
26
with powerful scripting and debugging support and a client interface that
27
allows an operating system and its loaders to use Open Firmware services
28
during the configuration and initialization process. Open Firmware stores
29
information about the hardware in a tree structure called the
30
"device tree". This device tree supports multiple interconnected system
31
buses and offers a framework for "plug and play"-type auto configuration
32
across different buses. It was designed to support a variety of different
33
processor Instruction Set Architectures (ISAs) and buses.
35
The full documentation of this Standard can be found in [1].
37
Slimline Open Firmware (SLOF) is now an implementation of the IEEE 1275
38
standard that is available under a BSD-style license. Please see the file
42
2.0 Using the source code
43
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
45
This version of SLOF currently supports two major platforms ("boards" in the
48
- js2x : The PowerPC 970 based systems JS20, JS21 and the PowerStation
49
- qemu : Used as partition firmware for pseries machines running on KVM/QEMU
51
The following sections will give you a short introduction about how to compile
52
and improve the source code.
53
Please read the file INSTALL for details about how to install the firmware on
58
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
60
To build SLOF you need:
61
- Recent GNU tools, configured for powerpc64-linux
62
- GCC: 3.3.3 and newer are known to work
63
- Binutils: use a version as new as possible
64
- Subversion (for retrieving the x86 emulator)
66
- set the CROSS variable
67
- something like export CROSS="powerpc64-unknown-linux-gnu-"
68
when using a cross compiler
71
when using a native compiler
73
- For building SLOF for the PowerStation, it is necessary to
74
download a x86 emulator which is used to execute the BIOS
75
of VGA card; to download the x86 emulator following steps are
77
- cd other-licence/x86emu/
78
- ./x86emu_download.sh # this downloads the x86 emulator sources
81
- Now you can compile the firmware.
82
- For building SLOF for JS20, JS21 or the PowerStation, type:
84
You also might want to build the takeover executable by typing:
85
make -C board-js2x takeover
86
- For building SLOF as the partition firmware for KVM/QEMU, type:
88
The resulting ROM image "boot_rom.bin" can then be found in the main
92
2.2 Overview of the source code
93
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
95
The SLOF source code is structured into the following directories:
97
- llfw : The Low-Level Firmware - this part is platform-specific firmware
98
that is responsible to boot the system from the reset vector to a
99
state where it is possible to run the Open Firmware Forth engine
100
(i.e. it sets up the necessary CPU registers, intializes the memory,
101
does some board-specific hardware configuration, etc.)
103
- slof : The code for the Open Firmware environment, including the Forth
104
engine (called "Paflof") and the necessary Forth source files.
106
- rtas : The Run-Time Abstraction Services, which can be used by the operating
107
system to access certain hardware without knowing the details.
108
See [2] for a description of these services.
110
- clients : Code that runs on top of the Open Firmware client interface.
111
Currently, there are two clients:
112
- net-snk : Used for network bootloading (a TFTP client)
113
- takeover : A separate binary that can be used for bootstrapping
114
SLOF on a JS20/JS21 (see FlashingSLOF.pdf for details).
116
- drivers : Driver code for various hardware (currently only NIC drivers).
118
- lib : Libraries with common code.
120
- romfs / tools : Tools that are required for building the firmware image.
122
- board-* : The board directories contain all the code that is unique to the
123
corresponding platform.
126
2.3 The Open Firmware engine
127
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
129
Open Firmware (OF) is based on the programming language Forth.
130
SLOF use Paflof as the Forth engine, which was originally developed by
131
Segher Boessenkool. Most parts of the Forth engine are implemented in C, by
132
using GNU extensions of ANSI C, (e.g. assigned goto, often misnamed "computed
133
goto"), resulting in a very efficient yet still quite portable engine.
135
The basic Forth words, so-called primitives, are implemented with
136
a set of C macros. A set of .in and .code files are provided, which
137
define the semantic of the Forth primitives. A Perl script translates
138
these files into valid C code, which will be compiled into the Forth engine.
139
The complete Forth system composes of the basic Forth primitives and
140
a set of Forth words, which are compiled during the start of the Forth
144
Forth primitive 'dup'
146
dup ( a -- a a) \ Duplicate top of stack element
153
PRIM(DUP) cell x = TOS; PUSH; TOS = x; MIRP
157
static cell xt_DUP[] = { { .a = xt_DOTICK }, { .c = "\000\003DUP" },
158
{ .a = &&code_DUP }, };
160
code_DUP: { asm("#### " "DUP"); void *w = (cfa = (++ip)->a)->a;
161
cell x = (*dp); dp++; (*dp) = x; goto *w; }
163
Without going into detail, it can be seen, that the data stack is
164
implemented in C as an array of cells, where dp is the pointer to the top of
167
For the implementation of the Open Firmware, most of the code is added as
168
Forth code and bound to the engine. Also the system vectors for all kinds of
169
exceptions will be part of the image. Additionally a secondary boot-loader
170
or any other client application can be bound to the code as payload,
171
e.g. diagnostics and test programs.
173
The Open Firmware image will be put together by the build
174
process, with a loader at the start of the image. This loader
175
is called by Low Level Firmware and loads at boot time the Open
176
Firmware to it's location in memory (see 1.3 Load process). Additionally
177
a secondary boot loader or any other client application can be bound
178
to the code as payload.
180
The Low Level Firmware (LLFW) is responsible for setting up the
181
system in an initial state. This task includes the setup of the
182
CPUs, the system memory and all the buses as well as the serial port
186
2.4 Extending the Forth engine
187
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
189
In the following paragraphs it will be shown how to add
190
new primitive words (i.e., words implemented not by building
191
pre-existing Forth words together, but instead implemented in
192
C or assembler). With this, it is possible to adapt SLOF to
193
the specific needs of different hardware and architectures.
198
For a new primitive, following steps have to be done:
200
+ Definition of primitive name in <arch>.in
201
- cod(ABC) defines primitive ABC
203
You can also use the following in a .in file, see existing
204
code for how to use these:
205
- con(ABC) defines constant ABC
206
- col(ABC) defines colon definition ABC
207
- dfr(ABC) defines defer definition ABC
209
+ Definition of the primitives effects in <arch>.code
212
The code for the primitive body is any C-code. With
213
the macros of prim.code the data and return stack of
214
the Forth engine can be appropriately manipulated.
217
3.0 Limitations of this package
218
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
220
On a JS20 the memory setup is very static and therefore there are
221
only very few combinations of memory DIMM placement actually work.
223
Known booting configurations:
225
* 4x 256 MB (filling all slots) -- only "0.5 GB" reported.
226
* 2x 1 GB, slots 3/4 -- only "0.5 GB" reported.
228
Known failing configurations
230
* 2x 256 MB, slots 3/4
231
* 2x 256 MB, slots 1/2
233
On a JS20 SLOF wil always report 0.5 GB even if there is much more memory
236
On a JS21 all memory configurations should work.
240
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
242
[1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration)
243
Firmware: Core Requirements and Practices
245
[2] PAPR Standard, Power.org(TM) Standard for Power Architecture(R) Platform
246
Requirements (Workstation, Server), Version 2.4, December 7, 2009
added
removed
README
