Debian Codegraph @

upstream/debian-unstable/man8/usbhid-dump.8

raw
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]>