qemu/roms/openbios/README

   1 Welcome to OpenBIOS
   2 -------------------
   3
   4 OpenBIOS is a free, portable implementation of IEEE 1275-1994
   5 (Open Firmware). Find detailed information about OpenBIOS at
   6 http://www.openbios.org/
   7
   8 What is OpenBIOS?
   9 -----------------
  10
  11 OpenBIOS can replace your system firmware (BIOS) partly or completely. It
  12 can also be used as a bootloader to create an Open Firmware compatible
  13 interface between legacy firmware and an operating system.
  14
  15 This is achieved by a modular concept that consists of a portable Forth
  16 kernel and three interfaces for user interaction, device initialization
  17 and client (operating system) control.
  18
  19 While far not all possible applications of OpenBIOS are implemented yet,
  20 a lot of functionality is already there. OpenBIOS can be used to enhance
  21 LinuxBIOS (http://www.linuxbios.org), or be booted from any multiboot
  22 capable bootloader to bring Open Firmware to your machine. OpenBIOS can
  23 also be used when an operating system is already running. It provides
  24 the needed OpenFirmware functionality to MOL (MacOnLinux) to boot MacOS
  25 9 and X on PPC machines, as well as Linux (all supported platforms)
  26
  27 OpenBIOS build options
  28 ---------------------
  29
  30    config/scripts/switch-arch <platform>  - build for specified platform
  31                                             Look in config/example for
  32                                             platforms.
  33
  34    make            - build all configured binaries
  35
  36    make run        - run unix example.
  37
  38
  39 How OpenBIOS works
  40 ------------------
  41
  42  The OpenBIOS forth core is split into a forth kernel written in portable
  43  C and a forth dictionary which operated on by the kernel.
  44
  45  When building the forth core, you get different versions of
  46  the forth kernel:
  47
  48  * a unix executable program
  49
  50    - to execute a forth dictionary from a file. This can be used for
  51      easily testing and developing OpenBIOS on a unix host.
  52
  53    - to create a dictionary file. Such a dictionary file sets up
  54      all of the forth language. Primitives are indexed to save relocations.
  55
  56      The default is to create a forth dictionary forth.dict from
  57      forth/start.fs. This file includes all of the basic forth language
  58      constructs from forth/bootstrap.fs and starts the interpreter.
  59
  60      To achieve this, the hosted unix version contains a basic set of
  61      forth words coded in C that allow creating a full dictionary.
  62
  63  * a varying number of target specific binaries. On x86 you can start
  64    openbios for example from GRUB or LinuxBIOS. They are all based on
  65    the same forth engine consisting of a dictionary scheduler, primitive
  66    words needed to build the forth environment, 2 stacks and a simple
  67    set of console functions. These binaries can not be started directly
  68    in the unix host environment.
  69
  70 Requirements
  71 ------------
  72  * gcc
  73  * gnu make
  74  * OpenBIOS FCode Utils
  75    Download with svn co svn://openbios.org/openbios/fcode-utils
  76  * grub or any other multiboot loader to run the multiboot
  77    binary "openbios.multiboot" with it's module "openbios-<platform>.dict"
  78  * xsltproc
  79
  80 Building & Usage
  81 ----------------
  82
  83  * make
  84
  85    this builds "openbios.multiboot", the standalone image and "openbios-unix",
  86    the hosted image. Additionally it creates a forth dictionary
  87    file from forth/start.fs. All generated files are written to
  88    the absolute directory held by the variable BUILDDIR, which defaults
  89    to obj-[platform]. Some compile time parameters can be tweaked in
  90    include/config.h
  91
  92  * use "openbios-unix" to create a forth dictionary on your own:
  93    $ obj-x86/openbios-unix -Iforth start.fs
  94    creates the file forth.dict from forth source forth/start.fs.
  95
  96  * use "openbios-unix" to run a created dictionary:
  97    $ obj-x86/openbios-unix obj-x86/openbios-unix.dict
  98    This is useful for testing
  99
 100  * booting openbios
 101    You can boot openbios i.e. in grub. Add the following lines to
 102    your menu.lst:
 103
 104     title openbios
 105       kernel (hd0,2)/boot/openbios.multiboot
 106       module (hd0,2)/boot/openbios-x86.dict
 107
 108    Note: change (hd0,2) to the partition you copied the openbios image and
 109    openbios-x86.dict to.
 110
 111    To boot OpenBIOS from LinuxBIOS/etherboot, you can either use
 112    "openbios-plain.elf" or "openbios-builtin.elf":
 113
 114    - openbios-plain.elf is the pure kernel that loads the dictionary from a
 115      hardcoded address in flash memory (0xfffe0000)
 116
 117    - openbios-builtin.elf also includes the dictionary directly so that it
 118      can be easily used from etherboot or the LinuxBIOS builtin ELF
 119      loader without taking care of the dictionary
 120
 121 CREDITS
 122 -------
 123 OpenBIOS was developed by Stefan Reinauer, Samuel Rydh and Patrick Mauritz.
 124 The OpenBIOS IDE driver was written by Jens Axboe.
 125 For license details on this piece of software, see Documentation/COPYING.
 126
 127
 128 If you have patches, questions, comments, feel free to contact the OpenBIOS
 129 mailinglist.
 130
 131 Regards,
 132      the OpenBIOS team