@CHIP-RTOS - USB API Data Structures

IPC@CHIP® Documentation Index

In this section data structures are described that are needed with the USB API. These are defined in the header-file USB_API.H.
Notes:

Byte alignment is required for all data structures used within the API.

Component List

UsbError

typedef enum
{
  USB_ERROR_NO                =  0,
  USB_ERROR_ILLEGAL_ARGUMENT  = -1,
  USB_ERROR_OUT_OF_MEMORY     = -2,.
  USB_ERROR_RESOURCE_LACK     = -3,
  USB_ERROR_QUEUE_MAXIMUM     = -4,
  USB_ERROR_FEATURE_DISABLED  = -5,
  USB_ERROR_OUT_OF_INTERFACES = -6,
  USB_ERROR_OUT_OF_ENDPOINTS  = -7,
  USB_ERROR_RESET_SETUP       = -8,
  USB_ERROR_UNKNOWN_SERVICE   = -9,
  USB_ERROR_PROTOCOL          = -10,
  USB_ERROR_BUSY              = -11,
  USB_ERROR_OUT_OF_DEVICES    = -12,
  USB_ERROR_TIMEOUT           = -13,
  USB_ERROR_QUEUE_EMPTY       = -14
} UsbError;

Comments

This data type is used as the result of most USB functions. It indicates whether the function was executed successfully and if not what kind of error occured.

USB_ERROR_NO

The requested operation finished successfully.
USB_ERROR_ILLEGAL_ARGUMENT

An argument with an invalid value was passed.
USB_ERROR_OUT_OF_MEMORY

Memory needed for the requested operation could not be allocated.
USB_ERROR_RESOURCE_LACK

There is a lack of some kind of internally managed resources such as tasks, semaphores, buffers, etc.
USB_ERROR_QUEUE_MAXIMUM

A request could not be enqueued due to the resp. queue having reached its maximum.
USB_ERROR_FEATURE_DISABLED

The requested feature is not enabled. This error e.g. occures if you try to wakup the Host in Device mode when the Remote Wakeup Feature has been disabled by the Host previously.
USB_ERROR_OUT_OF_INTERFACES

There were not enough free interfaces/alternate settings left.
USB_ERROR_OUT_OF_ENDPOINTS

There were not enough free endpoints left.
USB_ERROR_RESET_SETUP

A reset occured or a SETUP token has been received on the resp. endpoint but the event has not yet been notified. The requested action cannot be performed in this situation. (Device mode only)
USB_ERROR_UNKNOWN_SERVICE

The software interrupt was triggered with an unknown service number.
USB_ERROR_PROTOCOL

The USB protocol was violated or the protocol indicated an error.
USB_ERROR_BUSY

A resource is temporarily not available, but might be available again later.
USB_ERROR_OUT_OF_DEVICES

This error code is currently not used on SC1x3/SC2x.
USB_ERROR_TIMEOUT

This error code is currently not used on SC1x3/SC2x.
USB_ERROR_QUEUE_EMPTY

This error code is currently not used on SC1x3/SC2x.

Top of list
Index page

UsbEventStatus

typedef enum
{
  USB_EVENT_RECEIVED = 0,
  USB_EVENT_SENT = 1,
  USB_EVENT_RESET = 2,
  USB_EVENT_SETUP = 3,
  USB_EVENT_SUSPEND = 4,
  USB_EVENT_RESUME = 5,
  USB_EVENT_SOF = 13,
  USB_EVENT_ATTACH = 14,
  USB_EVENT_DETACH = 15,
  USB_EVENT_RELEASE = 16,
  USB_EVENT_ERROR_BIT_STUFF = 6,
  USB_EVENT_ERROR_DMA = 7,
  USB_EVENT_ERROR_TURNAROUND = 8,
  USB_EVENT_ERROR_DATA_FIELD = 9,
  USB_EVENT_ERROR_CRC16 = 10,
  USB_EVENT_ERROR_CRC5 = 11,
  USB_EVENT_ERROR_PID = 12,
  USB_EVENT_NAK = 17,
  USB_EVENT_STALL = 18,
  USB_EVENT_ERROR_DATA_OVERRUN = 25,
  USB_EVENT_ERROR_DATA_TOGGLE = 19,
  USB_EVENT_ERROR_SOF_LOST = 20,
  USB_EVENT_ERROR_SOF_BANDWIDTH = 21,
  USB_EVENT_ERROR_ATTACH = 22,
  USB_EVENT_ERROR_LOST_EVENT = 23,
  USB_EVENT_ERROR_BANDWIDTH = 24,
  USB_EVENT_INVALID = -1
} UsbEventStatus;

