qemu/roms/SLOF/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
  15
  16 1.0 Introduction to Slimline Open Firmware
  17 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  18
  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.
  34
  35 The full documentation of this Standard can be found in [1].
  36
  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
  50
  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
 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 128
 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.
 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
 149 prim.in:
 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
 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.
 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
 186 2.4 Extending the Forth engine
 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:
 197
 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
 238
 239 Documentation
 240 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 241
 242 [1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration)
 243     Firmware: Core Requirements and Practices
 244
 245 [2] PAPR Standard, Power.org(TM) Standard for Power Architecture(R) Platform
 246     Requirements (Workstation, Server), Version 2.4, December 7, 2009