USB Device Configuration#

This section discusses how to configure Micrium OS USB Device. There are three groups of configuration parameters:

USB Device Compile-Time Configuration#

Micrium OS USB Device can be configured at compile time via approximately a set of #defines located in the usbd_cfg.h file. USB Device uses #defines when possible because they allow code and data sizes to be scaled at compile time based on which features are enabled. This allows the read-only memory (ROM) and random-access memory (RAM) footprints of Micrium OS USB Device to be adjusted based on your application's requirements.

Recommended: Start the configuration process with the default values (highlighted in bold).

The sections below are organized based on the order in the template configuration file, usbd_cfg.h.

Core Configuration#

Table - Generic Configuration Constants#

Constant

Description

Possible values

USBD_CFG_OPTIMIZE_SPD

Optimizes for either better performance or for smallest code size. Enabling this define will optimize Micrium OS USB Device code for better performance, and disabling this define will lead to a smaller code size.

DEF_ENABLED or DEF_DISABLED

USBD_CFG_STR_EN

Enables or disables the USB strings. Disabling this will cause the device to not store any USB description strings passed from the application. This means the host will be unable to retrieve the description strings (such as manufacturer and product name).

DEF_ENABLED or DEF_DISABLED

USBD_CFG_HS_EN

Enables or disables supports for High-Speed devices. If your USB device controller(s) do not support High-Speed, or you configure them to be Full-Speed only, this should be set to DEF_DISABLED to reduce RAM/ROM usage.

DEF_ENABLED or DEF_DISABLED

USBD_CFG_EP_ISOC_EN

Enables or disables support for Isochronous endpoints. This feature is currently unavailable. As a result, it should be set to DEF_DISABLED.

DEF_ENABLED or DEF_DISABLED

USBD_CFG_URB_EXTRA_EN

Enables or disables support for allocation of more than one USB Request Block (URB) per endpoint. This feature is currently unavailable. As a result, it should be set to DEF_DISABLED.

DEF_ENABLED or DEF_DISABLED

USBD_CFG_MS_OS_DESC_EN

Enables or disables support for Microsoft OS descriptors. Enabling this feature will cause the device to respond to Microsoft OS string descriptor requests and Microsoft OS-specific descriptors. This feature is useful if you are using the Vendor class and you don't want to provide an .inf file for your Microsoft Windows users. For more information on Microsoft OS descriptors, refer to the Microsoft Hardware Dev Center .

DEF_ENABLED or DEF_DISABLED

Classes Configuration#

Some classes may have specific compile-time configurations. Refer to USB Device Classes for more information.

USB Device Run-Time Application-Specific Configuration#

Core Initialization#

You must initialize Micrium OS USB Device by calling the function USBD_Init(). This function takes one configuration argument that is described below.

p_qty_cfg#

p_qty_cfg is a pointer to a configuration structure of type USBD_QTY_CFG. Its purpose is to inform the USB device module on how many USB objects to allocate.

The number of objects to allocate depends mostly on the class functions you will add to your device(s). For more information, refer to the section "Resource needs from core" of each class function you will add.

Table - USBD_CFG configuration structure in the USB Device Run-Time Application-Specific Configuration page describes each configuration field available in this configuration structure.

Table - USBD_CFG configuration structure#

Field

Description

.DevQty

Number of devices that will be added via the USBD_DevAdd() function.

.ConfigQty

The total number of configurations (for all of your USB devices) that will be added via the USBD_ConfigAdd() function. Remember that if you have a High-speed device, you must add both a Full-speed and a High-speed configuration to your device in order to comply with the Universal Serial Bus 2.0 specification.

.IF_Qty

The total number of USB interfaces to be added for all your devices and configurations. This greatly depends on the class(es) used. For more information on how many interfaces a class requires, refer to the section "Resources required from the core" of your class(es).

.IF_AltQty

The total number of USB alternate interfaces to be added for all your devices and configurations. This greatly depends on the class(es) used. This value must always be equal or greater than .IF_Qty. For more information on how many alternate interfaces a class requires, refer to the section "Resources required from the core" of your class(es).

.IF_GrpQty

The total number of USB interface groups that will be added for all your devices and configurations. This greatly depends on the class(es) used. For more information on how many interface groups requires a class, refer to the section "Resources required from the core" of your class(es).

.EP_DescQty

The total number of Endpoint descriptors that will be added for all your devices and configurations. This greatly depends on the class(es) used. For more information on how many endpoint descriptors a class requires, refer to the section "Resources required from the core" of your class(es).

.URB_ExtraQty

The total number of extra URBs. This greatly depends on the class(es) used. For more information on how many extra URBs a class requires, refer to the section "Resources required from the core" of your class(es).This configuration has no impact if the configuration USBD_CFG_URB_EXTRA_EN is set to DEF_DISABLED.

.StrQty

The total number of USB strings per device.This configuration has no impact if the configuration USBD_CFG_STR_EN is set to DEF_DISABLED.

.EP_OpenQty

The total number of opened endpoints per device. A device requires at least two opened endpoints for control transfers, but you must also add the endpoints of the class(es) used. For more information on how many opened endpoints a class requires, refer to the section "Resources required from the core" of your class(es).

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

Note that these configurations must be set BEFORE you call the function USBD_Init().

Table - USB Device Core Optional Configurations#

Configurations

Description

Type

Function to call

Default

Field from default configuration structure

Buffer alignment

The USB Device module allocates buffers used for data transfers with the host. You can use this function to set the address alignment for those buffers. Note: If you have more than one USB device controller you must set the alignment to the highest value.

