Static Stack Configuration

µC/USB-Device is configurable at compile time via approximately 20 #defines in the application’s copy of usbd_cfg.h. µC/USB-Device uses #defines when possible, because they allow code and data sizes to be scaled at compile time based on enabled features and the configured number of USB objects. This allows the Read-Only Memory (ROM) and Random-Access Memory (RAM) footprints of µC/USB-Device to be adjusted based on application requirements.

It is recommended that the configuration process begins with the default configuration values which in the next sections will be shown in bold.

The sections in this chapter are organized following the order in µC/USB-Device’s template configuration file, usbd_cfg.h.

Core Configuration

Generic Configuration


Table - Generic Configuration Constants
ConstantDescriptionPossible values
USBD_CFG_OPTIMIZE_SPDOptimizes for either better performance or for smallest code size. Enabling this define will optimize µC/USB-Device code for better performance and disabling this define will lead to smaller code size. DEF_ENABLED or DEF_DISABLED
USBD_CFG_MAX_NBR_DEVConfigures the maximum number of devices. This value should be set to the number of device controllers used on your platform.Default value is 1.
USBD_CFG_BUF_ALIGN_OCTETSConfigures the alignment in octets that internal stack’s buffer needs. This value should be set in function of your platform/hardware requirements. If your platform does not require buffer alignment, this should be set to the size of a CPU word (sizeof(CPU_ALIGN)).Typically 1, 2, 4 or 8. Default value is sizeof(CPU_ALIGN).
USBD_ERR_CFG_ARG_CHK_EXT_ENAllows code to be generated to check arguments for functions that can be called by the user and, for functions which are internal but receive arguments from an API that the user can call. DEF_ENABLED or DEF_DISABLED
USBD_CFG_MS_OS_DESC_ENEnables or disables support of Microsoft OS descriptors. Enabling this feature will cause the device to respond to Microsoft OS string descriptor requests and Microsoft OS specific descriptors.

For more information on Microsoft OS descriptors, refer to the Microsoft Hardware Dev Center.
DEF_ENABLED or DEF_DISABLED


USB Device Configuration


