X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=qemu%2Froms%2FSLOF%2FREADME;fp=qemu%2Froms%2FSLOF%2FREADME;h=58e929427722a1722ce11ae3e19b863618f9055b;hb=e44e3482bdb4d0ebde2d8b41830ac2cdb07948fb;hp=0000000000000000000000000000000000000000;hpb=9ca8dbcc65cfc63d6f5ef3312a33184e1d726e00;p=kvmfornfv.git diff --git a/qemu/roms/SLOF/README b/qemu/roms/SLOF/README new file mode 100644 index 000000000..58e929427 --- /dev/null +++ b/qemu/roms/SLOF/README @@ -0,0 +1,246 @@ +Slimline Open Firmware - SLOF + +Copyright (C) 2004, 2012 IBM Corporation + + +Index +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +1.0 Introduction to Open Firmware +2.0 Using the source code +2.1 Build process +2.2 Overview of the source code +2.4 Extending the Forth engine +3.0 Limitations + + +1.0 Introduction to Slimline Open Firmware +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The IEEE Standard 1275-1994 [1], Standard for Boot (Initialization Configura- +tion) Firmware, Core Requirements and Practices, was the first non-proprietary +open standard for boot firmware that is usable on different processors and +buses. Firmware which complies with this standard (also known as Open Firmware) +includes a processor-independent device interface that allows add-in devices +to identify itself and to supply a single boot driver that can be used, +unchanged, on any CPU. In addition, Open Firmware includes a user interface +with powerful scripting and debugging support and a client interface that +allows an operating system and its loaders to use Open Firmware services +during the configuration and initialization process. Open Firmware stores +information about the hardware in a tree structure called the +"device tree". This device tree supports multiple interconnected system +buses and offers a framework for "plug and play"-type auto configuration +across different buses. It was designed to support a variety of different +processor Instruction Set Architectures (ISAs) and buses. + +The full documentation of this Standard can be found in [1]. + +Slimline Open Firmware (SLOF) is now an implementation of the IEEE 1275 +standard that is available under a BSD-style license. Please see the file +LICENSE for details. + + +2.0 Using the source code +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +This version of SLOF currently supports two major platforms ("boards" in the +SLOF jargon): + +- js2x : The PowerPC 970 based systems JS20, JS21 and the PowerStation +- qemu : Used as partition firmware for pseries machines running on KVM/QEMU + +The following sections will give you a short introduction about how to compile +and improve the source code. +Please read the file INSTALL for details about how to install the firmware on +your target system. + + +2.1 Build process +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + To build SLOF you need: + - Recent GNU tools, configured for powerpc64-linux + - GCC: 3.3.3 and newer are known to work + - Binutils: use a version as new as possible + - Subversion (for retrieving the x86 emulator) + + - set the CROSS variable + - something like export CROSS="powerpc64-unknown-linux-gnu-" + when using a cross compiler + or + - export CROSS="" + when using a native compiler + + - For building SLOF for the PowerStation, it is necessary to + download a x86 emulator which is used to execute the BIOS + of VGA card; to download the x86 emulator following steps are + required: + - cd other-licence/x86emu/ + - ./x86emu_download.sh # this downloads the x86 emulator sources + - cd - + + - Now you can compile the firmware. + - For building SLOF for JS20, JS21 or the PowerStation, type: + make js2x + You also might want to build the takeover executable by typing: + make -C board-js2x takeover + - For building SLOF as the partition firmware for KVM/QEMU, type: + make qemu + The resulting ROM image "boot_rom.bin" can then be found in the main + directory. + + +2.2 Overview of the source code +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The SLOF source code is structured into the following directories: + +- llfw : The Low-Level Firmware - this part is platform-specific firmware + that is responsible to boot the system from the reset vector to a + state where it is possible to run the Open Firmware Forth engine + (i.e. it sets up the necessary CPU registers, intializes the memory, + does some board-specific hardware configuration, etc.) + +- slof : The code for the Open Firmware environment, including the Forth + engine (called "Paflof") and the necessary Forth source files. + +- rtas : The Run-Time Abstraction Services, which can be used by the operating + system to access certain hardware without knowing the details. + See [2] for a description of these services. + +- clients : Code that runs on top of the Open Firmware client interface. + Currently, there are two clients: + - net-snk : Used for network bootloading (a TFTP client) + - takeover : A separate binary that can be used for bootstrapping + SLOF on a JS20/JS21 (see FlashingSLOF.pdf for details). + +- drivers : Driver code for various hardware (currently only NIC drivers). + +- lib : Libraries with common code. + +- romfs / tools : Tools that are required for building the firmware image. + +- board-* : The board directories contain all the code that is unique to the + corresponding platform. + + +2.3 The Open Firmware engine +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Open Firmware (OF) is based on the programming language Forth. +SLOF use Paflof as the Forth engine, which was originally developed by +Segher Boessenkool. Most parts of the Forth engine are implemented in C, by +using GNU extensions of ANSI C, (e.g. assigned goto, often misnamed "computed +goto"), resulting in a very efficient yet still quite portable engine. + +The basic Forth words, so-called primitives, are implemented with +a set of C macros. A set of .in and .code files are provided, which +define the semantic of the Forth primitives. A Perl script translates +these files into valid C code, which will be compiled into the Forth engine. +The complete Forth system composes of the basic Forth primitives and +a set of Forth words, which are compiled during the start of the Forth +system. + +Example: +Forth primitive 'dup' + + dup ( a -- a a) \ Duplicate top of stack element + + +prim.in: + cod(DUP) + +prim.code: + PRIM(DUP) cell x = TOS; PUSH; TOS = x; MIRP + +Generated code: + +static cell xt_DUP[] = { { .a = xt_DOTICK }, { .c = "\000\003DUP" }, + { .a = &&code_DUP }, }; + +code_DUP: { asm("#### " "DUP"); void *w = (cfa = (++ip)->a)->a; + cell x = (*dp); dp++; (*dp) = x; goto *w; } + +Without going into detail, it can be seen, that the data stack is +implemented in C as an array of cells, where dp is the pointer to the top of +stack. + +For the implementation of the Open Firmware, most of the code is added as +Forth code and bound to the engine. Also the system vectors for all kinds of +exceptions will be part of the image. Additionally a secondary boot-loader +or any other client application can be bound to the code as payload, +e.g. diagnostics and test programs. + +The Open Firmware image will be put together by the build +process, with a loader at the start of the image. This loader +is called by Low Level Firmware and loads at boot time the Open +Firmware to it's location in memory (see 1.3 Load process). Additionally +a secondary boot loader or any other client application can be bound +to the code as payload. + +The Low Level Firmware (LLFW) is responsible for setting up the +system in an initial state. This task includes the setup of the +CPUs, the system memory and all the buses as well as the serial port +itself. + + +2.4 Extending the Forth engine +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In the following paragraphs it will be shown how to add +new primitive words (i.e., words implemented not by building +pre-existing Forth words together, but instead implemented in +C or assembler). With this, it is possible to adapt SLOF to +the specific needs of different hardware and architectures. + + +To add primitives: + + For a new primitive, following steps have to be done: + + + Definition of primitive name in .in + - cod(ABC) defines primitive ABC + + You can also use the following in a .in file, see existing + code for how to use these: + - con(ABC) defines constant ABC + - col(ABC) defines colon definition ABC + - dfr(ABC) defines defer definition ABC + + + Definition of the primitives effects in .code + - PRIM(ABC) ... MIRP + + The code for the primitive body is any C-code. With + the macros of prim.code the data and return stack of + the Forth engine can be appropriately manipulated. + + +3.0 Limitations of this package +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + On a JS20 the memory setup is very static and therefore there are + only very few combinations of memory DIMM placement actually work. + + Known booting configurations: + + * 4x 256 MB (filling all slots) -- only "0.5 GB" reported. + * 2x 1 GB, slots 3/4 -- only "0.5 GB" reported. + + Known failing configurations + + * 2x 256 MB, slots 3/4 + * 2x 256 MB, slots 1/2 + + On a JS20 SLOF wil always report 0.5 GB even if there is much more memory + available. + + On a JS21 all memory configurations should work. + + +Documentation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration) + Firmware: Core Requirements and Practices + +[2] PAPR Standard, Power.org(TM) Standard for Power Architecture(R) Platform + Requirements (Workstation, Server), Version 2.4, December 7, 2009