Comments

This is the type of the status parameter passed along with callbacks. It indicates the type of event that has occured and decides what the meaning of the other parameters is.

USB_EVENT_RECEIVED

address

epNumber

buffer

length

usbFreeReceiveBuffer()

USB_SERVICE_FREE_RECEIVE_BUFFER

USB_EVENT_SENT

address

epNumber

buffer

length

USB_EVENT_RESET

USB_EVENT_SETUP

epNumber

USB_EVENT_RECEIVED

USB_EVENT_SUSPEND

USB_EVENT_RESUME

USB_EVENT_SOF

usbSofNotify()

USB_SERVICE_SOF_NOTIFY

USB_EVENT_ERROR_SOF_LOST

USB_EVENT_ERROR_SOF_BANDWIDTH

USB_EVENT_ATTACH

address

USB_EVENT_DETACH

address

USB_EVENT_RELEASE

usbHostClearQueue()

USB_SERVICE_HOST_CLEAR_QUEUE

buffer

The follwoing events indicate error conditions. If nothing else is stated, the callback parameter address indicates the device with which an error occured in Host mode or 0 in Device mode, epNumber indicates the resp. endpoint and length indicates whether the error occured while receiving or sending as a boolean value (TRUE = sending, FALSE = receiving).

USB_EVENT_ERROR_BIT_STUFF

Indicates that a bit stuff error was detected in the data stream on the bus. The resp. packet was rejected. The Host should repeat it.
USB_EVENT_ERROR_DMA

Fatal! There was a problem regarding DMA data transport between memory and the USB controller hardware. Data may be lost.
USB_EVENT_ERROR_TURNAROUND

A bus turnaround timeout occured. This means that too much time elapsed between two phases of a data transfer. This is likely to happen if the USB cable is too long.
USB_EVENT_ERROR_DATA_FIELD

Indicates that a data field did not consist of an integral number of bytes. The resp. packet was rejected. The Host should repeat it.
USB_EVENT_ERROR_CRC16 or USB_EVENT_ERROR_CRC5

USB_EVENT_ERROR_CRC5

USB_EVENT_ERROR_PID

A PID check field didn't match. This is similar to a checksum error. The resp. packet was rejected. The Host should repeat it.
USB_EVENT_NAK

A transaction on an INTERRUPT endpoint has been NAKed by the device. (Host mode only)
USB_EVENT_STALL

The device returned a STALL handshake on the given endpoint. (Host mode only)
USB_EVENT_ERROR_DATA_OVERRUN

This event is currently not used on SC1x3/SC2x.
USB_EVENT_ERROR_DATA_TOGGLE

USB_EVENT_RECEIVED

The three following error events do not relate to a special device or endpoint.
All callback parameters, except for the status, will be set to 0.

USB_EVENT_ERROR_SOF_LOST

USB_EVENT_SOF

USB_EVENT_ERROR_SOF_BANDWIDTH

USB_EVENT_SOF

USB_EVENT_ERROR_ATTACH

USB_EVENT_ERROR_LOST_EVENT

Fatal! An overrun occured in the ring queue used to manage events and events have been lost. USB_EVENT_ERROR_BANDWIDTH

This event is currently not used on SC1x3/SC2x.

UsbCallback

typedef void huge ( far *UsbCallback )( unsigned epNumber,
                                        UsbEventStatus status,
                                        void far *buffer,
                                        unsigned length,
                                        unsigned address );

Comments

This is the prototype for callback-functions that a user driver registers with the USB-API. The callback-function is used to notify asynchronous events to the application, such as received data packets or completed send-requests.
The functions usbHostInit() (interrupt service USB_SERVICE_HOST_INIT) and usbDeviceInit() (interrupt service USB_SERVICE_DEVICE_INIT) are used to install a callback-function.

epNumber

epNumber

status

UsbEventStatus

buffer

usbFreeReceiveBuffer()

USB_SERVICE_FREE_RECEIVE_BUFFER

length

address

address

