 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The USBX™ Host Class Video module provides a high-level API for USBX Host Class Video applications and configures the USBX Host Class Video Source, USBX Host Configuration, USBX Source and USBX Port Host Controller Device. The USBX Host Class Video module uses the USB peripheral on the Synergy MCU.
Unsupported Features
Multiple instances of the USB device class are not supported on two different physical interfaces.
The USBX Host Class Video Module does not have an API for the user application.
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 Video (ux_host_class_video) | N/A | 35KB |
UX_THREAD_STACK_SIZE: 512 (bytes) for S1 parts; 2048 (bytes) for the other partsTo specify an Alt. setting in an interface in the UVC (USB video class) device, you may need to use the USBX API ux_host_class_video_ioctl() instead of ux_host_class_video_start(), specifying UX_HOST_CLASS_VIDEO_IOCTL_CHANNEL_START for the argument "ioctl_function". You also need to specify the argument parameter with setting the member .ux_host_class_video_parameter_channel_bandwidth_selection to match to the wMaxPacketSize of an isochronous endpoint. For instance, if .ux_host_class_video_parameter_channel_bandwidth_selection is set to 1024 for a UVC device with the device descriptor shown in the following figure, the IF1 Alt.1 will not be selected (since it requires high-bandwidth transfer). Instead, IF1 Alt.2 will be selected. For limitations of isochronous transfers, see section "Logic USBX Synergy
Port Framework Limitations."
This section describes how to include the USBX Host Class Video Module in an application using the SSP configurator.
To add the USBX Host Class Video Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
USBX Host Class Video Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_ux_host_class_video0 USBX Host Class Video | Threads | New Stack> X-Ware> USBX> Host > Classes > Video > USBX Host Class Video |
When the USBX Host Class Video 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 Video 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 Video Module
| ISDE Property | Value | Description |
|---|---|---|
| Class Instance Name | g_ux_host_class_video0 | Class instance 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.
The USBX Host Class Printer Module defines APIs, which are used to interact with the Printer interface. 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 PRINTER Module Summary
| Function Name | Example API Call and Description |
|---|---|
| ux_host_class_printer_read | UINT ux_host_class_printer_read (UX_HOST_CLASS_PRINTER *printer, UCHAR *data_pointer, ULONG requested_length, ULONG *actual_length)This function reads from the printer interface. The call is blocking and only returns when there is either an error or when the transfer is complete. A read is allowed only on bi-directional printers. |
| ux_host_class_printer_write | UINT ux_host_class_printer_write (UX_HOST_CLASS_PRINTER *printer,UCHAR *data_pointer, ULONG requested_length,ULONG *actual_length)This function writes to the printer interface. The call is blocking and only returns when there is either an error or when the transfer is complete. |
| ux_host_class_printer_soft_reset | UINT ux_host_class_printer_soft_reset (UX_HOST_CLASS_PRINTER *printer)This function performs a soft reset to the printer |
| ux_host_class_printer_status_get | UINT ux_host_class_printer_status_get (UX_HOST_CLASS_PRINTER *printer,ULONG *printer_status)This function obtains the printer status. The printer status is similar to the LPT status (1284 standard). |
| _ux_host_class_printer_name_get | UINT _ux_host_class_printer_name_get(UX_HOST_CLASS_PRINTER *printer)This function obtains the Device ID string. |
Return Values
| Name | Description |
|---|---|
| UX_SUCCESS | This operation was successful. |
| UX_FUNCTION_NOT_SUPPORTED | Function not supported because the printer is not bi-directional. |
| UX_TRANSFER_TIMEOUT | Transfer timeout, reading or writing is incomplete, or reset not completed. |
| UX_MEMORY_INSUFFICIENT | Not enough memory to perform the operation. |
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 Video Module; however, communication must be done after the Host is connected to the host.
The typical steps in using the USBX Host Class Video Module in an application are:
1. Wait until the device is inserted using the tx_event_flags_get API function
2. Set the camera parameters using the ux_host_class_video_frame_parameters_set API function
3. Set the user callback function using the ux_host_class_video_transfer_callback_set API function
4. Get the maximum memory buffer size using the ux_host_class_video_max_payload_get API function
5. Start video transfer using the ux_host_class_video_start API function
6. Add a video buffer to the video device using the ux_host_class_video_transfer_buffer_add API function
7. Wait for a received data frame using the tx_semiphore_get API function
8. Add the video buffer back using the ux_host_class_video_transfer_buffer_add API function
9. Stop the video transfer using the ux_host_class_video_stop API function
These common steps are illustrated in a typical operational flow diagram in the following figure:
