API
The XMOS USB Device library is provided by module_xud and the USB Device Helper Functions are provided by module_usb_device.
The APIs of module_xud is listed in XMOS USB Device (XUD) Library. The API of module_usb_device is detailed in this section.
Please note, both module_xud and module_usb_device depend on the module module_usb_shared
module_usb_shared
USB_SetupPacket_t
This structure closely matches the structure defined in the USB 2.0 Specification:
typedef struct USB_SetupPacket { USB_BmRequestType_t bmRequestType; /* (1 byte) Specifies direction of dataflow, type of rquest and recipient */ unsigned char bRequest; /* Specifies the request */ unsigned short wValue; /* Host can use this to pass info to the device in its own way */ unsigned short wIndex; /* Typically used to pass index/offset such as interface or EP no */ unsigned short wLength; /* Number of data bytes in the data stage (for Host -> Device this this is exact count, for Dev->Host is a max. */ } USB_SetupPacket_t;
module_usb_device
USB_GetSetupPacket()
-
XUD_Result_t USB_GetSetupPacket(XUD_ep ep_out, XUD_ep ep_in, USB_SetupPacket_t &sp)
Receives a Setup data packet and parses it into the passed USB_SetupPacket_t structure.
Parameters
ep_out
OUT endpint from XUD
ep_in
IN endpoint to XUD
sp
SetupPacket structure to be filled in (passed by ref)
Returns
Returns XUD_RES_OKAY on success, XUD_RES_RST on bus reset
USB_StandardRequests()
This function takes a populated USB_SetupPacket_t structure as an argument.
-
XUD_Result_t USB_StandardRequests(XUD_ep ep_out, XUD_ep ep_in, ?_ARRAY_OF(unsigned char, devDesc_hs), int devDescLength_hs, ?_ARRAY_OF(unsigned char, cfgDesc_hs), int cfgDescLength_hs, ?_ARRAY_OF(unsigned char, devDesc_fs), int devDescLength_fs, ?_ARRAY_OF(unsigned char, cfgDesc_fs), int cfgDescLength_fs, char *unsafe strDescs[], int strDescsLength, USB_SetupPacket_t &sp, chanend ?c_usb_test, XUD_BusSpeed_t usbBusSpeed)
This function deals with common requests This includes Standard Device Requests listed in table 9-3 of the USB 2.0 Spec all devices must respond to these requests, in some cases a bare minimum implementation is provided and should be extended in the devices EP0 code It handles the following standard requests appropriately using values passed to it:.
Get Device Descriptor (using devDesc_hs/devDesc_fs arguments)
Get Configuration Descriptor (using cfgDesc_hs/cfgDesc_fs arguments)
String requests (using strDesc argument)
Get Device_Qualifier Descriptor
Get Other-Speed Configuration Descriptor
Set/Clear Feature (Endpoint Halt)
Get/Set Interface
Set Configuration
If the request is not recognised the endpoint is marked STALLED
Parameters
ep_out
Endpoint from XUD (ep 0)
ep_in
Endpoint from XUD (ep 0)
devDesc_hs
The Device descriptor to use, encoded according to the USB standard
devDescLength_hs
Length of device descriptor in bytes
cfgDesc_hs
Configuration descriptor
cfgDescLength_hs
Length of config descriptor in bytes
devDesc_fs
The Device descriptor to use, encoded according to the USB standard
devDescLength_fs
Length of device descriptor in bytes. If 0 the HS device descriptor is used.
cfgDesc_fs
Configuration descriptor
cfgDescLength_fs
Length of config descriptor in bytes. If 0 the HS config descriptor is used.
strDescs
strDescsLength
sp
USB_SetupPacket_t (passed by ref) in which the setup data is returned
c_usb_test
Optional channel param for USB test mode support
usbBusSpeed
The current bus speed (XUD_SPEED_HS or XUD_SPEED_FS)
Returns
Returns XUD_RES_OKAY on success.
Standard Device Request Types
USB_StandardRequests() handles the following Standard Device Requests:
- SET_ADDRESS
- The device address is set in XUD (using XUD_SetDevAddr()).
- SET_CONFIGURATION
- A global variable is updated with the given configuration value.
- GET_STATUS
- The status of the device is returned. This uses the device Configuration descriptor to return if the device is bus powered or not.
- SET_CONFIGURATION
- A global variable is returned with the current configuration last set by SET_CONFIGURATION.
- GET_DESCRIPTOR
- Returns the relevant descriptors. See Device Descriptors for further details.
Note, some changes of returned descriptor will occur based on the current bus speed the
device is running.
- DEVICE
- CONFIGURATION
- DEVICE_QUALIFIER
- OTHER_SPEED_CONFIGURATION
- STRING
- Returns the relevant descriptors. See Device Descriptors for further details.
Note, some changes of returned descriptor will occur based on the current bus speed the
device is running.
In addition the following test mode requests are dealt with (with the correct test mode set in XUD):
- SET_FEATURE
- TEST_J
- TEST_K
- TEST_SE0_NAK
- TEST_PACKET
- FORCE_ENABLE
Standard Interface Requests
USB_StandardRequests() handles the following Standard Interface Requests:
- SET_INTERFACE
- A global variable is maintained for each interface. This is updated by a SET_INTERFACE. Some basic range checking is included using the value numInterfaces from the ConfigurationDescriptor.
- GET_INTERFACE
- Returns the value written by SET_INTERFACE.
Standard Endpoint Requests
USB_StandardRequests() handles the following Standard Endpoint Requests:
- SET_FEATURE
- CLEAR_FEATURE
- GET_STATUS
If parsing the request does not result in a match, the request is not handled, the Endpoint is marked “Halted” (Using XUD_SetStall_Out() and XUD_SetStall_In()) and the function returns XUD_RES_ERR.
The function returns XUD_RES_OKAY if a request was handled without error (See also Status Reporting).