Updated the documentation

Now the documentation reflect that we support KVM/QEMU, too. Also added a
short section about the source code structure.

Signed-off-by: Thomas Huth <thuth@linux.vnet.ibm.com>

1 files changed, 116 insertions, 23 deletions

diff --git a/README b/README
index c4fc677..58e9294 100644
--- a/README
+++ b/README
@@ -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 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
+"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.
 
-1.1 Build process
+
+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 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 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 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 buses as well as the serial port
 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 and architectures.
 
 
 To add primitives:
-   
+
    For a new primitive, following steps have to be done:
 
    + Definition of primitive name in <arch>.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