 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The USBX Host Class CDC-ACM module provides a high-level API for USBX Host Class CDC-ACM applications and configures the USBX Host Class CDC-ACM Source, USBX Host Configuration, USBX Source, USBX Port HCD and a transfer driver. The USBX Host Class CDC-ACM module uses the DMAC/DTC and USB Host Class peripherals on the Synergy MCU.
The CDC-ACM class uses a composite device framework to group interfaces (control and data). As a result, care should be taken when defining the device descriptor. The USBX relies on the IAD descriptor to know internally how to bind interfaces. The IAD descriptor should be declared before the interfaces and contain the first interface of the CDC-ACM class and how many interfaces are attached. The CDC-ACM class also uses a union functional descriptor which performs the same function as the newer IAD descriptor. Although a union functional descriptor must be declared for historical reasons and compatibility with the host side, it is not used by the USBX.
The USBX Host Class CDC-ACM Module defines APIs for reading, writing and ioctl. 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 Host Class CDC-ACM Module Summary
| Function Name | Example API Call and Description |
|---|---|
| ux_host_class_cdc_acm_read | status = ux_host_class_cdc_acm_read(cdc_acm, data_pointer, requested_length,&actual_length);This function reads from the cdc_acm interface. The call is blocking and only returns when there is either an error or when the transfer is complete. |
| ux_host_class_cdc_acm_write | status = ux_host_class_cdc_acm_write(cdc_acm, data_pointer,requested_length,&actual_length);This function writes to the cdc_acm interface. The call is blocking and only returns when there is either an error or when the transfer is complete. |
| ux_host_class_cdc_acm_ioctl | status = ux_host_class_cdc_acm_ioctl(cdc_acm, ioctl_function, ¶meter_p);This function performs a specific ioctl function to the cdc_acm interface. The call is blocking and only returns when there is either an error or when the command is completed. |
Status Return Values
| Name | Description |
|---|---|
| UX_SUCCESS | The data transfer was completed. |
| UX_TRANSFER_TIMEOUT | Transfer timeout, reading/writing not completed. |
| UX_MEMORY_INSUFFICIENT | Not enough memory. |
| UX_HOST_CLASS_UNKNOWN | Wrong class instance. |
| UX_FUNCTION_NOT_SUPPORTED | Unknown IOCTL function. |
Initialization of USBX Resources
The USBX has its own memory manager. The memory needs to be allocated to the USBX before the host or device side of the USBX is initialized. The USBX memory manager can accommodate systems where memory can be cached.
Definition of USB Host Controllers
It is required to define at least one USB host controller for USBX to operate in host-mode. The application-initialization file should contain this definition. SSP defines USB host controller when USB host controller driver is added to thread stacks.
Definition of Device Classes
It is required to define one or more device classes(s) with the USBX. A USB class is required to drive a USB device after the USB stack has configured the USB device. A USB class is very specific to the device; one or more classes may be required to drive a USB device depending on the number of interfaces contained in the USB device descriptors.
USB Class Binding
When the device is configured, the topology manager will let the class manager continue the device discovery by looking at the device-interface descriptors. A device can have one or more interface descriptors.
An interface represents a function in a device. For instance, a USB speaker has three interfaces, one for audio streaming, one for audio control, and one to manage the various speaker buttons.
The class manager has two mechanisms to join the device interface(s) to one or more classes. It can either use the combination of a PID/VID (product ID and vendor ID) found in the interface descriptor or the combination of Class/Subclass/Protocol.
The PID/VID combination is valid for interfaces that cannot be driven by a generic class. The Class/Subclass/Protocol combination is used by interfaces that belong to a USB-IF certified class such as a printer, hub, storage, audio, or Human Interface Design (HID).
The class manager contains a list of registered classes from the initialization of the USBX. The class manager will call each class one-at-a-time until one class accepts to manage the interface for that device; each class can only manage one interface. In the case of the USB audio speaker, the class manager will call all the classes for each of the interfaces.
Once a class accepts an interface, a new instance of that class is created; the class manager will then search for the default alternate setting for the interface. A device may have one or more alternate settings for each interface. The alternate setting 0 will be the one used by default until a class decides to change it.
For the default alternate setting, the class manager will mount all the endpoints contained in the alternate setting. If the mounting of each endpoint is successful, the class manager will complete its job by returning to the class that will finish the initialization of the interface.
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 Host CDC-ACM (ux_host_class_cdc_acm) | N/A | 30KB |
UX_THREAD_STACK_SIZE: 512(bytes) for S1 parts; 2048(bytes) for the other parts
This section describes how to include the USBX Host Class CDC-ACM Module in an application using the SSP configurator.
To add the USBX Host Class CDC-ACM Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
USBX Host Class CDC-ACM Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_ux_device_class_cdc_acm0 USBX Host Class CDC-ACM | Threads | New Stack> X-Ware> USBX> Device> Classes > CDC-ACM > USBX Host Class CDC-ACM |
When the USBX Host 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 Host 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 Host Class CDC-ACM Module
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ux_host_class_cdc_acm0 | Specify the name of USBX Host CDC-ACM Class module instance. It must be a valid C symbol. |
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 Host 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. |
Configuration Settings for the USBX Host Configuration Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ux_host0 | Specify the name of USBX Host Configuration instance. It must be a valid C symbol. |
| Name of generated initialization function | ux_host_hid_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Configuration Settings for the USBX Port HCD 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. |
| VBUSEN pin Signal Logic | Active Low, Active High Default: Active High | Select the VBUSEN pin signal logic. |
| 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_hcd_fs_0 | Module name. |
| USB Controller Selection | USBFS | Select the USB controller. |
Configuration Settings for the USBX Port HCD on sf_el_ux for 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. |
| FIFO size for Bulk/Isochronous Pipes | 512, 1024, 1536, 2048 bytes Default: 512 bytes | Select the FIFO size for bulk and isochronous transfers. |
| Number of Isochronous Pipes Reserved | 0,1,2 Default: 0 | Select the number of isochronous pipes to reserve. |
| VBUSEN pin Signal Logic | Active Low, Active High Default: Active High | Select the VBUSEN pin signal logic. |
| Enable High Speed | Enable, Disable Default: Enable | Select if high speed should be enabled. |
| Name | g_sf_el_ux_hcd_hs_0 | Module name. |
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 Host Class CDC-ACM module; however, communication must be done after the Host is connected to the host.
The typical steps in using the USBX Host Class CDC-ACM module in an application are:
1. Get the first instance of the connected device with ux_host_stack_class_instance_get API.
2. Wait for the device status to become live.
3. Check that the class of the device is CDC Data Class.
4. If there is the next device, check the status again.
5. For received data reading, use the ux_host_class_cdc_acm_read API.
6. For data sending, use the ux_host_class_cdc_acm_write API.
These common steps are illustrated in a typical operational flow diagram in the following figure:
