Autoreinstallation image

From OLPC
Revision as of 08:02, 13 April 2007 by Gnu (talk | contribs) (Correct Linux partition type number)
Jump to navigation Jump to search
  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, without requiring the user to do more than insert a prepared USB disk and turn on the machine.

(If you have a B1 system, it is very important to use this procedure first; 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. Note that some old firmware found on some B1 machines looks for olpcboot.fth rather than olpc.fth. The work-around is simply to copy olpc.fth to olpcboot.fth.)

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 all B1 and B2 laptops. It works with both Open Firmware and Linux-as-BIOS installations - but does not work with Insyde BIOS. If you are still running Insyde BIOS, you will first have to upgrade the firmware using procedures described elsewhere.

Release Notes

The Software Release Notes document the status of the most important issues 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 http://olpc.download.redhat.com/olpc/autoupdate/olpc385_b87.zip
    md5sum: a7f6fd26a5954bb577428b5286e58a00 olpc385_b87.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). If your system currently has Open Firmware, the filesystem can be either FAT (like a factory-formatted device) or ext2. But it will not work if it partitioned such that the partition type code says "83" (Linux ext2 or ext3) but the actual filesystem inside the partition is FAT. If your system has Linux-as-BIOS, the USB device must have a primary partition and an ext2 filesystem on it, as /dev/sda1 is the device that linux as bootloader look for.
  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.) Three files must be in the directory named "boot", for the automatic update to occur: q2b87.rom; nand385.img; and olpc.fth. A fourth file, bzimage must be in the root directory. 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.
  4. (Optional) If you want to install an OS image besides build 385, download the appropriate jffs2 image from the image repository, and save it as nandXXX.img, where XXX is the number of the build. Then, edit olpc.fth, replacing 385 everywhere it occurs with the build number in the filename.
  5. Insert the USB flash key into the machine. If you have Open Firmware, just turn on the power. If you have Linux-as-BIOS, hit ESC when you see the boot progress bar, then choose the USB key icon and hit Enter.

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

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! When you next power the machine on, you'll be running the new image.

Transcript of System Update

Type any key to interrupt automatic startup
Boot device: /usb/disk:\boot\olpc.fth  Arguments:
Checking existing OS image on NAND FLASH
OS build is 353

Updating OS image on NAND FLASH
Erasing...
1800
Skipping bad block at 0xc20000 = page 0x1840 = eblock 0x61
3ff40
Writing 80c blocks
80b
Done
firmware version b85

Updating firmware
Reading disk:\boot\q2b87.rom
Got firmware version: CL1  Q2B87  Q2B
Checking integrity ...
SPI FLASH is type 13 - Spansion, Winbond, or ST
Merging existing manufacturing data
Erasing
0
Writing
ff000
...
Done

In most cases, the system will power-off automatically after the firmware 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, nandNNN.img, q2bNN.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 bzImage file, which is needed to support upgrading from Linux-as-BIOS, goes in the root directory.)
  • 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 a 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


Workaround for "Removable" or large-sector devices

  • Shut down the system
  • Remove the USB disk that has the updater image
  • Boot Linux from NAND FLASH
  • Insert the USB disk
  • Copy the file /bzImage from the updater filesystem on the USB disk file to /ofw.bzi the root directory of the NAND FLASH on the OLPC machine, e.g.
 mount /dev/sda1 /mnt
 cp /mnt/bzImage /ofw.bzi
  • Shutdown Linux
  • Power on, and type space during the Open Firmware auto-boot countdown
  • At the Open Firmware "ok" prompt, type the following, and the update procedure should then proceed automatically:
 ok null$ to ramdisk  boot nand:\ofw.bzi