drivers: uhc_dwc2: Initial support

[roma-jam]

• DWC2 USB Host controller (UHC) #102931

Description

Adding USB host driver initial support for DWC2 controller.

Features and Limitations

• One peripheral port controller
• One pipe/channel
• Control transfer only
• Buffer DMA only

Commits by their order

• Updated hal_espressif
• Added host_prj.conf overlay for sample/subsys/usb/shell
• Added host register sets to usb_dwc2_hw.h
• Added uhc_dwc2.* files with vendor quirks and Kconfig for UHC_DWC2

Testing

After running the shell sample and initial driver enabling with commands usbh init and usbh enable:

[github-actions]

Hello @roma-jam, and thank you very much for your first pull request to the Zephyr project!
Our Continuous Integration pipeline will execute a series of checks on your Pull Request commit messages and code, and you are expected to address any failures by updating the PR. Please take a look at our commit message guidelines to find out how to format your commit messages, and at our contribution workflow to understand how to update your Pull Request. If you haven't already, please make sure to review the project's Contributor Expectations and update (by amending and force-pushing the commits) your pull request if necessary.
If you are stuck or need help please join us on Discord and ask your question there. Additionally, you can escalate the review when applicable. 😊

[josuah]

For anyone trying this, here is what I did to get it built:

cd ~/zephyrproject/modules/hal/espressif

Then modify the build script to include one extra directory (espressif-specific):

diff --git a/zephyr/esp32s3/CMakeLists.txt b/zephyr/esp32s3/CMakeLists.txt
index aedf412601..6a5546da9e 100644
--- a/zephyr/esp32s3/CMakeLists.txt
+++ b/zephyr/esp32s3/CMakeLists.txt
@@ -221,7 +221,7 @@ if(CONFIG_SOC_SERIES_ESP32S3)
     )
   endif()

-  if (CONFIG_UDC_DWC2)
+  if (CONFIG_UDC_DWC2 OR CONFIG_UHC_DWC2)
     zephyr_include_directories(
     ../../components/usb/include
     )

Then to build it, disable the device stack (or build error occurs insofar):

west build -b esp32s3_devkitm/esp32s3/procpu samples/subsys/usb/shell/ \
    -DEXTRA_CONF_FILE=host_prj.conf -DCONFIG_USB_DEVICE_STACK_NEXT=n

[josuah]

@roma-jam thank you very much for this effort!

Maybe you saw this incomplete branch from Espressif? raffarost@54dcf56

I could run the firmware but not yet test it I am still waiting an ESP32-S3 devkit (with 2 discrete USB interface to make sure there is no bug related to switching between the "jtag/serial and "usb-otg" interface on the same port) in the mail.

In the other hand, I will also try to get it working on a Nordic devkit that also has DWC2, and it seems like some STM32 part also has it. Glad to see you preserved all the vendor-quirks system to keep all vendor-specific on separate files.

I will post here as I am able to get more progress, and start doing early review as well.

[roma-jam]

Hi @josuah,

yes, I saw that and many thanks to @raffarost, I took couple of things from his work.

Besides that, I decided to proceed with simple implementation for all controllers with dwc2 (I hope, at least I tried to predict as much as I could) with Buffer DMA config (as currently in TinyUSB host) and with similar logic of event handling (ports, pipes and channels) , as in esp-idf USB Host stack.

Buffer DMA (not Scatter-Gahter) because it supports split-transactions, and I believe we want to have fully-working external hubs with HS root ports.

Thanks for you support and just in case - this is still a draft and I pushed it because the first step positive scenario (like device enumeration is done) is copmleted. But there are still a lot of parts are missing.

[josuah]

@roma-jam I received my ESP32-S3 DevkitC-1 to test this. So far I used an OTG adapter on the "USB" interface and connected it to various devices but after usbh init and usbh enable, the usbh device list command did not return any.

No problem, I can investigate this, but just in case there was something obvious I missed, what is your physical setup?
This uses MicroUSB so no USB-PD involved, only the OTG pin, MicroUSB cables only on that picture.

Build command used with your latest commits from 40 minutes ago:

$ west build -b esp32s3_devkitm/esp32s3/procpu samples/subsys/usb/shell/ \
    -DEXTRA_CONF_FILE=host_prj.conf -DCONFIG_USB_DEVICE_STACK_NEXT=n
$ west flash
$ picocom -b 115200 /dev/ttyUSB0
uart:~$ usbh init
host: USB host initialized
[00:00:07.296,000] <wrn> uhc_dwc2: FS PHY config not implemented yet
uart:~$ usbh enable
host: USB host enabled
uart:~$ rem Now connecting various USB devices
uart:~$ usbh device list
uart:~$ usbh device list
uart:~$ usbh device list
uart:~$

I suppose the warning message means it needs an USB HighSpeed device (USB MSC dongle) instead of FullSpeed? Or maybe a LowSpeed only (keyboard/mouse)?

I will try to support for DWC2 OTG on an nRF54LM20 DK, so different hardware anyway, but I was interested in testing the same way as you, to check that things still work on the ESP32 after introducing more code for the nRF54LM20.

I have the access to DWC2 docs and can join the effort with writing the driver as soon as I am done with the low levels (enable the core, PHY setup...).

Thanks!

[roma-jam]

Hi @josuah,

Sorry for this. Yes, there is no 5V on the USB OTG port connector, so this dev kit is for the usb device, not the host.

But! You can use the usb wire, attached to the pins or bypass the D7 to provide 5V to the port.

Please, refer to the schematic: https://dl.espressif.com/dl/schematics/SCH_ESP32-S3-DevKitC-1_V1.1_20221130.pdf

UPD:

I suppose the warning message means it needs an USB HighSpeed device (USB MSC dongle) instead of FullSpeed? Or maybe a LowSpeed only (keyboard/mouse)?

No, the warning message just shows that the supported PHY is FS and there is no config for this so far. On esp this config is by default after the power on, so it will work without it. But I will add it soon.

Thanks.

[josuah]

That makes sense thank you for the hint I thought I missed something obvious.
No problem ofc, that is a good occasion to document the hardware setup for anyone else trying.
I will try soon and give news.

[josuah]

This was an un-initialized mutex in data (not in priv).

If rebasing on main, you might face this issue:

• shell: semaphore causes crashes, replacing by mutex works #99081

Which has this workaround:

• 9b72076

[josuah]

If asking to make one change, waiting the answer, then test things locally on the devkit, it will take ages.

Let's try to make modifications, and announce them, so that it's possible to give feedback, and potentially I revert some changes if I am mistaken or better options exist etc.

Once things are in shape, it becomes easier to pursue with actual feature development on top on both our side, this becomes normal PRs...

[josuah]

First few modifications I am doing on my fork...

[roma-jam]

Hi @josuah,

thanks a lot for looking through my code and for such a usefull feedback!

I can‘t guarantee that I will fix everything in the next couple weeks, as I am in the middle of the other task.

So, I will definetely return back to this PR and I hope to make it sooner.

[josuah]

To avoid ambiguity: I am only announcing the asethetical code changes I'm doing now, and report what I've changed (to keep this a discussion and not impose anything).

Then I will propose you a replacement PR that we can both use as a root.

Hopefully this removes you the paperwork, while give an example to use to implement the actual features! :)

[github-actions]

The following west manifest projects have changed revision in this Pull Request:

Name	Old Revision	New Revision	Diff

✅ All manifest checks OK

Note: This message is automatically posted and updated by the Manifest GitHub Action.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[roma-jam]

Closed, as the feature was split into several PRs (chunks) to simplify the review process and increase code transparency.

Follow-up in #101886.