OLPC Ethiopia/XO reflash process

  For Developers

THESE INSTRUCTIONS ARE NOT SUITABLE FOR MASS-INSTALLATION.

Introduction

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

Collection

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.

Reflashing

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:

1. Reboot for firmware update
2. Update firmware
3. Reboot for ak tag deletion (undoing preactivation)
4. Delete ak tag, causes another reboot
5. Copy image onto NAND disk
6. 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 OpenFirmware 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:

1. Insert firmware stick
2. Let it upgrade the firmware, reboot, and start the normal boot process
3. Turn off system
4. Unplug firmware stick
5. Plug in reflashing stick
6. Boot and continue the Reflashing instructions as above