tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
usb: dwc3: add ReST documentation
Document a few details about DWC3 in order to help people report bugs
and debug DWC3.
Signed-off-by: Felipe Balbi <felipe.balbi@linux.intel.com>
+713
+712
Documentation/driver-api/usb/dwc3.rst
+712
Documentation/driver-api/usb/dwc3.rst
···
1
+
===============================================================
2
+
Synopsys DesignWare Core SuperSpeed USB 3.0 Controller
3
+
===============================================================
4
+
5
+
:Author: Felipe Balbi <felipe.balbi@linux.intel.com>
6
+
:Date: April 2017
7
+
8
+
Introduction
9
+
============
10
+
11
+
The *Synopsys DesignWare Core SuperSpeed USB 3.0 Controller*
12
+
(hereinafter referred to as *DWC3*) is a USB SuperSpeed compliant
13
+
controller 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
+
20
+
Linux currently supports several versions of this controller. In all
21
+
likelyhood, the version in your SoC is already supported. At the time
22
+
of this writing, known tested versions range from 2.02a to 3.10a. As a
23
+
rule of thumb, anything above 2.02a should work reliably well.
24
+
25
+
Currently, we have many known users for this driver. In alphabetical
26
+
order:
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
+
37
+
Summary of Features
38
+
======================
39
+
40
+
For details about features supported by your version of DWC3, consult
41
+
your IP team and/or *Synopsys DesignWare Core SuperSpeed USB 3.0
42
+
Controller Databook*. Following is a list of features supported by the
43
+
driver 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
+
58
+
These features have all been exercised with many of the **in-tree**
59
+
gadget drivers. We have verified both *ConfigFS* [#configfs]_ and
60
+
legacy gadget drivers.
61
+
62
+
Driver Design
63
+
==============
64
+
65
+
The DWC3 driver sits on the *drivers/usb/dwc3/* directory. All files
66
+
related to this driver are in this one directory. This makes it easy
67
+
for new-comers to read the code and understand how it behaves.
68
+
69
+
Because of DWC3's configuration flexibility, the driver is a little
70
+
complex in some places but it should be rather straightforward to
71
+
understand.
72
+
73
+
The biggest part of the driver refers to the Gadget API.
74
+
75
+
Known Limitations
76
+
===================
77
+
78
+
Like any other HW, DWC3 has its own set of limitations. To avoid
79
+
constant questions about such problems, we decided to document them
80
+
here and have a single location to where we could point users.
81
+
82
+
OUT Transfer Size Requirements
83
+
---------------------------------
84
+
85
+
According to Synopsys Databook, all OUT transfer TRBs [#trb]_ must
86
+
have their *size* field set to a value which is integer divisible by
87
+
the endpoint's *wMaxPacketSize*. This means that *e.g.* in order to
88
+
receive a Mass Storage *CBW* [#cbw]_, req->length must either be set
89
+
to a value that's divisible by *wMaxPacketSize* (1024 on SuperSpeed,
90
+
512 on HighSpeed, etc), or DWC3 driver must add a Chained TRB pointing
91
+
to a throw-away buffer for the remaining length. Without this, OUT
92
+
transfers will **NOT** start.
93
+
94
+
Note that as of this writing, this won't be a problem because DWC3 is
95
+
fully capable of appending a chained TRB for the remaining length and
96
+
completely hide this detail from the gadget driver. It's still worth
97
+
mentioning because this seems to be the largest source of queries
98
+
about DWC3 and *non-working transfers*.
99
+
100
+
TRB Ring Size Limitation
101
+
-------------------------
102
+
103
+
We, currently, have a hard limit of 256 TRBs [#trb]_ per endpoint,
104
+
with the last TRB being a Link TRB [#link_trb]_ pointing back to the
105
+
first. This limit is arbitrary but it has the benefit of adding up to
106
+
exactly 4096 bytes, or 1 Page.
107
+
108
+
DWC3 driver will try its best to cope with more than 255 requests and,
109
+
for the most part, it should work normally. However this is not
110
+
something that has been exercised very frequently. If you experience
111
+
any problems, see section **Reporting Bugs** below.
112
+
113
+
Reporting Bugs
114
+
================
115
+
116
+
Whenever you encounter a problem with DWC3, first and foremost you
117
+
should 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
+
124
+
After all these are verified, then here's how to capture enough
125
+
information so we can be of any help to you.
126
+
127
+
Required Information
128
+
---------------------
129
+
130
+
DWC3 relies exclusively on Trace Events for debugging. Everything is
131
+
exposed there, with some extra bits being exposed to DebugFS
132
+
[#debugfs]_.
133
+
134
+
In order to capture DWC3's Trace Events you should run the following
135
+
commands **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
+
146
+
After this is done, you can connect your USB cable and reproduce the
147
+
problem. 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
+
155
+
Make sure to compress ``trace.txt`` and ``regdump.txt`` in a tarball
156
+
and email it to `me`_ with `linux-usb`_ in Cc. If you want to be extra
157
+
sure that I'll help you, write your subject line in the following
158
+
format:
159
+
160
+
**[BUG REPORT] usb: dwc3: Bug while doing XYZ**
161
+
162
+
On the email body, make sure to detail what you doing, which gadget
163
+
driver you were using, how to reproduce the problem, what SoC you're
164
+
using, which OS (and its version) was running on the Host machine.
165
+
166
+
With all this information, we should be able to understand what's
167
+
going on and be helpful to you.
168
+
169
+
Debugging
170
+
===========
171
+
172
+
First 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
+
179
+
With that out of the way, let's carry on.
180
+
181
+
If you're willing to debug your own problem, you deserve a round of
182
+
applause :-)
183
+
184
+
Anyway, there isn't much to say here other than Trace Events will be
185
+
really helpful in figuring out issues with DWC3. Also, access to
186
+
Synopsys Databook will be **really** valuable in this case.
187
+
188
+
A USB Sniffer can be helpful at times but it's not entirely required,
189
+
there's a lot that can be understood without looking at the wire.
190
+
191
+
Feel 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
197
+
with DWC3 and/or any endpoint.
198
+
199
+
On DWC3's ``DebugFS`` directory, you will find the following files and
200
+
directories:
201
+
202
+
``ep[0..15]{in,out}/``
203
+
``link_state``
204
+
``regdump``
205
+
``testmode``
206
+
207
+
``link_state``
208
+
``````````````
209
+
210
+
When 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
+
215
+
This file can also be written to in order to force link to one of the
216
+
states above.
217
+
218
+
``regdump``
219
+
`````````````
220
+
221
+
File name is self-explanatory. When read, ``regdump`` will print out a
222
+
register dump of DWC3. Note that this file can be grepped to find the
223
+
information you want.
224
+
225
+
``testmode``
226
+
``````````````
227
+
228
+
When read, ``testmode`` will print out a name of one of the specified
229
+
USB 2.0 Testmodes (``test_j``, ``test_k``, ``test_se0_nak``,
230
+
``test_packet``, ``test_force_enable``) or the string ``no test`` in
231
+
case no tests are currently being executed.
232
+
233
+
In order to start any of these test modes, the same strings can be
234
+
written to the file and DWC3 will enter the requested test mode.
235
+
236
+
237
+
``ep[0..15]{in,out}``
238
+
``````````````````````
239
+
240
+
For each endpoint we expose one directory following the naming
241
+
convention ``ep$num$dir`` *(ep0in, ep0out, ep1in, ...)*. Inside each
242
+
of 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
+
254
+
With access to Synopsys Databook, you can decode the information on
255
+
them.
256
+
257
+
``transfer_type``
258
+
~~~~~~~~~~~~~~~~~~
259
+
260
+
When read, ``transfer_type`` will print out one of ``control``,
261
+
``bulk``, ``interrupt`` or ``isochronous`` depending on what the
262
+
endpoint descriptor says. If the endpoint hasn't been enabled yet, it
263
+
will print ``--``.
264
+
265
+
``trb_ring``
266
+
~~~~~~~~~~~~~
267
+
268
+
When read, ``trb_ring`` will print out details about all TRBs on the
269
+
ring. It will also tell you where our enqueue and dequeue pointers are
270
+
located 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
+
533
+
Trace Events
534
+
-------------
535
+
536
+
DWC3 also provides several trace events which help us gathering
537
+
information about the behavior of the driver during runtime.
538
+
539
+
In order to use these events, you must enable ``CONFIG_FTRACE`` in
540
+
your kernel config.
541
+
542
+
For details about how enable DWC3 events, see section **Reporting
543
+
Bugs**.
544
+
545
+
The following subsections will give details about each Event Class and
546
+
each Event defined by DWC3.
547
+
548
+
MMIO
549
+
```````
550
+
551
+
It is sometimes useful to look at every MMIO access when looking for
552
+
bugs. Because of that, DWC3 offers two Trace Events (one for
553
+
dwc3_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
+
558
+
Interrupt Events
559
+
````````````````
560
+
561
+
Every IRQ event can be logged and decoded into a human readable
562
+
string. Because every event will be different, we don't give an
563
+
example 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
+
568
+
Control Request
569
+
`````````````````
570
+
571
+
Every USB Control Request can be logged to the trace buffer. The
572
+
output format is::
573
+
574
+
TP_printk("%s", dwc3_decode_ctrl(__entry->bRequestType,
575
+
__entry->bRequest, __entry->wValue,
576
+
__entry->wIndex, __entry->wLength)
577
+
)
578
+
579
+
Note that Standard Control Requests will be decoded into
580
+
human-readable strings with their respective arguments. Class and
581
+
Vendor requests will be printed out a sequence of 8 bytes in hex
582
+
format.
583
+
584
+
Lifetime of a ``struct usb_request``
585
+
```````````````````````````````````````
586
+
587
+
The entire lifetime of a ``struct usb_request`` can be tracked on the
588
+
trace buffer. We have one event for each of allocation, free,
589
+
queueing, 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
+
599
+
Generic Commands
600
+
````````````````````
601
+
602
+
We can log and decode every Generic Command with its completion
603
+
code. 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
+
611
+
Endpoint Commands
612
+
````````````````````
613
+
614
+
Endpoints commands can also be logged together with completion
615
+
code. 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
+
624
+
Lifetime of a ``TRB``
625
+
``````````````````````
626
+
627
+
A ``TRB`` Lifetime is simple. We are either preparing a ``TRB`` or
628
+
completing it. With these two events, we can see how a ``TRB`` changes
629
+
over 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
+
663
+
Lifetime of an Endpoint
664
+
```````````````````````
665
+
666
+
And endpoint's lifetime is summarized with enable and disable
667
+
operations, 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
+
685
+
Structures, 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