Add manual page

Add usbhid-dump manual page.

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>