712 lines · plain
1===============================================================2Synopsys DesignWare Core SuperSpeed USB 3.0 Controller3===============================================================4 5:Author: Felipe Balbi <felipe.balbi@linux.intel.com>6:Date: April 20177 8Introduction9============10 11The *Synopsys DesignWare Core SuperSpeed USB 3.0 Controller*12(hereinafter referred to as *DWC3*) is a USB SuperSpeed compliant13controller which can be configured in one of 4 ways:14 15 1. Peripheral-only configuration16 2. Host-only configuration17 3. Dual-Role configuration18 4. Hub configuration19 20Linux currently supports several versions of this controller. In all21likelihood, the version in your SoC is already supported. At the time22of this writing, known tested versions range from 2.02a to 3.10a. As a23rule of thumb, anything above 2.02a should work reliably well.24 25Currently, we have many known users for this driver. In alphabetical26order:27 28 1. Cavium29 2. Intel Corporation30 3. Qualcomm31 4. Rockchip32 5. ST33 6. Samsung34 7. Texas Instruments35 8. Xilinx36 37Summary of Features38======================39 40For details about features supported by your version of DWC3, consult41your IP team and/or *Synopsys DesignWare Core SuperSpeed USB 3.042Controller Databook*. Following is a list of features supported by the43driver at the time of this writing:44 45 1. Up to 16 bidirectional endpoints (including the control46 pipe - ep0)47 2. Flexible endpoint configuration48 3. Simultaneous IN and OUT transfer support49 4. Scatter-list support50 5. Up to 256 TRBs [#trb]_ per endpoint51 6. Support for all transfer types (*Control*, *Bulk*,52 *Interrupt*, and *Isochronous*)53 7. SuperSpeed Bulk Streams54 8. Link Power Management55 9. Trace Events for debugging56 10. DebugFS [#debugfs]_ interface57 58These features have all been exercised with many of the **in-tree**59gadget drivers. We have verified both *ConfigFS* [#configfs]_ and60legacy gadget drivers.61 62Driver Design63==============64 65The DWC3 driver sits on the *drivers/usb/dwc3/* directory. All files66related to this driver are in this one directory. This makes it easy67for new-comers to read the code and understand how it behaves.68 69Because of DWC3's configuration flexibility, the driver is a little70complex in some places but it should be rather straightforward to71understand.72 73The biggest part of the driver refers to the Gadget API.74 75Known Limitations76===================77 78Like any other HW, DWC3 has its own set of limitations. To avoid79constant questions about such problems, we decided to document them80here and have a single location to where we could point users.81 82OUT Transfer Size Requirements83---------------------------------84 85According to Synopsys Databook, all OUT transfer TRBs [#trb]_ must86have their *size* field set to a value which is integer divisible by87the endpoint's *wMaxPacketSize*. This means that *e.g.* in order to88receive a Mass Storage *CBW* [#cbw]_, req->length must either be set89to a value that's divisible by *wMaxPacketSize* (1024 on SuperSpeed,90512 on HighSpeed, etc), or DWC3 driver must add a Chained TRB pointing91to a throw-away buffer for the remaining length. Without this, OUT92transfers will **NOT** start.93 94Note that as of this writing, this won't be a problem because DWC3 is95fully capable of appending a chained TRB for the remaining length and96completely hide this detail from the gadget driver. It's still worth97mentioning because this seems to be the largest source of queries98about DWC3 and *non-working transfers*.99 100TRB Ring Size Limitation101-------------------------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 the105first. This limit is arbitrary but it has the benefit of adding up to106exactly 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 not110something that has been exercised very frequently. If you experience111any problems, see section **Reporting Bugs** below.112 113Reporting Bugs114================115 116Whenever you encounter a problem with DWC3, first and foremost you117should 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 changes121 to DWC3122 3. You have checked that it's not a fault on the host machine123 124After all these are verified, then here's how to capture enough125information so we can be of any help to you.126 127Required Information128---------------------129 130DWC3 relies exclusively on Trace Events for debugging. Everything is131exposed there, with some extra bits being exposed to DebugFS132[#debugfs]_.133 134In order to capture DWC3's Trace Events you should run the following135commands **before** plugging the USB cable to a host machine:136 137.. code-block:: sh138 139 # mkdir -p /d140 # mkdir -p /t141 # mount -t debugfs none /d142 # mount -t tracefs none /t143 # echo 81920 > /t/buffer_size_kb144 # echo 1 > /t/events/dwc3/enable145 146After this is done, you can connect your USB cable and reproduce the147problem. As soon as the fault is reproduced, make a copy of files148``trace`` and ``regdump``, like so:149 150.. code-block:: sh151 152 # cp /t/trace /root/trace.txt153 # cat /d/*dwc3*/regdump > /root/regdump.txt154 155Make sure to compress ``trace.txt`` and ``regdump.txt`` in a tarball156and email it to `me`_ with `linux-usb`_ in Cc. If you want to be extra157sure that I'll help you, write your subject line in the following158format:159 160 **[BUG REPORT] usb: dwc3: Bug while doing XYZ**161 162On the email body, make sure to detail what you doing, which gadget163driver you were using, how to reproduce the problem, what SoC you're164using, which OS (and its version) was running on the Host machine.165 166With all this information, we should be able to understand what's167going on and be helpful to you.168 169Debugging170===========171 172First and foremost a disclaimer::173 174 DISCLAIMER: The information available on DebugFS and/or TraceFS can175 change at any time at any Major Linux Kernel Release. If writing176 scripts, do **NOT** assume information to be available in the177 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 of182applause :-)183 184Anyway, there isn't much to say here other than Trace Events will be185really helpful in figuring out issues with DWC3. Also, access to186Synopsys 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 on197with DWC3 and/or any endpoint.198 199On DWC3's ``DebugFS`` directory, you will find the following files and200directories: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 the216states above.217 218``regdump``219`````````````220 221File name is self-explanatory. When read, ``regdump`` will print out a222register dump of DWC3. Note that this file can be grepped to find the223information you want.224 225``testmode``226``````````````227 228When read, ``testmode`` will print out a name of one of the specified229USB 2.0 Testmodes (``test_j``, ``test_k``, ``test_se0_nak``,230``test_packet``, ``test_force_enable``) or the string ``no test`` in231case no tests are currently being executed.232 233In order to start any of these test modes, the same strings can be234written 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 naming241convention ``ep$num$dir`` *(ep0in, ep0out, ep1in, ...)*. Inside each242of 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 on255them.256 257``transfer_type``258~~~~~~~~~~~~~~~~~~259 260When read, ``transfer_type`` will print out one of ``control``,261``bulk``, ``interrupt`` or ``isochronous`` depending on what the262endpoint descriptor says. If the endpoint hasn't been enabled yet, it263will print ``--``.264 265``trb_ring``266~~~~~~~~~~~~~267 268When read, ``trb_ring`` will print out details about all TRBs on the269ring. It will also tell you where our enqueue and dequeue pointers are270located in the ring:271 272.. code-block:: sh273 274 buffer_addr,size,type,ioc,isp_imi,csp,chn,lst,hwo275 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 D366 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,1531 532 533Trace Events534-------------535 536DWC3 also provides several trace events which help us gathering537information about the behavior of the driver during runtime.538 539In order to use these events, you must enable ``CONFIG_FTRACE`` in540your kernel config.541 542For details about how enable DWC3 events, see section **Reporting543Bugs**.544 545The following subsections will give details about each Event Class and546each Event defined by DWC3.547 548MMIO549```````550 551It is sometimes useful to look at every MMIO access when looking for552bugs. Because of that, DWC3 offers two Trace Events (one for553dwc3_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 Events559````````````````560 561Every IRQ event can be logged and decoded into a human readable562string. Because every event will be different, we don't give an563example 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 Request569`````````````````570 571Every USB Control Request can be logged to the trace buffer. The572output 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 into580human-readable strings with their respective arguments. Class and581Vendor requests will be printed out a sequence of 8 bytes in hex582format.583 584Lifetime of a ``struct usb_request``585```````````````````````````````````````586 587The entire lifetime of a ``struct usb_request`` can be tracked on the588trace 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->status597 )598 599Generic Commands600````````````````````601 602We can log and decode every Generic Command with its completion603code. 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 Commands612````````````````````613 614Endpoints commands can also be logged together with completion615code. 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`` or628completing it. With these two events, we can see how a ``TRB`` changes629over 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 Endpoint664```````````````````````665 666And endpoint's lifetime is summarized with enable and disable667operations, 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 Definitions685====================================686 687.. kernel-doc:: drivers/usb/dwc3/core.h688 :doc: main data structures689 :internal:690 691.. kernel-doc:: drivers/usb/dwc3/gadget.h692 :doc: gadget-only helpers693 :internal:694 695.. kernel-doc:: drivers/usb/dwc3/gadget.c696 :doc: gadget-side implementation697 :internal:698 699.. kernel-doc:: drivers/usb/dwc3/core.c700 :doc: core driver (probe, PM, etc)701 :internal:702 703.. [#trb] Transfer Request Block704.. [#link_trb] Transfer Request Block pointing to another Transfer705 Request Block.706.. [#debugfs] The Debug File System707.. [#configfs] The Config File System708.. [#cbw] Command Block Wrapper709.. _Linus' tree: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/710.. _me: felipe.balbi@linux.intel.com711.. _linux-usb: linux-usb@vger.kernel.org712