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_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
 684 Structures, 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