Autoreinstallation image: Difference between revisions
| Line 96: | Line 96: | ||
'''Usage:''' |
'''Usage:''' |
||
:sugar-update.py [-''' |
:sugar-update.py [-'''dflLosv'''] [-'''b''' build] [directory] |
||
'''Description:''' |
'''Description:''' |
||
Revision as of 00:49, 30 August 2007
This page describes how to update the software image on your laptop. This process changes regularly, so please read the instructions carefully. Some 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
If you are upgrading firmware, and anything goes wrong which is not mentioned on this page, do not turn off the machine; please get help from OLPC, preferably immediately on IRC or by email.
Firmware q2c24 (in autoreinstallation images "2007-08-17 23:10Z" and "2007-08-18 05:08Z") has been withdrawn because it may brick B2 machines. Be sure you get the latest version of the autoreinstallation image!
The autoreinstallation image version is displayed at the start of the upgrade process. You can also find the version string at the top of the olpc.fth text file in the boot directory.
Recent firmwares do not support A-test boards or pre-B1 machines. Do not use this process if you have one of these; contact OLPC for an upgrade.
Starting with autoreinstallation image "2007-08-15 18:23Z", the upgrade process automatically backs up user data before the upgrade and restores it afterward. 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. WARNING: the old update procedure entirely erased the flash memory of the system. Be sure you know which version of the autoreinstallation image you are using; download the newest image from the link below if you are not certain.
As of autoreinstallation image "2007-08-17 16:35Z" activating a previously-unactivated machine after the upgrade has been simplified; see details below.
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 (ie, 128MB B2) 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 recent OLPC hardware:
- Most B1 (see workaround below); and
- All B2, B3, B4 and C laptops.
It has only been tested with Open Firmware:
- If you are running Linux-as-BIOS or Insyde BIOS, see the workaround below.
Nomenclature
It is important to identify which versions of the XO you are upgrading:
- A-Test board (bare motherboards)
- B1 machines (identifiable by a B1-TEST SAMPLE label under the battery)
- B2-1 machines (identifiable by B2-TEST SAMPLE and B2-1 through B2-16 labels under the battery)
- B2-2 machines (identifiable by B2-7-ext label under the battery)
- B3 machines (colored cover-plate; identifiable by a B3-TEST SAMPLE label under the battery)
- B4 machines (textured handle; colored cover-plate; identifiable by a B4-TEST SAMPLE and B4-1 through B4-16 labels under the battery)
- Preproduction (C machines) (fully textured; identifiable by a C-TEST SAMPLE and C-4 label under the battery)
(See the Laptop Development Schedule for a more detailed description of the various development systems.)
System Update Procedure
Preparing the hardware
1. Plug in your laptop and ensure the battery is charged. It is very important that the update process (Which takes about 3 minutes) not be interrupted.
2. 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, and 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.
NOTE: If you have python and the smallest bit of familiarity with the command line, the initialization of the auto-installation directory and the preparation of an update image can be accomplished automatically.
Initializing the auto-installation directory
1. Download 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, Q2E41.rom, usbupgos.img, and usbupgrd.img.
Preparing the latest image (manually)
1. If you have previously created an auto-installation image, remove the .img and .crc files from the boot directory of the flash or disk drive.
2. Download the latest build image (.img) and its checksum file (.crc). You may choose between the the latest stable build and the the latest unstable development build.
- The image is called osNNN.img ("NNN" represents the build number). The checksum file of the same name has the .crc extension.
- If you are downloading a build earlier than Build 530, the files on the download site will need to be renamed. 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.
3. Copy osNNN.img and osNNN.crc files to the boot directory of the flash or disk drive.
4. One of the files in the boot directory should be the latest firmware image, Q2E41.rom. If the Firmware page lists a newer firmware release than the one you have, download it to the boot directory.
- The firmware will be named qZZZZ.rom, where ZZZZ is are the firmware release number in hexadecimal (letters A-F and numbers 0-9).
5. Verify that these six files exist in the directory named boot on your USB key or disk: Q2E41.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.
6. You're now ready to upgrade the machine!
Preparing the latest image (automatically)
The sugar-update.py script automates the steps listed above for creating an auto-installation directory and preparing a new image. This is a python script, and as such requires python to run. Note: The script is not available at this moment, but will be available shortly.
Usage:
- sugar-update.py [-dflLosv] [-b build] [directory]
Description:
- This script will create an autoinstallation image boot directory within the specified directory. If the boot directory already exists, it will only download the necessary image files (.img, .crc, and .rom). Any of these files already present within this boot directory will be deleted before the download begins. If no directory is specified, the current working directory will be used.
- This script has also has automatic support for downgrades, and will add the necessary force.os file to the boot directory if the build image already present there is newer than the build specified.
Options:
- -b Specify a build number; defaults to latest development build
- -d Force downgrade image; implicit when a newer build exists in boot
- -f Skip firmware update
- -l Print the associated change log
- -L Print the change log for the specified build without performing a download
- -o Overwrite the existing boot directory with a clean auto-installation image
- -s Download the latest stable build; overrides the -b option
- -v Verbose
Examples:
If you're creating a boot directory from scratch, you'll simply want to use:
sugar-update.py -v /path/to/USBdrive/
By adding the -s flag to the above, the latest stable image will be prepared instead:
sugar-update.py -vs /path/to/USBdrive/
For frequent updates it's useful to show the change log for the new builds:
sugar-update.py -vl /path/to/USBdrive/
Upgrading the machine
Please follow these 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 watch it carefully; if it says "Firmware is already current" you can skip to Step (I); if instead you see "Updating firmware from q2XXX to q2YYY", then continue with Step (E);
- (E) Let the upgrade complete; the laptop will power off automatically after the firmware upgrade;
- (F) Remove both AC power and the battery and let it sit unpowered for 10 seconds (do not remove the USB disk); this step is very important: you must remove all power from the laptop in order to reset the embedded controller;
- (G) Reconnect AC power and re-insert the battery;
- (H) Power up the laptop and let it finish the install;
- (I) The XO will boot, backup the user files, reboot, upgrade the base image, then boot again to restore the user files; it will then power down;
- (J) Remove the USB key;
- (K) Power on the laptop again without the USB key inserted.
Congratulations: when you reboot, you'll be running a new build image.
A sample transcript of the update procedure is shown in following section.
Important notes
- If you are upgrading an unactivated machine (prior to Build 542), you may see either a message that says, "Could not activate this XO" followed by the serial number of your machine, or else a XO icon in the center of the display with a lock icon in the bottom right corner. If this happens: turn off the machine; reinsert the USB key; and hold down the 'X' and 'check' game buttons down while turning the power on. (If your XO is pre-B4 and does not have a 'check' button, use the 'O' button instead.) Release the buttons when directed. The system should boot into the new system image and perform activation using the activation lease stored on the USB key; Do not remove the USB key until you've reached the sugar "XO" screen, or the activation process will fail;
- If you have Open Firmware Q2C11 or later, hold down the X game key 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.
- After the upgrade, a backup of your user files can be found on the USB key with the name 'backup/<your XO's serial number>/complete.tgz'.
- If you are upgrading firmware, the machine will power off and not reboot. Please power the machine on by hand.
- As per above, 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.
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-15 19:27Z
Existing firmware version is q2c08
Updating firmware from q2c08 to q2c25
Reading disk:\boot\{{Latest Releases/firmware number}}.rom
Got firmware version: CL1 Q2C25 Q2C
Checking integrity ...
SPI FLASH is type 13 - Spansion, Winbond, or ST
Merging existing manufacturing data
Erasing
0
Writing
ff000
...
Powering off
[Then you remove power, replace power, and turn it back on again...]
OLPC B4, 256 MiB memory installed, S/N Unknown OpenFirmware CL1 Q2C25 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
[Boots into Linux]
....lots of kernel boot messages.... Backing up /home/olpc, size 13487 Backing up /security, size 1 Total used KB: 13473, disk free KB: 734112 Skipping from ignore list: /home/olpc/Library tar: Removing leading '/' from member names Done! *** Done ***
[Reboots]
Autoreinstallation version: 2007-08-02 23:28Z Existing firmware version is Q2C25 Firmware is already current; skipping update Existing firmware version is Q2C25 Firmware is already current; skipping update Activation lease created successfully. 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 6fd blocks 6fc Filling with cleanmarkers ... Done Booting into linux to restore user files.
[Linux boots up again]
....lots of kernel boot messages.... **** Restoring from backup **** *** Done ***
The machine powers off. Upgrade is complete.
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: power off, reinsert the autoreinstallation USB key, hold down the X and the 'check' button (use the 'O' button if you don't have a check button) and while holding them turn the power on. Leave the USB key in until you get the Sugar prompt to enter your name.
- The image on the laptop has a higher build number than the image on the USB flash. Solution: use the downgrading instructions below.
- It is better if the USB disk is partitioned, but:
- 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.
- If the USB disk is not partitioned, builds before 552 will fail to activate.
- 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.
- On an ATest board the X Server may fail to start up. You may need to provide a custom configuration.
Reporting problems
If you are unable to update your machine, please let us know:
- What version of the software you were upgrading from;
- What version you were upgrading to;
- What type of machine you have (b1, b2-1, b2-2, b3, b4, etc);
- What type of installation media you were using (USB flash key, SD card, something else?);
- (if you know this) how your installation media was formatted (FAT16, FAT32, ext2/3, etc) and partitioned (no partition, one partition, etc).
- Did you follow the instructions in Step K (above) carefully for an unactivated machine?
- Did you see the following text under "possible problems": "If the USB disk is not partitioned, builds before 552 will fail to activate."?
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 "netnandwrite" tool. 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\Q2E41.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.)
Some additional details
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 load an older version:
- Download the osNNN.img and osNNN.crc files for the old build into the boot/ directory of your autoreinstallation key. Make sure that the boot directory contains os515.img and os515.crc but not os528.img or any other newer os image.
- Create a new file in the boot subdirectory with the name 'force.os'. It doesn't matter what's in it, it just matters that it's there and has that name. This will cause the autoreinstallation script to try to install the latest version in boot/, regardless of whether it is older or newer than the current build on the XO.
- Follow the standard 12-step autoreinstallation procedure above.
If you want to reinstall the *same* image you've currently got, you should find an earlier build such as 515 (known to be good), use the procedure above to downgrade to 515, and then upgrade from there to your new image.
Resetting the EC
There is a capacitor on the reset line of the EC that controls how long the reset signal is asserted. This capacitor is the wrong value so the reset timing is invalid. This means that when you reset the EC with the power enabled there is a good chance it will not boot correctly.
If the EC does not reset correctly then the laptop will not start. Any laptop that is earlier than CTest may have this problem.
The only way to guarantee that the EC is fully reset after you upgrade the firmware is to power it off. The only way to really power off the EC is to remove the external power and the battery. Even when the power to the laptop CPU is off the EC is still powered. The capacitors in the system will hold their charge for several seconds after you remove power. You have to wait 10 seconds to make sure that all the capacitors have discharged.
The reason you do not remove the USB disk is that when the laptop powers off the upgrade procedure is not finished. You still have to boot with the USB disk so that it updates the OS image.
Generating CRC files
If for some reason you need to generate a CRC file -- for example, if you make a custom build -- please follow these instructions:
git clone git://git.fedoraproject.org/git/pilgrim cd pilgrim/crcimg make ./crcimg myfile.img
The output is in myfile.crc
Cheat codes
There are some boot options that are described here.