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

[Heinrich Schuchardt]

On 8/4/23 21:37, Miquel Raynal wrote:
> 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...
> ---
>   doc/board/ti/am335x_evm.rst | 61 +++++++++++++++++++++++++++++++++++++
>   1 file changed, 61 insertions(+)
>
> diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
> index ee4faec37c2..0587b506ee2 100644
> --- a/doc/board/ti/am335x_evm.rst
> +++ b/doc/board/ti/am335x_evm.rst
> @@ -201,3 +201,64 @@ 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 device model in its management of the

Thanks for extending the documentation. Please, have a look at the
suggestions below.

%s/device model/driver model/

> +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 should be rather explicit in that

%s/should be rather explicit in that sense, showing exactly what driver
is bound to what/shows which driver is bound to which/

> +sense, showing exactly what driver is bound to what device, so the user
> +can easily configure its platform differently from the command line:

%s/its/their/ ("they" is used as gender neutral pronoun.)

> +
> +.. 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 to the fastboot command to bind with this device (at least

%s/to/for/

> +from a Bootloader point of view). The solution here would be to use the

%s/Bootloader/bootloader/

> +unbind command using the class and index parameters (as shown above in

%/using/specifying/ (just to avoiding duplicate verb 'use')

> +the 'dm tree' output) to target the driver to unbind:
> +
> +.. code-block:: text
> +
> +	=> unbind ethernet 1
> +
> +Checking the output of the 'dm tree' command now shows full availability

%s/Checking the/The/

> +for the fastboot gadget to bind with UDC 0:

Could the following catch it?

"now shows the availability of the fastboot gadget as child of the first
USB device controller."

Best regards

Heinrich

> +
> +.. 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