Autoreinstallation image

  This page is monitored by the OLPC team.

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.

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.

Important Notes

+	Software
XO
	13.2.11	2020-01-29
XS
	xs-0.7	2012-02-20

WARNING: The update procedure as is will entirely erase the flash memory of the system. Starting with build 542, you can turn on the backup and restore capability as part of the upgrade. This has not been fully tested yet, so it isn't on by default. To do the autoinstallation upgrade with backup, edit the olpc.fth file to change 'false' to 'true' in line 11 (true constant do-usb-upgrade). The USB key must be large enough to hold both the image to be installed and any and all files the user may have created in /home/OLPC.

As of Build 542 (firmware Q2C20e), we have fixed a bug that corrupted USB keys which were formatted FAT32.

• Please redownload the autoreinstallation image (olpc-auto.zip) and use the new files.
• You may also want to either reformat your USB key or use a file system checker on it to repair any corruption that may have occurred with the old firmware.

As of Build 525, we have added an activation step to the update process.

• You will need to use the new version of the autoreinstallation image files.
• You must leave the USB flash key or disk in the machine after the upgrade, while it reboots.
• Note that the activation code is only in the build, not in the firmware, so you can (until further notice) keep your firmware up to date while still running Build 406.15, the current recommendation for those of you with B2-1 machines.

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

(1) Plug in your machine and ensure the battery is charged. It is very important that the update process not be interrupted. To upgrade both the NAND image and firmware will take about 3 minutes.

(2) Also, before you begin, get a USB flash key or disk with at least 300 MiB of free space in the primary partition.

• The filesystem should be FAT (like a factory-formatted device).
• It does not have to be partitioned.
  • 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.

Preparing the image for loading

(1) Download the autoinstallation (olpc.fth) script and related files (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 four files in the boot directory initially: olpc.fth, q2c22.rom, usbupgos.img, and usbupgrd.img.

(3) Download the latest build image, and its checksum file.

• If you want a stable build, download the the latest stable build
  • The filesystem image is called olpc-redhat-stream-development-build-NNN.NN-DDDDDDDD_TTTT-devel_jffs2.img (with the "NNN.NN" replaced by the build number, and the D's and T's replaced with the date and time of the build). The checksum file has the same name, plus the extension .crc.
  • After downloading these files, rename the image to osNNNNN.img and the checksum to osNNNNN.crc. For instance, if you downloaded build 406.15, you would rename the files to os40615.img and os40615.crc. Copy the renamed files to the "boot" directory on your USB flash key or disk drive.
• For an unstable development build, download the the latest unstable development build.
  • The filesystem image is called osNNN.img (with "NNN" replaced by the build number) and the checksum file is called osNNN.crc. Download them and save them both to the "boot" directory on your USB flash key or disk drive.
  • If you are downloading a build earlier than Build 530, the files on the download site will have longer names, and you will need to rename them, as in the instructions for the stable builds above. For instance, if you want to download Build 528, you would download olpc-redhat-stream-development-build-528-20070720_0056-devel_jffs2.img, and rename it to os528.img, and likewise for its .crc file.

(4) As noted in Step 2 above, one of the files in the boot directory should be the latest firmware image (q2c22.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 six files in the directory named boot on your USB key or disk for the automatic update to occur: q2c22.rom; osNNN.img; osNNN.crc; usbupgos.img, usbupgrd.img, 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.

Upgrading the machine

(1) Please follow these 7 steps:

(A) Power off the laptop;

(B) Connect up AC and insert a battery;

(C) Insert the USB disk with the autoupdate image;

(D) Power on the laptop and let it upgrade (The laptop will power off automatically after the firmware upgrade);

(E) Remove both AC power and the battery and let it sit unpowered for 10 seconds (Do not remove the USB disk.);

(F) Reconnect AC power and re-insert the battery;

(G) Power up the laptop and let it finish the install.

Step E is very important. You must remove all power from the laptop in order to reset the embedded controller.

• 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.

A sample transcript of the update procedure is shown in following section.

• When updating some older firmware, you may see the message: "REFUSING TO WRITE ACTIVATION LEASE: Firmware Q2CXX is too old." This error message can be ignored.
• NAND flash almost 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.

The system should 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 you are upgrading firmware, the machine will power off and not reboot. Please power the machine on by hand.
  • If the machine does not power on, you need to reset the EC: (a) unplug the machine; (b) remove the battery; (c) wait 30 seconds; (d) reinsert the battery; (e) reconnect power (i.e., plug in the machine); and (f) power on the machine.This behavior is expected for machines with Li batteries so be prepared for that. Please do not remove the USB key until the activation process is completed.
• If anything else goes wrong do not turn off the machine; please get help from OLPC, preferably immediately on IRC or by email.

(2) Power off the machine and then remove the USB key. Congratulations: you are finished! When you reboot, you'll be running a new build image.

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:
Autoreinstallation version: 2007-08-02 23:28Z

WARNING: this process will delete any user data on this machine!
Type the ESC key to interrupt.

Existing firmware version is q2c08

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

[Then you power it back on again...]

OLPC B1, 256 MiB memory installed, S/N Unknown
OpenFirmware  CL1   Q2C22  Q2C

Can't assign address ranges larger than 32-bits
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: /usr/disk:\boot\olpc.fth  Arguments:
Autoreinstallation version: 2007-08-02 23:28Z

WARNING: this process will delete any user data on this machine!
Type the Esc key to interrupt.
Activation lease created successfully.
Existing firmware version is Q2C22
Firmware is already current; skipping update
Checking existing OS image on NAND FLASH
Existing OS build is 353 .0

Updating OS image on NAND FLASH from build 353 .0 to build 542 .0
Check file is /pci/usb@f,5/scsi@1,0/disk@0:\boot\OS542.crc
Erasing...
3ff40
Writing 6fc blocks
6fc
Filling with cleanmarkers ...

Done

Upgrade complete.  Booting to finish activation.
DO NOT REMOVE USB KEY UNTIL ACTIVATION IS COMPLETE.

[Linux boots up]

....lots of kernel boot messages....
Unmounting root (this may take a while unless you've got firmware q2c19)... done.
***********************************************
Activating....
***********************************************
....lots more system boot messages....

The graphical user interface will come up automatically (and probably ask you for your machine's name).

Possible Problems

• Installation failed. Solution: download the new autoreinstallation image (olpc-auto.zip) onto a newly formatted USB key and try again.
• Authentication failed! Solution: leave the USB key in until you get the Sugar prompt to enter your name.
• Installation skipped because the filenames you chose for the build images are too long (they violate the 8.3 character restriction for FAT filesystems). Solution: use shorter filenames.
• The image on the laptop has a higher build number than the image on the USB flash. Solution: use copy-nand as per the instructions below.
• 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 (olpc.fth, osNNN.img, osNNN.crc, usbupgos.img, usbupgrd.img, and q2XXX.rom) must be in the boot/ subdirectory.
• 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. (A 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\q2c20.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. Follow this procedure to first load an older version and then try the upgrade again:

1. 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.
2. Boot up the laptop by pressing the power button and hold down the gamepad X button.
3. When the message asks you to stop pressing it, let go.
4. Then press the escape key when it gives you 3 seconds to stop the rest of the boot.
5. 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.)
6. Assuming that started correctly you will end up with Build 515. 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 Build 515 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.)