Gitiles
Code Review Sign In
192.168.1.100 / T103 / 1f884588077ad3476b9c91cbb0ee9ee0332bbb68 / . / src / kernel / linux / v4.14 / Documentation / driver-api / usb / dwc3.rst
blob: c3dc84a50ce54013aca2cd1b83b65e704b918e3b [file] [log] [blame]
rjw1f884582022-01-06 17:20:42 +0800[diff] [blame^]1===============================================================
2Synopsys DesignWare Core SuperSpeed USB 3.0 Controller
3===============================================================
4
5:Author: Felipe Balbi <felipe.balbi@linux.intel.com>
6:Date: April 2017
7
8Introduction
9============
10
11The *Synopsys DesignWare Core SuperSpeed USB 3.0 Controller*
12(hereinafter referred to as *DWC3*) is a USB SuperSpeed compliant
13controller which can be configured in one of 4 ways:
14
15 1. Peripheral-only configuration
16 2. Host-only configuration
17 3. Dual-Role configuration
18 4. Hub configuration
19
20Linux currently supports several versions of this controller. In all
21likelyhood, the version in your SoC is already supported. At the time
22of this writing, known tested versions range from 2.02a to 3.10a. As a
23rule of thumb, anything above 2.02a should work reliably well.
24
25Currently, we have many known users for this driver. In alphabetical
26order:
27
28 1. Cavium
29 2. Intel Corporation
30 3. Qualcomm
31 4. Rockchip
32 5. ST
33 6. Samsung
34 7. Texas Instruments
35 8. Xilinx
36
37Summary of Features
38======================
39
40For details about features supported by your version of DWC3, consult
41your IP team and/or *Synopsys DesignWare Core SuperSpeed USB 3.0
42Controller Databook*. Following is a list of features supported by the
43driver at the time of this writing:
44
45 1. Up to 16 bidirectional endpoints (including the control
46 pipe - ep0)
47 2. Flexible endpoint configuration
48 3. Simultaneous IN and OUT transfer support
49 4. Scatter-list support
50 5. Up to 256 TRBs [#trb]_ per endpoint
51 6. Support for all transfer types (*Control*, *Bulk*,
52 *Interrupt*, and *Isochronous*)
53 7. SuperSpeed Bulk Streams
54 8. Link Power Management
55 9. Trace Events for debugging
56 10. DebugFS [#debugfs]_ interface
57
58These features have all been exercised with many of the **in-tree**
59gadget drivers. We have verified both *ConfigFS* [#configfs]_ and
60legacy gadget drivers.
61
62Driver Design
63==============
64
65The DWC3 driver sits on the *drivers/usb/dwc3/* directory. All files
66related to this driver are in this one directory. This makes it easy
67for new-comers to read the code and understand how it behaves.
68
69Because of DWC3's configuration flexibility, the driver is a little
70complex in some places but it should be rather straightforward to
71understand.
72
73The biggest part of the driver refers to the Gadget API.
74
75Known Limitations
76===================
77
78Like any other HW, DWC3 has its own set of limitations. To avoid
79constant questions about such problems, we decided to document them
80here and have a single location to where we could point users.
81
82OUT Transfer Size Requirements
83---------------------------------
84
85According to Synopsys Databook, all OUT transfer TRBs [#trb]_ must
86have their *size* field set to a value which is integer divisible by
87the endpoint's *wMaxPacketSize*. This means that *e.g.* in order to
88receive a Mass Storage *CBW* [#cbw]_, req->length must either be set
89to a value that's divisible by *wMaxPacketSize* (1024 on SuperSpeed,
90512 on HighSpeed, etc), or DWC3 driver must add a Chained TRB pointing
91to a throw-away buffer for the remaining length. Without this, OUT
92transfers will **NOT** start.
93
94Note that as of this writing, this won't be a problem because DWC3 is
95fully capable of appending a chained TRB for the remaining length and
96completely hide this detail from the gadget driver. It's still worth
97mentioning because this seems to be the largest source of queries
98about DWC3 and *non-working transfers*.
99
100TRB Ring Size Limitation
101-------------------------
102
103We, currently, have a hard limit of 256 TRBs [#trb]_ per endpoint,
104with the last TRB being a Link TRB [#link_trb]_ pointing back to the
105first. This limit is arbitrary but it has the benefit of adding up to
106exactly 4096 bytes, or 1 Page.
107
108DWC3 driver will try its best to cope with more than 255 requests and,
109for the most part, it should work normally. However this is not
110something that has been exercised very frequently. If you experience
111any problems, see section **Reporting Bugs** below.
112
113Reporting Bugs
114================
115
116Whenever you encounter a problem with DWC3, first and foremost you
117should make sure that:
118
119 1. You're running latest tag from `Linus' tree`_
120 2. You can reproduce the error without any out-of-tree changes
121 to DWC3
122 3. You have checked that it's not a fault on the host machine
123
124After all these are verified, then here's how to capture enough
125information so we can be of any help to you.
126
127Required Information
128---------------------
129
130DWC3 relies exclusively on Trace Events for debugging. Everything is
131exposed there, with some extra bits being exposed to DebugFS
132[#debugfs]_.
133
134In order to capture DWC3's Trace Events you should run the following
135commands **before** plugging the USB cable to a host machine:
136
137.. code-block:: sh
138
139 # mkdir -p /d
140 # mkdir -p /t
141 # mount -t debugfs none /d
142 # mount -t tracefs none /t
143 # echo 81920 > /t/buffer_size_kb
144 # echo 1 > /t/events/dwc3/enable
145
146After this is done, you can connect your USB cable and reproduce the
147problem. As soon as the fault is reproduced, make a copy of files
148``trace`` and ``regdump``, like so:
149
150.. code-block:: sh
151
152 # cp /t/trace /root/trace.txt
153 # cat /d/*dwc3*/regdump > /root/regdump.txt
154
155Make sure to compress ``trace.txt`` and ``regdump.txt`` in a tarball
156and email it to `me`_ with `linux-usb`_ in Cc. If you want to be extra
157sure that I'll help you, write your subject line in the following
158format:
159
160 **[BUG REPORT] usb: dwc3: Bug while doing XYZ**
161
162On the email body, make sure to detail what you doing, which gadget
163driver you were using, how to reproduce the problem, what SoC you're
164using, which OS (and its version) was running on the Host machine.
165
166With all this information, we should be able to understand what's
167going on and be helpful to you.
168
169Debugging
170===========
171
172First and foremost a disclaimer::
173
174 DISCLAIMER: The information available on DebugFS and/or TraceFS can
175 change at any time at any Major Linux Kernel Release. If writing
176 scripts, do **NOT** assume information to be available in the
177 current format.
178
179With that out of the way, let's carry on.
180
181If you're willing to debug your own problem, you deserve a round of
182applause :-)
183
184Anyway, there isn't much to say here other than Trace Events will be
185really helpful in figuring out issues with DWC3. Also, access to
186Synopsys Databook will be **really** valuable in this case.
187
188A USB Sniffer can be helpful at times but it's not entirely required,
189there's a lot that can be understood without looking at the wire.
190
191Feel free to email `me`_ and Cc `linux-usb`_ if you need any help.
192
193``DebugFS``
194-------------
195
196``DebugFS`` is very good for gathering snapshots of what's going on
197with DWC3 and/or any endpoint.
198
199On DWC3's ``DebugFS`` directory, you will find the following files and
200directories:
201
202``ep[0..15]{in,out}/``
203``link_state``
204``regdump``
205``testmode``
206
207``link_state``
208``````````````
209
210When read, ``link_state`` will print out one of ``U0``, ``U1``,
211``U2``, ``U3``, ``SS.Disabled``, ``RX.Detect``, ``SS.Inactive``,
212``Polling``, ``Recovery``, ``Hot Reset``, ``Compliance``,
213``Loopback``, ``Reset``, ``Resume`` or ``UNKNOWN link state``.
214
215This file can also be written to in order to force link to one of the
216states above.
217
218``regdump``
219`````````````
220
221File name is self-explanatory. When read, ``regdump`` will print out a
222register dump of DWC3. Note that this file can be grepped to find the
223information you want.
224
225``testmode``
226``````````````
227
228When read, ``testmode`` will print out a name of one of the specified
229USB 2.0 Testmodes (``test_j``, ``test_k``, ``test_se0_nak``,
230``test_packet``, ``test_force_enable``) or the string ``no test`` in
231case no tests are currently being executed.
232
233In order to start any of these test modes, the same strings can be
234written to the file and DWC3 will enter the requested test mode.
235
236
237``ep[0..15]{in,out}``
238``````````````````````
239
240For each endpoint we expose one directory following the naming
241convention ``ep$num$dir`` *(ep0in, ep0out, ep1in, ...)*. Inside each
242of these directories you will find the following files:
243
244``descriptor_fetch_queue``
245``event_queue``
246``rx_fifo_queue``
247``rx_info_queue``
248``rx_request_queue``
249``transfer_type``
250``trb_ring``
251``tx_fifo_queue``
252``tx_request_queue``
253
254With access to Synopsys Databook, you can decode the information on
255them.
256
257``transfer_type``
258~~~~~~~~~~~~~~~~~~
259
260When read, ``transfer_type`` will print out one of ``control``,
261``bulk``, ``interrupt`` or ``isochronous`` depending on what the
262endpoint descriptor says. If the endpoint hasn't been enabled yet, it
263will print ``--``.
264
265``trb_ring``
266~~~~~~~~~~~~~
267
268When read, ``trb_ring`` will print out details about all TRBs on the
269ring. It will also tell you where our enqueue and dequeue pointers are
270located in the ring:
271
272.. code-block:: sh
273
274 buffer_addr,size,type,ioc,isp_imi,csp,chn,lst,hwo
275 000000002c754000,481,normal,1,0,1,0,0,0
276 000000002c75c000,481,normal,1,0,1,0,0,0
277 000000002c780000,481,normal,1,0,1,0,0,0
278 000000002c788000,481,normal,1,0,1,0,0,0
279 000000002c78c000,481,normal,1,0,1,0,0,0
280 000000002c754000,481,normal,1,0,1,0,0,0
281 000000002c75c000,481,normal,1,0,1,0,0,0
282 000000002c784000,481,normal,1,0,1,0,0,0
283 000000002c788000,481,normal,1,0,1,0,0,0
284 000000002c78c000,481,normal,1,0,1,0,0,0
285 000000002c790000,481,normal,1,0,1,0,0,0
286 000000002c758000,481,normal,1,0,1,0,0,0
287 000000002c780000,481,normal,1,0,1,0,0,0
288 000000002c788000,481,normal,1,0,1,0,0,0
289 000000002c790000,481,normal,1,0,1,0,0,0
290 000000002c758000,481,normal,1,0,1,0,0,0
291 000000002c780000,481,normal,1,0,1,0,0,0
292 000000002c784000,481,normal,1,0,1,0,0,0
293 000000002c788000,481,normal,1,0,1,0,0,0
294 000000002c78c000,481,normal,1,0,1,0,0,0
295 000000002c754000,481,normal,1,0,1,0,0,0
296 000000002c758000,481,normal,1,0,1,0,0,0
297 000000002c780000,481,normal,1,0,1,0,0,0
298 000000002c784000,481,normal,1,0,1,0,0,0
299 000000002c78c000,481,normal,1,0,1,0,0,0
300 000000002c790000,481,normal,1,0,1,0,0,0
301 000000002c758000,481,normal,1,0,1,0,0,0
302 000000002c780000,481,normal,1,0,1,0,0,0
303 000000002c788000,481,normal,1,0,1,0,0,0
304 000000002c790000,481,normal,1,0,1,0,0,0
305 000000002c758000,481,normal,1,0,1,0,0,0
306 000000002c780000,481,normal,1,0,1,0,0,0
307 000000002c788000,481,normal,1,0,1,0,0,0
308 000000002c790000,481,normal,1,0,1,0,0,0
309 000000002c758000,481,normal,1,0,1,0,0,0
310 000000002c780000,481,normal,1,0,1,0,0,0
311 000000002c788000,481,normal,1,0,1,0,0,0
312 000000002c790000,481,normal,1,0,1,0,0,0
313 000000002c758000,481,normal,1,0,1,0,0,0
314 000000002c780000,481,normal,1,0,1,0,0,0
315 000000002c788000,481,normal,1,0,1,0,0,0
316 000000002c790000,481,normal,1,0,1,0,0,0
317 000000002c758000,481,normal,1,0,1,0,0,0
318 000000002c780000,481,normal,1,0,1,0,0,0
319 000000002c788000,481,normal,1,0,1,0,0,0
320 000000002c790000,481,normal,1,0,1,0,0,0
321 000000002c758000,481,normal,1,0,1,0,0,0
322 000000002c780000,481,normal,1,0,1,0,0,0
323 000000002c788000,481,normal,1,0,1,0,0,0
324 000000002c790000,481,normal,1,0,1,0,0,0
325 000000002c758000,481,normal,1,0,1,0,0,0
326 000000002c780000,481,normal,1,0,1,0,0,0
327 000000002c788000,481,normal,1,0,1,0,0,0
328 000000002c790000,481,normal,1,0,1,0,0,0
329 000000002c758000,481,normal,1,0,1,0,0,0
330 000000002c780000,481,normal,1,0,1,0,0,0
331 000000002c78c000,481,normal,1,0,1,0,0,0
332 000000002c784000,481,normal,1,0,1,0,0,0
333 000000002c788000,481,normal,1,0,1,0,0,0
334 000000002c78c000,481,normal,1,0,1,0,0,0
335 000000002c754000,481,normal,1,0,1,0,0,0
336 000000002c758000,481,normal,1,0,1,0,0,0
337 000000002c780000,481,normal,1,0,1,0,0,0
338 000000002c788000,481,normal,1,0,1,0,0,0
339 000000002c790000,481,normal,1,0,1,0,0,0
340 000000002c758000,481,normal,1,0,1,0,0,0
341 000000002c780000,481,normal,1,0,1,0,0,0
342 000000002c758000,481,normal,1,0,1,0,0,0
343 000000002c780000,481,normal,1,0,1,0,0,0
344 000000002c78c000,481,normal,1,0,1,0,0,0
345 000000002c75c000,481,normal,1,0,1,0,0,0
346 000000002c78c000,481,normal,1,0,1,0,0,0
347 000000002c780000,481,normal,1,0,1,0,0,0
348 000000002c754000,481,normal,1,0,1,0,0,0
349 000000002c788000,481,normal,1,0,1,0,0,0
350 000000002c754000,481,normal,1,0,1,0,0,0
351 000000002c780000,481,normal,1,0,1,0,0,0
352 000000002c788000,481,normal,1,0,1,0,0,0
353 000000002c78c000,481,normal,1,0,1,0,0,0
354 000000002c790000,481,normal,1,0,1,0,0,0
355 000000002c754000,481,normal,1,0,1,0,0,0
356 000000002c758000,481,normal,1,0,1,0,0,0
357 000000002c75c000,481,normal,1,0,1,0,0,0
358 000000002c780000,481,normal,1,0,1,0,0,0
359 000000002c784000,481,normal,1,0,1,0,0,0
360 000000002c788000,481,normal,1,0,1,0,0,0
361 000000002c78c000,481,normal,1,0,1,0,0,0
362 000000002c790000,481,normal,1,0,1,0,0,0
363 000000002c754000,481,normal,1,0,1,0,0,0
364 000000002c758000,481,normal,1,0,1,0,0,0
365 000000002c75c000,512,normal,1,0,1,0,0,1 D
366 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 E
367 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
368 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
369 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
370 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
371 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
372 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
373 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
374 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
375 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
376 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
377 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
378 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
379 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
380 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
381 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
382 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
383 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
384 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
385 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
386 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
387 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
388 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
389 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
390 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
391 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
392 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
393 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
394 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
395 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
396 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
397 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
398 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
399 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
400 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
401 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
402 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
403 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
404 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
405 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
406 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
407 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
408 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
409 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
410 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
411 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
412 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
413 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
414 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
415 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
416 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
417 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
418 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
419 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
420 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
421 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
422 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
423 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
424 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
425 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
426 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
427 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
428 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
429 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
430 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
431 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
432 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
433 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
434 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
435 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
436 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
437 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
438 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
439 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
440 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
441 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
442 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
443 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
444 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
445 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
446 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
447 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
448 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
449 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
450 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
451 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
452 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
453 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
454 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
455 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
456 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
457 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
458 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
459 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
460 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
461 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
462 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
463 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
464 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
465 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
466 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
467 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
468 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
469 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
470 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
471 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
472 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
473 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
474 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
475 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
476 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
477 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
478 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
479 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
480 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
481 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
482 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
483 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
484 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
485 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
486 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
487 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
488 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
489 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
490 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
491 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
492 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
493 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
494 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
495 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
496 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
497 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
498 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
499 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
500 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
501 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
502 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
503 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
504 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
505 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
506 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
507 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
508 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
509 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
510 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
511 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
512 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
513 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
514 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
515 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
516 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
517 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
518 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
519 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
520 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
521 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
522 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
523 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
524 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
525 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
526 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
527 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
528 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
529 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
530 00000000381ab000,0,link,0,0,0,0,0,1
531
532
533Trace Events
534-------------
535
536DWC3 also provides several trace events which help us gathering
537information about the behavior of the driver during runtime.
538
539In order to use these events, you must enable ``CONFIG_FTRACE`` in
540your kernel config.
541
542For details about how enable DWC3 events, see section **Reporting
543Bugs**.
544
545The following subsections will give details about each Event Class and
546each Event defined by DWC3.
547
548MMIO
549```````
550
551It is sometimes useful to look at every MMIO access when looking for
552bugs. Because of that, DWC3 offers two Trace Events (one for
553dwc3_readl() and one for dwc3_writel()). ``TP_printk`` follows::
554
555 TP_printk("addr %p value %08x", __entry->base + __entry->offset,
556 __entry->value)
557
558Interrupt Events
559````````````````
560
561Every IRQ event can be logged and decoded into a human readable
562string. Because every event will be different, we don't give an
563example other than the ``TP_printk`` format used::
564
565 TP_printk("event (%08x): %s", __entry->event,
566 dwc3_decode_event(__entry->event, __entry->ep0state))
567
568Control Request
569`````````````````
570
571Every USB Control Request can be logged to the trace buffer. The
572output format is::
573
574 TP_printk("%s", dwc3_decode_ctrl(__entry->bRequestType,
575 __entry->bRequest, __entry->wValue,
576 __entry->wIndex, __entry->wLength)
577 )
578
579Note that Standard Control Requests will be decoded into
580human-readable strings with their respective arguments. Class and
581Vendor requests will be printed out a sequence of 8 bytes in hex
582format.
583
584Lifetime of a ``struct usb_request``
585```````````````````````````````````````
586
587The entire lifetime of a ``struct usb_request`` can be tracked on the
588trace buffer. We have one event for each of allocation, free,
589queueing, dequeueing, and giveback. Output format is::
590
591 TP_printk("%s: req %p length %u/%u %s%s%s ==> %d",
592 __get_str(name), __entry->req, __entry->actual, __entry->length,
593 __entry->zero ? "Z" : "z",
594 __entry->short_not_ok ? "S" : "s",
595 __entry->no_interrupt ? "i" : "I",
596 __entry->status
597 )
598
599Generic Commands
600````````````````````
601
602We can log and decode every Generic Command with its completion
603code. Format is::
604
605 TP_printk("cmd '%s' [%x] param %08x --> status: %s",
606 dwc3_gadget_generic_cmd_string(__entry->cmd),
607 __entry->cmd, __entry->param,
608 dwc3_gadget_generic_cmd_status_string(__entry->status)
609 )
610
611Endpoint Commands
612````````````````````
613
614Endpoints commands can also be logged together with completion
615code. Format is::
616
617 TP_printk("%s: cmd '%s' [%d] params %08x %08x %08x --> status: %s",
618 __get_str(name), dwc3_gadget_ep_cmd_string(__entry->cmd),
619 __entry->cmd, __entry->param0,
620 __entry->param1, __entry->param2,
621 dwc3_ep_cmd_status_string(__entry->cmd_status)
622 )
623
624Lifetime of a ``TRB``
625``````````````````````
626
627A ``TRB`` Lifetime is simple. We are either preparing a ``TRB`` or
628completing it. With these two events, we can see how a ``TRB`` changes
629over time. Format is::
630
631 TP_printk("%s: %d/%d trb %p buf %08x%08x size %s%d ctrl %08x (%c%c%c%c:%c%c:%s)",
632 __get_str(name), __entry->queued, __entry->allocated,
633 __entry->trb, __entry->bph, __entry->bpl,
634 ({char *s;
635 int pcm = ((__entry->size >> 24) & 3) + 1;
636 switch (__entry->type) {
637 case USB_ENDPOINT_XFER_INT:
638 case USB_ENDPOINT_XFER_ISOC:
639 switch (pcm) {
640 case 1:
641 s = "1x ";
642 break;
643 case 2:
644 s = "2x ";
645 break;
646 case 3:
647 s = "3x ";
648 break;
649 }
650 default:
651 s = "";
652 } s; }),
653 DWC3_TRB_SIZE_LENGTH(__entry->size), __entry->ctrl,
654 __entry->ctrl & DWC3_TRB_CTRL_HWO ? 'H' : 'h',
655 __entry->ctrl & DWC3_TRB_CTRL_LST ? 'L' : 'l',
656 __entry->ctrl & DWC3_TRB_CTRL_CHN ? 'C' : 'c',
657 __entry->ctrl & DWC3_TRB_CTRL_CSP ? 'S' : 's',
658 __entry->ctrl & DWC3_TRB_CTRL_ISP_IMI ? 'S' : 's',
659 __entry->ctrl & DWC3_TRB_CTRL_IOC ? 'C' : 'c',
660 dwc3_trb_type_string(DWC3_TRBCTL_TYPE(__entry->ctrl))
661 )
662
663Lifetime of an Endpoint
664```````````````````````
665
666And endpoint's lifetime is summarized with enable and disable
667operations, both of which can be traced. Format is::
668
669 TP_printk("%s: mps %d/%d streams %d burst %d ring %d/%d flags %c:%c%c%c%c%c:%c:%c",
670 __get_str(name), __entry->maxpacket,
671 __entry->maxpacket_limit, __entry->max_streams,
672 __entry->maxburst, __entry->trb_enqueue,
673 __entry->trb_dequeue,
674 __entry->flags & DWC3_EP_ENABLED ? 'E' : 'e',
675 __entry->flags & DWC3_EP_STALL ? 'S' : 's',
676 __entry->flags & DWC3_EP_WEDGE ? 'W' : 'w',
677 __entry->flags & DWC3_EP_BUSY ? 'B' : 'b',
678 __entry->flags & DWC3_EP_PENDING_REQUEST ? 'P' : 'p',
679 __entry->flags & DWC3_EP_MISSED_ISOC ? 'M' : 'm',
680 __entry->flags & DWC3_EP_END_TRANSFER_PENDING ? 'E' : 'e',
681 __entry->direction ? '<' : '>'
682 )
683
684
685Structures, Methods and Definitions
686====================================
687
688.. kernel-doc:: drivers/usb/dwc3/core.h
689 :doc: main data structures
690 :internal:
691
692.. kernel-doc:: drivers/usb/dwc3/gadget.h
693 :doc: gadget-only helpers
694 :internal:
695
696.. kernel-doc:: drivers/usb/dwc3/gadget.c
697 :doc: gadget-side implementation
698 :internal:
699
700.. kernel-doc:: drivers/usb/dwc3/core.c
701 :doc: core driver (probe, PM, etc)
702 :internal:
703
704.. [#trb] Transfer Request Block
705.. [#link_trb] Transfer Request Block pointing to another Transfer
706 Request Block.
707.. [#debugfs] The Debug File System
708.. [#configfs] The Config File System
709.. [#cbw] Command Block Wrapper
710.. _Linus' tree: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/
711.. _me: felipe.balbi@linux.intel.com
712.. _linux-usb: linux-usb@vger.kernel.org