aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/usb/usbmon.txt
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@woody.linux-foundation.org>2007-04-27 17:19:17 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-04-27 17:19:17 -0400
commit50f732ee63b91eb08a29974b36bd63e1150bb642 (patch)
treefdfc63411a34ffbe26a3b0a997aaeff742a0301b /Documentation/usb/usbmon.txt
parentaa5bc2b58e3344da57f26b62e99e13e91c9e0a94 (diff)
parenta7205b30106a2d4ee268132644cdb292da2d9b41 (diff)
Merge master.kernel.org:/pub/scm/linux/kernel/git/gregkh/usb-2.6
* master.kernel.org:/pub/scm/linux/kernel/git/gregkh/usb-2.6: (78 commits) USB: update MAINAINERS and CREDITS for Freescale USB driver USB: update gadget files for fsl_usb2_udc driver USB: add Freescale high-speed USB SOC device controller driver USB: quirk for broken suspend of IT8152F/G USB: iowarrior.c: timeouts too small in usb_control_msg calls USB: dell device id for option.c USB: Remove Huawei unusual_devs entry USB: CP2101 New Device IDs USB: add picdem device to ldusb usbfs micro optimitation USB: remove ancient/broken CRIS hcd usb ethernet gadget, workaround network stack API glitch USB: add "busnum" attribute for USB devices USB: cxacru: ADSL state management usbatm: Detect usb device shutdown and ignore failed urbs USB: Remove duplicate define of OHCI_QUIRK_ZFMICRO USB: BandRich BandLuxe HSDPA Data Card Driver USB gadget rndis: fix struct rndis_packet_msg_type unaligned bug USB Elan FTDI: check for driver registration status USB: sierra: add more checks on shutdown ...
Diffstat (limited to 'Documentation/usb/usbmon.txt')
-rw-r--r--Documentation/usb/usbmon.txt80
1 files changed, 56 insertions, 24 deletions
diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt
index 0f6808abd612..53ae866ae37b 100644
--- a/Documentation/usb/usbmon.txt
+++ b/Documentation/usb/usbmon.txt
@@ -16,7 +16,7 @@ situation as with tcpdump.
16 16
17Unlike the packet socket, usbmon has an interface which provides traces 17Unlike the packet socket, usbmon has an interface which provides traces
18in a text format. This is used for two purposes. First, it serves as a 18in a text format. This is used for two purposes. First, it serves as a
19common trace exchange format for tools while most sophisticated formats 19common trace exchange format for tools while more sophisticated formats
20are finalized. Second, humans can read it in case tools are not available. 20are finalized. Second, humans can read it in case tools are not available.
21 21
22To collect a raw text trace, execute following steps. 22To collect a raw text trace, execute following steps.
@@ -34,7 +34,7 @@ if usbmon is built into the kernel.
34Verify that bus sockets are present. 34Verify that bus sockets are present.
35 35
36# ls /sys/kernel/debug/usbmon 36# ls /sys/kernel/debug/usbmon
371s 1t 2s 2t 3s 3t 4s 4t 371s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
38# 38#
39 39
402. Find which bus connects to the desired device 402. Find which bus connects to the desired device
@@ -54,7 +54,7 @@ Bus=03 means it's bus 3.
54 54
553. Start 'cat' 553. Start 'cat'
56 56
57# cat /sys/kernel/debug/usbmon/3t > /tmp/1.mon.out 57# cat /sys/kernel/debug/usbmon/3u > /tmp/1.mon.out
58 58
59This process will be reading until killed. Naturally, the output can be 59This process will be reading until killed. Naturally, the output can be
60redirected to a desirable location. This is preferred, because it is going 60redirected to a desirable location. This is preferred, because it is going
@@ -75,46 +75,80 @@ that the file size is not excessive for your favourite editor.
75 75
76* Raw text data format 76* Raw text data format
77 77
78The '1t' type data consists of a stream of events, such as URB submission, 78Two formats are supported currently: the original, or '1t' format, and
79the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
80format adds a few fields, such as ISO frame descriptors, interval, etc.
81It produces slightly longer lines, but otherwise is a perfect superset
82of '1t' format.
83
84If it is desired to recognize one from the other in a program, look at the
85"address" word (see below), where '1u' format adds a bus number. If 2 colons
86are present, it's the '1t' format, otherwise '1u'.
87
88Any text format data consists of a stream of events, such as URB submission,
79URB callback, submission error. Every event is a text line, which consists 89URB callback, submission error. Every event is a text line, which consists
80of whitespace separated words. The number or position of words may depend 90of whitespace separated words. The number or position of words may depend
81on the event type, but there is a set of words, common for all types. 91on the event type, but there is a set of words, common for all types.
82 92
83Here is the list of words, from left to right: 93Here is the list of words, from left to right:
94
84- URB Tag. This is used to identify URBs is normally a kernel mode address 95- URB Tag. This is used to identify URBs is normally a kernel mode address
85 of the URB structure in hexadecimal. 96 of the URB structure in hexadecimal.
97
86- Timestamp in microseconds, a decimal number. The timestamp's resolution 98- Timestamp in microseconds, a decimal number. The timestamp's resolution
87 depends on available clock, and so it can be much worse than a microsecond 99 depends on available clock, and so it can be much worse than a microsecond
88 (if the implementation uses jiffies, for example). 100 (if the implementation uses jiffies, for example).
101
89- Event Type. This type refers to the format of the event, not URB type. 102- Event Type. This type refers to the format of the event, not URB type.
90 Available types are: S - submission, C - callback, E - submission error. 103 Available types are: S - submission, C - callback, E - submission error.
91- "Pipe". The pipe concept is deprecated. This is a composite word, used to 104
92 be derived from information in pipes. It consists of three fields, separated 105- "Address" word (formerly a "pipe"). It consists of four fields, separated by
93 by colons: URB type and direction, Device address, Endpoint number. 106 colons: URB type and direction, Bus number, Device address, Endpoint number.
94 Type and direction are encoded with two bytes in the following manner: 107 Type and direction are encoded with two bytes in the following manner:
95 Ci Co Control input and output 108 Ci Co Control input and output
96 Zi Zo Isochronous input and output 109 Zi Zo Isochronous input and output
97 Ii Io Interrupt input and output 110 Ii Io Interrupt input and output
98 Bi Bo Bulk input and output 111 Bi Bo Bulk input and output
99 Device address and Endpoint number are 3-digit and 2-digit (respectively) 112 Bus number, Device address, and Endpoint are decimal numbers, but they may
100 decimal numbers, with leading zeroes. 113 have leading zeros, for the sake of human readers.
101- URB Status. In most cases, this field contains a number, sometimes negative, 114
102 which represents a "status" field of the URB. This field makes no sense for 115- URB Status word. This is either a letter, or several numbers separated
103 submissions, but is present anyway to help scripts with parsing. When an 116 by colons: URB status, interval, start frame, and error count. Unlike the
104 error occurs, the field contains the error code. In case of a submission of 117 "address" word, all fields save the status are optional. Interval is printed
105 a Control packet, this field contains a Setup Tag instead of an error code. 118 only for interrupt and isochronous URBs. Start frame is printed only for
106 It is easy to tell whether the Setup Tag is present because it is never a 119 isochronous URBs. Error count is printed only for isochronous callback
107 number. Thus if scripts find a number in this field, they proceed to read 120 events.
108 Data Length. If they find something else, like a letter, they read the setup 121
109 packet before reading the Data Length. 122 The status field is a decimal number, sometimes negative, which represents
123 a "status" field of the URB. This field makes no sense for submissions, but
124 is present anyway to help scripts with parsing. When an error occurs, the
125 field contains the error code.
126
127 In case of a submission of a Control packet, this field contains a Setup Tag
128 instead of an group of numbers. It is easy to tell whether the Setup Tag is
129 present because it is never a number. Thus if scripts find a set of numbers
130 in this word, they proceed to read Data Length (except for isochronous URBs).
131 If they find something else, like a letter, they read the setup packet before
132 reading the Data Length or isochronous descriptors.
133
110- Setup packet, if present, consists of 5 words: one of each for bmRequestType, 134- Setup packet, if present, consists of 5 words: one of each for bmRequestType,
111 bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. 135 bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
112 These words are safe to decode if Setup Tag was 's'. Otherwise, the setup 136 These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
113 packet was present, but not captured, and the fields contain filler. 137 packet was present, but not captured, and the fields contain filler.
138
139- Number of isochronous frame descriptors and descriptors themselves.
140 If an Isochronous transfer event has a set of descriptors, a total number
141 of them in an URB is printed first, then a word per descriptor, up to a
142 total of 5. The word consists of 3 colon-separated decimal numbers for
143 status, offset, and length respectively. For submissions, initial length
144 is reported. For callbacks, actual length is reported.
145
114- Data Length. For submissions, this is the requested length. For callbacks, 146- Data Length. For submissions, this is the requested length. For callbacks,
115 this is the actual length. 147 this is the actual length.
148
116- Data tag. The usbmon may not always capture data, even if length is nonzero. 149- Data tag. The usbmon may not always capture data, even if length is nonzero.
117 The data words are present only if this tag is '='. 150 The data words are present only if this tag is '='.
151
118- Data words follow, in big endian hexadecimal format. Notice that they are 152- Data words follow, in big endian hexadecimal format. Notice that they are
119 not machine words, but really just a byte stream split into words to make 153 not machine words, but really just a byte stream split into words to make
120 it easier to read. Thus, the last word may contain from one to four bytes. 154 it easier to read. Thus, the last word may contain from one to four bytes.
@@ -153,20 +187,18 @@ class ParsedLine {
153 } 187 }
154} 188}
155 189
156This format may be changed in the future.
157
158Examples: 190Examples:
159 191
160An input control transfer to get a port status. 192An input control transfer to get a port status.
161 193
162d5ea89a0 3575914555 S Ci:001:00 s a3 00 0000 0003 0004 4 < 194d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
163d5ea89a0 3575914560 C Ci:001:00 0 4 = 01050000 195d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
164 196
165An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper 197An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper
166to a storage device at address 5: 198to a storage device at address 5:
167 199
168dd65f0e8 4128379752 S Bo:005:02 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 200dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000
169dd65f0e8 4128379808 C Bo:005:02 0 31 > 201dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
170 202
171* Raw binary format and API 203* Raw binary format and API
172 204