diff options
Diffstat (limited to 'Documentation/website')
32 files changed, 2839 insertions, 0 deletions
diff --git a/Documentation/website/.gitignore b/Documentation/website/.gitignore new file mode 100644 index 0000000..69fa449 --- /dev/null +++ b/Documentation/website/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/Documentation/website/Adding_words_to_openbios.md b/Documentation/website/Adding_words_to_openbios.md new file mode 100644 index 0000000..59842d5 --- /dev/null +++ b/Documentation/website/Adding_words_to_openbios.md @@ -0,0 +1,151 @@ +# Adding words to OpenBIOS +How to add “words” to the OpenBIOS Dictionary using the C language. + +In this example, we are going to implement a forth “word” in C. There +are two arrays that need to be looked at. One is located in the file +openbios-devel/kernel/bootstrap.c. The other array is located in the +file openbios-devel/kernel/forth.c. The two arrays are used to map a C +function to a forth word. + +The array in bootstrap.c is where the name of the forth word would go. +The array in forth.c is where the corresponding C function would go. +When adding to these arrays, make sure to add at the end of the list. +This ensures everything continues to run smoothly. + +Here is an example on adding to the dictionary. Say you want to add a +word called dog. You can define the C function like this: + +``` +static void dog(void) +{ + printk(“bark bark!”); +} +``` + +Add this function to a .c file. Knowing which file to pick can involve a +lot of trial and error. In this example, we will use the file +openbios-devel/kernel/forth.c. Be sure to include the static keyword +before in the function declaration, or OpenBIOS won’t build +successfully. + +Now we add the word dog to the end of the forth word list. Open the file +bootstrap.c, then find the array called wordnames. When adding the word +dog, be sure the name of the word is surrounded in double quotes. Here +is how the array should look: + +``` +/* the word names are used to generate the prim words in the + dictionary. This is done by the C written interpreter. +*/ + +static const char *wordnames[] = { + "(semis)", "", "(lit)", "", "", "", "", "(do)", "(?do)", "(loop)", + "(+loop)", "", "", "", "dup", "2dup", "?dup", "over", "2over", "pick", "drop", + "2drop", "nip", "roll", "rot", "-rot", "swap", "2swap", ">r", "r>", + "r@", "depth", "depth!", "rdepth", "rdepth!", "+", "-", "*", "u*", + "mu/mod", "abs", "negate", "max", "min", "lshift", "rshift", ">>a", + "and", "or", "xor", "invert", "d+", "d-", "m*", "um*", "@", "c@", + "w@", "l@", "!", "+!", "c!", "w!", "l!", "=", ">", "<", "u>", "u<", + "sp@", "move", "fill", "(emit)", "(key?)", "(key)", "execute", + "here", "here!", "dobranch", "do?branch", "unaligned-w@", + "unaligned-w!", "unaligned-l@", "unaligned-l!", "ioc@", "iow@", + "iol@", "ioc!", "iow!", "iol!", "i", "j", "call", "sys-debug", + "$include", "$encode-file", "(debug", "(debug-off)", “dog” // <------- insert here +}; +``` + +Next we add the C function name to the end of the function list. Open +the file forth.c and add dog (no quotes this time) to the end of the +list. You may want to add a comment to the right indicating the word +this c function corresponds to, but this isn’t necessary. + +```C + sysdebug, /* sys-debug */ + do_include, /* $include */ + do_encode_file, /* $encode-file */ + do_debug_xt, /* (debug */ + do_debug_off, /* (debug-off) */ + dog /* dog */ //<-------- insert here +}; +``` + +Now you should be ready to build OpenBIOS. Go to the shell and set the +current directory to the root level of openbios-devel folder: + + cd openbios-devel + +Set the architure you wish to build openbios for (amd64 is used in this +example): + + ./config/scripts/switch-arch amd64 + +Then start building OpenBIOS: + + make build-verbose + +Once these commands are done, you need to be able to execute OpenBIOS. +In this example we will be using the unix program version of OpenBIOS. + +We run the program like this: + + ./obj-amd64/openbios-unix ./obj-amd64/openbios-unix.dict + +We should then be greeted by the OpenBIOS Banner: + + Welcome to OpenBIOS v1.0 built on Mar 9 2010 21:06 + Type 'help' for detailed information + + [unix] Booting default not supported. + + 0 > + +Type dog at the prompt and see what it says: + + 0 > dog + bark bark! ok + 0 > + +Congratulations, you have just taken your first step to improving +OpenBIOS. + +## Advanced example: + +Suppose you want to make a forth word that would give you access to a +PowerPC CPU register. To do this you can use inline assembly language to +access the register from C. Then use the `bind_func()` function to make +this C function available to forth. + +In this example we implement a word called fpscr@ that will push the +value of the FPSCR onto the top of the stack. + +In the file arch/ppc/qemu/init.c add this code right above the +`arch_of_init()` function: + +```C + static void get_fpscr(void) + { + asm volatile("mffs 0"); + asm volatile("stfd 0, 40(1)"); + uint32_t return_value; + asm volatile("lwz %0, 44(1)" : "=r"(return_value)); + PUSH(return_value); + } +``` + +Then to make this function available from forth we add this line to the +end of the `arch_of_init()` function in the same file: + +```C +bind_func("fpscr@", get_fpscr); +``` + +To build this example you would have to issue this command: + + ./config/scripts/switch-arch ppc && make build-verbose + +The resulting file can be used with QEMU like this: + + qemu-system-ppc -bios `<path to openbios folder>`/obj-ppc/openbios-qemu.elf.nostrip + +Entering fpscr@ in the OpenBIOS prompt would return the value to the +fpscr. diff --git a/Documentation/website/BeginAgain.md b/Documentation/website/BeginAgain.md new file mode 100644 index 0000000..47f6954 --- /dev/null +++ b/Documentation/website/BeginAgain.md @@ -0,0 +1,117 @@ +# What is BeginAgain? + +BeginAgain is the Forth kernel, basically the heart of OpenBIOS. + +Right after the system is far enough to execute any C code, this kernel +will take over control and execute the forth code part of OpenBIOS. + +BeginAgain supports the Forth language command group of IEEE 1275-1994 +and passes the Hayes ANS forth compliance test. + +# How does BeginAgain work? + +The OpenBIOS forth core "BeginAgain" is split into a forth kernel +written in C and a forth dictionary which operated on by the kernel. + +BeginAgain's approach is indirect threading. Forth words are compiled to +execution tokens (pointers to the words dictionary entries). Only the +prim words (minimal language support) are available as native C code. +When building the forth core, you get different versions of the forth +kernel: + +- a "hosted" unix binary. This binary can be used on a unix system: + - to execute a forth dictionary from a file. This can be used for + testing openbios code in a development environment 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 coreboot. 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. + +# Building and Using BeginAgain + +## Requirements + +- gcc +- grub or any other multiboot loader to run the standalone binary + "openbios.multiboot" + +## Building and Usage + +- make + +this builds "openbios.multiboot", the standalone image and "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 "unix" to create a forth dictionary on your own: + + $ ./unix -Iforth start.fs + +creates the file forth.dict from forth source forth/start.fs. + +- use "unix" to run a created dictionary: + + $ ./unix forth.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/openfirmware.dict + +Note: change (hd0,2) to the partition you copied openbios and forth.dict +to. + +To boot OpenBIOS from coreboot/etherboot, you can either use "openbios" +or "openbios.full": + +- openbios is the pure kernel that loads the dictionary from a hardcoded + address in flash memory (0xfffe0000) +- openbios.full also includes the dictionary directly so that it can be + easily used from etherboot or the coreboot builtin ELF loader without + taking care of the dictionary + +# Dictionary Format + +The dictionary is a linked list of forth word definitions. Each forth +word in this list looks like the following: name length of name in +bytes + 0x80 align with 0's flags (bit 7 set) LFA CFA PFA + +When the forth interpreter looks for a certain word, it reads the +variable last that always points to the last defined word and iterates +over the list until it finds an appropriate word. + +# Glossary + +## Dictionary + +- LFA == link field address (backlink) +- CFA == code field address ("word type") +- PFA == program field address (definitions) + +## Forth Engine + +- TIB == text input buffer +- inner interpreter: interprets dictionary, does threading +- outer interpreter: "user" interpreter, reads forth words from user. diff --git a/Documentation/website/Bindings.md b/Documentation/website/Bindings.md new file mode 100644 index 0000000..f96366b --- /dev/null +++ b/Documentation/website/Bindings.md @@ -0,0 +1,65 @@ +# Bindings + +## Bindings and Supplements for Bus Systems + +- [PCI - Approved Version + 2.1](http://www.openbios.org/data/docs/bus.pci.pdf) +- [USB 1.0](http://www.openbios.org/data/docs/bus.usb.pdf) +- [ISA - Draft 0.4](http://www.openbios.org/data/docs/bus.isa.pdf) +- [PC-Card](http://www.openbios.org/data/docs/bus.pccard.pdf) + +## Bindings and Supplements for CPU Architectures + +- [Open Firmware 64bit + extensions](http://www.openbios.org/data/docs/12756d5.ps) +- [ARM bindings](http://www.openbios.org/data/docs/arm0_3d.pdf) +- [PPC bindings](http://www.openbios.org/data/docs/ppc-2_1.ps) +- [PPC PREP bindings](http://www.openbios.org/data/docs/PREP.ps) +- [PPC CHRP bindings](http://www.openbios.org/data/docs/CHRP.ps) +- [Sparc 32bit Supplement - IEEE 1754 + ISA](http://www.openbios.org/data/docs/12751d1a.pdf) + +## Device Bindings + +- [8042](http://www.openbios.org/data/docs/8042-1_0d.ps) - ISA + Keyboard/Mouse Controller +- [Audio](http://www.openbios.org/data/docs/audio-1_0d.ps) - ISA Audio +- [Floppy](http://www.openbios.org/data/docs/fdc-1_0d.ps) - ISA Floppy + Controller +- [ISA DMA](http://www.openbios.org/data/docs/isa-dma-1_0d.ps) - ISA DMA + Controller +- [ISA PIC](http://www.openbios.org/data/docs/isa-pic-1_1d.ps) - ISA + Interrupt Controller +- [Linear Framebuffer](http://www.openbios.org/data/docs/lfb-1_0d.ps) +- [Parallel](http://www.openbios.org/data/docs/parallel-1_0d.ps) - ISA + Parallel Port +- [Serial](http://www.openbios.org/data/docs/serial-1_0d.ps) - ISA + Serial Port +- [VGA](http://www.openbios.org/data/docs/vga-1_0d.ps) - VGA Display + +## Recommended Practice + +- [16 Color Text + Extension](http://www.openbios.org/data/docs/rec.16color.d12.pdf) - + Draft 1.2 +- [8 Bit Graphics + Extension](http://www.openbios.org/data/docs/rec.8bgraph.d12.pdf) - + Draft 1.2 +- [Device Support + Extensions](http://www.openbios.org/data/docs/rec.dse.app10.pdf) - + Approved Version 1.0 +- [Generic + Names](http://www.openbios.org/data/docs/rec.gennames.app14.pdf) - + Approved Version 1.4 +- [Interrupt + Mapping](http://www.openbios.org/data/docs/rec.intmap.d09.pdf) - Draft + 0.9 +- [Interposition](http://www.openbios.org/data/docs/rec.intpos.d02.pdf) - + Draft 0.2 +- [SCSI-3 Parallel + Interface](http://www.openbios.org/data/docs/rec.scsi3pi.10.pdf) - + Version 1.0 - bug: last page first!! +- [TFTP Booting + Extension](http://www.openbios.org/data/docs/rec.tftp.10.pdf) - + Version 1.0 +- [dma-ranges](http://playground.sun.com/1275/proposals/Closed/Accepted/410-it.txt) diff --git a/Documentation/website/Building_OFW_for_ARM.md b/Documentation/website/Building_OFW_for_ARM.md new file mode 100644 index 0000000..58b742a --- /dev/null +++ b/Documentation/website/Building_OFW_for_ARM.md @@ -0,0 +1,76 @@ +# Building OFW for ARM +This page tells how to build Open Firmware for an ARM target system. + +## Host System Requirements + +During the Open Firmware build process, the Forth system inside OFW is +executed several times to extend itself. Those steps must run on the +same CPU instruction set (in this case ARM) as the final target. So you +must build OFW either on an ARM computer or by using an ARM instruction +set emulator running on some other computer. +[QEMU](http://wiki.qemu.org/) works well for this purpose. + +### Compiler Setup for Native ARM Host + +To compile on an ARM host, you need Linux on that host, along with the +GNU toolchain (GCC), GNU make, and the Subversion version control +system. + +### Compiler Setup for x86 Host + +To compile on an x86 host, you need everything listed for the native +host (Linux, GNU toolchain, GNU make, and Subversion), plus QEMU. + +Note that the GNU toolchain that you need is the native x86 one, not an +ARM cross-toolchain. OFW uses its own built-in ARM assembler. The native +x86 toolchain is needed for the one-time step of compiling a small +interface program that lets the OFW builder operate under Linux. It +would be possible to eliminate that need by distributing a precompiled +binary of that interface program, but in practice, most developers +already have the native x86 toolchain already installed, so requiring it +isn't a problem (as opposed to cross-toolchains, which can be a serious +hassle to set up correctly). + +To install QEMU: + +- Debian: sudo apt-get install qemu +- Ubuntu 8.04 (Hardy): sudo apt-get install qemu +- Ubuntu 9.10 (Karmic): sudo apt-get install qemu qemu-kvm-extras +- Fedora: sudo yum install qemu-user + +In general, the file that you need is "qemu-arm". You can use commands +like (Fedora) "yum whatprovides qemu-arm" or (Debian/Ubuntu) "apt-file +search qemu-arm" to work out which top-level package to install. + +For Fedora, you might also need to temporarily disable SELinux security +before OFW compilation: + + sudo /usr/sbin/setenforce 0 + +## Building Open Firmware + +Get the Open Firmware source: + + svn co svn://openfirmware.info/openfirmware + +Build OFW: + + cd openfirmware/cpu/arm/mmp2/build + make + +The last line of the compilation output should say something like: + + --- Saving as ofw.rom + +That tells you the name of the output file. + +There are some other build directories like "cpu/arm/versatilepb/build". +They work the same way - just type "make" in the directory. At present, +those other versions are fairly rudimentary, containing core OFW plus a +serial driver for interaction, but lacking drivers for most of the other +hardware on those systems. Essentially, they are "quick ports to get an +ok prompt". The MMP2 version is quite a bit more complete, on its way to +being a fully-fledged OFW system. The MMP2 is Marvell's hardware +development platform for their PXA688 chip, which is slated for use in +the OLPC XO-1.75 system. We are using the MMP2 to get a jump-start on +XO-1.75 development. diff --git a/Documentation/website/Building_OFW_for_OLPC.md b/Documentation/website/Building_OFW_for_OLPC.md new file mode 100644 index 0000000..ad8c159 --- /dev/null +++ b/Documentation/website/Building_OFW_for_OLPC.md @@ -0,0 +1,35 @@ +# Building OFW for OLPC +This page tells how to build the OLPC (One Laptop Per Child) version of +Open Firmware. This is the version of OFW that is normally shipped on +that machine. You can get precompiled ROMs from +<http://dev.laptop.org/pub/firmware> , so you only need to recompile +from source if you want to change something. See +<http://wiki.laptop.org/go/Firmware> for version history. + +## Software Requirements + +- Open Firmware source code +- GCC and GNU make - most versions are okay for building OFW +- IASL (Intel ASL compiler, for compiling ACPI tables) - most Linux + distributions have an "iasl" package. + +## Building Open Firmware + +Get the Open Firmware source: + + svn co svn://openfirmware.info/openfirmware + +Build OFW: + + cd openfirmware/cpu/x86/pc/olpc/build + make + +The last line of the compilation output should say something like: + + --- Saving as q2e24.rom + +That tells you the name of the output file. You can install it in your +OLPC XO computer by copying that file to a USB FLASH key, inserting the +key into the XO, and typing on the XO: + + ok flash u:\q2e24.rom diff --git a/Documentation/website/Building_OFW_for_QEMU.md b/Documentation/website/Building_OFW_for_QEMU.md new file mode 100644 index 0000000..a4a0f21 --- /dev/null +++ b/Documentation/website/Building_OFW_for_QEMU.md @@ -0,0 +1,280 @@ +# Building OFW for QEMU +This page tells how to build the x86 version of Open Firmware to run under +the QEMU emulator. In this version, OFW replaces QEMU's normal "bios.bin" +file, so QEMU boots directly into OFW, without a conventional BIOS. This +version supports most of QEMU's I/O capabilities, illustrating some of +the things that OFW can do. See the QEMU Options / Things to Try section. + +The OFW tree contains a version of the platform-specific "early startup" +code that is suitable for initializing QEMU's virtual hardware. The +early-startup code for QEMU is as simple as such code can possibly be, +because the QEMU core system "hardware" requires no initialization. On +real hardware, you must turn on PLLs, configure bus bridges and superIO +chips, detect DRAM characteristics and configure memory controllers, and +do other complex chipset-dependent things in the early stages of +startup. QEMU omits all that "magic" stuff that is outside of generic +x86 programming models, so the only system-specific early startup code +for QEMU is a simple memory sizing loop. + +In addition to this "direct" version, there are two other ways to run +OFW under QEMU: + +- You can build OFW as "payload" for coreboot, so Core boot does the + early-startup stuff - see [OFW as a coreboot Payload](OFW_as_a_coreboot_Payload). +- You can boot OFW from a conventional BIOS - see + [Building OFW to Load from BIOS](Building_OFW_to_Load_from_BIOS) + +## Software Requirements + +- qemu-0.9.1 +- Open Firmware rev. \>= 1051 +- GCC and GNU make - OFW builds with most versions + +## Getting QEMU + +Get QEMU \>= 0.9.1 from <http://bellard.org/qemu/download.html> + +## Building Open Firmware + +Get the Open Firmware source: + + svn co svn://openfirmware.info/openfirmware + +Build OFW: + + cd openfirmware/cpu/x86/pc/emu/build + make + +After make is finished (it shouldn't take long) there should be a file +"emuofw.rom" in the build directory. Copy this to your qemu directory. + +## Run Your ROM Image + + qemu -L . -bios emuofw.rom -hda fat:. + +That is the basic invocation; you should get a console window with OFW +running in it. OFW is using the emulated Cirrus graphics display in +linear framebuffer mode, not in VGA mode. + +## QEMU Options / Things to Try + +QEMU has lots of options that let you do all sorts of fun things. The +following sections illustrate a few of OFW's I/O capabilities. + +### Memory Size + +If you look in OFW's startup banner, you should see "128 MiB memory +installed". That is QEMU's default memory size. You can change that by +adding "-m NNN" to the qemu command line, for example: + + qemu -L . -bios emuofw.rom -hda fat:. -m 32 + +OFW as configured will work with power-of-two size between 32 and 2048 +MiB (although my QEMU installation only works up to 1024 MB). Those +limits aren't inherent inheret OFW, but rather artifacts of the way this +particular "port" is configured. + +### Hard Disk Images + +The command line argument "-hda fat:." as shown above makes the current +directory on the host system appear to OFW as an IDE hard disk with a +read-only FAT filesystem. You can inspect it with: + + ok .partitions c + ok dir c:\ + +The device name "c" is a devalias. You can see the actual device name +with: + + ok devalias c + ok devalias + +Instead of that "virtual FAT filesystem", you can make use Linux tools +to make a filesystem image. In this example, we'll create a 10 MByte +image with a single partition and an ext2 filesystem: + + $ dd if=/dev/zero of=filesystem.img bs=1M count=10 + $ /sbin/mke2fs -F filesystem.img + $ dd if=filesystem.img of=fs.img bs=512 seek=1 + $ rm filesystem.img + $ /sbin/sfdisk -L -uS -C 10 -H 64 -S 32 fs.img \<\<EOF + ,,L,* + ; + ; + ; + EOF + $ mkdir mnt + $ sudo mount -o loop,offset=512 fs.img mnt + $ # Now copy some files to "mnt" + $ sudo umount mnt + + $ qemu -L . -bios emuofw.rom -hda fs.img + +In the QEMU OFW console window: + + ok dir c:\ + +In the recipe above, the total size (10 MiB) appears on the first "dd" +line (count=10) and on the "sfdisk" line (-C 10). The sfdisk values for +heads (-H 64) and sectors (-S 32) are set so that the cylinder size is +1MiB (64\*32\*512), making it easy to set the overall size with the +cylinders (-C) argument. It is more common to use the maximum values -H +255 -S 63 in order to maximize the possible overall size, but that +results in a cylinder size of just under 8M, which isn't quite as easy +to work with for this example. The recipe uses two "dd" lines instead of +making the image file in one step because the "mke2fs" command doesn't +give you the option of skipping the first sector where the partition map +has to be located. + +### Serial Console + +You can tell QEMU to emulate a serial port by adding "-serial NAME" to +the command line, as with: + + $ qemu -L . -bios emuofw.rom -hda fat:. -serial `tty` + +Then you can tell OFW to use the serial console with: + + ok com1 io + +QEMU has lots of options for directing the emulated serial port to +various places, including real serial ports on the host system and +network connections to other machines. Read the [QEMU +documentation](http://bellard.org/qemu/qemu-doc.html) (-serial option) +for more information. + +You can configure OFW to use the serial port by default, instead of the +graphics screen and emulated PC keyboard. To do so, uncomment the line +"create serial-console" in openfirmware/cpu/x86/emu/config.fth and +re-execute the "make" command. Serial consoles are convenient because +it's usually easy to cut-and-paste Forth code into the window that is +acting as the "terminal emulator" for the serial console; you can't +paste into QEMU's graphical console. + +### Networking + +OFW has an extensive network stack, supporting many protocols including +TFTP, NFS, HTTP (client and server), and Telnet (client and server). +Here's an example qemu command line with networking support enabled: + + $ qemu -L . -bios emuofw.rom -hda fat:. -net nic,model=pcnet -net tap + +Consult the [QEMU documentation](http://bellard.org/qemu/qemu-doc.html) +(the "-net" option) to learn how to configure the "tap" interface to +connect through to the real network. + +Here are some OFW networking commands that you might want to try: + + ok watch-net + ok debug-net + ok ping yahoo.com + ok undebug-net + ok ping irmworks.com + ok more http:\\firmworks.com\hello.fth + ok fload http:\\firmworks.com\hello.fth + ok telnetd + telnet://10.20.0.107 + +Now start a telnet client on some machine, connecting to the IP address +shown. Quitting the telnet client restores the OFW prompt to the QEMU +console. + + ok telnet 10.20.0.5 + +Instead of "10.20.0.5", use the hostname or IP address of a telnet +server. To exit, type Ctrl-\] . + + ok httpd + http://10.20.0.107 + +Browse to the URL shown. Type any key on the QEMU console to exit the +HTTP server. In addition to static pages, the HTTP server can do +server-side scripting with Forth, and of course you do client-side +scripting by serving up Javascript or Java pages. This facility has been +used for an interactive embedded system with a Web interface programmed +entirely in Open Firmware - a multi-headed high-speed camera for +real-time analysis of golf clubs and golf swings. + +OFW also supports IPV6 networking, but it's not compiled into this +version. + +You can, of course, boot operating systems over the network, using TFTP, +NFS, or HTTP. + +### Graphics + +OFW uses the display in linear framebuffer mode, so it can display 2D +graphics. To see a simple demo: + + ok fload http:\\firmworks.com\testrect.fth + +To clear the screen afterwards: + + ok page + +OFW has a graphical menu system that is not enabled in this +configuration. You can navigate it with either the mouse or the +keyboard. OFW can display .BMP files. + +### USB + +To make QEMU emulate a USB mass storage device, do this: + + $ qemu -L . -bios emuofw.rom -hda fat:. -usbdevice disk:fat:. + +Then, in OFW: + + ok probe-usb + ok dir u:\ + +"p2" is an alias for "probe-usb" for us lazy people. Since OFW tries not +to do stuff "behind your back", if you plug in a new USB device, you +must tell OFW to rescan the USB bus. In this case, it will have already +scanned the device (it does that automatically at startup), but +rescanning is a convenient way to get OFW to show you what is there. You +could instead say: + + ok show-devs usb + +but "p2" is easier to type. + +In the qemu command, you could attach a writable disk image with, for +example: + + $ qemu -L . -bios emuofw.rom -hda fat:. -usbdevice disk:fs.img + +assuming that you have created a suitable fs.img file as per the +instructions above. You can't use the same writable image for both -hda +and -usbdevice, but it's okay to use the same read-only image (as with +the fat:<directory> syntax) for both. + +OFW has reasonably good support for a wide selection of USB mass storage +devices - flash keys, disks, CDROMs, multi-card readers, etc. OFW also +supports USB keyboards, but I haven't yet figured out how to make that +work under QEMU. OFW supports some USB 2.0 network interfaces and some +USB-to-serial adapters. You might be able to make those work using +QEMU's ability to connect to real USB devices on the host. On real +hardware, OFW supports UHCI (USB 1.1), OHCI (USB 1.1), and EHCI (USB +2.0) host controllers. + +### Sound + +To enable sound support in QEMU, do this: + + $ qemu -L . -bios emuofw.rom -hda fat:. -soundhw sb + +In OFW: + + ok select /sound + ok d# 200 d# 2000 tone + ok unselect + +That plays a 200 Hz sine wave for 2 seconds (2000 mS). OFW can also play +.wav files, but that's not included in this configuration. + +QEMU has a lot of options to control the sound emulation; read the +documentation to get totally confused. + +OFW's SoundBlaster driver, as included in this configuration, is rather +rudimentary. OFW has better drivers for the more common AC97 sound +hardware. diff --git a/Documentation/website/Building_OFW_to_Load_from_BIOS.md b/Documentation/website/Building_OFW_to_Load_from_BIOS.md new file mode 100644 index 0000000..15ba2b8 --- /dev/null +++ b/Documentation/website/Building_OFW_to_Load_from_BIOS.md @@ -0,0 +1,167 @@ +# Building OFW to Load from BIOS +This page tells how to build the x86 version of Open Firmware to boot +under a conventional BIOS. These instructions specifically describe a +configuration that is good for running on the QEMU and VirtualBox +emulators, but very similar instructions can be used to make a version +that runs on any PC. In this version, OFW is stored on a floppy disk +image. The conventional BIOS boots it as if it were an operating system +like DOS or Windows. OFW then "takes over" the machine, ignoring the +conventional BIOS that booted it. That BIOS has already done the work of +early-startup machine initialization - turning on the memory controller +and configuring chipset-dependent registers. + +In addition to this BIOS-loaded version, there are two other ways to run +OFW under QEMU: + +- You can build an OFW image that replaces the QEMU BIOS ROM image, + entirely from code in the OFW tree - see + [Building OFW for QEMU](Building_OFW_for_QEMU). +- You can build an OFW image that replaces the QEMU BIOS ROM image, + using OFW as a "payload" for coreboot, so coreboot does the + early-startup stuff - see [OFW as a coreboot Payload](OFW_as_a_coreboot_Payload). + +## Software Requirements + +- qemu-0.9.1 or VirtualBox +- Open Firmware rev. \>= 1053 +- GCC and GNU make - most versions work for builing OFW + +## Getting Open Firmware Source + + $ svn co svn://openfirmware.info/openfirmware + +## Building OFW + + $ cd cpu/x86/pc/biosload/ + $ cp config-virtualbox.fth config.fth + $ cd build + $ make floppyofw.img + +The "config-virtualbox.fth" configuration is known to work with QEMU. +Other configurations may work also - but the "qemu-loaded" config option +isn't what you want for this technique, because it's a subcase of the +CoreBoot-payload configuration. + +You will use the "floppyofw.img" output file in a later step. + +## Making a bootable Floppy Image + + $ ../../../Linux/forth fw.dic ../makefloppy.fth + +This creates a file that is a bootable floppy image with an empty FAT12 +filesystem. This step only has to be done once. + +## Copying OFW onto the Floppy Image + + $ mkdir flp + $ sudo mount -t msdos -o loop floppy.img flp + $ sudo cp floppyofw.img flp/ofw.img + $ sudo umount flp + +Copy floppy.img to the QEMU or VirtualBox directory. + +## Booting OFW from QEMU + + $ qemu -L *dir* -boot a -fda floppy.img + +"*dir*" is the directory that contains QEMU's BIOS and VGA BIOS files. + +## Booting OFW from VirtualBox + +The following VirtualBox configuration settings work for me: + +- OS Type = Other/Unknown +- Base Memory = 64 MB +- Video Memory = 8 MB +- Boot Order = Floppy, Hard Disk +- ACPI = Disabled +- IO APIC = Disabled +- VT-x/AMD-V = Disabled +- PAE/NX = Disabled +- Floppy Image = floppy.img +- Network Adapter 1 = PCnet-PCI II (host interface, `<tap name>`) +- (other settings are mostly irrelevant) + +## Recompiling + +If you want to make changes and recompile OFW, you need not repeat the +"makefloppy" step; you can just loopback mount the floppy image and copy +the new OFW version to ofw.img . + +## What is on the Floppy Image + +The floppy image is a bootable floppy with a FAT12 filesystem. Its first +two sectors contain a simple bootloader program that uses BIOS INT 13 +callbacks to read floppy sectors. The program scans the FAT root +directory entries to find the file "ofw.img", then loads that into +memory and jumps to it. + +When you build floppyofw.img, as a side effect it also builds +bootsec.img, which is that simple bootloader. The source code +(Forth-style assembly language) is in biosload/bootsec.fth . + +The "makefloppy.fth" program that creates the image is pretty simple; it +copies bootsec.img to the output file "floppy.img", creates a couple of +initially empty FAT tables, zeros the root directory area, and fills the +data area with zeros. + +## Making a Prototype Floppy Image with Linux Commands + +Here's a pair of Linux commands that accomplish the same thing as +makefloppy.fth: + + Step6a $ /sbin/mkdosfs -C -f 2 -F 12 -R 2 -r 224 -s 1 -S 512 floppy.img 1440 + Step6b $ dd <bootsec.img of=floppy.img conv=nocreat,notrunc + +The arguments to mkdosfs force the filesystem layout to match the layout +that is specified in the BIOS parameter block in bootsec.img. + +The advantage of makefloppy.fth is that it reads the filesystem layout +parameters from the BPB in bootsec.img, so its guaranteed to be +consistent. If bootsec.fth were edited to change the layout, the +arguments to "mkdosfs" would have to change. (But there's little need to +change that layout, since it's a standard floppy size.) + +The advantage of the Linux command sequence is that it creates a file +with "holes", thus saving disk space for awhile (until something fills +in the holes). + +## Booting on a Real PC from a USB Key + +To build for a real PC: + + $ cd openfirmware/cpu/x86/biosload + $ cp config-usbkey.fth config.fth + $ cd build + $ make + +That will create a file named "ofw.c32" that can be booted from a USB +key that has "syslinux" installed on it. +<http://www.911cd.net/forums//index.php?showtopic=21902> has some tips +on how to install syslinux. + +Your syslinux.cfg file needs a line that says: + + kernel ofw.c32 + +## Booting on a Real PC via GRUB or Etherboot + +You can make a version in "Multiboot" format that you can boot with +GRUB: + + $ cd openfirmware/cpu/x86/biosload + $ cp config-grub.fth config.fth + $ cd build + $ make + +The output file is "ofwgrub.elf". Copy that in to /boot on your +GRUB-enabled disk and add this to /boot/grub/menu.lst: + + title Open Firmware + kernel /boot/ofwgrub.elf + +That version can also be booted via Etherboot. Here's an example of how +to Etherboot it with QEMU (assuming that the ofwgrub.elf file is in /tmp +on the host machine): + + qemu -L . -boot n -tftp /tmp -bootp /ofwgrub.elf diff --git a/Documentation/website/Code_of_Conduct.md b/Documentation/website/Code_of_Conduct.md new file mode 100644 index 0000000..6d21fb2 --- /dev/null +++ b/Documentation/website/Code_of_Conduct.md @@ -0,0 +1,55 @@ +# Code of Conduct +Dear OpenBIOS project members and other interested parties, + +For the ease of development and for information on what can be expected +from this project we want to set down the following ground rules in +order to achieve a high quality implementation of our project +objectives. + +1. The objective of this project is to develop a free, open source, +architecture independant firmware implementation following, if possible, +the IEEE Standard for Boot (Initialization Configuration) Firmware (IEEE +1275-1994). Including not only the implementation of the standard itself +but also the required toolkit consisting of a C to FCode compiler, an +FCode tokenizer and an FCode detokenizer. This toolkit will simplify +driver and API development implementing ANSI C as the development +language instead of implementing Forth/FCode directly as suggested by +the IEEE standard. + +2. We cannot allow _any_ discussion or use of _any_ copyrighted, +patented, or otherwise protected Firmware or BIOS implementations +without an OSI approved license in this project or on the mailing list +associated with this project. All members of this project and/or the +according mailing lists agree to not disclose or use any copyrighted, +patented, or otherwise protected information, ideas or concepts. + +3. We do not intend to implement any of the ideas or concepts expressed +in the current Intel 32bit architechture, except when these are +necessary to insure the compatability with existing hardware. Such ideas +and concepts will only be used if such use is not restricted by _any_ +laws, copyrights or patents. + +4. In order to assure truly universal implementation and/or optimize +the functionality and performance it is our expressed wish to work in +conjunction with other open source (firmware) projects, such as coreboot +or U-Boot. + +5. Cooperation with hardware vendors is necessary to implement this +project on an architecture-independent basis. In certain cases this may +include signing non-disclosure agreements with the aforementioned +hardware vendors in an attempt to acquire hardware specific information +or support that may not otherwise be available although the results of +such cooperation must be freely redistributable. + +6. Cooperation with any university, research project, or organization +is desired except in such cases where the resulting information is +restricted in use or redistributability. + +If, for whatever reasons, any of the above statements are unacceptable +or seem to be incorrect or unclear in _any_ way please do not hesitate +to discuss this matter on the mailing list, we are open for suggestions. +This is simply an attempt to assure the legal status of this project, +protecting those involved from legal prosecution as well as to state the +general objectives of the project. + +OpenBIOS development team. diff --git a/Documentation/website/Contact_us.md b/Documentation/website/Contact_us.md new file mode 100644 index 0000000..22aca30 --- /dev/null +++ b/Documentation/website/Contact_us.md @@ -0,0 +1,45 @@ +# Contact us + +## The OpenBIOS Project + +The OpenBIOS project coordinates all free and open source implementations +of the Open Firmware standard. Yet our development team is rather +small. You are welcome to contact us, if you + +- want to help developing drivers, support for new systems, write + documentation. +- need help porting Open Firmware to your custom hardware and are + looking for specialists to get it done. + +Of course we appreciate any help, hints, patches, comments, etc. + +NOTE: Please read our [Code of Conduct](Code_of_Conduct). + +## Mailinglist + +Development and other things about OpenBIOS are discussed on the +[OpenBIOS mailing list](Mailinglist). If you want to +contribute, ask questions, get information or have some ideas, please +subscribe to this list. It's currently very low traffic. If you have +patches, feel free to send them to the list, too. Please note: To keep +the amount of spam as low as possible, only subscribed users are allowed +to post to the list. + +## Internet Relay Chat + +Currently most of the discussion moved over to Internet Relay Chat +(IRC). You can find us on [irc.freenode.net](http://www.freenode.net/) +in \#coreboot. Most people are in CET timezone, so don't give up when +this channels seems very quiet for some time. + +Here you have the chance to talk to people being involved or interested +in this project. Most of the discussion is tech talk. There's no need to +ask whether you are allowed to ask. Questions on OpenBIOS, coreboot, +firmware and related topics are welcome. + +## Project Maintainer + +The OpenBIOS Project is maintained by Stefan Reinauer from [coresystems +GmbH](http://www.coresystems.de). If you have any questions regarding +the project that are beyond the scope of the mailing list, please +contact Stefan. diff --git a/Documentation/website/Credits.md b/Documentation/website/Credits.md new file mode 100644 index 0000000..4f4dbcf --- /dev/null +++ b/Documentation/website/Credits.md @@ -0,0 +1,42 @@ +# Credits + +Development contributions + +- Stefan Reinauer (project coordination, main development) +- Patrick Mauritz (initial kernel work) +- Samuel Rydh (forth interfaces, MOL port, ...) +- BlueSwirl (Sparc/Sparc64 port) +- Greg Watson (briq port) +- [David Paktor](mailto:David@paktor.biz) (improving Toke) +- Chen-Chau Chu (ppc fixes) +- Tim Barrett (detok patches) +- Krishna Myneni (permission to include kForth examples with toke) +- Laurent Vivier (ppc/qemu port) + +Patches and other contributions from + +- Stefan Assmann +- Paul Brook +- Mark Cave-Ayland +- Justin Chevrier +- Peter Creath +- Alexander Graf +- Mike Hommey +- Aurelien Jarno +- Igor Kovalenko + +Hardware/Funding + +- Michael Gibson (EsEsIx) for donating a CS5530 based thin client for + /dev/bios development. +- [LinuxFund.org](http://www.linuxfund.org/) chose OpenBIOS to be + awarded in the spring 2002 grant cycle with US\$1000. Thanks a lot for + supporting our work! +- [Newisys](http://www.newisys.com/) funded the OpenBIOS project with a + very nice piece of hardware, an Opteron based 1U 2CPU Newisys 2100. + This machine is nowadays running www.openfirmware.info and + www.coreboot.org. +- [Daniele Frijia](http://sase.de/) for donating a Motorola PPC-machine + +If you or somebody else is missing on this list, send an email to Stefan +Reinauer diff --git a/Documentation/website/FCODE_suite.md b/Documentation/website/FCODE_suite.md new file mode 100644 index 0000000..33b29e4 --- /dev/null +++ b/Documentation/website/FCODE_suite.md @@ -0,0 +1,219 @@ +# FCode Suite + +## What is the OpenBIOS FCODE Suite? + +OpenBIOS provides a sophisticated set of FCODE utilities: + +- the tokenizer **toke** +- the detokenizer **detok** +- and a PCI rom header utility. +- a portable implementation of forth local values + +These files are offered without any warranty. If you experience +problems, please contact the [OpenBIOS mailinglist](Mailinglist). + +## Downloading the OpenBIOS FCode Suite + +**The latest version of the OpenBIOS FCode Suite is 1.0.2 (released +2006-10-30)** + +### Source Code + +View the [Sources](https://github.com/openbios/fcode-utils) online. +Available as a ZIP-File: [FCode-utils +1.0.2](https://github.com/openbios/fcode-utils/archive/v1.0.2.zip) + +See the +[ChangeLog](https://raw.githubusercontent.com/openbios/fcode-utils/v1.0.2/ChangeLog) +for a list of changes since 1.0.1. A hand crafted html document +describes [some more +changes](http://www.openbios.org/data/visiblediffs/V01_versus_V2x/). + +### Documentation + +There are three documents, all in html format, plus a sub-directory of +templates that provide common formatting support. + +It is important that these be kept in the same directory, as there are +some links from one file to another. + +The documents are User's Guides to: + +- the [New Features of the + Tokenizer](http://www.openbios.org/data/fcodesuite/Documents/toke.html), +- [the + Detokenizer](http://www.openbios.org/data/fcodesuite/Documents/detok.html), + and +- the [Local Values + feature](http://www.openbios.org/data/fcodesuite/Documents/localvalues.html), + which is mentioned briefly in the Tokenizer User's Guide and described + fully in the Local Values document. + +These documents are also part of the source code repository. + +There is also doxygen generated documentation available + +- [doxygen documentation for toke + 0.6.10](http://openbios.org/data/toke/toke-0.6.10) +- [doxygen documentation for toke + 1.0.0](http://openbios.org/data/toke/toke-1.0) +- TODO: doxygen documentation for toke 1.0.2 + +### Executables for three platforms + +While you can find a couple of executables here we strongly recommend +that you compile the FCode toolchain from the sources above so you gain +from the integration work and fixes that have been done since these +executables have been created. + +There are three programs: the Tokenizer, the Detokenizer and the +ROMHeaders utility. +([Binaries](http://www.openbios.org/data/fcodesuite/Binaries)) + +There is a version for each of three platforms (i.e., combinations of +Processor and O/S): Cygwin running on an X86, GNU Linux running on a +Power-PC, and AIX running on a Power-PC. + +There are two variants of each version: One that has level-2 +Optimization and one that has no optimization at all, which I provided +for purposes of Debugging. Optimization causes some routines and +variables to become obscured and inaccessible to debuggers, and also +re-arranges the sequence of execution in a way that can become confusing +during single-stepping. + +And finally, for each, there is a "stripped" and an "unstripped" +executable image. The "unstripped" image has an extension of +"unstripped"; the "stripped" image has no extension. + +There are separate directories for the Debug and Optim(ized Level)2 +variants. + +Under each are sub-directories for the different platforms, within which +the executable images reside. + +All binaries are also available in a single Tar-File: +[Binaries.tar.bz2](http://www.openbios.org/data/fcodesuite/Binaries.tar.bz2) + +### Local Value Support + +Includ-able tokenizer-source files for [Local Values +Support](https://github.com/openbios/fcode-utils/tree/master/localvalues) +(explained in one of the User's Guide documents). Five files: + +- One supplies the [basic + functionality](https://github.com/openbios/fcode-utils/tree/master/localvalues/LocalValuesSupport.fth) +- the second adds a [development-time + facility](https://github.com/openbios/fcode-utils/tree/master/localvalues/LocalValuesDevelSupport.fth) +- the third generates a variant behavior (["Global" + scope](https://github.com/openbios/fcode-utils/tree/master/localvalues/GlobalLocalValues.fth) + rather than scope limited to a single Device-Node) +- and the fourth [combines the "Global" variant behavior with the + development-time + facility](https://github.com/openbios/fcode-utils/tree/master/localvalues/GlobalLocalValuesDevel.fth). +- The fifth [allows the choice of combinations to be governed by + command-line + switches](https://github.com/openbios/fcode-utils/tree/master/localvalues/TotalLocalValuesSupport.fth), + and is probably the best to use with Makefiles in commercial + development and production environments. + +There is commentation in each one explaining how it is to be used. + +Available as part of the OpenBIOS FCODE suite. + +### Todo + +A list of "Still To Be Done" items, excerpted from the commentation in +the Sources + +The source files have, scattered among their commentation, an occasional +item discussing a feature or implementation detail that might be worth +attention in future revisions. + +This file is a [collection of all of +them](https://github.com/openbios/fcode-utils/tree/master/TODO) in a +single convenient location. + +## Unit-Test Suite + +### The suite of unit-test cases + +This is the [accumulation of +test-cases](https://github.com/openbios/fcode-utils/tree/master/testsuite) +that were created in the course of development. Some of these are a +straightforward invocation of a feature, others are convoluted +combinations of features whose interaction needed to be carefully +watched, and still others are collections of coding errors, for purposes +of verifying the Error-detection capabilities of the Tokenizer. They are +grouped into sub-directories representing broad categories. + +Run the unit-test cases with + + $ make tests + +### Test Tools + +The tools to run the Unit-Test Suite as a batch and examine the results +for changes relative to the results from a previous run. + +The process of manually running a unit-test and comparing against the +previous output, after every change, became unwieldy, especially when it +came to running the entire suite of tests. These scripts were developed +to automate both processes: + +- [AutoExec](https://github.com/openbios/fcode-utils/tree/master/testsuite/AutoExec) + automates the execution, and +- [AutoCompare](https://github.com/openbios/fcode-utils/tree/master/testsuite/AutoCompare) + automates the comparison. + +There is commentation in each explaining how it is used. + +## Unit-Test Suite Logs + +These can be used as base-lines for comparison against future versions, +or, if so be, versions compiled for additional platforms. + +Note that a comparison of these against each other will not yield exact +identity. Some of the test-cases, for instance, code the current date +and time, others display a complete file-path, and still one other +attempts to load a file for encoding using a syntax that is erroneous on +some O/S's but not on others. + +All in all, five or six file differences will be expected to be reported +by AutoCompare. + +- The results from a run of the Unit-Test Suite on the + [X86/Cygwin](https://github.com/openbios/fcode-utils/tree/master/testlogs/testlogs-x86-cygwin) + platform. + +<!-- --> + +- The results from a run of the Unit-Test Suite on the + [PowerPC/Linux](https://github.com/openbios/fcode-utils/tree/master/testlogs/testlogs-ppc-linux) + platform. + +<!-- --> + +- The results from a run of the Unit-Test Suite on the + [PowerPC/AIX](https://github.com/openbios/fcode-utils/tree/master/testlogs/testlogs-ppc-aix) + platform. + +## Coverage Reports + +The test suite has been run using gcov/lcov to produce graphical code +coverage reports. + +- [coverage report for FCODE suite + 1.0.2](http://www.openbios.org/data/coverage-fcode-suite-1.0.2/) +- [coverage report for toke + 1.0.2](http://www.openbios.org/data/coverage-toke-1.0.2/) +- [coverage report for toke + 1.0.0](http://openbios.org/data/toke/coverage/) + +## Kudos and Thanks + +The OpenBIOS FCODE Suite has been significantly enhanced to meet +commercial grade requirements by [David +Paktor](mailto:David@paktor.biz). Regarding to code readability and +stability, he made the FCODE suite the best part of OpenBIOS. And it's +probably the best FCODE development environment out there. **Thank you, +David!** diff --git a/Documentation/website/FlashRom.md b/Documentation/website/FlashRom.md new file mode 100644 index 0000000..88faa32 --- /dev/null +++ b/Documentation/website/FlashRom.md @@ -0,0 +1,18 @@ +# Flash Updates with Linux + +Formerly OpenBIOS provided its own flashing facility implemented as a +device driver called **/dev/bios**. One big disadvantage of +**/dev/bios** was that it needed to be recompiled for every minor kernel +update. + +Ollie Lho, back when working at SIS, started a new effort which he +called **flash_and_burn**. This utility became part of the [coreboot +project](http://www.coreboot.org) and evolved to work with non-SIS +chipsets. + +Stefan Reinauer added a lot of new features to Ollie's utility and +renamed it to **flashrom**. This utility still lacks some features the +old **/dev/bios** driver was having, but it can easily be used from +userspace without recompiling the kernel. + +For more information about flashrom see <http://www.flashrom.org/> diff --git a/Documentation/website/Forth_FCode.md b/Documentation/website/Forth_FCode.md new file mode 100644 index 0000000..3ad87ad --- /dev/null +++ b/Documentation/website/Forth_FCode.md @@ -0,0 +1,41 @@ +# What is Forth? + +From the [Forth +FAQ](http://www.faqs.org/faqs/computer-lang/forth-faq/part1/): Forth is +a stack-based, extensible language without type-checking. It is probably +best known for its "reverse Polish" (postfix) arithmetic notation, +familiar to users of Hewlett-Packard calculators: to add two numbers in +Forth, you would type 3 5 + instead of 3+5. The fundamental program unit +in Forth is the "word": a named data item, subroutine, or operator. +Programming in Forth consists of defining new words in terms of existing +ones. + +# Why and where is Forth used? + +Although invented in 1970, Forth became widely known with the advent of +personal computers, where its high performance and economy of memory +were attractive. These advantages still make Forth popular in embedded +microcontroller systems, in locations ranging from the Space Shuttle to +the bar-code reader used by your Federal Express driver. Forth's +interactive nature streamlines the test and development of new hardware. +Incremental development, a fast program-debug cycle, full interactive +access to any level of the program, and the ability to work at a high +"level of abstraction," all contribute to Forth's reputation for very +high programmer productivity. These, plus the flexibility and +malleability of the language, are the reasons most cited for choosing +Forth for embedded systems. Find more information +[here](http://www.complang.tuwien.ac.at/forth/faq/why-forth). + +# FCode + +FCode is a Forth dialect compliant to ANS Forth, that is available in +two different forms: source and bytecode. FCode bytecode is the compiled +form of FCode source. + +# Why bytecode? + +Bytecode is small and efficient. And an evaluator (bytecode virtual +machine) is almost trivial to implement. For example, putting a 1 to the +stack only takes one byte in an FCode bytecode binary. This is +especially valuable on combined system or expansion hardware roms where +the available space is limited. diff --git a/Documentation/website/GPLv2.md b/Documentation/website/GPLv2.md new file mode 100644 index 0000000..d8aafa2 --- /dev/null +++ b/Documentation/website/GPLv2.md @@ -0,0 +1,359 @@ +# OpenBIOS Licensing + +OpenBIOS is covered by the General Public License V2. + +# GNU GENERAL PUBLIC LICENSE + +Version 2, June 1991 + +Copyright (C) 1989, 1991 Free Software Foundation, Inc. +51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. + +## Preamble + +The licenses for most software are designed to take away your freedom to +share and change it. By contrast, the GNU General Public License is +intended to guarantee your freedom to share and change free software--to +make sure the software is free for all its users. This General Public +License applies to most of the Free Software Foundation's software and +to any other program whose authors commit to using it. (Some other Free +Software Foundation software is covered by the GNU Library General +Public License instead.) You can apply it to your programs, too. + +When we speak of free software, we are referring to freedom, not price. +Our General Public Licenses are designed to make sure that you have the +freedom to distribute copies of free software (and charge for this +service if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs; and that you know you can do these things. + +To protect your rights, we need to make restrictions that forbid anyone +to deny you these rights or to ask you to surrender the rights. These +restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + +For example, if you distribute copies of such a program, whether gratis +or for a fee, you must give the recipients all the rights that you have. +You must make sure that they, too, receive or can get the source code. +And you must show them these terms so they know their rights. + +We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + +Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + +Finally, any free program is threatened constantly by software patents. +We wish to avoid the danger that redistributors of a free program will +individually obtain patent licenses, in effect making the program +proprietary. To prevent this, we have made it clear that any patent must +be licensed for everyone's free use or not licensed at all. + +The precise terms and conditions for copying, distribution and +modification follow. + +## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +**0.** This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, either +verbatim or with modifications and/or translated into another language. +(Hereinafter, translation is included without limitation in the term +"modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of running +the Program is not restricted, and the output from the Program is +covered only if its contents constitute a work based on the Program +(independent of having been made by running the Program). Whether that +is true depends on what the Program does. + +**1.** You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the notices +that refer to this License and to the absence of any warranty; and give +any other recipients of the Program a copy of this License along with +the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +**2.** You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and distribute +such modifications or work under the terms of Section 1 above, provided +that you also meet all of these conditions: + + +a\) You must cause the modified files to carry prominent notices stating +that you changed the files and the date of any change. + +<!-- --> + + +b\) You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any part +thereof, to be licensed as a whole at no charge to all third parties +under the terms of this License. + +<!-- --> + + +c\) If the modified program normally reads commands interactively when +run, you must cause it, when started running for such interactive use in +the most ordinary way, to print or display an announcement including an +appropriate copyright notice and a notice that there is no warranty (or +else, saying that you provide a warranty) and that users may +redistribute the program under these conditions, and telling the user +how to view a copy of this License. (Exception: if the Program itself is +interactive but does not normally print such an announcement, your work +based on the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, and +can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based on +the Program, the distribution of the whole must be on the terms of this +License, whose permissions for other licensees extend to the entire +whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of a +storage or distribution medium does not bring the other work under the +scope of this License. + +**3.** You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + +a\) Accompany it with the complete corresponding machine-readable source +code, which must be distributed under the terms of Sections 1 and 2 +above on a medium customarily used for software interchange; or, + +<!-- --> + + +b\) Accompany it with a written offer, valid for at least three years, +to give any third party, for a charge no more than your cost of +physically performing source distribution, a complete machine-readable +copy of the corresponding source code, to be distributed under the terms +of Sections 1 and 2 above on a medium customarily used for software +interchange; or, + +<!-- --> + + +c\) Accompany it with the information you received as to the offer to +distribute corresponding source code. (This alternative is allowed only +for noncommercial distribution and only if you received the program in +object code or executable form with such an offer, in accord with +Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source code +means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to control +compilation and installation of the executable. However, as a special +exception, the source code distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies the +executable. + +If distribution of executable or object code is made by offering access +to copy from a designated place, then offering equivalent access to copy +the source code from the same place counts as distribution of the source +code, even though third parties are not compelled to copy the source +along with the object code. + +**4.** You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt otherwise +to copy, modify, sublicense or distribute the Program is void, and will +automatically terminate your rights under this License. However, parties +who have received copies, or rights, from you under this License will +not have their licenses terminated so long as such parties remain in +full compliance. + +**5.** You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and all +its terms and conditions for copying, distributing or modifying the +Program or works based on it. + +**6.** Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further restrictions +on the recipients' exercise of the rights granted herein. You are not +responsible for enforcing compliance by third parties to this License. + +**7.** If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot distribute +so as to satisfy simultaneously your obligations under this License and +any other pertinent obligations, then as a consequence you may not +distribute the Program at all. For example, if a patent license would +not permit royalty-free redistribution of the Program by all those who +receive copies directly or indirectly through you, then the only way you +could satisfy both it and this License would be to refrain entirely from +distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is implemented +by public license practices. Many people have made generous +contributions to the wide range of software distributed through that +system in reliance on consistent application of that system; it is up to +the author/donor to decide if he or she is willing to distribute +software through any other system and a licensee cannot impose that +choice. + +This section is intended to make thoroughly clear what is believed to be +a consequence of the rest of this License. + +**8.** If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License may +add an explicit geographical distribution limitation excluding those +countries, so that distribution is permitted only in or among countries +not thus excluded. In such case, this License incorporates the +limitation as if written in the body of this License. + +**9.** The Free Software Foundation may publish revised and/or new +versions of the General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Program does not specify a version +number of this License, you may choose any version ever published by the +Free Software Foundation. + +**10.** If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the +author to ask for permission. For software which is copyrighted by the +Free Software Foundation, write to the Free Software Foundation; we +sometimes make exceptions for this. Our decision will be guided by the +two goals of preserving the free status of all derivatives of our free +software and of promoting the sharing and reuse of software generally. + +## NO WARRANTY + +**11.** BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, +EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE +ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH +YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL +NECESSARY SERVICING, REPAIR OR CORRECTION. + +**12.** IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR +DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL +DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM +(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED +INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF +THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR +OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +# END OF TERMS AND CONDITIONS + +## How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest to +attach them to the start of each source file to most effectively convey +the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + +one line to give the program's name and an idea of what it does. +Copyright (C) yyyy name of author + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +Gnomovision version 69, Copyright (C) year name of author +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `show c' +for details. + +The hypothetical commands \`show w' and \`show c' should show the +appropriate parts of the General Public License. Of course, the commands +you use may be called something other than \`show w' and \`show c'; they +could even be mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +signature of Ty Coon, 1 April 1989 +Ty Coon, President of Vice + +This General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications +with the library. If this is what you want to do, use the [GNU Lesser +General Public License](http://www.fsf.org/licensing/licenses/lgpl.html) +instead of this License. diff --git a/Documentation/website/How_Local_Variables_in_Forth_Work.md b/Documentation/website/How_Local_Variables_in_Forth_Work.md new file mode 100644 index 0000000..cc86dbc --- /dev/null +++ b/Documentation/website/How_Local_Variables_in_Forth_Work.md @@ -0,0 +1,99 @@ +# How Local Variables in Forth Work - Using Apple's Open Firmware Implementation + +## How to try out these code examples + +The following example code may be entered and ran in Apple's Open +Firmware. In order to access Open Firmware, just hold down +Command-Option-O-F while you boot your pre-Intel Mac. PowerPC iMacs and +PowerBooks, iBooks, PowerMac G3's, G4's, and G5's all have Open Firmware +built-in. + + +## Declaring local variables: + +Place curly braces next to the word name. The curly braces must be on +the same line as the word's name. The semicolon is optional. The +semicolon lets the system know that the variables following it will not +be initializing their values to the values that would have been popped +from the stack. + +### Example 1 + + + : myword { ; cat dog } + ; + + +Omitting the semicolon will initialize the local variable's values to +values popped from the stack. Make sure the stack has enough values in +it before proceeding. + + +## Setting local variables: +The word "-\>" (hyphen greater-than) is used to set the values of local +variables. + +### Example 2 + + + : myword { ; cat dog } + 4 -> cat + 5 -> dog + ; + + +In the above example, the numbers are each pushed into the stack first. +Then the -\> word pops a value out of the stack and sets each variable's +value to a popped value. If a value is already in the stack, the +following code would work as well: -\> cat (The 4 has been omitted). + + +## Setting a local variable's value automatically + +When you don't use the semicolon in the local variable declaration, the +variables get their value from the stack. The order is the last variable +declared is set to the last value pushed on the stack. + +### Example 3 + + stack before myword is called ... + + 3 \<---- top of stack + 2 + 1 + + + : myword { one two three } + cr ." one = " one . + cr ." two = " two . + cr ." three = " three . + ; + + +after myword is called ... + + one = 1 + two = 2 + three = 3 + + +## Obtaining a local variable's value + +To push a local variable's value onto the stack, just enter a local +variable's name in a word. + +### Example 4 + + + : myword { ; cat dog } + 4 -> cat + 5 -> dog + + cat \ cat's value pushed onto stack ( - cat) + dog \ dog's value pushed onto stack (cat - cat dog ) + + + + cr + ." Total animals = " . + cr + ; diff --git a/Documentation/website/How_to_build_OpenBIOS_on_Mac_OS_X.md b/Documentation/website/How_to_build_OpenBIOS_on_Mac_OS_X.md new file mode 100644 index 0000000..b63729e --- /dev/null +++ b/Documentation/website/How_to_build_OpenBIOS_on_Mac_OS_X.md @@ -0,0 +1,88 @@ +# How to build OpenBIOS on Mac OS X +Apple's GCC on Mac OS X does not support the elf binary format. So +compiling OpenBIOS on Mac OS X is not easy. Thankfully someone has +already made a PowerPC cross compiler for Mac OS X that can compile +OpenBIOS. Note: this tutorial was made with Mac OS 10.6. I suggest you +use Mac OS 10.5 or higher when trying to build OpenBIOS. + + +<FONT COLOR="#AA0000"><B><U>Part 1: Installing the cross compiler on Mac +OS X</U> +</B></FONT> +1). Download the AWOS cross compiler: +<http://awos.wilcox-tech.com/downloads/AWOS-CC.bz2> + +2) Expand this bz2 file by double clicking on it. + +3) Rename the file AWOS-CC to AWOS-CC.img. + +4) Open the image file. + +5) Open the "AWOS Cross-Compiler for OS X" file on the newly mounted +disk. + +6) Select the "PowerPC Support" and the "i386 Support" check boxes when +given the option. + +7) Continue with the installation until it is finished. + +8) Add the new compiler's folder to the PATH variable. This is the +command you use if you are in the Bash shell: +export PATH=\$PATH:/usr/local/ppcelfgcc/bin +export PATH=\$PATH:/usr/local/i386elf/i386elf/bin +Note: the above step will probably need to be repeated with each new +session of the shell you start. It can be made permanent by altering the +.bash_profile file for the Bash shell. It is located in your home +folder. +To open this file use these commands: +cd ~ +open .bash_profile +Then simply paste the export commands in this file. Save changes when +you are done. + +To test to see if the cross compilers work issue these commands: +i386-elf-gcc --version +ppc-elf-gcc --version + +You should see a message like this print: +ppc-elf-gcc (GCC) 4.2.3 Copyright (C) 2007 Free Software Foundation, +Inc. This is free software; see the source for copying conditions. There +is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. +This should conclude installing the compiler. + + +<FONT COLOR="#AA0000"><B><U>Part 2: Building OpenBIOS from source +code</U> +</B></FONT> +1) Open the Terminal application. + +2) Change the current directory to the inside of the openbios-devel +folder. + +3) Open the file makefile.target and add a \# in front of this text +"CFLAGS+= -Werror". Save the changes when done. + +4) Type this command in the terminal and watch the show: + + CROSS_COMPILE=ppc-elf- ./config/scripts/switch-arch ppc && make build-verbose + +There is a known build issue when building on Mac OS 10.6. The +switch-arch script will report your computer as 32 bit (x86) when it is +really 64 bit (amd64). If you see the message "panic: segmentation +violation at …" while building, you probably have this problem. + +If this happens to you, try setting the HOSTARCH variable before using +the switch-arch script. + +Example: + +HOSTARCH=amd64 CROSS_COMPILE=ppc-elf- ./config/scripts/switch-arch ppc +&& make build-verbose + +To test out your newly created binary in qemu, use the -bios option: +qemu-system-ppc -bios <path to binary>/openbios-qemu.elf.nostrip + +This tutorial was made using information available on 12/21/2017. If you +encounter any problems, please report it to the openbios developer list: +openbios@openbios.org. diff --git a/Documentation/website/IEEE_1275-1994.md b/Documentation/website/IEEE_1275-1994.md new file mode 100644 index 0000000..f7cf46a --- /dev/null +++ b/Documentation/website/IEEE_1275-1994.md @@ -0,0 +1,32 @@ +# IEEE 1275-1994 +After 5 years the IEEE 1275-1994 standard got withdrawn by the IEEE +Standards Association. This does by no means implicate that this +standard is abandoned or dead. There are several commercial +implementations of Open Firmware and a quite reasonable number of +hardware vendors support it. IEEE sold the rights to distribute the +standards document to Global Engineering who still offer it. + +To Contact Global Engineering, use Phone: 1-800-854-7179, Fax: +303-397-2740. Out side the U.S. call 303-792-2181. You can also purchase +the IEEE 1275-1994 document online from the [Global Engineering +website](http://global.ihs.com/). + +To get started with Open Firmware, download the IEEE 1275-1994, Standard +for Boot (Initialization Configuration) Firmware Core Requirements and +Practices. You can get the document from our [local +mirror](http://www.openbios.org/data/docs/of1275.pdf) or from the [IEEE +1275-1994 ftp archive at +sun.com](ftp://playground.sun.com/pub/p1275/coredoc/1275-1994/1275.ps.gz). + +For more information on IEEE 1275 Open Firmware, we recommend you browse +the [IEEE Standard 1275 Working Group's Home +Page](http://playground.sun.com/pub/p1275). + +No Standard without mistakes - This +[Errata](http://www.openbios.org/data/docs/1275errata.pdf) document +contains corrections of mistakes and clarifications of the IEEE +1275-1994 standard (Draft 4). + +The Open Firmware standard is the elementary base of OpenBIOS. Any +questions are welcome, please contact Stefan Reinauer or the [OpenBIOS +Mailinglist](Mailinglist). diff --git a/Documentation/website/Licensing.md b/Documentation/website/Licensing.md new file mode 100644 index 0000000..d6a58aa --- /dev/null +++ b/Documentation/website/Licensing.md @@ -0,0 +1,23 @@ +# OpenBIOS Licensing + +OpenBIOS is licensed under the GNU General Public License v2. If you +adapt OpenBIOS to your needs, please contact us with your changes so +that you can contribute your changes back to the community. + +# Why GPL? + +We see the GPL giving OpenBIOS a big competitive advantage over other +firmware solutions: + +- As a hardware vendor you get the warranty that nobody hiddenly + improves the code you have been contributing without giving those + improvements back. Thus, GPL guarantees that you keep control over + your work and contributions. +- End users / customers get great benefit from OpenBIOS being GPL + licensed: The GPL insures customers that a given platform will act + like all other OpenBIOS platforms. BSD is a negative marketing point + where BIOS is concerned. + +# View the license + +Have a look at the [complete license](GPLv2) diff --git a/Documentation/website/Mailinglist.md b/Documentation/website/Mailinglist.md new file mode 100644 index 0000000..2ad6d1d --- /dev/null +++ b/Documentation/website/Mailinglist.md @@ -0,0 +1,16 @@ +# Mailinglist + +The OpenBIOS project currently has one mailing list which is intended +for development, informational and general project purposes. You can +subscribe to the OpenBIOS mailing list via a web interface or with a +simple email (un-)subscription mechanism. + +For questions and general information about OpenBIOS, subscribe to the +OpenBIOS mailing list, at: + +- <http://www.openfirmware.info/mailman/listinfo/openbios> + +A mailing list archive dating back as far as February 1998 can be found +at: + +- <http://www.openfirmware.info/pipermail/openbios> diff --git a/Documentation/website/News.md b/Documentation/website/News.md new file mode 100644 index 0000000..cb3eea3 --- /dev/null +++ b/Documentation/website/News.md @@ -0,0 +1,225 @@ +# News +**FCODE suite 1.0.2 released** (2006-10-30) + +[David Paktor](mailto:David@paktor.biz) sent a new fork of the +[OpenBIOS FCODE suite](FCODE_suite). After only a +couple of days we finally got this merged into the official code base. + +**LinuxBIOS Symposium 2006** (2006-10-01) + +The first European [LinuxBIOS Symposium +2006](http://www.linuxbios.org/index.php/LinuxBIOS_Symposium_2006) took +place in Hamburg from October 1st to 3rd. This event was organized by +[coresystems GmbH](http://www.coresystems.de). + +**FCODE suite 1.0.1 available** (2006-09-21) + +[David Paktor](mailto:David@paktor.biz), on behalf of the IBM +Corporation, contributed to the [OpenBIOS FCODE suite](FCODE_suite). This release has +higher test coverage, a more detailed report on one type of error, and +removal of dead code and consolidation of some other code. + +**SUN released OpenBOOT source code** (2006-09-06) + +[SUN microsystems](http://www.sun.com/) has recently released their +OpenBOOT source code to the community under a BSD license. Go to their +[OpenSparc T1 +website](http://opensparc-t1.sunsource.net/download_sw.html)\] to +download the full archive (190MB) or check out our [local +mirror](http://www.openbios.org/~stepan/sun-obp.tar.bz2) (1.7MB). + +**New FCODE suite available** (2006-08-08) + +[David Paktor](mailto:David@paktor.biz), on behalf of the IBM +Corporation, contributed some groundbreaking feature updates to the +OpenBIOS FCODE utilities toke, detok and romheaders. Find details and +binaries here + +**Sparc32 support in development** (2006-05-05) + +OpenBIOS has a port for 32bit Sparc CPUs now. The initially targeted +milestone is to get a full firmware implementation for the QEMU project. + +**OpenBIOS switched to Subversion** (2006-04-26) + +See the [development repository](OpenBIOS) for more +information. + +**Bugfix version of tokenizer toke** (2005-10-15) + +Version 0.6.10 of the OpenBIOS tokenizer toke has been released. This is +a bugfix release. + +**New version of toke** (2005-10-05) + +Version 0.6.9 of the OpenBIOS tokenizer toke has been released. This is +a bugfix release. + +**New versions of toke and detok** (2005-03-10) + +New versions of the OpenBIOS utilities have been released: The tokenizer +toke 0.6.8 and the detokenizer detok 0.6.1. + +**Stallman calls for action on Free BIOS** (2005-02-26) + +FSF President Richard M. Stallman was calling for action on free BIOS in +his speech at FOSDEM 2005. Read about The Free Software Foundation's +Campaign for Free BIOS. + +**Portability and cross development** (2005-01-12) + +OpenBIOS is pushing towards new hardware platforms. Improvements in the +cross compilation ability of OpenBIOS are currently merged into a +seperate development tree. This will allow to develop and test OpenBIOS +for ARM, PPC, AMD64 and others just using an ordinary PC. + +**OpenBIOS boots, part II** (2004-08-01) + +After some major cleanup, OpenBIOS now also boots on real PPC hardware: +The Total Impact Briq. + +**Linux Tag** (2004-06-27) + +The OpenBIOS team went to the LinuxTag, hacking and chatting at the +Forth e.V. booth. OpenBIOS can run forth files from a filesystem now and +it has a preliminary PCI driver. + +**OpenBIOS boots** (2004-05-23) + +After many bugfixes OpenBIOS booted Linux on real hardware now (AMD64 +and x86). + +**IDE support** (2004-01-23) + +Jens Axboe wrote an IDE driver for OpenBIOS. This will help OpenBIOS to +boot on real hardware soon. + +**Device and Client Interface** (2004-01-10) + +OpenBIOS' interfaces for device and client (OS) interaction are +basically finished. When used in MacOnLinux (MOL), OpenBIOS can boot +MacOS and Linux. + +**Bitkeeper repository** (2003-12-20) + +Most of OpenBIOS moved to a bitkeeper repository. Check out +bk://openbios.bkbits.net/unstable for the latest development tree. + +**Toke and Detok update** (2003-11-29) + +Toke and Detok, OpenBIOS' FCode toolchain, have been updated. Toke can +now be used to directly create PCI Option ROMs with FCode. Both toke and +detok got a couple of bugfixes and integrate cleanly in the OpenBIOS +build process now. + +**OpenBIOS forth kernel 1.1** (2003-10-12) + +After the first release here's an update with some fixes, optimized +speed and a plugin system that allows easier development under a +Linux/Unix system. + +**OpenBIOS forth kernel released** (2003-09-16) + +After some months of development we are happy to announce the new +OpenBIOS forth kernel "BeginAgain". + +**New domain: openbios.org!** (2003-08-23) + +We got it! After many years of hazzling with a domain grabber we finally +got the domain [openbios.org](http://openbios.org/). + +**dictionary dumping** (2002-10-16) + +OpenBIOS' forth kernel paflof knows how to dump dictionaries now. Read +more information on how to use this feature in the +[mailing list archive](Mailinglist). + +**LinuxFund.org** (2002-07-04) + +OpenBIOS is one out of three projects funded in LinuxFund.org's Spring +Grant Cycle 2002. The Development Grant of \$1000 will be used to +advance the project. + +**toke and detok update** (2002-05-26) + +Toke 0.4 and detok 0.5.2 have been released. Detok has some new +features, such as line numbers or byte offsets, proper checksum +calculations, 64bit opcodes and several bug fixes. Toke comes with +better error messages, working case...endcase constructs, improved +number parsing, better IEEE compliance and less bugs. + +**toke 0.2 released** (2002-03-20) + +The new version of toke is quite an improvement compared to the last +release. Most of the missing control words and tokenizer directives are +supported now, string handling was improved, error messages and warnings +contain line numbers etc. This component needs heavy testing. + +**toke 0.1 released** (2002-03-04) + +Time is passing by and the OpenBIOS project has a tokenizer now. Even +though some things are yet missing, it is capable to tokenize quite a +huge amount of test code fed into it. + +**detok 0.3 released** (2002-02-26) + +The IEEE-1275 FCode detokenizer got some cleanup. Dictionary is no more +autogenerated, memory consumption reduced by almost 70%. + +**/dev/bios 0.3.2 released** (2002-02-19) + +After having almost no releases in the last 2 years, /dev/bios shows up +in version 0.3.2 now. It has support for NSC CS5530(A), AMD 7xx, +ServerWorks, Intel 4x0/8xx and other chipsets. + +**new version of /dev/bios available** (2002-02-15) + +The kernel level firmware flasher /dev/bios is under control of the +OpenBIOS CVS now. /dev/bios now supports quite a big number of +motherboard chipsets. + +**new version of feval released** (2001-12-16) + +FCode evaluator feval-0.2.6 released. This is a bug fix release. + +**Talk to us LIVE!** (2001-12-03) + +Yesterday we moved from IRCNet to irc.freenode.net. You can talk with us +at \#OpenBIOS usually all the day (CET timezone) + +**new version of detok released** (2001-12-02) + +FCode detokenizer detok-0.2.3 released. This version should compile on +any ANSI C Compiler and has corrected FCode names. Check the status page +for more details. + +**OpenBIOS is now under control of CVS** (2001-11-12) + +The OpenBIOS development CVS is up and running. + +**new version of feval released** (2001-11-08) + +FCode evaluator feval-0.2.5 released. This version has preliminary +package support. + +**new version of detok released** (2001-10-15) + +FCode detokenizer detok-0.2.2 released. This version fixes indentation +and a string allocation error. + +**new version of detok and feval released** (2001-09-16) + +Update: FCode evaluator feval-0.2 and detokenizer detok-0.2.1 available +now. + +**we now have a detokenizer** (2001-09-09) + +There's a first version of an fcode detokenizer now. This is the first +part of the OpenBIOS development suite. + +**general news on bios-coding** (2000-02-13) + +The LinuxBIOS Project replace the firmware of their Rockhopper cluster +machines with a special Linux kernel image, and instead of running the +BIOS on startup they run Linux. For information and patches, check out +their homepage at <http://www.linuxbios.org/>. diff --git a/Documentation/website/OFW_as_a_coreboot_Payload.md b/Documentation/website/OFW_as_a_coreboot_Payload.md new file mode 100644 index 0000000..58a0cd9 --- /dev/null +++ b/Documentation/website/OFW_as_a_coreboot_Payload.md @@ -0,0 +1,65 @@ +# OFW as a coreboot payload +This page tells how to build Open Firmware as a coreboot payload and run +it under QEMU. You can also run Open Firmware under QEMU without +coreboot: + +- You can build a QEMU ROM image directly from code in the OFW tree - + see [Building OFW for QEMU](Building_OFW_for_QEMU). +- You can boot OFW from a conventional BIOS - see + [Building OFW to Load from BIOS](Building_OFW_to_Load_from_BIOS) + +## Software Requirements + +- qemu-0.9.1 +- Open Firmware rev. \>= 1051 +- coreboot \>= v2 +- GCC and GNU make - OFW builds with most versions; I'm not sure which + versions coreboot needs + +## Building Open Firmware + +Download the Open Firmware source: + + svn co svn://openfirmware.info/openfirmware + +Configure OFW for coreboot: + + cd openfirmware/cpu/x86/pc/biosload + cp config-coreboot.fth config.fth + +Build OFW: + + cd build + make + +After make is finished (it shouldn't take long) there should be a file +"ofwlb.elf" in the same directory. Copy this to your coreboot-v\[x\] +directory. + +## Building coreboot + +Follow the instructions in the coreboot documentation, using ofwlb.elf +as your payload file. + +## Getting QEMU + +Get QEMU \>= 0.9.1 from <http://bellard.org/qemu/download.html> + +Version 0.9.1 should "just work". It supports reasonably large ROM +images, determining the emulated ROM size from the size of the image +file. There was a "qemu_biossize.patch" for qemu-0.9.0, but the site +that hosted that patch is defunct. + +## Run Your ROM Image + + qemu -L coreboot-v3/build -hda path/to/disk.img -serial `tty` -nographic + +## Ideas for Improvement + +These instructions build a rather plain OFW configuration that lacks +drivers for several of QEMU's specific I/O devices (Ethernet, video, +sound). Suitable drivers are in the OFW tree, and are included in the QEMU +build described in [Building OFW for QEMU](Building_OFW_for_QEMU). It +would be nice to add those drivers to the configuration described +herein. If the Cirrus video driver were added, qemu could be used in +graphic mode. diff --git a/Documentation/website/On_the_Net.md b/Documentation/website/On_the_Net.md new file mode 100644 index 0000000..64d256e --- /dev/null +++ b/Documentation/website/On_the_Net.md @@ -0,0 +1,109 @@ +# On the Net + +## Open Firmware Companies/Vendor support + +- [CodeGen](http://www.codegen.com) +- [FirmWorks](http://www.firmworks.com) +- [SUN](http://www.sun.com) +- [IBM](http://www.ibm.com) +- [coresystems GmbH](http://www.coresystems.de) + +## Open Firmware Documentation + +- [What is Open Firmware?](http://www.firmworks.com/www/ofw.htm) +- [Hardware Independant Boot + Code](http://playground.sun.com/pub/1275/mejohnson/) - - An Open + Firmware description at an introductory level by Matthew Johnson +- [Open Firmware homepage](http://www.openfirmware.org/) +- [The OpenFirmware IEEE 1275-1994](http://playground.sun.com/pub/1275/) +- [Writing FCode 3.x + Programs](ftp://docs-pdf.sun.com/806-1379-10/806-1379-10.pdf) +- [OpenBoot 3.x Command Reference + Manual](ftp://docs-pdf.sun.com/806-1377-10/806-1377-10.pdf) +- [OpenBoot 3.x Quick + Reference](ftp://docs-pdf.sun.com/806-2908-10/806-2908-10.pdf) + +## Forth + +- [Forth FAQ](http://www.faqs.org/faqs/computer-lang/forth-faq/) +- [kForth](http://ccreweb.org/software/kforth/kforth4.html) - + programming examples +- DPANS'94 \[ + [HTML](http://forth.sourceforge.net/standard/dpans/index.html) \] \| + \[ [PDF](http://www.openfirmware.info/data/docs/dpans94.pdf) \] - very + interesting: annex D and E. +- [Gforth](http://www.jwdt.com/~paysan/gforth.html) - Forth + implementation of the GNU project +- [PFE](http://pfe.sourceforge.net/) - The Portable Forth Environment is + based on the ANSI Standard for Forth. It is targeted for embedded + environments. +- [vnpforth](http://www.geocities.com/simon_baldwin/packages/) - + contains a traditional compiler, which turns Forth into standard + object (.o) files +- [Moving Forth](http://zetetics.com/bj/papers/) - Article on writing + Forth Kernels by Brad Rodriguez +- [Hayes ANS compliance test](http://www.taygeta.com/forth.html) - a + test for ANS Forth compliance by John Hayes. The OpenBIOS forth kernel + passes this test. +- [gfob](ftp://ftp.taygeta.com/pub/Forth/Tools/gfob-0.1.0.tar.gz) - a + forth source obfuscator +- [Thoughtful Programming and + Forth](http://www.ultratechnology.com/forth.htm) - an essay by Jeff + Fox. +- [Selected Forth Papers](http://www.theforthsource.com/fp000.html) - at + theforthsource.com + +## Stack Machines + +- [Stack Computers: the new + wave](http://www-2.cs.cmu.edu/~koopman/stack_computers/) - Philip J. + Koopman Jr's book on stack computers offered as pdf and html. + +## Booting + +- [Multiboot + standard](ftp://flux.cs.utah.edu/flux/multiboot/MultiBoot.html) +- [GRUB - GRand Unified Bootloader](http://www.gnu.org/software/grub/) +- GRUB2 +- [Nilo](http://www.nilo.org/) - Network Interface Loader. NILO will + boot Linux, FreeBSD, Windows 95/98/NT4 and support the Intel PXE + standard. +- [Etherboot](http://www.etherboot.org) +- Redboot + +## Flashing on Linux Systems + +- [MTD](http://www.linux-mtd.infradead.org/) - Memory Technology Device + Subsystem for Linux +- /dev/bios - Flash ROM driver for Linux (for flashing System and PCI + adapter firmware) (obsolete) +- [Uniflash](http://www.uniflash.org/) (nonlinux) +- flashrom ([coreboot](http://www.coreboot.org/Flashrom)) + +## Other Open Source Firmware Implementations + +- [coreboot](http://www.coreboot.org/) - The coreboot project bootstraps + systems to the point where they can run an OS kernel or any other + application or bootloader from flash. +- [TIARA](http://sourceforge.net/projects/utcboot/) - TIARA, an + Openbios/GRUB/PFORTH composite, BIOS replacement (dead?) +- [Proll](http://people.redhat.com/zaitcev/linux/) - Proll is a firmware + replacement for SUN JavaStations to boot Linux +- [GNUFI](http://gnufi.blogspot.com/), an open source EFI implementation +- [redboot](http://cygwin.com/redboot/) +- SLOF +- [Open Hackware](http://perso.magic.fr/l_indien/OpenHackWare/) +- SUN OpenBoot +- [GBIOS](http://www.humboldt.co.uk/gbios.html) - GBIOS is a GPLed + firmware for PowerPC G3/G4 and some Motorola cpus. (dead?) +- ... + +## Virtual Machines and Emulation + +- [QEMU](http://www.qemu.com/) +- [XEN](http://www.cl.cam.ac.uk/research/srg/netos/xen/) Virtualization +- [Bochs](http://bochs.sourceforge.net/) - portable open source IA-32 + (x86) PC emulator +- [DOSemu](http://www.dosemu.org/) - DOS Emulation for Linux +- Hypervisor +- ... diff --git a/Documentation/website/OpenBIOS.md b/Documentation/website/OpenBIOS.md new file mode 100644 index 0000000..0a4f476 --- /dev/null +++ b/Documentation/website/OpenBIOS.md @@ -0,0 +1,214 @@ +# OpenBIOS + +Welcome to the OpenBIOS download page. Here you'll find releases of +OpenBIOS components. + +After 4 years of hard work, OpenBIOS v1.1 has been released. The new +features include: + +* Internal memory API (OFMEM) implementation +* Forth Source Debugger +* 64-bit 1275 6d5 implementation +* Forth Local Variables +* Internal libopenbios code reorganisation + +See the [OpenBIOS issue +tracker](https://github.com/openbios/openbios/issues) for milestones, +tasks and open bugs. + +# OpenBIOS - Code Releases + +Download the latest release of OpenBIOS including the Forth kernel and +all of the IEEE 1275-1994 compliant Forth code for user interface, +client interface and device interface. + +Latest release version is: [OpenBIOS +1.1](https://github.com/openbios/openbios/archive/v1.1.zip) (2013-05-04) + +**NOTE:** The FCODE utilities are no longer part of the main OpenBIOS +distribution. Have a look at the +[FCODE suite](FCODE_suite) if you are looking for toke and detok. + +# Status and use cases + +OpenBIOS can be used directly as a boot ROM for [QEMU](http://qemu.org/) +system emulators for PPC, PPC64, Sparc32 and Sparc64. + +OpenBIOS/SPARC32 is currently able to boot the following OS/kernels: + +* Linux +* NetBSD +* OpenBSD +* Solaris + +OpenBIOS/SPARC64 is currently able to boot the following OS/kernels: + +* Linux +* NetBSD +* OpenBSD +* FreeBSD +* HelenOS + +OpenBIOS/PPC is currently able to boot the following OS/kernels: + +* Linux +* HelenOS +* Darwin/Mac OS X + +The following operating systems will partially boot, but may suffer from +some emulation bugs under QEMU: + +* FreeBSD +* NetBSD +* Mac OS 9 + +[coreboot](http://www.coreboot.org) can use OpenBIOS as a payload on +x86. + +Do not try to put OpenBIOS in a real boot ROM, it will not work and may +damage your hardware! + +## Kernel + +There is also an ancient stand-alone version of the OpenBIOS Forth +kernel *BeginAgain*. + +The last released stand-alone version is: [BeginAgain +1.1](http://www.openbios.org/data/bin/kernel-1.1.tar.bz2) (2003-10-12). + +**NOTE:** You should use the latest version of *BeginAgain* that is +present in the complete *OpenBIOS release* above. It is much newer than +*BeginAgain 1.1* and it supports cross compiling and lots of other nifty +features. *BeginAgain 1.1* is here for educational purposes only: The +core binary is only 6k on x86. + +# Development Environment + +## FCode Suite + +To download the latest version of the FCode Suite, including an FCode +detokenizer, an FCode tokenizer and the romheader utility, please go to +the [FCode Suite page](FCODE_suite). + +## Flashing + +/dev/bios is obsolete and has been replaced by a new and better +utility. Please download a coreboot snapshot and use the [flashrom +utility](FlashRom) from *coreboot-v2/util/flashrom*. + +# Development Repository + +OpenBIOS keeps its development tree in a [git](http://git-scm.com/) +repository. If you do not want to use git, please have a look at the +Snapshots below. + +## Anonymous access + +You can check it out as follows: + + $ git clone https://github.com/openbios/openbios.git + +or for checking out the source code for the OpenBIOS FCode Suite: + + $ git clone https://github.com/openbios/fcode-utils.git + +## Developer access + +Access for developers is very similar to anonymous access. Just add your +github username as follows when checking out the repository: + + $ git clone https://username@github.com/openbios/openbios.git + +# Source code browsing + +You can also browse the [OpenBIOS github repository](https://github.com/openbios/openbios) online. + +# Snapshots + +There is currently no archive of snapshots available for OpenBIOS. You +can use the [source code browser](https://github.com/openbios/openbios) +to download a ZIP archive of any revision. + +Alternatively you can also download the [most current +snapshot](https://github.com/openbios/openbios/archive/master.zip) +directly. + +# Building OpenBIOS + +Download fcode suite: + + $ git clone https://github.com/openbios/fcode-utils.git + +Build the needed programs inside the fcode-utils-devel folder: + + $ make + +Install the programs: + + $ make install + +Download OpenBIOS: + + $ git clone https://github.com/openbios/openbios.git + +Select the build targets: + + $ ./config/scripts/switch-arch sparc32 sparc64 x86 ppc amd64 + +Build OpenBIOS: + + $ make + +or + + $ make build-verbose + +OpenBIOS can even be cross-compiled on a host which is different type +(big vs. little endian and 32 vs. 64 bits) from the target. At least +Linux and OpenBSD hosts are known to work. + +If your cross tools use different prefix from what the makefiles assume, +the prefix can be overridden with: + + $ make build-verbose TARGET=powerpc-elf- + +or + + $ make -C obj-ppc CC=powerpc-elf-gcc + +The OpenBIOS binaries (typically openbios-builtin.elf) can be found in +obj- subdirectories. The Unix executable version (native only) is named +openbios-unix. + +# Additional Resources + +[PowerPC, x86, ARM, and Sparc elf cross-compilers for Mac OS +X](http://www.mediafire.com/download/wy5xgj2hwjp8k4k/AWOS_Cross-Compilers.zip) + +- This compiler uses a unsupported compiler prefix. To use it, set the + `CROSS_COMPILE` variable to "ppc-elf-" before running the switch-arch + script. + +Example: + + CROSS_COMPILE=ppc-elf- ./switch-arch ppc + +# Notes for Building on Mac OS X + +There is a known build issue when building on Mac OS 10.6. The +switch-arch script will report your computer as 32 bit (x86) when it is +really 64 bit (amd64). If you see the message "*panic: segmentation +violation at …*" while building, you probably have this problem. + +If this happens to you, try setting the HOSTARCH variable before using +the switch-arch script. + +Example: + + HOSTARCH=amd64 ./switch-arch ppc + +# Troubleshooting + +Seeing this message: *Unable to locate toke executable from the +fcode-utils package - aborting* +- Install the fcode suite first before trying to build OpenBIOS. diff --git a/Documentation/website/OpenBOOT.md b/Documentation/website/OpenBOOT.md new file mode 100644 index 0000000..bbba093 --- /dev/null +++ b/Documentation/website/OpenBOOT.md @@ -0,0 +1,17 @@ +# OpenBOOT +## Introduction + +In 2006 [Sun Microsystems](http://sun.com/) released their Open Firmware +implementation OpenBoot under a BSL like license. Their code supports +the sun4v architecture running on a hypervisor. + +## Download + +You can [browse the source code +online](https://github.com/openbios/openboot). + +The repository is available through git: + +You can check it out as follows: + + $ git checkout https://github.com/openbios/openboot.git diff --git a/Documentation/website/Open_Firmware.md b/Documentation/website/Open_Firmware.md new file mode 100644 index 0000000..a8be68f --- /dev/null +++ b/Documentation/website/Open_Firmware.md @@ -0,0 +1,65 @@ +# Open Firmware +## Introduction + +In 2006 the company of Open Firmware inventor Mitch Bradley, [Firmworks, +Inc](http://firmworks.com/), released their Open Firmware implementation +(OFW) under a BSD license. This code shares some code with SUN's +OpenBOOT implementation. The open source OFW supports x86, PowerPC, and +ARM architectures. Other architectures, including SPARC and MIPS, may be +added as time and interest dictate. + +The x86 version is used on the OLPC "XO" computer. The x86 version can +be configured for numerous other environments, including + +- Direct QEMU ROM (replacing the "bios.bin" that is supplied with QEMU +- Coreboot payload +- Loadable on directly on top of a conventional PC BIOS (booted from + floppy or hard disk like an OS). In this configuration it can run on + an arbitrary PC, or on an emulator like QEMU, VirtualBox, or VMWare. + +OFW can boot Linux directly from a disk file (FAT, ext2, ISO9660, or +jffs2 filesystems) without the need for an intermediate bootloader like +LILO or GRUB. The Linux image can be in either ELF format (as created by +the first phase of the Linux kernel compilation process) or in the +"bzImage" format that "wraps" the ELF image. When booting an ELF image, +OFW can read the ELF symbol table so OFW's assembly language debugger +can resolve kernel symbols. + +OFW can also boot other ELF standalone images, providing to them +rudimentary "libc" capability. That facility has been used for booting, +for example, Minix, ReactOS, Plan9, Inferno and SqueakNOS. The OLPC +system ROM includes several such "standalone client programs", including +MicroEMACS, memtest86, and NANDblaster (a facility for fast OS updates +over multicast wireless). + +On the OLPC system, OFW emulates enough legacy BIOS "real mode INTs" to +boot Windows XP. On another system, OFW supports booting Windows CE. + +## Download + +You can [browse the source code +online](https://github.com/openbios/openfirmware). + +The repository is available through git: + +You can check it out as follows: + + $ git checkout https://github.com/openbios/openfirmware.git + +## Building Different Versions + +- Direct QEMU ROM: see [Building OFW for QEMU](Building_OFW_for_QEMU) +- Coreboot: see [OFW as a Coreboot Payload](OFW_as_a_coreboot_Payload) +- OLPC: see [Building OFW for OLPC](Building_OFW_for_OLPC) +- BIOS-loaded: see [Building OFW to Load from BIOS](Building_OFW_to_Load_from_BIOS) +- ARM: see [Building OFW for ARM](Building_OFW_for_ARM) + +## Mailing List + +There's an Open Firmware mailing list at: + +- <http://www.openfirmware.info/mailman/listinfo/openfirmware>. + +The mailing list archive is also available: + +- <http://www.openfirmware.info/pipermail/openfirmware/> diff --git a/Documentation/website/README.md b/Documentation/website/README.md new file mode 100644 index 0000000..9e23123 --- /dev/null +++ b/Documentation/website/README.md @@ -0,0 +1,10 @@ +To build the docs, you'll need sphinx and a few extensions that are listed in `conf.py`. + +A simple way to get a working setup is to install `pipx`, then run: + +``` +$ pipx install sphinx +$ pipx inject sphinx {the extensions} +``` + +Afterwards, building the docs is a single command: `sphinx-build $srcdir $destdir` diff --git a/Documentation/website/SLOF.md b/Documentation/website/SLOF.md new file mode 100644 index 0000000..231f1fe --- /dev/null +++ b/Documentation/website/SLOF.md @@ -0,0 +1,17 @@ +# SLOF +Slimline Open Firmware (SLOF) is initialization and boot source code +based on the IEEE-1275 (Open Firmware) standard, developed by engineers +of the IBM Corporation. + +The SLOF source code provides illustrates what's needed to initialize +and boot Linux or a hypervisor on the industry Open Firmware boot +standard. + +Currently the SLOF source code is hosted on github at +<https://github.com/aik/SLOF/> and provides: + +- Documentation +- An Open Firmware implementation for prototyping, test, and debug +- Low Level Firmware for IBM's JS20, JS21 and the YDL PowerStation + (partially closed source) +- Firmware for the emulated 'pseries' machine of QEMU diff --git a/Documentation/website/SmartFirmware.md b/Documentation/website/SmartFirmware.md new file mode 100644 index 0000000..2884aec --- /dev/null +++ b/Documentation/website/SmartFirmware.md @@ -0,0 +1,25 @@ +# SmartFirmware +## Introduction + +In 2006 [CodeGen, Inc](http://codegen.com/) released their Open Firmware +implementation under a BSL like license. Their code, entirely written in +ANSI C, contains the following components: + +- [SmartFirmware™](http://www.codegen.com/SmartFirmware/index.html): an + ANSI C implementation of the IEEE-1275 Open Firmware boot firmware + standard. Dramatically reduce and ease your firmware development and + system bring-up times and costs. +- An [ANSI C + compiler](http://www.codegen.com/SmartFirmware/ccfcode.html) that + generates Open Firmware compatible Forth/Fcode makes it easy to + develop drivers for PCI cards and PMC modules. + +## Download + +You can [browse the code online](https://github.com/openbios/smartfirmware). + +The repository is available through git: + +You can check it out as follows: + + $ git checkout https://github.com/openbios/smartfirmware.git diff --git a/Documentation/website/_toc.yml b/Documentation/website/_toc.yml new file mode 100644 index 0000000..63b5e80 --- /dev/null +++ b/Documentation/website/_toc.yml @@ -0,0 +1,46 @@ +root: index +defaults: + titlesonly: True +subtrees: +- entries: + - file: Contact_us + - file: Mailinglist + - file: Code_of_Conduct + - file: Credits + - file: Licensing + entries: + - file: GPLv2 +- caption: Implementations + titlesonly: True + entries: + - file: Open_Firmware + entries: + - file: Building_OFW_for_QEMU + - file: OFW_as_a_coreboot_Payload + - file: Building_OFW_for_OLPC + - file: Building_OFW_to_Load_from_BIOS + - file: Building_OFW_for_ARM + - file: SmartFirmware + - file: OpenBOOT + - file: OpenBIOS + entries: + - file: How_to_build_OpenBIOS_on_Mac_OS_X + - file: SLOF +- caption: Development + entries: + - file: FCODE_suite + - file: BeginAgain + - file: FlashRom + - url: https://github.com/openbios/openbios/issues + title: Issues/Bugs +- caption: Documentation + entries: + - file: IEEE_1275-1994 + - file: Bindings + - file: Forth_FCode + - file: News + - file: On_the_Net +- caption: Tutorials + entries: + - file: Adding_words_to_openbios + - file: How_Local_Variables_in_Forth_Work diff --git a/Documentation/website/conf.py b/Documentation/website/conf.py new file mode 100644 index 0000000..27b08dd --- /dev/null +++ b/Documentation/website/conf.py @@ -0,0 +1,34 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'OpenBIOS' +copyright = '2025, The OpenBIOS authors' +author = 'The OpenBIOS authors' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['myst_parser', 'sphinx_external_toc', 'sphinx_reredirects'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md'] + +redirects = { + "License": "Licensing.html", + "OpenBoot": "OpenBOOT.html", + "Project_Statement": "Code_of_Conduct.html", + "Releases": "OpenBIOS.html", + "Building_OFW_to_Run_Under_BIOS": "Building_OFW_to_Load_from_BIOS.html", +} + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/Documentation/website/index.md b/Documentation/website/index.md new file mode 100644 index 0000000..8d6b319 --- /dev/null +++ b/Documentation/website/index.md @@ -0,0 +1,83 @@ +# Welcome to OpenBIOS + +The **OpenBIOS** project provides you with most free and open source +Open Firmware implementations available. Here you find several +implementations of IEEE 1275-1994 (Referred to as Open Firmware) +compliant firmware. + +Among its features, Open Firmware provides an instruction set +independent device interface. This can be used to boot the operating +system from expansion cards without native initialization code. + +It is Open Firmware's goal to work on all common platforms, like x86, +AMD64, PowerPC, ARM, Sparc and Mips. With its flexible and modular +design, Open Firmware targets servers, workstations and embedded +systems, where a sane and unified firmware is a crucial design goal and +reduces porting efforts noticably. + +Open Firmware is found on many servers and workstations and +there are several commercial implementations from [SUN](OpenBOOT), +[Firmworks](Open_Firmware), [CodeGen](SmartFirmware), Apple, [IBM](SLOF) +and others. + +In most cases, the Open Firmware implementations provided on this site +rely on an additional low-level firmware for hardware initialization, +such as [coreboot](http://www.coreboot.org/) or +[U-Boot](http://www.denx.de/wiki/U-Boot). + +## Download +Get the latest version of OpenBIOS. See the [development download +page](OpenBIOS). Have a look at the Implementations section on the +left side. + +## Contact +The easiest way to get in contact with the OpenBIOS team is +to subscribe the OpenBIOS mailinglist. If you want to contribute to +OpenBIOS development, you should subscribe to the mailinglist as well. +See further information on the [Mailinglist](Mailinglist) page. + +## Credits +Who are the people behind OpenBIOS? Who helped and contributed to make +OpenBIOS as successful as it is today. See the growing [Credits](Credits) +page for a (yet incomplete) list of people contributing to OpenBIOS with +hardware, patches, code, hints, etc. + +## News +### OpenBIOS v1.1 released (2013-05-04) +After 4 years of hard work, the OpenBIOS team are proud to announce +the release of OpenBIOS 1.1. Since the last release, over 600 commits +have been made to the SVN repository with a wealth of improvements and +new features. As a result of these changes, the ability of OpenBIOS 1.1 +to boot various kernels under QEMU has significantly improved. For more +information, please visit the [development page](OpenBIOS). + +### OpenBIOS v1.0 released (2009-03-01) +OpenBIOS v1.0 has been released. For more information, please visit +the [development page](OpenBIOS). + +### FCODE suite 1.0.2 released (2006-10-30) +[David Paktor](mailto:David@paktor.biz) added tracing support to the +[OpenBIOS FCODE suite](FCODE_suite). + +### LinuxBIOS Symposium 2006 (2006-10-01) +The first European [LinuxBIOS Symposium +2006](http://www.coreboot.org/index.php/LinuxBIOS_Symposium_2006) took +place in Hamburg from October 1st to 3rd. This event was organized by +[coresystems GmbH](http://www.coresystems.de/).</p> + +### FCODE suite 1.0.1 available (2006-09-21) +[David Paktor](mailto:David@paktor.biz), when he was with +the IBM Corporation, contributed to the [OpenBIOS FCODE suite](FCODE_suite). + +This release has higher test coverage, a more detailed report on one +type of error, and removal of dead code and consolidation of some other +code. + +### SUN released OpenBOOT source code (2006-09-06) +[SUN microsystems](http://www.sun.com/) has recently released their +OpenBOOT source code to the community under a BSD license. Go to their +[OpenSparc T1 website](http://opensparc-t1.sunsource.net/download_sw.html) +to download the full archive (190MB) or check out our [local +mirror](OpenBOOT) (1.7MB). + +[older news](News) |