Jump to content Jump to page navigation: previous page [access key p]/next page [access key n]
AppStream
AppStream › Upstream Metadata › Firmware
AppStream › Upstream Metadata › Firmware
Top
←→

## 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 id="hughski.com">
        <name>Hughski Limited</name>
      </developer>
      <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/>.