kernel/README

   1
   2 Welcome to the OpenBIOS forth core "begin again".
   3
   4 Find more information about OpenBIOS at http://www.openbios.org/
   5
   6 This program was written by Patrick Mauritz and Stefan Reinauer in 2003
   7 For license details on this piece of software, check Documentation/COPYING.
   8
   9 How OpenBIOS works
  10 ------------------
  11
  12  The OpenBIOS forth core is split into a forth kernel written in C
  13  and a forth dictionary which operated on by the kernel.
  14
  15  When building the forth core, you get different versions of
  16  the forth kernel:
  17
  18  * a "hosted" unix binary. This binary can be used on a unix system
  19
  20    - to execute a forth dictionary from a file. This can be used for
  21      testing openbios code in a development environment on a unix host.
  22
  23    - to create a dictionary file. Such a dictionary file sets up
  24      all of the forth language. Primitives are indexed to save relocations.
  25
  26      The default is to create a forth dictionary forth.dict from
  27      forth/start.fs. This file includes all of the basic forth language
  28      constructs from forth/bootstrap.fs and starts the interpreter.
  29
  30      To achieve this, the hosted unix version contains a basic set of
  31      forth words coded in C that allow creating a full dictionary.
  32
  33  * a varying number of target specific binaries. On x86 you can start
  34    openbios for example from GRUB or LinuxBIOS. They are all based on
  35    the same forth engine consisting of a dictionary scheduler, primitive
  36    words needed to build the forth environment, 2 stacks and a simple
  37    set of console functions. These binaries can not be started directly
  38    in the unix host environment.
  39
  40 Requirements
  41 ------------
  42  * gcc
  43  * grub or any other multiboot loader to run the standalone
  44    binary "openbios.multiboot"
  45
  46 Building & Usage
  47 ----------------
  48
  49  * make
  50
  51    this builds "openbios.multiboot", the standalone image and "unix",
  52    the hosted image. Additionally it creates a forth dictionary
  53    file from forth/start.fs. All generated files are written to
  54    the absolute directory held by the variable BUILDDIR, which defaults
  55    to obj-[platform]. Some compile time parameters can be tweaked in
  56    include/config.h
  57
  58  * use "unix" to create a forth dictionary on your own:
  59    $ ./unix -Iforth start.fs
  60    creates the file forth.dict from forth source forth/start.fs.
  61
  62  * use "unix" to run a created dictionary:
  63    $ ./unix forth.dict
  64    This is useful for testing
  65
  66  * booting openbios
  67    You can boot openbios i.e. in grub. Add the following lines to
  68    your menu.lst:
  69
  70     title openbios
  71       kernel (hd0,2)/boot/openbios.multiboot
  72       module (hd0,2)/boot/openfirmware.dict
  73
  74    Note: change (hd0,2) to the partition you copied openbios and
  75    forth.dict to.
  76
  77    To boot OpenBIOS from LinuxBIOS/etherboot, you can either use
  78    "openbios" or "openbios.full":
  79
  80    - openbios is the pure kernel that loads the dictionary from a
  81      hardcoded address in flash memory (0xfffe0000)
  82
  83    - openbios.full also includes the dictionary directly so that it
  84      can be easily used from etherboot or the LinuxBIOS builtin ELF
  85      loader without taking care of the dictionary
  86
  87
  88 Comments are welcome.
  89
  90      OpenBIOS team
  91
  92 ------------------------------------------------------------------------
  93 tag: README for openbios forth core