diff options
author | Nikolai Kondrashov <spbnick@gmail.com> | 2012-02-05 15:24:31 +0200 |
---|---|---|
committer | Nikolai Kondrashov <spbnick@gmail.com> | 2012-02-05 15:24:31 +0200 |
commit | 8672e398646657e1a1cd2891524e634e56c40272 (patch) | |
tree | 7e435d95bddb740ae1b6f6d6f9ac5a588db64eda | |
parent | dd79e31fa928dc0f0ef5b771e7275f3d3fbfc5ca (diff) | |
download | usbhid-dump-8672e398646657e1a1cd2891524e634e56c40272.tar.gz |
Add manual page
Add usbhid-dump manual page.
-rw-r--r-- | Makefile.am | 2 | ||||
-rw-r--r-- | configure.ac | 3 | ||||
-rw-r--r-- | doc/.gitignore | 2 | ||||
-rw-r--r-- | doc/Makefile.am | 19 | ||||
-rw-r--r-- | doc/usbhid-dump.8 | 118 |
5 files changed, 142 insertions, 2 deletions
diff --git a/Makefile.am b/Makefile.am index 83db5f7..33d1b4f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -16,7 +16,7 @@ # along with usbhid-dump; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -SUBDIRS = include lib src +SUBDIRS = include lib src doc dist_noinst_SCRIPTS = bootstrap diff --git a/configure.ac b/configure.ac index c8dcba5..98ac558 100644 --- a/configure.ac +++ b/configure.ac @@ -95,5 +95,6 @@ AC_CONFIG_FILES([Makefile include/Makefile include/uhd/Makefile lib/Makefile - src/Makefile]) + src/Makefile + doc/Makefile]) AC_OUTPUT diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..b336cc7 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +/Makefile +/Makefile.in diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..4435bdb --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,19 @@ +# Copyright (C) 2010 Nikolai Kondrashov +# +# This file is part of usbhid-dump. +# +# Usbhid-dump is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# Usbhid-dump is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with usbhid-dump; if not, write to the Free Software +# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + +dist_man_MANS = usbhid-dump.8 diff --git a/doc/usbhid-dump.8 b/doc/usbhid-dump.8 new file mode 100644 index 0000000..868c452 --- /dev/null +++ b/doc/usbhid-dump.8 @@ -0,0 +1,118 @@ +.\" Process this file with +.\" groff -man -Tascii usbhid-dump.8 +.\" +.\" This file is part of usbhid-dump. +.\" +.\" Usbhid-dump is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" Usbhid-dump is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with usbhid-dump; if not, write to the Free Software +.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +.\" +.TH usbhid-dump "8" "February 2012" +.SH NAME +usbhid-dump \- dump USB HID device report descriptors and streams +.SH SYNOPSIS +.B usbhid-dump +[OPTION]... +.SH DESCRIPTION +.B usbhid-dump +uses +.B libusb +to dump report descriptors and streams from HID (human interface device) +interfaces of USB devices. By default, it dumps HID interfaces of all +connected USB devices, but could be limited to a subset of them, or to a single +interface, using options. + +NOTE: usbhid-dump detaches kernel drivers from the interfaces it dumps and uses +them exclusively, so no other program receives the input in the meantime. The +report descriptor dumping is instantaneous, but the stream dumping continues +until terminated with SIGINT (^C from the terminal) or a timeout expires. + +If you accidentally start dumping a stream from the USB keyboard you use to +control the terminal, the system will stop receiving the input and you won't +be able to terminate usbhid-dump. Just stop your input and wait until the +timeout expires. The stream dumping will stop, the keyboard will be +reattached to the kernel driver and you will regain control. + +The default stream dumping timeout is 60 seconds and could be changed with the +-t option. +.SH OPTIONS +.TP +.B -h, --help +Output a help message and exit. +.TP +.B -v, --version +Output version information and exit. +.TP +.B -s, -a, --address=bus[:dev] +Limit interfaces by bus number and device address. Both 1-255, decimal. +Zeroes match any bus or device. +.TP +.B -d, -m, --model=vid[:pid] +Limit interfaces by device vendor and product IDs. Both 1-FFFF, hexadecimal. +Zeroes match any vendor or product. +.TP +.B -i, --interface=NUMBER +Limit interfaces by number (0-254), decimal. 255 matches any interface. +.TP +.B -e, --entity=STRING +The entity to dump: either "descriptor", "stream" or "all". The value can be +abbreviated down to one letter. The default is "descriptor". +.TP +.B -t, --stream-timeout=NUMBER +Stream interrupt transfer timeout, ms. Zero means infinity. The default is +60000 (60 seconds). +.TP +.B -p, --stream-paused +Start with the stream dump output paused. +.TP +.B -f, --stream-feedback +Enable stream dumping feedback: print a dot to stderr for every transfer +dumped. +.SH SIGNALS +.TP +.B USR1/USR2 +Pause/resume stream dump output. +.SH OUTPUT FORMAT +.B usbhid-dump +outputs dumps in chunks. Each chunk is separated by an empty line and starts +with the following header line: + +BUS:DEVICE:INTERFACE:ENTITY TIMESTAMP + +Here, BUS, DEVICE and INTERFACE are bus, device and interface numbers +respectively. ENTITY is either "DESCRIPTOR" or "STREAM". TIMESTAMP is +timestamp in seconds since epoch. + +After the header the actual dump data follows as hex bytes. A descriptor +chunk includes the whole report descriptor. Every stream chunk includes a +whole report, usually, but if a report is bigger than endpoint's +wMaxPacketSize, it will span several chunks. +.SH EXAMPLES +.TP +Dump report descriptor for a device with address 3 on bus number 2: +.B usbhid-dump -a 2:3 + +.TP +Dump report stream for a device with vendor ID 0x5543 and product ID 0x0005: +.B usbhid-dump -m 5543:0005 -es + +.TP +Dump report descriptor from interface 1 of a device with vendor ID 0x5543: +.B usbhid-dump -m 5543 -i 1 -ed + +.TP +Dump report streams from all HID interfaces of all USB devices (caution: you will loose control over the terminal if you use USB keyboard): +.B usbhid-dump -es + +.SH AUTHOR +Nikolai Kondrashov <spbnick@gmail.com> |