CPU_SIZE_T

USBD_ConfigureBufAlignOctets()

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

.BufAlignOctets

Memory segments

The USB Device module allocates control data and buffers used for data transfers with the host. It has the ability to use a different memory segment for the control data and for the data buffers.

MEM_SEG*

USBD_ConfigureMemSeg()

General-purpose heap .

.MemSegPtr

Memory segments

The USB Device module allocates control data and buffers used for data transfers with the host. It has the ability to use a different memory segment for the control data and for the data buffers.

MEM_SEG*

USBD_ConfigureMemSeg()

General-purpose heap .

.MemSegBufPtr

Post-Init Configurations#

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

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

Table - USB Device Core Optional Configurations#

Configurations

Description

Type

Function to call

Default

Standard requests timeout

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

CPU_INT32U

USBD_StdReqTimeoutSet()

5000

Device task priority

Each USB device added via the function USBD_DevAdd() will create a task. You can change the priority of the created task at any time.

RTOS_TASK_PRIO

USBD_DevTaskPrioSet()

N/A

USB Device and Device Controller Driver Configuration#

This section describes USB device driver configuration. Each newly-added device has an individual configuration, which is specified at run-time.

To add a USB device, you must call the USBD_DevAdd() function. This call requires four configurations arguments, which are described below.

p_task_cfg#

Each USB device has a kernel task associated with it. p_task_cfg is a pointer to a configuration structure of type RTOS_TASK_CFG that allows you to configure the priority, stack base pointer, and stack size (in quantity of stack elements) for that task.

Guidelines on How to Properly Set the Priority and Stack Size#

Task Priorities#

The priority of a USB device’s task greatly depends on the requirements of your application. If your application requires a lot of tasks and is CPU intensive, it may be best to set the device task to a high priority; otherwise, the task might not be able to process the bus and control requests on time. On the other hand, if you plan on using asynchronous communication, and data throughput is not a priority, you might want to give the core task a low priority.

Task Stack Sizes#

A stack size of 1024 is a good starting point for most applications.

Refer to this page for more information on how to properly set the stack size.

p_dev_cfg#

p_dev_cfg is a pointer to a configuration structure of type USBD_DEV_CFG. Its purpose is to give the USB device module basic information regarding your device, such as Vendor/Product ID, device strings, etc.

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

Table - USBD_DEV_CFG configuration structure#

Field

Description

.VendorID

Your vendor identification number as delivered by the USB Implementers Forum. For more information on how you can obtain a vendor ID, see http://www.usb.org/developers/vendor/ .

.ProductID

Your product identification number.

.DeviceBCD

Release number of your device.

.ManufacturerStrPtr

Pointer to a string describing the manufacturer of your device. This configuration is ignored when the configuration USBD_CFG_STR_EN is set to DEF_DISABLED .

.ProductStrPtr

Pointer to a string describing your product. This configuration is ignored when the configuration USBD_CFG_STR_EN is set to DEF_DISABLED.

.SerialNbrStrPtr

Pointer to a string containing the serial number of your device. This configuration is ignored when the configuration USBD_CFG_STR_EN is set to DEF_DISABLED.

.LangId

Identification number of the language of your device's strings. Possible values are:

- USBD_LANG_ID_ARABIC_SAUDI_ARABIA

- USBD_LANG_ID_CHINESE_TAIWAN

- USBD_LANG_ID_ENGLISH_US

- USBD_LANG_ID_ENGLISH_UK

- USBD_LANG_ID_FRENCH

- USBD_LANG_ID_GERMAN

- USBD_LANG_ID_GREEK

- USBD_LANG_ID_ITALIAN

- USBD_LANG_ID_PORTUGUESE

- USBD_LANG_ID_SANSKRIT

This configuration is ignored when the configuration USBD_CFG_STR_EN is set to DEF_DISABLED.

p_dev_drv_cfg#

p_dev_drv_cfg is a pointer to a configuration structure of type USBD_DEV_DRV_CFG. Its purpose is to give the USB device controller driver associated with your device basic information regarding the number of resources to allocate.

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

Table - USBD_DEV_DRV_CFG configuration structure#

Field

Description

.EP_OpenQty

Maximum number of endpoints that can be opened at any time on this device.

.URB_ExtraQty

Number of extra URB to allocate for this device.This configuration is ignored when the configuration USBD_CFG_URB_EXTRA_EN is set to DEF_DISABLED.

p_bus_fnct#

p_bus_cfg is a pointer to a configuration structure of type USBD_BUS_FNCTS. Its purpose is to give the USB device module a set of optional callback functions to be called when a bus event occurs.

A null pointer (DEF_NULL) can be passed to this argument if no callbacks are needed.

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

Table - USBD_BUS_FNCTS configuration structure#

Field

Description

Function signature

.Reset

Function called when a reset signal is received from the host.

void Reset (CPU_INT08U dev_nbr)

.Suspend

Function called when the device is suspended by the host.

void Suspend(CPU_INT08U dev_nbr)

.Resume

Function called when a resume signal is received from the host.

void Resume (CPU_INT08U dev_nbr)

.CfgSet

Function called when a configuration has been set by the host.

void CfgSet (CPU_INT08U dev_nbr, CPU_INT08U cfg_val)

.CfgClr

Function called when a configuration has been cleared by the host.

void CfgClr (CPU_INT08U dev_nbr, CPU_INT08U cfg_val)

.Conn

Function called when the device has been connected.

void Conn (CPU_INT08U dev_nbr)

.Disconn

Function called when the device has been disconnected.

void Disconn(CPU_INT08U dev_nbr)