pkg/tinyusb: Note distinction from USBUS

[chrysn]

Contribution description

Users who find tinyusb in the documentation might be misled into thinking that this is what backs the USB features advertised around RIOT, or think that one of the stacks can use the other. This adds text to the docs to say that they are distinct and incompatible.

Testing procedure

• Look at text: Is it correct?
• Look at rendered documentation to see whether it looks nice.

[riot-ci]

Murdock results

✔️ PASSED

def30c1 pkg/tinyusb: Note distinction from USBUS

Success	Failures	Total	Runtime
2000	0	2000	06m:43s

Artifacts

• Documentation preview

This only reflects a subset of all builds from https://ci-prod.riot-os.org. Please refer to https://ci.riot-os.org for a complete build for now.

[gschorcht]

Although I'm working on an abstraction layer that will allow to use RIOT's usbdev drivers with the tinyUSB stack and tinyUSB drivers with USBUS, the stacks will be different and will coexist. The note helps the user to understand this. Thanks.

[chrysn]

A criss-cross adapter would be awesome, I'm looking forward to that -- then, that note would read differently, and the docs would say anyway how to select the backend. (Also, then, I'd love to implement the UsbDevice Rust trait on one of them, or on the one that comes out on top if only one can be used atop the other).

[benpicco]

A criss-cross adapter would be awesome, I'm looking forward to that

You can of course do what you like, but I don't quite see the use case for that.
If I understand correctly tinyUSB already provides support for all the hardware supported by usbdev, same for USB classes.

[chrysn]

If I understand correctly tinyUSB already provides support for all the hardware supported by usbdev, same for USB classes.

If it turns out that tinyUSB outperforms our current one on all metrics (dylad mentioned it being heavier) and thus replaces USBUS, that's just as valid an outcome for me. My main point is that while there's no clear roadmap and two APIs, people who might do stuff with USB might rather wait to see things settle than bet on the wrong API and later rewrite their code. (This PR is just about documenting the status quo; if we continue roadmap discussions we might want to ping @bergzand to join in).

[gschorcht]

If I understand correctly tinyUSB already provides support for all the hardware supported by usbdev, same for USB classes.

Yes, and a few more device classes are supported.

When I ported the tinyUSB package, my intention was not to replace USBUS but to use tinyUSB device drivers for MCUs that do not have usbdev support in RIOT, e.g. for ESP32 and EFM32. In the meantime, this initial intention has become obsolete as we have ported the STM32 USB OTG driver to the other MCUs that use the same Synopsys DWC2 IP core. Another use case of tinyUSB that I had thought about was that a programmer who is already familiar with tinyUSB could want to use tinyUSB instead of USBUS. And third, tinyUSB might be interesting for a programmer because it supports more device classes, e.g. audio/video, Bluetooth, RNDIS and mass storage, although I don't know how good the support is.

The disadvantages of tinyUSB that I see are:

• tinyUSB requires more resources than USBUS.
• The approach how descriptors are defined and handled in tinyUSB is not very well done.
• The documentation of the tinyUSB API, its usage and examples are a nightmare. They are almost not documented.

[benpicco]

• tinyUSB requires more resources than USBUS.

to put numbers on that: With the CDC ACM stdio test tinyUSB requires 2776 bytes more ROM on same54-xpro and 264 bytes less RAM compared to the usbus based implementation.

[gschorcht]

• tinyUSB requires more resources than USBUS.

to put numbers on that: With the CDC ACM stdio test tinyUSB requires 2776 bytes more ROM on same54-xpro and 264 bytes less RAM compared to the usbus based implementation.

🤔 The question is, what's better, less RAM or less ROM?

[gschorcht]

If I understand correctly tinyUSB already provides support for all the hardware supported by usbdev, same for USB classes.

Yes, and a few more device classes are supported.

I have to add something to my statement. Although tinyUSB supports more device classes than USBUS, a lot of work has to be done integrate them into RIOT. To have same functionality as with USBUS, we need at least:

• stdio implementation for tinyUSB CDC ACM (PR pkg/tinyusb: implement stdio via CDC ACM #18804)
• netdev implemenation for tinyUSB CDC ECM
• DFU implementation for RIOT bootloader

IMHO, one of the biggest problems with tinyUSB is the approach they use for implementing the descriptors that in tinyUSB the application is responsible for. The descriptors are assembled as a single byte array using some macros according to the device classes, interfaces and endpoints used by the application. Usually, each application has to implement the descriptors and their handling from scratch over and over again. In PR #18835, I tried a generic approach for common use cases where the descriptors of different device classes are conditionally compiled in using these descriptor macros according to selected device class modules and (in future) according to further Kconfig variables. Unfortunately, this approach is quite limited:

• It is impossible cover all possible combinations of device classes and for any number of interfaces of each device class.
• There are device classes for which not only one descriptor macro exists, but several for different applications. For the Audio device class, for example, the descriptor is assembled from 15 possible subdescriptors depending on the application.