UsbInit

typedef struct UsbInit_
{
  UsbCallback callback;
  unsigned char classCode;
  unsigned char subClassCode;
  unsigned char protocolCode;
  unsigned short vendorId;
  unsigned short productId;
  unsigned short versionBcd;
  char far *manufacturerString;
  char far *productString;
  char far *serialNumberString;
  char far *configString;
  BOOL_ selfPowered;
  unsigned char maxPowerConsumption;
  unsigned char pioNumber;
} UsbInit;

Comments

This structure is used to pass arguments to the interrupt service USB_SERVICE_DEVICE_INIT. It is not needed if you use the C-library function usbDeviceInit().

callback

Pointer to the callback-function that the USB-driver will call to notifiy the application of certain events
classCode

Class code of the device
subClassCode

Subclass code of the device
protocolCode

Protocol code of the device

The Host uses classCode, subClassCode and protocolCode to find an appropriate standard driver for the device. If classCode is 0xFF - which means that the device uses a vendor-specific protocol - the host uses vendor and product ID to find a driver.
classCode, subClassCode and protocolCode may also be set with interfaces. In this case the values here should be 0x00.
vendorId

USB Implementers Forum

productId

Product code of the device. The several devices of a vendor are differed by their product ID. The vendor is free to assign any product ID.
versionBcd

Release version of the device in BCD-format. This is used to distinguish several releases of the same product.

The following are human readable strings describing the device. The host may show these to the user. The maximum length of a string is USB_SPEC_MAX_STRING_LENGTH characters. If the string is longer it will be cut. Note that they have to be static, since the driver will not copy their content but only hold a pointer. If a string shall not be used, set the pointer to NULL.

manufacturerString

Pointer to manufacturer string (e.g. "Beck IPC GmbH")
productString

Pointer to product string (e.g. "IPC@CHIP SC123")
serialNumberString

Pointer to serial-number string (e.g. "123456-ABCDE")
configString

Pointer to configuration string
selfPowered

TRUE, if the device is self-powered
maxPowerConsumption

Maximum current that the device may draw from the bus. Given in steps of 2mA.
pioNumber

Number of PIO to be used to control attach- and speed-detection circuit; Refer to SC1x3 hardware manual. On SC2x this circuit is integrated at the chip and hardwired to PIO 26.

UsbDevice

typedef struct UsbDevice_
{
  unsigned short usbVersion;
  unsigned char classCode;
  unsigned char subClassCode;
  unsigned char protocolCode;
  unsigned char maxPacketSizeEp0;
  unsigned short vendorId;
  unsigned short productId;
  unsigned short version;
  unsigned char manufacturerStringIndex;
  unsigned char productStringIndex;
  unsigned char serialNumberStringIndex;
  unsigned char nConfiguration;
} UsbDevice;

Comments

This structure represents the information from the Device Descriptor of a device. It is returned by the API function usbHostGetDeviceInfo() (Interrupt service USB_SERVICE_HOST_GET_DEVICE_INFO). For detailed information on the Device Descriptor refer to the USB specification.

usbVersion

USB specification version that the device supports, encoded in BCD
classCode

Class code of the device
subClassCode

Subclass code of the device
protocolCode

Protocol code of the device

Class code, Subclass code and Protocol code are used to find an appropriate standard driver for the device. If classCode is 0xFF - which means that the device uses a vendor-specific protocol - vendor and product ID are used to find a driver.
classCode, subClassCode and protocolCode may also be set with interfaces. In this case the values here will be 0x00.

maxPacketSizeEp0

Maximum packet size supported on endpoint 0
vendorId

USB Implementers Forum

productId

Product code of the device. The several devices of a vendor are differed by their product ID. The vendor is free to assign any product ID.
version

Release version of the device in BCD-format.

If the Class code of the device is 0xFF, the device uses a vendor-specific protocol. Vendor and product ID as well as the product version are used to find an appropriate driver. Still it is possible that single interfaces are handled by a standard driver.

manufacturerStringIndex, productStringIndex and serialNumberStringIndex

usbHostGetString()

USB_SERVICE_HOST_GET_STRING

nConfigurations

The RTOS USB-driver doesn't support more than 1 Configuration. So this field will always have the value 1.

UsbConfig