Table - Device Configuration Constants
ConstantDescriptionPossible Values
USBD_CFG_MAX_NBR_CFGSets the maximum number of USB configurations used by your device. Keep in mind that if you use a high-speed USB device controller, you will need at least two USB configurations, one for low and full-speed and another for high-speed. Refer to the Universal Serial Bus specification, Revision 2.0, section 9.2.3 for more details on USB configuration.From 1 (low- or full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_CFG_EP_ISOC_ENSelected portions of μC/USB-Device code required only for isochronous transfers may be disabled to reduce the code size by configuring USBD_CFG_EP_ISOC_EN. This define should be set to DEF_DISABLED if isochronous transfers are not required, to save space. DEF_ENABLED or DEF_DISABLED
USBD_CFG_HS_ENSelected portions of μC/USB-Device code required only for high-speed operation may be disabled to reduce the code size by configuring USBD_CFG_HS_EN. This define should be set to DEF_ENABLED if the USB device controller supports high-speed, or to DEF_DISABLED otherwise. DEF_ENABLED or DEF_DISABLED
USBD_CFG_CTRL_REQ_TIMEOUT_mSSets the timeout in milliseconds for the Data and the Status phases of a control transfer. This timeout prevent from a deadlock situation during a control transfer processing by the core layer. Thus a value of 0, meaning wait forever, is not allowed.From 1 to 65535. Default value is 5000.


Interface Configuration


Table - Interface Configuration Constants
ConstantDescriptionPossible Values
USBD_CFG_MAX_NBR_IFConfigures the maximum number of interfaces available. This value should at least be equal to USBD_CFG_MAX_NBR_CFG and greatly depends on the USB class(es) used. It represents the total number of interfaces usable for all configurations of your device. Each class instance requires at least one interface, while CDC-ACM requires two.Refer to the Universal Serial Bus specification, Revision 2.0, section 9.2.3 for more details on USB interfaces.From 1 to 254. Default value is 2.
USBD_CFG_MAX_NBR_IF_ALTDefines the maximum number of alternate interfaces (alternate settings) available. This value should at least be equal to USBD_CFG_MAX_NBR_IF and represents the total number of alternate interfaces usable by all interfaces of your device. Refer to the Universal Serial Bus specification, Revision 2.0, section 9.2.3 for more details on alternate settings.From 1 to 254. Default value is 2.
USBD_CFG_MAX_NBR_IF_GRPDefines the maximum number of interface groups or associations available. For the moment, Micrium offers only one USB class (CDC-ACM) that requires interface groups. Refer to the Interface Association Descriptors USB Engineering Change Notice for more details about interface associations.From 0 to 254. Default value is 0 (should be equal to the number of instances of CDC-ACM).
USBD_CFG_MAX_NBR_EP_DESCDefines the maximum number of endpoint descriptors available. This value greatly depends on the USB class(es) used. For information on how many endpoints are needed for each class, refer to the class specific chapter. Keep in mind that control endpoints do not need any endpoint descriptors.From 0 to 254. Default value is 2.
USBD_CFG_MAX_NBR_EP_OPENConfigures the maximum number of opened endpoints per device. If you use more than one device, set this value to the worst case. This value greatly depends on the USB class(es) used. For information on how many endpoints are needed for each class, refer to the class specific chapter.From 2 to 32. Default value is 4 (2 control plus 2 other endpoints).
USBD_CFG_MAX_NBR_URB_EXTRADefines the number of additional URBs that are used for asynchronous transfers only. Since these URBs are shared between every endpoint, if one endpoint uses them all, other endpoints will not be able to queue any transfer, although it is guaranteed that every endpoint always has one URB still available, to ensure that a transfer can be done at any time.From 0 to (65535 - USBD_CFG_MAX_NBR_EP_OPENUSBD_CORE_EVENT_URB_NBR_TOTAL). Default value is 0.


String Configuration


Table - String Configuration Constants
ConstantDescriptionPossible Values
USBD_CFG_MAX_NBR_STRConfigures the maximum number of string descriptors supported. This value can be increased if, for example, you plan to add interface specific strings.From 1 to 254. Default value is 3 (1 descriptor for Manufacturer string, Product string and Serial Number string).


Debug Configuration

Configurations in this section only need to be set if you use the core debugging service. For more information on that service, see the Debug and Trace page.


Table - Debug Configuration Constants
ConstantDescriptionPossible Values
USBD_CFG_DBG_TRACE_ENEnables or disables the core debug trace engine.DEF_ENABLED or DEF_DISABLED
USBD_CFG_DBG_TRACE_NBR_EVENTSDefines the maximum number of debug trace events that can be queued by the core debug trace engine. This configuration constant has no effect and will not allocate any memory if USBD_CFG_DBG_TRACE_EN is set to DEF_DISABLED.From 1 to 65535. Default value is 10.


Classes Configuration

Audio Class Configuration

Constant

Description

Possible Values
USBD_AUDIO_CFG_PLAYBACK_ENEnables or disables playback.   DEF_ENABLED or DEF_DISABLED
USBD_AUDIO_CFG_RECORD_EN

Enables or disables record.

USBD_AUDIO_CFG_PLAYBACK_EN and USBD_AUDIO_CFG_RECORD_EN can be DEF_DISABLED at the same time. In that case, only the AudioControl interface is active. No AudioStreaming interface can be defined. It may be useful to configure an audio device which does not interact with the host through USB for audio streaming.

DEF_ENABLED or DEF_DISABLED
USBD_AUDIO_CFG_FU_MAX_CTRLEnables all Feature Unit controls or disables all optional controls. When disabled, only the mute and volume controls are kept.DEF_ENABLED or DEF_DISABLED
USBD_AUDIO_CFG_MAX_NBR_AICConfigures the maximum number of class instances. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to 1.From 1 to 254. Default value is  1 .
USBD_AUDIO_CFG_MAX_NBR_CFGConfigures the maximum number of configurations in which audio class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed.From 1 (full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_AUDIO_CFG_MAX_NBR_ITConfigures the maximum number of input terminals.From 1 to 255. Default value is  2.
USBD_AUDIO_CFG_MAX_NBR_OTConfigures the maximum number of output terminals.From 1 to 255. Default value is  2 .
USBD_AUDIO_CFG_MAX_NBR_FUConfigures the maximum number of feature units.From 1 to 255. Default value is  2 .
USBD_AUDIO_CFG_MAX_NBR_MUConfigures the maximum number of mixer units. A Mixer Unit is optional.From 0 to 255. Default value is  0 .
USBD_AUDIO_CFG_MAX_NBR_SUConfigures the maximum number of selector units. A Selector Unit is optional.  From 0 to 255. Default value is  0 .
USBD_AUDIO_CFG_MAX_NBR_AS_IF_PLAYBACKConfigures the maximum number of playback AudioStreaming interfaces per class instance.From 1 to 255. Default value is  1 .
USBD_AUDIO_CFG_MAX_NBR_AS_IF_RECORD Configures the maximum number of record AudioStreaming interfaces per class instance.From 1 to 255. Default value is    1 .
USBD_AUDIO_CFG_MAX_NBR_IF_ALTConfigures the maximum number of operational alternate setting interfaces per AudioStreaming interface.From 1 to 255. Default value is  2 .
USBD_AUDIO_CFG_CLASS_REQ_MAX_LENConfigures the maximum class-specific request playload length in bytes. Among all class-specific requests supported by Audio 1.0 class, the Graphic Equalizer control of the Feature Unit use the longest payload size for the SET_CUR request. The payload for the Graphic Equalizer control can take up to 34 bytes depending of the number of frequency bands present. If the Graphical Equalizer control is not used by any feature unit, this constant can be set to 4. Refer to audio 1.0 specification, Table 5-27 for more details about Graphic Equalizer control.From 1 to 34. Default value is  4 .
USBD_AUDIO_CFG_BUF_ALIGN_OCTETS

Configures the alignment in octets that audio buffers allocated for each AudioStreaming interface will use. The alignment is dependent of the peripheral used to move data between the memory and the audio peripheral. Note that this buffer alignment should be a multiple of the internal stack's buffer alignment set with the constant USBD_CFG_BUF_ALIGN_OCTETS as the audio buffers are passed to the USB device controller that can also have its alignment requirement. If your platform does not require buffer alignment, this should be set to USBD_AUDIO_CFG_BUF_ALIGN_OCTETS.

If the CPU cache is used with the audio buffers, USBD_AUDIO_CFG_BUF_ALIGN_OCTETS should also take into account the cache line size requirement. To sum up, the value of USBD_AUDIO_CFG_BUF_ALIGN_OCTETS is influenced by:

  • Audio peripheral alignment requirement
  • USB device controller alignment requirement
  • Cache alignment requirement

If all above requirements must be taken into account, USBD_AUDIO_CFG_BUF_ALIGN_OCTETS will be the worst case among all alignment requirements.

Typically 1, 2, 4 or 8. Default value is  USBD_CFG_BUF_ALIGN_OCTETS .
USBD_AUDIO_CFG_PLAYBACK_FEEDBACK_ENEnables or disables the playback feedback support. If an isochronous OUT endpoint using the asynchronous synchronization is associated to an AudioStreaming interface, you need to set DEF_ENABLED to enable the feedback support. Refer to section  Playback Feedback Correction for more details about the audio feedback.DEF_ENABLED or DEF_DISABLED
USBD_AUDIO_CFG_PLAYBACK_CORR_ENEnables or disables built-in playback stream correction.DEF_ENABLED or DEF_DISABLED
USBD_AUDIO_CFG_RECORD_CORR_ENEnables or disables built-in record stream correction.DEF_ENABLED or DEF_DISABLED
USBD_AUDIO_CFG_STAT_ENEnables or disables audio statistics for playback and record.DEF_ENABLED or DEF_DISABLED

Communication Device Class Configuration

Some constants are available to customize the CDC base class. These constants are located in the USB device configuration file, usbd_cfg.h. Table - CDC Class Configuration Constants shows their description.

Table - CDC Class Configuration Constants
ConstantDescriptionPossible Values
USBD_CDC_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Each associated subclass also defines a maximum number of subclass instances. The sum of all the maximum numbers of subclass instances must not be greater than USBD_CDC_CFG_MAX_NBR_DEV.From 1 to 254. Default value is 1.
USBD_CDC_CFG_MAX_NBR_CFGConfigures the maximum number of configurations in which CDC class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed.From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_CDC_CFG_MAX_NBR_DATA_IFConfigures the maximum number of Data interfaces.From 1 to 254. The default value is 1.

CDC Abstract Control Model Serial Class Configuration

Table - ACM Serial Emulation Subclass Configuration Constants shows the constant available to customize the ACM serial emulation subclass. This constant is located in the USB device configuration file, usbd_cfg.h.

Table - ACM Serial Emulation Subclass Configuration Constants
ConstantDescriptionPossible Values
USBD_ACM_SERIAL_CFG_MAX_NBR_DEVConfigures the maximum number of subclass instances. The constant value cannot be greater than USBD_CDC_CFG_MAX_NBR_DEV. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to the default value.From 1 to USBD_CDC_CFG_MAX_NBR_DEV. Default value is 1.

Communication Device Class Ethernet Emulation Model Subclass Configuration 

There are various configuration constants necessary to customize the CDC EEM subclass. These constants are located in the usbd_cfg.h file.  Table - CDC EEM Configuration Constants shows a description of each constant.

Table - CDC EEM Configuration Constants
ConstantDescriptionPossible Values
USBD_CDC_EEM_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan having multiple configuration or interfaces using different class instances, this should be set to 1.From 1 to 254. Default value is 1.
USBD_CDC_EEM_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which CDC EEM is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed.From 1 (full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_CDC_EEM_CFG_RX_BUF_LENConfigures the length, in octets, of the buffer(s) used to receive the data from the host. This buffer must ideally be a multiple of the max packet size of the endpoint. However, most of the time this can be set to the Ethernet Maximum Transmit Unit (MTU -> 1518) + 2 for the CDC EEM header for better performances.64 or more. Multiple of maximum packet size if below (MTU + 2). Default value is 1520.
USBD_CDC_EEM_CFG_ECHO_BUF_LENConfigures the length, in octets, of the echo buffer used to transmit an echo response command upon reception of an echo command from the host. Size of this buffer depends on the largest possible echo data that can be sent by the host.Higher than 2. Default value is 64.
USBD_CDC_EEM_CFG_RX_BUF_QTY_PER_DEV (optional)Configures the quantity of receive buffers to be used to receive data from the host. It is not mandatory to set the value in your usbd_cfg.h file. Before setting this value to something higher than 1, you MUST ensure that you USB device driver supports URB queuing. You must also correctly configure the constant USBD_CFG_MAX_NBR_URB_EXTRA. Increasing this value will improve the data reception performances by providing multiple buffering mechanism.1 or more. Default value is 1.
 

Human Interface Device Class Configuration

Table - HID Class Configuration Constants
ConstantDescriptionPossible Values
USBD_HID_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to the default value.From 1 to 254. Default value is 1.
USBD_HID_CFG_MAX_NBR_CFGConfigures the maximum number of configurations in which HID class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed.From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_HID_CFG_MAX_NBR_REPORT_IDConfigures the maximum number of report IDs allowed in a report. The value should be set properly to accommodate the number of report ID to be used in the report.From 1 to 65535. Default value is 1.
USBD_HID_CFG_MAX_NBR_REPORT_PUSHPOPConfigures the maximum number of Push and Pop items used in a report. If the constant is set to 0, no Push and Pop items are present in the report.From 0 to 254. Default value is 0.

The HID class uses an internal task to manage periodic input reports. The task priority and stack size shown in Table - HID Internal Task’s Configuration Constants are defined in the application configuration file, app_cfg.h. Refer to the HID Periodic Input Reports Task page for more details about the HID internal task.

Table - HID Internal Task’s Configuration Constants
ConstantDescriptionPossible Values
USBD_HID_OS_CFG_TMR_TASK_PRIOConfigures the priority of the HID periodic input reports task.From the lowest to the highest priority supported by the OS used.
USBD_HID_OS_CFG_TMR_TASK_STK_SIZE
Configures the stack size of the HID periodic input reports task. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation.From the minimal to the maximal stack size supported by the OS used.

Mass Storage Class Configuration

There are various configuration constants necessary to customize the MSC device. These constants are located in the usbd_cfg.h file. Table - MSC Configuration Constants shows a description of each constant.

Table - MSC Configuration Constants
ConstantDescriptionPossible Values
USBD_MSC_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan having multiple configuration or interfaces using different class instances, this should be set to 1.From 1 to 254. Default value is 1.
USBD_MSC_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which MSC is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed.From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_MSC_CFG_MAX_LUNConfigures the maximum number of logical units.From 1 to 255. Default value is 1.
USBD_MSC_CFG_DATA_LENConfigures the read/write data length in octets.Higher than 0. The default value is 2048.
USBD_MSC_CFG_FS_REFRESH_TASK_ENEnables or disables the use of a task in µC/FS storage layer for removable media insertion/removal detection. If only fixed media such as RAM, NAND are used, this constant should be set to DEF_DISABLED. Otherwise, DEF_ENABLED should be set.DEF_ENABLED or  DEF_DISABLED
USBD_MSC_CFG_DEV_POLL_DLY_mSConfigures the period of the µC/FS storage layer’s task. It is expressed in milliseconds. If USBD_MSC_CFG_FS_REFRESH_TASK_EN is set to DEF_DISABLED, this constant has no effect. A faster period may improve the delay to detect the removable media insertion/removal resulting in a host computer displaying the removable media icon promptly. But the CPU will be interrupted often to check the removable media status. A slower period may result in a certain delay for the host computer to display the removable media icon. But the CPU will spend less time verifying the removable media status.The default value is 100 ms.


Since MSC device relies on a task handler to implement the MSC protocol, this OS-task’s priority and stack size constants need to be configured if µC/OS-II or µC/OS-III RTOS is used. Moreover if USBD_MSC_CFG_FS_REFRESH_TASK_EN is set to DEF_ENABLED, the µC/FS storage layer task’s priority and stack size need also to be configured. These constants are summarized in Table - MSC OS-Task Handler Configuration Constants.

Table - MSC OS-Task Handler Configuration Constants
ConstantDescriptionPossible Values
USBD_MSC_OS_CFG_TASK_PRIOMSC task handler’s priority level. The priority level must be lower (higher valued) than the start task and core task priorities.From the lowest to the highest priority supported by the OS used.
USBD_MSC_OS_CFG_TASK_STK_SIZEMSC task handler’s stack size. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation.From the minimal to the maximal stack size supported by the OS used. Default value is set to 256.
USBD_MSC_OS_CFG_REFRESH_TASK_PRIOµC/FS storage layer task’s priority level. The priority level must be lower (higher valued) than the MSC task.From the lowest to the highest priority supported by the OS used.
USBD_MSC_OS_CFG_REFRESH_TASK_STK_SIZEµC/FS storage layer task’s stack size. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation.From the minimal to the maximal stack size supported by the OS used. Default value is set to 256.

Personal Healthcare Device Class Configuration

Some constants are available to customize the class. These constants are located in the usbd_cfg.h file. Table - Configuration Constants Summary shows a description of each of them.

Table - Configuration Constants Summary
ConstantDescriptionPossible Values
USBD_PHDC_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan on having multiple configuration or interfaces using different class instances, this can be set to 1.From 1 to 254. Default value is 1.
USBD_PHDC_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which PHDC is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. Default value is 2.From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_PHDC_CFG_DATA_OPAQUE_MAX_LENMaximum length in octets that opaque data can be.Equal or less than MaxPacketSize - 21. Default value is 43.
USBD_PHDC_OS_CFG_SCHED_EN

If using µC/OS-II or µC/OS-III RTOS port, enable or disable the scheduler feature. You should set it to DEF_DISABLED if the device only uses one QoS level to send data, for instance. (See the PHDC RTOS QoS-based scheduler page). If you set USBD_PHDC_OS_CFG_SCHED_EN to DEF_ENABLED and you use a µC/OS-II or µC/OS-III RTOS port, PHDC will need an internal task for the scheduling operations. There are two application specific configurations that must be set in this case. They should be defined in the app_cfg.h file.

If you set this constant to DEF_ENABLED, you must ensure that the scheduler’s task has a lower priority (i.e., higher priority value) than any task that can write PHDC data.
DEF_ENABLED or DEF_DISABLED


If you set USBD_PHDC_OS_CFG_SCHED_EN to DEF_ENABLED and you use a µC/OS-II or µC/OS-III RTOS port, PHDC will need an internal task for the scheduling operations. There are two application specific configurations that must be set in this case. They should be defined in the app_cfg.h file. Table - Application-Specific Configuration Constants describes these configurations.

Table - Application-Specific Configuration Constants
ConstantDescriptionPossible Values
USBD_PHDC_OS_CFG_SCHED_TASK_PRIO

QoS based scheduler’s task priority.

You must ensure that the scheduler’s task has a lower priority (i.e. higher priority value) than any task writing PHDC data.

From the lowest to the highest priority supported by the OS used.
USBD_PHDC_OS_CFG_SCHED_TASK_STK_SIZEQoS based scheduler’s task stack size. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation.From the minimal to the maximal stack size supported by the OS used. Default value is 512.

Vendor Class Configuration

Some constants are available to customize the class. These constants are located in the USB device configuration file, usbd_cfg.h. Table - General Configuration Constants Summary shows their description.

Table - General Configuration Constants Summary
ConstantDescriptionPossible Values
USBD_VENDOR_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to 1.From 1 to 254. Default value is 1.
USBD_VENDOR_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which Vendor class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed.From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2.
USBD_VENDOR_CFG_MAX_NBR_MS_EXT_PROPERTY

Configures the maximum number of Microsoft extended properties that can be defined per Vendor class instance.

For more information on Microsoft OS descriptors and extended properties, refer to the Microsoft Hardware Dev Center .

From 1 to 255. Default value is 1.