Skip to main content

Linux Firmware Packages

For virtual devices capable to run Linux (with Arm Cortex-A cores) you can create and run your own firmware packages with Linux distributions. Such firmware package is a zip archive containing multiple file as explained in this section.

Zip package content​

The firmware package with Linux support for Arm Virtual Hardware is a zip archive that shall contain following files:

  • Info.plist file with meta information about the firmware package in JSON format. See details in Info.plist file.
  • kernel file with a Linux kernel in the Image format. See Kernel image file for more.
  • devicetree file with flattened Device Tree Blob (DTB). See Device Tree file for additional information
  • Other files may be required for the boot process on the specific platform. See Storage for details.

An example of Linux firmware package is explained in Custom Firmware for Raspberry Pi 4.

Info.plist file​

An Info.plist file in the firmware package specifies the meta information for the firmware: version, type, build, unique identifier and device identifier, and optionally boot arguments. The file can be also provided under name Info.json with the same format.

Info.plist file example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Type</key>
    <string>iot</string>
    <key>UniqueIdentifier</key>
    <string>Ubuntu Server on RPi</string>
    <key>DeviceIdentifier</key>
    <string>rpi4b</string>
    <key>Version</key>
    <string>22.04.1</string>
    <key>Build</key>
    <string>Ubuntu Server</string>
</dict>
</plist>

Bootargs:

Boot Arguments are specific configuration flags passed to Linux Kernel during the boot process. Every kernel has certain arguments it accepts and the values of these flags can be changed.

See Linux kernel command-line parameters at www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html. Vendor devices may offer other undocumented command-line parameters.

The default bootargs are provided by the model, but can be overriden in the Info.plist or Info.json file. The normal key is used for every regular boot. The restore key, if present, is used for a "firstboot" prior to the device being declared ready. It is expected that the device will reboot itself to indicate that this phase is complete. It is used, for example, on the Raspberry Pi 4 to expand the root fs as shown below:

<key>bootargs</key>
<dict>
    <key>normal</key>
    <string>earlycon=uart8250,mmio32,0xfe215040 console=ttyS0,115200n8 rw rootwait root=/dev/mmcblk0p2 coherent_pool=1M 8250.nr_uarts=1 cma=64M</string>
    <key>restore</key>
    <string>earlycon=uart8250,mmio32,0xfe215040 console=ttyS0,115200n8 console=tty0 rw rootwait root=/dev/mmcblk0p2 coherent_pool=1M 8250.nr_uarts=1 cma=64M init=/usr/lib/raspi-config/init_resize.sh</string>
</dict>

Kernel image file​

A kernel file in the Linux firmware package provides the uncompressed Linux kernel image in Image format.

Device Tree file​

A devicetree file in the firmware package is a binary flattened Device Tree Blob (DTB) that represents the hardware used by bootloaders provided to the kernel. It is a hierarchical representation of devices by connection, used by the kernel to communicate with the I/O buses and other low-level hardware. For more information on device trees, see http://elinux.org/Device_Tree.

The devicetree file shall be present in the firmware package. You can also change the device tree after the virtual device is created without changing the full firmware or re-creating the device instance, see Custom Device Tree for more information.

Storage​

In hardware boards non-volatile memory (NVM) (such as flash memory) is used to provide a OS image and program code for the boot process. In AVH devices this memory is enabled with storage files that need to be provided as part of the firmware pacakge. For the proper names refer to the storage files page for a target device listed in Supported Platforms.

For example, virtual Raspberry Pi 4 uses storage file nand for the content of its microSD flash memory, as also referenced in Storage Files for Raspberry Pi 4.