Firmware | AppStream | AppStream 0.16

AppStream › Upstream Metadata › Firmware

AppStream

Navigation←→

2.12 Firmware #

2.12.1 Introduction #

Device firmware can be accompanied by AppStream upstream metadata, to be incorporated by a distribution. Tools like fwupd (https://github.com/hughsie/fwupd) make use of this metadata to automatically update flashed firmware of devices found in the machine. Additionally, this component type can also be used for firmware which is loaded onto the device at runtime.

Firmware can ship one or more files in /usr/share/metainfo/%{id}.metainfo.xml.

2.12.2 Example file #

A firmware metainfo file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<component type="firmware">
  <id>com.hughski.ColorHug2.firmware</id>
  <name>ColorHugALS Firmware</name>
  <summary>Firmware for the ColorHugALS Ambient Light Sensor</summary>
  <description>
    <p>
      Updating the firmware on your ColorHugALS device improves performance and
      adds new features.
    </p>
  </description>
  <url type="homepage">http://www.hughski.com/</url>
  <metadata_license>CC0-1.0</metadata_license>
  <project_license>GPL-2.0+</project_license>
  <developer_name>Hughski Limited</developer_name>
  <provides>
    <firmware type="flashed">84f40464-9272-4ef7-9399-cd95f12da696</firmware>
  </provides>
  <releases>
    <release version="3.0.2" date="2015-02-16">
      <artifacts>
        <artifact type="binary">
          <location>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab</location>
        </artifact>
      </artifacts>
      <description>
        <p>This stable release fixes the following bugs:</p>
        <ul>
          <li>Fix the return code from GetHardwareVersion</li>
          <li>Scale the output of TakeReadingRaw by the datasheet values</li>
        </ul>
      </description>
    </release>
  </releases>
</component>

You can find additional information on how to create a complete firmware package for flashed firmware upstream in the README document of fwupd (https://github.com/hughsie/fwupd/blob/master/README.md).

2.12.3 File specification #

Note that the XML root must have the type property set to firmware. This clearly identifies this metainfo document as describing firmware.

<id/> #

For firmware, the value of the <id/> tag must follow the reverse-DNS scheme as described for generic components. It is sometimes useful to suffix the ID with .firmware to make it more unique. For example com.hughski.ColorHug2.firmware.

<releases/> #

This tag is identical to the generic <releases/> tag. Additional to the generic tag, for each <release/> child at least one <artifact/> tag is required in case the component describes flashed firmware.

The <location/> tag of the binary artifact specifies a remote location where the firmware .cab can be downloaded from. The download location needs to be accessible via HTTP, HTTPS or FTP.

Example:

<releases>
  <release version="3.0.2" date="2015-02-16">
    <artifacts>
      <artifact type="binary">
        <location>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab</location>
      </artifact>
    </artifacts>
    <description>
      <p>This stable release fixes bugs.</p>
    </description>
  </release>
</releases>

<provides/> ↪ <firmware/> #

The provides/firmware tag describes the technical information needed to associate a firmware with a device, or describes which runtime firmware file it makes available to the kernel.

For runtime-loadable firmware, the type property of the firmware tag needs to be set to runtime, and its value needs to define the filename of a firmware below /lib/firmware to the firmware file in question, like the firmware value exported from Linux kernel modules.

Example:

<provides>
  <firmware type="runtime">ipw2200-bss.fw</firmware>
</provides>

For flashed firmware, the type property of the tag needs to be set to flashed. Its value needs to define the GUID of the device the firmware should be flashed onto.

Example:

<provides>
  <firmware type="flashed">84f40464-9272-4ef7-9399-cd95f12da696</firmware>
</provides>

For a component of type firmware, the following tags are required and must be present for a valid document: <id/>, <name/>, <summary/>, <metadata_license/>, <provides/> ↪ <firmware/>.