.github/workflows: add release.yml for generating an OpenBIOS release
[openbios.git] / 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 the file 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