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