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).
Purpose
This procedure installs LinuxBIOS in the SPI FLASH of an OLPC development board, replacing the factory-installed Insyde BIOS. Insyde BIOS expires on Aug. 26, 2006, so the OLPC team hopes to cut over to LinuxBIOS soon.
Warnings
- This is a one-way procedure. Once you have installed LinuxBIOS and rebooted, going back to Insyde BIOS requires other tools and procedures.
- LinuxBIOS is not compatible with Insyde BIOS. After LinuxBIOS is installed, old OLPC software installations that used to work under Insyde BIOS may no longer boot.
The procedure
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...) 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 you are vulnerable to power failures that could cause your hardware to become unusable (or "bricked", as we sometimes call it).
Download spi_flash_linuxbios-20060824.dd from this location, with the following checksums:
http://dev.laptop.org/~krstic/spi_flash_linuxbios-20060824.dd MD5: 9fba47b90c6269571a0a558103fc30ae SHA1: 4cc2c4c6fd962d0e4132468ec0bd078a6c65c302
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:
$ dd bs=5M if=/dev/sda of=oldkey.img $ dd bs=5M if=spi_flash_linuxbios-20060824.dd of=/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, there will be a "$" shell prompt hidden in the midst of some USB probing messages.
On the OLPC USB keyboard, type:
$ flashlb
(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:
$ 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.
Hardware Requirements - Details
- An OLPC development board - this is the machine whose SPI FLASH you will update.
- 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 drive. Any size will do, since the software image is only 5 MB. 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 stuff 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 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.
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.
New startup message will stop appearing after a few seconds. The last few lines on the screen will be messages about "/dev/sda" from the USB subsystem. The "$" prompt from the shell will already be on the screen, but it's hard to find because there are several USB messages after it.
If you want to get a fresh prompt, just type the Enter key.
flashlb details
The steps that occurs during the execution of "flashlb" are as follows. It should be clear from the screen messages which steps are happening.
- Make a backup copy of the SPI FLASH in /insyde.rom (unless /insyde.rom already exists)
- Erase the SPI FLASH
- Write the contents of /linuxbios.rom to the SPI FLASH
- Verify that the newly-written data matches the file
Disaster Recovery
If the reflashing process fails, Don't power off 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.
$ flashlb
Retrying might conceivably be of some use if the failure was transient.
Re-executing flashlb won't overwrite the /insyde.rom backup file that was created on the first try, since the program only creates a backup if no such file exists.
Restoring Insyde BIOS
You might be able to restore the Insyde BIOS with
$ restore
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 flashlb process, it's possible - perhaps even likely that the same problem might also affect "restore". So don't expect miracles from "restore"; it is provided "just in case it helps".
("restore" 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 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 the board, we will have no way to diagnose the problem short of returning the board to OLPC and time consuming hardware diagnosis.
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".