| 1 |
.\"SPDX-License-Identifier: GPL-2.0-or-later |
| 2 |
.\" Copyright Nikolai Kondrashov <[email protected]> |
| 3 |
.TH usbhid-dump "8" "February 2012" "usbutils" "Linux USB Utilities" |
| 4 |
.IX usbhid-dump |
| 5 |
.SH NAME |
| 6 |
usbhid-dump \- dump USB HID device report descriptors and streams |
| 7 |
.SH SYNOPSIS |
| 8 |
.B usbhid-dump |
| 9 |
[OPTION]... |
| 10 |
.SH DESCRIPTION |
| 11 |
.B usbhid-dump |
| 12 |
uses |
| 13 |
.B libusb |
| 14 |
to dump report descriptors and streams from HID (human interface device) |
| 15 |
interfaces of USB devices. By default, it dumps HID interfaces of all |
| 16 |
connected USB devices, but could be limited to a subset of them, or to a single |
| 17 |
interface, using options. |
| 18 |
|
| 19 |
NOTE: usbhid-dump detaches kernel drivers from the interfaces it dumps and uses |
| 20 |
them exclusively, so no other program receives the input in the meantime. The |
| 21 |
report descriptor dumping is instantaneous, but the stream dumping continues |
| 22 |
until terminated with SIGINT (^C from the terminal) or a timeout expires. |
| 23 |
|
| 24 |
If you accidentally start dumping a stream from the USB keyboard you use to |
| 25 |
control the terminal, the system will stop receiving the input and you won't |
| 26 |
be able to terminate usbhid-dump. Just stop your input and wait until the |
| 27 |
timeout expires. The stream dumping will stop, the keyboard will be |
| 28 |
reattached to the kernel driver and you will regain control. |
| 29 |
|
| 30 |
The default stream dumping timeout is 60 seconds and could be changed with the |
| 31 |
-t option. |
| 32 |
.SH OPTIONS |
| 33 |
.TP |
| 34 |
.B -h, --help |
| 35 |
Output a help message and exit. |
| 36 |
.TP |
| 37 |
.B -v, --version |
| 38 |
Output version information and exit. |
| 39 |
.TP |
| 40 |
.B -s, -a, --address=bus[:dev] |
| 41 |
Limit interfaces by bus number and device address. Both 1-255, decimal. |
| 42 |
Zeroes match any bus or device. |
| 43 |
.TP |
| 44 |
.B -d, -m, --model=vid[:pid] |
| 45 |
Limit interfaces by device vendor and product IDs. Both 1-FFFF, hexadecimal. |
| 46 |
Zeroes match any vendor or product. |
| 47 |
.TP |
| 48 |
.B -i, --interface=NUMBER |
| 49 |
Limit interfaces by number (0-254), decimal. 255 matches any interface. |
| 50 |
.TP |
| 51 |
.B -e, --entity=STRING |
| 52 |
The entity to dump: either "descriptor", "stream" or "all". The value can be |
| 53 |
abbreviated down to one letter. The default is "descriptor". |
| 54 |
.TP |
| 55 |
.B -t, --stream-timeout=NUMBER |
| 56 |
Stream interrupt transfer timeout, ms. Zero means infinity. The default is |
| 57 |
60000 (60 seconds). |
| 58 |
.TP |
| 59 |
.B -p, --stream-paused |
| 60 |
Start with the stream dump output paused. |
| 61 |
.TP |
| 62 |
.B -f, --stream-feedback |
| 63 |
Enable stream dumping feedback: print a dot to stderr for every transfer |
| 64 |
dumped. |
| 65 |
.SH SIGNALS |
| 66 |
.TP |
| 67 |
.B USR1/USR2 |
| 68 |
Pause/resume stream dump output. |
| 69 |
.SH OUTPUT FORMAT |
| 70 |
.B usbhid-dump |
| 71 |
outputs dumps in chunks. Each chunk is separated by an empty line and starts |
| 72 |
with the following header line: |
| 73 |
|
| 74 |
BUS:DEVICE:INTERFACE:ENTITY TIMESTAMP |
| 75 |
|
| 76 |
Here, BUS, DEVICE and INTERFACE are bus, device and interface numbers |
| 77 |
respectively. ENTITY is either "DESCRIPTOR" or "STREAM". TIMESTAMP is |
| 78 |
timestamp in seconds since epoch. |
| 79 |
|
| 80 |
After the header the actual dump data follows as hex bytes. A descriptor |
| 81 |
chunk includes the whole report descriptor. Every stream chunk includes a |
| 82 |
whole report, usually, but if a report is bigger than endpoint's |
| 83 |
wMaxPacketSize, it will span several chunks. |
| 84 |
.SH EXAMPLES |
| 85 |
.TP |
| 86 |
Dump report descriptor for a device with address 3 on bus number 2: |
| 87 |
.B usbhid-dump -a 2:3 |
| 88 |
|
| 89 |
.TP |
| 90 |
Dump report stream for a device with vendor ID 0x5543 and product ID 0x0005: |
| 91 |
.B usbhid-dump -m 5543:0005 -es |
| 92 |
|
| 93 |
.TP |
| 94 |
Dump report descriptor from interface 1 of a device with vendor ID 0x5543: |
| 95 |
.B usbhid-dump -m 5543 -i 1 -ed |
| 96 |
|
| 97 |
.TP |
| 98 |
Dump report streams from all HID interfaces of all USB devices (caution: you will lose control over the terminal if you use USB keyboard): |
| 99 |
.B usbhid-dump -es |
| 100 |
|
| 101 |
.SH AUTHOR |
| 102 |
Nikolai Kondrashov <[email protected]> |