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_TRANSFER_STARTED ? 'B' : 'b',
678  	__entry->flags & DWC3_EP_PENDING_REQUEST ? 'P' : 'p',
679  	__entry->flags & DWC3_EP_END_TRANSFER_PENDING ? 'E' : 'e',
680  	__entry->direction ? '<' : '>'
681  )
682
683
684Structures, Methods and Definitions
685====================================
686
687.. kernel-doc:: drivers/usb/dwc3/core.h
688   :doc: main data structures
689   :internal:
690
691.. kernel-doc:: drivers/usb/dwc3/gadget.h
692   :doc: gadget-only helpers
693   :internal:
694
695.. kernel-doc:: drivers/usb/dwc3/gadget.c
696   :doc: gadget-side implementation
697   :internal:
698
699.. kernel-doc:: drivers/usb/dwc3/core.c
700   :doc: core driver (probe, PM, etc)
701   :internal:
702
703.. [#trb] Transfer Request Block
704.. [#link_trb] Transfer Request Block pointing to another Transfer
705	       Request Block.
706.. [#debugfs] The Debug File System
707.. [#configfs] The Config File System
708.. [#cbw] Command Block Wrapper
709.. _Linus' tree: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/
710.. _me: felipe.balbi@linux.intel.com
711.. _linux-usb: linux-usb@vger.kernel.org
712