# Firmware

## Introduction

Device firmware can be accompanied by AppStream upstream metadata, to be incorporated by a distribution. Tools like 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 to the device at runtime.

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

## Example file

A firmware meta-info 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" timestamp="1424116753">
          <location>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab</location>
          <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.

## File specification

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

<id/>

  For firmware, the value of the `<id/>` tag must be a unique name for the device the firmware belongs to, constsing of the vendor domain and the device name. A reverse URL scheme in form of `<tld>.<vendor>.<product>.firmware` is used, e.g. `com.hughski.ColorHug2.firmware`.

<releases/>

  This tag is almost identical to the generic tag. Additional to the generic tag, for each `<release/>` child a `<location/>` tag is allowed, in case the component describes flashed firmware.

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

  Example:

      <releases>
        <release version="3.0.2" timestamp="1424116753">
          <location>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab</location>
          <description>
            <p>This stable release fixes bugs.</p>
          </description>
        </release>
      </releases>

  The `<location/>` tag is currently only allowed to be specified once.

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