USB Host Configuration#

To configure Micrium OS USB Host, there are three groups of configuration parameters:

USB Host Memory Schemes#

The USB Host module allocates internal objects (devices, functions, interface, endpoints, etc.) to manage the devices that are connected. Determining the number of objects that need to be allocated is complicated as it greatly depends on your application and on the devices that will be connected. Unfortunately, devices that appear to have the same functionalities — for example, two simple mouses with a few buttons — may use different approaches to present themselves to the host, and may require a different number of objects to be allocated. That is why, by default, the USB host module is configured to allocate all its objects dynamically. It uses dynamic memory pools provided by Common's Lib module, and allocates the objects from the memory segment(s) you passed during the initialization. For more information on the memory segments and the dynamic memory pools, see the Memory Segments and LIB Heap page.

This means that objects are allocated as the devices are connected. This does not create memory leaks; once a device is disconnected, the objects that were allocated for one device can then be used for another one.

There are two compile-time configurations that are related to memory allocations: USBH_CFG_OPTIMIZE_SPD_EN and USBH_CFG_INIT_ALLOC_EN. Both can be set to either DEF_ENABLED or DEF_DISABLED, which makes four possibilities. In the next sections, the four possibilities will be explained.

The following sections explain these two configurations.

USBH_CFG_INIT_ALLOC_EN#

This configuration enables or disables the allocation of USB objects at initialization. When disabled, objects are allocated as the need arises (when devices are connected). The USB host module uses memory pools for its USB objects (devices, functions, interfaces, endpoints, etc.). These memory pools are global, which means that all the host controllers, devices, etc. will allocate their objects inside the same pools.

When USBH_CFG_INIT_ALLOC_EN is set to DEF_DISABLED, the global memory pools are created with an initial quantity of objects of 0 and with no maximum.

When USBH_CFG_INIT_ALLOC_EN is set to DEF_ENABLED, the global memory pools are created with an initial and maximum quantity of objects as given in the CFG_INIT_ALLOC structures.

Table - Benefits and downsides of allocation at initialization feature disabled in the USB Host Memory Schemes page shows the benefits and downsides of not allocating the USB objects at initialization.

Table - Benefits and downsides of allocation at initalization feature disabled#

Table - Benefits and downsides of allocation at initialization feature disabled

USBH_CFG_OPTIMIZE_SPD_EN#

This configuration controls the way the objects are retrieved internally. The objects in the stack are represented as a tree. So, when an object at the extremity of the tree must be retrieved, the USB host module must start at the root the tree. Each object maintains a list of their child objects, and this list can either be a simple linked list, or an array of pointers to these objects. Selecting which of methods to use is done by using the USBH_CFG_OPTIMIZE_SPD_EN configuration.

When USBH_CFG_OPTIMIZE_SPD_EN is set to DEF_DISABLED, a linked list is used to keep a reference to the child objects.

When USBH_CFG_OPTIMIZE_SPD_EN is set to DEF_ENABLED, an array of pointers is used. The size of these arrays is given in the CFG_OPTIMIZE_SPD structures.

Table - Benefits and downsides of optimization for speed feature disabled in the USB Host Memory Schemes page shows the benefits and downsides of not optimizing the USB host module for speed.

Table - Benefits and downsides of optimization for speed feature disabled#

Table - Benefits and downsides of optimization for speed feature disabled

USB Host Compile-Time Configurations#

Micrium OS USB Host is configurable at compile time via approximately a set of #defines located in usbh_cfg.h file. USB Host uses #defines when possible because they allow code and data sizes to be scaled at compile time based on enabled features. This allows the Read-Only Memory (ROM) and Random-Access Memory (RAM) footprints of Micrium OS USB Host to be adjusted based on application requirements.

We recommend that you begin the configuration process with the default configuration values, which are shown in bold in the next sections.

These sections are organized according to the order in Micrium OS USB Host's template configuration file, usbh_cfg.h.

Core Configuration#

Table - Generic Configuration Constants#

Table - Generic Configuration Constants

Class Drivers Configuration#

Some class drivers may have specific compile-time configurations. Refer to the class driver manual section for more information.

USB Host Run-Time Application Specific Configurations#

