Upgrading to LinuxBIOS

Important: This procedure is currently being vetted. Unless you are one of the designated testers, please ignore this page until this message is removed (hopefully within the next day or so).

Introduction

This procedure installs LinuxBIOS in the SPI FLASH of an OLPC development board, replacing the factory-installed Insyde BIOS. Insyde BIOS expires as soon as Aug. 23, 2006.

This process works by booting one of the OLPC Build_images, which include the utilities for updating the SPI BIOS flash with a LinuxBIOS with Linux as bootloader image. The build image can boot either under Insyde BIOS or under LinuxBIOS. Once the flash has been updated, you may optionally continue to install the build image to internal NAND flash, or install a full Fedora installation on a USB hard disk.

Warnings

• This is a one-way procedure. Once you have installed LinuxBIOS and rebooted, going back to Insyde BIOS requires other tools and procedures.
• We expect that most people may find it easiest to reinstall their systems from scratch. However, you can also use the Fedora image provided solely to update your BIOS from Insyde to LinuxBIOS.
• LinuxBIOS is not compatible with Insyde BIOS. After LinuxBIOS is installed, old software installations that used to work under Insyde BIOS will no longer boot. If you wish to continue using your existing installation, you will need to update both your kernel and your X driver, as described below.
• The Geode does not have VESA console graphics hardware built in: instead, the Insyde BIOS has code that emulates VESA hardware. This emulator is not owned by AMD, and we prefer to use the BIOS space for other capability. We could also not maintain this binary blob should it require maintenance. This means that DOS or Windows will *not* boot under LinuxBIOS directly, as they expect to find VESA graphics present.
• If for some reason you are not using the Fedora builds, you should first update your kernel to our latest kernel, and use the gxfb driver as your console. You will also need the amd X driver. To boot a Linux kernel on OLPC on the graphics console, you must use the gxfb driver. Note that the VESA X driver will also no longer function: you should be using the new "amd" X Window System driver as well, which has much higher performance.

The procedure

Before you begin

Since the distribution includes the Marvell wireless driver, please ensure your antennae have been installed; there is a chance of damage to the wireless if it is turned on without the antennae installed.

If you have a UPS (uninterruptable power supply) handy, you should plug in your OLPC system to use it; you do not want to lose power part way through this operation. While the SPI flash is erased and not fully rewritten (a period of a minute or two) you are vulnerable to power failures that could cause your hardware to become unusable (or "bricked", as we sometimes call it).

You need a USB key (or USB disk), an OLPC devel board with a powered USB 2.0 hub and a USB keyboard (important), and a Linux-based host system. (More hardware details...) (Using Windows as a Host System...)

Hardware Requirements - Details

