<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title xmlns:d="http://docbook.org/ns/docbook">2.10. Firmware</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta xmlns:d="http://docbook.org/ns/docbook" name="generator" content="publican v4.3.2" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="AppStream-AppStream-0.11-en-US-0.0-0" /><link rel="home" href="index.html" title="AppStream" /><link rel="up" href="chap-Metadata.html" title="Chapter 2. Upstream Metadata" /><link rel="prev" href="sect-Metadata-InputMethod.html" title="2.9. Input Methods" /><link rel="next" href="sect-Metadata-Driver.html" title="2.11. Driver" /></head><body><p id="title"><a class="left" href="http://www.freedesktop.org/wiki/Distributions/AppStream/"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="http://www.freedesktop.org/software/appstream/docs/"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="sect-Metadata-InputMethod.html"><strong>Prev</strong></a></li><li class="home">AppStream</li><li class="next"><a accesskey="n" href="sect-Metadata-Driver.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title"><a id="sect-Metadata-Firmware">
</a>2.10. Firmware</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="spec-firmware-introduction">
</a>2.10.1. Introduction</h3></div></div></div><div class="para">
Device firmware can be accompanied by AppStream upstream metadata, to be incorporated by a distribution. Tools like <a href="https://github.com/hughsie/fwupd">fwupd</a> 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.
</div><div class="para">
Firmware can ship one or more files in <code class="filename">/usr/share/metainfo/%{id}.metainfo.xml</code>.
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="spec-firmware-example">
</a>2.10.2. Example file</h3></div></div></div><div class="para">
A firmware meta-info file should look like this:
</div><pre class="programlisting"><span xmlns="" class="line"></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"><?xml</span> version="1.0" encoding="UTF-8"<span xmlns="" class="perl_Keyword">?></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"><component</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"firmware"</span><span xmlns="" class="perl_Keyword">></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><id></span>com.hughski.ColorHug2.firmware<span xmlns="" class="perl_Keyword"></id></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><name></span>ColorHugALS Firmware<span xmlns="" class="perl_Keyword"></name></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><summary></span>Firmware for the ColorHugALS Ambient Light Sensor<span xmlns="" class="perl_Keyword"></summary></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><description></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><p></span>
<span xmlns="" class="line"></span> Updating the firmware on your ColorHugALS device improves performance and
<span xmlns="" class="line"></span> adds new features.
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></p></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></description></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><url</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"homepage"</span><span xmlns="" class="perl_Keyword">></span>http://www.hughski.com/<span xmlns="" class="perl_Keyword"></url></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><metadata_license></span>CC0-1.0<span xmlns="" class="perl_Keyword"></metadata_license></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><project_license></span>GPL-2.0+<span xmlns="" class="perl_Keyword"></project_license></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><developer_name></span>Hughski Limited<span xmlns="" class="perl_Keyword"></developer_name></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><provides></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><firmware</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"flashed"</span><span xmlns="" class="perl_Keyword">></span>84f40464-9272-4ef7-9399-cd95f12da696<span xmlns="" class="perl_Keyword"></firmware></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></provides></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><releases></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><release</span><span xmlns="" class="perl_Others"> version=</span><span xmlns="" class="perl_String">"3.0.2"</span><span xmlns="" class="perl_Others"> date=</span><span xmlns="" class="perl_String">"2015-02-16"</span><span xmlns="" class="perl_Keyword">></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><location></span>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab<span xmlns="" class="perl_Keyword"></location></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><description></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><p></span>This stable release fixes the following bugs:<span xmlns="" class="perl_Keyword"></p></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><ul></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><li></span>Fix the return code from GetHardwareVersion<span xmlns="" class="perl_Keyword"></li></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><li></span>Scale the output of TakeReadingRaw by the datasheet values<span xmlns="" class="perl_Keyword"></li></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></ul></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></description></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></release></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></releases></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"></component></span></pre><div class="para">
You can find additional information on how to create a complete firmware package for flashed firmware upstream in the <a href="https://github.com/hughsie/fwupd/blob/master/README.md">README document of fwupd</a>.
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="spec-firmware-filespec">
</a>2.10.3. File specification</h3></div></div></div><div class="para">
Note that the XML root must have the <code class="literal">type</code> property set to <code class="code">firmware</code>. This clearly identifies this metainfo document as describing firmware.
</div><div class="variablelist"><dl class="variablelist"><dt><a id="tag-id-firmware">
</a><span class="term"><id/></span></dt><dd><div class="para">
For firmware, the value of the <code class="code"><id/></code> tag must follow the reverse-DNS scheme as described for generic components. It is sometimes useful to suffix the ID with <code class="literal">.firmware</code> to make it more unique. For example <code class="code">com.hughski.ColorHug2.firmware</code>.
</div></dd><dt><a id="tag-firmware-releases">
</a><span class="term"><releases/></span></dt><dd><div class="para">
This tag is almost identical to the generic <a class="xref" href="chap-Metadata.html#tag-releases"><releases/></a> tag. Additional to the generic tag, for each <code class="code"><release/></code> child a <code class="code"><location/></code> tag is allowed, in case the component describes flashed firmware.
</div><div class="para"><a id="tag-firmware-location">
</a>
The <code class="code"><location/></code> tag specifies a remote location where the firmware <code class="literal">.cab</code> can be downloaded from. The download location needs to be accessible via HTTP, HTTPS or FTP.
</div><div class="para">
Example:
</div><pre class="programlisting"><span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"><releases></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><release</span><span xmlns="" class="perl_Others"> version=</span><span xmlns="" class="perl_String">"3.0.2"</span><span xmlns="" class="perl_Others"> date=</span><span xmlns="" class="perl_String">"2015-02-16"</span><span xmlns="" class="perl_Keyword">></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><location></span>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab<span xmlns="" class="perl_Keyword"></location></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><description></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><p></span>This stable release fixes bugs.<span xmlns="" class="perl_Keyword"></p></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></description></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"></release></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"></releases></span></pre><div class="para">
The <code class="code"><location/></code> tag is currently only allowed to be specified once.
</div></dd><dt><a id="tag-firmware-provides">
</a><span class="term"><provides/> ↪ <firmware/></span></dt><dd><div class="para">
The <code class="literal">provides/firmware</code> 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.
</div><div class="para">
For runtime-loadable firmware, the <code class="literal">type</code> property of the <code class="literal">firmware</code> tag needs to be set to <code class="code">runtime</code>, and its value needs to define the filename of a firmware below <code class="filename">/lib/firmware</code> to the firmware file in question, like the firmware value exported from Linux kernel modules.
</div><div class="para">
Example:
</div><pre class="programlisting"><span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"><provides></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><firmware</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"runtime"</span><span xmlns="" class="perl_Keyword">></span>ipw2200-bss.fw<span xmlns="" class="perl_Keyword"></firmware></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"></provides></span></pre><div class="para">
For flashed firmware, the <code class="literal">type</code> property of the tag needs to be set to <code class="code">flashed</code>. Its value needs to define the GUID of the device the firmware should be flashed onto.
</div><div class="para">
Example:
</div><pre class="programlisting"><span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"><provides></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><firmware</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"flashed"</span><span xmlns="" class="perl_Keyword">></span>84f40464-9272-4ef7-9399-cd95f12da696<span xmlns="" class="perl_Keyword"></firmware></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"></provides></span></pre></dd></dl></div><div class="para">
For a component of type <code class="literal">firmware</code>, the following tags are required and must be present for a valid document: <a class="xref" href="sect-Metadata-Firmware.html#tag-id-firmware"><id/></a>, <a class="xref" href="chap-Metadata.html#tag-name"><name/></a>, <a class="xref" href="chap-Metadata.html#tag-summary"><summary/></a>, <a class="xref" href="chap-Metadata.html#tag-metadata_license"><metadata_license/></a>, <a class="xref" href="sect-Metadata-Firmware.html#tag-firmware-provides"><provides/> ↪ <firmware/></a>.
</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="sect-Metadata-InputMethod.html"><strong>Prev</strong>2.9. Input Methods</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="sect-Metadata-Driver.html"><strong>Next</strong>2.11. Driver</a></li></ul></body></html>
