Autoreinstallation image

  This page is monitored by the OLPC team.

Automatic Reinstallation Image

We've worked very hard to make it as easy as possible to update a machine in the field. Until network boot and update is available, this is as easy as it can get.

The Autoreinstallation image consists of an Open Firmware script that updates the NAND flash and firmware with the latest stable images and an activation lease, without requiring the user to do more than insert a prepared USB disk and turn on the machine.

NOTE: for builds 525 and later there are two changes to the update procedure that you should be aware of:

1. You need to replace the .fth file with the new one in olpc-auto.zip; and
2. you must leave the USB flash key or disk in the machine after the upgrade, while it reboots.

NOTE: this procedure creates a USB flash key or disk that when booted on an OLPC laptop, updates its BIOS and installs (OVERWRITES) an operating system image onto NAND flash. NEVER boot this USB flash key or disk unless you intend to update your system, which will entirely erase anything you had on the flash memory of the system.

This procedure works for all types of OLPC hardware, including A-test boards and most B1 (see #Workaround for old B1 systems) and all B2 laptops. It has only been tested with Open Firmware. If you are running Linux-as-BIOS or Insyde BIOS, see the workaround below.

The Software Release Notes document the status of the most important issues of this software. The Test Group Release Notes describe the status of development versions of the software.

System Update Procedure

Before you start: plug in your machine and ensure the battery is charged. It is very important that the update process not be interrupted. It will take about 2 minutes and 15 seconds total.

1. Download the file olpc-auto.zip
2. Get a USB flash key or disk with at least 300 MiB of free space in the primary partition (it doesn't have to be partitioned at all). The filesystem should be FAT (like a factory-formatted device). It will not work if it is partitioned such that the partition type code says "83" (Linux ext2 or ext3) but the actual filesystem inside the partition is FAT.
3. Unzip the files at the root of the USB flash key or disk drive, thus creating a directory called "boot". (If you drag and drop the files from the zip archive, you'll have to create the "boot" directory manually on the flash or disk drive.) There will be two files in the "boot" directory initially: olpc.fth and q2c18.rom.
4. Download the latest build image. Links are provided on the OS images page. There are two files you should download. The first file is named olpc-redhat-stream-development-build-NNN-YYYYYYYY_YYYY-devel_jffs2.img, with the N's and Y's replaced with a build number and date, respectively. Download this file and save it to the "boot" directory on your USB flash key or disk drive as osNNN.img. The second file has the same name as the first, but adds the extension .crc. This is a small checksum file. Save it to the boot directory on your USB flash key or disk drive as osNNN.crc. For stable releases, use the filename osNNNNN.img and osNNNNN.crc -- for example, stable release 406.15 would go in files named os40615.img and os40614.crc.
   • Grab the latest stable build, or
   • Grab the latest unstable development build.
5. You should also have the latest firmware image in the "boot" directory. There should already be a file named q2c18.rom in the "boot" directory of your USB flash drive or disk drive. If the Firmware page lists a newer firmware release, download it to the "boot" directory. The filename should be qZZZZ.rom, where the Z's are the firmware release number in hexadecimal (which means it uses the letters a-f as well as the numbers 0-9).
6. There should now be at least four files in the directory named "boot" on your USB key or disk drive for the automatic update to occur: q2c18.rom; os???.img; os???.crc; and olpc.fth, where the question marks are the build number to which you are updating. Do not use a flash key or disk for which there have been any errors reported during unzipping: the files may be (probably are) damaged. As a further safeguard, the OLPC OFW BIOS checks the integrity of any BIOS flash image before reflashing the BIOS. (The CRC file is required to be present --- e.g., \boot\osNNN.crc --- even though earlier firmware did not check for the CRC file.)
7. Insert the USB flash key into the machine or plug in the USB disk drive. If you have Open Firmware Q2C11 or later, hold down one of the "game keys" next to the screen, while you press the power button to turn on the laptop; then release the game keys when the screen lights up. If you have Open Firmware before version Q2C11, just turn on the power.
8. If your USB device is a hard disk instead of flash, you may need to interrupt the Open Firmware boot sequence by pressing the Esc key (the upper left key on the keyboard, marked with an X in a circle), waiting a moment, then entering probe-usb2. You should see additional entries compared to the initial list that Open Firmware displayed. Then you can enter boot and the update should proceed. This is because many external hard drives take a long time to come ready. The latest firmware should fix this issue, however.

You will see messages like those in the following section as the system is updated. NAND flash always has some bad blocks: the "Skipping bad block" messages during writing NAND flash are therefore normal, informing you of the bad blocks that will never be used by Linux.

The system will automatically boot into the new system image and perform activation using the activation lease stored on the USB key during autoreinstallation. DO NOT REMOVE THE USB KEY until you've reached the sugar "XO" screen, or the activation process will fail.

If anything goes wrong DO NOT TURN OFF THE MACHINE but please get help from OLPC, preferably immediately on IRC or by email.

Congratulations: you are finished! Power the machine down and remove the USB key.

Transcript of System Update

Release the game key to continue
OLPC B1, 256 MiB memory installed, S/N Unknown
Open Firmware  CL1   Q2C08  Q2C

USB2 devices:
/pci/usb@f,5/wlan@3,0
/pci/usb@f,5/scsi@1,0
/pci/usb@f,5/scsi@1,0/disk
USB1 devices:
Type the Esc key to interrupt automatic startup
Boot device: /usb/disk:\boot\olpc.fth  Arguments:
Checking existing OS image on NAND FLASH
Existing OS build is 353

Updating OS image on NAND FLASH from build 353 to build 515
Erasing...
1800
Skipping bad block at 0xc20000 = page 0x1840 = eblock 0x61
3ff40
Writing 80c blocks
80b
Done
Existing firmware version is q2c08

Updating firmware
Reading disk:\boot\q2c18.rom
Got firmware version: CL1  Q2C18  Q2C
Checking integrity ...
SPI FLASH is type 13 - Spansion, Winbond, or ST
Merging existing manufacturing data
Erasing
0
Writing
ff000
...
Powering off

In most cases, the system will boot automatically after the firmware or disk image is updated.

Possible Problems

• It is better if the USB disk is not partitioned. If it is partitioned:

1. The partition type must agree with the filesystem type - a FAT filesystem inside a partition marked ext2 won't work
2. The updater files should be in the partition that is marked as "bootable", or if there isn't one, in the first partition.

• The main files (olpcboot.fth, osNNN.img, q2NNN.rom) must be in the boot/ subdirectory. That will happen automatically if you "unzip" the archive, but if you drag-and-drop from a file manager like file-roller, it is possible to put them anywhere, and that won't work. Those files must be in boot/ .
• The current Open Firmware releases do not support USB keys that identify themselves as class "mass_storage/removable", as opposed to the more common "mass_storage/scsi", which is supported. (The fix for this problem is in the release pipeline, but that doesn't help for upgrading from existing firmware.) The way to check for this is to insert your USB key, power-on the system and stop the auto-boot by typing the Esc key (upper left key) at the countdown. Then look at the list of "USB2 devices". If you see an entry like "/pci/usb@f,5/removable@1,0", your disk has the problem. (If you are running an old version of OFW that does not display the "USB2 devices" list automatically, type "show-devs /usb" to see the list.) The workaround procedure is below.
• The current firmware also fails with USB devices whose hardware sector size is not 512 bytes. To determine the sector size of your device, you can use fdisk on the device under Linux, and it will tell you when it first accesses the device if the sector size is not 512. The workaround is the same as for the "removable" problem, i.e. the procedure below.
• Many Multi-Function devices do not work.
• If during the upgrade you see the following message, try renaming the file olpc.7th in the boot directory of the update image to olpc-boot.7th.

Trying startup script disk:\boot\olpc-boot.7th
Can't open boot device

• On an ATest board the X server may fail to start up. You may need to provide a custom configuration.

Workaround for LinuxBIOS or Insyde BIOS

If you are running LinuxBIOS, this process will probably not work (it has not been tested). The old version of this procedure may work for you.

If you are still running Insyde BIOS, you will first have to upgrade the firmware using procedures described elsewhere.

Workaround for old B1 systems

If you have a B1 system that has never been upgraded, it is very important to use this page's Autoreinstallation procedure for your first update; do not try to use the new "netnandwrite" tool first. The reason is that this procedure automatically fixes a manufacturing error in the identification data that was stored in the system firmware FLASH, and updates the firmware, neither of which is done by the network-based tool. Also, some old firmware will not update with the auto-update script. If the standard procedure above doesn't update, instead, follow these steps:

1. Insert the autoupdater key;
2. boot up the laptop and when it says "Press a key to interrupt" then press any key;
3. at the Ok prompt type "flash disk:\boot\q2c18.rom". The machine will turn off when finished.
4. power up again and boot the autoupdater normally; (It will reflash the NAND with the new build.)

Downgrading

Note: DO NOT DOWNGRADE Q2Cxx firmware to Q2Bxx firmware. This will destroy the manufacturing information. For details, see Firmware.

If you are trying to load a build that is older than the one on the XO, you will get a message that the software is up to date. To force it to load an older version, just rename your build image to os999.img and os999.crc. This will bypass the up-to-date check and force installation. Be careful using this trick for firmware images as the script will automatically reboot after installing the firmware, causing the same "newer" images to be installed over again in an infinite loop. Watch the process and turn off the machine quickly when the screen goes dark during the reboot.