Imaging for XO-1.5

XO-1.5 only. Tested by User:Quozl using os304 on 2010-08-05.

How to build your own operating system image file, by extracting an image from a laptop and using our tools to convert to the format required by the firmware.

You might do this in order to rapidly deploy a customised image, using fs-update or NANDblaster for XO-1.5.

Know the image size

• identify the .zd file you are starting with,
• read the first line of the file to determine the amount of space taken by the image,

$ head -1 os304.zd
zblocks: 20000 7331

These values are hex. They represent a block size of 131072 decimal, and a block count of 29489 decimal. These are used below.

Prepare image

You may prepare the image on the internal microSD, or an external SD card. See the appropriate subsection below.

Internal microSD

• prepare the image on the laptop's internal microSD, e.g. by installing the build and making changes, remove the files that cause side effects on imaging, and then shutdown,
• boot an OLPC build from external SD or use a USB booted Linux (such as Tiny Core Linux)
• prepare an output directory with enough space to hold the image,
  • if you are booting an OLPC build from external SD, you must first mount a USB stick larger than the build you are imaging, e.g. mount /dev/sda1 /mnt
  • if you are booting from media that is not mounted after boot, as is the case with Tiny Core Linux, you will need to mount it, e.g. mount /dev/sda1 /mnt
• capture the image:

$ dd if=/dev/mmcblk0 of=/mnt/fs.img bs=131072 count=29489

After doing this you will have an fs.img file that contains the raw blocks of the internal microSD.

External SD

• prepare the image on a removable SD, e.g. by installing the build to the removable SD and making changes, remove the files that cause side effects on imaging, and then shutdown,
• remove the SD card and insert into a running system, identify the block device from /proc/partitions,
• capture the image

$ dd if=/dev/mmcblk1 of=fs.img bs=131072 count=29489

Convert to ZD

• install some development tools:

# yum install git make gcc zlib-devel libtomcrypt-devel

• clone the git repository of the bios crypto source package and build it:

$ git clone --depth=1 git://dev.laptop.org/bios-crypto
$ cd bios-crypto/build
$ make zhashfs

• convert the fs.img file to .zd format (this takes a fair while if run on XO-1.5 hardware, but block number progress feedback is provided):

$ ./zhashfs 0x20000 sha256 fs.img fs.zsp fs.zd

Installing

fs-update

• place the fs.zd file on a USB stick,
• at Ok prompt use fs-update to install the image:

ok fs-update u:\fs.zd

The total block count shown after fs-update completes should match the block count determined earlier.

NANDblaster

• place the fs.zd file on a USB stick,
• sign the build with your deployment keys and place the fs.zip file on a USB stick,
• insert USB stick in sending XO,
• at Ok prompt use nb-secure to transmit the image:

ok nb-secure

See NANDblaster for more information.

Optimisations

Some ideas for optimisation of this process.

zerofree

The zerofree package available for Fedora can zero free blocks on the ext2 and ext3 filesystems that are in the fs.img file, so that the minimum amount of data is processed by zhashfs. zerofree does not appear to support offsets into the file, however, so it must be used on the original device.

Zerofree is ineffective on the original image, since it was built with zero blocks already. It is effective if the image you are building has contained many files that have since been deleted.

pv

The pv package available for Fedora provides progress reports for the image capture stage. In place of the dd command above, an alternative command is:

pv /dev/mmcblk0 | dd of=/mnt/fs.img bs=131072 count=29489