This section defines the configurations related to Micrium OS USB Host but which are specified during the initialization process. You may find that determining the appropriate values for some of these configurations is challenging, so we recommend that you consult this guide: USB Host Device Resource Needs .

Core Initialization#

To initialize Micrium OS USB Host, you call the function USBH_Init(). This function takes one configuration argument that is described here.

host_qty#

Determines the number of USB hosts you want to have. Each USB host has a unique set of device addresses. You should have one host for each host controller that you plan to use on your system.

Note that if a USB host controller uses companion controller(s), they must use the same host.

Optional Configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply.

The default values can be retrieved via the structure USBH_InitCfgDflt.Note that these configurations must be set before you call the function USBH_Init().

Buffer Alignment#

This module allocates buffers used for data transfers with the devices. You may have a specific need for address alignment for these buffers depending on your USB controller. If you use more than one USB controller, you must set the alignment to the largest value.

Type

Function to call

Default

Field from default configuration structure

CPU_SIZE_T

USBH_ConfigureBufAlignOctets()

Size of cache line, or CPU alignment, if no cache.

.BufAlignOctets

Maximum Descriptor Length#

The USB Host core module uses a single buffer to retrieve the different descriptors from the devices.

Type

Function to call

Default

Field from default configuration structure

CPU_INT16U

USBH_ConfigureMaxDescLen()

128

.MaxDescLen

Event Functions#

Configures a set of application callbacks to be called on certain USB events (device connection, disconnection, etc.).

Type

Function to call

Default

Field from default configuration structure

USBH_EVENT_FNCTS

USBH_ConfigureEventFncts()

None.

.EventFnctsPtr

Memory Segments#

This module allocates control data and buffers used for data transfers with the devices. It has the ability to use a different memory segment for the control data and for the data buffers.

Type

Function to call

Default

Field from default configuration structure

MEM_SEG*

USBH_ConfigureMemSeg()

General-purpose heap .

.MemSegPtr .MemSegBufPtr

Asynchronous Task's Stack#

The asynchronous task handles all the USB transfer completions. This configuration allows you to set the stack pointer and the stack size (in quantity of elements).

Type

Function to call

Default

Field from default configuration structure

CPU_INT32Uvoid *

USBH_ConfigureAsyncTaskStk()

A stack of 512 elements allocated on Common 's memory segment.

.AsyncTaskStkSizeElements .AsyncTaskStkPtr

Hub Task's Stack#

The hub task handles all the hub-related events such as device connection, disconnection, etc. This configuration allows you to set the stack pointer and the stack size (in quantity of elements).

Type

Function to call

Default

Field from default configuration structure

CPU_INT32Uvoid *

USBH_ConfigureHubTaskStk()

A stack of 768 elements allocated on Common 's memory segment.

.HubTaskStkSizeElements .HubTaskStkPtr

Optimize Speed Quantities#

This configuration is mandatory if you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED and therefore USBH_ConfigureOptimizeSpdCfg() must be called from your application.

When the optimize speed mode is enabled, you must provide further information. When this mode is enabled, the module will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. This configuration specifies the size of each of these tables.This configuration is available only when USBH_CFG_OPTIMIZE_SPD_EN is set to DEF_ENABLED.

Type

Function to call

Default

Field from default configuration structure

USBH_CFG_OPTIMIZE_SPD

USBH_ConfigureOptimizeSpdCfg()

No default value.

.OptimizeSpd

Allocation at Initialization Quantities#

This configuration is mandatory if you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED and therefore USBH_ConfigureInitAllocCfg() must be called from your application.

When this module allocates all its objects at initialization, it must know how many objects of each type to allocate. This configuration specifies the number of objects to allocate.This configuration is available only when USBH_CFG_INIT_ALLOC_EN is set to DEF_ENABLED.

Type

Function to call

Default

Field from default configuration structure

USBH_CFG_INIT_ALLOC

USBH_ConfigureInitAllocCfg()

No default value.

.InitAlloc

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you called the function USBH_Init().

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Standard Requests Timeout#

Timeout, in milliseconds, for the standard requests executed by this module.

Type

Function to call

Default

