![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Qemu by Fabrice Bellard] / qemu / roms / SLOF|
Return to README CVS log | Up to [Qemu by Fabrice Bellard] / qemu / roms / SLOF |
1.1 root 1: Slimline Open Firmware - SLOF
2:
1.1.1.2 ! root 3: Copyright (C) 2004, 2012 IBM Corporation
1.1 root 4:
5:
6: Index
7: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
8: 1.0 Introduction to Open Firmware
1.1.1.2 ! root 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
1.1 root 13: 3.0 Limitations
14:
1.1.1.2 ! root 15:
! 16: 1.0 Introduction to Slimline Open Firmware
1.1 root 17: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
18:
1.1.1.2 ! root 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)
1.1 root 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
1.1.1.2 ! root 30: "device tree". This device tree supports multiple interconnected system
! 31: buses and offers a framework for "plug and play"-type auto configuration
1.1 root 32: across different buses. It was designed to support a variety of different
33: processor Instruction Set Architectures (ISAs) and buses.
34:
35: The full documentation of this Standard can be found in [1].
36:
1.1.1.2 ! root 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
! 39: LICENSE for details.
! 40:
! 41:
! 42: 2.0 Using the source code
! 43: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
! 44:
! 45: This version of SLOF currently supports two major platforms ("boards" in the
! 46: SLOF jargon):
! 47:
! 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
1.1 root 50:
1.1.1.2 ! root 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
! 54: your target system.
! 55:
! 56:
! 57: 2.1 Build process
! 58: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
! 59:
! 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)
! 65:
! 66: - set the CROSS variable
! 67: - something like export CROSS="powerpc64-unknown-linux-gnu-"
! 68: when using a cross compiler
! 69: or
! 70: - export CROSS=""
! 71: when using a native compiler
! 72:
! 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
! 76: required:
! 77: - cd other-licence/x86emu/
! 78: - ./x86emu_download.sh # this downloads the x86 emulator sources
! 79: - cd -
! 80:
! 81: - Now you can compile the firmware.
! 82: - For building SLOF for JS20, JS21 or the PowerStation, type:
! 83: make js2x
! 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:
! 87: make qemu
! 88: The resulting ROM image "boot_rom.bin" can then be found in the main
! 89: directory.
! 90:
! 91:
! 92: 2.2 Overview of the source code
! 93: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
! 94:
! 95: The SLOF source code is structured into the following directories:
! 96:
! 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.)
! 102:
! 103: - slof : The code for the Open Firmware environment, including the Forth
! 104: engine (called "Paflof") and the necessary Forth source files.
! 105:
! 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.
! 109:
! 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).
! 115:
! 116: - drivers : Driver code for various hardware (currently only NIC drivers).
! 117:
! 118: - lib : Libraries with common code.
! 119:
! 120: - romfs / tools : Tools that are required for building the firmware image.
! 121:
! 122: - board-* : The board directories contain all the code that is unique to the
! 123: corresponding platform.
! 124:
! 125:
! 126: 2.3 The Open Firmware engine
1.1 root 127: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
128:
129: Open Firmware (OF) is based on the programming language Forth.
1.1.1.2 ! root 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.
1.1 root 134:
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
141: system.
142:
143: Example:
144: Forth primitive 'dup'
145:
146: dup ( a -- a a) \ Duplicate top of stack element
147:
148:
1.1.1.2 ! root 149: prim.in:
1.1 root 150: cod(DUP)
151:
152: prim.code:
153: PRIM(DUP) cell x = TOS; PUSH; TOS = x; MIRP
154:
155: Generated code:
156:
157: static cell xt_DUP[] = { { .a = xt_DOTICK }, { .c = "\000\003DUP" },
158: { .a = &&code_DUP }, };
159:
160: code_DUP: { asm("#### " "DUP"); void *w = (cfa = (++ip)->a)->a;
161: cell x = (*dp); dp++; (*dp) = x; goto *w; }
162:
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
165: stack.
166:
1.1.1.2 ! root 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
1.1 root 170: or any other client application can be bound to the code as payload,
171: e.g. diagnostics and test programs.
172:
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.
179:
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
183: itself.
184:
185:
1.1.1.2 ! root 186: 2.4 Extending the Forth engine
1.1 root 187: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
188:
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.
194:
195:
196: To add primitives:
1.1.1.2 ! root 197:
1.1 root 198: For a new primitive, following steps have to be done:
199:
200: + Definition of primitive name in <arch>.in
201: - cod(ABC) defines primitive ABC
202:
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
208:
209: + Definition of the primitives effects in <arch>.code
210: - PRIM(ABC) ... MIRP
211:
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.
215:
216:
217: 3.0 Limitations of this package
218: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
219:
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.
222:
223: Known booting configurations:
224:
225: * 4x 256 MB (filling all slots) -- only "0.5 GB" reported.
226: * 2x 1 GB, slots 3/4 -- only "0.5 GB" reported.
227:
228: Known failing configurations
229:
230: * 2x 256 MB, slots 3/4
231: * 2x 256 MB, slots 1/2
232:
233: On a JS20 SLOF wil always report 0.5 GB even if there is much more memory
234: available.
235:
236: On a JS21 all memory configurations should work.
237:
1.1.1.2 ! root 238:
1.1 root 239: Documentation
240: +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
241:
242: [1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration)
1.1.1.2 ! root 243: Firmware: Core Requirements and Practices
1.1 root 244:
1.1.1.2 ! root 245: [2] PAPR Standard, Power.org(TM) Standard for Power Architecture(R) Platform
! 246: Requirements (Workstation, Server), Version 2.4, December 7, 2009
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.