^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) usbmon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) The name "usbmon" in lowercase refers to a facility in kernel which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) used to collect traces of I/O on the USB bus. This function is analogous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) to a packet socket used by network monitoring tools such as tcpdump(1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) or Ethereal. Similarly, it is expected that a tool such as usbdump or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) USBMon (with uppercase letters) is used to examine raw traces produced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) by usbmon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) The usbmon reports requests made by peripheral-specific drivers to Host
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) usbmon may not correspond to bus transactions precisely. This is the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) situation as with tcpdump.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) Two APIs are currently implemented: "text" and "binary". The binary API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) is available through a character device in /dev namespace and is an ABI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) The text API is deprecated since 2.6.35, but available for convenience.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) How to use usbmon to collect raw text traces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) Unlike the packet socket, usbmon has an interface which provides traces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) in a text format. This is used for two purposes. First, it serves as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) common trace exchange format for tools while more sophisticated formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) are finalized. Second, humans can read it in case tools are not available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) To collect a raw text trace, execute following steps.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) 1. Prepare
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Mount debugfs (it has to be enabled in your kernel configuration), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) load the usbmon module (if built as module). The second step is skipped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) if usbmon is built into the kernel::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) # mount -t debugfs none_debugs /sys/kernel/debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) # modprobe usbmon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) #
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) Verify that bus sockets are present:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) # ls /sys/kernel/debug/usb/usbmon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) #
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Now you can choose to either use the socket '0u' (to capture packets on all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) buses), and skip to step #3, or find the bus used by your device with step #2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) This allows to filter away annoying devices that talk continuously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) 2. Find which bus connects to the desired device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) ------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) to the device. Usually you do it by looking for the vendor string. If you have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) many similar devices, unplug one and compare the two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) /sys/kernel/debug/usb/devices outputs. The T-line will have a bus number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) P: Vendor=0557 ProdID=2004 Rev= 1.00
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) S: Manufacturer=ATEN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) S: Product=UC100KM V2.00
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) "Bus=03" means it's bus 3. Alternatively, you can look at the output from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) "lsusb" and get the bus number from the appropriate line. Example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) 3. Start 'cat'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) to listen on a single bus, otherwise, to listen on all buses, type::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) This process will read until it is killed. Naturally, the output can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) redirected to a desirable location. This is preferred, because it is going
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) to be quite long.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) 4. Perform the desired operation on the USB bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) -----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) This is where you do something that creates the traffic: plug in a flash key,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) copy files, control a webcam, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) 5. Kill cat
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Usually it's done with a keyboard interrupt (Control-C).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) At this point the output file (/tmp/1.mon.out in this example) can be saved,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) sent by e-mail, or inspected with a text editor. In the last case make sure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) that the file size is not excessive for your favourite editor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) Raw text data format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Two formats are supported currently: the original, or '1t' format, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) format adds a few fields, such as ISO frame descriptors, interval, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) It produces slightly longer lines, but otherwise is a perfect superset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) of '1t' format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) If it is desired to recognize one from the other in a program, look at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) "address" word (see below), where '1u' format adds a bus number. If 2 colons
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) are present, it's the '1t' format, otherwise '1u'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Any text format data consists of a stream of events, such as URB submission,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) URB callback, submission error. Every event is a text line, which consists
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) of whitespace separated words. The number or position of words may depend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) on the event type, but there is a set of words, common for all types.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) Here is the list of words, from left to right:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) - URB Tag. This is used to identify URBs, and is normally an in-kernel address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) of the URB structure in hexadecimal, but can be a sequence number or any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) other unique string, within reason.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - Timestamp in microseconds, a decimal number. The timestamp's resolution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) depends on available clock, and so it can be much worse than a microsecond
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) (if the implementation uses jiffies, for example).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) - Event Type. This type refers to the format of the event, not URB type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) Available types are: S - submission, C - callback, E - submission error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) - "Address" word (formerly a "pipe"). It consists of four fields, separated by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) colons: URB type and direction, Bus number, Device address, Endpoint number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) Type and direction are encoded with two bytes in the following manner:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) == == =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) Ci Co Control input and output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Zi Zo Isochronous input and output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Ii Io Interrupt input and output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) Bi Bo Bulk input and output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) == == =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) Bus number, Device address, and Endpoint are decimal numbers, but they may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) have leading zeros, for the sake of human readers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) - URB Status word. This is either a letter, or several numbers separated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) by colons: URB status, interval, start frame, and error count. Unlike the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) "address" word, all fields save the status are optional. Interval is printed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) only for interrupt and isochronous URBs. Start frame is printed only for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) isochronous URBs. Error count is printed only for isochronous callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) The status field is a decimal number, sometimes negative, which represents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) a "status" field of the URB. This field makes no sense for submissions, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) is present anyway to help scripts with parsing. When an error occurs, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) field contains the error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) In case of a submission of a Control packet, this field contains a Setup Tag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) instead of an group of numbers. It is easy to tell whether the Setup Tag is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) present because it is never a number. Thus if scripts find a set of numbers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) in this word, they proceed to read Data Length (except for isochronous URBs).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) If they find something else, like a letter, they read the setup packet before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) reading the Data Length or isochronous descriptors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) - Setup packet, if present, consists of 5 words: one of each for bmRequestType,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) packet was present, but not captured, and the fields contain filler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) - Number of isochronous frame descriptors and descriptors themselves.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) If an Isochronous transfer event has a set of descriptors, a total number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) of them in an URB is printed first, then a word per descriptor, up to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) total of 5. The word consists of 3 colon-separated decimal numbers for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) status, offset, and length respectively. For submissions, initial length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) is reported. For callbacks, actual length is reported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) - Data Length. For submissions, this is the requested length. For callbacks,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) this is the actual length.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) - Data tag. The usbmon may not always capture data, even if length is nonzero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) The data words are present only if this tag is '='.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) - Data words follow, in big endian hexadecimal format. Notice that they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) not machine words, but really just a byte stream split into words to make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) it easier to read. Thus, the last word may contain from one to four bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) The length of collected data is limited and can be less than the data length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) reported in the Data Length word. In the case of an Isochronous input (Zi)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) completion where the received data is sparse in the buffer, the length of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) the collected data can be greater than the Data Length value (because Data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Length counts only the bytes that were received whereas the Data words
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) contain the entire transfer buffer).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Examples:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) An input control transfer to get a port status::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Bulk wrapper to a storage device at address 5::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) Raw binary format and API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) The overall architecture of the API is about the same as the one above,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) only the events are delivered in binary format. Each event is sent in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) the following structure (its name is made up, so that we can refer to it)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) struct usbmon_packet {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) u64 id; /* 0: URB ID - from submission to callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) unsigned char type; /* 8: Same as text; extensible. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) unsigned char epnum; /* Endpoint number and transfer direction */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) unsigned char devnum; /* Device address */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) u16 busnum; /* 12: Bus number */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) char flag_setup; /* 14: Same as text */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) char flag_data; /* 15: Same as text; Binary zero is OK. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) s64 ts_sec; /* 16: gettimeofday */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) s32 ts_usec; /* 24: gettimeofday */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) int status; /* 28: */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) unsigned int length; /* 32: Length of data (submitted or actual) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) unsigned int len_cap; /* 36: Delivered length */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) union { /* 40: */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) unsigned char setup[SETUP_LEN]; /* Only for Control S-type */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) struct iso_rec { /* Only for ISO */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) int error_count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) int numdesc;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) } iso;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) } s;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) int interval; /* 48: Only for Interrupt and ISO */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) int start_frame; /* 52: For ISO */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) unsigned int ndesc; /* 60: Actual number of ISO descriptors */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) }; /* 64 total length */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) These events can be received from a character device by reading with read(2),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) with an ioctl(2), or by accessing the buffer with mmap. However, read(2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) only returns first 48 bytes for compatibility reasons.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) The character device is usually called /dev/usbmonN, where N is the USB bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) number. Number zero (/dev/usbmon0) is special and means "all buses".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) Note that specific naming policy is set by your Linux distribution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) If you create /dev/usbmon0 by hand, make sure that it is owned by root
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) and has mode 0600. Otherwise, unprivileged users will be able to snoop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) keyboard traffic.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) The following ioctl calls are available, with MON_IOC_MAGIC 0x92:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) This call returns the length of data in the next event. Note that majority of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) events contain no data, so if this call returns zero, it does not mean that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) no events are available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) The argument is a pointer to the following structure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) struct mon_bin_stats {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) u32 queued;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) u32 dropped;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) The member "queued" refers to the number of events currently queued in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) buffer (and not to the number of events processed since the last reset).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) The member "dropped" is the number of events lost since the last call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) to MON_IOCG_STATS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) This call sets the buffer size. The argument is the size in bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) The size may be rounded down to the next chunk (or page). If the requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) size is out of [unspecified] bounds for this kernel, the call fails with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) -EINVAL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) This call returns the current size of the buffer in bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) MON_IOCX_GETX, defined as _IOW(MON_IOC_MAGIC, 10, struct mon_get_arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) These calls wait for events to arrive if none were in the kernel buffer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) then return the first event. The argument is a pointer to the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) structure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) struct mon_get_arg {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) struct usbmon_packet *hdr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) void *data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) size_t alloc; /* Length of data (can be zero) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) Before the call, hdr, data, and alloc should be filled. Upon return, the area
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) pointed by hdr contains the next event structure, and the data buffer contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) the data, if any. The event is removed from the kernel buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) This ioctl is primarily used when the application accesses the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) with mmap(2). Its argument is a pointer to the following structure::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) struct mon_mfetch_arg {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) uint32_t *offvec; /* Vector of events fetched */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) uint32_t nfetch; /* Number of events to fetch (out: fetched) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) uint32_t nflush; /* Number of events to flush */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) The ioctl operates in 3 stages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) First, it removes and discards up to nflush events from the kernel buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) The actual number of events discarded is returned in nflush.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) Second, it waits for an event to be present in the buffer, unless the pseudo-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) device is open with O_NONBLOCK.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) Third, it extracts up to nfetch offsets into the mmap buffer, and stores
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) them into the offvec. The actual number of event offsets is stored into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) the nfetch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) This call removes a number of events from the kernel buffer. Its argument
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) is the number of events to remove. If the buffer contains fewer events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) than requested, all events present are removed, and no error is reported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) This works when no events are available too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) FIONBIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) The ioctl FIONBIO may be implemented in the future, if there's a need.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) In addition to ioctl(2) and read(2), the special file of binary API can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) be polled with select(2) and poll(2). But lseek(2) does not work.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) * Memory-mapped access of the kernel buffer for the binary API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) The basic idea is simple:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) To prepare, map the buffer by getting the current size, then using mmap(2).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) Then, execute a loop similar to the one written in pseudo-code below::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) struct mon_mfetch_arg fetch;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) struct usbmon_packet *hdr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) int nflush = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) for (;;) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) fetch.offvec = vec; // Has N 32-bit words
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) fetch.nfetch = N; // Or less than N
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) fetch.nflush = nflush;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) nflush = fetch.nfetch; // This many packets to flush when done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) for (i = 0; i < nflush; i++) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) hdr = (struct ubsmon_packet *) &mmap_area[vec[i]];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) if (hdr->type == '@') // Filler packet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) continue;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) caddr_t data = &mmap_area[vec[i]] + 64;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) process_packet(hdr, data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) Thus, the main idea is to execute only one ioctl per N events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) Although the buffer is circular, the returned headers and data do not cross
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) the end of the buffer, so the above pseudo-code does not need any gathering.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags