version: update to 20190114
[SLOF.git] / README
1 Slimline Open Firmware - SLOF
2
3 Copyright (C) 2004, 2012  IBM Corporation
4
5
6 Index
7 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
8 1.0 Introduction to Open Firmware
9 2.0 Using the source code
10 2.1 Build process
11 2.2 Overview of the source code
12 2.4 Extending the Forth engine
13 3.0 Limitations
14 4.0 Submitting patches
15 5.0 Coding style
16
17
18 1.0 Introduction to Slimline Open Firmware
19 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
20
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.
36
37 The full documentation of this Standard can be found in [1].
38
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
41 LICENSE for details.
42
43
44 2.0 Using the source code
45 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
46
47 This version of SLOF currently supports two major platforms ("boards" in the
48 SLOF jargon):
49
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
52
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
56 your target system.
57
58
59 2.1 Build process
60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
61
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)
67
68   - set the CROSS variable
69     - something like export CROSS="powerpc64-unknown-linux-gnu-"
70       when using a cross compiler
71     or
72     - export CROSS=""
73       when using a native compiler
74
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
78     required:
79     - cd other-licence/x86emu/
80     - ./x86emu_download.sh      # this downloads the x86 emulator sources
81     - cd -
82
83   - Now you can compile the firmware.
84     - For building SLOF for JS20, JS21 or the PowerStation, type:
85         make js2x
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:
89         make qemu
90     The resulting ROM image "boot_rom.bin" can then be found in the main
91     directory.
92
93
94 2.2 Overview of the source code
95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
96
97 The SLOF source code is structured into the following directories:
98
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.)
104
105 - slof : The code for the Open Firmware environment, including the Forth
106          engine (called "Paflof") and the necessary Forth source files.
107
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.
111
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).
117
118 - drivers : Driver code for various hardware (currently only NIC drivers).
119
120 - lib : Libraries with common code.
121
122 - romfs / tools : Tools that are required for building the firmware image.
123
124 - board-* : The board directories contain all the code that is unique to the
125             corresponding platform.
126
127
128 2.3 The Open Firmware engine
129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
130
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.  
136
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
143 system.
144
145 Example:
146 Forth primitive 'dup'
147
148         dup ( a -- a a) \ Duplicate top of stack element
149
150
151 prim.in:
152         cod(DUP)
153
154 prim.code:
155         PRIM(DUP) cell x = TOS; PUSH; TOS = x; MIRP
156
157 Generated code:
158
159 static cell xt_DUP[] = { { .a = xt_DOTICK }, { .c = "\000\003DUP" },
160          { .a = &&code_DUP }, };
161
162 code_DUP: { asm("#### " "DUP"); void *w = (cfa = (++ip)->a)->a;
163          cell x = (*dp); dp++; (*dp) = x; goto *w; }
164
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
167 stack. 
168
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.
174
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.
181
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
185 itself.
186
187
188 2.4 Extending the Forth engine
189 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
190
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.
196
197
198 To add primitives:
199
200    For a new primitive, following steps have to be done:
201
202    + Definition of primitive name in <arch>.in
203      - cod(ABC) defines primitive ABC
204
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
210
211    + Definition of the primitives effects in <arch>.code
212      - PRIM(ABC) ... MIRP
213
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.
217
218
219 3.0 Limitations of this package
220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
221
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.
224
225  Known booting configurations:
226
227     * 4x 256 MB (filling all slots) -- only "0.5 GB" reported.
228     * 2x 1 GB, slots 3/4 -- only "0.5 GB" reported.
229
230  Known failing configurations
231
232     * 2x 256 MB, slots 3/4
233     * 2x 256 MB, slots 1/2
234
235  On a JS20 SLOF wil always report 0.5 GB even if there is much more memory
236  available.
237
238  On a JS21 all memory configurations should work.
239
240
241 4.0 Submitting patches
242 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
243
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,
248 see [3] for details.
249
250
251 5.0 Coding style
252 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
253
254 New C code submitted to SLOF should follow the coding style guidelines
255 for the Linux kernel [4] with the following exceptions:
256
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.
260
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
263 3 space indentation.
264
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.
267
268
269 Documentation
270 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
271
272 [1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration)
273     Firmware: Core Requirements and Practices
274
275 [2] PAPR Standard, Power.org(TM) Standard for Power Architecture(R) Platform
276     Requirements (Workstation, Server), Version 2.4, December 7, 2009
277
278 [3] Developer Certificate of Origin Version 1.1
279     http://developercertificate.org/
280
281 [4] Linux kernel coding style
282     https://github.com/torvalds/linux/blob/master/Documentation/CodingStyle