OFW FAQ
vareleltch
Introduction
Open Firmware is an interactive firmware system that can do boot loading, system test, and many other things. It contains a complete interactive programming language (Forth) with thousands of commands. A brief description of the most important commands can be found at http://firmworks.com/QuickRef.html .
There is a series of introductory lessons about Forth and Open Firmware.
Booting
What is the auto-boot sequence?
The usual way to boot from Open Firmware is just to let it auto-boot, i.e. turn on the power and leave the system alone. It will first try to find a Linux kernel on a USB mass storage device (disk or FLASH key), and if it doesn't find one there, it will look on the NAND FLASH. The file it looks for is /boot/vmlinuz. It also looks for /boot/initrd.img and loads that as a ramdisk if it finds it.
How do I stop it from auto-booting?
After Open Firmware has located all of the I/O devices, it turns on the screen and then waits a few seconds to see if you want to grab control. Just hold down the 'X' game pad button (just above the power button). The prompt will tell you when to release the button, and then ask you to press "Esc" to interrupt automatic boot. The 'Esc' key is the white-x-in-a-black-circle key in the top-left corner. At that point you should have an "ok" (Forth) prompt. From that prompt you can do just about anything ...
(If you have a serial console, you can type Enter on it during boot: that will give you an open firmware prompt on the serial console.)
How do I boot from the ok prompt?
Just type "boot".
But see the next topic...
How do I boot from NAND Flash
If you just let OFW auto-boot, booting from NAND FLASH should just work, provided that there is no USB disk with a valid kernel (/boot/vmlinuz) or boot script (/boot/olpc-boot.fth).
If you want to boot from NAND FLASH manually (i.e. from the ok prompt), you will first have to set the boot-file , boot-device , and ramdisk configuration variables. There are three ways to do that:
- If your NAND FLASH has a kernel in the standard place, i.e. /boot/vmlinuz , you can just type boot-configure at the ok prompt, and the system will set up the configuration variables for you. But if you also have a USB storage device with a kernel, boot-configure will set up for it in preference to the NAND kernel. So unplug your USB device if you want to use NAND.
- You can use editenv or setenv to set the variables; see setenv and editenv instructions below
- You can put setenv commands into a /boot/olpc-boot.fth file on the NAND FLASH filesystem (using a text editor under Linux). But, as before, a USB setup will take priority.
After you have set the configuration variables, just type boot
How can I set up custom cmdlines and stuff?
There are three configuration variables that control the booting process:
- boot-device - This is the device and file path to the kernel. Example: disk:\boot\vmlinuz or nand:\boot\vmlinuz
- boot-file - This is the kernel command line (the unfortunate name is historical) Example: quiet root=sda1 rootfstype=ext3
- ramdisk - This is the device and file path to the initrd. If null, no initrd will be loaded. Example: disk:\boot\initrd.img
Their default values are suitable for booting from a USB storage device. As described above, boot-configure will set the values of these variables to baseline values typical for the first device that has either /boot/olpc-boot.fth or /boot/vmlinuz , trying USB first and then NAND FLASH.
You can set values manually with:
setenv boot-device nand:\boot\vmlinuz setenv boot-file ro quiet root=mtd0 rootfstype=jffs2 setenv ramdisk
You can make small changes to existing values with:
editenv boot-file
then use arrow keys, backspace, etc. to change the value. If the value is longer than the screen width, it will scroll automatically when the cursor is at the edge of the screen. Type Enter when you are done editing, and type 'y' to confirm the edit.
Basic Forth
See also the Forth Lessons written by Mitch Bradley.
What is Forth stack notation?
The stack effect of a Forth word - i.e. the arguments it pops from the stack and the results is pushes back - is conventionally described as follows:
foo ( a b c -- d e )
means that the word "foo" pops three arguments (numbers) from the stack (c from the top of stack), and pushes two results back (e on the top).
The item names (a, b, etc) are clues about what kind of number it is, e.g. 'adr' for address, 'n' for number, 'b' for 8-bit number, 'w' for 16-bit number, 'l' for 32-bit number, 'flag' for boolean result. For multiple items of the same type the convention is "( n1 n2 -- n3 )".
How do I do x86 I/O port accesses in the OFW interpreter?
pc@ ( port# -- byte ) \ Read from an 8-bit I/O port pw@ ( port# -- word ) \ Read from a 16-bit I/O port pl@ ( port# -- long ) \ Read from a 32-bit I/O port pc! ( byte port# -- ) \ Write to an 8-bit I/O port pw! ( word port# -- ) \ Write to a 16-bit I/O port pl! ( long port# -- ) \ Write to a 32-bit I/O port
c is byte, w is short, l is long.
@ is conventional notation for read, takes port# from stack and leaves value on stack
! is convetnional notation for write, takes port# from top of stack and value from underneath that.
for example: 45 66 pc! writes 0x45 to port 0x66 as a byte
How do I do Geode MSR accesses in the ofw interpreter?
rdmsr ( addr -- value.low value.high ) wrmsr ( value.low value.high addr -- )
for example: 10 rdmsr u. u. reads and prints the x86 time stamp counter (MSR 0x10)
How do I enter numbers?
Typing a number pushes it on the stack.
OFW defaults to hex radix. If you want a decimal number, precede it with "d# ", as in "d# 99". You can also say "h# 12ab" if you want to be explicit about the hex radix.
For clarity, you can embed punctuation in numbers. I usually write long hex numbers with a period at position 4, e.g. "c000.2001" so I don't have to count 0's when looking at the number. You can also embed ',' e.g "d# 1,000,000". I usually use comma every third position for decimal numbers.
What does the "p" stand for in I/O access words (e.g. pc@ )?
port
I read some MSRs and "." printed them as signed. Is there a better way to print?
. pops stack and displays signed number in default radix.
u. displays unsigned.
.x or .h displays in hex.
.d displays in decimal.
How can I watch what's on the stack?
showstack \ Turns on show stack mode noshowstack \ Turns off show stack mode
In show stack mode, the Forth interpreter shows you what's on the stack before every prompt. For example:
123 ffab0012 34 ok
That means that there are currently 3 numbers on the stack. The 34 is on top.