 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The USBX™ Device Class CDC-ACM module provides a high-level API for USBX Device Class CDC-ACM module applications and uses the USB and data-transfer peripherals on the Synergy MCU. A user defined callback can be created to determine when the stack activates or deactivates the USB CDC-ACM class.
The USB Device Class CDC-ACM module allows for a USB host-system to communicate with the device as a serial device. This class is based on the USB standard and is a subset of the CDC standard. The USBX Device Class CDC‑ACM module includes the following key features:
The USBX Device Class CDC-ACM Module defines APIs for reading and writing over the USB peripheral. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
USBX Device Class CDC-ACM Module Summary
| Function Name | Example API Call and Description |
|---|---|
| ux_device_class_cdc_acm_read | status = ux_device_class_cdc_acm_read(cdc, buffer, UX_DEMO_BUFFER_SIZE, &actual_length);This function is called when an application needs to read from the OUT data pipe (OUT from the host, IN from the device). |
| ux_device_class_cdc_acm_write | status = ux_device_class_cdc_acm_write(cdc, buffer, UX_DEMO_BUFFER_SIZE, &actual_length);This function is called when an application needs to write to the IN data pipe (IN from the host, OUT from the device). |
Status Return Values
| Name | Description |
|---|---|
| UX_SUCCESS | This operation was successful. |
| UX_CONFIGURATION_HANDLE_UNKNOWN | Device is no longer in the configured state. |
| UX_TRANSFER_NO_ANSWER | No answer from device. The device was probably disconnected while the transfer was pending. |
The initialization of the CDC-ACM class expects some specific parameters as illustrated in the application project associated with this module guide.
The CDC-ACM is based on a USB-IF standard and is automatically recognized by Mac OS® and Linux OS®. On Windows® platforms, this class requires a .inf file. Azure RTOS supplies a template for the CDC-ACM class, and it can be found in the usbx_windows_host_files directory. For more recent versions of Windows, the file CDC_ACM_Template_Win7_64bit.inf should be used; this file needs to be modified to reflect the PID/VID used by the device. The PID/VID will be specific to the final customer when the company and the product are registered with the USB-IF. In the .inf file, the fields to modify are described in the application project associated with this module guide.
In the device framework of the USBX CDC-ACM device, the PID/VID are stored in the device descriptor (see the device descriptor declared in the application project referenced in the preceding paragraph).
When a USB host-system discovers the USBX CDC-ACM device, it will mount a serial class and the device can be used with any serial terminal program. (See the host operating system for reference.)
The USBX Device stack or USBX Host stack consumes RAM for the control block. The Synergy Configuration tool allocates memory to the USBX memory pool statically in the auto-generate code as shown in the following table. You need to set the appropriate memory size in bytes to the USBX Pool Memory Size property of the USBX on ux component in the Synergy Configuration tool in section "USBX on ux Configuration." If multiple classes are used, set the total memory size to the property.
Memory (RAM) Requirements for the USBX Memory Pool
| USBX Class | S1 Parts | Other Parts |
|---|---|---|
| USBX Device CDC-ACM (ux_device_class_cdc_acm) | 6.1KB | 18KB |
UX_THREAD_STACK_SIZE: 512 (bytes) for S1 parts; 2048 (bytes) for the other parts
The application needs to save the instance with the callback function registered in USBX CDC-ACM instance_activate Function Callback. Read and write are executed using the saved instance.
This section describes how to include the USBX Device Class CDC-ACM Module in an application using the SSP configurator.
To add the USBX Device Class CDC-ACM Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
USBX Device Class CDC-ACM Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_ux_device_class_cdc_acm0 USBX Device Class CDC-ACM | Threads | New Stack> X-Ware> USBX> Device> Classes > CDC-ACM > USBX Device Class CDC-ACM |
When the USBX Device Class CDC-ACM Module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
The USBX Device Class CDC-ACM Module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the USBX Device Class CDC-ACM Module
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ux_device_class_cdc_acm0 | Specify the name of the USBX Device CDC-ACM Class module instance. It must be a valid C symbol. |
| USBX CDC-ACM instance_activate Function Callback | ux_cdc_device0_instance_activate | Specify the name of the instance_activate user callback function for the USBX Device CDC-ACM Class module. Name must be a valid C symbol. See the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device CDC-ACM Class" for more information about the instance_activate callback function. |
| USBX CDC-ACM instance_deactivate Function Callback | ux-cdc_device0_instance_deactivate | Specify the name of the instance_deactivate user callback function for the USBX Device CDC-ACM Class module. Name must be a valid C symbol. Refer to the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device CDC-ACM Class" for more information about the instance_activate callback function. |
| USBX CDC-ACM parameter_change Function Callback | NULL | Specify the name of the parameter change user callback function for the USBX Device CDC-ACM Class module. Name must be a valid C symbol. Refer to the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device CDC-ACM Class" for more information about the parameter_change callback function. |
| Name of generated initialization function | ux_device_class_cdc_acm_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Note: Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.
Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the USBX Device Class CDC-ACM Source
| ISDE Property | Value | Description |
|---|---|---|
| Show linkage warning | Enabled, Disabled Default: Enabled | Notification message for users will be shown if "Enabled" option is selected. This is just to warn users possible linkage errors by multiple symbol definitions. Select "Disabled" stops the notification message. |
| CDC ACM device write auto ZLP enable | Enabled, Disabled Default: Disabled | UX_DEVICE_CLASS_CDC_ACM_WRITE_AUTO_ZLP When enabled, the CDC class sends a ZLP automatically after a buffer is sent. |
| Device CDC ACM Zero Copy | Enabled, Disabled Default: Disabled | UX_DEVICE_CLASS_CDC_ACM_ZERO_COPY When enabled, device CDC ACM zero copy for bulk in/out endpoints is supported. |
Configuration Settings for the USBX Device Configuration Instance
| ISDE Property | Value | Description |
|---|---|---|
| Vendor ID | 0x045B | Specify Vendor ID assigned by USB-IF. This configuration is a part of the USB Device Descriptor (idVendor). |
| Product ID | 0x0000 | Specify Product ID assigned by manufacturer. This configuration is a part of the Device Descriptor (idProduct). |
| Device Release Number | 0x0000 | Specify Device Release Number in binary-coded decimal. This configuration is a part of the USB Device Descriptor (bcdDevice). |
| Index of Manufacturing String Descriptor | 0x00 | Specify the Index of Manufacturer String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iManufacturer). Set zero if String Descriptor is not used. See section USBX-String-Framework-Configuration for more information. |
| Index of Product String Descriptor | 0x00 | Specify the Index of Product String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iProduct). Set zero if String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Index of Serial Number String Descriptor | 0x00 | Specify the Index of Serial Number String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iSerialNumber). Set zero if the String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Class Code | Communications(CDC), HID, Mass Storage, Miscellaneous, Vendor specific Default: Communications(CDC) | Select the USB Device Class Code. This configuration is a part of the USB Configuration Descriptor (bDeviceClass). |
| Index of String Descriptor describing this configuration | 0x00 | Specify the Index of String Descriptor describing this configuration. This configuration is a part of the USB Configuration Descriptor (iConfiguration). Set zero if String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Size of USB Descriptor in bytes for this configuration (Modify this value only for Vendor-specific Class, otherwise set zero) | 0x00 | Specify the size of USB Descriptor in bytes. Modify the value for Vendor-specific Class, otherwise you can set zero to calculate the size automatically in the auto-generated code from Synergy Configuration tool. This configuration is a part of the USB Configuration Descriptor (wTotalLength). |
| Number of Interfaces (Modify this value only for Vendor-specific Class, otherwise set zero) | 0x00 | Specify the Number of interfaces supported by this configuration. Modify the value for Vendor-specific Class, otherwise you can set zero to calculate the value automatically in the auto-generated code from Synergy Configuration tool. This configuration is a part of the USB Configuration Descriptor (bNumInterfaces). |
| Self-Powered | Enable, Disable Default: Enable | Enable this configuration if your USB Device is a self- powered device. This configuration is a part of the USB Configuration Descriptor (bmAttributes bit6). |
| Remote Wakeup | Enable, Disable Default: Disable | Enable this configuration if your USB Device supports remote wakeup. This configuration is a part of the USB Configuration Descriptor (bmAttributes bit5). |
| Maximum Power Consumption (in 2mA units) | 50 | Set the maximum power consumption of your device to indicate the amount of bus power required. This configuration is 2mA units, thus, the maximum 500 mA can be specified. This configuration is a part of the USB Configuration Descriptor (bMaxPower). |
| Supported Language Code | 0x0409 | Specify the Language ID Code. For example, 0x0409 English - United States. This configuration is used for Language ID Framework code generation. See section "USBX Language Framework Configuration" for more information. |
| Name of USBX String Framework | NULL | Specify the name of user defined USBX String Framework. This must be a valid C symbol. Set NULL if the String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Total index number of USB String Descriptors in USB String Framework | 0 | Specify the total number of index for String Descriptor. See section "USBX String Framework Configuration" for more information. |
| Name of USBX Language Framework | NULL | Specify the name of user defined USBX Language Framework. This must be a valid C symbol. If '0' is set to the property "Total Number of Language Support", this configuration is ignored. See section "USBX Language Framework Configuration" for more information. |
| Number of Languages to support (US English is applied if zero is set) | 0 | Specify the total number of languages to support. See section "USBX String Framework Configuration" for more information. If '0' is set here, US English (0x0409) is applied as the default language. |
| Name of generated initialization function | ux_device_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Configuration Settings for the USBX Interface Configuration CDC-ACM Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_usb_interface_desc_cdcacm_0 | Specify the name of USBX Interface Descriptor for CDC-ACM. It must be a valid C symbol. |
| Interface Number of Communications Class interface | 0x00 | Specify the index number of Communications Class interface. This configuration is a part of the USB Interface Descriptor (bInterface). The number must not be duplicated with the Interface Number of Data Class interface. Also must not be duplicated with any Interface Numbers if your USB device consists of a USB composite device. |
| Interrupt Transfer endpoint to use for Communications Class | Endpoint 1-9 Default: Endpoint 3 | Specify the Endpoint Number of Interrupt Endpoint. It must not be duplicated with ones for the other Endpoints. |
| Polling period for Interrupt Endpoint (in mS/125us units for FS/HS) | 0x0F | Specify the Interval for polling Endpoint transfers. This configuration is valid for Interrupt Endpoint and ignored for Bulk Endpoints. Value is in frame counts (1ms units for FS mode and 125us units for HS mode). |
| Interface Number of Data Class interface | 0x01 | Specify the index number of Data Class interface. This configuration is a part of the USB Interface Descriptor (bInterface). The number must not be duplicated with the Interface Number of Communications Class interface. Also must not be duplicated with any Interface Numbers if your USB device consists of a USB composite device. |
| Bulk In Transfer endpoint to use for Data Class | Endpoint 1-9 Default: Endpoint 1 | Specify the Endpoint Number of Bulk In Endpoint. It must not be duplicated with ones for the other Endpoints. |
| Bulk Out Transfer endpoint to use for Data Class | Endpoint 1-9 Default: Endpoint 2 | Specify the Endpoint Number of Bulk Out Endpoint. It must not be duplicated with ones for the other Endpoints. |
| Index of String Descriptor Describing Communications Class interface (Interface Descriptor: Interface) | 0x00 | Specify the index number of String Descriptor Describing Communications Class interface. This configuration is a part of the USB Interface Descriptor (iInterface). Set '0' if do not have String information for the interface. |
| Index of String Descriptor Describing Data Class interface (Interface Descriptor: Interface) | 0x00 | Specify the index number of String Descriptor Describing Data Class interface. This configuration is a part of the USB Interface Descriptor (iInterface). Set '0' if do not have String information for the interface. |
Configuration Settings for the USBX Port DCD on sf_el_ux for USBFS
| ISDE Property | Value | Description |
|---|---|---|
| Full Speed Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Select the interrupt priority for full-speed USB. |
| LDO Regulator (Only for S3 and S1 part MCUs) | Enable, Disable Default: Disable | Select the LDO regulator will be enabled. |
| Name | g_sf_el_ux_dcd_fs_0 | Module name. |
| USB Controller Selection | USBFS | Select the USB controller. |
Configuration Settings for the USBX Port DCD on USBHS
| ISDE Property | Value | Description |
|---|---|---|
| High Speed Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Select the interrupt priority for high speed USB. |
| Name | g_sf_el_ux_dcd_hs_0 | Module name. |
| USB Controller Selection | USBHS | Select the USB controller. |
Configuration Settings for the USBX on ux Instance
| ISDE Property | Value | Description |
|---|---|---|
| USBX Pool Memory Name | g_ux_pool_memory | Name must be a valid C symbol. |
| USBX Pool Memory Size | 18432 | See section "Azure RTOS USBX Memory Requirements" for the required memory size for each classes. |
| User Callback for Host Event Notification (Only valid for USB Host) | NULL | Name must be a valid C symbol. The name of User defined USBX Host event notification can be given to this property. |
| Name of generated initialization function | ux_common_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
The USB peripheral module uses the UCLK as its clock source; the UCLK should be configured for 48MHz operation. In the SSP configuration window, select the Clocks tab to view the clock-source setting.
The USB peripheral module uses MCU pins to communicate with external devices. Select I/O pins and configure to the external device requirements. The following table lists the pin selection method within the SSP Configuration Window and the subsequent tables demonstrate the selection process using USB pins as an example.
USBFS and USBHS Pin Selection Sequence
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| USBFS | Pins | Select Peripherals > Connectivity: USBFS> USBFS0 |
| USBHS | Pins | Select Peripherals > Connectivity: USBHS> USBHS0 |
USBHS Pin Configuration Settings
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, Device, Host, OTG Default: Custom | Select device as the Operation Mode |
| USBDP | USBDP | USBDP pin |
| USBDM | USBDM | USBDM pin |
| OVRCURB | None | OVRCURB pin |
| OVRCURA | None | OVRCURA pin |
| VBUSEN | None | VBUSEN pin |
| VBUS | None, P407 Default: P407 | VBUS pin |
| EXICEN | None | EXICEN pin |
| ID | None | ID Pin |
| VCCUSB | VCCUSB | VCCUSB pin |
| VSSUSB | VSSUSB | VSSUSB pin |
USBHS Pin Configuration Settings
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, Device, Host, OTG Default: Custom | Select Device as the Operation Mode |
| USBHSDP | USBHSDP | USBHSDP pin |
| USBHSDM | USBHSDM | USBHSDM pin |
| OVRCURB | None | OVRCURB pin |
| OVRCURA | None | OVRCURA pin |
| VBUSEN | PB00 | VBUSEN pin |
| VBUS | PB01 | VBUS pin |
| EXICEN | None | EXICEN pin |
| ID | None | ID pin |
| USBHSRREF | USBHSRREF | USBHSRREF pin |
| AVCCUSBHS | AVCCUSBHS | AVCCUSBHS pin |
| AVSSUSBHS | AVSSUSBHS | AVSSUSBHS pin |
| PVSSUSBHS | PVSSUSBHS | PVSSUSBHS pin |
| VCCUSBHS | VCCUSBHS | VCCUSBHS pin |
| VSS1USBHS | VSS1USBHS | VSS1USBHS pin |
| VSS2USBHS | VSS2USBHS | VSS2USBHS pin |
The configurator generates processing to create and register the USBX Device Class CDC-ACM module; however, communication must be done after the device is connected to the host.
The typical steps in using the USBX Device Class CDC-ACM module in an application are:
1. Wait for the callback function registered in USBX CDC-ACM instance_activate Function Callback to be called.
2. In the callback function, save the instance.
3. For received data reading, use the ux_device_class_cdc_acm_read API.
4. For sending data, use the ux_device_class_cdc_acm_write API.
These common steps are illustrated in a typical operational flow diagram in the following figure:
