diff --git a/plugins/dfu/dfu-tool.c b/plugins/dfu/dfu-tool.c index b3e9e2d98..3d3653a58 100644 --- a/plugins/dfu/dfu-tool.c +++ b/plugins/dfu/dfu-tool.c @@ -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); diff --git a/plugins/dfu/dfu-tool.h2m b/plugins/dfu/dfu-tool.h2m new file mode 100644 index 000000000..98afd1126 --- /dev/null +++ b/plugins/dfu/dfu-tool.h2m @@ -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. diff --git a/plugins/dfu/dfu-tool.sgml b/plugins/dfu/dfu-tool.sgml deleted file mode 100644 index 22aacf25e..000000000 --- a/plugins/dfu/dfu-tool.sgml +++ /dev/null @@ -1,449 +0,0 @@ - - 26 February,2015"> - - GNU"> - GPL"> -]> - - - -
- richard@hughsie.com; -
- - Richard - Hughes - - - 2015 - Richard Hughes - - &date; - - - dfu-tool - 1 - - - &package; - Device Firmware Upgrade Tool - - - - &package; - - - - - - - - - DESCRIPTION - - This manual page documents briefly the &package; command. - - - &package; 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. - - - All synchronous actions can be safely cancelled and on failure will return - errors with both a type and a full textual description. - &package; 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. - - - Additionally &package; 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. - - - - OPTIONS - - This program follows the usual &gnu; command line syntax, - with long options starting with two dashes (-). - A summary of options is included below. - - - - - - - - Show summary of all the commands available for use. - - - - - - - - Show the version of &package; installed. - - - - - - - - Show extra debugging information. - - - - - - - - - If multiple DFU-capable devices are attached you can specify the - specific vendor and product ID of the DFU device you want to query. - - - - - - - - - - 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. - - - - - - - - - - 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. - - - - - - - DEVICE COMMANDS - - These commands are used to interface with DFU-capable devices. - - - - - - - - - This command lists currently attached DFU capable devices. - Some devices do not support the official DFU runtime - 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. - - - - - - - - - - This command detaches the currently attached DFU capable device into - a special programming mode. - Whilst the device is in this special DFU mode it - can not be used as a normal device. - For example, a printer will not accept documents when in DFU mode. - - - - - - - - - - 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. - - - - - - - - - - This command watches DFU devices being hotplugged and can be used to - verify libdfu matches up the runtime and DFU modes - when attaching and detaching. - Use to make this command quit. - - - - - - - - - - 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, - is the command you want. - - - - - - - - - - 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. - - e.g. &package; read-alt backup.dfu SRAM - - - - - - - - - This command downloads firmware from a file into all possible - partitions of a device. - If you only want to write one partition, - is the command you want. - - - - - - - - - - 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. - - e.g. &package; write-alt sram.dfu SRAM __SRAM - - - - - - FIRMWARE COMMANDS - - These commands are used to read and modify existing firmware files. - - - - - - - - - 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. - - - - - - - - - - This command converts the firmware from one format to another, optionally - padding to a certain size. - Possible values for the destination include: - raw, ihex, - dfu and dfuse. - The and 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. - - e.g. &package; convert dfu firmware.hex firmware.dfu 8000 - - - - - - - - - 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 include: - xtea and nop. - If the 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. - - e.g. &package; encrypt firmware.dfu firmware.xdfu xtea deadbeef - - - - - - - - - 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 include: - xtea and nop. - If the 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. - - e.g. &package; decrypt firmware.xdfu firmware.dfu xtea deadbeef - - - - - - - - - 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. - - e.g. &package; merge combined.dfu lib.dfu app.dfu - - - - - - - - - This command modifies the alternative number on firmware file. - - e.g. &package; set-alt-setting firmware.dfu 1 - - - - - - - - - This command modifies the alternative name on firmware file. - - e.g. &package; set-alt-setting-name firmware.dfu SRAM - - - - - - - - - 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 License value should be - specified in SPDX format. - - e.g. &package; set-metadata firmware.dfu Licence GPL-2.0+ - - - - - - - - - This command sets vendor ID on a firmware file that will be used to - match specific devices. - Values of ffff will match any device vendor. - - e.g. &package; set-vendor firmware.dfu 273f - - - - - - - - - This command sets the product ID on a firmware file that will be used to - match specific devices. - Values of ffff will match any device product. - - e.g. &package; set-product firmware.dfu 1004 - - - - - - - - - This command sets the release version on firmware file that will be used to - match specific devices. - Values of ffff will match any device release. - - e.g. &package; set-release firmware.dfu ffff - - - - - - AUTHOR - This manual page was written by Richard Hughes richard@hughsie.com. - - - - - diff --git a/plugins/dfu/meson.build b/plugins/dfu/meson.build index be831797b..bec01a356 100644 --- a/plugins/dfu/meson.build +++ b/plugins/dfu/meson.build @@ -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'),