Autoreinstallation image
Automatic Reinstallation Image
This page describes how to update the software image on your laptop. This process changes regularly, so please read the instructions carefully. Important changes are noted below. The update procedure creates a USB flash key or disk that when booted on an OLPC laptop, updates its firmware and installs a new version of the operating system image onto NAND flash.
WARNING: The update procedure will entirely erase the flash memory of the system. Be sure to backup any user-space files onto an external device before reinstallation.
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.
Notes
As of Build 525, we have added an activation step to the update process.
- You will need to use the new version of the fth script.
- You must leave the USB flash key or disk in the machine after the upgrade, while it reboots.
As of Build 406, we have added a checksum file to the update process.
- You will need both the .img file and the .crc file to update.
This procedure works for all types of OLPC hardware:
- including A-test boards (but not for firmware more recent than Q2C18);
- most B1 (see workaround below); 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.
System Update Procedure
Before you begin, 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.
Also, before you begin, 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), even if the actual filesystem inside the partition is FAT.
(1) Download the fth script (olpc-auto.zip).
(2) unzip olpc-auto.zip 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.
(3) Download the latest build image. Links are provided on the OS images page.
- Either the latest stable build, or the latest unstable development build.
- 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.
(4) As noted in Step 2 above, you should also have the latest firmware image in the boot directory (q2c18.rom).
- 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).
(5) There should now be at least four files in the directory named boot on your USB key or disk for the automatic update to occur: q2c18.rom; osNNN.img; osNNN.crc; and olpc.fth, where the NNNs 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 damaged. As a further safeguard, the firmware checks the integrity of the flash image before reflashing.
- The CRC file is required even though earlier firmware did not check for the CRC file.
(6) Insert the USB key or disk into the machine or plug in the USB disk drive.
- If you have Open Firmware Q2C11 or later, hold down any one of the game keys on the bezel above the power button, 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 without pressing a game key.
- If your USB device is a harddisk 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. Recent firmware should fix this issue, however.
(7) A sample transcript of the update procedure is shown in following section.
- NAND flash always has some bad blocks. You will see Skipping bad block messages during writing NAND flash. These are normal; they are informing you of the bad blocks that will never be used by Linux.
(8) 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.
(9) 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:
- The partition type must agree with the filesystem type - a FAT filesystem inside a partition marked ext2 won't work
- 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:
- Insert the autoupdater key;
- boot up the laptop and when it says "Press a key to interrupt" then press any key;
- at the Ok prompt type "flash disk:\boot\q2c18.rom". The machine will turn off when finished.
- 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. Follow this procedure to first load an older version and then try the upgrade again:
- In this example you have already loaded build 528 and need to try loading the same one again. Find an earlier build such as 515 (known to be good). Download the .img and .crc files onto a USB stick. They can be at the root but the two files have to be in the same directory.
- Boot up the laptop by pressing the power button and hold down the gamepad X button.
- When the message asks you to stop pressing it, let go.
- Then press the escape key when it gives you 3 seconds to stop the rest of the boot.
- From this OK prompt you should be able to type: copy-nand u:\nand515.img (use the full path if you didn't copy it into the root.)
- Assuming that started correctly you will end up with a 515 build. You can power down and then proceed to upgrade with the newer files on your usb stick for the new upgrade procedure.
(Note: After you've downgraded you might want to remove the 515 build from your USB stick, especially if you put it on the \boot directory of your usb stick. It is important that you have the correct .fth, .img, and .crc in the boot directory of the usb in order to upgrade properly with activation. Having more than one .img in there might cause problems.)