USB Host multiconfiguration support pt1 (getting the configuration descriptor)
Closes IDFGH-11532 and IDF-8732
See merge request espressif/esp-idf!26760
- usb host reads device's configuration on request
- a control transfer is sent
- memory is allocated for a new descriptor
- user must manually free the memory
Checking for an exact match for product or serial and string descriptors can
lead to test failures if the USB devices connected to the runner is changed. This
commit adds some kconfig options to make the string descriptor checks optional,
with the product and serial string checks being disabled by default.
Previously, descriptors of the test devices were stored direclty in the mock
device files (e.g., "mock_[hid|msc].[h|c]"). This commit splits out the device
descriptors to separate files (e.g., "dev_[hid|msc].c") along with getter
functions.
Users that want to run the tests locally on a different device simply need to
update the "dev_[hid|msc].c" file for their device.
This commit updates how the USBH handles device creation and enumeration so that
upper layers (such as the Hub driver) can use the USBH API for enumeration instead
of calling the HCD.
USBH Updates:
USBH now creates unenumerated devices set to address 0 with no device/config
descriptor. A newly created device can be opened and communicated with immediately
(using control transfers). This allows the Hub driver to call the USBH instead of
the HCD. Summary of USBH changes:
- Added new APIs to add/remove a device. Devices are now created as unenumerated
and can be immediately opened and communicated with.
- Added new APIs to enumerate a device (see 'usbh_dev_set_...()' functions). Device
must be locked (see 'usbh_dev_enum_lock()') before enumeration functions can be called.
- Added UID for each device. This allows the particular USBH without needing to
use the device's handle (which implies opening the device).
Hub Driver Updates:
Hub driver now calls the USBH for enumeration. Summary of USBH changes:
- Replace all 'hcd_pipe_...()' calls with 'usbh_dev_...()' calls
- Refactored port event handling to fit with new USBH API
- Updated to use UID to uniquely identify devices without opening them
USB Host Updates:
- Reroute USBH control transfers to clients and hub driver
This commit updates the HCD API to allow port resets to occur even if pipes
are allocated. The pipes cannot be active and the port reset will simply
restore the pipes (by reinitializing their channel registers) following the
reset.
Changes:
- Allow port resets while channels are allocated
- Remove pipe persistance API 'hcd_pipe_set_persist_reset()'
This commit renames the following APIs and variables in the USBH:
- Rename the prefix of device pool functions from 'usbh_dev_...' to
'usbh_devs_...'.
- Rename 'ref_count' to 'open_count'. This variable tracks the number of times
a device has been opened.
This commit rearranges the USBH functions into new groupings to provide a
clearer abstraction. This is in preparation for refactoring/removing the Hub
related functions in the USBH API. This commit DOES NOT MAKE ANY BEHAVIORAL
CHANGES to the code.
Functions are now grouped into...
- USBH Processing: Functions dealing with overall USBH processing
- Device Pool: Functions that add/remove/open/close devices from the internal
device pool
- Device: Functions that pertain to setting/getting a particular device
- Endpoints: Functions that pertain to a particular endpoint
- Transfer: Functions that pertain to sending transfers
This commit adds/updates the USB PHY related HAL APIs. The following changes
are made:
- Updated 'usb_wrap_hal.h' API
- Added 'usb_serial_jtag_hal.h' API
This commit updates updates the LLs of USB WRAP and USJ as follows:
- Added missing 'usb_wrap_ll.h' and 'usb_serial_jtag_ll.h' for the ESP32-P4
- Added LL cap macros to distinguish feature differences between the LLs of
different targets:
- '..._LL_EXT_PHY_SUPPORTED' indicates whether the USB WRAP/USJ supports
routing to an external FSLS PHY.
- '..._LL_SWAP_PHY_SUPPORTED' indicates whether the USB WRAP/USJ supports
swapping between multiple internal FSLS PHYs.
- Tidied up some RCC LL functions and their callers.
- Added 'usb_wrap_types.h' and 'usb_serial_jtag_types.h' to provide types used
in LLs.
- Fixed some spelling/naming issues as part of code-spell pre-commit
Previously, on a device disconnection, the USBH and Hub would the require the
following 2-way interaction:
- Hub -> usbh_hub_pass_event() -> USBH to indicate a port error
- USBH -> usbh_hub_req_cb_t -> Hub to request port recovery after the device
has been freed.
The 2-way interaction has been simplified:
- USBH now nofities upper layers of devices being freed via the
USBH_EVENT_DEV_FREE event
- Hub now handles port recovery only after a device has been freed
This commit rewrite the 'usb_wrap_ll.h' API as follows:
- All APIs renamed from 'usb_fsls_phy_ll_...()' to 'usb_wrap_ll_...()'
- APIs now match their equivalent counter parts in 'usb_serial_jtag_ll.h'
For targets that only contain a USJ peripheral (and not a DWC OTG), their
'usb_fsls_phy_ll.h' headers only contain a single function
('usb_fsls_phy_ll_int_jtag_enable()') whose feature is already covered by
functions in 'usb_serial_jtag_ll.h'. Thus, this header is redundant.
This commit does the following:
- Remove 'usb_fsls_phy_ll.h' for targets that only contain a USJ peripheral
- Rename 'usb_fsls_phy_[hal|ll].[h|c]' to `usb_wrap_[hal|ll].[h|c]` for targets
that contain a DWC OTG peripheral. This better reflects the underlying peripheral
that the LL header accesses.
This commit does the following:
- Updates the USBH event callback arguments to now pass a usbh_event_data_t
which can contain different data for each event
- Updated event names
- added new test for usb_host_lib example for all targets
- CI USB host test are run on esp32p4
- CI USB device tests temporarily disabled until usb_device runner is fixed
- hcd and usb_host tests which do not require PHY are run on esp32p4
This commit fixes a bug where if multiple concurrent USBH API calls trigger
multiple events on the same device, some events will be lost. As a result,
those lost events don't get processed by the subsequent usbh_process() call.
- Renamed usb_otg_periph.h/c to usb_dwc_periph.h/c to match naming convention
of other DWC OTG related files
- Added compatibility header for usb_otg_periph.h
- user callback funciton to set device configuration
as a part of usb_host_install
- callback provides device descriptor of a device being enumerated
- user can set which cfg descriptor the USB device will be set with
- user can filter device enumeration
- Kconfig menu to enable callback function
- usb_host_lib example demonstration