typedef struct UsbConfig_
{
  unsigned char nInterface;
  unsigned char stringIndex;
  BOOL_ selfPowered;
  BOOL_ remoteWakeup;
  unsigned char maxPowerConsumption;
  char *specificDesc;
  unsigned short specificDescLength;
} UsbConfig;

Comments

This structure represents the information from the Configuration Descriptor of a device. It is returned by the API function usbHostGetConfigInfo() (Interrupt service USB_SERVICE_HOST_GET_CONFIG_INFO). For detailed information on the Configuration Descriptor refer to the USB specification.

nInterface

Number of Interfaces defined in this Configuration
stringIndex

usbHostGetString()

USB_SERVICE_HOST_GET_STRING

selfPowered

TRUE, if the device is self-powered (i.e. it has its own power supply)
remoteWakeup

TRUE, if the device supports the Remote Wakeup Feature
maxPowerConsumption

CHIP.INI

specificDesc

Class- or vendor-specific descriptor(s) assigned to the Configuration. Don't manipulate this data.
speceifcDescLength

Length of the class- or vendor-specific descriptor data in bytes.

UsbInterface

typedef struct UsbInterface_
{
  unsigned char nAltSetting;
  unsigned char nEp;
  unsigned long epBitmap;
  unsigned char classCode;
  unsigned char subClassCode;
  unsigned char protocolCode;
  unsigned char stringIndex;
  char *specificDesc;
  unsigned short specificDescLength;
} UsbInterface;

Comments

This structure represents the information from an Interface Descriptor. It is returned by the API function usbHostGetInterfaceInfo() (Interrupt service USB_SERVICE_HOST_GET_INTERFACE_INFO). For detailed information on the Interface Descriptor refer to the USB specification.

nAltSetting

Number of Alternate Settings the interface has
nEp

Number of Endpoints assigned to the Interface/Alternate Setting
epBitmap

Bitmap field representing the the endpoint numbers that are assigned to the interface. IN and OUT endpoints are distinguished here. The lower 16 bit represent the OUT endpoints, the higher 16 bit represent the IN endpoints. If e.g. bit 3 ist set, endpoint 3 OUT is assigned to the interface. If bit 31 is set, endpoint 15 IN is assigned to the interface. For control endpoints both directions are assigned of course. So if the control endpoint 4 is assigned to the interface, the bits 4 and 20 are set.
classCode

Class code of the Interface
subClassCode

Subclass code of the Interface
protocolCode

Protocol code of the Interface

For details on these codes refer to the description of the structure UsbDevice.

stringIndex

usbHostGetString()

USB_SERVICE_HOST_GET_STRING

specificDesc

Class- or vendor-specific descriptor(s) assigned to the Interface. Don't manipulate this data.
speceifcDescLength

Length of the class- or vendor-specific descriptor data in bytes.

UsbEp

typedef struct UsbEp_
{
  unsigned char transferType;
  unsigned short maxPacketSize;
  unsigned char interval;
  char *specificDesc;
  unsigned short specificDescLength;
} UsbEp;

Comments

This structure represents the information from an Endpoint Descriptor. It is returned by the API function usbHostGetEpInfo() (Interrupt service USB_SERVICE_HOST_GET_EP_INFO). For detailed information on the Endpoint Descriptor refer to the USB specification.

transferType

USB_SPEC_TRANSFER_TYPE_CONTROL
USB_SPEC_TRANSFER_TYPE_ISOCHRONOUS
USB_SPEC_TRANSFER_TYPE_BULK
USB_SPEC_TRANSFER_TYPE_INTERRUPT

maxPacketSize

The maximum packet size of this endpoint
interval

The interval at which this endpoint is polled by the Host if it is an INTERRUPT or ISOCHRONOUS endpoint. The interval is measured in 1-ms-frames.
specificDesc

Class- or vendor-specific descriptor(s) assigned to the Endpoint. Don't manipulate this data.
speceifcDescLength

Length of the class- or vendor-specific descriptor data in bytes.

@CHIP-RTOS - USB API Data Structures

Component List

UsbError

Comments

UsbEventStatus

Comments

Related Topics

UsbCallback

Comments

Related Topics

UsbInit

Comments

Related Topics

UsbDevice

Comments

Related Topics

UsbConfig

Comments

Related Topics

UsbInterface

Comments

Related Topics

UsbEp

Comments

Related Topics