USB support consists of several packages: the main USB subsystem CYGPKG_IO_USB; at least one HCD or PCD package, for example CYGPKG_DEVS_USB_OHCI or CYGPKG_DEVS_USB_PCD_DWC; and a target specific configuration package, for example CYGPKG_DEVS_USB_STM32. The driver and configuration packages are usually part of the target specification in ecos.db. Once these packages are installed, there are a number of configuration options that may be set. Those for the controllers and configuration packages are described in their own documentation, those for the USB subsystem are described here.
To enable USB support in any configuration it should simply be necessary to add the CYGPKG_IO_USB package and then enable CYGPKG_IO_USB_HOST and/or CYGPKG_IO_USB_TARGET to provide the appropriate stack modes.
The following configuration options control the behaviour of the USB subsystem.
- cdl_component CYGPKG_IO_USB_HOST
This component enables USB host support in the USB stack.
- cdl_option CYGNUM_IO_USB_HOST_BUFFER_SIZE
The USB subsystem uses a shared buffer for some purposes. This option defines the size of that buffer. Class drivers may require that this buffer be increased in size. The default size is 64 bytes, which is sufficient for the configurations of most devices.
- cdl_component CYGSEM_IO_USB_HUB
This option controls the level of HUB support. When enabled, full HUB support is provided, for both root and external HUBs. When disabled, only rudimentary root hub support is provided, external hubs are not supported, and all devices must be plugged in to the USB host device. This option is enabled by default.
- cdl_option CYGNUM_IO_USB_HUB_POLL_INTERVAL
This option defines the interval in milliseconds between polls of a hub's ports for device attach and detach events. This value effectively defines how responsive the system is to device attach/detach. The default value is 1000, causing the hubs to be polled once a second.
- cdl_option CYGNUM_IO_USB_HUB_PORT_MAX
This option defines the maximum number of ports allowed per hub. The default value is four since most external hubs have just four downstream ports; virtual root hubs seldom have more and usually have fewer.
- cdl_component CYGPKG_IO_USB_TARGET
This component enables USB target support in the USB stack.
- cdl_option CYGNUM_IO_USB_MEMORY_TABLE_TARGET_ENDPOINT_SIZE
Number of endpoints allocated for target use.
- cdl_option CYGNUM_IO_USB_OS_THREAD_STACK_SIZE
The USB subsystem uses an internal thread to handle asynchronous actions. This option defines the size of this stack in addition to CYGNUM_HAL_STACK_SIZE_TYPICAL. The default value is 4KiB.
- cdl_option CYGNUM_IO_USB_OS_THREAD_PRIORITY
The USB subsystem uses an internal thread to handle asynchronous actions. This option defines the priority at which this thread is scheduled. The default value is set to 10, which makes the USB thread run at a medium high priority.
- cdl_component CYGSEM_IO_USB_MEMORY_SYSTEM_HEAP
This option enables use of the system heap for all USB memory allocations. It is orthogonal to the PRIVATE_HEAP and TABLES options. This is the default memory allocation option.
- cdl_option CYGNUM_IO_USB_MEMORY_SYSTEM_HEAP_LIMIT
This option sets a limit on the amount of memory allocated from the system heap. Once the USB stack has allocated this much, it will refuse further allocations until memory is freed. If this value is set to 0 (the default) the limit is not enforced.
- cdl_component CYGSEM_IO_USB_MEMORY_PRIVATE_HEAP
This option enables use of a fixed size private heap for all USB memory allocations. It is orthogonal to the SYSTEM_HEAP and TABLES options.
- cdl_option CYGNUM_IO_USB_MEMORY_PRIVATE_HEAP_SIZE
This option defines the size of the private heap. Once this heap is exhausted, no more memory will be allocated.
- cdl_component CYGSEM_IO_USB_MEMORY_TABLES
This option enables use of fixed sized static tables for all USB memory allocations. It is orthogonal to the SYSTEM_HEAP and PRIVATE_HEAP options.
- cdl_option CYGNUM_IO_USB_MEMORY_TABLE_TFR_SIZE
Number of transfer objects in table. This option defaults to 4.
- cdl_option CYGNUM_IO_USB_MEMORY_TABLE_DEVICE_SIZE
Number of device objects in table. This option defaults to 4.
- cdl_option CYGNUM_IO_USB_MEMORY_TABLE_ENDPOINT_SIZE
Number of endpoints allocated. The endpoint object table will be the device table size multiplied by this value plus the value of CYGNUM_IO_USB_MEMORY_TABLE_TARGET_ENDPOINT_SIZE. The default value is 3. Typically devices need an entry for endpoint zero plus input and output endpoints. If any class driver needs more it should require a larger value for this option.
- cdl_option CYGNUM_IO_USB_MEMORY_TABLE_DESC_SIZE
Number of descriptor objects in table. This option defaults to five times the number of entries in the device table. Typically each device needs an entry each for one configuration, one interface and three endpoints. Class drivers can increase this value if necessary.
- cdl_option CYGNUM_IO_USB_TRANSFER_POOL_SIZE
This option defines the number of transfer objects maintained in the free pool for fast allocation. When the memory allocation strategy is to use tables, this option is ignored and the pool is set to the same size as the transfer table, and all transfers are kept in the pool. The default value is 4.
- cdl_option CYGDBG_IO_USB_DIAG
This option controls the inclusion of diagnostics in the USB stack. The exact set of diagnostic messages can be further controlled at runtime on a per-subsystem basis.
- cdl_option CYGDBG_IO_USB_LOG
This option controls the inclusion of logging in the USB stack. This differs from diagnostics in that only major events like device attach/detach are logged.
- cdl_option CYGDBG_IO_USB_STATISTICS
This option controls the inclusion of statistics gathering in the USB stack.
- cdl_option CYGNUM_IO_USB_STATISTICS_INTERVAL
This option defines the interval between reporting USB stack statistics. The time is given in seconds. A value of 0 disables the regular reports and statistics will only be reported if the application calls