X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=Documentation%2Fusb%2Fusbmon.txt;h=e65ec828d7aa226f1fb8365c48afadb225dae79e;hb=97bf2856c6014879bd04983a3e9dfcdac1e7fe85;hp=2f8431f92b77fe7f762a75386f20ca8a92fbf0ca;hpb=4b659086703c3cfdabfc916b517590ad55d1ddfa;p=linux-2.6.git

diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt
index 2f8431f92..e65ec828d 100644
--- a/Documentation/usb/usbmon.txt
+++ b/Documentation/usb/usbmon.txt
@@ -29,14 +29,13 @@ if usbmon is built into the kernel.
 
 # mount -t debugfs none_debugs /sys/kernel/debug
 # modprobe usbmon
+#
 
 Verify that bus sockets are present.
 
-[root@lembas zaitcev]# ls /sys/kernel/debug/usbmon
+# ls /sys/kernel/debug/usbmon
 1s  1t  2s  2t  3s  3t  4s  4t
-[root@lembas zaitcev]#
-
-# ls /sys/kernel
+#
 
 2. Find which bus connects to the desired device
 
@@ -76,7 +75,7 @@ that the file size is not excessive for your favourite editor.
 
 * Raw text data format
 
-The '0t' type data consists of a stream of events, such as URB submission,
+The '1t' type data consists of a stream of events, such as URB submission,
 URB callback, submission error. Every event is a text line, which consists
 of whitespace separated words. The number of position of words may depend
 on the event type, but there is a set of words, common for all types.
@@ -97,13 +96,25 @@ Here is the list of words, from left to right:
     Zi Zo   Isochronous input and output
     Ii Io   Interrupt input and output
     Bi Bo   Bulk input and output
-  Device address and Endpoint number are decimal numbers with leading zeroes
-  or 3 and 2 positions, correspondingly.
-- URB Status. This field makes no sense for submissions, but is present
-  to help scripts with parsing. In error case, it contains the error code.
-- Data Length. This is the actual length in the URB.
+  Device address and Endpoint number are 3-digit and 2-digit (respectively)
+  decimal numbers, with leading zeroes.
+- URB Status. In most cases, this field contains a number, sometimes negative,
+  which represents a "status" field of the URB. This field makes no sense for
+  submissions, but is present anyway to help scripts with parsing. When an
+  error occurs, the field contains the error code. In case of a submission of
+  a Control packet, this field contains a Setup Tag instead of an error code.
+  It is easy to tell whether the Setup Tag is present because it is never a
+  number. Thus if scripts find a number in this field, they proceed to read
+  Data Length. If they find something else, like a letter, they read the setup
+  packet before reading the Data Length.
+- Setup packet, if present, consists of 5 words: one of each for bmRequestType,
+  bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
+  These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
+  packet was present, but not captured, and the fields contain filler.
+- Data Length. For submissions, this is the requested length. For callbacks,
+  this is the actual length.
 - Data tag. The usbmon may not always capture data, even if length is nonzero.
-  Only if tag is '=', the data words are present.
+  The data words are present only if this tag is '='.
 - Data words follow, in big endian hexadecimal format. Notice that they are
   not machine words, but really just a byte stream split into words to make
   it easier to read. Thus, the last word may contain from one to four bytes.
@@ -125,25 +136,31 @@ class ParsedLine {
 			String data_str = st.nextToken();
 			int len = data_str.length() / 2;
 			int i;
+			int b;	// byte is signed, apparently?! XXX
 			for (i = 0; i < len; i++) {
-				data[data_len] = Byte.parseByte(
-				    data_str.substring(i*2, i*2 + 2),
-				    16);
+				// data[data_len] = Byte.parseByte(
+				//     data_str.substring(i*2, i*2 + 2),
+				//     16);
+				b = Integer.parseInt(
+				     data_str.substring(i*2, i*2 + 2),
+				     16);
+				if (b >= 128)
+					b *= -1;
+				data[data_len] = (byte) b;
 				data_len++;
 			}
 		}
 	}
 }
 
-This format is obviously deficient. For example, the setup packet for control
-transfers is not delivered. This will change in the future.
+This format may be changed in the future.
 
 Examples:
 
-An input control transfer to get a port status:
+An input control transfer to get a port status.
 
-d74ff9a0 2640288196 S Ci:001:00 -115 4 <
-d74ff9a0 2640288202 C Ci:001:00 0 4 = 01010100
+d5ea89a0 3575914555 S Ci:001:00 s a3 00 0000 0003 0004 4 <
+d5ea89a0 3575914560 C Ci:001:00 0 4 = 01050000
 
 An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper
 to a storage device at address 5: