summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/stable/sysfs-class-udc16
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-uac118
-rw-r--r--Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy12
-rw-r--r--Documentation/devicetree/bindings/usb/dwc3.txt2
-rw-r--r--Documentation/devicetree/bindings/usb/iproc-udc.txt21
-rw-r--r--Documentation/driver-api/usb/dwc3.rst712
-rw-r--r--Documentation/driver-api/usb/index.rst3
-rw-r--r--Documentation/driver-api/usb/typec.rst (renamed from Documentation/usb/typec.rst)0
-rw-r--r--Documentation/driver-api/usb/usb3-debug-port.rst (renamed from Documentation/usb/usb3-debug-port.rst)0
-rw-r--r--Documentation/usb/gadget-testing.txt53
10 files changed, 817 insertions, 20 deletions
diff --git a/Documentation/ABI/stable/sysfs-class-udc b/Documentation/ABI/stable/sysfs-class-udc
index 85d3dac2e204..d1e2f3ec1fc9 100644
--- a/Documentation/ABI/stable/sysfs-class-udc
+++ b/Documentation/ABI/stable/sysfs-class-udc
@@ -55,14 +55,6 @@ Description:
Indicates the maximum USB speed supported by this port.
Users:
-What: /sys/class/udc/<udc>/maximum_speed
-Date: June 2011
-KernelVersion: 3.1
-Contact: Felipe Balbi <balbi@kernel.org>
-Description:
- Indicates the maximum USB speed supported by this port.
-Users:
-
What: /sys/class/udc/<udc>/soft_connect
Date: June 2011
KernelVersion: 3.1
@@ -91,3 +83,11 @@ Description:
'configured', and 'suspended'; however not all USB Device
Controllers support reporting all states.
Users:
+
+What: /sys/class/udc/<udc>/function
+Date: June 2017
+KernelVersion: 4.13
+Contact: Felipe Balbi <balbi@kernel.org>
+Description:
+ Prints out name of currently running USB Gadget Driver.
+Users:
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1
index 8ba9a123316e..abfe447c848f 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uac1
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1
@@ -1,12 +1,14 @@
What: /config/usb-gadget/gadget/functions/uac1.name
-Date: Sep 2014
-KernelVersion: 3.18
+Date: June 2017
+KernelVersion: 4.14
Description:
The attributes:
- audio_buf_size - audio buffer size
- fn_cap - capture pcm device file name
- fn_cntl - control device file name
- fn_play - playback pcm device file name
- req_buf_size - ISO OUT endpoint request buffer size
- req_count - ISO OUT endpoint request count
+ c_chmask - capture channel mask
+ c_srate - capture sampling rate
+ c_ssize - capture sample size (bytes)
+ p_chmask - playback channel mask
+ p_srate - playback sampling rate
+ p_ssize - playback sample size (bytes)
+ req_number - the number of pre-allocated request
+ for both capture and playback
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy b/Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy
new file mode 100644
index 000000000000..b2eaefd9bc49
--- /dev/null
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1_legacy
@@ -0,0 +1,12 @@
+What: /config/usb-gadget/gadget/functions/uac1_legacy.name
+Date: Sep 2014
+KernelVersion: 3.18
+Description:
+ The attributes:
+
+ audio_buf_size - audio buffer size
+ fn_cap - capture pcm device file name
+ fn_cntl - control device file name
+ fn_play - playback pcm device file name
+ req_buf_size - ISO OUT endpoint request buffer size
+ req_count - ISO OUT endpoint request count
diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt
index f658f394c2d3..52fb41046b34 100644
--- a/Documentation/devicetree/bindings/usb/dwc3.txt
+++ b/Documentation/devicetree/bindings/usb/dwc3.txt
@@ -45,6 +45,8 @@ Optional properties:
a free-running PHY clock.
- snps,dis-del-phy-power-chg-quirk: when set core will change PHY power
from P0 to P1/P2/P3 without delay.
+ - snps,dis-tx-ipgap-linecheck-quirk: when set, disable u2mac linestate check
+ during HS transmit.
- snps,is-utmi-l1-suspend: true when DWC3 asserts output signal
utmi_l1_suspend_n, false when asserts utmi_sleep_n
- snps,hird-threshold: HIRD threshold
diff --git a/Documentation/devicetree/bindings/usb/iproc-udc.txt b/Documentation/devicetree/bindings/usb/iproc-udc.txt
new file mode 100644
index 000000000000..272d7faf1a97
--- /dev/null
+++ b/Documentation/devicetree/bindings/usb/iproc-udc.txt
@@ -0,0 +1,21 @@
+Broadcom IPROC USB Device controller.
+
+The device node is used for UDCs integrated into Broadcom's
+iProc family (Northstar2, Cygnus) of SoCs'. The UDC is based
+on Synopsys Designware Cores AHB Subsystem Device Controller
+IP.
+
+Required properties:
+ - compatible: Add the compatibility strings for supported platforms.
+ For Broadcom NS2 platform, add "brcm,ns2-udc","brcm,iproc-udc".
+ For Broadcom Cygnus platform, add "brcm,cygnus-udc", "brcm,iproc-udc".
+ - reg: Offset and length of UDC register set
+ - interrupts: description of interrupt line
+ - phys: phandle to phy node.
+
+Example:
+ udc_dwc: usb@664e0000 {
+ compatible = "brcm,ns2-udc", "brcm,iproc-udc";
+ reg = <0x664e0000 0x2000>;
+ interrupts = <GIC_SPI 424 IRQ_TYPE_LEVEL_HIGH>;
+ phys = <&usbdrd_phy>;
diff --git a/Documentation/driver-api/usb/dwc3.rst b/Documentation/driver-api/usb/dwc3.rst
new file mode 100644
index 000000000000..c3dc84a50ce5
--- /dev/null
+++ b/Documentation/driver-api/usb/dwc3.rst
@@ -0,0 +1,712 @@
+===============================================================
+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
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 1bf64edc8c8a..8fe995a1ec94 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -16,7 +16,10 @@ Linux USB API
persist
error-codes
writing_usb_driver
+ dwc3
writing_musb_glue_layer
+ typec
+ usb3-debug-port
.. only:: subproject and html
diff --git a/Documentation/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
index 8a7249f2ff04..8a7249f2ff04 100644
--- a/Documentation/usb/typec.rst
+++ b/Documentation/driver-api/usb/typec.rst
diff --git a/Documentation/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst
index feb1a36a65b7..feb1a36a65b7 100644
--- a/Documentation/usb/usb3-debug-port.rst
+++ b/Documentation/driver-api/usb/usb3-debug-port.rst
diff --git a/Documentation/usb/gadget-testing.txt b/Documentation/usb/gadget-testing.txt
index fb0cc4df1765..fbc397d17e98 100644
--- a/Documentation/usb/gadget-testing.txt
+++ b/Documentation/usb/gadget-testing.txt
@@ -16,10 +16,11 @@ provided by gadgets.
13. RNDIS function
14. SERIAL function
15. SOURCESINK function
-16. UAC1 function
+16. UAC1 function (legacy implementation)
17. UAC2 function
18. UVC function
19. PRINTER function
+20. UAC1 function (new API)
1. ACM function
@@ -589,15 +590,16 @@ device: run the gadget
host: test-usb (tools/usb/testusb.c)
-16. UAC1 function
+16. UAC1 function (legacy implementation)
=================
-The function is provided by usb_f_uac1.ko module.
+The function is provided by usb_f_uac1_legacy.ko module.
Function-specific configfs interface
------------------------------------
-The function name to use when creating the function directory is "uac1".
+The function name to use when creating the function directory
+is "uac1_legacy".
The uac1 function provides these attributes in its function directory:
audio_buf_size - audio buffer size
@@ -772,3 +774,46 @@ host:
More advanced testing can be done with the prn_example
described in Documentation/usb/gadget-printer.txt.
+
+
+20. UAC1 function (virtual ALSA card, using u_audio API)
+=================
+
+The function is provided by usb_f_uac1.ko module.
+It will create a virtual ALSA card and the audio streams are simply
+sinked to and sourced from it.
+
+Function-specific configfs interface
+------------------------------------
+
+The function name to use when creating the function directory is "uac1".
+The uac1 function provides these attributes in its function directory:
+
+ c_chmask - capture channel mask
+ c_srate - capture sampling rate
+ c_ssize - capture sample size (bytes)
+ p_chmask - playback channel mask
+ p_srate - playback sampling rate
+ p_ssize - playback sample size (bytes)
+ req_number - the number of pre-allocated request for both capture
+ and playback
+
+The attributes have sane default values.
+
+Testing the UAC1 function
+-------------------------
+
+device: run the gadget
+host: aplay -l # should list our USB Audio Gadget
+
+This function does not require real hardware support, it just
+sends a stream of audio data to/from the host. In order to
+actually hear something at the device side, a command similar
+to this must be used at the device side:
+
+$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 &
+
+e.g.:
+
+$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \
+aplay -D default:CARD=OdroidU3
generated by cgit (git 2.34.1) at 2024-06-07 11:14:14 +0000