Welcome to OpenBIOS
-------------------

OpenBIOS is a free, portable implementation of IEEE 1275-1994 
(Open Firmware). Find detailed information about OpenBIOS at 
http://www.openbios.org/

What is OpenBIOS?
-----------------

OpenBIOS can replace your system firmware (BIOS) partly or completely. It
can also be used as a bootloader to create an Open Firmware compatible
interface between legacy firmware and an operating system.

This is achieved by a modular concept that consists of a portable Forth
kernel and three interfaces for user interaction, device initialization
and client (operating system) control.

While far not all possible applications of OpenBIOS are implemented yet,
a lot of functionality is already there. OpenBIOS can be used as a payload
for coreboot (http://www.coreboot.org), or be booted from any multiboot
capable bootloader to bring Open Firmware to your machine. OpenBIOS can
also be used when an operating system is already running. It provides
the needed OpenFirmware functionality to MOL (MacOnLinux) to boot MacOS
9 and X on PPC machines, as well as Linux (all supported platforms)

OpenBIOS build options
---------------------

   config/scripts/switch-arch <platform>  - build for specified platform
   					    Look in config/example for
					    platforms.

   make            - build all configured binaries

   make run        - run unix example.

   
How OpenBIOS works
------------------

 The OpenBIOS forth core is split into a forth kernel written in portable 
 C and a forth dictionary which operated on by the kernel.

 When building the forth core, you get different versions of
 the forth kernel: 

 * a unix executable program

   - to execute a forth dictionary from a file. This can be used for
     easily testing and developing OpenBIOS on a unix host.

   - to create a dictionary file. Such a dictionary file sets up
     all of the forth language. Primitives are indexed to save relocations.

     The default is to create a forth dictionary forth.dict from
     forth/start.fs. This file includes all of the basic forth language
     constructs from forth/bootstrap.fs and starts the interpreter.

     To achieve this, the hosted unix version contains a basic set of
     forth words coded in C that allow creating a full dictionary.

 * a varying number of target specific binaries. On x86 you can start 
   openbios for example from GRUB or LinuxBIOS. They are all based on
   the same forth engine consisting of a dictionary scheduler, primitive 
   words needed to build the forth environment, 2 stacks and a simple 
   set of console functions. These binaries can not be started directly
   in the unix host environment.

Requirements
------------
 * gcc
 * gnu make
 * OpenBIOS FCode Utils
   Download with svn co svn://openbios.org/openbios/fcode-utils
 * grub or any other multiboot loader to run the multiboot
   binary "openbios.multiboot" with it's module "openbios-<platform>.dict"
 * xsltproc
 
Building & Usage
----------------

 * make

   this builds "openbios.multiboot", the standalone image and "openbios-unix", 
   the hosted image. Additionally it creates a forth dictionary
   file from forth/start.fs. All generated files are written to 
   the absolute directory held by the variable BUILDDIR, which defaults
   to obj-[platform]. Some compile time parameters can be tweaked in
   include/config.h
   
 * use "openbios-unix" to create a forth dictionary on your own:
   $ obj-x86/openbios-unix -Iforth start.fs
   creates the file forth.dict from forth source forth/start.fs.

 * use "openbios-unix" to run a created dictionary: 
   $ obj-x86/openbios-unix obj-x86/openbios-unix.dict
   This is useful for testing
 
 * booting openbios
   You can boot openbios i.e. in grub. Add the following lines to
   your menu.lst:

    title openbios
      kernel (hd0,2)/boot/openbios.multiboot
      module (hd0,2)/boot/openbios-x86.dict

   Note: change (hd0,2) to the partition you copied the openbios image and
   openbios-x86.dict to.

   To boot OpenBIOS from LinuxBIOS/etherboot, you can either use
   "openbios-plain.elf" or "openbios-builtin.elf":

   - openbios-plain.elf is the pure kernel that loads the dictionary from a 
     hardcoded address in flash memory (0xfffe0000)

   - openbios-builtin.elf also includes the dictionary directly so that it
     can be easily used from etherboot or the LinuxBIOS builtin ELF
     loader without taking care of the dictionary

CREDITS
-------
OpenBIOS was developed by Stefan Reinauer, Samuel Rydh and Patrick Mauritz.
The OpenBIOS IDE driver was written by Jens Axboe.
For license details on this piece of software, see the file COPYING.


If you have patches, questions, comments, feel free to contact the OpenBIOS
mailinglist.

Regards,
     the OpenBIOS team