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
14 4.0 Submitting patches
18 1.0 Introduction to Slimline Open Firmware
19 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
21 The IEEE Standard 1275-1994 [1], Standard for Boot (Initialization Configura-
22 tion) Firmware, Core Requirements and Practices, was the first non-proprietary
23 open standard for boot firmware that is usable on different processors and
24 buses. Firmware which complies with this standard (also known as Open Firmware)
25 includes a processor-independent device interface that allows add-in devices
26 to identify itself and to supply a single boot driver that can be used,
27 unchanged, on any CPU. In addition, Open Firmware includes a user interface
28 with powerful scripting and debugging support and a client interface that
29 allows an operating system and its loaders to use Open Firmware services
30 during the configuration and initialization process. Open Firmware stores
31 information about the hardware in a tree structure called the
32 "device tree". This device tree supports multiple interconnected system
33 buses and offers a framework for "plug and play"-type auto configuration
34 across different buses. It was designed to support a variety of different
35 processor Instruction Set Architectures (ISAs) and buses.
37 The full documentation of this Standard can be found in [1].
39 Slimline Open Firmware (SLOF) is now an implementation of the IEEE 1275
40 standard that is available under a BSD-style license. Please see the file
44 2.0 Using the source code
45 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
47 This version of SLOF currently supports two major platforms ("boards" in the
50 - js2x : The PowerPC 970 based systems JS20, JS21 and the PowerStation
51 - qemu : Used as partition firmware for pseries machines running on KVM/QEMU
53 The following sections will give you a short introduction about how to compile
54 and improve the source code.
55 Please read the file INSTALL for details about how to install the firmware on
60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
62 To build SLOF you need:
63 - Recent GNU tools, configured for powerpc64-linux
64 - GCC: 3.3.3 and newer are known to work
65 - Binutils: use a version as new as possible
66 - Subversion (for retrieving the x86 emulator)
68 - set the CROSS variable
69 - something like export CROSS="powerpc64-unknown-linux-gnu-"
70 when using a cross compiler
73 when using a native compiler
75 - For building SLOF for the PowerStation, it is necessary to
76 download a x86 emulator which is used to execute the BIOS
77 of VGA card; to download the x86 emulator following steps are
79 - cd other-licence/x86emu/
80 - ./x86emu_download.sh # this downloads the x86 emulator sources
83 - Now you can compile the firmware.
84 - For building SLOF for JS20, JS21 or the PowerStation, type:
86 You also might want to build the takeover executable by typing:
87 make -C board-js2x takeover
88 - For building SLOF as the partition firmware for KVM/QEMU, type:
90 The resulting ROM image "boot_rom.bin" can then be found in the main
94 2.2 Overview of the source code
95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
97 The SLOF source code is structured into the following directories:
99 - llfw : The Low-Level Firmware - this part is platform-specific firmware
100 that is responsible to boot the system from the reset vector to a
101 state where it is possible to run the Open Firmware Forth engine
102 (i.e. it sets up the necessary CPU registers, intializes the memory,
103 does some board-specific hardware configuration, etc.)
105 - slof : The code for the Open Firmware environment, including the Forth
106 engine (called "Paflof") and the necessary Forth source files.
108 - rtas : The Run-Time Abstraction Services, which can be used by the operating
109 system to access certain hardware without knowing the details.
110 See [2] for a description of these services.
112 - clients : Code that runs on top of the Open Firmware client interface.
113 Currently, there are two clients:
114 - net-snk : Used for network bootloading (a TFTP client)
115 - takeover : A separate binary that can be used for bootstrapping
116 SLOF on a JS20/JS21 (see FlashingSLOF.pdf for details).
118 - drivers : Driver code for various hardware (currently only NIC drivers).
120 - lib : Libraries with common code.
122 - romfs / tools : Tools that are required for building the firmware image.
124 - board-* : The board directories contain all the code that is unique to the
125 corresponding platform.
128 2.3 The Open Firmware engine
129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
131 Open Firmware (OF) is based on the programming language Forth.
132 SLOF use Paflof as the Forth engine, which was originally developed by
133 Segher Boessenkool. Most parts of the Forth engine are implemented in C, by
134 using GNU extensions of ANSI C, (e.g. assigned goto, often misnamed "computed
135 goto"), resulting in a very efficient yet still quite portable engine.
137 The basic Forth words, so-called primitives, are implemented with
138 a set of C macros. A set of .in and .code files are provided, which
139 define the semantic of the Forth primitives. A Perl script translates
140 these files into valid C code, which will be compiled into the Forth engine.
141 The complete Forth system composes of the basic Forth primitives and
142 a set of Forth words, which are compiled during the start of the Forth
146 Forth primitive 'dup'
148 dup ( a -- a a) \ Duplicate top of stack element
155 PRIM(DUP) cell x = TOS; PUSH; TOS = x; MIRP
159 static cell xt_DUP[] = { { .a = xt_DOTICK }, { .c = "\000\003DUP" },
160 { .a = &&code_DUP }, };
162 code_DUP: { asm("#### " "DUP"); void *w = (cfa = (++ip)->a)->a;
163 cell x = (*dp); dp++; (*dp) = x; goto *w; }
165 Without going into detail, it can be seen, that the data stack is
166 implemented in C as an array of cells, where dp is the pointer to the top of
169 For the implementation of the Open Firmware, most of the code is added as
170 Forth code and bound to the engine. Also the system vectors for all kinds of
171 exceptions will be part of the image. Additionally a secondary boot-loader
172 or any other client application can be bound to the code as payload,
173 e.g. diagnostics and test programs.
175 The Open Firmware image will be put together by the build
176 process, with a loader at the start of the image. This loader
177 is called by Low Level Firmware and loads at boot time the Open
178 Firmware to it's location in memory (see 1.3 Load process). Additionally
179 a secondary boot loader or any other client application can be bound
180 to the code as payload.
182 The Low Level Firmware (LLFW) is responsible for setting up the
183 system in an initial state. This task includes the setup of the
184 CPUs, the system memory and all the buses as well as the serial port
188 2.4 Extending the Forth engine
189 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
191 In the following paragraphs it will be shown how to add
192 new primitive words (i.e., words implemented not by building
193 pre-existing Forth words together, but instead implemented in
194 C or assembler). With this, it is possible to adapt SLOF to
195 the specific needs of different hardware and architectures.
200 For a new primitive, following steps have to be done:
202 + Definition of primitive name in <arch>.in
203 - cod(ABC) defines primitive ABC
205 You can also use the following in a .in file, see existing
206 code for how to use these:
207 - con(ABC) defines constant ABC
208 - col(ABC) defines colon definition ABC
209 - dfr(ABC) defines defer definition ABC
211 + Definition of the primitives effects in <arch>.code
214 The code for the primitive body is any C-code. With
215 the macros of prim.code the data and return stack of
216 the Forth engine can be appropriately manipulated.
219 3.0 Limitations of this package
220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
222 On a JS20 the memory setup is very static and therefore there are
223 only very few combinations of memory DIMM placement actually work.
225 Known booting configurations:
227 * 4x 256 MB (filling all slots) -- only "0.5 GB" reported.
228 * 2x 1 GB, slots 3/4 -- only "0.5 GB" reported.
230 Known failing configurations
232 * 2x 256 MB, slots 3/4
233 * 2x 256 MB, slots 1/2
235 On a JS20 SLOF wil always report 0.5 GB even if there is much more memory
238 On a JS21 all memory configurations should work.
241 4.0 Submitting patches
242 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
244 Patches for SLOF should be made against https://github.com/aik/SLOF,
245 the master branch and posted to slof@lists.ozlabs.org.
246 The patches must be signed using "Signed-off-by" tag with a real name to
247 confirm that you certify the Developer Certificate of Origin Version 1.1,
252 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
254 New C code submitted to SLOF should follow the coding style guidelines
255 for the Linux kernel [4] with the following exceptions:
257 - in the event that you require a specific width, use a standard type
258 like int32_t, uint32_t, uint64_t, etc. Don't use Linux kernel internal
259 types like u32, __u32 or __le32.
261 New Forth code should use 4 space indentations and no tabs. Patches for
262 the old code should keep the existing style which usually is
265 New assembly code submitted to SLOF should follow the coding style
266 guidelines for the Linux kernel [4], i.e. indent with tabs, not with spaces.
270 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
272 [1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration)
273 Firmware: Core Requirements and Practices
275 [2] PAPR Standard, Power.org(TM) Standard for Power Architecture(R) Platform
276 Requirements (Workstation, Server), Version 2.4, December 7, 2009
278 [3] Developer Certificate of Origin Version 1.1
279 http://developercertificate.org/
281 [4] Linux kernel coding style
282 https://github.com/torvalds/linux/blob/master/Documentation/CodingStyle