 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The USBX™ Host Class Mass Storage module provides a high-level API for USBX Host Class Mass Storage applications and uses the USB and data-transfer peripherals on the Synergy MCU.
The USBX Host Class Mass Storage module does not have a separate API available for user applications. When a USB media is connected, it is attached to the FileX® member included in the USBX Host Class Mass Storage instance. The user application uses this FileX member to access files on the USB media. For FileX APIs, refer to the FileX User Guide for the Renesas Synergy™ Platform for more details.
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 Mass Storage (ux_host_class_storage) | N/A | Pre-built library: 42KB Source: 39KB + UX_HOST_CLASS_STORAGE_MEMORY_BUFFER_SIZE + UX_HOST_CLASS_STORAGE_THREAD_STACK_SIZE+ (Add the additional memory as per Note*1 ) |
UX_THREAD_STACK_SIZE: 512 (bytes) for S1 parts; 2048 (bytes) for the other partsUX_THREAD_STACK_SIZE: 2048 (bytes)
This section describes how to include the USBX Host Class Mass Storage Module in an application using the SSP configurator.
To add the USBX Host Class Mass Storage Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
USBX Host Class Mass Storage Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_ux_host_class_storage USBX Host Class Mass Storage | Threads | New Stack> X-Ware> USBX> Device> Classes> Mass Storage > USBX Host Class Mass Storage |
When the USBX Host Class Mass Storage 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 Mass Storage 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 Mass Storage Module
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ux_host_class_storage0 | Module name. |
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 Mass Storage Source
| ISDE Property | Value | Description |
|---|---|---|
| Use FileX Stub | Enabled, Disabled Default: Disabled | UX_NO_FILEX Enable this option only in cases where FileX is not available to use. |
| Maximum number of SCSI logical units | Value must be greater than 0 or empty Default: 1 | UX_MAX_HOST_LUN The value represents the maximum number of SCSI logical units represented in the host storage class driver. |
| Maximum number of storage media instance | Value must be greater than 0 or empty Default: 1 | UX_HOST_CLASS_STORAGE_MAX_MEDIA The value represents the maximum number of storage media instances represented in the host storage class driver. |
| Storage memory size in bytes for FileX used for data transfer | Value must be greater than 512 or empty Default: 1024 | UX_HOST_CLASS_STORAGE_MEMORY_BUFFER_SIZE The value represents the block of memory in bytes for FileX to use when doing transfers. The value can be changed to save on memory space but should not be smaller than the media sector size. Because USB devices are SCSI devices and there is a great deal of overhead when doing read/writes, it is better to increase it for higher data throughput. |
| Maximum transfer size in bytes in one BOT data-transport phase | Value must be greater than 512 or empty Default: 1024 | UX_HOST_CLASS_STORAGE_MAX_TRANSFER_SIZE The value represents maximum size of memory chunk in bytes to send in one data-transport phase in the Bulk-Only Transport protocol. Large size of data transfer request is split into smaller chunks specified by this configuration. It is better to increase it for higher data throughput. Note: Sufficient numbers of TDs are required, when user changes this parameter for large size(FS more than 8KB and HS more the 64KB) of data transfer. Sufficient number of 'Maximum TDs' needs to be specified in USBX Source module(USBX Source property >> Common >> Maximum TDs). - Maximum TDs for FS mode (maximum data transfer size in bytes /64 bytes = TDs + additional TDs for SCSI wrapper commands). - Maximum TDs for HS mode (maximum data transfer size in bytes /512 bytes = TDs + additional TDs for SCSI wrapper commands). |
| Stack size for the Mass Storage Class internal thread | Value must be greater than 512 or empty Default: 1024 | UX_HOST_CLASS_STORAGE_THREAD_STACK_SIZE The value represents the stack size in bytes for Mass Storage Class internal thread named ux_storage_thread. |
| Timeout (in milliseconds) for a BOT transfer request | Value must be greater than 0 or empty Default: 100000 | UX_HOST_CLASS_STORAGE_TRANSFER_TIMEOUT_IN_MS The value represents timeout value in millisecond for a data transfer request in Bulk-Only Transport protocol. |
| Timeout (in milliseconds) for the status from a command in the Control/Bulk/Interrupt transport | Value must be greater than 0 or empty Default: 30000 | UX_HOST_CLASS_STORAGE_CBI_STATUS_TIMEOUT_IN_MS The value represents timeout value in millisecond for the status from a command, which is returned by the interrupt endpoint in the Control/Bulk/ Interrupt transport. The transport is mainly used by storage devices that have very slow read/write commands. |
| Host storage class dependency on Filex | Enabled, Disabled Default: Disabled | UX_HOST_CLASS_STORAGE_NO_FILEX If enabled, Filex dependency on host storage class is removed. |
| 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 Mass Storage Module; however, communication must be done after the Host is connected to the host.
The typical steps in using the USBX Host Class Mass Storage Module in an application are:
1. Get the first instance of the connected device with the ux_host_stack_class_instance_get API.
2. Wait until successful.
3. Wait for the device status to become live.
4. Wait for media to be mounted.
5. Access the file on the media with the FileX API.
These common steps are illustrated in a typical operational flow diagram in the following figure:
