Planned USB device/host support rework/enhancements

[jfischer-no]

This is a meta issue for maintainers and developers of relevant subsystems to track progress on new USB support.

Introduction

Currently we have only USB device support in Zephyr OS. Existing USB device support has many disadvantages and issues, like missing support for multiple driver instances, no endpoint (request) buffers management, missing class instances management and possibility to configure/enable class instance at runtime, not a good notification channel to the user/application, messy callback architecture, no API to set/reconfigure idVendor/iSerialNumber/bcdDevice at runtime, confusing usb_dc_ep_read()/usb_dc_ep_write() API, and more.

There is no USB host support in the project. It is asked again and again for it and there was effort like #30361, but that is far from suitable. USB device stack would also benefit from the host support and allow self-contained tests with emulated device and host controllers, and better support for USBIP.

Since many problems with the USB device support are due to the way it is designed (imported in Zephyr OS), we would like to redesign USB device support. That means USB device controller driver API and USB device stack will be rewritten in parallel and independent to existing implementation. Due to the need for testing/validation, USB host controller driver API and some parts of higher level will also be implemented.

Rough plan

• New USB device support (PR usb: add new (experimental) USB device support #38679)

  • Introduction of USB device controller API
  • virtual device controller driver implementation
  • Porting more device controller drivers to new API (There is UDC driver skeleton PR drivers: udc: add USB device controller driver skeleton  #57615, please use it as a starting point for a new UDC driver)
    • usb_dc_nrfx -> udc_nrf
    • usb_dc_kinetis -> udc_kinetis
    • usb_dc_it82xx2 -> udc_it82xx2
    • usb_dc_numaker -> udc_numaker: drivers: usb: Port usb_dc_numaker to UDC API #74660
    • usb_dc_smartbond -> udc_smartbond: drivers: usb: udc: add Smartbond UDC driver #79184
    • usb_dc_dw -> udc_dwc2
    • usb_dc_stm32 -> udc_stm32
    • usb_dc_mcux -> udc_mcux
    • usb_dc_rpi_pico -> udc_rpi_pico: drivers: usb: Port usb_dc_rpi_pico to UDC API #74666
    • usb_dc_sam_usbhs -> udc_sam_usbhs: drivers: usb: Port usb_dc_sam_usbhs to UDC API #74663 (MCHP)
    • usb_dc_sam0 -> udc_sam0: drivers: usb: Port usb_dc_sam0 to UDC API #74667 (@jfischer-no PR drivers: udc: add new UDC driver for SAM0 USB controller  #86814)
    • usb_dc_sam_usbc -> udc_sam_usbc: drivers: usb: Port usb_dc_sam_usbc to UDC API #74665 (@nandojve)
    • usb_dc_native_posix -> 🗑️ driver will be dropped (see USBIP support based on host support)
  • New USB device stack implementation
  • New USB notification mechanism (USB: notifications overhaul #51034, PR usb: device_next: implementation of USB device support notification #68256)
  • MS Descriptor support (PR usb: device_next: support BOS descriptor with vendor request code #76326)
  • Porting USB device classes to new USB device support
    • CDC ACM class support (PR usb: add new (experimental) USB device support #38679)
    • Audio class support (WIP @tmon-nordic Initial PR dt-bindings: usb: initial USB Audio Class 2 support #65972, usb: device_next: new USB Audio 2 implementation #67614)
    • HID class support (WIP @jfischer-no PR usb: device_next: add initial HID device support #65801)
    • USB DFU class support (Cannot be ported due to license, will be a new implementation (usb: device_next: implement USB DFU class for the new device support #79794))
    • USB MSC class support (PR usb: device_next: new USB Mass Storage implementation #54776)
    • Bluetooth HCI interface drivers (usb: device_next: add BT HCI USB transport layer  #53870)
    • CDC ECM (usb: device_next: add CDC ECM class implementation  #54448)
    • CDC NCM (usb: device_next: USB CDC NCM class implementation #79508)

• USB host support (PR usb: add USB host controller API, support for virtual controller, and experimental host support #50985)

  • Introduction of USB host controller API
  • MAX3421E driver implementation
  • virtual host controller driver implementation
  • Add more host controller drivers to new API (planned: dwc2)
  • Introduction of USB host stack implementation (WIP @jfischer-no)
  • UHC USBIP implementation (usb: usbip: add initial support for USBIP server #74141 WIP @jfischer-no)
  • Implementation of USB classes support
    • CDC ACM class support (WIP @jfischer-no)
    • Audio class support
    • HID class support
    • USB DFU class support
    • USB MSC class support
    • USB Video class support (Planned USB host video implementation #93517)
    • Bluetooth HCI interface drivers

Choice of support of the legacy stack

a) Remove the legacy stack entirely after 4.1.0 (hard switch)
b) Keep the stack, but remove tests and samples
c) Keep the stack, keep tests and some samples, but deprecated and not building in CI
d) Keep the stack, keep tests and some samples, but deprecated. Have a special build in CI that does not fail with deprecation

Agreement to go with d), with samples for the legacy stack placed under a legacy/ folder.

Timeline for transitioning to USB device "next" support

• Remove experimental label from device next: usb: device_next: Remove experimental status #79921
• Port remaining drivers to "next" (stragglers will be left behind if no maintainers step up. Currently Atmel controllers are not ported)
• Merge initial UHC USBIP implementation
• MS Descriptor support
• USB DFU Class
• Move the legacy samples under a folder (usb: make device-next default and move legacy sample code to legacy directory #87269). Also default to device_next in samples that work with both
• Resolution for USB device serial numbers may change between current device stack and the device_next stack #78979, UDC events silently dropped on queue full lead to USB stack issues #74058, USB next stack: make SOF events optional #87732
• Set up the CI build of samples and tests using the legacy stack with disabled deprecation (requires Provide consistent deprecated behavior and reduce downstream breakage #49708 be40d85)
• Evaluate the test coverage of the next stack
• Evaluate the impact of usb: device: next: increased RAM and flash footprint with "device_next" USB stack #83309
• Deprecate the current USB stack between 4.2.0 and 4.3.0
• Make device next the default in 4.3.0
• Remove the current USB stack in 4.5.0

Main "switch":

zephyr/subsys/usb/device_next/Kconfig

Line 5 in 745ace8

menuconfig USB_DEVICE_STACK_NEXT

[koffes]

This is good news. I would like to link to this issue: #26857, and hopefully the high CPU load will be resolved here as well. FYI @alexsven
Also, any plans for async USB audio support?

[qipengzha]

For driver support, will you plan to enable Synopsys DWC USB2.0 OTG controller ? thx

[dleach02]

Do we need a separate tracking ticket for USB Host?

[jfischer-no]

Do we need a separate tracking ticket for USB Host?

No, not at this time. My plan is that host controller driver API immediately follows device controller API (+ device stack), details of host support come afterwards.

[dleach02]

@jfischer-no Is there any of this that can be parallelized if additional resources are made available?

Also, what forum are we to use to have some open discussions about the API changes and requirements?

[jfischer-no]

@jfischer-no Is there any of this that can be parallelized if additional resources are made available?

Not yet.

[jfischer-no]

Plan updated.

[hlleng]

hello, i use usb audio these , and the usb audio leak some feature unit, like volume . It there have some plan to do this?

[fabiobaltieri]

@jfischer-no do you think we should push this to the v3.3 milestone? (it's currently tagged for v3.2)