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