CPU_INT32U

USBH_StdReqTimeoutSet()

5000

Asynchronous Task Priority#

The USB host module will create a task that handles the data transfers completion. You can change the priority of the created task at any time.

Type

Function to call

Default

RTOS_TASK_PRIO

USBH_AsyncTaskPrioSet()

See Appendix A - Internal Tasks .

Hub Task Priority#

The USB host module will create a task that handles the hub-related events. You can change the priority of the created task at any time.The Hub task must have a higher priority than any other USB host task or any other application tasks that perform USB transfers.

Type

Function to call

Default

RTOS_TASK_PRIO

USBH_HUB_TaskPrioSet()

See Appendix A - Internal Tasks .

Preferred String Language ID#

Preferred language ID to use when retrieving USB strings from a device. Possible values can be found in the file usbh_core_langid.h.This configuration is available only when USBH_CFG_STR_EN is set to DEF_ENABLED.

Type

Function to call

Default

CPU_INT16U

USBH_PreferredStrLangID_Set()

USBH_LANGID_ENGLISH_UNITEDSTATES

USB Host Run-time Application Specific Configurations Event Functions#

USBH_EVENT_FNCTS is a structure that contains application event functions. Its purpose is to provide a set of application callbacks that are called on certain USB events (device connection, disconnection, etc.).

For more information on these callbacks, see USB Host Event Callbacks Usage .

Table - USBH_EVENT_FNCTS callback structure in the USB Host Run-time Application Specific Configurations Event Functions page describes each configuration field available in this configuration structure.

Table - USBH_EVENT_FNCTS callback structure#

Field

Description

Function signature

.DevConnAccept

A device was connected. Your application can decline the device connection by returning DEF_NO. Otherwise, DEF_YES must be returned.

CPU_BOOLEAN App_DevConnAccept (void)

.DevConfigAccept

The configuration of the newly connected device was retrieved. Your application can decline the configuration by returning DEF_NO. Otherwise, DEF_YES must be returned.

CPU_BOOLEAN App_DevConfigAccept(void)

.DevConfig

The connected device is now in the configured state. It is ready for communication.

void App_DevConfig (USBH_DEV_HANDLE dev_handle, CPU_INT08U cfg_nbr, RTOS_ERR err);

.FnctConnFail

A function connection of your newly connected device has failed. Refer to the error code (err) passed to this function for more information.

void App_FnctConnFail (USBH_FNCT_HANDLE fnct_handle, RTOS_ERR err);

.DevConnFail

The connection of your newly connected device has failed. Refer to the error code (err) passed to this function for more information.

void App_DevConnFail (CPU_INT08U hub_addr, CPU_INT08U port_nbr, RTOS_ERR err);

.DevDisconn

A device was disconnected.

void App_DevDisconn (USBH_DEV_HANDLE dev_handle)

USB Host Run-Time Application-Specific Configurations for Speed Optimization#

The structure USBH_CFG_OPTIMIZE_SPD allows you to configure the number of references per object.

Table - USBH_CFG_OPTIMIZE_SPD configuration structure in the USB Host Run-Time Application-Specific Configurations for Speed Optimization page describes each configuration field available in this configuration structure.

Table - USBH_CFG_OPTIMIZE_SPD configuration structure#

Field

Description

.HC_PerHostQty

Maximum number of host controllers per host. Unless you have a USB host controller that uses companion controllers, this should be set to 1.

.DevPerHostQty

Maximum number of connected devices per host that you want to support.

.FnctPerConfigQty

Maximum number of functions per configuration that you want to support. If you don't plan to use composite devices (multi-functions), this can be set to 1.

.IF_PerFnctQty

Maximum number of interfaces per function. For most of the devices, 1 will work here. If you use class drivers such as CDC ACM, 2 or more may be needed here, depending on your device.

USB Host Run-time Application Specific Configurations for Allocation at Initialization#

The structure USBH_CFG_INIT_ALLOC allows you to configure the number of USB objects to allocate.

Table - USBH_CFG_INIT_ALLOC configuration structure in the USB Host Run-time Application Specific Configurations for Allocation at Initialization page describes each configuration field available in this configuration structure.

