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 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