USB Host Configuration#

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

• USB Host Compile-Time Configurations

• USB Host Run-Time Application Specific Configurations

• USB Host and Host Controller Driver Configuration

USB Host Memory Schemes#

• USBH_CFG_INIT_ALLOC_EN

• USBH_CFG_OPTIMIZE_SPD_EN

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#

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#

USB Host Compile-Time Configurations#

• Core Configuration

• Class Drivers Configuration

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#

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#

• Core Initialization

  • host_qty

• Optional Configurations

  • Buffer Alignment

  • Maximum Descriptor Length

  • Event Functions

  • Memory Segments

  • Asynchronous Task's Stack

  • Hub Task's Stack

  • Optimize Speed Quantities

  • Allocation at Initialization Quantities

• Post-Init Configurations

  • Standard Requests Timeout

  • Asynchronous Task Priority

  • Hub Task Priority

  • Preferred String Language ID

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.

Maximum Descriptor Length#

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

Event Functions#

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

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.

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).

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).

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.

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.

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.

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.

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.

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.

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#

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#

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#

USB Host and Host Controller Driver Configuration#

• p_hc_cfg_ext

• USBH_HC_CFG_DEDICATED_MEM

• USBH_HC_CFG_OPTIMIZE_SPD

• USBH_HC_CFG_INIT_ALLOC

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#

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#

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#

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#