Table - USBH_CFG_INIT_ALLOC configuration structure#

Field

Description

.DevQtyTot

Total number of devices.

.FnctQtyTot

Total number of USB functions.

.IF_QtyTot

Total number of interfaces.

.EP_QtyTot

Total number of endpoints.

.EP_QtyOpenTot

Total number of simultaneously opened endpoints.

.URB_QtyTot

Total number of USB request blocks.

.HubFnctQtyTot

Total number of Hub functions (excluding root hub(s)).

.HubEventQtyTot

Total number of Hub events.

USB Host and Host Controller Driver Configuration#

This section describes the configurations for the Micrium OS USB Host module that are specified at run-time, and which are specific to each added host controller.

To add a USB Host Controller, you call the USBD_HC_Add() function. This function takes one configurations argument that is described here.

p_hc_cfg_ext#

p_hc_cfg_ext is a pointer to a configuration structure of type USBH_HC_CFG_EXT. It is an optional configuration structure that is necessary only if you enable the configurations USBH_CFG_OPTIMIZE_SPD_EN and/or USBH_CFG_INIT_ALLOC_EN. Otherwise, a null pointer (DEF_NULL) can be passed to this argument.

Table - USBH_HC_CFG_EXT configuration structure in the USB Host and Host Controller Driver Configuration page describes each configuration field available in this configuration structure.

Table - USBH_HC_CFG_EXT configuration structure#

Table - Generic Configuration Constants

USBH_HC_CFG_DEDICATED_MEM#

If your USB controller is configured to use dedicated memory for the data buffers, you will have to provide additional information to the USB host controller driver.

Table - USBH HC CFG DEDICATED MEM configuration structure in the USB Host and Host Controller Driver Configuration page describes each configuration field available in this configuration structure.

Table - USBH_HC_CFG_DEDICATED_MEM configuration structure#

Field

Description

.DataBufQty

Number of data buffers that should be allocated by the host controller in the dedicated memory. Any provided buffer that is not already inside the dedicated memory will first be copied into one of these buffers. The more buffers you allocate, the more transfers you will be able to queue. Keep in mind that if you allocate a buffer from the dedicated memory segment in your application, the driver won't copy it to one of these buffers, therefore improving the throughput.

.DataBufLen

Length in octets of each data buffer allocated in the dedicated memory.

USBH_HC_CFG_OPTIMIZE_SPD#

If you set the configuration USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED, you will have to provide further information to the USB host controller driver. In this case, the USB host controller driver will use indexes and arrays to retrieve its internal objects instead of browsing through a list. So it is necessary to know the size of these tables.

Table - USBH_HC_CFG_OPTIMIZE_SPD configuration structure in the USB Host and Host Controller Driver Configuration page describes each configuration field available in this configuration structure.

Table - USBH_HC_CFG_OPTIMIZE_SPD configuration structure#

Field

Description

.XferDescQty

Number of transfer descriptors.

.XferDescIsocQty

Number of isochronous transfer descriptors. Not supported for the moment, always set to 0.

USBH_HC_CFG_INIT_ALLOC#

If you set the configuration USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED, you must provide additional information to the USB host controller driver. In this case, the USB host controller driver will allocate all its USB objects at initialization and will be unable to allocate more objects during execution. So, you must provide the number of each object type to allocate. This greatly depends on your needs and on the USB devices you plan to use.

Table - USBH_HC_CFG_INIT_ALLOC configuration structure in the USB Host and Host Controller Driver Configuration page describes each configuration field available in this configuration structure.

Table - USBH_HC_CFG_INIT_ALLOC configuration structure#

Field

Description

.EP_DescQty

Number of endpoint descriptors.

.EP_DescIsocQty

Number of isochronous endpoint descriptors. Not supported for the moment, always set to 0.

.XferDescQty

Number of transfer descriptors.

.XferDescIsocQty

Number of isochronous transfer descriptors. Not supported for the moment, always set to 0.

Note that if you enabled both USBH_CFG_OPTIMIZE_SPD_EN and USBH_CFG_INIT_ALLOC_EN, the values of the fields .XferDescQty and.XferDescIsocQty from both configuration structures must match.