This commit refactors the USBH and the USB Host Library in the following ways:
- USBH now presents an abstraction of an endpoint (via usbh_ep_handle_t)
- Added separate functions to enqueue/dequeue URBs to a particular endpoint
- USB Host Library no longer calls HCD API directly. Calls USBH endpoint API
instead.
- Renamed "notif_cb" to "proc_req_cb" (Processing Request Callback)
- This is to avoid confusion with FreerTOS task notifications and Host
Library client event notifications.
- The processing functions of each layer (i.e., "xxx_process()") request
calls via the "proc_req_cb"
- The main handling function (i.e., usb_host_lib_handle_events()) is
responsible for calling the required "xxx_process()" of each layer
When a USB does not support a particular string dsecriptor (e.g.,
manufacturer, product, and serial number), the string descriptors corresponding
index will be set to 0 in the device descriptor (e.g., iManufacturer, iProduct,
iString).
Previously, the Hub driver would always attempt to fetch the all three string
descriptors, thus leading an error in CHECK_SHORT_SER_STR_DESC if the device
did not support the descriptor.
This commit fixes the Hub drvier by skipping the enumeration stages of a
particular descriptor if its index is 0 (i.e., not supported by the device).
USB devices may support string descriptors in multiple languages. The supported
languages are stored in a LANGID table, which itself is a string descriptor at
index 0.
When fetching the LANGID table itself, the USB 2.0 specification does not
specify what LANGID to use, thus the Hub driver would use the default LANGID
"ENUM_LANGID". However, this would cause some devices to stall.
This commit fixes the issue by always requesting the LANGID table itself using
a LANGID of 0.
usb_host_transfer_submit_control() uses the incorrect bmRequestType direction
flag. Therefore, when doing a transfer check, all transfers were mistakenly
treated as OUT transfers (only affects transfer check and not actual transfer).
This commit adds a simple flag/check in the USB Host Library that prevents
users from submitting a transfer that is already inflight.
- A transfer is considered inflight as soon as it is submitted by calling
usb_host_transfer_submit() or usb_host_transfer_submit_control()
- An inflight transfer remains inflight up until right before its callback
is called by one of the USB Host Library handler functions.
Closes https://github.com/espressif/esp-idf/issues/8748
Following the file renaming to use the "usb_dwc" prefix, this commit
updates the symbol names of those files to use the "usb_dwc" as well.
Some LL functions were also renamed so that the register name is
mentioned.
This commit updates the DWC_OTG based struct/ll/hal file names to
use the prefix "usb_dwc". This naming scheme reduces ambiguity if
another USB controller implementation is added.
As a result, "hcd.c" has been renamed to "hcd_dwc.c"
This commit fixes incorrect usage of memset() in the HCD's various
_buffer_parse_...() functions. The memset was not clearing the qtd lists, and
were simply setting the first qtd to a non zero value (i.e., the length of
the QTD list).
However, no bug occurred as the subsequent _buffer_fill_...() functions would
overwrite the QTD list anyways.
Some components were including esp_timer.h without declaring a
dependency on esp_timer component. This used to work due to a
transitive public dependency on esp_timer from freertos component.
Add explicit dependencies where needed.
Also some source files were using esp_timer functions without
including the header file. This used to work because esp_timer.h was
included from freertos port header file. This commit adds esp_timer.h
includes where needed.
This commit updates the USB Host Library as follows:
- usb_helpers.h
- Removed dependency on USB Host Library API
- Added function to print string descriptors
- usbh
- Fixed bug where an interface/endpoint could be claimed/allocated multiple times
- Removed redundant device ref_count change
- Added unit test for USB Host Library API usage
This commit updates the Hub Driver and USBH as follows:
- Updated communication mechanism between Hub Driver and USBH
- USBH notifies the Hub Driver via Hub request callback (usbh_hub_req_cb_t)
- Hub Driver notifies the USBH via usbh_hub_pass_event()
- Hub Driver now defers all event handling to hub_process.
- Hub Driver and USBH will now automatically recover the port after a disconnected
device has been closed.
- Fixed incorrect assert in usbh_dev_close()
Hub Driver is refactored as follows:
This commit update and refactors the Hub Driver as follows:
- Refactored enumeration state machine and stage functions
- Enumeration stage is now incremented
- Combined transfer stages of enumeration into common functions
- Comments updated
- Fixed usbh_hal_disable_debounce_lock() that would cause root_port_handle_events()
to fail the HCD_PORT_CMD_RESET call because the previous port connection interrupt
was not cleared.
The following features were added to the Hub Driver
- Enumeration config descriptor is now fetched in two separate stages
- Header is fetched first to determine the wTotalLength of the descriptor
- Fetching the full descriptor will request exactly wTotalLength bytes
- This works around some non-compliant devices that will babble/return zero
when requesting a length > wTotalLength
- Closes https://github.com/espressif/esp-idf/issues/7799
- Enumeration now stores string descriptors
- The Manufacturer, Product, and Serial Number string descriptors are
now read and stored during enumeration
- String descriptors are now part of usb_device_info_t
- Added unit test to test enumeration
This commit updates the USB Host stack to use the USB PHY driver. The
USB PHY and the OTG Controller should now both be setup/deleted using
usb_new_phy() and usb_del_phy() respectively.
- The hcd_install() now expects the USB PHY and OTG Contorller to be
already setup before it is called
- usb_host_install() now has an option to skip calling usb_del_phy() if
the user wants to setup their own USB PHY (e.g., in the case of using
and external PHY).
- CDC-ACM and MSC examples/test updated to use internal PHY
Closes https://github.com/espressif/esp-idf/issues/8061
This commit fixes the following bugs in the HCD
- HCD control pipes fill incorrect transfer size
_buffer_fill_ctrl() would fill the transfer descriptors length with
wLength instead of transfer->num_bytes. Therefore, the remaining length
would be incorrect when a control transfer requests more bytes than are
available.
- Fix USB_TRANSFER_FLAG_ZERO_PACK behavior
The previous behavior of USB_TRANSFER_FLAG_ZERO_PACK was incorrect, and did not
support interrupt pipes. A zero length packet can now be added to Bulk/Interrupt
OUT transfers where the length is a multiple of the endpoint's MPS.
- Fixed HCD port suspend and resume test case
Halting a control pipe mid control transfer can lead some test devices to get stuck
peripheral enable/disable usually should be managed by driver itself,
so make it as espressif private APIs, not recommended for user to use it
in application code.
However, if user want to re-write the driver or ports to other platform,
this is still possible by including the header in this way:
"esp_private/peripheral_ctrl.h"
This commit updates the USB Host Library API in the following wasy:
- usb_host_client_handle_t and usb_device_handle_t made into struct pointers
to generate compiler warnings about conflicting handle types
- usb_host_client_config_t changed to future proof API for Synchronous Clients
- Added usb_host_lib_unblock()
- Added usb_host_device_addr_list_fill()
- Return of usb_host_device_free_all() updated to indicate whether there
are still devices yet to be freed.
- Blockg APIs are now marked explicitly
- Fixed a bug in usb_host_transfer_submit_control() when checking the bEndpointAddress
of a control transfer.
Tests are also refactored to move some common macros into shared headers
Closes https://github.com/espressif/esp-idf/issues/7786
This commit fixes how the USBH handling of a sudden device disconnection,
more specifically handling of device gone.
- Previously the USBH would only halt, flush, and dequeue the device's
default EP, then send a device gone event to the Host Library layer.
- Now the USBH will also halt and flush all non-default EPs, allowing
all of the URBs to be dequeud.
- Some internal object members are now protected by a mutex instead of
a spinlock.
Closes https://github.com/espressif/esp-idf/issues/7505
This commit fixes how the USB Host HCD handles sudden disconnections.
Bugs:
- HW channels remain active when the port suddenly disconnects, and
previously the channel would be disabled by setting the disabled bit,
then waiting for a disabled interrupt. However, ISOC channels do not
generate the disabled interrupt when the port is invalid, thus leading
to tasks getting indefinitely blocked in hcd_pipe_command().
Fix:
On a sudden disconnection, forcibly treat all channels as halted even
if their HCCHAR.ChEna bit is still set. We do a soft reset after a port
error anyways, so the channels will eventually be reset.
Closes https://github.com/espressif/esp-idf/issues/7505
- This commit adds the API documentation for the USB Host Library.
- Warnings about the beta API are also added.
- usb_host_misc.h renamed to usb_helpers.h
This commit adds the preliminary version of the USB Host Library. This commit contains:
- USBH (USB Host Driver)
- Hub Driver that only supports a single device and device enumeration
- USB Host Library (asychronous API)
- Test cases for USB Host Library asychronous API
The following changes were made to the existing HCD:
- Removed HCD_PIPE_STATE_INVALID. Pipes are no longer invalidated
- Changed pipe commands to halt, flush, and clear. Pipes need to be manually
halted, flush, and cleared.
- Halting and flushing a pipe will execute the pipe callback if it causes a
HCD_PIPE_EVENT_URB_DONE event
This commit moves the mock classes used for HCD unit tests into
a common header so that other layers of the USB Host stack can
also utilzie them for their own unit tests.
This commit fixes the following bugs with the HCD and USB Host HAL
- Make the setting to periodic frame list and scheduling to occur after
a reset command
- All port errors states should put the port into the HCD_PORT_STATE_RECOVERY
state.
- Fixed incorrect return type of hcd_port_command() function
This commit changes the IRP (I/O Request Packet) structure to
the URB (USB Request Block) in order to represent USB transfers
in the host stack. The new URB strcuture:
- Add extra safety with const fields
- Allows each layer of the stack to add their own overhead variables
The HCD layer API and tests have been updated to use this new URB structure
This commit adds support for interrupt and isochronous pipes to the HCD:
- HCD now internally uses double buffering
- Added test cases for interrupt and isochronous transfers
- Reorganized test cases for each transfer type
- Updated API comments and maintainer's notes
Some minor bugs were also fixed
This commit updates the HCD so that transfer requests are no longer used.
The USB IRP object is updated so that the it can be directly passed to the HCD
to start a transfer. HCD API, tests, and documentation updated accordingly.
This commit separates out the common USB types used throughout most of the stack into its
own header file inside the USB component. The types used in the USB HAL are now exclusive
to the HAL.
