OFW FAQ

  This page is monitored by the OLPC team.

Introduction

Open Firmware is an interactive firmware system that can do boot loading, system test, and many other things. It contains a complete interactive Forth interpreter 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.

Firmware security defines the boot sequence for a secured XO. Unsecured XOs auto-boot via an intermediate Forth script (olpc.fth) as described in Custom bootloader.

In both cases, the XO searches for boot files first on a USB mass storage device (hard disk or flash memory stick), then on an SD card, and then on the laptop's internal flash memory. In the unsecured case, it further tried to boot from a wired USB network device, then from the wireless network. The network boot option is mostly used for manufacturing.

How do I stop it from auto-booting?

You can make the laptop do a few other things at power-on by using Cheat codes by pressing the buttons on either side of the screen. This includes hardware diagnostics, more verbose booting for diagnosing system problems, etc.

To get to the OFW prompt on a laptop with "security enabled", you will need a Developer Key. Most G1G1 laptops have security enabled.

After Open Firmware has located all of the I/O devices, it turns on the screen. If you have a developer key installed, OFW will then wait a few seconds to see if you want to grab control. 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-disc 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. You only have a serial console if you open the guts of the laptop and connect a special developer circuit board to it.)

How do I boot from the ok prompt?

Just type "boot".

But see the next topic...

How do I boot from the laptop's internal flash memory?

If you just let OFW auto-boot, booting from the internal flash should just work, provided that there is no USB disk with a boot script (/boot/olpc-boot.fth).

If you want to force it to boot from a specific device, you can type at the ok prompt:

 ok boot nand:\boot\olpc.fth

or

 ok boot u:\boot\olpc.fth

or

 ok boot sd:\boot\olpc.fth

The olpc.fth script sets some configuration variables:

 * boot-device - the location of the OS kernel file
 * boot-file - the Linux "cmdline" arguments
 * ramdisk - the location of the (optional) "initrd" ramdisk root filesystem

If you want to change those variables to use different files or different cmdline arguments, you can either

1. Edit /boot/olpc.fth using a text editor (e.g. from Linux)
2. Or set the variables from the ok prompt using editenv or setenv ; see setenv and editenv instructions below.

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 the internal flash memory.

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' (byte) for 8-bit number, 'w' (word) for 16-bit number, 'l' (long word) 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 hexadecimal 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.

Note: the XO's Open Firmware mentions this page's URL. In at least firmware version Q2E12, entering help at its 'ok' prompt displays "More information: http://wiki.laptop.org/go/OFW_FAQ"