Autoreinstallation image: Difference between revisions

From OLPC
Jump to navigation Jump to search
(remove latest releases table, it does not serve any purpose here and is a distraction)
 
(166 intermediate revisions by 25 users not shown)
Line 1: Line 1:
{{Obsolete|link=[[Clean-install procedure]]}}
{{OLPC}}{{Translations}}
{{TOCright}}
{{TOCright}}
{{Developers}}


== If you are not a developer ==
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 [[#Important Notes|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.


This page is <font color=red>'''for software developers only'''</font>. It <font color=red>'''does not apply to laptops received from a school or Give One Get One laptops'''</font> unless you first get a [[Activation_and_Developer_Keys|'''developer key''']]; until then, please use '''[[olpc-update]]''' or '''[[clean-install procedure]]'''.
The [[Software Release Notes]] document the status of the most important issues of this software.


==Before you begin==
The [[Test Group Release Notes]] describe the status of development versions of the software.
'''This process is not recommended for newer machines and newer builds, unless debugging problems. Please use the [[olpc-update]] method instead.'''

This page describes how to update the software image on your laptop. 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.

'''This process changes regularly, so please read the instructions carefully.''' Some important changes are [[#Important Notes|noted below]]. The basic procedure has three parts:
# [[#Preparing the hardware|Preparing the hardware]];
# [[#Preparing the autoupdate image|Preparing the autoupdate image]]; and
# [[#Upgrading the machine|Upgrading the machine]].

The software version you choose depends on: [[#What type of laptop do I have?|what version of laptop hardware you are upgrading]] and whether you want to use a stable version or one of the experimental development versions of the software. The development versions have more features, but also many more bugs (sometimes big ones). The [[Test Group Release Notes]] describe the development versions. The [[release notes]] describe the status of important software problems you may have encountered previously. Most people with recent laptops will use the stable version. People with older laptop prototypes may need to use older versions. Developers may wish to use newer versions.

===What firmware/build am I currently running?===
While the current firmware number should be stored in <tt>/ofw/ec-name</tt>, this can be stale, so run 'olpc-bios-sig' or try watching the initial boot process. The current build number is stored in <tt>/boot/olpc_build</tt> and is displayed as part of the login prompt in the console. Both firmware number and build number are displayed in the developer console.

===What type of laptop do I have?===

It is important to identify which version of the laptop hardware you are upgrading.

See [[Laptop models]].


==Important Notes==
==Important Notes==
{{Latest Releases | firmware = inline | extra = inline}}


<big>''Older notes and upgrading older builds: see [[Autoreinstallation_image/archive#Important_Notes|the archive]]''</big>
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.


If you are upgrading ''firmware'', and anything goes wrong which is not mentioned on this page, <span style="color:red; ">'''do not turn off the machine'''</span>; please get help from OLPC, preferably immediately on IRC or by email.
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.


Firmware q2c26 is the last firmware safe to use for the '''406.x and old 5xx stable series builds'''.
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 in the boot directory.

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.

As of '''Build 613''' (firmware Q2C28), the "X" game-key is ''not'' used when doing an upgrade. So if you are upgrading from a firmware ''before'' q2c28, to a firmware of q2c28 or later, the "X" gamekey gets pressed once, before the firmware upgrade, but ''not'' the second time, for the user file backup and os 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.
As of '''Build 542''' (firmware Q2C20e), we have fixed a bug that corrupted USB keys which were formatted FAT32.
Line 21: Line 48:
* 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.
* 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.


These procedures work for B4 and MP machines. It has only been tested with Open Firmware.
As of '''Build 525''', we have added an activation step to the update process.
* If you are running Linux-as-BIOS or Insyde BIOS, see the [[#Workaround for LinuxBIOS or Insyde BIOS| workaround below]].
* You will need to use the '''[http://dev.laptop.org/git?p=users/cscott/autore;a=blob_plain;f=olpc-auto.zip;hb=HEAD 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.


==System Update Procedure==
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.


===Preparing the hardware===
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 for old B1 systems| workaround below]]); and
* All B2 laptops.


For older, pre-G1G1 laptops, see [[Preparing old laptops for autoreinstallation]]
It has only been tested with Open Firmware:
* If you are running Linux-as-BIOS or Insyde BIOS, see the [[#Workaround for LinuxBIOS or Insyde BIOS| workaround below]].


# 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.
==System Update Procedure==
# 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).
#* Autoreinstallation will not work if the flash key or disk is partitioned such that the partition type code says "83" (Linux ext2 or ext3), even if the actual filesystem inside the partition is FAT.
#* If the USB disk is not partitioned, builds before 552 will fail to activate.


===Before you begin===
===Preparing the autoupdate image===
<font color=red>We '''strongly''' recommend that you use a '''factory-formatted''' USB key.</font>
'''(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.
These instructions are for loading an autoupdate image onto a USB flash key or USB disk drive. The instructions for preparing an SD card are similar.
* 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.


NOTE: If your XO-1 is internet connected and you have a recent build (> 650) you can use [[SoftwareBinaryDifferentialUpdate]]s to reduce data transfer.
===Preparing the image for loading===
'''(1)''' Download the autoinstallation (olpc.fth) script and related files ([http://dev.laptop.org/git?p=users/cscott/autore;a=blob_plain;f=olpc-auto.zip;hb=HEAD olpc-auto.zip]).


==== Preparing the latest image (automatically) ====
'''(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''', '''q2c23.rom''', '''usbupgos.img''', and '''usbupgrd.img'''.


If you have Python available and some familiarity with the command line, then the initialization of the auto-installation directory and the preparation of an update image can be accomplished automatically with [[Sugar-update]].
'''(3)''' Download the latest build image, and its checksum file.
* If you want a stable build, download the [http://olpc.download.redhat.com/olpc/streams/development/LATEST-STABLE-BUILD/ the latest stable build]
** The filesystem image is called '''osNNN.img''' (with the "NNN" replaced by the build number). The checksum file has the same name, plus the extension '''.crc'''.
** Download these files and copy them to the "boot" directory on your USB flash key or disk drive.
* For an unstable development build, download the [http://olpc.download.redhat.com/olpc/streams/development/latest/devel_jffs2/ 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. 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.


====Initializing the auto-installation directory (manually)====
'''(4)''' As noted in Step 2 above, one of the files in the boot directory should be the latest firmware image ('''q2c23.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).


# Download [http://dev.laptop.org/git?p=users/cscott/autore;a=blob_plain;f=olpc-auto.zip;hb=HEAD olpc-auto.zip] (make sure you have the correct .rom file after unzip; see below)
'''(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: '''q2c23.rom'''; '''osNNN.img'''; '''osNNN.crc'''; '''usbupgos.img''', '''usbupgrd.img''', and '''olpc.fth''', where the NNNs are the build number to which you are updating.
# Unzip '''<tt>olpc-auto.zip</tt>''' at the root of the USB flash key or disk drive, thus creating a directory called '''boot'''.
* 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.
#* 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.
* The CRC file is required even though earlier firmware did not check for the CRC file.
#* There will be four files in the boot directory initially: <tt>'''olpc.fth''', '''{{Latest Releases/firmware number}}.rom''', '''usbupgos.img''', and '''usbupgrd.img'''</tt>.

====Preparing the latest image (manually)====

# If you have previously created an auto-installation image, remove the <tt>.img</tt> and <tt>.crc</tt> files from the boot directory of the flash or disk drive - but not those named '''usbupgos.img''' or '''usbupgrd.img'''!. (Don't forget to "Empty Trash.")
# Download the latest build image (<tt>.img</tt>) and its checksum file (<tt>.crc</tt>). You may choose between the [http://download.laptop.org/xo-1/os/official/latest/jffs2/ the latest stable build] and the [http://xs-dev.laptop.org/~cscott/olpc/streams/joyride/latest/devel_jffs2/ the latest unstable development build].
#* See [[Test Group Release Notes]] for build differences.
#* The image is called '''<tt>osNNN.img</tt>''' ("<tt>NNN</tt>" represents the build number). The checksum file of the same name has the '''<tt>.crc</tt>''' 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 '''<tt>olpc-redhat-stream-development-build-528-20070720_0056-devel_jffs2.img</tt>''', and rename it to '''<tt>os528.img</tt>''', and likewise for its '''<tt>.crc</tt>''' file.
#* If you are downloading a build with a non-integer number, e.g., Build 542.3, you need to rename it without the decimal point, e.f., '''<tt>os5423.img</tt>''' and '''<tt>os5423.crc</tt>'''.
# Copy '''<tt>osNNN.img</tt>''' and '''<tt>osNNN.crc</tt>''' files to the '''<tt>boot</tt>''' directory of the flash or disk drive.
# One of the files in the boot directory should be the latest firmware image, <tt>{{Latest Releases/firmware number}}.rom</tt>. 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 <tt>qXXXX.rom</tt>, where <tt>XXXX</tt> is the firmware release number in hexadecimal (letters A-F and numbers 0-9).
# Verify that these six files exist in the directory named '''<tt>boot</tt>''' on your USB key or disk: <tt>'''{{Latest Releases/firmware number}}.rom'''; '''osNNN.img'''; '''osNNN.crc'''; '''usbupgos.img''', '''usbupgrd.img''', and '''olpc.fth'''</tt>, where the <tt>NNN</tt>s 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.
# You're now ready to [[Autoreinstallation image#Upgrading the machine | upgrade the machine]]!


===Upgrading the machine===
===Upgrading the machine===
Please follow these 12 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.''');
:(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 powerdown.
:(J) '''Remove the USB key.'''
:(K) Power on the laptop again without a USB key inserted. [[Image:Locked_XO.png|right|thumb|Icon displayed when activation fails.]] 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, reboot the machine, wait until you see 6 icons in the top left, then insert the USB key. The system should 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.'''
:(L) Congratulations: you are finished! When you reboot, you'll be running a new build image.


Please follow these steps:
Step F is very important: you must remove all power from the laptop in order to reset the embedded controller.
:(A) Switch off the laptop;
:(B) Provide power: put in a battery; plug in the laptop;
:(C) Insert the USB key with the autoupdate image;
:(D) Switch on the laptop, and watch it carefully;
::(D.1) If your current firmware is between Q2C11 and Q2C27 (inclusive), hold down the X game key on the bezel above the power button, while you press the power button; then release the game key when the screen lights up.
::(D.2) if the laptop says "<tt>Firmware is already current</tt>" you can skip to Step (I) below; if instead you see "<tt>Updating firmware from q2XXX to q2YYY</tt>", then continue with Step (E);
----
:(E) Let the firmware update complete; the laptop will then turn off automatically;
:(F) Remove all power from the laptop. This step is very important (it resets the embedded controller). <span style="color:red; ">'''Do not remove the USB key'''</span> yet.
::(F.1) unplug the laptop; take out the battery;
::(F.2) wait 30 seconds;
:(G) Put in the battery; plug the machine back in;
:(H) Switch on the laptop;
::(H.1) If you are upgrading to a firmware between Q2C11 and Q2C27 (inclusive), hold down the X game key on the bezel above the power button, while you press the power button; then release the game key when the screen lights up.


----
* 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.
:(I) The XO will now, by itself,
* If you have Open Firmware before version Q2C11, just turn on the power without pressing a game key.
:: boot, to backup the user files, (possibly pausing afterwards for half a minute)
* 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.
:: reboot, to upgrade the base image,
* 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'.
:: reboot, to restore the user files, (finally says "done", and "you can power down now", then pauses)
:: then powers down itself;(XO doesn't power off sometimes. Instead it restarts and get stuck at 'ok' prompt. If you see message "Firmware is already current; skipping update" then you can remove USB key and power-off XO manually. Then power-on XO without USB key inserted. This time XO shall boot with the latest build you have upgraded with. Congratulations!)
:(J) '''Remove the USB key''';
:(K) Power on the laptop again '''without the USB key inserted'''.

Congratulations: you are running a new build image.


A sample transcript of the update procedure is shown in [[#Transcript_of_System_Update|following section]].
A sample transcript of the update procedure is shown in [[#Transcript_of_System_Update|following section]].


====Additional notes====
* 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 <span style="color:red; ">'''do not remove the USB key'''</span> until the activation process is completed.
* If you have Open Firmware version Q2C11 (2007-05-06) through Q2C27 (2007-09-19), hold down the X game key on the bezel above the power button, while you press the power button; then release the game key when the screen lights up. With versions earlier than Q2C11, or later than Q2C27, turn on the power ''without'' pressing a game key.
* If anything else goes wrong <span style="color:red; ">'''do not turn off the machine'''</span>; please get help from OLPC, preferably immediately on IRC or by email.
* 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. [[Image:Locked_XO.png|right|thumb|Icon displayed when activation fails.]] 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 the USB disk is not partitioned, builds before 552 will fail to activate.
* 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 disc), waiting a moment, then entering ''<tt>probe-usb2</tt>''. You should see additional entries compared to the initial list that Open Firmware displayed. Then you can enter ''<tt>boot</tt>'' 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.
* 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 <span style="color:red; ">'''do not remove the USB key'''</span> until the activation process is completed.
* When removing all power from the laptop, any external USB peripherals should be disconnected, just in case they are faulty and supply current to the system.
* If anything else goes wrong <span style="color:red; ">'''do not turn off the machine'''</span>; please get help from OLPC, preferably immediately on IRC (on '''#olpc''' or '''#olpc-help''' freenode's channels) or by email.
* After the upgrade, a backup of your user files can be found on the USB key with the name '<tt>backup/<your XO's serial number>/complete.tgz</tt>'.


==Transcript of System Update==
==Transcript of System Update==
Line 115: Line 156:
Existing firmware version is q2c08
Existing firmware version is q2c08


Updating firmware from q2c08 to q2c23
Updating firmware from q2c08 to q2c25
Reading disk:\boot\q2c23.rom
Reading disk:\boot\{{Latest Releases/firmware number}}.rom
Got firmware version: CL1 Q2C23 Q2C
Got firmware version: CL1 Q2C25 Q2C
Checking integrity ...
Checking integrity ...
SPI FLASH is type 13 - Spansion, Winbond, or ST
SPI FLASH is type 13 - Spansion, Winbond, or ST
Line 131: Line 172:
<pre>
<pre>
OLPC B4, 256 MiB memory installed, S/N Unknown
OLPC B4, 256 MiB memory installed, S/N Unknown
OpenFirmware CL1 Q2C23 Q2C
OpenFirmware CL1 Q2C25 Q2C


Can't assign address ranges larger than 32-bits
Can't assign address ranges larger than 32-bits
Line 159: Line 200:
Autoreinstallation version: 2007-08-02 23:28Z
Autoreinstallation version: 2007-08-02 23:28Z


Existing firmware version is Q2C23
Existing firmware version is Q2C25
Firmware is already current; skipping update
Firmware is already current; skipping update
Existing firmware version is Q2C23
Existing firmware version is Q2C25
Firmware is already current; skipping update
Firmware is already current; skipping update
Activation lease created successfully.
Activation lease created successfully.
Line 187: Line 228:


== Possible Problems ==
== Possible Problems ==
* The majority of problems that have been reported are due to the file format on the USB key or SD card. If you have trouble, the first remedy to try is '''factory-formatted media''', which by default should be a flavor of FAT.
* Installation failed. Solution: download the new autoreinstallation image ([http://dev.laptop.org/git?p=users/cscott/autore;a=blob_plain;f=olpc-auto.zip;hb=HEAD olpc-auto.zip]) onto a newly formatted USB key and try again.
* Installation failed. Solution: download the new autoreinstallation image ([http://dev.laptop.org/git?p=users/cscott/autore;a=blob_plain;f=olpc-auto.zip;hb=HEAD olpc-auto.zip]) onto a newly formatted USB key and try again.
* Authentication failed! Solution: remove the autoreinstallation USB key, power off, and reinsert it just after you see the penguin in the top left. Leave the USB key in until you get the Sugar prompt to enter your name.
* 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.
* If the USB disk is not partitioned, builds before 552 will fail to activate.
* The image on the laptop has a higher build number than the image on the USB flash. Solution: use the [[#Downgrading|downgrading instructions below]].
* The image on the laptop has a higher build number than the image on the USB flash. Solution: use the [[#Downgrading|downgrading instructions below]].
* It is better if the USB disk is not partitioned. If it is partitioned:
* 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 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 updater files should be in the partition that is marked as "bootable", or if there isn't one, in the first partition.
** There is a situation where a disk can appear to both have a partition table and also have a FAT file system starting in the first sector. We are not yet able to support this anomalous situation.
* The main files (olpc.fth, osNNN.img, osNNN.crc, usbupgos.img, usbupgrd.img, and q2XXX.rom) must be in the boot/ subdirectory.
* We have seen some USB disks that take several seconds to detect. In those cases, hold the Game Key for 2+ sec or let the count down expire.
* The current Open Firmware releases do not support USB keys that identify themselves as class "mass_storage/removable" &ndash; 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 main files (<tt>olpc.fth, osNNN.img, osNNN.crc, usbupgos.img, usbupgrd.img, and q2XXX.rom</tt>) must be in the <tt>boot/</tt> subdirectory.
* 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.
* The current Open Firmware releases do not support USB keys that identify themselves as class "<tt>mass_storage/removable</tt>" &ndash; as opposed to the more common "<tt>mass_storage/scsi</tt>", 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 "<tt>/pci/usb@f,5/removable@1,0</tt>", your disk has the problem. (If you are running an old version of OFW that does not display the "USB2 devices" list automatically, type "<tt>show-devs /usb</tt>" 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 <tt>fdisk</tt> 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.
* Many Multi-Function devices do not work.
* If Laptop loses activation (a message "Could not activate this XO" appears after the kernel has booted) you might need to revert to a previous image (like 515 as suggested in http://www.mail-archive.com/devel@lists.laptop.org/msg00690.html) or follow the procedure described in "Additional Notes" above for an unactivated machine.
* On an ATest board the X Server may fail to start up. You may need to provide [[Configuring X on an ATest board|a custom configuration]].
* under some circumstances olpc-update fails <tt>OSError: [Errno 2] No such file or directory: '/versions/run/... /drivers/input/joydev.ko'</tt> Under these circumstances you need to recover by upgrading to the latest firmware.
===Multi-card readers===
There is a common problem with multi-card readers. Each slot appears as
a different "SCSI Logical Unit Number". OFW does not do a "deep probe"
to determine exactly which slots are currently populated at any given
instant (because doing so would slow down booting for the vast majority
of cases where there is no choice). Consequently, when OFW tries to
resolve the "disk" devalias, it doesn't know which LUN to use. It
guesses 0, which has only a 1 in N chance of being right.

There are two possible workarounds:

(1) Put the SD card directly into the XO's SD slot (below the screen; you
have to rotate the display 90 degrees to get to it) and then do the
4-keys procedure

(2) Assuming that you can get to the ok prompt (i.e. your system is not
in secure mode), there is a manual workaround:

ok " usb1/disk@3" fs-update-from-list

Notes:

(a) There must be one space after the first " (i.e. between " and u),
and one or more spaces after the second "

(b) Depending on your multi-reader, you might need to use "usb2"
instead of "usb1". You can find out by typing "probe-usb" and noting
which list shows your device.

(c) The "@3" is just an example - you will need to search manually for
the number that corresponds to the SD slot in your multi-reader. The
arrow keys can save you some typing during this search.

=== 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 ([[#Upgrading_the_machine|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 ===
=== Workaround for LinuxBIOS or Insyde BIOS ===

If you are running LinuxBIOS, this process will probably not work (it has not been tested). The [http://wiki.laptop.org/index.php?title=Autoreinstallation_image&oldid=49797 old version of this procedure] may work for you.
If you are running LinuxBIOS, this process will probably not work (it has not been tested). The [http://wiki.laptop.org/index.php?title=Autoreinstallation_image&oldid=49797 old version of this procedure] may work for you.


Line 207: Line 297:


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:
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;
# Insert the autoupdater key;
#boot up the laptop and when it says "Press a key to interrupt" then press any key;
# boot up the laptop and when it says "<tt>Press a key to interrupt</tt>" then press any key;
#at the Ok prompt type "flash disk:\boot\q2c23.rom". The machine will turn off when finished.
# at the Ok prompt type "<tt>flash disk:\boot\{{Latest Releases/firmware number}}.rom</tt>". The machine will turn off when finished.
#power up again and boot the autoupdater normally; (It will reflash the NAND with the new build.)
# power up again and boot the autoupdater normally; (It will reflash the NAND with the new build.)

==Some additional details==

=== Making a "clean" install ===

By default, installation process preserves files in <tt>/home/olpc</tt>. If some of those files are corrupted, it may be desirable to make clean installation.

* With firmware q2c28 (2007-10-01) or later, just press the SQUARE game key [[Cheat codes|cheat code]] when installing. Done.
* With firmware before q2c28 (2007-10-01), the easiest thing to do is delete the <tt>datastore</tt> and <tt>config</tt> files. They will be replaced by clean copies upon reinstallation. From the console:

rm -r /home/olpc/.sugar/default/datastore/
rm /home/olpc/.sugar/default/config
rm /home/olpc/.sugar/default/owner.key*
rm /home/olpc/.sugar/default/nm/*
rm /home/olpc/.sugar/default/friends

Then proceed with the standard installation process.


=== Downgrading ===
=== Downgrading ===

<b>Note: DO NOT DOWNGRADE Q2Cxx firmware to Q2Bxx firmware.</b> This will destroy the manufacturing information. For details, see [[Firmware]].
<b>Note: DO NOT DOWNGRADE Q2Cxx firmware to Q2Bxx firmware.</b> 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:
If you tried to load a build that is older than the one currently installed on your XO, then you will have gotten a message that the software is up to date. Follow this procedure to load an older version:


====Automatic downgrade====
#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 [[#Upgrading the machine|12-step autoreinstallation procedure above]].


Note: please confirm that this method works (it may not for all combinations; the force.os didn't work for at least one case).
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.
:(610 q2c27->609 worked for me [[User:MitchellNCharity|MitchellNCharity]] 14:12, 1 October 2007 (EDT))
:(542.3 q2c26->405.16 worked for me [[User:Hummingbird|Hummingbird]] 20:58, 15 October 2007 (EDT))
# Download the <tt>osNNN.img and osNNN.crc</tt> files for the old build into the <tt>boot/</tt> directory of your autoreinstallation key. Make sure that the boot directory contains both the <tt>osNNN.img and osNNN.crc</tt> files to which you are downgrading, but not any newer os image.
# Create a new file in the <tt>boot</tt> subdirectory with the name '<tt>force.os</tt>'. (It does not matter what is in it; it just matters that the subdirectory exists and has a file with that name.) This will cause the autoreinstallation script to try to install the image in <tt>boot/</tt>, regardless of whether it is older or newer than the current build on your XO.
# Follow the standard [[#Upgrading the machine|autoreinstallation procedure above]].

====Manual downgrade====

You can also downgrade by using the copy-nand command at the OK prompt.
copy-nand d:\boot\os525.img

After the copy, you need to activate your laptop:
# reboot the machine holding the 'X' and 'check' game-pad keys; (If your XO does not have a 'check' key, use the 'O' key.)
# leave the USB stick in while it writes the activation code.

(Note that automatic backup of user files will fail with this technique.)

====Reinstalling the same image====

If you want to reinstall the *same* image you've currently got, you should find an earlier '''stable''' build, use the downgrade procedure, and then the standard upgrade procedure to your new image.


==Some additional details==
===Resetting the EC===
===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.
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.
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 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.
Line 233: Line 359:
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.
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===
===Customizing Nand / 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:
You can create a [[Customizing_NAND_images|custom]] build, but you will then need to generate a CRC file; please follow these instructions:
<pre>
<pre>
git clone git://git.fedoraproject.org/git/pilgrim
git clone git://git.fedoraproject.org/git/pilgrim
Line 242: Line 369:
</pre>
</pre>


The output is in myfile.crc
The output is in <tt>myfile.crc</tt>

===Network upgrade===

The olpc-upgrade command can be run from the console (as root) to upgrade from recent (612+) builds. Usage is olpc-upgrade build#, e.g.,
olpc-upgrade 613

===Where to find experimental builds===

There are test builds available for developers (joyride, meshtest, debian, etc.). Details are available [[Test_Config_Notes#OLPC_Update|here]].

===Cheat codes===

Boot options can be controlled by pressing game key [[Cheat codes]] at power-on.





Latest revision as of 21:58, 5 August 2013

542-stopicon.png This page has a more up-to-date location: Clean-install procedure

If you are not a developer

This page is for software developers only. It does not apply to laptops received from a school or Give One Get One laptops unless you first get a developer key; until then, please use olpc-update or clean-install procedure.

Before you begin

This process is not recommended for newer machines and newer builds, unless debugging problems. Please use the olpc-update method instead.

This page describes how to update the software image on your laptop. 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.

This process changes regularly, so please read the instructions carefully. Some important changes are noted below. The basic procedure has three parts:

  1. Preparing the hardware;
  2. Preparing the autoupdate image; and
  3. Upgrading the machine.

The software version you choose depends on: what version of laptop hardware you are upgrading and whether you want to use a stable version or one of the experimental development versions of the software. The development versions have more features, but also many more bugs (sometimes big ones). The Test Group Release Notes describe the development versions. The release notes describe the status of important software problems you may have encountered previously. Most people with recent laptops will use the stable version. People with older laptop prototypes may need to use older versions. Developers may wish to use newer versions.

What firmware/build am I currently running?

While the current firmware number should be stored in /ofw/ec-name, this can be stale, so run 'olpc-bios-sig' or try watching the initial boot process. The current build number is stored in /boot/olpc_build and is displayed as part of the login prompt in the console. Both firmware number and build number are displayed in the developer console.

What type of laptop do I have?

It is important to identify which version of the laptop hardware you are upgrading.

See Laptop models.

Important Notes

Older notes and upgrading older builds: see the archive

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 q2c26 is the last firmware safe to use for the 406.x and old 5xx stable series builds.

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.

As of Build 613 (firmware Q2C28), the "X" game-key is not used when doing an upgrade. So if you are upgrading from a firmware before q2c28, to a firmware of q2c28 or later, the "X" gamekey gets pressed once, before the firmware upgrade, but not the second time, for the user file backup and os 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.

These procedures work for B4 and MP machines. It has only been tested with Open Firmware.

System Update Procedure

Preparing the hardware

For older, pre-G1G1 laptops, see Preparing old laptops for autoreinstallation

  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).
    • Autoreinstallation will not work if the flash key or disk is partitioned such that the partition type code says "83" (Linux ext2 or ext3), even if the actual filesystem inside the partition is FAT.
    • If the USB disk is not partitioned, builds before 552 will fail to activate.

Preparing the autoupdate image

We strongly recommend that you use a factory-formatted USB key.

These instructions are for loading an autoupdate image onto a USB flash key or USB disk drive. The instructions for preparing an SD card are similar.

NOTE: If your XO-1 is internet connected and you have a recent build (> 650) you can use SoftwareBinaryDifferentialUpdates to reduce data transfer.

Preparing the latest image (automatically)

If you have Python available and some familiarity with the command line, then the initialization of the auto-installation directory and the preparation of an update image can be accomplished automatically with Sugar-update.

Initializing the auto-installation directory (manually)

  1. Download olpc-auto.zip (make sure you have the correct .rom file after unzip; see below)
  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 - but not those named usbupgos.img or usbupgrd.img!. (Don't forget to "Empty Trash.")
  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.
    • See Test Group Release Notes for build differences.
    • 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.
    • If you are downloading a build with a non-integer number, e.g., Build 542.3, you need to rename it without the decimal point, e.f., os5423.img and os5423.crc.
  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 qXXXX.rom, where XXXX is 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!

Upgrading the machine

Please follow these steps:

(A) Switch off the laptop;
(B) Provide power: put in a battery; plug in the laptop;
(C) Insert the USB key with the autoupdate image;
(D) Switch on the laptop, and watch it carefully;
(D.1) If your current firmware is between Q2C11 and Q2C27 (inclusive), hold down the X game key on the bezel above the power button, while you press the power button; then release the game key when the screen lights up.
(D.2) if the laptop says "Firmware is already current" you can skip to Step (I) below; if instead you see "Updating firmware from q2XXX to q2YYY", then continue with Step (E);

(E) Let the firmware update complete; the laptop will then turn off automatically;
(F) Remove all power from the laptop. This step is very important (it resets the embedded controller). Do not remove the USB key yet.
(F.1) unplug the laptop; take out the battery;
(F.2) wait 30 seconds;
(G) Put in the battery; plug the machine back in;
(H) Switch on the laptop;
(H.1) If you are upgrading to a firmware between Q2C11 and Q2C27 (inclusive), hold down the X game key on the bezel above the power button, while you press the power button; then release the game key when the screen lights up.

(I) The XO will now, by itself,
boot, to backup the user files, (possibly pausing afterwards for half a minute)
reboot, to upgrade the base image,
reboot, to restore the user files, (finally says "done", and "you can power down now", then pauses)
then powers down itself;(XO doesn't power off sometimes. Instead it restarts and get stuck at 'ok' prompt. If you see message "Firmware is already current; skipping update" then you can remove USB key and power-off XO manually. Then power-on XO without USB key inserted. This time XO shall boot with the latest build you have upgraded with. Congratulations!)
(J) Remove the USB key;
(K) Power on the laptop again without the USB key inserted.

Congratulations: you are running a new build image.

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

Additional notes

  • If you have Open Firmware version Q2C11 (2007-05-06) through Q2C27 (2007-09-19), hold down the X game key on the bezel above the power button, while you press the power button; then release the game key when the screen lights up. With versions earlier than Q2C11, or later than Q2C27, turn on the power without pressing a game key.
  • 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.
    Icon displayed when activation fails.
    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 the USB disk is not partitioned, builds before 552 will fail to activate.
  • 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 disc), 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.
  • 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.
  • When removing all power from the laptop, any external USB peripherals should be disconnected, just in case they are faulty and supply current to the system.
  • If anything else goes wrong do not turn off the machine; please get help from OLPC, preferably immediately on IRC (on #olpc or #olpc-help freenode's channels) or by email.
  • 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'.

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

  • The majority of problems that have been reported are due to the file format on the USB key or SD card. If you have trouble, the first remedy to try is factory-formatted media, which by default should be a flavor of FAT.
  • 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.
  • If the USB disk is not partitioned, builds before 552 will fail to activate.
  • 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.
    • There is a situation where a disk can appear to both have a partition table and also have a FAT file system starting in the first sector. We are not yet able to support this anomalous situation.
  • We have seen some USB disks that take several seconds to detect. In those cases, hold the Game Key for 2+ sec or let the count down expire.
  • 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 Laptop loses activation (a message "Could not activate this XO" appears after the kernel has booted) you might need to revert to a previous image (like 515 as suggested in http://www.mail-archive.com/devel@lists.laptop.org/msg00690.html) or follow the procedure described in "Additional Notes" above for an unactivated machine.
  • under some circumstances olpc-update fails OSError: [Errno 2] No such file or directory: '/versions/run/... /drivers/input/joydev.ko' Under these circumstances you need to recover by upgrading to the latest firmware.

Multi-card readers

There is a common problem with multi-card readers. Each slot appears as a different "SCSI Logical Unit Number". OFW does not do a "deep probe" to determine exactly which slots are currently populated at any given instant (because doing so would slow down booting for the vast majority of cases where there is no choice). Consequently, when OFW tries to resolve the "disk" devalias, it doesn't know which LUN to use. It guesses 0, which has only a 1 in N chance of being right.

There are two possible workarounds:

(1) Put the SD card directly into the XO's SD slot (below the screen; you have to rotate the display 90 degrees to get to it) and then do the 4-keys procedure

(2) Assuming that you can get to the ok prompt (i.e. your system is not in secure mode), there is a manual workaround:

ok  " usb1/disk@3"  fs-update-from-list

Notes:

(a) There must be one space after the first " (i.e. between " and u), and one or more spaces after the second "

(b) Depending on your multi-reader, you might need to use "usb2" instead of "usb1". You can find out by typing "probe-usb" and noting which list shows your device.

(c) The "@3" is just an example - you will need to search manually for the number that corresponds to the SD slot in your multi-reader. The arrow keys can save you some typing during this search.

Reporting problems

If you are unable to update your machine, please let us know:

  1. What version of the software you were upgrading from;
  2. What version you were upgrading to;
  3. What type of machine you have (b1, b2-1, b2-2, b3, b4, etc);
  4. What type of installation media you were using (USB flash key, SD card, something else?);
  5. (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:

  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\Q2E41.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.)

Some additional details

Making a "clean" install

By default, installation process preserves files in /home/olpc. If some of those files are corrupted, it may be desirable to make clean installation.

  • With firmware q2c28 (2007-10-01) or later, just press the SQUARE game key cheat code when installing. Done.
  • With firmware before q2c28 (2007-10-01), the easiest thing to do is delete the datastore and config files. They will be replaced by clean copies upon reinstallation. From the console:
rm -r /home/olpc/.sugar/default/datastore/
rm /home/olpc/.sugar/default/config
rm /home/olpc/.sugar/default/owner.key*
rm /home/olpc/.sugar/default/nm/*
rm /home/olpc/.sugar/default/friends

Then proceed with the standard installation process.

Downgrading

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

If you tried to load a build that is older than the one currently installed on your XO, then you will have gotten a message that the software is up to date. Follow this procedure to load an older version:

Automatic downgrade

Note: please confirm that this method works (it may not for all combinations; the force.os didn't work for at least one case).

(610 q2c27->609 worked for me MitchellNCharity 14:12, 1 October 2007 (EDT))
(542.3 q2c26->405.16 worked for me Hummingbird 20:58, 15 October 2007 (EDT))
  1. 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 both the osNNN.img and osNNN.crc files to which you are downgrading, but not any newer os image.
  2. Create a new file in the boot subdirectory with the name 'force.os'. (It does not matter what is in it; it just matters that the subdirectory exists and has a file with that name.) This will cause the autoreinstallation script to try to install the image in boot/, regardless of whether it is older or newer than the current build on your XO.
  3. Follow the standard autoreinstallation procedure above.

Manual downgrade

You can also downgrade by using the copy-nand command at the OK prompt.

copy-nand d:\boot\os525.img

After the copy, you need to activate your laptop:

  1. reboot the machine holding the 'X' and 'check' game-pad keys; (If your XO does not have a 'check' key, use the 'O' key.)
  2. leave the USB stick in while it writes the activation code.

(Note that automatic backup of user files will fail with this technique.)

Reinstalling the same image

If you want to reinstall the *same* image you've currently got, you should find an earlier stable build, use the downgrade procedure, and then the standard upgrade procedure 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.

Customizing Nand / Generating CRC files

You can create a custom build, but you will then need to generate a CRC file; 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

Network upgrade

The olpc-upgrade command can be run from the console (as root) to upgrade from recent (612+) builds. Usage is olpc-upgrade build#, e.g.,

olpc-upgrade 613

Where to find experimental builds

There are test builds available for developers (joyride, meshtest, debian, etc.). Details are available here.

Cheat codes

Boot options can be controlled by pressing game key Cheat codes at power-on.