OLPC Ethiopia/XO reflash process
These instructions are unofficial. OLPC does not support them.
THESE INSTRUCTIONS ARE EXPERIMENTAL.
FOLLOWING THEM MAY DAMAGE YOUR MACHINE.
By following them, you take responsibility for this risk.
THESE INSTRUCTIONS ARE NOT SUITABLE FOR MASS-INSTALLATION.
Ethiopia received 5000 laptops that were all preactivated. However, activation security was a critical part of the plan from the start, so it is necessary to turn this off on every XO. This requires a developer key to reach the OFW prompt.
Additionally, a custom OS image is used, based on XO OS 8.1 build 708. Another problem is that a large number of USB keys in the ecbp office do not work with the firmware that came on the laptops from the factory.
When done manually, this means as many as 4 USB keys are required. We have automated some of the process as described below, so that just 2 keys are required (actually just one, since the steps do not overlap).
First, create a collection key as described on Activation and developer keys. Plug this key into the group of XOs that you are working on. We do it in groups of 200.
Take the resultant leases.dat file and upload it to the activation.laptop.org web interface, first generating developer keys, and then generating activation leases.
Next, take a USB key and set it up as follows
- Put lease.sig in the root directory
- Put develop.sig in the security subdirectory
- Put the .img and .crc files of your image in the root directory
- Take the signed firmware image (bootfw.zip) of the firmware inside your image (or newer) and put it in the boot subdirectory. If you want to extract this from the image, you can find it at /boot/bootfw.zip on a booted XO.
- Copy and paste the following Forth script into a file named "olpc.fth" in the boot subdirectory
\ boot script to delete ak tag, copy flash, and secure boot for leasing : do-firmware-update ( img$ -- ) \ Keep .error from printing an input sream position report \ which makes a buffer@<address> show up in the error message ['] noop to show-error visible tuck flash-buf swap move ( len ) ['] ?image-valid catch ?dup if ( ) visible red-letters ." Bad firmware image file - " .error ." Continuing with old firmware" cr black-letters exit then true to file-loaded? d# 12,000 wait-until \ Wait for EC to notice the battery ['] ?enough-power catch ?dup if visible red-letters ." Unsafe to update firmware now - " .error ." Continuing with old firmware" cr black-letters exit then " Updating firmware" ?lease-debug-cr ec-indexed-io-off? if visible ." Restarting to enable SPI FLASH writing." cr d# 3000 ms ec-ixio-reboot security-failure then \ Latch alternate? flag for next startup alternate? if [char] A h# 82 cmos! then reflash \ Should power-off and reboot show-x " Reflash returned, unexpectedly" .security-failure ; [then] [ifndef] ?ofw-reflash \ Check for new firmware. : ?ofw-reflash ( -- ) " u:\boot\bootfw.zip" expand$ ['] (boot-read) catch if 2drop exit then img$ firmware-up-to-date? if exit then img$ do-firmware-update ; [then] : update-sequence unfreeze ?ofw-reflash " ak" ['] $delete-tag catch if 2drop ." AK tag gone, flash now" cr then " copy-nand u:\708ak.img" evaluate ." Done flashing, now booting for leasing" 2000 ms button-x to game-key-mask true to secure? secure-startup ; update-sequence
Update the "copy-nand" line with the appropriate path to your OS image file.
Plug the USB key into an XO, and turn it on. It will do the following:
- Reboot for firmware update
- Update firmware
- Reboot for ak tag deletion (undoing preactivation)
- Delete ak tag, causes another reboot
- Copy image onto NAND disk
- Boot in secure mode
- Secure mode will cause the lease to be installed during boot
- You end up in Sugar, at which point you can power off by pressing Ctrl+Alt+Mesh, Enter, poweroff, Enter
Beware that if you then boot the system again with the USB key plugged in, it will run copy-nand again, erasing anything you have saved on disk.
You can make multiple copies of this USB stick to speed up the process by flashing multiple XOs in parallel. We do about 25 at a time.
Factory firmware problems
We have twenty-something Kingston USB sticks which do not work with the Open Firmware present on the machines as they arrived from the factory. However, as the flashing takes a long time sometimes it is useful for us to use them, allowing us to flash larger number of machines in parallel. In this case, we use a small number of the non-Kingston "good" USB sticks to flash the firmware first, then we are able to use our large number of Kingston disks.
We set up the Kingston disks according to the Reflashing procedure above. Then we take a few non-Kingston sticks and make them firmware sticks including a single "bootfw.zip" file in the boot subdirectory (nothing else needed on the stick). The bootfw.zip file can be any signed firmware image that supports the Kingston sticks, we recommend using the same bootfw.zip that you put on the reflashing keys.
The reflashing process then becomes:
- Insert firmware stick
- Let it upgrade the firmware, reboot, and start the normal boot process
- Turn off system
- Unplug firmware stick
- Plug in reflashing stick
- Boot and continue the Reflashing instructions as above