 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Azure RTOS USBX USB stack (ux) is integrated into the SSP. This document provides an overview and summary of the Azure RTOS USBX Interface for SSP. Specific USBX modules in SSP each have their own module overview section. Refer to the appropriate module overview sections in the SSP User's Manual for details on designing with specific modules.
USBX supports the two existing USB specifications: 1.1 and 2.0. It is designed to be scalable and will accommodate simple USB topologies with only one connected device, as well as complex topologies with multiple devices and cascading hubs. USBX supports both the host and device sides.
The USBX class modules listed below are fully supported in the Synergy Configuration tool. To use these USBX class modules, go to the Threads tab of the Synergy Configuration tool (configuration.xml), and select any of the USB class modules:
The USBX class modules listed below are experimental modules for Synergy parts. The experimental modules are not currently supported in Synergy Configuration. To experiment with these USBX class modules, go to the Components tab of the Synergy Configuration tool (configuration.xml) and select any of the USB class modules:
When the components above are added, a prebuilt library of the application code is also added. For each component listed above, there is an analogous component ending in '_src' that contains protected source files. The '_src' component can be added in addition to the prebuilt library module.
Refer to the associated module overview section in the SSP User's Manual for details on how to write an application with USBX modules. Additionally, each of the associated Module Guides have a working application project that illustrates how to use the module in a typical application. Module Guides are available from the Renesas Synergy web site.
In the SSP version 1.2.0 or later, the USBX stack configuration is supported in the Synergy Configuration tool and the few USBX relevant components, which were defined in previous SSP versions, are now treated as [DEPRECATED] components. They are kept in the SSP version today to provide you with backward compatibility. Anyone using a new version of SSP and wanting to keep their existing application code compatible to an existing SSP version, can use [DEPRECATED] components.
In e2 studio, create and configure a project and add the drivers:
| Azure RTOS USBX Device Class CDC-ACM(option) | Threads | Framework > USB > [DEPRECATED] USBX Device Class CDC-ACM on ux_device_class_cdc_acm |
|---|---|---|
| Azure RTOS USBX (option) | Threads | Framework > USB > [DEPRECATED] USBX on ux |
The following figure shows the interface diagram of the USBX Device Class stack. The stack consists of one USBX device class component (ux_device_class_xxx) on the top, the USBX (ux) in the middle and the USBX Port driver (sf_el_ux Device Controller Driver (DCD)) on the bottom of the device class stack. As a recommended option, the SSP Transfer module (r_dmac) supports data transfer between memory and hardware FIFO in Synergy USB peripherals (USBHS or USBFS). To support the USB device stack configuration, there are components named USBX Device Configuration and USBX Interface Configuration. These two components do not represent actual software modules in SSP; they are virtual modules to handle the code generation.
Note: Currently, the r_dtc is not supported for the device side driver (only r_dmac is supported).
The following figure shows the interface diagram of the USBX Host Class stack. The stack consists of one of the USBX Host Class components (ux_host_class_xxx) on the top, the USBX (ux) in the middle and the USBX Port driver component (sf_el_ux Host Controller Driver (HCD)) on the bottom of the host class stack. As a recommended option, the SSP Transfer module (r_dmac) supports data transfer between memory and hardware FIFO in Synergy USB peripherals (USBHS or USBFS). To support the USB host stack configuration, there is a virtual component (USBX Host Configuration) to handle the code generation:
The USBX Device Configuration component has configurations, as shown in below table, to auto-generate the USB Device Descriptor and USB Configuration Descriptor. Refer to http://www.usb.org and download USB 2.0 Specification for more information about the specification of USB Device Descriptor and or Configuration Descriptor.
USBX Device Configuration
| Configuration | Settings | Description |
|---|---|---|
| Composite Device | Enable or Disable (Default) | Enable this configuration only if composite device support is required in the application. |
| Vendor ID | 16-bit arbitrary number (Default: 0x045B) | Specify Vendor ID assigned by USB-IF. This configuration is a part of the USB Device Descriptor (idVendor). |
| Product ID | 16-bit arbitrary number (Default: 0x0000) | Specify Product ID assigned by manufacturer. This configuration is a part of the Device Descriptor (idProduct). |
| Device Release Number | 16-bit arbitrary number (Default: 0x0000) | Specify Device Release Number in binary-coded decimal. This configuration is a part of the USB Device Descriptor (bcdDevice). |
| Index of Manufacturer String Descriptor | Arbitrary number from 0 to 255 (Default: 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 | Arbitrary number from 0 to 255 (Default: 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 | Arbitrary number from 0 to 255 (Default: 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 | Device(0x00), Communications(CDC) (0x02, Default), HID (0x03), Mass Storage (0x08), Miscellaneous (0xEF), Vendor Specific (0xFF) | Select the USB Device Class Code. This configuration is a part of the USB Configuration Descriptor (bDeviceClass). |
| Index of String Descriptor describing this configuration | Arbitrary number from 0 to 255 (Default: 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 | 0x00 (Default) or value to be set to wTotalLength (calculated by user) | 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 | 0x00 (Default) or value to be set to bNumInterfaces (calculated by user). | 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 (Default) or Disable | 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 or Disable (Default) | 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(0-250) | 50 (Default), Integer value from 0 to 250. | 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 | 16-bit number assigned by Manufacturer (Default: 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 | Arbitrary C language symbol (Default: 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 in USB String Descriptor in USBX String Framework | Arbitrary integer number (Default: 0) | Specify the total number of index for String Descriptor. See section "USBX String Framework Configuration" for more information. |
| Name of USB Language Descriptor | Arbitrary C language symbol (Default: 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. |
| Total Number of Language Support | Arbitrary integer number (Default: 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. |
The USBX String Framework is byte stream data to provide USB device information with human readable strings to the USB Host device. Users need to define the byte stream data in their application code if required. See the USBX Device Class User Guide section Definition of the Strings of the Device Framework for more information about the USBX String Framework. Here is an example of USBX String Framework, which consists of three indexes String descriptors.
You can configure the properties of the USBX Device Configuration component as shown in the following table. Refer to USBX Device Configuration for more information about each configuration in the table.
Example of the USBX String Framework Configuration
| Configurations for String Descriptor on Synergy Configuration tool | Setting Example |
|---|---|
| Name of USB String Framework | g_usb_string_framework |
| Total index number of USB String Descriptor in USBX String Framework | 3 (3 indexes) |
| Index of Manufacturer String Descriptor | 1 (Index #1) |
| Index of Product String Descriptor | 2 (Index #2) |
| Index of Serial Number String Descriptor | 3 (Index #3) |
| Index of String Descriptor describing this configuration | 0 (no string information) |
| Index of String Descriptor Describing Communications Class interface | 0 (no string information) |
The USBX Languages Framework is byte stream data to support multiple languages. You need to define the byte stream data in your application code if required. See the USBX Device Class User Guide section Definition of the Languages Supported by the Device for Each String for more information. The following is an example of the USBX Language Framework which supports two Languages:
You can configure the properties of USBX Device Configuration component as shown in the following table. See section "USBX Device Configuration" for more information.
Example of the USBX Language Framework Configuration
| Configurations for String Descriptor on Synergy Configuration tool | Setting Example |
|---|---|
| Name of USB Language Descriptor | g_usb_language_framework |
| Total Number of Language Support | 2 (2 languages) |
The Azure RTOS USBX module is built in device-only mode to reduce code size for Synergy S1 parts. The configuration (UX_SYSTEM_DEVICE_ONLY) is applied automatically if the S1 board is selected in the Synergy Configuration tool BSP tab. Note that the following configurations are fixed in the device-only mode.
| USBX Mass Storage Class | USBX HID Class | |||||||
|---|---|---|---|---|---|---|---|---|
| Host | Device | Host | Device | |||||
| High Speed | Full Speed | High Speed | Full Speed | High Speed | Full Speed | High Speed | Full Speed | |
| S1JA | N/A | N/A | N/A | ✓ | N/A | N/A | N/A | ✓ |
| S124 | N/A | N/A | N/A | ✓ | N/A | N/A | N/A | ✓ |
| S128 | N/A | N/A | N/A | ✓ | N/A | N/A | N/A | ✓ |
| S3A1 | N/A | ✓ | N/A | ✓ | N/A | ✓ | N/A | ✓ |
| S3A3 | N/A | ✓ | N/A | ✓ | N/A | ✓ | N/A | ✓ |
| S3A6 | N/A | ⌧ | N/A | ✓ | N/A | ⌧ | N/A | ✓ |
| S3A7 | N/A | ✓ | N/A | ✓ | N/A | ✓ | N/A | ✓ |
| S5D5 | N/A | ✓ | N/A | ✓ | N/A | ✓ | N/A | ✓ |
| S5D3 | N/A | ✓ | N/A | ✓ | N/A | ✓ | N/A | ✓ |
| S5D9 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| S7G2 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| USBX CDC/ACM | USBX Video Class | USBX HUB Class | ||||||
|---|---|---|---|---|---|---|---|---|
| Host | Device | Host | Host | |||||
| High Speed | Full Speed | High Speed | Full Speed | High Speed | Full Speed | High Speed | Full Speed | |
| S1JA | N/A | N/A | N/A | ✓ | N/A | N/A | N/A | ✓ |
| S124 | N/A | N/A | N/A | ✓ | N/A | N/A | N/A | ✓ |
| S128 | N/A | N/A | N/A | ✓ | N/A | N/A | N/A | ✓ |
| S3A1 | N/A | ✓ | N/A | ✓ | N/A | ⌧ | N/A | ✓ |
| S3A3 | N/A | ✓ | N/A | ✓ | N/A | ⌧ | N/A | ✓ |
| S3A6 | N/A | ✓ | N/A | ✓ | N/A | ⌧ | N/A | ✓ |
| S3A7 | N/A | ✓ | N/A | ✓ | N/A | ⌧ | N/A | ✓ |
| S5D5 | N/A | ✓ | N/A | ✓ | N/A | ✓ | N/A | ✓* |
| S5D3 | N/A | ✓ | N/A | ✓ | N/A | ⌧ | N/A | ✓* |
| S5D9 | ✓ | ✓ | ✓ | ✓ | ✓ | ⌧ | ✓ | ✓ |
| S7G2 | ✓ | ✓ | ✓ | ✓ | ✓ | ⌧ | ✓ | ✓ |
| Symbol | Meaning |
|---|---|
| ✓ | Available (Tested) |
| ⌧ | Not Available (Not tested/not functional or both) |
| N/A | Not supported by MCU |
✓ * denotes that the HUB class is tested with self-powered hubs only.
The following code sample is pseudo code for USBX Device Classes. The function call sequence is auto-generated from the Synergy Configuration tool if one (or multiple) USBX Device Class component(s) is added to the Synergy Configuration tool. Auto-generated code is emitted to common_data.c file and provides the following features:
The following code sample is pseudo code for USBX Host Classes. The function call sequence is auto-generated from the Synergy Configuration tool if one (or multiple) USBX Host Class component(s) is added to the Synergy Configuration tool. Auto-generated code is emitted to the common_data.c file and provides the following features:
Application projects are available in the module guides for each USBX module. Refer to the module guides for application projects showing working code for typical use cases.
The USBX Device Stack configuration uses the following special memory sections in the linker script files. The order of memory sections in the linker script needs to consist of the USB Device Descriptor byte stream, which is given to _ux_device_stack_initialize() function; the linker script definitions must not be modified.
Memory section for the USBX Device Descriptor
| Memory section | USB Descriptor to be defined in the section |
|---|---|
| .usb_device_desc_fs* | The USB Device Descriptor for FS mode |
| .usb_config_desc_fs* | The USB Configuration Descriptor for FS mode |
| .usb_interface_desc_fs* | The USB Interface Descriptor for FS mode |
| .usb_device_desc_hs* | The USB Device Descriptor for HS mode |
| .usb_config_desc_hs* | The USB Configuration Descriptor for HS mode |
| .usb_interface_desc_hs* | The USB Interface Descriptor for HS mode |
The USBX Device stack and/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-generated code. The memory consumption is different for each class. Refer to the module overview section in the SSP User's Manual for the USBX memory requirements for a specific module.
ux_device_class_cdc_ecm, ux_device_class_rndis, ux_host_class_audio, ux_host_class_gser, ux_host_class_prolific, ux_host_class_swar) and USBX network driver (ux_network_driver) are experimental modules and not yet tested for Synergy parts in this version of SSP. It is not recommended to use them for product developments.