Firmware zip file handling: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Created page with '{{draft}} The firmware and the security system deals with zip archives found in the <tt>/boot</tt> directory of the boot partition. These zip files are: *…')
 
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{draft}}

The firmware and the [[Firmware security|security system]] deals with zip archives found in the <tt>/boot</tt> directory of the boot partition. These zip files are:
The firmware and the [[Firmware security|security system]] deals with zip archives found in the <tt>/boot</tt> directory of the boot partition. These zip files are:


* <tt>bootfw</tt>: an on-disk copy of the OpenFirmware image, used for automatic firmware upgrades
* <tt>bootfw</tt>: an on-disk copy of the Open Firmware image, used for automatic firmware upgrades
* <tt>runos</tt>: an executable image treated as the operating system kernel for normal boots of the system
* <tt>runos</tt>: an executable image loaded as the operating system kernel for normal boots of the system
* <tt>runrd</tt>: a ramdisk image loaded into memory when runos is booted
* <tt>runrd</tt>: a ramdisk image loaded when runos is booted
* <tt>actos</tt>: an executable image treated as theoperating system kernel for when the system is booted in activation mode
* <tt>actos</tt>: an executable image loaded as the operating system kernel for when the system is booted in activation mode
* <tt>actrd</tt>: a ramdisk image loaded into memory when actos is booted
* <tt>actrd</tt>: a ramdisk image loaded when actos is booted
* <tt>fs</tt>: contains checksums for an accompanying filesystem image
* <tt>fs</tt>: contains checksums for an accompanying filesystem image


== Zip file contents ==
== Zip file contents ==


Note that executable images above can be simple forth scripts, and the ramdisks are optional (if not needed to boot the OS).
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).

<tt>bootfw</tt> 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 <tt>data.img</tt>. If dealing with signed content, the signature is stored in a file called <tt>data.sig</tt> in the [[Firmware Key and Signature Formats#Signature|firmware signature format]] with hashname "sha256".
The content (as described above) must be stored in the zip file in a file called <tt>data.img</tt>. If dealing with signed content, the signature is stored in a file called <tt>data.sig</tt> in the [[Firmware Key and Signature Formats#Signature|firmware signature format]] with hashname "sha256".


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


== Zip file naming ==
== Zip file naming ==
Line 34: Line 36:
* <tt>fs2.zip</tt> - Filesystem image checksums for an XO-1.75 image
* <tt>fs2.zip</tt> - Filesystem image checksums for an XO-1.75 image


In each situation where OFW 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. <tt>actos.zip</tt>, <tt>fs.zip</tt>).
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. <tt>actos.zip</tt>, <tt>fs.zip</tt>).


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

Latest revision as of 02:38, 27 November 2012

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.