Firmware zip file handling

The firmware and the security system deals with zip archives found in the /boot directory of the boot partition. These zip files are:

• bootfw: an on-disk copy of the Open Firmware image, used for automatic firmware upgrades
• runos: an executable image loaded as the operating system kernel for normal boots of the system
• runrd: a ramdisk image loaded when runos is booted
• actos: an executable image loaded as the operating system kernel for when the system is booted in activation mode
• actrd: a ramdisk image loaded when actos is booted
• fs: contains checksums for an accompanying filesystem image

Zip file contents

Note that executable images above must contain a load format supported by Open Firmware. The two most common that we use are Linux bzImage and simple forth scripts.

The ramdisks are optional (if not needed to boot the OS). When used, the ramdisk zip must contain a ramdisk image format supported by the kernel (we usually use initramfs format).

bootfw contains a firmware in the normal Open Firmware image format.

The content (as described above) must be stored in the zip file in a file called data.img. If dealing with signed content, the signature is stored in a file called data.sig in the firmware signature format with hashname "sha256".

All files in the zip file must be uncompressed; Open Firmware will not access compressed files inside the zip file.

Zip file naming

Each zip file is named according to its base name, followed by a laptop model suffix, followed by the extension .zip.

The laptop model suffixes are:

• 0: XO-1
• 1: XO-1.5
• 2: XO-1.75
• 3: XO-3
• 4: XO-4

For example:

• bootfw4.zip - Firmware for the XO-4
• fs2.zip - Filesystem image checksums for an XO-1.75 image

In each situation where Open Firmware seeks one of the above zip files, it will first try the naming scheme detailed above. If such a file is not found, it will fall back on the same filename but without the model suffix (e.g. actos.zip, fs.zip).

Old, released versions of XO-1 and XO-1.5 firmwares do not support the naming scheme that includes the model suffix, so when working with the XO-1 and XO-1.5, you will need to ship files without the model suffix (or perhaps back-compat symlinks) to retain full compatibility with all released versions.

Another reason for the firmware continuing to fall-back on "unversioned" zip file names is for convenience; as executable images can be machine-independent (e.g. the Collection stick is a machine-independent signed forth script), it is useful to be able to share a single file between multiple laptop models.