1=============================================================== 2Synopsys DesignWare Core SuperSpeed USB 3.0 Controller 3=============================================================== 4 5:Author: Felipe Balbi <felipe.balbi@linux.intel.com> 6:Date: April 2017 7 8Introduction 9============ 10 11The *Synopsys DesignWare Core SuperSpeed USB 3.0 Controller* 12(hereinafter referred to as *DWC3*) is a USB SuperSpeed compliant 13controller which can be configured in one of 4 ways: 14 15 1. Peripheral-only configuration 16 2. Host-only configuration 17 3. Dual-Role configuration 18 4. Hub configuration 19 20Linux currently supports several versions of this controller. In all 21likelyhood, the version in your SoC is already supported. At the time 22of this writing, known tested versions range from 2.02a to 3.10a. As a 23rule of thumb, anything above 2.02a should work reliably well. 24 25Currently, we have many known users for this driver. In alphabetical 26order: 27 28 1. Cavium 29 2. Intel Corporation 30 3. Qualcomm 31 4. Rockchip 32 5. ST 33 6. Samsung 34 7. Texas Instruments 35 8. Xilinx 36 37Summary of Features 38====================== 39 40For details about features supported by your version of DWC3, consult 41your IP team and/or *Synopsys DesignWare Core SuperSpeed USB 3.0 42Controller Databook*. Following is a list of features supported by the 43driver at the time of this writing: 44 45 1. Up to 16 bidirectional endpoints (including the control 46 pipe - ep0) 47 2. Flexible endpoint configuration 48 3. Simultaneous IN and OUT transfer support 49 4. Scatter-list support 50 5. Up to 256 TRBs [#trb]_ per endpoint 51 6. Support for all transfer types (*Control*, *Bulk*, 52 *Interrupt*, and *Isochronous*) 53 7. SuperSpeed Bulk Streams 54 8. Link Power Management 55 9. Trace Events for debugging 56 10. DebugFS [#debugfs]_ interface 57 58These features have all been exercised with many of the **in-tree** 59gadget drivers. We have verified both *ConfigFS* [#configfs]_ and 60legacy gadget drivers. 61 62Driver Design 63============== 64 65The DWC3 driver sits on the *drivers/usb/dwc3/* directory. All files 66related to this driver are in this one directory. This makes it easy 67for new-comers to read the code and understand how it behaves. 68 69Because of DWC3's configuration flexibility, the driver is a little 70complex in some places but it should be rather straightforward to 71understand. 72 73The biggest part of the driver refers to the Gadget API. 74 75Known Limitations 76=================== 77 78Like any other HW, DWC3 has its own set of limitations. To avoid 79constant questions about such problems, we decided to document them 80here and have a single location to where we could point users. 81 82OUT Transfer Size Requirements 83--------------------------------- 84 85According to Synopsys Databook, all OUT transfer TRBs [#trb]_ must 86have their *size* field set to a value which is integer divisible by 87the endpoint's *wMaxPacketSize*. This means that *e.g.* in order to 88receive a Mass Storage *CBW* [#cbw]_, req->length must either be set 89to a value that's divisible by *wMaxPacketSize* (1024 on SuperSpeed, 90512 on HighSpeed, etc), or DWC3 driver must add a Chained TRB pointing 91to a throw-away buffer for the remaining length. Without this, OUT 92transfers will **NOT** start. 93 94Note that as of this writing, this won't be a problem because DWC3 is 95fully capable of appending a chained TRB for the remaining length and 96completely hide this detail from the gadget driver. It's still worth 97mentioning because this seems to be the largest source of queries 98about DWC3 and *non-working transfers*. 99 100TRB Ring Size Limitation 101------------------------- 102 103We, currently, have a hard limit of 256 TRBs [#trb]_ per endpoint, 104with the last TRB being a Link TRB [#link_trb]_ pointing back to the 105first. This limit is arbitrary but it has the benefit of adding up to 106exactly 4096 bytes, or 1 Page. 107 108DWC3 driver will try its best to cope with more than 255 requests and, 109for the most part, it should work normally. However this is not 110something that has been exercised very frequently. If you experience 111any problems, see section **Reporting Bugs** below. 112 113Reporting Bugs 114================ 115 116Whenever you encounter a problem with DWC3, first and foremost you 117should make sure that: 118 119 1. You're running latest tag from `Linus' tree`_ 120 2. You can reproduce the error without any out-of-tree changes 121 to DWC3 122 3. You have checked that it's not a fault on the host machine 123 124After all these are verified, then here's how to capture enough 125information so we can be of any help to you. 126 127Required Information 128--------------------- 129 130DWC3 relies exclusively on Trace Events for debugging. Everything is 131exposed there, with some extra bits being exposed to DebugFS 132[#debugfs]_. 133 134In order to capture DWC3's Trace Events you should run the following 135commands **before** plugging the USB cable to a host machine: 136 137.. code-block:: sh 138 139 # mkdir -p /d 140 # mkdir -p /t 141 # mount -t debugfs none /d 142 # mount -t tracefs none /t 143 # echo 81920 > /t/buffer_size_kb 144 # echo 1 > /t/events/dwc3/enable 145 146After this is done, you can connect your USB cable and reproduce the 147problem. As soon as the fault is reproduced, make a copy of files 148``trace`` and ``regdump``, like so: 149 150.. code-block:: sh 151 152 # cp /t/trace /root/trace.txt 153 # cat /d/*dwc3*/regdump > /root/regdump.txt 154 155Make sure to compress ``trace.txt`` and ``regdump.txt`` in a tarball 156and email it to `me`_ with `linux-usb`_ in Cc. If you want to be extra 157sure that I'll help you, write your subject line in the following 158format: 159 160 **[BUG REPORT] usb: dwc3: Bug while doing XYZ** 161 162On the email body, make sure to detail what you doing, which gadget 163driver you were using, how to reproduce the problem, what SoC you're 164using, which OS (and its version) was running on the Host machine. 165 166With all this information, we should be able to understand what's 167going on and be helpful to you. 168 169Debugging 170=========== 171 172First and foremost a disclaimer:: 173 174 DISCLAIMER: The information available on DebugFS and/or TraceFS can 175 change at any time at any Major Linux Kernel Release. If writing 176 scripts, do **NOT** assume information to be available in the 177 current format. 178 179With that out of the way, let's carry on. 180 181If you're willing to debug your own problem, you deserve a round of 182applause :-) 183 184Anyway, there isn't much to say here other than Trace Events will be 185really helpful in figuring out issues with DWC3. Also, access to 186Synopsys Databook will be **really** valuable in this case. 187 188A USB Sniffer can be helpful at times but it's not entirely required, 189there's a lot that can be understood without looking at the wire. 190 191Feel free to email `me`_ and Cc `linux-usb`_ if you need any help. 192 193``DebugFS`` 194------------- 195 196``DebugFS`` is very good for gathering snapshots of what's going on 197with DWC3 and/or any endpoint. 198 199On DWC3's ``DebugFS`` directory, you will find the following files and 200directories: 201 202``ep[0..15]{in,out}/`` 203``link_state`` 204``regdump`` 205``testmode`` 206 207``link_state`` 208`````````````` 209 210When read, ``link_state`` will print out one of ``U0``, ``U1``, 211``U2``, ``U3``, ``SS.Disabled``, ``RX.Detect``, ``SS.Inactive``, 212``Polling``, ``Recovery``, ``Hot Reset``, ``Compliance``, 213``Loopback``, ``Reset``, ``Resume`` or ``UNKNOWN link state``. 214 215This file can also be written to in order to force link to one of the 216states above. 217 218``regdump`` 219````````````` 220 221File name is self-explanatory. When read, ``regdump`` will print out a 222register dump of DWC3. Note that this file can be grepped to find the 223information you want. 224 225``testmode`` 226`````````````` 227 228When read, ``testmode`` will print out a name of one of the specified 229USB 2.0 Testmodes (``test_j``, ``test_k``, ``test_se0_nak``, 230``test_packet``, ``test_force_enable``) or the string ``no test`` in 231case no tests are currently being executed. 232 233In order to start any of these test modes, the same strings can be 234written to the file and DWC3 will enter the requested test mode. 235 236 237``ep[0..15]{in,out}`` 238`````````````````````` 239 240For each endpoint we expose one directory following the naming 241convention ``ep$num$dir`` *(ep0in, ep0out, ep1in, ...)*. Inside each 242of these directories you will find the following files: 243 244``descriptor_fetch_queue`` 245``event_queue`` 246``rx_fifo_queue`` 247``rx_info_queue`` 248``rx_request_queue`` 249``transfer_type`` 250``trb_ring`` 251``tx_fifo_queue`` 252``tx_request_queue`` 253 254With access to Synopsys Databook, you can decode the information on 255them. 256 257``transfer_type`` 258~~~~~~~~~~~~~~~~~~ 259 260When read, ``transfer_type`` will print out one of ``control``, 261``bulk``, ``interrupt`` or ``isochronous`` depending on what the 262endpoint descriptor says. If the endpoint hasn't been enabled yet, it 263will print ``--``. 264 265``trb_ring`` 266~~~~~~~~~~~~~ 267 268When read, ``trb_ring`` will print out details about all TRBs on the 269ring. It will also tell you where our enqueue and dequeue pointers are 270located in the ring: 271 272.. code-block:: sh 273 274 buffer_addr,size,type,ioc,isp_imi,csp,chn,lst,hwo 275 000000002c754000,481,normal,1,0,1,0,0,0 276 000000002c75c000,481,normal,1,0,1,0,0,0 277 000000002c780000,481,normal,1,0,1,0,0,0 278 000000002c788000,481,normal,1,0,1,0,0,0 279 000000002c78c000,481,normal,1,0,1,0,0,0 280 000000002c754000,481,normal,1,0,1,0,0,0 281 000000002c75c000,481,normal,1,0,1,0,0,0 282 000000002c784000,481,normal,1,0,1,0,0,0 283 000000002c788000,481,normal,1,0,1,0,0,0 284 000000002c78c000,481,normal,1,0,1,0,0,0 285 000000002c790000,481,normal,1,0,1,0,0,0 286 000000002c758000,481,normal,1,0,1,0,0,0 287 000000002c780000,481,normal,1,0,1,0,0,0 288 000000002c788000,481,normal,1,0,1,0,0,0 289 000000002c790000,481,normal,1,0,1,0,0,0 290 000000002c758000,481,normal,1,0,1,0,0,0 291 000000002c780000,481,normal,1,0,1,0,0,0 292 000000002c784000,481,normal,1,0,1,0,0,0 293 000000002c788000,481,normal,1,0,1,0,0,0 294 000000002c78c000,481,normal,1,0,1,0,0,0 295 000000002c754000,481,normal,1,0,1,0,0,0 296 000000002c758000,481,normal,1,0,1,0,0,0 297 000000002c780000,481,normal,1,0,1,0,0,0 298 000000002c784000,481,normal,1,0,1,0,0,0 299 000000002c78c000,481,normal,1,0,1,0,0,0 300 000000002c790000,481,normal,1,0,1,0,0,0 301 000000002c758000,481,normal,1,0,1,0,0,0 302 000000002c780000,481,normal,1,0,1,0,0,0 303 000000002c788000,481,normal,1,0,1,0,0,0 304 000000002c790000,481,normal,1,0,1,0,0,0 305 000000002c758000,481,normal,1,0,1,0,0,0 306 000000002c780000,481,normal,1,0,1,0,0,0 307 000000002c788000,481,normal,1,0,1,0,0,0 308 000000002c790000,481,normal,1,0,1,0,0,0 309 000000002c758000,481,normal,1,0,1,0,0,0 310 000000002c780000,481,normal,1,0,1,0,0,0 311 000000002c788000,481,normal,1,0,1,0,0,0 312 000000002c790000,481,normal,1,0,1,0,0,0 313 000000002c758000,481,normal,1,0,1,0,0,0 314 000000002c780000,481,normal,1,0,1,0,0,0 315 000000002c788000,481,normal,1,0,1,0,0,0 316 000000002c790000,481,normal,1,0,1,0,0,0 317 000000002c758000,481,normal,1,0,1,0,0,0 318 000000002c780000,481,normal,1,0,1,0,0,0 319 000000002c788000,481,normal,1,0,1,0,0,0 320 000000002c790000,481,normal,1,0,1,0,0,0 321 000000002c758000,481,normal,1,0,1,0,0,0 322 000000002c780000,481,normal,1,0,1,0,0,0 323 000000002c788000,481,normal,1,0,1,0,0,0 324 000000002c790000,481,normal,1,0,1,0,0,0 325 000000002c758000,481,normal,1,0,1,0,0,0 326 000000002c780000,481,normal,1,0,1,0,0,0 327 000000002c788000,481,normal,1,0,1,0,0,0 328 000000002c790000,481,normal,1,0,1,0,0,0 329 000000002c758000,481,normal,1,0,1,0,0,0 330 000000002c780000,481,normal,1,0,1,0,0,0 331 000000002c78c000,481,normal,1,0,1,0,0,0 332 000000002c784000,481,normal,1,0,1,0,0,0 333 000000002c788000,481,normal,1,0,1,0,0,0 334 000000002c78c000,481,normal,1,0,1,0,0,0 335 000000002c754000,481,normal,1,0,1,0,0,0 336 000000002c758000,481,normal,1,0,1,0,0,0 337 000000002c780000,481,normal,1,0,1,0,0,0 338 000000002c788000,481,normal,1,0,1,0,0,0 339 000000002c790000,481,normal,1,0,1,0,0,0 340 000000002c758000,481,normal,1,0,1,0,0,0 341 000000002c780000,481,normal,1,0,1,0,0,0 342 000000002c758000,481,normal,1,0,1,0,0,0 343 000000002c780000,481,normal,1,0,1,0,0,0 344 000000002c78c000,481,normal,1,0,1,0,0,0 345 000000002c75c000,481,normal,1,0,1,0,0,0 346 000000002c78c000,481,normal,1,0,1,0,0,0 347 000000002c780000,481,normal,1,0,1,0,0,0 348 000000002c754000,481,normal,1,0,1,0,0,0 349 000000002c788000,481,normal,1,0,1,0,0,0 350 000000002c754000,481,normal,1,0,1,0,0,0 351 000000002c780000,481,normal,1,0,1,0,0,0 352 000000002c788000,481,normal,1,0,1,0,0,0 353 000000002c78c000,481,normal,1,0,1,0,0,0 354 000000002c790000,481,normal,1,0,1,0,0,0 355 000000002c754000,481,normal,1,0,1,0,0,0 356 000000002c758000,481,normal,1,0,1,0,0,0 357 000000002c75c000,481,normal,1,0,1,0,0,0 358 000000002c780000,481,normal,1,0,1,0,0,0 359 000000002c784000,481,normal,1,0,1,0,0,0 360 000000002c788000,481,normal,1,0,1,0,0,0 361 000000002c78c000,481,normal,1,0,1,0,0,0 362 000000002c790000,481,normal,1,0,1,0,0,0 363 000000002c754000,481,normal,1,0,1,0,0,0 364 000000002c758000,481,normal,1,0,1,0,0,0 365 000000002c75c000,512,normal,1,0,1,0,0,1 D 366 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 E 367 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 368 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 369 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 370 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 371 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 372 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 373 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 374 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 375 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 376 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 377 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 378 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 379 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 380 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 381 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 382 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 383 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 384 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 385 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 386 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 387 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 388 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 389 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 390 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 391 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 392 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 393 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 394 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 395 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 396 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 397 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 398 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 399 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 400 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 401 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 402 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 403 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 404 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 405 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 406 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 407 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 408 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 409 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 410 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 411 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 412 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 413 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 414 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 415 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 416 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 417 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 418 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 419 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 420 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 421 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 422 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 423 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 424 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 425 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 426 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 427 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 428 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 429 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 430 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 431 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 432 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 433 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 434 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 435 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 436 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 437 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 438 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 439 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 440 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 441 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 442 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 443 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 444 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 445 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 446 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 447 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 448 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 449 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 450 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 451 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 452 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 453 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 454 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 455 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 456 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 457 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 458 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 459 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 460 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 461 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 462 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 463 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 464 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 465 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 466 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 467 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 468 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 469 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 470 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 471 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 472 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 473 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 474 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 475 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 476 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 477 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 478 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 479 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 480 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 481 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 482 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 483 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 484 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 485 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 486 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 487 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 488 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 489 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 490 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 491 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 492 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 493 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 494 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 495 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 496 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 497 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 498 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 499 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 500 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 501 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 502 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 503 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 504 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 505 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 506 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 507 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 508 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 509 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 510 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 511 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 512 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 513 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 514 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 515 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 516 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 517 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 518 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 519 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 520 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 521 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 522 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 523 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 524 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 525 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 526 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 527 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 528 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 529 0000000000000000,0,UNKNOWN,0,0,0,0,0,0 530 00000000381ab000,0,link,0,0,0,0,0,1 531 532 533Trace Events 534------------- 535 536DWC3 also provides several trace events which help us gathering 537information about the behavior of the driver during runtime. 538 539In order to use these events, you must enable ``CONFIG_FTRACE`` in 540your kernel config. 541 542For details about how enable DWC3 events, see section **Reporting 543Bugs**. 544 545The following subsections will give details about each Event Class and 546each Event defined by DWC3. 547 548MMIO 549``````` 550 551It is sometimes useful to look at every MMIO access when looking for 552bugs. Because of that, DWC3 offers two Trace Events (one for 553dwc3_readl() and one for dwc3_writel()). ``TP_printk`` follows:: 554 555 TP_printk("addr %p value %08x", __entry->base + __entry->offset, 556 __entry->value) 557 558Interrupt Events 559```````````````` 560 561Every IRQ event can be logged and decoded into a human readable 562string. Because every event will be different, we don't give an 563example other than the ``TP_printk`` format used:: 564 565 TP_printk("event (%08x): %s", __entry->event, 566 dwc3_decode_event(__entry->event, __entry->ep0state)) 567 568Control Request 569````````````````` 570 571Every USB Control Request can be logged to the trace buffer. The 572output format is:: 573 574 TP_printk("%s", dwc3_decode_ctrl(__entry->bRequestType, 575 __entry->bRequest, __entry->wValue, 576 __entry->wIndex, __entry->wLength) 577 ) 578 579Note that Standard Control Requests will be decoded into 580human-readable strings with their respective arguments. Class and 581Vendor requests will be printed out a sequence of 8 bytes in hex 582format. 583 584Lifetime of a ``struct usb_request`` 585``````````````````````````````````````` 586 587The entire lifetime of a ``struct usb_request`` can be tracked on the 588trace buffer. We have one event for each of allocation, free, 589queueing, dequeueing, and giveback. Output format is:: 590 591 TP_printk("%s: req %p length %u/%u %s%s%s ==> %d", 592 __get_str(name), __entry->req, __entry->actual, __entry->length, 593 __entry->zero ? "Z" : "z", 594 __entry->short_not_ok ? "S" : "s", 595 __entry->no_interrupt ? "i" : "I", 596 __entry->status 597 ) 598 599Generic Commands 600```````````````````` 601 602We can log and decode every Generic Command with its completion 603code. Format is:: 604 605 TP_printk("cmd '%s' [%x] param %08x --> status: %s", 606 dwc3_gadget_generic_cmd_string(__entry->cmd), 607 __entry->cmd, __entry->param, 608 dwc3_gadget_generic_cmd_status_string(__entry->status) 609 ) 610 611Endpoint Commands 612```````````````````` 613 614Endpoints commands can also be logged together with completion 615code. Format is:: 616 617 TP_printk("%s: cmd '%s' [%d] params %08x %08x %08x --> status: %s", 618 __get_str(name), dwc3_gadget_ep_cmd_string(__entry->cmd), 619 __entry->cmd, __entry->param0, 620 __entry->param1, __entry->param2, 621 dwc3_ep_cmd_status_string(__entry->cmd_status) 622 ) 623 624Lifetime of a ``TRB`` 625`````````````````````` 626 627A ``TRB`` Lifetime is simple. We are either preparing a ``TRB`` or 628completing it. With these two events, we can see how a ``TRB`` changes 629over time. Format is:: 630 631 TP_printk("%s: %d/%d trb %p buf %08x%08x size %s%d ctrl %08x (%c%c%c%c:%c%c:%s)", 632 __get_str(name), __entry->queued, __entry->allocated, 633 __entry->trb, __entry->bph, __entry->bpl, 634 ({char *s; 635 int pcm = ((__entry->size >> 24) & 3) + 1; 636 switch (__entry->type) { 637 case USB_ENDPOINT_XFER_INT: 638 case USB_ENDPOINT_XFER_ISOC: 639 switch (pcm) { 640 case 1: 641 s = "1x "; 642 break; 643 case 2: 644 s = "2x "; 645 break; 646 case 3: 647 s = "3x "; 648 break; 649 } 650 default: 651 s = ""; 652 } s; }), 653 DWC3_TRB_SIZE_LENGTH(__entry->size), __entry->ctrl, 654 __entry->ctrl & DWC3_TRB_CTRL_HWO ? 'H' : 'h', 655 __entry->ctrl & DWC3_TRB_CTRL_LST ? 'L' : 'l', 656 __entry->ctrl & DWC3_TRB_CTRL_CHN ? 'C' : 'c', 657 __entry->ctrl & DWC3_TRB_CTRL_CSP ? 'S' : 's', 658 __entry->ctrl & DWC3_TRB_CTRL_ISP_IMI ? 'S' : 's', 659 __entry->ctrl & DWC3_TRB_CTRL_IOC ? 'C' : 'c', 660 dwc3_trb_type_string(DWC3_TRBCTL_TYPE(__entry->ctrl)) 661 ) 662 663Lifetime of an Endpoint 664``````````````````````` 665 666And endpoint's lifetime is summarized with enable and disable 667operations, both of which can be traced. Format is:: 668 669 TP_printk("%s: mps %d/%d streams %d burst %d ring %d/%d flags %c:%c%c%c%c%c:%c:%c", 670 __get_str(name), __entry->maxpacket, 671 __entry->maxpacket_limit, __entry->max_streams, 672 __entry->maxburst, __entry->trb_enqueue, 673 __entry->trb_dequeue, 674 __entry->flags & DWC3_EP_ENABLED ? 'E' : 'e', 675 __entry->flags & DWC3_EP_STALL ? 'S' : 's', 676 __entry->flags & DWC3_EP_WEDGE ? 'W' : 'w', 677 __entry->flags & DWC3_EP_TRANSFER_STARTED ? 'B' : 'b', 678 __entry->flags & DWC3_EP_PENDING_REQUEST ? 'P' : 'p', 679 __entry->flags & DWC3_EP_END_TRANSFER_PENDING ? 'E' : 'e', 680 __entry->direction ? '<' : '>' 681 ) 682 683 684Structures, Methods and Definitions 685==================================== 686 687.. kernel-doc:: drivers/usb/dwc3/core.h 688 :doc: main data structures 689 :internal: 690 691.. kernel-doc:: drivers/usb/dwc3/gadget.h 692 :doc: gadget-only helpers 693 :internal: 694 695.. kernel-doc:: drivers/usb/dwc3/gadget.c 696 :doc: gadget-side implementation 697 :internal: 698 699.. kernel-doc:: drivers/usb/dwc3/core.c 700 :doc: core driver (probe, PM, etc) 701 :internal: 702 703.. [#trb] Transfer Request Block 704.. [#link_trb] Transfer Request Block pointing to another Transfer 705 Request Block. 706.. [#debugfs] The Debug File System 707.. [#configfs] The Config File System 708.. [#cbw] Command Block Wrapper 709.. _Linus' tree: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/ 710.. _me: felipe.balbi@linux.intel.com 711.. _linux-usb: linux-usb@vger.kernel.org 712