[PATCH v2] doc: ti: Explain how the various gadget devices can be used

[Miquel Raynal]

Describe the current situation wrt the handling of USB devices on AM33xx
based boards, taking the example of a common board (the Beagle Bone
Black) and explaining how the different USB gadgets can be used.

Signed-off-by: Miquel Raynal <miquel.raynal at bootlin.com>

---

I've tried to be as transparent and honnest as I could with my limited
knowledge of the situation and the USB world, based on our latest
dicussions. I am fully open to suggestions, changes, rephrasing...

Changes in v2:
* Mostly style changes proposed by Heinrich.

---
 doc/board/ti/am335x_evm.rst | 62 +++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
index ee4faec37c2..3332d51b365 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -201,3 +201,65 @@ booting and mtdparts have been configured correctly for the board:
 	U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
 	U-Boot # nand erase.part u-boot-spl-os
 	U-Boot # nand write ${fdtaddr} u-boot-spl-os
+
+USB device
+----------
+
+The platform code for am33xx based designs is legacy in the sense that
+it is not fully compliant with the driver model in its management of the
+various resources. This is particularly true for the USB Ethernet gadget
+which will automatically be bound to the first USB Device Controller
+(UDC). This make the USB Ethernet gadget work out of the box on common
+boards like the Beagle Bone Blacks and by default will prevents other
+gadgets to be used.
+
+The output of the 'dm tree' command shows which driver is bound to which
+device, so the user can easily configure their platform differently from
+the command line:
+
+.. code-block:: text
+
+	=> dm tree
+	 Class     Index  Probed  Driver                Name
+	-----------------------------------------------------------
+	[...]
+	misc          0  [ + ]   ti-musb-wrapper       |   |-- usb at 47400000
+	usb           0  [ + ]   ti-musb-peripheral    |   |   |-- usb at 47401000
+	ethernet      1  [ + ]   usb_ether             |   |   |   `-- usb_ether
+	bootdev       3  [   ]   eth_bootdev           |   |   |       `-- usb_ether.bootdev
+	usb           0  [   ]   ti-musb-host          |   |   `-- usb at 47401800
+
+Typically here any network command performed using the usb_ether
+interface would work, while using other gadgets would fail:
+
+.. code-block:: text
+
+	=> fastboot usb 0
+	All UDC in use (1 available), use the unbind command
+	g_dnl_register: failed!, error: -19
+	exit not allowed from main input shell.
+
+As hinted by the primary error message, the only controller available
+(usb at 47401000) is currently bound to the usb_ether driver, which makes
+it impossible for the fastboot command to bind with this device (at
+least from a bootloader point of view). The solution here would be to
+use the unbind command specifying the class and index parameters (as
+shown above in the 'dm tree' output) to target the driver to unbind:
+
+.. code-block:: text
+
+	=> unbind ethernet 1
+
+The output of the 'dm tree' command now shows the availability of the
+first USB device controller, the fastboot gadget will now be able to
+bind with it:
+
+.. code-block:: text
+
+	=> dm tree
+	 Class     Index  Probed  Driver                Name
+	-----------------------------------------------------------
+	[...]
+	misc          0  [ + ]   ti-musb-wrapper       |   |-- usb at 47400000
+	usb           0  [   ]   ti-musb-peripheral    |   |   |-- usb at 47401000
+	usb           0  [   ]   ti-musb-host          |   |   `-- usb at 47401800
-- 
2.34.1