root/hodgestar/PythonCode/PicturePocketRevEng/usbmon.html

Revision 283, 39.9 kB (checked in by simon, 4 years ago)

Move Picture Pocket reverse engineering attempts into svn.

Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html><head>
3<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
4<meta name="description" content="Linux Kernel Documentation">
5<meta name="keywords" content="linux,kernel,docs,howto,readme,documentation,notes,driver,tips,guides">
6<meta name="copyright" content="Copyright (c) 2007 Mauriat Miranda">
7<meta name="author" content="Mauriat Miranda">
8<link rel="stylesheet" href="/css/kdoc.css">
9<title>Linux Kernel Documentation :: usb : usbmon.txt</title>
10<script type="text/javascript">
11var swap=0;
12function hA(){
13if(swap) return;
14var d=document.getElementsByTagName('span');
15for(i=0;i<d.length;i++)
16if(d[i].className=='l')
17d[i].innerHTML="";
18swap=!swap;
19document.getElementById("corner").style.display="none";
20}
21</script>
22</head>
23<body><div id="kbody">
24<div id="tagline"><span class="aboutkernel"><a href="http://www.mjmwired.net/resources/mjm-kernel-docs.html">About Kernel Documentation</a></span><span class="bluelink"> <a href="http://www.kernel.org/" target="_blank">Linux Kernel</a> <a href="http://www.mjmwired.net/contact/">Contact</a> <a href="http://www.mjmwired.net/resources/">Linux Resources</a> <a href="http://www.mjmwired.net/linux/">Linux Blog</a></span></div>
25<script type="text/javascript"><!--
26google_ad_client = "pub-5258443501063629";
27google_ad_width = 468;
28google_ad_height = 15;
29google_ad_format = "468x15_0ads_al_s";
30google_ad_channel = "5452528277+6281983790";
31google_color_border = "FFFFFF";
32google_color_bg = "FFFFFF";
33google_color_link = "0000FF";
34google_color_url = "666666";
35google_color_text = "000000";
36//--></script>
37<script type="text/javascript"
38  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
39</script>
40
41<h2><a href="/kernel/Documentation">Documentation</a> / <a href="/kernel/Documentation/usb">usb</a> / <a href="/kernel/Documentation/usb/usbmon.txt">usbmon.txt</a></h2>
42<script type="text/javascript"><!--
43google_ad_client = "pub-5258443501063629";
44google_ad_width = 300;
45google_ad_height = 250;
46google_ad_format = "300x250_as";
47google_ad_type = "text_image";
48google_ad_channel = "5452528277+1305615863";
49google_color_border = "FFFFFF";
50google_color_bg = "FFFFFF";
51google_color_link = "0000FF";
52google_color_text = "000000";
53google_color_url = "CCCCCC";
54//--></script>
55<script type="text/javascript"
56  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
57</script>
58<script type="text/javascript"><!--
59google_ad_client = "pub-5258443501063629";
60google_ad_width = 300;
61google_ad_height = 250;
62google_ad_format = "300x250_as";
63google_cpa_choice = "CAEQABAAEAAQABAAEAAQABAAEAAQABAAEAAQABAAEAAQABAAEAAQABoIE8q6AK-185ko97vOwwEor-C55gEo573OwwEoq73OwwEos7zOwwEo77zOwwEo_7rOwwEo377OwwEoo77OwwEou7vOwwEogf-9pQEoxdrhtwEo2sC-5gEoqO3stAEo_frLxQEoqbiNvgEo4pm5ogIozarxqgEo4qPPwgI";
64google_color_border = "FFFFFF";
65google_color_bg = "FFFFFF";
66google_color_link = "0000FF";
67google_color_text = "000000";
68google_color_url = "666666";
69//-->
70</script>
71<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
72</script>
73
74
75<p><small>Based on kernel version <tt><a href="http://www.kernel.org/pub/linux/kernel/v2.6/ChangeLog-2.6.23" target="_blank">2.6.23</a></tt>. Page generated on <tt>2007-10-11 12:02 EST</tt>.</small></p>
76<pre>
77<span class="l"><a name="1" href="#1">1</a>     </span>* Introduction
78<span class="l"><a name="2" href="#2">2</a>     </span>
79<span class="l"><a name="3" href="#3">3</a>     </span>The name "usbmon" in lowercase refers to a facility in kernel which is
80<span class="l"><a name="4" href="#4">4</a>     </span>used to collect traces of I/O on the USB bus. This function is analogous
81<span class="l"><a name="5" href="#5">5</a>     </span>to a packet socket used by network monitoring tools such as tcpdump(1)
82<span class="l"><a name="6" href="#6">6</a>     </span>or Ethereal. Similarly, it is expected that a tool such as usbdump or
83<span class="l"><a name="7" href="#7">7</a>     </span>USBMon (with uppercase letters) is used to examine raw traces produced
84<span class="l"><a name="8" href="#8">8</a>     </span>by usbmon.
85<span class="l"><a name="9" href="#9">9</a>     </span>
86<span class="l"><a name="10" href="#10">10</a>  </span>The usbmon reports requests made by peripheral-specific drivers to Host
87<span class="l"><a name="11" href="#11">11</a>  </span>Controller Drivers (HCD). So, if HCD is buggy, the traces reported by
88<span class="l"><a name="12" href="#12">12</a>  </span>usbmon may not correspond to bus transactions precisely. This is the same
89<span class="l"><a name="13" href="#13">13</a>  </span>situation as with tcpdump.
90<span class="l"><a name="14" href="#14">14</a>  </span>
91<span class="l"><a name="15" href="#15">15</a>  </span>* How to use usbmon to collect raw text traces
92<span class="l"><a name="16" href="#16">16</a>  </span>
93<span class="l"><a name="17" href="#17">17</a>  </span>Unlike the packet socket, usbmon has an interface which provides traces
94<span class="l"><a name="18" href="#18">18</a>  </span>in a text format. This is used for two purposes. First, it serves as a
95<span class="l"><a name="19" href="#19">19</a>  </span>common trace exchange format for tools while more sophisticated formats
96<span class="l"><a name="20" href="#20">20</a>  </span>are finalized. Second, humans can read it in case tools are not available.
97<span class="l"><a name="21" href="#21">21</a>  </span>
98<span class="l"><a name="22" href="#22">22</a>  </span>To collect a raw text trace, execute following steps.
99<span class="l"><a name="23" href="#23">23</a>  </span>
100<span class="l"><a name="24" href="#24">24</a>  </span>1. Prepare
101<span class="l"><a name="25" href="#25">25</a>  </span>
102<span class="l"><a name="26" href="#26">26</a>  </span>Mount debugfs (it has to be enabled in your kernel configuration), and
103<span class="l"><a name="27" href="#27">27</a>  </span>load the usbmon module (if built as module). The second step is skipped
104<span class="l"><a name="28" href="#28">28</a>  </span>if usbmon is built into the kernel.
105<span class="l"><a name="29" href="#29">29</a>  </span>
106<span class="l"><a name="30" href="#30">30</a>  </span># mount -t debugfs none_debugs /sys/kernel/debug
107<span class="l"><a name="31" href="#31">31</a>  </span># modprobe usbmon
108<span class="l"><a name="32" href="#32">32</a>  </span>#
109<span class="l"><a name="33" href="#33">33</a>  </span>
110<span class="l"><a name="34" href="#34">34</a>  </span>Verify that bus sockets are present.
111<span class="l"><a name="35" href="#35">35</a>  </span>
112<span class="l"><a name="36" href="#36">36</a>  </span># ls /sys/kernel/debug/usbmon
113<span class="l"><a name="37" href="#37">37</a>  </span>1s  1t  1u  2s  2t  2u  3s  3t  3u  4s  4t  4u
114<span class="l"><a name="38" href="#38">38</a>  </span>#
115<span class="l"><a name="39" href="#39">39</a>  </span>
116<span class="l"><a name="40" href="#40">40</a>  </span>2. Find which bus connects to the desired device
117<span class="l"><a name="41" href="#41">41</a>  </span>
118<span class="l"><a name="42" href="#42">42</a>  </span>Run "cat /proc/bus/usb/devices", and find the T-line which corresponds to
119<span class="l"><a name="43" href="#43">43</a>  </span>the device. Usually you do it by looking for the vendor string. If you have
120<span class="l"><a name="44" href="#44">44</a>  </span>many similar devices, unplug one and compare two /proc/bus/usb/devices outputs.
121<span class="l"><a name="45" href="#45">45</a>  </span>The T-line will have a bus number. Example:
122<span class="l"><a name="46" href="#46">46</a>  </span>
123<span class="l"><a name="47" href="#47">47</a>  </span>T:  Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=12  MxCh= 0
124<span class="l"><a name="48" href="#48">48</a>  </span>D:  Ver= 1.10 Cls=00(&gt;ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
125<span class="l"><a name="49" href="#49">49</a>  </span>P:  Vendor=0557 ProdID=2004 Rev= 1.00
126<span class="l"><a name="50" href="#50">50</a>  </span>S:  Manufacturer=ATEN
127<span class="l"><a name="51" href="#51">51</a>  </span>S:  Product=UC100KM V2.00
128<span class="l"><a name="52" href="#52">52</a>  </span>
129<span class="l"><a name="53" href="#53">53</a>  </span>Bus=03 means it's bus 3.
130<span class="l"><a name="54" href="#54">54</a>  </span>
131<span class="l"><a name="55" href="#55">55</a>  </span>3. Start 'cat'
132<span class="l"><a name="56" href="#56">56</a>  </span>
133<span class="l"><a name="57" href="#57">57</a>  </span># cat /sys/kernel/debug/usbmon/3u &gt; /tmp/1.mon.out
134<span class="l"><a name="58" href="#58">58</a>  </span>
135<span class="l"><a name="59" href="#59">59</a>  </span>This process will be reading until killed. Naturally, the output can be
136<span class="l"><a name="60" href="#60">60</a>  </span>redirected to a desirable location. This is preferred, because it is going
137<span class="l"><a name="61" href="#61">61</a>  </span>to be quite long.
138<span class="l"><a name="62" href="#62">62</a>  </span>
139<span class="l"><a name="63" href="#63">63</a>  </span>4. Perform the desired operation on the USB bus
140<span class="l"><a name="64" href="#64">64</a>  </span>
141<span class="l"><a name="65" href="#65">65</a>  </span>This is where you do something that creates the traffic: plug in a flash key,
142<span class="l"><a name="66" href="#66">66</a>  </span>copy files, control a webcam, etc.
143<span class="l"><a name="67" href="#67">67</a>  </span>
144<span class="l"><a name="68" href="#68">68</a>  </span>5. Kill cat
145<span class="l"><a name="69" href="#69">69</a>  </span>
146<span class="l"><a name="70" href="#70">70</a>  </span>Usually it's done with a keyboard interrupt (Control-C).
147<span class="l"><a name="71" href="#71">71</a>  </span>
148<span class="l"><a name="72" href="#72">72</a>  </span>At this point the output file (/tmp/1.mon.out in this example) can be saved,
149<span class="l"><a name="73" href="#73">73</a>  </span>sent by e-mail, or inspected with a text editor. In the last case make sure
150<span class="l"><a name="74" href="#74">74</a>  </span>that the file size is not excessive for your favourite editor.
151<span class="l"><a name="75" href="#75">75</a>  </span>
152<span class="l"><a name="76" href="#76">76</a>  </span>* Raw text data format
153<span class="l"><a name="77" href="#77">77</a>  </span>
154<span class="l"><a name="78" href="#78">78</a>  </span>Two formats are supported currently: the original, or '1t' format, and
155<span class="l"><a name="79" href="#79">79</a>  </span>the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
156<span class="l"><a name="80" href="#80">80</a>  </span>format adds a few fields, such as ISO frame descriptors, interval, etc.
157<span class="l"><a name="81" href="#81">81</a>  </span>It produces slightly longer lines, but otherwise is a perfect superset
158<span class="l"><a name="82" href="#82">82</a>  </span>of '1t' format.
159<span class="l"><a name="83" href="#83">83</a>  </span>
160<span class="l"><a name="84" href="#84">84</a>  </span>If it is desired to recognize one from the other in a program, look at the
161<span class="l"><a name="85" href="#85">85</a>  </span>"address" word (see below), where '1u' format adds a bus number. If 2 colons
162<span class="l"><a name="86" href="#86">86</a>  </span>are present, it's the '1t' format, otherwise '1u'.
163<span class="l"><a name="87" href="#87">87</a>  </span>
164<span class="l"><a name="88" href="#88">88</a>  </span>Any text format data consists of a stream of events, such as URB submission,
165<span class="l"><a name="89" href="#89">89</a>  </span>URB callback, submission error. Every event is a text line, which consists
166<span class="l"><a name="90" href="#90">90</a>  </span>of whitespace separated words. The number or position of words may depend
167<span class="l"><a name="91" href="#91">91</a>  </span>on the event type, but there is a set of words, common for all types.
168<span class="l"><a name="92" href="#92">92</a>  </span>
169<span class="l"><a name="93" href="#93">93</a>  </span>Here is the list of words, from left to right:
170<span class="l"><a name="94" href="#94">94</a>  </span>
171<span class="l"><a name="95" href="#95">95</a>  </span>- URB Tag. This is used to identify URBs is normally a kernel mode address
172<span class="l"><a name="96" href="#96">96</a>  </span> of the URB structure in hexadecimal.
173<span class="l"><a name="97" href="#97">97</a>  </span>
174<span class="l"><a name="98" href="#98">98</a>  </span>- Timestamp in microseconds, a decimal number. The timestamp's resolution
175<span class="l"><a name="99" href="#99">99</a>  </span>  depends on available clock, and so it can be much worse than a microsecond
176<span class="l"><a name="100" href="#100">100</a>       </span>  (if the implementation uses jiffies, for example).
177<span class="l"><a name="101" href="#101">101</a>       </span>
178<span class="l"><a name="102" href="#102">102</a>       </span>- Event Type. This type refers to the format of the event, not URB type.
179<span class="l"><a name="103" href="#103">103</a>       </span>  Available types are: S - submission, C - callback, E - submission error.
180<span class="l"><a name="104" href="#104">104</a>       </span>
181<span class="l"><a name="105" href="#105">105</a>       </span>- "Address" word (formerly a "pipe"). It consists of four fields, separated by
182<span class="l"><a name="106" href="#106">106</a>       </span>  colons: URB type and direction, Bus number, Device address, Endpoint number.
183<span class="l"><a name="107" href="#107">107</a>       </span>  Type and direction are encoded with two bytes in the following manner:
184<span class="l"><a name="108" href="#108">108</a>       </span>    Ci Co   Control input and output
185<span class="l"><a name="109" href="#109">109</a>       </span>    Zi Zo   Isochronous input and output
186<span class="l"><a name="110" href="#110">110</a>       </span>    Ii Io   Interrupt input and output
187<span class="l"><a name="111" href="#111">111</a>       </span>    Bi Bo   Bulk input and output
188<span class="l"><a name="112" href="#112">112</a>       </span>  Bus number, Device address, and Endpoint are decimal numbers, but they may
189<span class="l"><a name="113" href="#113">113</a>       </span>  have leading zeros, for the sake of human readers.
190<span class="l"><a name="114" href="#114">114</a>       </span>
191<span class="l"><a name="115" href="#115">115</a>       </span>- URB Status word. This is either a letter, or several numbers separated
192<span class="l"><a name="116" href="#116">116</a>       </span>  by colons: URB status, interval, start frame, and error count. Unlike the
193<span class="l"><a name="117" href="#117">117</a>       </span>  "address" word, all fields save the status are optional. Interval is printed
194<span class="l"><a name="118" href="#118">118</a>       </span>  only for interrupt and isochronous URBs. Start frame is printed only for
195<span class="l"><a name="119" href="#119">119</a>       </span>  isochronous URBs. Error count is printed only for isochronous callback
196<span class="l"><a name="120" href="#120">120</a>       </span>  events.
197<span class="l"><a name="121" href="#121">121</a>       </span>
198<span class="l"><a name="122" href="#122">122</a>       </span>  The status field is a decimal number, sometimes negative, which represents
199<span class="l"><a name="123" href="#123">123</a>       </span>  a "status" field of the URB. This field makes no sense for submissions, but
200<span class="l"><a name="124" href="#124">124</a>       </span>  is present anyway to help scripts with parsing. When an error occurs, the
201<span class="l"><a name="125" href="#125">125</a>       </span>  field contains the error code.
202<span class="l"><a name="126" href="#126">126</a>       </span>
203<span class="l"><a name="127" href="#127">127</a>       </span>  In case of a submission of a Control packet, this field contains a Setup Tag
204<span class="l"><a name="128" href="#128">128</a>       </span>  instead of an group of numbers. It is easy to tell whether the Setup Tag is
205<span class="l"><a name="129" href="#129">129</a>       </span>  present because it is never a number. Thus if scripts find a set of numbers
206<span class="l"><a name="130" href="#130">130</a>       </span>  in this word, they proceed to read Data Length (except for isochronous URBs).
207<span class="l"><a name="131" href="#131">131</a>       </span>  If they find something else, like a letter, they read the setup packet before
208<span class="l"><a name="132" href="#132">132</a>       </span>  reading the Data Length or isochronous descriptors.
209<span class="l"><a name="133" href="#133">133</a>       </span>
210<span class="l"><a name="134" href="#134">134</a>       </span>- Setup packet, if present, consists of 5 words: one of each for bmRequestType,
211<span class="l"><a name="135" href="#135">135</a>       </span>  bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
212<span class="l"><a name="136" href="#136">136</a>       </span>  These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
213<span class="l"><a name="137" href="#137">137</a>       </span>  packet was present, but not captured, and the fields contain filler.
214<span class="l"><a name="138" href="#138">138</a>       </span>
215<span class="l"><a name="139" href="#139">139</a>       </span>- Number of isochronous frame descriptors and descriptors themselves.
216<span class="l"><a name="140" href="#140">140</a>       </span>  If an Isochronous transfer event has a set of descriptors, a total number
217<span class="l"><a name="141" href="#141">141</a>       </span>  of them in an URB is printed first, then a word per descriptor, up to a
218<span class="l"><a name="142" href="#142">142</a>       </span>  total of 5. The word consists of 3 colon-separated decimal numbers for
219<span class="l"><a name="143" href="#143">143</a>       </span>  status, offset, and length respectively. For submissions, initial length
220<span class="l"><a name="144" href="#144">144</a>       </span>  is reported. For callbacks, actual length is reported.
221<span class="l"><a name="145" href="#145">145</a>       </span>
222<span class="l"><a name="146" href="#146">146</a>       </span>- Data Length. For submissions, this is the requested length. For callbacks,
223<span class="l"><a name="147" href="#147">147</a>       </span>  this is the actual length.
224<span class="l"><a name="148" href="#148">148</a>       </span>
225<span class="l"><a name="149" href="#149">149</a>       </span>- Data tag. The usbmon may not always capture data, even if length is nonzero.
226<span class="l"><a name="150" href="#150">150</a>       </span>  The data words are present only if this tag is '='.
227<span class="l"><a name="151" href="#151">151</a>       </span>
228<span class="l"><a name="152" href="#152">152</a>       </span>- Data words follow, in big endian hexadecimal format. Notice that they are
229<span class="l"><a name="153" href="#153">153</a>       </span>  not machine words, but really just a byte stream split into words to make
230<span class="l"><a name="154" href="#154">154</a>       </span>  it easier to read. Thus, the last word may contain from one to four bytes.
231<span class="l"><a name="155" href="#155">155</a>       </span>  The length of collected data is limited and can be less than the data length
232<span class="l"><a name="156" href="#156">156</a>       </span>  report in Data Length word.
233<span class="l"><a name="157" href="#157">157</a>       </span>
234<span class="l"><a name="158" href="#158">158</a>       </span>Here is an example of code to read the data stream in a well known programming
235<span class="l"><a name="159" href="#159">159</a>       </span>language:
236<span class="l"><a name="160" href="#160">160</a>       </span>
237<span class="l"><a name="161" href="#161">161</a>       </span>class ParsedLine {
238<span class="l"><a name="162" href="#162">162</a>       </span> int data_len;           /* Available length of data */
239<span class="l"><a name="163" href="#163">163</a>       </span> byte data[];
240<span class="l"><a name="164" href="#164">164</a>       </span>
241<span class="l"><a name="165" href="#165">165</a>       </span> void parseData(StringTokenizer st) {
242<span class="l"><a name="166" href="#166">166</a>       </span>         int availwords = st.countTokens();
243<span class="l"><a name="167" href="#167">167</a>       </span>         data = new byte[availwords * 4];
244<span class="l"><a name="168" href="#168">168</a>       </span>         data_len = 0;
245<span class="l"><a name="169" href="#169">169</a>       </span>         while (st.hasMoreTokens()) {
246<span class="l"><a name="170" href="#170">170</a>       </span>                 String data_str = st.nextToken();
247<span class="l"><a name="171" href="#171">171</a>       </span>                 int len = data_str.length() / 2;
248<span class="l"><a name="172" href="#172">172</a>       </span>                 int i;
249<span class="l"><a name="173" href="#173">173</a>       </span>                 int b;  // byte is signed, apparently?! XXX
250<span class="l"><a name="174" href="#174">174</a>       </span>                 for (i = 0; i &lt; len; i++) {
251<span class="l"><a name="175" href="#175">175</a>       </span>                         // data[data_len] = Byte.parseByte(
252<span class="l"><a name="176" href="#176">176</a>       </span>                         //     data_str.substring(i*2, i*2 + 2),
253<span class="l"><a name="177" href="#177">177</a>       </span>                         //     16);
254<span class="l"><a name="178" href="#178">178</a>       </span>                         b = Integer.parseInt(
255<span class="l"><a name="179" href="#179">179</a>       </span>                              data_str.substring(i*2, i*2 + 2),
256<span class="l"><a name="180" href="#180">180</a>       </span>                              16);
257<span class="l"><a name="181" href="#181">181</a>       </span>                         if (b &gt;= 128)
258<span class="l"><a name="182" href="#182">182</a>       </span>                                 b *= -1;
259<span class="l"><a name="183" href="#183">183</a>       </span>                         data[data_len] = (byte) b;
260<span class="l"><a name="184" href="#184">184</a>       </span>                         data_len++;
261<span class="l"><a name="185" href="#185">185</a>       </span>                 }
262<span class="l"><a name="186" href="#186">186</a>       </span>         }
263<span class="l"><a name="187" href="#187">187</a>       </span> }
264<span class="l"><a name="188" href="#188">188</a>       </span>}
265<span class="l"><a name="189" href="#189">189</a>       </span>
266<span class="l"><a name="190" href="#190">190</a>       </span>Examples:
267<span class="l"><a name="191" href="#191">191</a>       </span>
268<span class="l"><a name="192" href="#192">192</a>       </span>An input control transfer to get a port status.
269<span class="l"><a name="193" href="#193">193</a>       </span>
270<span class="l"><a name="194" href="#194">194</a>       </span>d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 &lt;
271<span class="l"><a name="195" href="#195">195</a>       </span>d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
272<span class="l"><a name="196" href="#196">196</a>       </span>
273<span class="l"><a name="197" href="#197">197</a>       </span>An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper
274<span class="l"><a name="198" href="#198">198</a>       </span>to a storage device at address 5:
275<span class="l"><a name="199" href="#199">199</a>       </span>
276<span class="l"><a name="200" href="#200">200</a>       </span>dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000
277<span class="l"><a name="201" href="#201">201</a>       </span>dd65f0e8 4128379808 C Bo:1:005:2 0 31 &gt;
278<span class="l"><a name="202" href="#202">202</a>       </span>
279<span class="l"><a name="203" href="#203">203</a>       </span>* Raw binary format and API
280<span class="l"><a name="204" href="#204">204</a>       </span>
281<span class="l"><a name="205" href="#205">205</a>       </span>The overall architecture of the API is about the same as the one above,
282<span class="l"><a name="206" href="#206">206</a>       </span>only the events are delivered in binary format. Each event is sent in
283<span class="l"><a name="207" href="#207">207</a>       </span>the following structure (its name is made up, so that we can refer to it):
284<span class="l"><a name="208" href="#208">208</a>       </span>
285<span class="l"><a name="209" href="#209">209</a>       </span>struct usbmon_packet {
286<span class="l"><a name="210" href="#210">210</a>       </span> u64 id;                 /*  0: URB ID - from submission to callback */
287<span class="l"><a name="211" href="#211">211</a>       </span> unsigned char type;     /*  8: Same as text; extensible. */
288<span class="l"><a name="212" href="#212">212</a>       </span> unsigned char xfer_type; /*    ISO (0), Intr, Control, Bulk (3) */
289<span class="l"><a name="213" href="#213">213</a>       </span> unsigned char epnum;    /*     Endpoint number and transfer direction */
290<span class="l"><a name="214" href="#214">214</a>       </span> unsigned char devnum;   /*     Device address */
291<span class="l"><a name="215" href="#215">215</a>       </span> u16 busnum;             /* 12: Bus number */
292<span class="l"><a name="216" href="#216">216</a>       </span> char flag_setup;        /* 14: Same as text */
293<span class="l"><a name="217" href="#217">217</a>       </span> char flag_data;         /* 15: Same as text; Binary zero is OK. */
294<span class="l"><a name="218" href="#218">218</a>       </span> s64 ts_sec;             /* 16: gettimeofday */
295<span class="l"><a name="219" href="#219">219</a>       </span> s32 ts_usec;            /* 24: gettimeofday */
296<span class="l"><a name="220" href="#220">220</a>       </span> int status;             /* 28: */
297<span class="l"><a name="221" href="#221">221</a>       </span> unsigned int length;    /* 32: Length of data (submitted or actual) */
298<span class="l"><a name="222" href="#222">222</a>       </span> unsigned int len_cap;   /* 36: Delivered length */
299<span class="l"><a name="223" href="#223">223</a>       </span> unsigned char setup[8]; /* 40: Only for Control 'S' */
300<span class="l"><a name="224" href="#224">224</a>       </span>};                               /* 48 bytes total */
301<span class="l"><a name="225" href="#225">225</a>       </span>
302<span class="l"><a name="226" href="#226">226</a>       </span>These events can be received from a character device by reading with read(2),
303<span class="l"><a name="227" href="#227">227</a>       </span>with an ioctl(2), or by accessing the buffer with mmap.
304<span class="l"><a name="228" href="#228">228</a>       </span>
305<span class="l"><a name="229" href="#229">229</a>       </span>The character device is usually called /dev/usbmonN, where N is the USB bus
306<span class="l"><a name="230" href="#230">230</a>       </span>number. Number zero (/dev/usbmon0) is special and means "all buses".
307<span class="l"><a name="231" href="#231">231</a>       </span>However, this feature is not implemented yet. Note that specific naming
308<span class="l"><a name="232" href="#232">232</a>       </span>policy is set by your Linux distribution.
309<span class="l"><a name="233" href="#233">233</a>       </span>
310<span class="l"><a name="234" href="#234">234</a>       </span>If you create /dev/usbmon0 by hand, make sure that it is owned by root
311<span class="l"><a name="235" href="#235">235</a>       </span>and has mode 0600. Otherwise, unpriviledged users will be able to snoop
312<span class="l"><a name="236" href="#236">236</a>       </span>keyboard traffic.
313<span class="l"><a name="237" href="#237">237</a>       </span>
314<span class="l"><a name="238" href="#238">238</a>       </span>The following ioctl calls are available, with MON_IOC_MAGIC 0x92:
315<span class="l"><a name="239" href="#239">239</a>       </span>
316<span class="l"><a name="240" href="#240">240</a>       </span> MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1)
317<span class="l"><a name="241" href="#241">241</a>       </span>
318<span class="l"><a name="242" href="#242">242</a>       </span>This call returns the length of data in the next event. Note that majority of
319<span class="l"><a name="243" href="#243">243</a>       </span>events contain no data, so if this call returns zero, it does not mean that
320<span class="l"><a name="244" href="#244">244</a>       </span>no events are available.
321<span class="l"><a name="245" href="#245">245</a>       </span>
322<span class="l"><a name="246" href="#246">246</a>       </span> MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
323<span class="l"><a name="247" href="#247">247</a>       </span>
324<span class="l"><a name="248" href="#248">248</a>       </span>The argument is a pointer to the following structure:
325<span class="l"><a name="249" href="#249">249</a>       </span>
326<span class="l"><a name="250" href="#250">250</a>       </span>struct mon_bin_stats {
327<span class="l"><a name="251" href="#251">251</a>       </span> u32 queued;
328<span class="l"><a name="252" href="#252">252</a>       </span> u32 dropped;
329<span class="l"><a name="253" href="#253">253</a>       </span>};
330<span class="l"><a name="254" href="#254">254</a>       </span>
331<span class="l"><a name="255" href="#255">255</a>       </span>The member "queued" refers to the number of events currently queued in the
332<span class="l"><a name="256" href="#256">256</a>       </span>buffer (and not to the number of events processed since the last reset).
333<span class="l"><a name="257" href="#257">257</a>       </span>
334<span class="l"><a name="258" href="#258">258</a>       </span>The member "dropped" is the number of events lost since the last call
335<span class="l"><a name="259" href="#259">259</a>       </span>to MON_IOCG_STATS.
336<span class="l"><a name="260" href="#260">260</a>       </span>
337<span class="l"><a name="261" href="#261">261</a>       </span> MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4)
338<span class="l"><a name="262" href="#262">262</a>       </span>
339<span class="l"><a name="263" href="#263">263</a>       </span>This call sets the buffer size. The argument is the size in bytes.
340<span class="l"><a name="264" href="#264">264</a>       </span>The size may be rounded down to the next chunk (or page). If the requested
341<span class="l"><a name="265" href="#265">265</a>       </span>size is out of [unspecified] bounds for this kernel, the call fails with
342<span class="l"><a name="266" href="#266">266</a>       </span>-EINVAL.
343<span class="l"><a name="267" href="#267">267</a>       </span>
344<span class="l"><a name="268" href="#268">268</a>       </span> MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5)
345<span class="l"><a name="269" href="#269">269</a>       </span>
346<span class="l"><a name="270" href="#270">270</a>       </span>This call returns the current size of the buffer in bytes.
347<span class="l"><a name="271" href="#271">271</a>       </span>
348<span class="l"><a name="272" href="#272">272</a>       </span> MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)
349<span class="l"><a name="273" href="#273">273</a>       </span>
350<span class="l"><a name="274" href="#274">274</a>       </span>This call waits for events to arrive if none were in the kernel buffer,
351<span class="l"><a name="275" href="#275">275</a>       </span>then returns the first event. Its argument is a pointer to the following
352<span class="l"><a name="276" href="#276">276</a>       </span>structure:
353<span class="l"><a name="277" href="#277">277</a>       </span>
354<span class="l"><a name="278" href="#278">278</a>       </span>struct mon_get_arg {
355<span class="l"><a name="279" href="#279">279</a>       </span> struct usbmon_packet *hdr;
356<span class="l"><a name="280" href="#280">280</a>       </span> void *data;
357<span class="l"><a name="281" href="#281">281</a>       </span> size_t alloc;           /* Length of data (can be zero) */
358<span class="l"><a name="282" href="#282">282</a>       </span>};
359<span class="l"><a name="283" href="#283">283</a>       </span>
360<span class="l"><a name="284" href="#284">284</a>       </span>Before the call, hdr, data, and alloc should be filled. Upon return, the area
361<span class="l"><a name="285" href="#285">285</a>       </span>pointed by hdr contains the next event structure, and the data buffer contains
362<span class="l"><a name="286" href="#286">286</a>       </span>the data, if any. The event is removed from the kernel buffer.
363<span class="l"><a name="287" href="#287">287</a>       </span>
364<span class="l"><a name="288" href="#288">288</a>       </span> MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
365<span class="l"><a name="289" href="#289">289</a>       </span>
366<span class="l"><a name="290" href="#290">290</a>       </span>This ioctl is primarily used when the application accesses the buffer
367<span class="l"><a name="291" href="#291">291</a>       </span>with mmap(2). Its argument is a pointer to the following structure:
368<span class="l"><a name="292" href="#292">292</a>       </span>
369<span class="l"><a name="293" href="#293">293</a>       </span>struct mon_mfetch_arg {
370<span class="l"><a name="294" href="#294">294</a>       </span> uint32_t *offvec;       /* Vector of events fetched */
371<span class="l"><a name="295" href="#295">295</a>       </span> uint32_t nfetch;        /* Number of events to fetch (out: fetched) */
372<span class="l"><a name="296" href="#296">296</a>       </span> uint32_t nflush;        /* Number of events to flush */
373<span class="l"><a name="297" href="#297">297</a>       </span>};
374<span class="l"><a name="298" href="#298">298</a>       </span>
375<span class="l"><a name="299" href="#299">299</a>       </span>The ioctl operates in 3 stages.
376<span class="l"><a name="300" href="#300">300</a>       </span>
377<span class="l"><a name="301" href="#301">301</a>       </span>First, it removes and discards up to nflush events from the kernel buffer.
378<span class="l"><a name="302" href="#302">302</a>       </span>The actual number of events discarded is returned in nflush.
379<span class="l"><a name="303" href="#303">303</a>       </span>
380<span class="l"><a name="304" href="#304">304</a>       </span>Second, it waits for an event to be present in the buffer, unless the pseudo-
381<span class="l"><a name="305" href="#305">305</a>       </span>device is open with O_NONBLOCK.
382<span class="l"><a name="306" href="#306">306</a>       </span>
383<span class="l"><a name="307" href="#307">307</a>       </span>Third, it extracts up to nfetch offsets into the mmap buffer, and stores
384<span class="l"><a name="308" href="#308">308</a>       </span>them into the offvec. The actual number of event offsets is stored into
385<span class="l"><a name="309" href="#309">309</a>       </span>the nfetch.
386<span class="l"><a name="310" href="#310">310</a>       </span>
387<span class="l"><a name="311" href="#311">311</a>       </span> MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8)
388<span class="l"><a name="312" href="#312">312</a>       </span>
389<span class="l"><a name="313" href="#313">313</a>       </span>This call removes a number of events from the kernel buffer. Its argument
390<span class="l"><a name="314" href="#314">314</a>       </span>is the number of events to remove. If the buffer contains fewer events
391<span class="l"><a name="315" href="#315">315</a>       </span>than requested, all events present are removed, and no error is reported.
392<span class="l"><a name="316" href="#316">316</a>       </span>This works when no events are available too.
393<span class="l"><a name="317" href="#317">317</a>       </span>
394<span class="l"><a name="318" href="#318">318</a>       </span> FIONBIO
395<span class="l"><a name="319" href="#319">319</a>       </span>
396<span class="l"><a name="320" href="#320">320</a>       </span>The ioctl FIONBIO may be implemented in the future, if there's a need.
397<span class="l"><a name="321" href="#321">321</a>       </span>
398<span class="l"><a name="322" href="#322">322</a>       </span>In addition to ioctl(2) and read(2), the special file of binary API can
399<span class="l"><a name="323" href="#323">323</a>       </span>be polled with select(2) and poll(2). But lseek(2) does not work.
400<span class="l"><a name="324" href="#324">324</a>       </span>
401<span class="l"><a name="325" href="#325">325</a>       </span>* Memory-mapped access of the kernel buffer for the binary API
402<span class="l"><a name="326" href="#326">326</a>       </span>
403<span class="l"><a name="327" href="#327">327</a>       </span>The basic idea is simple:
404<span class="l"><a name="328" href="#328">328</a>       </span>
405<span class="l"><a name="329" href="#329">329</a>       </span>To prepare, map the buffer by getting the current size, then using mmap(2).
406<span class="l"><a name="330" href="#330">330</a>       </span>Then, execute a loop similar to the one written in pseudo-code below:
407<span class="l"><a name="331" href="#331">331</a>       </span>
408<span class="l"><a name="332" href="#332">332</a>       </span>   struct mon_mfetch_arg fetch;
409<span class="l"><a name="333" href="#333">333</a>       </span>   struct usbmon_packet *hdr;
410<span class="l"><a name="334" href="#334">334</a>       </span>   int nflush = 0;
411<span class="l"><a name="335" href="#335">335</a>       </span>   for (;;) {
412<span class="l"><a name="336" href="#336">336</a>       </span>      fetch.offvec = vec; // Has N 32-bit words
413<span class="l"><a name="337" href="#337">337</a>       </span>      fetch.nfetch = N;   // Or less than N
414<span class="l"><a name="338" href="#338">338</a>       </span>      fetch.nflush = nflush;
415<span class="l"><a name="339" href="#339">339</a>       </span>      ioctl(fd, MON_IOCX_MFETCH, &amp;fetch);   // Process errors, too
416<span class="l"><a name="340" href="#340">340</a>       </span>      nflush = fetch.nfetch;       // This many packets to flush when done
417<span class="l"><a name="341" href="#341">341</a>       </span>      for (i = 0; i &lt; nflush; i++) {
418<span class="l"><a name="342" href="#342">342</a>       </span>         hdr = (struct ubsmon_packet *) &amp;mmap_area[vec[i]];
419<span class="l"><a name="343" href="#343">343</a>       </span>         if (hdr-&gt;type == '@')     // Filler packet
420<span class="l"><a name="344" href="#344">344</a>       </span>            continue;
421<span class="l"><a name="345" href="#345">345</a>       </span>         caddr_t data = &amp;mmap_area[vec[i]] + 64;
422<span class="l"><a name="346" href="#346">346</a>       </span>         process_packet(hdr, data);
423<span class="l"><a name="347" href="#347">347</a>       </span>      }
424<span class="l"><a name="348" href="#348">348</a>       </span>   }
425<span class="l"><a name="349" href="#349">349</a>       </span>
426<span class="l"><a name="350" href="#350">350</a>       </span>Thus, the main idea is to execute only one ioctl per N events.
427<span class="l"><a name="351" href="#351">351</a>       </span>
428<span class="l"><a name="352" href="#352">352</a>       </span>Although the buffer is circular, the returned headers and data do not cross
429<span class="l"><a name="353" href="#353">353</a>       </span>the end of the buffer, so the above pseudo-code does not need any gathering.
430</pre><div id="corner"><a href="javascript:hA()">Hide Line Numbers</a></div>
431<script type="text/javascript"><!--
432google_ad_client = "pub-5258443501063629";
433google_ad_width = 728;
434google_ad_height = 90;
435google_ad_format = "728x90_as";
436google_ad_type = "text_image";
437google_ad_channel = "5452528277+4023403012";
438google_color_border = "FFFFFF";
439google_color_bg = "FFFFFF";
440google_color_link = "0000FF";
441google_color_url = "666666";
442google_color_text = "000000";
443//--></script>
444<script type="text/javascript"
445  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
446</script>
447
448<ul id="tm" class="guides">
449<li></li>
450<li><a href="/kernel/Documentation/usb">[ usb ]</a></li>
451<li><a href="/kernel/Documentation/usb/CREDITS">CREDITS</a></li>
452<li><a href="/kernel/Documentation/usb/URB.txt">URB.txt</a></li>
453<li><a href="/kernel/Documentation/usb/acm.txt">acm.txt</a></li>
454<li><a href="/kernel/Documentation/usb/auerswald.txt">auerswald.txt</a></li>
455<li><a href="/kernel/Documentation/usb/dma.txt">dma.txt</a></li>
456<li><a href="/kernel/Documentation/usb/ehci.txt">ehci.txt</a></li>
457<li><a href="/kernel/Documentation/usb/error-codes.txt">error-codes.txt</a></li>
458<li><a href="/kernel/Documentation/usb/gadget_serial.txt">gadget_serial.txt</a></li>
459<li><a href="/kernel/Documentation/usb/hiddev.txt">hiddev.txt</a></li>
460<li><a href="/kernel/Documentation/usb/hotplug.txt">hotplug.txt</a></li>
461<li><a href="/kernel/Documentation/usb/linux.inf">linux.inf</a></li>
462<li><a href="/kernel/Documentation/usb/mtouchusb.txt">mtouchusb.txt</a></li>
463<li><a href="/kernel/Documentation/usb/ohci.txt">ohci.txt</a></li>
464<li><a href="/kernel/Documentation/usb/persist.txt">persist.txt</a></li>
465<li><a href="/kernel/Documentation/usb/proc_usb_info.txt">proc_usb_info.txt</a></li>
466<li><a href="/kernel/Documentation/usb/rio.txt">rio.txt</a></li>
467<li><a href="/kernel/Documentation/usb/uhci.txt">uhci.txt</a></li>
468<li><a href="/kernel/Documentation/usb/usb-help.txt">usb-help.txt</a></li>
469<li><a href="/kernel/Documentation/usb/usb-serial.txt">usb-serial.txt</a></li>
470<li id="current"><a href="/kernel/Documentation/usb/usbmon.txt">usbmon.txt</a></li>
471<li>&nbsp;</li>
472<li><script type="text/javascript"><!--
473google_ad_client = "pub-5258443501063629";
474google_ad_width = 120;
475google_ad_height = 240;
476google_ad_format = "120x240_as";
477google_ad_type = "text_image";
478google_ad_channel = "5452528277+3146992977";
479google_color_border = "FFFFFF";
480google_color_bg = "FFFFFF";
481google_color_link = "0000FF";
482google_color_url = "666666";
483google_color_text = "000000";
484//--></script>
485<script type="text/javascript"
486  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
487</script>
488
489</li>
490</ul>
491<div id="tagline"><span class="aboutkernel"><a href="http://www.mjmwired.net/resources/mjm-kernel-docs.html">About Kernel Documentation</a></span><span class="bluelink"> <a href="http://www.kernel.org/" target="_blank">Linux Kernel</a> <a href="http://www.mjmwired.net/contact/">Contact</a> <a href="http://www.mjmwired.net/resources/">Linux Resources</a> <a href="http://www.mjmwired.net/linux/">Linux Blog</a></span></div>
492<script type="text/javascript"><!--
493google_ad_client = "pub-5258443501063629";
494google_ad_width = 468;
495google_ad_height = 15;
496google_ad_format = "468x15_0ads_al_s";
497google_ad_channel = "5452528277+1845082300";
498google_color_border = "FFFFFF";
499google_color_bg = "FFFFFF";
500google_color_link = "0000FF";
501google_color_url = "666666";
502google_color_text = "000000";
503//--></script>
504<script type="text/javascript"
505  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
506</script>
507<hr><div id="disclaim">Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.</div>
508
509</div>
510</body></html>
Note: See TracBrowser for help on using the browser.