mirror of
https://git.proxmox.com/git/fwupd
synced 2025-08-09 06:12:15 +00:00
use help2man for dfu-tool too
This commit is contained in:
Mario Limonciello
Richard Hughes
parent
9b8eef4ccc
commit
2c43d3e6e6
@ -2229,55 +2229,55 @@ main (int argc, char *argv[])
|
|||||||
priv->cmd_array = g_ptr_array_new_with_free_func ((GDestroyNotify) dfu_tool_item_free);
|
priv->cmd_array = g_ptr_array_new_with_free_func ((GDestroyNotify) dfu_tool_item_free);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"convert",
|
"convert",
|
||||||
NULL,
|
"FORMAT FILE-IN FILE OUT [SIZE]",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Convert firmware to DFU format"),
|
_("Convert firmware to DFU format"),
|
||||||
dfu_tool_convert);
|
dfu_tool_convert);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"merge",
|
"merge",
|
||||||
NULL,
|
"FILE-OUT FILE1 FILE2 [FILE3...]",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Merge multiple firmware files into one"),
|
_("Merge multiple firmware files into one"),
|
||||||
dfu_tool_merge);
|
dfu_tool_merge);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-vendor",
|
"set-vendor",
|
||||||
NULL,
|
"FILE VID",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Set vendor ID on firmware file"),
|
_("Set vendor ID on firmware file"),
|
||||||
dfu_tool_set_vendor);
|
dfu_tool_set_vendor);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-product",
|
"set-product",
|
||||||
NULL,
|
"FILE PID",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Set product ID on firmware file"),
|
_("Set product ID on firmware file"),
|
||||||
dfu_tool_set_product);
|
dfu_tool_set_product);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-address",
|
"set-address",
|
||||||
NULL,
|
"FILE ADDRESS",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Set element address on firmware file"),
|
_("Set element address on firmware file"),
|
||||||
dfu_tool_set_address);
|
dfu_tool_set_address);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-target-size",
|
"set-target-size",
|
||||||
NULL,
|
"FILE SIZE",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Set the firmware size for the target"),
|
_("Set the firmware size for the target"),
|
||||||
dfu_tool_set_target_size);
|
dfu_tool_set_target_size);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-release",
|
"set-release",
|
||||||
NULL,
|
"FILE RELEASE",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Set release version on firmware file"),
|
_("Set release version on firmware file"),
|
||||||
dfu_tool_set_release);
|
dfu_tool_set_release);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-alt-setting",
|
"set-alt-setting",
|
||||||
NULL,
|
"FILE ALT-ID",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Set alternative number on firmware file"),
|
_("Set alternative number on firmware file"),
|
||||||
dfu_tool_set_alt_setting);
|
dfu_tool_set_alt_setting);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-alt-setting-name",
|
"set-alt-setting-name",
|
||||||
NULL,
|
"FILE VALUE",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Set alternative name on firmware file"),
|
_("Set alternative name on firmware file"),
|
||||||
dfu_tool_set_alt_setting_name);
|
dfu_tool_set_alt_setting_name);
|
||||||
@ -2295,13 +2295,13 @@ main (int argc, char *argv[])
|
|||||||
dfu_tool_reset);
|
dfu_tool_reset);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"read",
|
"read",
|
||||||
NULL,
|
"FILENAME",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Read firmware from device into a file"),
|
_("Read firmware from device into a file"),
|
||||||
dfu_tool_read);
|
dfu_tool_read);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"read-alt",
|
"read-alt",
|
||||||
NULL,
|
"FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Read firmware from one partition into a file"),
|
_("Read firmware from one partition into a file"),
|
||||||
dfu_tool_read_alt);
|
dfu_tool_read_alt);
|
||||||
@ -2313,7 +2313,7 @@ main (int argc, char *argv[])
|
|||||||
dfu_tool_write);
|
dfu_tool_write);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"write-alt",
|
"write-alt",
|
||||||
NULL,
|
"FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID [IMAGE-ALT-NAME|IMAGE-ALT-ID]",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Write firmware from file into one partition"),
|
_("Write firmware from file into one partition"),
|
||||||
dfu_tool_write_alt);
|
dfu_tool_write_alt);
|
||||||
@ -2331,7 +2331,7 @@ main (int argc, char *argv[])
|
|||||||
dfu_tool_detach);
|
dfu_tool_detach);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"dump",
|
"dump",
|
||||||
NULL,
|
"FILENAME",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Dump details about a firmware file"),
|
_("Dump details about a firmware file"),
|
||||||
dfu_tool_dump);
|
dfu_tool_dump);
|
||||||
@ -2343,19 +2343,19 @@ main (int argc, char *argv[])
|
|||||||
dfu_tool_watch);
|
dfu_tool_watch);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"encrypt",
|
"encrypt",
|
||||||
NULL,
|
"FILENAME-IN FILENAME-OUT TYPE KEY",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Encrypt firmware data"),
|
_("Encrypt firmware data"),
|
||||||
dfu_tool_encrypt);
|
dfu_tool_encrypt);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"decrypt",
|
"decrypt",
|
||||||
NULL,
|
"FILENAME-IN FILENAME-OUT TYPE KEY",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Decrypt firmware data"),
|
_("Decrypt firmware data"),
|
||||||
dfu_tool_decrypt);
|
dfu_tool_decrypt);
|
||||||
dfu_tool_add (priv->cmd_array,
|
dfu_tool_add (priv->cmd_array,
|
||||||
"set-metadata",
|
"set-metadata",
|
||||||
NULL,
|
"FILE KEY VALUE",
|
||||||
/* TRANSLATORS: command description */
|
/* TRANSLATORS: command description */
|
||||||
_("Sets metadata on a firmware file"),
|
_("Sets metadata on a firmware file"),
|
||||||
dfu_tool_set_metadata);
|
dfu_tool_set_metadata);
|
||||||
|
|||||||
43
plugins/dfu/dfu-tool.h2m
Normal file
43
plugins/dfu/dfu-tool.h2m
Normal file
@ -0,0 +1,43 @@
|
|||||||
|
[DESCRIPTION]
|
||||||
|
.PP
|
||||||
|
This manual page documents briefly the \fBdfu-tool\fR command.
|
||||||
|
.PP
|
||||||
|
\fBdfu-tool\fR allows a user to write various kinds of
|
||||||
|
firmware onto devices supporting the USB Device Firmware Upgrade protocol.
|
||||||
|
This tool can be used to switch the device from the normal runtime mode
|
||||||
|
to `DFU mode' which allows the user to read and write firmware.
|
||||||
|
Either the whole device can be written in one operation, or individual
|
||||||
|
`targets' can be specified with the alternative name or number.
|
||||||
|
.PP
|
||||||
|
\fBdfu-tool\fR uses the libdfu shared
|
||||||
|
library to perform actions.
|
||||||
|
All synchronous actions can be safely cancelled and on failure will return
|
||||||
|
errors with both a type and a full textual description.
|
||||||
|
libdfu supports DFU 1.0, DFU 1.1 and the ST DfuSe vendor extension, and
|
||||||
|
handles many device `quirks' necessary for the real-world implementations
|
||||||
|
of DFU\&.
|
||||||
|
.PP
|
||||||
|
Additionally \fBdfu-tool\fR can be used to convert firmware
|
||||||
|
from various different formats, or to modify details about the elements,
|
||||||
|
images and metadata contained inside the firmware file.
|
||||||
|
For example, you can easily convert DFU 1.1 firmware into the
|
||||||
|
vendor-specific DfuSe format, convert a Intel HEX file into a raw file
|
||||||
|
padded to a specific size, or add new copyright and licensing information
|
||||||
|
to an existing file.
|
||||||
|
Fields such as the vendor and product IDs can be changed, and the firmware
|
||||||
|
elements can be encrypted and decrypted using various different methods.
|
||||||
|
Merging two DfuSe files together is also possible, although specifying
|
||||||
|
different alt-setting numbers before merging is a good idea to avoid
|
||||||
|
confusion.
|
||||||
|
.PP
|
||||||
|
Although \fBdfu-tool\fR tries to provide a large number of
|
||||||
|
easy-to-use commands, it may only be possible to do certain operations
|
||||||
|
using the libdfu library directly.
|
||||||
|
This is easier than it sounds, as the library is built with GObject
|
||||||
|
Introspection support making it usable in many languages such as C,
|
||||||
|
Javascript and Python.
|
||||||
|
Furthermore, using the library is a good idea if you want to perform
|
||||||
|
multiple operations on large firmware files, for instance,
|
||||||
|
converting from an Intel HEX file, padding to a certain size, setting
|
||||||
|
vendor and adding licensing information and then saving to a remote
|
||||||
|
location.
|
||||||
@ -1,449 +0,0 @@
|
|||||||
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
|
|
||||||
<!-- Please adjust the date whenever revising the manpage. -->
|
|
||||||
<!ENTITY date "<date>26 February,2015</date>">
|
|
||||||
<!ENTITY package "dfu-tool">
|
|
||||||
<!ENTITY gnu "<acronym>GNU</acronym>">
|
|
||||||
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
|
|
||||||
]>
|
|
||||||
|
|
||||||
<refentry>
|
|
||||||
<refentryinfo>
|
|
||||||
<address>
|
|
||||||
<email>richard@hughsie.com</email>;
|
|
||||||
</address>
|
|
||||||
<author>
|
|
||||||
<firstname>Richard</firstname>
|
|
||||||
<surname>Hughes</surname>
|
|
||||||
</author>
|
|
||||||
<copyright>
|
|
||||||
<year>2015</year>
|
|
||||||
<holder>Richard Hughes</holder>
|
|
||||||
</copyright>
|
|
||||||
&date;
|
|
||||||
</refentryinfo>
|
|
||||||
<refmeta>
|
|
||||||
<refentrytitle>dfu-tool</refentrytitle>
|
|
||||||
<manvolnum>1</manvolnum>
|
|
||||||
</refmeta>
|
|
||||||
<refnamediv>
|
|
||||||
<refname>&package;</refname>
|
|
||||||
<refpurpose>Device Firmware Upgrade Tool</refpurpose>
|
|
||||||
</refnamediv>
|
|
||||||
<refsynopsisdiv>
|
|
||||||
<cmdsynopsis>
|
|
||||||
<command>&package;</command>
|
|
||||||
<arg><option>--verbose</option></arg>
|
|
||||||
<arg><option>--version</option></arg>
|
|
||||||
<arg><option>--force</option></arg>
|
|
||||||
<arg><option>--device=VID:PID</option></arg>
|
|
||||||
<arg><option>--transfer-size=BYTES</option></arg>
|
|
||||||
</cmdsynopsis>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
<refsect1>
|
|
||||||
<title>DESCRIPTION</title>
|
|
||||||
<para>
|
|
||||||
This manual page documents briefly the <command>&package;</command> command.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<command>&package;</command> allows a user to write various kinds of
|
|
||||||
firmware onto devices supporting the USB Device Firmware Upgrade protocol.
|
|
||||||
This tool can be used to switch the device from the normal runtime mode
|
|
||||||
to `DFU mode' which allows the user to read and write firmware.
|
|
||||||
Either the whole device can be written in one operation, or individual
|
|
||||||
`targets' can be specified with the alternative name or number.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
All synchronous actions can be safely cancelled and on failure will return
|
|
||||||
errors with both a type and a full textual description.
|
|
||||||
<command>&package;</command> supports DFU 1.0, DFU 1.1 and the ST DfuSe
|
|
||||||
vendor extension, and handles many device `quirks' necessary for the
|
|
||||||
real-world implementations of <acronym>DFU</acronym>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Additionally <command>&package;</command> can be used to convert firmware
|
|
||||||
from various different formats, or to modify details about the elements,
|
|
||||||
images and metadata contained inside the firmware file.
|
|
||||||
For example, you can easily convert DFU 1.1 firmware into the
|
|
||||||
vendor-specific DfuSe format, convert a Intel HEX file into a raw file
|
|
||||||
padded to a specific size, or add new copyright and licensing information
|
|
||||||
to an existing file.
|
|
||||||
Fields such as the vendor and product IDs can be changed, and the firmware
|
|
||||||
elements can be encrypted and decrypted using various different methods.
|
|
||||||
Merging two DfuSe files together is also possible, although specifying
|
|
||||||
different alt-setting numbers before merging is a good idea to avoid
|
|
||||||
confusion.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
|
||||||
<refsect1>
|
|
||||||
<title>OPTIONS</title>
|
|
||||||
<para>
|
|
||||||
This program follows the usual &gnu; command line syntax,
|
|
||||||
with long options starting with two dashes (<literal>-</literal>).
|
|
||||||
A summary of options is included below.
|
|
||||||
</para>
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>--help</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>Show summary of all the commands available for use.</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>--version</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>Show the version of <command>&package;</command> installed.</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>--verbose</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>Show extra debugging information.</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>--device=VID:PID</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If multiple DFU-capable devices are attached you can specify the
|
|
||||||
specific vendor and product ID of the DFU device you want to query.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>--transfer-size=BYTES</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Manually override the size of each USB transfer, which you may want
|
|
||||||
for unreliable hardware or when the device lies about the maximum
|
|
||||||
packet size it accepts.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>--force</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Force the operation, disregarding warnings or sanity checks like
|
|
||||||
file CRC and checksums.
|
|
||||||
This is useful if you really know what you are doing, or in the
|
|
||||||
specialised case of fuzz-testing the binary loaders.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</refsect1>
|
|
||||||
<refsect1>
|
|
||||||
<title>DEVICE COMMANDS</title>
|
|
||||||
<para>
|
|
||||||
These commands are used to interface with DFU-capable devices.
|
|
||||||
</para>
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>list</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command lists currently attached DFU capable devices.
|
|
||||||
Some devices do not support the official DFU <literal>runtime</literal>
|
|
||||||
mode and thus do not support auto-discovery using this command.
|
|
||||||
For those devices, putting the device into DFU mode manually (e.g. by
|
|
||||||
holding a button down when rebooting the device) will make it show
|
|
||||||
up here.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>detach</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command detaches the currently attached DFU capable device into
|
|
||||||
a special programming mode.
|
|
||||||
Whilst the device is in this special <acronym>DFU</acronym> mode it
|
|
||||||
can not be used as a normal device.
|
|
||||||
For example, a printer will not accept documents when in DFU mode.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>attach</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command attaches a DFU capable device back to runtime so it can
|
|
||||||
be used as a normal device.
|
|
||||||
Some devices do not support attaching, and need to be manually
|
|
||||||
disconnected and connected before changing modes.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>watch</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command watches DFU devices being hotplugged and can be used to
|
|
||||||
verify <literal>libdfu</literal> matches up the runtime and DFU modes
|
|
||||||
when attaching and detaching.
|
|
||||||
Use <option>CTRL+C</option> to make this command quit.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>read FILENAME</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command uploads all the firmware from device into a file.
|
|
||||||
If the device has multiple partitions exported as different alternative
|
|
||||||
sections then they will all be read into a multi-image DfuSe-format
|
|
||||||
file.
|
|
||||||
If you just want the contents of one partition, <option>read-alt</option>
|
|
||||||
is the command you want.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>read-alt FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command uploads firmware from one partition into a file.
|
|
||||||
You can specify the partition by either the ALT-ID or ALT-NAME if set.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; read-alt backup.dfu SRAM</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>write</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command downloads firmware from a file into all possible
|
|
||||||
partitions of a device.
|
|
||||||
If you only want to write one partition, <option>write-alt</option>
|
|
||||||
is the command you want.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>write-alt FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID [IMAGE-ALT-NAME|IMAGE-ALT-ID]</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command downloads firmware from the file into one partition.
|
|
||||||
You can specify the partition by either the ALT-ID or ALT-NAME if set.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; write-alt sram.dfu SRAM __SRAM</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</refsect1>
|
|
||||||
<refsect1>
|
|
||||||
<title>FIRMWARE COMMANDS</title>
|
|
||||||
<para>
|
|
||||||
These commands are used to read and modify existing firmware files.
|
|
||||||
</para>
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>dump FILENAME</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command dumps all know details about a firmware file.
|
|
||||||
The complete memory map is shown, along with any metadata or vendor
|
|
||||||
information about the firmware file.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>convert FORMAT FILE-IN FILE-OUT [SIZE]</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command converts the firmware from one format to another, optionally
|
|
||||||
padding to a certain size.
|
|
||||||
Possible values for the destination <option>FORMAT</option> include:
|
|
||||||
<literal>raw</literal>, <literal>ihex</literal>,
|
|
||||||
<literal>dfu</literal> and <literal>dfuse</literal>.
|
|
||||||
The <option>FILE-IN</option> and <option>FILE-OUT</option> values can
|
|
||||||
be the same if the source file is to be overwritten.
|
|
||||||
Although padding increases the file size with no apparent advantages
|
|
||||||
it can be used to support devices that do not store the runtime image
|
|
||||||
size and where validation of the written firmware is required.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; convert dfu firmware.hex firmware.dfu 8000</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>encrypt FILENAME-IN FILENAME-OUT TYPE KEY</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command encrypts firmware data.
|
|
||||||
Only the image contents are actually modified, the DFU footer and
|
|
||||||
DfuSe header are left unaltered.
|
|
||||||
Possible values for the destination <option>TYPE</option> include:
|
|
||||||
<literal>xtea</literal> and <literal>nop</literal>.
|
|
||||||
If the <option>KEY</option> is not of the required length it is used
|
|
||||||
as an input to a hash function which can produce a key of the
|
|
||||||
required size.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; encrypt firmware.dfu firmware.xdfu xtea deadbeef</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>decrypt FILENAME-IN FILENAME-OUT TYPE KEY</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command decrypts firmware data.
|
|
||||||
Only the image contents are actually modified, the DFU footer and
|
|
||||||
DfuSe header are left unaltered.
|
|
||||||
Possible values for the destination <option>TYPE</option> include:
|
|
||||||
<literal>xtea</literal> and <literal>nop</literal>.
|
|
||||||
If the <option>KEY</option> is not of the required length it is used
|
|
||||||
as an input to a hash function which can produce a key of the
|
|
||||||
required size.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; decrypt firmware.xdfu firmware.dfu xtea deadbeef</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>merge FILE-OUT FILE1 FILE2 [FILE3...]</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command merges multiple firmware files into one file.
|
|
||||||
Although you can merge files with the same ALT-ID or ALT-NAME this
|
|
||||||
probably isn't what you want to do.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; merge combined.dfu lib.dfu app.dfu</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>set-alt-setting FILE ALT-ID</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command modifies the alternative number on firmware file.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; set-alt-setting firmware.dfu 1</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>set-alt-setting-name</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command modifies the alternative name on firmware file.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; set-alt-setting-name firmware.dfu SRAM</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>set-metadata FILE KEY VALUE</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command adds or modifies existing metadata on a firmware file.
|
|
||||||
NOTE: There is only very limited metadata storage space in DFU files,
|
|
||||||
so keys and values should be kept as short as possible.
|
|
||||||
In particular, the <literal>License</literal> value should be
|
|
||||||
specified in SPDX format.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; set-metadata firmware.dfu Licence GPL-2.0+</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>set-vendor FILE VID</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command sets vendor ID on a firmware file that will be used to
|
|
||||||
match specific devices.
|
|
||||||
Values of <literal>ffff</literal> will match any device vendor.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; set-vendor firmware.dfu 273f</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>set-product FILE PID</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command sets the product ID on a firmware file that will be used to
|
|
||||||
match specific devices.
|
|
||||||
Values of <literal>ffff</literal> will match any device product.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; set-product firmware.dfu 1004</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<option>set-release FILE RELEASE</option>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This command sets the release version on firmware file that will be used to
|
|
||||||
match specific devices.
|
|
||||||
Values of <literal>ffff</literal> will match any device release.
|
|
||||||
</para>
|
|
||||||
<para>e.g. <command>&package; set-release firmware.dfu ffff</command></para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</refsect1>
|
|
||||||
<refsect1>
|
|
||||||
<title>AUTHOR</title>
|
|
||||||
<para>This manual page was written by Richard Hughes <email>richard@hughsie.com</email>.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
|
||||||
</refentry>
|
|
||||||
|
|
||||||
<!-- Keep this comment at the end of the file
|
|
||||||
Local variables:
|
|
||||||
mode: sgml
|
|
||||||
sgml-omittag:t
|
|
||||||
sgml-shorttag:t
|
|
||||||
sgml-minimize-attributes:nil
|
|
||||||
sgml-always-quote-attributes:t
|
|
||||||
sgml-indent-step:2
|
|
||||||
sgml-indent-data:t
|
|
||||||
sgml-parent-document:nil
|
|
||||||
sgml-default-dtd-file:nil
|
|
||||||
sgml-exposed-tags:nil
|
|
||||||
sgml-local-catalogs:nil
|
|
||||||
sgml-local-ecat-files:nil
|
|
||||||
End:
|
|
||||||
-->
|
|
||||||
@ -59,7 +59,7 @@ shared_module('fu_plugin_dfu',
|
|||||||
],
|
],
|
||||||
)
|
)
|
||||||
|
|
||||||
executable(
|
dfu_tool = executable(
|
||||||
'dfu-tool',
|
'dfu-tool',
|
||||||
sources : [
|
sources : [
|
||||||
'dfu-tool.c',
|
'dfu-tool.c',
|
||||||
@ -87,13 +87,19 @@ executable(
|
|||||||
)
|
)
|
||||||
|
|
||||||
if get_option('man')
|
if get_option('man')
|
||||||
docbook2man = find_program('docbook2man')
|
help2man = find_program('help2man')
|
||||||
|
extra = join_paths(meson.current_source_dir(), 'dfu-tool.h2m')
|
||||||
custom_target('dfu-tool-man',
|
custom_target('dfu-tool-man',
|
||||||
input : 'dfu-tool.sgml',
|
input : dfu_tool,
|
||||||
output : 'dfu-tool.1',
|
output : 'dfu-tool.1',
|
||||||
command : [
|
command : [
|
||||||
docbook2man, '@INPUT@',
|
help2man, '@INPUT@',
|
||||||
'--output', meson.current_build_dir(),
|
'--no-info',
|
||||||
|
'--output', '@OUTPUT@',
|
||||||
|
'--name', 'dfu-tool',
|
||||||
|
'--manual', 'User Commands',
|
||||||
|
'--version-string', fwupd_version,
|
||||||
|
'--include', extra,
|
||||||
],
|
],
|
||||||
install : true,
|
install : true,
|
||||||
install_dir : join_paths(mandir, 'man1'),
|
install_dir : join_paths(mandir, 'man1'),
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user