OFW FAQ: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
(17 intermediate revisions by 12 users not shown)
Line 1: Line 1:
vareleltch
{{OLPC}}
{{OLPC}}
== Introduction ==
== Introduction ==


Open Firmware is an interactive firmware system that can do boot loading, system test, and many other things.
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
It contains a complete interactive [http://en.wikipedia.org/wiki/Forth_(programming_language) Forth] interpreter with thousands of commands. A brief description of the most important commands can be found at
description of the most important commands can be found at http://firmworks.com/QuickRef.html .
http://firmworks.com/QuickRef.html .


'''There is a series of introductory [[Forth Lessons|lessons about Forth and Open Firmware]].'''
'''There is a series of introductory [[Forth Lessons|lessons about Forth and Open Firmware]].'''
Line 13: Line 12:
=== What is the auto-boot sequence? ===
=== 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.
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 [[Forth_Lesson_12#Network_Booting|network boot]] option is mostly used for manufacturing.


=== How do I stop it from auto-booting? ===
=== 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.
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|Forth]]) prompt. From that prompt you can do just about anything ...

To get to the OFW prompt on a laptop with "security enabled", you will need a [[Activation_and_developer_keys|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|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.)
(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? ===
=== How do I boot from the ok prompt? ===
Line 27: Line 36:
But see the next topic...
But see the next topic...


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


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 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:
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:


ok boot nand:\boot\olpc.fth
# 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.
or
# You can use editenv or setenv to set the variables; see setenv and editenv instructions below
ok boot u:\boot\olpc.fth
# 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.
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

# Edit /boot/olpc.fth using a text editor (e.g. from Linux)
# 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'''
After you have set the configuration variables, just type '''boot'''
Line 47: Line 68:
* ramdisk - This is the device and file path to the initrd. If null, no initrd will be loaded. Example: ''disk:\boot\initrd.img''
* 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.
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:
You can set values manually with:
Line 73: Line 94:
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).
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 )".
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? ===
=== How do I do x86 I/O port accesses in the OFW interpreter? ===
Line 103: Line 124:
Typing a number pushes it on the stack.
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.
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,
For clarity, you can embed punctuation in numbers. I usually write long hex numbers with a period at position 4,
Line 132: Line 153:


That means that there are currently 3 numbers on the stack. The 34 is on top.
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 <tt>help</tt> at its 'ok' prompt displays "<nowiki>More information: http://wiki.laptop.org/go/OFW_FAQ</nowiki>"
[[Category:Wiki pages that XO content links to]]


[[Category:Developers]]
[[Category:Developers]]

Latest revision as of 22:45, 7 November 2014

  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"