0001 ===============================================================
0002 Synopsys DesignWare Core SuperSpeed USB 3.0 Controller
0003 ===============================================================
0004
0005 :Author: Felipe Balbi <felipe.balbi@linux.intel.com>
0006 :Date: April 2017
0007
0008 Introduction
0009 ============
0010
0011 The *Synopsys DesignWare Core SuperSpeed USB 3.0 Controller*
0012 (hereinafter referred to as *DWC3*) is a USB SuperSpeed compliant
0013 controller which can be configured in one of 4 ways:
0014
0015 1. Peripheral-only configuration
0016 2. Host-only configuration
0017 3. Dual-Role configuration
0018 4. Hub configuration
0019
0020 Linux currently supports several versions of this controller. In all
0021 likelyhood, the version in your SoC is already supported. At the time
0022 of this writing, known tested versions range from 2.02a to 3.10a. As a
0023 rule of thumb, anything above 2.02a should work reliably well.
0024
0025 Currently, we have many known users for this driver. In alphabetical
0026 order:
0027
0028 1. Cavium
0029 2. Intel Corporation
0030 3. Qualcomm
0031 4. Rockchip
0032 5. ST
0033 6. Samsung
0034 7. Texas Instruments
0035 8. Xilinx
0036
0037 Summary of Features
0038 ======================
0039
0040 For details about features supported by your version of DWC3, consult
0041 your IP team and/or *Synopsys DesignWare Core SuperSpeed USB 3.0
0042 Controller Databook*. Following is a list of features supported by the
0043 driver at the time of this writing:
0044
0045 1. Up to 16 bidirectional endpoints (including the control
0046 pipe - ep0)
0047 2. Flexible endpoint configuration
0048 3. Simultaneous IN and OUT transfer support
0049 4. Scatter-list support
0050 5. Up to 256 TRBs [#trb]_ per endpoint
0051 6. Support for all transfer types (*Control*, *Bulk*,
0052 *Interrupt*, and *Isochronous*)
0053 7. SuperSpeed Bulk Streams
0054 8. Link Power Management
0055 9. Trace Events for debugging
0056 10. DebugFS [#debugfs]_ interface
0057
0058 These features have all been exercised with many of the **in-tree**
0059 gadget drivers. We have verified both *ConfigFS* [#configfs]_ and
0060 legacy gadget drivers.
0061
0062 Driver Design
0063 ==============
0064
0065 The DWC3 driver sits on the *drivers/usb/dwc3/* directory. All files
0066 related to this driver are in this one directory. This makes it easy
0067 for new-comers to read the code and understand how it behaves.
0068
0069 Because of DWC3's configuration flexibility, the driver is a little
0070 complex in some places but it should be rather straightforward to
0071 understand.
0072
0073 The biggest part of the driver refers to the Gadget API.
0074
0075 Known Limitations
0076 ===================
0077
0078 Like any other HW, DWC3 has its own set of limitations. To avoid
0079 constant questions about such problems, we decided to document them
0080 here and have a single location to where we could point users.
0081
0082 OUT Transfer Size Requirements
0083 ---------------------------------
0084
0085 According to Synopsys Databook, all OUT transfer TRBs [#trb]_ must
0086 have their *size* field set to a value which is integer divisible by
0087 the endpoint's *wMaxPacketSize*. This means that *e.g.* in order to
0088 receive a Mass Storage *CBW* [#cbw]_, req->length must either be set
0089 to a value that's divisible by *wMaxPacketSize* (1024 on SuperSpeed,
0090 512 on HighSpeed, etc), or DWC3 driver must add a Chained TRB pointing
0091 to a throw-away buffer for the remaining length. Without this, OUT
0092 transfers will **NOT** start.
0093
0094 Note that as of this writing, this won't be a problem because DWC3 is
0095 fully capable of appending a chained TRB for the remaining length and
0096 completely hide this detail from the gadget driver. It's still worth
0097 mentioning because this seems to be the largest source of queries
0098 about DWC3 and *non-working transfers*.
0099
0100 TRB Ring Size Limitation
0101 -------------------------
0102
0103 We, currently, have a hard limit of 256 TRBs [#trb]_ per endpoint,
0104 with the last TRB being a Link TRB [#link_trb]_ pointing back to the
0105 first. This limit is arbitrary but it has the benefit of adding up to
0106 exactly 4096 bytes, or 1 Page.
0107
0108 DWC3 driver will try its best to cope with more than 255 requests and,
0109 for the most part, it should work normally. However this is not
0110 something that has been exercised very frequently. If you experience
0111 any problems, see section **Reporting Bugs** below.
0112
0113 Reporting Bugs
0114 ================
0115
0116 Whenever you encounter a problem with DWC3, first and foremost you
0117 should make sure that:
0118
0119 1. You're running latest tag from `Linus' tree`_
0120 2. You can reproduce the error without any out-of-tree changes
0121 to DWC3
0122 3. You have checked that it's not a fault on the host machine
0123
0124 After all these are verified, then here's how to capture enough
0125 information so we can be of any help to you.
0126
0127 Required Information
0128 ---------------------
0129
0130 DWC3 relies exclusively on Trace Events for debugging. Everything is
0131 exposed there, with some extra bits being exposed to DebugFS
0132 [#debugfs]_.
0133
0134 In order to capture DWC3's Trace Events you should run the following
0135 commands **before** plugging the USB cable to a host machine:
0136
0137 .. code-block:: sh
0138
0139 # mkdir -p /d
0140 # mkdir -p /t
0141 # mount -t debugfs none /d
0142 # mount -t tracefs none /t
0143 # echo 81920 > /t/buffer_size_kb
0144 # echo 1 > /t/events/dwc3/enable
0145
0146 After this is done, you can connect your USB cable and reproduce the
0147 problem. As soon as the fault is reproduced, make a copy of files
0148 ``trace`` and ``regdump``, like so:
0149
0150 .. code-block:: sh
0151
0152 # cp /t/trace /root/trace.txt
0153 # cat /d/*dwc3*/regdump > /root/regdump.txt
0154
0155 Make sure to compress ``trace.txt`` and ``regdump.txt`` in a tarball
0156 and email it to `me`_ with `linux-usb`_ in Cc. If you want to be extra
0157 sure that I'll help you, write your subject line in the following
0158 format:
0159
0160 **[BUG REPORT] usb: dwc3: Bug while doing XYZ**
0161
0162 On the email body, make sure to detail what you doing, which gadget
0163 driver you were using, how to reproduce the problem, what SoC you're
0164 using, which OS (and its version) was running on the Host machine.
0165
0166 With all this information, we should be able to understand what's
0167 going on and be helpful to you.
0168
0169 Debugging
0170 ===========
0171
0172 First and foremost a disclaimer::
0173
0174 DISCLAIMER: The information available on DebugFS and/or TraceFS can
0175 change at any time at any Major Linux Kernel Release. If writing
0176 scripts, do **NOT** assume information to be available in the
0177 current format.
0178
0179 With that out of the way, let's carry on.
0180
0181 If you're willing to debug your own problem, you deserve a round of
0182 applause :-)
0183
0184 Anyway, there isn't much to say here other than Trace Events will be
0185 really helpful in figuring out issues with DWC3. Also, access to
0186 Synopsys Databook will be **really** valuable in this case.
0187
0188 A USB Sniffer can be helpful at times but it's not entirely required,
0189 there's a lot that can be understood without looking at the wire.
0190
0191 Feel free to email `me`_ and Cc `linux-usb`_ if you need any help.
0192
0193 ``DebugFS``
0194 -------------
0195
0196 ``DebugFS`` is very good for gathering snapshots of what's going on
0197 with DWC3 and/or any endpoint.
0198
0199 On DWC3's ``DebugFS`` directory, you will find the following files and
0200 directories:
0201
0202 ``ep[0..15]{in,out}/``
0203 ``link_state``
0204 ``regdump``
0205 ``testmode``
0206
0207 ``link_state``
0208 ``````````````
0209
0210 When read, ``link_state`` will print out one of ``U0``, ``U1``,
0211 ``U2``, ``U3``, ``SS.Disabled``, ``RX.Detect``, ``SS.Inactive``,
0212 ``Polling``, ``Recovery``, ``Hot Reset``, ``Compliance``,
0213 ``Loopback``, ``Reset``, ``Resume`` or ``UNKNOWN link state``.
0214
0215 This file can also be written to in order to force link to one of the
0216 states above.
0217
0218 ``regdump``
0219 `````````````
0220
0221 File name is self-explanatory. When read, ``regdump`` will print out a
0222 register dump of DWC3. Note that this file can be grepped to find the
0223 information you want.
0224
0225 ``testmode``
0226 ``````````````
0227
0228 When read, ``testmode`` will print out a name of one of the specified
0229 USB 2.0 Testmodes (``test_j``, ``test_k``, ``test_se0_nak``,
0230 ``test_packet``, ``test_force_enable``) or the string ``no test`` in
0231 case no tests are currently being executed.
0232
0233 In order to start any of these test modes, the same strings can be
0234 written to the file and DWC3 will enter the requested test mode.
0235
0236
0237 ``ep[0..15]{in,out}``
0238 ``````````````````````
0239
0240 For each endpoint we expose one directory following the naming
0241 convention ``ep$num$dir`` *(ep0in, ep0out, ep1in, ...)*. Inside each
0242 of these directories you will find the following files:
0243
0244 ``descriptor_fetch_queue``
0245 ``event_queue``
0246 ``rx_fifo_queue``
0247 ``rx_info_queue``
0248 ``rx_request_queue``
0249 ``transfer_type``
0250 ``trb_ring``
0251 ``tx_fifo_queue``
0252 ``tx_request_queue``
0253
0254 With access to Synopsys Databook, you can decode the information on
0255 them.
0256
0257 ``transfer_type``
0258 ~~~~~~~~~~~~~~~~~~
0259
0260 When read, ``transfer_type`` will print out one of ``control``,
0261 ``bulk``, ``interrupt`` or ``isochronous`` depending on what the
0262 endpoint descriptor says. If the endpoint hasn't been enabled yet, it
0263 will print ``--``.
0264
0265 ``trb_ring``
0266 ~~~~~~~~~~~~~
0267
0268 When read, ``trb_ring`` will print out details about all TRBs on the
0269 ring. It will also tell you where our enqueue and dequeue pointers are
0270 located in the ring:
0271
0272 .. code-block:: sh
0273
0274 buffer_addr,size,type,ioc,isp_imi,csp,chn,lst,hwo
0275 000000002c754000,481,normal,1,0,1,0,0,0
0276 000000002c75c000,481,normal,1,0,1,0,0,0
0277 000000002c780000,481,normal,1,0,1,0,0,0
0278 000000002c788000,481,normal,1,0,1,0,0,0
0279 000000002c78c000,481,normal,1,0,1,0,0,0
0280 000000002c754000,481,normal,1,0,1,0,0,0
0281 000000002c75c000,481,normal,1,0,1,0,0,0
0282 000000002c784000,481,normal,1,0,1,0,0,0
0283 000000002c788000,481,normal,1,0,1,0,0,0
0284 000000002c78c000,481,normal,1,0,1,0,0,0
0285 000000002c790000,481,normal,1,0,1,0,0,0
0286 000000002c758000,481,normal,1,0,1,0,0,0
0287 000000002c780000,481,normal,1,0,1,0,0,0
0288 000000002c788000,481,normal,1,0,1,0,0,0
0289 000000002c790000,481,normal,1,0,1,0,0,0
0290 000000002c758000,481,normal,1,0,1,0,0,0
0291 000000002c780000,481,normal,1,0,1,0,0,0
0292 000000002c784000,481,normal,1,0,1,0,0,0
0293 000000002c788000,481,normal,1,0,1,0,0,0
0294 000000002c78c000,481,normal,1,0,1,0,0,0
0295 000000002c754000,481,normal,1,0,1,0,0,0
0296 000000002c758000,481,normal,1,0,1,0,0,0
0297 000000002c780000,481,normal,1,0,1,0,0,0
0298 000000002c784000,481,normal,1,0,1,0,0,0
0299 000000002c78c000,481,normal,1,0,1,0,0,0
0300 000000002c790000,481,normal,1,0,1,0,0,0
0301 000000002c758000,481,normal,1,0,1,0,0,0
0302 000000002c780000,481,normal,1,0,1,0,0,0
0303 000000002c788000,481,normal,1,0,1,0,0,0
0304 000000002c790000,481,normal,1,0,1,0,0,0
0305 000000002c758000,481,normal,1,0,1,0,0,0
0306 000000002c780000,481,normal,1,0,1,0,0,0
0307 000000002c788000,481,normal,1,0,1,0,0,0
0308 000000002c790000,481,normal,1,0,1,0,0,0
0309 000000002c758000,481,normal,1,0,1,0,0,0
0310 000000002c780000,481,normal,1,0,1,0,0,0
0311 000000002c788000,481,normal,1,0,1,0,0,0
0312 000000002c790000,481,normal,1,0,1,0,0,0
0313 000000002c758000,481,normal,1,0,1,0,0,0
0314 000000002c780000,481,normal,1,0,1,0,0,0
0315 000000002c788000,481,normal,1,0,1,0,0,0
0316 000000002c790000,481,normal,1,0,1,0,0,0
0317 000000002c758000,481,normal,1,0,1,0,0,0
0318 000000002c780000,481,normal,1,0,1,0,0,0
0319 000000002c788000,481,normal,1,0,1,0,0,0
0320 000000002c790000,481,normal,1,0,1,0,0,0
0321 000000002c758000,481,normal,1,0,1,0,0,0
0322 000000002c780000,481,normal,1,0,1,0,0,0
0323 000000002c788000,481,normal,1,0,1,0,0,0
0324 000000002c790000,481,normal,1,0,1,0,0,0
0325 000000002c758000,481,normal,1,0,1,0,0,0
0326 000000002c780000,481,normal,1,0,1,0,0,0
0327 000000002c788000,481,normal,1,0,1,0,0,0
0328 000000002c790000,481,normal,1,0,1,0,0,0
0329 000000002c758000,481,normal,1,0,1,0,0,0
0330 000000002c780000,481,normal,1,0,1,0,0,0
0331 000000002c78c000,481,normal,1,0,1,0,0,0
0332 000000002c784000,481,normal,1,0,1,0,0,0
0333 000000002c788000,481,normal,1,0,1,0,0,0
0334 000000002c78c000,481,normal,1,0,1,0,0,0
0335 000000002c754000,481,normal,1,0,1,0,0,0
0336 000000002c758000,481,normal,1,0,1,0,0,0
0337 000000002c780000,481,normal,1,0,1,0,0,0
0338 000000002c788000,481,normal,1,0,1,0,0,0
0339 000000002c790000,481,normal,1,0,1,0,0,0
0340 000000002c758000,481,normal,1,0,1,0,0,0
0341 000000002c780000,481,normal,1,0,1,0,0,0
0342 000000002c758000,481,normal,1,0,1,0,0,0
0343 000000002c780000,481,normal,1,0,1,0,0,0
0344 000000002c78c000,481,normal,1,0,1,0,0,0
0345 000000002c75c000,481,normal,1,0,1,0,0,0
0346 000000002c78c000,481,normal,1,0,1,0,0,0
0347 000000002c780000,481,normal,1,0,1,0,0,0
0348 000000002c754000,481,normal,1,0,1,0,0,0
0349 000000002c788000,481,normal,1,0,1,0,0,0
0350 000000002c754000,481,normal,1,0,1,0,0,0
0351 000000002c780000,481,normal,1,0,1,0,0,0
0352 000000002c788000,481,normal,1,0,1,0,0,0
0353 000000002c78c000,481,normal,1,0,1,0,0,0
0354 000000002c790000,481,normal,1,0,1,0,0,0
0355 000000002c754000,481,normal,1,0,1,0,0,0
0356 000000002c758000,481,normal,1,0,1,0,0,0
0357 000000002c75c000,481,normal,1,0,1,0,0,0
0358 000000002c780000,481,normal,1,0,1,0,0,0
0359 000000002c784000,481,normal,1,0,1,0,0,0
0360 000000002c788000,481,normal,1,0,1,0,0,0
0361 000000002c78c000,481,normal,1,0,1,0,0,0
0362 000000002c790000,481,normal,1,0,1,0,0,0
0363 000000002c754000,481,normal,1,0,1,0,0,0
0364 000000002c758000,481,normal,1,0,1,0,0,0
0365 000000002c75c000,512,normal,1,0,1,0,0,1 D
0366 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 E
0367 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0368 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0369 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0370 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0371 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0372 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0373 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0374 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0375 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0376 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0377 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0378 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0379 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0380 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0381 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0382 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0383 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0384 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0385 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0386 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0387 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0388 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0389 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0390 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0391 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0392 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0393 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0394 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0395 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0396 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0397 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0398 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0399 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0400 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0401 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0402 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0403 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0404 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0405 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0406 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0407 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0408 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0409 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0410 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0411 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0412 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0413 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0414 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0415 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0416 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0417 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0418 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0419 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0420 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0421 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0422 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0423 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0424 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0425 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0426 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0427 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0428 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0429 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0430 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0431 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0432 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0433 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0434 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0435 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0436 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0437 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0438 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0439 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0440 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0441 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0442 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0443 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0444 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0445 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0446 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0447 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0448 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0449 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0450 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0451 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0452 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0453 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0454 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0455 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0456 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0457 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0458 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0459 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0460 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0461 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0462 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0463 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0464 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0465 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0466 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0467 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0468 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0469 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0470 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0471 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0472 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0473 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0474 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0475 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0476 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0477 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0478 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0479 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0480 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0481 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0482 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0483 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0484 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0485 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0486 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0487 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0488 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0489 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0490 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0491 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0492 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0493 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0494 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0495 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0496 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0497 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0498 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0499 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0500 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0501 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0502 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0503 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0504 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0505 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0506 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0507 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0508 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0509 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0510 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0511 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0512 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0513 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0514 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0515 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0516 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0517 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0518 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0519 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0520 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0521 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0522 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0523 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0524 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0525 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0526 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0527 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0528 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0529 0000000000000000,0,UNKNOWN,0,0,0,0,0,0
0530 00000000381ab000,0,link,0,0,0,0,0,1
0531
0532
0533 Trace Events
0534 -------------
0535
0536 DWC3 also provides several trace events which help us gathering
0537 information about the behavior of the driver during runtime.
0538
0539 In order to use these events, you must enable ``CONFIG_FTRACE`` in
0540 your kernel config.
0541
0542 For details about how enable DWC3 events, see section **Reporting
0543 Bugs**.
0544
0545 The following subsections will give details about each Event Class and
0546 each Event defined by DWC3.
0547
0548 MMIO
0549 ```````
0550
0551 It is sometimes useful to look at every MMIO access when looking for
0552 bugs. Because of that, DWC3 offers two Trace Events (one for
0553 dwc3_readl() and one for dwc3_writel()). ``TP_printk`` follows::
0554
0555 TP_printk("addr %p value %08x", __entry->base + __entry->offset,
0556 __entry->value)
0557
0558 Interrupt Events
0559 ````````````````
0560
0561 Every IRQ event can be logged and decoded into a human readable
0562 string. Because every event will be different, we don't give an
0563 example other than the ``TP_printk`` format used::
0564
0565 TP_printk("event (%08x): %s", __entry->event,
0566 dwc3_decode_event(__entry->event, __entry->ep0state))
0567
0568 Control Request
0569 `````````````````
0570
0571 Every USB Control Request can be logged to the trace buffer. The
0572 output format is::
0573
0574 TP_printk("%s", dwc3_decode_ctrl(__entry->bRequestType,
0575 __entry->bRequest, __entry->wValue,
0576 __entry->wIndex, __entry->wLength)
0577 )
0578
0579 Note that Standard Control Requests will be decoded into
0580 human-readable strings with their respective arguments. Class and
0581 Vendor requests will be printed out a sequence of 8 bytes in hex
0582 format.
0583
0584 Lifetime of a ``struct usb_request``
0585 ```````````````````````````````````````
0586
0587 The entire lifetime of a ``struct usb_request`` can be tracked on the
0588 trace buffer. We have one event for each of allocation, free,
0589 queueing, dequeueing, and giveback. Output format is::
0590
0591 TP_printk("%s: req %p length %u/%u %s%s%s ==> %d",
0592 __get_str(name), __entry->req, __entry->actual, __entry->length,
0593 __entry->zero ? "Z" : "z",
0594 __entry->short_not_ok ? "S" : "s",
0595 __entry->no_interrupt ? "i" : "I",
0596 __entry->status
0597 )
0598
0599 Generic Commands
0600 ````````````````````
0601
0602 We can log and decode every Generic Command with its completion
0603 code. Format is::
0604
0605 TP_printk("cmd '%s' [%x] param %08x --> status: %s",
0606 dwc3_gadget_generic_cmd_string(__entry->cmd),
0607 __entry->cmd, __entry->param,
0608 dwc3_gadget_generic_cmd_status_string(__entry->status)
0609 )
0610
0611 Endpoint Commands
0612 ````````````````````
0613
0614 Endpoints commands can also be logged together with completion
0615 code. Format is::
0616
0617 TP_printk("%s: cmd '%s' [%d] params %08x %08x %08x --> status: %s",
0618 __get_str(name), dwc3_gadget_ep_cmd_string(__entry->cmd),
0619 __entry->cmd, __entry->param0,
0620 __entry->param1, __entry->param2,
0621 dwc3_ep_cmd_status_string(__entry->cmd_status)
0622 )
0623
0624 Lifetime of a ``TRB``
0625 ``````````````````````
0626
0627 A ``TRB`` Lifetime is simple. We are either preparing a ``TRB`` or
0628 completing it. With these two events, we can see how a ``TRB`` changes
0629 over time. Format is::
0630
0631 TP_printk("%s: %d/%d trb %p buf %08x%08x size %s%d ctrl %08x (%c%c%c%c:%c%c:%s)",
0632 __get_str(name), __entry->queued, __entry->allocated,
0633 __entry->trb, __entry->bph, __entry->bpl,
0634 ({char *s;
0635 int pcm = ((__entry->size >> 24) & 3) + 1;
0636 switch (__entry->type) {
0637 case USB_ENDPOINT_XFER_INT:
0638 case USB_ENDPOINT_XFER_ISOC:
0639 switch (pcm) {
0640 case 1:
0641 s = "1x ";
0642 break;
0643 case 2:
0644 s = "2x ";
0645 break;
0646 case 3:
0647 s = "3x ";
0648 break;
0649 }
0650 default:
0651 s = "";
0652 } s; }),
0653 DWC3_TRB_SIZE_LENGTH(__entry->size), __entry->ctrl,
0654 __entry->ctrl & DWC3_TRB_CTRL_HWO ? 'H' : 'h',
0655 __entry->ctrl & DWC3_TRB_CTRL_LST ? 'L' : 'l',
0656 __entry->ctrl & DWC3_TRB_CTRL_CHN ? 'C' : 'c',
0657 __entry->ctrl & DWC3_TRB_CTRL_CSP ? 'S' : 's',
0658 __entry->ctrl & DWC3_TRB_CTRL_ISP_IMI ? 'S' : 's',
0659 __entry->ctrl & DWC3_TRB_CTRL_IOC ? 'C' : 'c',
0660 dwc3_trb_type_string(DWC3_TRBCTL_TYPE(__entry->ctrl))
0661 )
0662
0663 Lifetime of an Endpoint
0664 ```````````````````````
0665
0666 And endpoint's lifetime is summarized with enable and disable
0667 operations, both of which can be traced. Format is::
0668
0669 TP_printk("%s: mps %d/%d streams %d burst %d ring %d/%d flags %c:%c%c%c%c%c:%c:%c",
0670 __get_str(name), __entry->maxpacket,
0671 __entry->maxpacket_limit, __entry->max_streams,
0672 __entry->maxburst, __entry->trb_enqueue,
0673 __entry->trb_dequeue,
0674 __entry->flags & DWC3_EP_ENABLED ? 'E' : 'e',
0675 __entry->flags & DWC3_EP_STALL ? 'S' : 's',
0676 __entry->flags & DWC3_EP_WEDGE ? 'W' : 'w',
0677 __entry->flags & DWC3_EP_TRANSFER_STARTED ? 'B' : 'b',
0678 __entry->flags & DWC3_EP_PENDING_REQUEST ? 'P' : 'p',
0679 __entry->flags & DWC3_EP_END_TRANSFER_PENDING ? 'E' : 'e',
0680 __entry->direction ? '<' : '>'
0681 )
0682
0683
0684 Structures, Methods and Definitions
0685 ====================================
0686
0687 .. kernel-doc:: drivers/usb/dwc3/core.h
0688 :doc: main data structures
0689 :internal:
0690
0691 .. kernel-doc:: drivers/usb/dwc3/gadget.h
0692 :doc: gadget-only helpers
0693 :internal:
0694
0695 .. kernel-doc:: drivers/usb/dwc3/gadget.c
0696 :doc: gadget-side implementation
0697 :internal:
0698
0699 .. kernel-doc:: drivers/usb/dwc3/core.c
0700 :doc: core driver (probe, PM, etc)
0701 :internal:
0702
0703 .. [#trb] Transfer Request Block
0704 .. [#link_trb] Transfer Request Block pointing to another Transfer
0705 Request Block.
0706 .. [#debugfs] The Debug File System
0707 .. [#configfs] The Config File System
0708 .. [#cbw] Command Block Wrapper
0709 .. _Linus' tree: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/
0710 .. _me: felipe.balbi@linux.intel.com
0711 .. _linux-usb: linux-usb@vger.kernel.org
