README - SLOF - Git at Google

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