--- qemu/roms/SLOF/README 2018/04/24 18:59:08 1.1.1.1 +++ qemu/roms/SLOF/README 2018/04/24 19:44:10 1.1.1.2 @@ -1,22 +1,25 @@ Slimline Open Firmware - SLOF -Copyright (C) 2004, 2008 IBM Corporation +Copyright (C) 2004, 2012 IBM Corporation Index ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1.0 Introduction to Open Firmware -1.1 Build process -2.0 Extension +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 Open Firmware + +1.0 Introduction to Slimline Open Firmware ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -The IEEE Standard 1275-1994 [1], Standard for Boot (Initialization Configuration) -Firmware, Core Requirements and Practices, is 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) +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 @@ -24,22 +27,110 @@ with powerful scripting and debugging su 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 +"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 -1.1 Build process +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 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. +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 @@ -55,7 +146,7 @@ Forth primitive 'dup' dup ( a -- a a) \ Duplicate top of stack element -prim.in: +prim.in: cod(DUP) prim.code: @@ -73,10 +164,9 @@ Without going into detail, it can be see 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 vector for reset and all kinds of exceptions -will be part of the image. Additionally a secondary boot-loader +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. @@ -93,7 +183,7 @@ CPUs, the system memory and all the buse itself. -2.0 Extension +2.4 Extending the Forth engine ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ In the following paragraphs it will be shown how to add @@ -104,7 +194,7 @@ the specific needs of different hardware To add primitives: - + For a new primitive, following steps have to be done: + Definition of primitive name in .in @@ -145,9 +235,12 @@ To add primitives: On a JS21 all memory configurations should work. + Documentation +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ [1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration) - Firmware: Core Requierements and Practices + 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