===============================================================
Synopsys DesignWare Core SuperSpeed USB 3.0 Controller
===============================================================

:Author: Felipe Balbi <felipe.balbi@linux.intel.com>
:Date: April 2017

Introduction
============

The *Synopsys DesignWare Core SuperSpeed USB 3.0 Controller*
(hereinafter referred to as *DWC3*) is a USB SuperSpeed compliant
controller which can be configured in one of 4 ways:

	1. Peripheral-only configuration
	2. Host-only configuration
	3. Dual-Role configuration
	4. Hub configuration

Linux currently supports several versions of this controller. In all
likelyhood, the version in your SoC is already supported. At the time
of this writing, known tested versions range from 2.02a to 3.10a. As a
rule of thumb, anything above 2.02a should work reliably well.

Currently, we have many known users for this driver. In alphabetical
order:

	1. Cavium
	2. Intel Corporation
	3. Qualcomm
	4. Rockchip
	5. ST
	6. Samsung
	7. Texas Instruments
	8. Xilinx

Summary of Features
======================

For details about features supported by your version of DWC3, consult
your IP team and/or *Synopsys DesignWare Core SuperSpeed USB 3.0
Controller Databook*. Following is a list of features supported by the
driver at the time of this writing:

	1. Up to 16 bidirectional endpoints (including the control
	   pipe - ep0)
	2. Flexible endpoint configuration
	3. Simultaneous IN and OUT transfer support
	4. Scatter-list support
	5. Up to 256 TRBs [#trb]_ per endpoint
	6. Support for all transfer types (*Control*, *Bulk*,
	   *Interrupt*, and *Isochronous*)
	7. SuperSpeed Bulk Streams
	8. Link Power Management
	9. Trace Events for debugging
	10. DebugFS [#debugfs]_ interface

These features have all been exercised with many of the **in-tree**
gadget drivers. We have verified both *ConfigFS* [#configfs]_ and
legacy gadget drivers.

Driver Design
==============

The DWC3 driver sits on the *drivers/usb/dwc3/* directory. All files
related to this driver are in this one directory. This makes it easy
for new-comers to read the code and understand how it behaves.

Because of DWC3's configuration flexibility, the driver is a little
complex in some places but it should be rather straightforward to
understand.

The biggest part of the driver refers to the Gadget API.

Known Limitations
===================

Like any other HW, DWC3 has its own set of limitations. To avoid
constant questions about such problems, we decided to document them
here and have a single location to where we could point users.

OUT Transfer Size Requirements
---------------------------------

According to Synopsys Databook, all OUT transfer TRBs [#trb]_ must
have their *size* field set to a value which is integer divisible by
the endpoint's *wMaxPacketSize*. This means that *e.g.* in order to
receive a Mass Storage *CBW* [#cbw]_, req->length must either be set
to a value that's divisible by *wMaxPacketSize* (1024 on SuperSpeed,
512 on HighSpeed, etc), or DWC3 driver must add a Chained TRB pointing
to a throw-away buffer for the remaining length. Without this, OUT
transfers will **NOT** start.

Note that as of this writing, this won't be a problem because DWC3 is
fully capable of appending a chained TRB for the remaining length and
completely hide this detail from the gadget driver. It's still worth
mentioning because this seems to be the largest source of queries
about DWC3 and *non-working transfers*.

TRB Ring Size Limitation
-------------------------

We, currently, have a hard limit of 256 TRBs [#trb]_ per endpoint,
with the last TRB being a Link TRB [#link_trb]_ pointing back to the
first. This limit is arbitrary but it has the benefit of adding up to
exactly 4096 bytes, or 1 Page.

DWC3 driver will try its best to cope with more than 255 requests and,
for the most part, it should work normally. However this is not
something that has been exercised very frequently. If you experience
any problems, see section **Reporting Bugs** below.

Reporting Bugs
================

Whenever you encounter a problem with DWC3, first and foremost you
should make sure that:

	1. You're running latest tag from `Linus' tree`_
	2. You can reproduce the error without any out-of-tree changes
	   to DWC3
	3. You have checked that it's not a fault on the host machine

After all these are verified, then here's how to capture enough
information so we can be of any help to you.

Required Information
---------------------

DWC3 relies exclusively on Trace Events for debugging. Everything is
exposed there, with some extra bits being exposed to DebugFS
[#debugfs]_.

In order to capture DWC3's Trace Events you should run the following
commands **before** plugging the USB cable to a host machine:

.. code-block:: sh

		 # mkdir -p /d
		 # mkdir -p /t
		 # mount -t debugfs none /d
		 # mount -t tracefs none /t
		 # echo 81920 > /t/buffer_size_kb
		 # echo 1 > /t/events/dwc3/enable

After this is done, you can connect your USB cable and reproduce the
problem. As soon as the fault is reproduced, make a copy of files
``trace`` and ``regdump``, like so:

.. code-block:: sh

		# cp /t/trace /root/trace.txt
		# cat /d/*dwc3*/regdump > /root/regdump.txt

Make sure to compress ``trace.txt`` and ``regdump.txt`` in a tarball
and email it to `me`_ with `linux-usb`_ in Cc. If you want to be extra
sure that I'll help you, write your subject line in the following
format:

	**[BUG REPORT] usb: dwc3: Bug while doing XYZ**

On the email body, make sure to detail what you doing, which gadget
driver you were using, how to reproduce the problem, what SoC you're
using, which OS (and its version) was running on the Host machine.

With all this information, we should be able to understand what's
going on and be helpful to you.

Debugging
===========

First and foremost a disclaimer::

  DISCLAIMER: The information available on DebugFS and/or TraceFS can
  change at any time at any Major Linux Kernel Release. If writing
  scripts, do **NOT** assume information to be available in the
  current format.

With that out of the way, let's carry on.

If you're willing to debug your own problem, you deserve a round of
applause :-)

Anyway, there isn't much to say here other than Trace Events will be
really helpful in figuring out issues with DWC3. Also, access to
Synopsys Databook will be **really** valuable in this case.

A USB Sniffer can be helpful at times but it's not entirely required,
there's a lot that can be understood without looking at the wire.

Feel free to email `me`_ and Cc `linux-usb`_ if you need any help.

``DebugFS``
-------------

``DebugFS`` is very good for gathering snapshots of what's going on
with DWC3 and/or any endpoint.

On DWC3's ``DebugFS`` directory, you will find the following files and
directories:

``ep[0..15]{in,out}/``
``link_state``
``regdump``
``testmode``

``link_state``
``````````````

When read, ``link_state`` will print out one of ``U0``, ``U1``,
``U2``, ``U3``, ``SS.Disabled``, ``RX.Detect``, ``SS.Inactive``,
``Polling``, ``Recovery``, ``Hot Reset``, ``Compliance``,
``Loopback``, ``Reset``, ``Resume`` or ``UNKNOWN link state``.

This file can also be written to in order to force link to one of the
states above.

``regdump``
`````````````

File name is self-explanatory. When read, ``regdump`` will print out a
register dump of DWC3. Note that this file can be grepped to find the
information you want.

``testmode``
``````````````

When read, ``testmode`` will print out a name of one of the specified
USB 2.0 Testmodes (``test_j``, ``test_k``, ``test_se0_nak``,
``test_packet``, ``test_force_enable``) or the string ``no test`` in
case no tests are currently being executed.

In order to start any of these test modes, the same strings can be
written to the file and DWC3 will enter the requested test mode.


``ep[0..15]{in,out}``
``````````````````````

For each endpoint we expose one directory following the naming
convention ``ep$num$dir`` *(ep0in, ep0out, ep1in, ...)*. Inside each
of these directories you will find the following files:

``descriptor_fetch_queue``
``event_queue``
``rx_fifo_queue``
``rx_info_queue``
``rx_request_queue``
``transfer_type``
``trb_ring``
``tx_fifo_queue``
``tx_request_queue``

With access to Synopsys Databook, you can decode the information on
them.

``transfer_type``
~~~~~~~~~~~~~~~~~~

When read, ``transfer_type`` will print out one of ``control``,
``bulk``, ``interrupt`` or ``isochronous`` depending on what the
endpoint descriptor says. If the endpoint hasn't been enabled yet, it
will print ``--``.

``trb_ring``
~~~~~~~~~~~~~

When read, ``trb_ring`` will print out details about all TRBs on the
ring. It will also tell you where our enqueue and dequeue pointers are
located in the ring:

.. code-block:: sh
   
		buffer_addr,size,type,ioc,isp_imi,csp,chn,lst,hwo
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c75c000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c75c000,481,normal,1,0,1,0,0,0         
		000000002c784000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c784000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c784000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c784000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c75c000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c75c000,481,normal,1,0,1,0,0,0         
		000000002c780000,481,normal,1,0,1,0,0,0         
		000000002c784000,481,normal,1,0,1,0,0,0         
		000000002c788000,481,normal,1,0,1,0,0,0         
		000000002c78c000,481,normal,1,0,1,0,0,0         
		000000002c790000,481,normal,1,0,1,0,0,0         
		000000002c754000,481,normal,1,0,1,0,0,0         
		000000002c758000,481,normal,1,0,1,0,0,0         
		000000002c75c000,512,normal,1,0,1,0,0,1        D
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0       E 
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		0000000000000000,0,UNKNOWN,0,0,0,0,0,0         
		00000000381ab000,0,link,0,0,0,0,0,1


Trace Events
-------------

DWC3 also provides several trace events which help us gathering
information about the behavior of the driver during runtime.

In order to use these events, you must enable ``CONFIG_FTRACE`` in
your kernel config.

For details about how enable DWC3 events, see section **Reporting
Bugs**.

The following subsections will give details about each Event Class and
each Event defined by DWC3.

MMIO
```````

It is sometimes useful to look at every MMIO access when looking for
bugs. Because of that, DWC3 offers two Trace Events (one for
dwc3_readl() and one for dwc3_writel()). ``TP_printk`` follows::

  TP_printk("addr %p value %08x", __entry->base + __entry->offset,
  		__entry->value)

Interrupt Events
````````````````

Every IRQ event can be logged and decoded into a human readable
string. Because every event will be different, we don't give an
example other than the ``TP_printk`` format used::

  TP_printk("event (%08x): %s", __entry->event,
  		dwc3_decode_event(__entry->event, __entry->ep0state))

Control Request
`````````````````

Every USB Control Request can be logged to the trace buffer. The
output format is::

  TP_printk("%s", dwc3_decode_ctrl(__entry->bRequestType,
  				__entry->bRequest, __entry->wValue,
  				__entry->wIndex, __entry->wLength)
  )

Note that Standard Control Requests will be decoded into
human-readable strings with their respective arguments. Class and
Vendor requests will be printed out a sequence of 8 bytes in hex
format.

Lifetime of a ``struct usb_request``
```````````````````````````````````````

The entire lifetime of a ``struct usb_request`` can be tracked on the
trace buffer. We have one event for each of allocation, free,
queueing, dequeueing, and giveback. Output format is::

  TP_printk("%s: req %p length %u/%u %s%s%s ==> %d",
  	__get_str(name), __entry->req, __entry->actual, __entry->length,
  	__entry->zero ? "Z" : "z",
  	__entry->short_not_ok ? "S" : "s",
  	__entry->no_interrupt ? "i" : "I",
  	__entry->status
  )

Generic Commands
````````````````````

We can log and decode every Generic Command with its completion
code. Format is::

  TP_printk("cmd '%s' [%x] param %08x --> status: %s",
  	dwc3_gadget_generic_cmd_string(__entry->cmd),
  	__entry->cmd, __entry->param,
  	dwc3_gadget_generic_cmd_status_string(__entry->status)
  )

Endpoint Commands
````````````````````

Endpoints commands can also be logged together with completion
code. Format is::

  TP_printk("%s: cmd '%s' [%d] params %08x %08x %08x --> status: %s",
  	__get_str(name), dwc3_gadget_ep_cmd_string(__entry->cmd),
  	__entry->cmd, __entry->param0,
  	__entry->param1, __entry->param2,
  	dwc3_ep_cmd_status_string(__entry->cmd_status)
  )

Lifetime of a ``TRB``
``````````````````````

A ``TRB`` Lifetime is simple. We are either preparing a ``TRB`` or
completing it. With these two events, we can see how a ``TRB`` changes
over time. Format is::

  TP_printk("%s: %d/%d trb %p buf %08x%08x size %s%d ctrl %08x (%c%c%c%c:%c%c:%s)",
  	__get_str(name), __entry->queued, __entry->allocated,
  	__entry->trb, __entry->bph, __entry->bpl,
  	({char *s;
  	int pcm = ((__entry->size >> 24) & 3) + 1;
  	switch (__entry->type) {
  	case USB_ENDPOINT_XFER_INT:
  	case USB_ENDPOINT_XFER_ISOC:
  		switch (pcm) {
  		case 1:
  			s = "1x ";
  			break;
  		case 2:
  			s = "2x ";
  			break;
  		case 3:
  			s = "3x ";
  			break;
  		}
  	default:
  		s = "";
  	} s; }),
  	DWC3_TRB_SIZE_LENGTH(__entry->size), __entry->ctrl,
  	__entry->ctrl & DWC3_TRB_CTRL_HWO ? 'H' : 'h',
  	__entry->ctrl & DWC3_TRB_CTRL_LST ? 'L' : 'l',
  	__entry->ctrl & DWC3_TRB_CTRL_CHN ? 'C' : 'c',
  	__entry->ctrl & DWC3_TRB_CTRL_CSP ? 'S' : 's',
  	__entry->ctrl & DWC3_TRB_CTRL_ISP_IMI ? 'S' : 's',
  	__entry->ctrl & DWC3_TRB_CTRL_IOC ? 'C' : 'c',
      dwc3_trb_type_string(DWC3_TRBCTL_TYPE(__entry->ctrl))
  )  

Lifetime of an Endpoint
```````````````````````

And endpoint's lifetime is summarized with enable and disable
operations, both of which can be traced. Format is::

  TP_printk("%s: mps %d/%d streams %d burst %d ring %d/%d flags %c:%c%c%c%c%c:%c:%c",
  	__get_str(name), __entry->maxpacket,
  	__entry->maxpacket_limit, __entry->max_streams,
  	__entry->maxburst, __entry->trb_enqueue,
  	__entry->trb_dequeue,
  	__entry->flags & DWC3_EP_ENABLED ? 'E' : 'e',
  	__entry->flags & DWC3_EP_STALL ? 'S' : 's',
  	__entry->flags & DWC3_EP_WEDGE ? 'W' : 'w',
  	__entry->flags & DWC3_EP_BUSY ? 'B' : 'b',
  	__entry->flags & DWC3_EP_PENDING_REQUEST ? 'P' : 'p',
  	__entry->flags & DWC3_EP_MISSED_ISOC ? 'M' : 'm',
  	__entry->flags & DWC3_EP_END_TRANSFER_PENDING ? 'E' : 'e',
  	__entry->direction ? '<' : '>'
  )


Structures, Methods and Definitions
====================================

.. kernel-doc:: drivers/usb/dwc3/core.h
   :doc: main data structures
   :internal:

.. kernel-doc:: drivers/usb/dwc3/gadget.h
   :doc: gadget-only helpers
   :internal:

.. kernel-doc:: drivers/usb/dwc3/gadget.c
   :doc: gadget-side implementation
   :internal:

.. kernel-doc:: drivers/usb/dwc3/core.c
   :doc: core driver (probe, PM, etc)
   :internal:
   
.. [#trb] Transfer Request Block
.. [#link_trb] Transfer Request Block pointing to another Transfer
	       Request Block.
.. [#debugfs] The Debug File System
.. [#configfs] The Config File System
.. [#cbw] Command Block Wrapper
.. _Linus' tree: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/
.. _me: felipe.balbi@linux.intel.com
.. _linux-usb: linux-usb@vger.kernel.org