• An OLPC development board - this is the machine whose SPI FLASH you will update.
• Antennae for your board, if you plan to ever power on the on-board wireless.
• A powered USB 2.0 hub attached to the OLPC board.
• A USB keyboard attached to that powered hub. (Don't use a PS/2 keyboard; it won't work right with this procedure because of a hardware interaction between the PS/2 and SPI programming circuits.)
• A USB FLASH key or USB disk drive, minimum size of 512Mb. Note that we often refer to a flash key when any USB storage device, flash or disk, will do. I tested with a SanDisk Cruzer Mini 1.0GB device. The procedure preserves and restores the USB key's existing contents so you can use a USB key that already has files on it.
• A working Linux-based "host system" to copy the software image to a USB key (or see #Using Windows as a Host system).
• If you have an UPS (Uninterruptible Power Supply), it's a good idea to power the OLPC board from it. A power failure during FLASH programming is difficult to recover from.

Installing LinuxBIOS

Download build image 79 from this location, with the following checksums:

 http://olpc.download.redhat.com/olpc/streams/development/build79/images-rpm/olpc-stream-development-78
MD5: insert here
SHA1: insert here

onto the host system. (Source code ...)

Check that the checksums match! You don't want to flash garbage into your flash.

Plug your USB key or disk into the host system, verify that /dev/sda is its correct name (Alternative names for /dev/sda...) and type:

$ bunzip2 olpc-stream-development-79.....-rpm-ext3.img.bz2
$ dd bs=5M if=/dev/sda of=oldkey.img
$ dd bs=5M if=olpc-stream-development-79.....-rpm-ext3.img.bz 2of=/dev/sda

Move the USB key to the OLPC board (connect it via the powered USB 2.0 hub).

Boot the OLPC board (Boot sequence details...)

When it finishes booting, you should see the sugar login prompt. Press ctrl+alt+F1 to get to a console, and login as 'root' with no password.

On the OLPC USB keyboard, type:

$ olpcflash -r insyde.rom
$ olpcflash -E
$ olpcflash -w /var/lib/olpc/linuxbios.rom
$ olpcflash -v /var/lib/olpc/linuxbios.rom

(Details of what flashlb does...)

If something goes wrong (shouldn't happen :-), see #Disaster Recovery.

If all goes well (i.e. the verification step succeeds), you can upgrade some more OLPB boards by repeating the boot/flashlb steps.

After you have upgraded all your OLPC boards, you can restore the previous contents of your USB key if you wish. Plug the USB key back into the host system and type, remembering to replace /dev/sda with your device name:

$ dd bs=5M if=oldkey.img of=/dev/sda

This is the end of the procedure. The sections below contain additional information that may be useful if you have problems or are just curious.

Continuing with an Installation

Read the release notes below as well.

Continuing with a Full Fedora Core Installation

The Installing_Fedora_Core page describes how to continue with a full Fedora installation, once you have installed LinuxBIOS, if the minimal OLPC installation is insufficient.

Continuing with a NAND flash installation

The Installing_to_NAND page describes how to install a build image to the internal NAND flash on the board and boot from it.

Release Notes

• The LinuxBIOS buildrom package is very sensitive to the compiler toolchain used to build it; we found that FC6 rawhide would build a broken ROM (now being investigated). Ubuntu Edgy unstable has other problems building buildrom head. We strongly recommend against trying to rebuild the LinuxBIOS rom yourself. Please only use binaries that OLPC has tested and do not attempt to build your own BIOS image unless you are a serious LinuxBIOS developer.
• The X server have been configured to use 1024x768x16@60hz, by default, to maximize the chance of it "just working" on as many panels and monitors as possible. Feel free to tune for your own use. Note the OLPC panel is 1200x900 resolution, so if your flat panel or monitor will support that resolution, you may want to choose that size during your development, though we highly recommend using scalable graphics libraries based on Cairo to keep independent of display resolution.
• The Marvell firmware is not yet included in the distribution, but must be separately installed. The firmware should be downloaded and installed as the file /lib/firmware/usb8388.bin.

Additional Information

Linux USB drive device names

On many Linux systems, USB mass storage devices (e.g. USB key drives) have device names like /dev/sda, /dev/sdb, etc. Those are the same names that are used for SCSI disks, because USB mass storage devices use SCSI-like commands at one level of their software protocol.

In the common case where there is only one USB key drive and no "real" SCSI hard disks, the device name will be /dev/sda. If there are multiple USB mass storage devices or some SCSI hard disks, the USB key might be /dev/sda, /dev/sdb, /dev/sdc, etc. Make sure that you find the right one, because you don't want to overwrite the wrong drive.

On some Linux systems, USB mass storage devices have names like /dev/uba, /dev/ubb, etc. ("ub" instead of "sd").

Boot sequence details

This section describes what you should see while the reflashing software is booting under Insyde BIOS.

A few seconds after power on, the white Insyde BIOS banner screen will appear. A little later, the top of that screen will show the results of USB probing. Those results should include your USB key.

Then the screen will switch to white text on a black background. Eventually it will boot GRUB (the intermediate bootloader). After a brief timeout, GRUB will then start Linux. When Linux takes control of the screen, the font size will decrease and you'll see a lot of Linux startup messages.

X should start, showing a graphical login prompt. At this point, you can press ctrl+alt+F1 to see a login shell.

olpcflash details

The steps that occurs during the execution of the instructions above are as follows. It should be clear from the screen messages which steps are happening.

1. Make a backup copy of the SPI FLASH in insyde.rom
2. Erase the SPI FLASH
3. Write the contents of /var/lib/olpc/linuxbios.rom to the SPI FLASH
4. Verify that the newly-written data matches the file

Disaster Recovery

If the reflashing process fails, Don't power off or reset the OLPC board. Here are some things you can try that might be helpful. These are just suggestions, because I've never seen any failures - recovery procedures for hypothetical failures are inherently speculative.

Retrying the write command

You can retry the command that writes the SPI FLASH, i.e.

$ olpcwrite -w /var/lib/olpc/linuxbios.rom

Retrying might conceivably be of some use if the failure was transient.

Restoring Insyde BIOS

You might be able to restore the Insyde BIOS with

$ olpcflash -w insyde.rom

This only works if you haven't powered off or otherwise reset the OLPC board since you loaded LinuxBIOS into FLASH. The reason is because LinuxBIOS cannot boot the software that we use in this procedure, which is set up to be booted by Insyde BIOS.

If something went wrong with the olpcflash process, it's possible - perhaps even likely that the same problem might also affect writing the insyde.rom back. So don't expect miracles; this is suggested "just in case it helps". It might help, for example, if the flash has a single bit error that Insyde BIOS's code has happened to hide.

("olpcflash -w insyde.rom" was helpful in the testing of this procedure, allowing me to test the procedure several times before committing to the "one way" nature of the upgrade.)

If you are still having trouble

Don't power off or reset the OLPC board and please get in contact with us, on IRC or via email, so that we have a chance to see what has gone wrong. If you power off or reset the board, we will have no way to diagnose the problem short of returning the board to OLPC and time consuming hardware diagnosis, and even then, may not be able to figure out what went wrong.

Using Windows as a Host System

http://www.chrysocome.net/dd has a version of the "dd" command that runs under Windows. The command line arguments are compatible with the Linux version, but you have to use the Windows form of the USB device name (not /dev/sda). The Windows "dd" has a "--list" command to help you discover the right device name.

Source Code

The source tarball(s) for the packages in the ROM image and the image BOM is available from http://dev.laptop.org/www/gpl . Look for names beginning with "linuxbios".

Credits

• LinuxBIOS: Ron Minnich, Richard Smith, Mitch Bradley, Li-Ta Lo and the LinuxBIOS project
• Linux: Cast of thousands
• gxfb driver: Jordan Crouse
• amd EXA X driver: Jordan Crouse
• Libertas Marvell 8388 wireless driver: Ronak Chokshi, Aswath Mohan, Michailis Bletsas, Marcelo Tosatti
• Distro hacking, and initramfs goodness: David Zeuthen
• Kernel hacking: David Woodhouse, Marcelo Tosatti
• JFFS2: David Woodhouse
• Sugar: Dan Williams, Marco Gritti, Chris Blizzard, Walter Bender
• Amazing Sleuthing: Mitch Bradley
• Testing: Chris Ball, Ivan Krstic, Ray Tseng
• Lots of information: Ray Tseng
• Installation directions: Ivan Krstic, Jim Gettys, Chris Ball