proxmox-mirrors/fwupd
1
0
Fork 0
mirror of https://git.proxmox.com/git/fwupd synced 2025-08-05 02:54:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

use help2man for dfu-tool too

Browse Source
This commit is contained in:
Mario Limonciello 2018-02-09 10:03:41 -06:00 committed by Richard Hughes
parent 9b8eef4ccc
commit 2c43d3e6e6
4 changed files with 70 additions and 470 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
plugins/dfu/dfu-tool.c
View File

@ -2229,55 +2229,55 @@ main (int argc, char *argv[])
priv->cmd_array = g_ptr_array_new_with_free_func ((GDestroyNotify) dfu_tool_item_free);
dfu_tool_add (priv->cmd_array,
"convert",
NULL,
"FORMAT FILE-IN FILE OUT [SIZE]",
/* TRANSLATORS: command description */
_("Convert firmware to DFU format"),
dfu_tool_convert);
dfu_tool_add (priv->cmd_array,
"merge",
NULL,
"FILE-OUT FILE1 FILE2 [FILE3...]",
/* TRANSLATORS: command description */
_("Merge multiple firmware files into one"),
dfu_tool_merge);
dfu_tool_add (priv->cmd_array,
"set-vendor",
NULL,
"FILE VID",
/* TRANSLATORS: command description */
_("Set vendor ID on firmware file"),
dfu_tool_set_vendor);
dfu_tool_add (priv->cmd_array,
"set-product",
NULL,
"FILE PID",
/* TRANSLATORS: command description */
_("Set product ID on firmware file"),
dfu_tool_set_product);
dfu_tool_add (priv->cmd_array,
"set-address",
NULL,
"FILE ADDRESS",
/* TRANSLATORS: command description */
_("Set element address on firmware file"),
dfu_tool_set_address);
dfu_tool_add (priv->cmd_array,
"set-target-size",
NULL,
"FILE SIZE",
/* TRANSLATORS: command description */
_("Set the firmware size for the target"),
dfu_tool_set_target_size);
dfu_tool_add (priv->cmd_array,
"set-release",
NULL,
"FILE RELEASE",
/* TRANSLATORS: command description */
_("Set release version on firmware file"),
dfu_tool_set_release);
dfu_tool_add (priv->cmd_array,
"set-alt-setting",
NULL,
"FILE ALT-ID",
/* TRANSLATORS: command description */
_("Set alternative number on firmware file"),
dfu_tool_set_alt_setting);
dfu_tool_add (priv->cmd_array,
"set-alt-setting-name",
NULL,
"FILE VALUE",
/* TRANSLATORS: command description */
_("Set alternative name on firmware file"),
dfu_tool_set_alt_setting_name);
@ -2295,13 +2295,13 @@ main (int argc, char *argv[])
dfu_tool_reset);
dfu_tool_add (priv->cmd_array,
"read",
NULL,
"FILENAME",
/* TRANSLATORS: command description */
_("Read firmware from device into a file"),
dfu_tool_read);
dfu_tool_add (priv->cmd_array,
"read-alt",
NULL,
"FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID",
/* TRANSLATORS: command description */
_("Read firmware from one partition into a file"),
dfu_tool_read_alt);
@ -2313,7 +2313,7 @@ main (int argc, char *argv[])
dfu_tool_write);
dfu_tool_add (priv->cmd_array,
"write-alt",
NULL,
"FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID [IMAGE-ALT-NAME|IMAGE-ALT-ID]",
/* TRANSLATORS: command description */
_("Write firmware from file into one partition"),
dfu_tool_write_alt);
@ -2331,7 +2331,7 @@ main (int argc, char *argv[])
dfu_tool_detach);
dfu_tool_add (priv->cmd_array,
"dump",
NULL,
"FILENAME",
/* TRANSLATORS: command description */
_("Dump details about a firmware file"),
dfu_tool_dump);
@ -2343,19 +2343,19 @@ main (int argc, char *argv[])
dfu_tool_watch);
dfu_tool_add (priv->cmd_array,
"encrypt",
NULL,
"FILENAME-IN FILENAME-OUT TYPE KEY",
/* TRANSLATORS: command description */
_("Encrypt firmware data"),
dfu_tool_encrypt);
dfu_tool_add (priv->cmd_array,
"decrypt",
NULL,
"FILENAME-IN FILENAME-OUT TYPE KEY",
/* TRANSLATORS: command description */
_("Decrypt firmware data"),
dfu_tool_decrypt);
dfu_tool_add (priv->cmd_array,
"set-metadata",
NULL,
"FILE KEY VALUE",
/* TRANSLATORS: command description */
_("Sets metadata on a firmware file"),
dfu_tool_set_metadata);

43
plugins/dfu/dfu-tool.h2m Normal file
View 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.

449
plugins/dfu/dfu-tool.sgml
View File

@ -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:
-->

16
plugins/dfu/meson.build
View File

@ -59,7 +59,7 @@ shared_module('fu_plugin_dfu',
],
)
executable(
dfu_tool = executable(
'dfu-tool',
sources : [
'dfu-tool.c',
@ -87,13 +87,19 @@ executable(
)
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',
input : 'dfu-tool.sgml',
input : dfu_tool,
output : 'dfu-tool.1',
command : [
docbook2man, '@INPUT@',
'--output', meson.current_build_dir(),
help2man, '@INPUT@',
'--no-info',
'--output', '@OUTPUT@',
'--name', 'dfu-tool',
'--manual', 'User Commands',
'--version-string', fwupd_version,
'--include', extra,
],
install : true,
install_dir : join_paths(mandir, 'man1'),