Home

Stellaris USB Library User's Guide

1. m Add a transmit event handler function YourUSBTransmitEventCallback in the previous exam ple to your application taking care to handle all messages which require a particular response For the generic bulk device class there are no events sent to the transmit callback which MUST be handled but applications will usually want to note USB EVENT TX COMPLETE since this is an interlock message indicating that the previous packet sent has been acknowledged by the host and a new packet can now be sent m From your main initialization function call the generic bulk device class driver initialization function to configure the USB controller and place the device on the bus pDevice USBDBulkInit 0 amp g sBulkDevice m Assuming pDevice returned is not NULL your device is now ready to communicate with a USB host m Once the host connects your receive event handler will be sent USB EVENT CONNECTED and the first packet of data may be sent to the host using USBDBulkPacketWrite with following packets transmitted as soon as USB EVENT TX COMPLETE is received Using the Composite Bulk Device Class When using the bulk device class in a composite device the configuration of the device is very similar to how it is configured as a non composite device Follow all of the configuration steps in the previous secti
2. Endpoint 0 lt lt gt USB Driver USB Device API HID Class Driver Receive Channel Device Functions Transmit Channel Application Code This device class uses one or optionally two endpoints in addition to endpoint zero One interrupt IN endpoint carries HID input reports from the device to the host Output and Feature reports from the host to the device are typically carried via endpoint zero but devices which expect high host to device data rates can select to offer an independent interrupt OUT endpoint to carry these Endpoint zero carries standard USB requests and also HID specific descriptor requests The HID mouse and keyboard device APIs described later in this document are both implemented above the HID Device Class Driver API The HID device class driver sends the following events to the application callback functions 3 13 1 HID Device Class Events 3 13 1 1 Receive Channel Events W USB EVENT CONNECTED W USB EVENT DISCONNECTED W USB EVENT RX AVAILABLE E USB EVENT ERROR E USB EVENT SUSPEND W USB EVENT RESUMF E USBD HID EVEN IDLE TIMEOUT m USBD HID EVENT GET REPORT BUFFER E USBD HID EVENT GET REPORT m USBD HID EVEN SET PROTOCOL m USBD HI
3. One other condition may cause an input report to be sent Each input report has a timeout associ ated with it and when this time interval expires the report must be returned to the host regardless of whether or not the device state has changed The timeout is set using a Set Idle request from the host and may be completely disabled as is typically done for mice and keyboards when com municating with a Windows PC for example by setting the timeout to O The HID device class driver internally tracks the required timeouts for each input report When a timer expires indicating that the report must be resent USBD HID EVENT IDLE TIMEOUT is sent to the application receive callback As in the previous case the application must respond with a pointer to the appropriate report and its length in bytes In this case the returned report is transmitted to the host using the interrupt IN endpoint and the successful completion of the transmission is notified to the application using USB EVENT TX COMPLETE sent to the transmit callback Note that the application returns information on the location and size of the report and MUST NOT call USBDHIDReportWrite in response to this event Output and Feature reports are sent from the host to the device to instruct it to set various parame ters and options A device can chose whether all host to device report communication takes place via endpoint zero or whether a dedicated interrupt OUT e
4. T_LINE_CODING ET LINE CODING SB EVENT CONNECTED SB EVENT DISCONNECTED SB EVENT SUSPEND SB EVENT RESUME SBD CDC EVENT SEND BREAK SBD CDC EVENT CLEAR BREAK SBD CDC EVENT SF SBD CDC EVENT G SBD CDC EVENT S ET CONTROL LIN E STATE Note In device mode the USB EVENT DISCONNECTED event will not be reported to the appli cation if the MCU s PB1 USBOVBUS pin is connected to a fixed 5 Volts rather than directly to the VBUS pin on the USB connector 3 7 2 Using the CDC Device Class Driver To add USB CDC data transmit and receive capability to your application via the CDC Device Class Driver take the following steps m Add the following header files to the source file s which are to support USB 88 include include include include src usb h usblib usblib h usblib device usbdevice h usblib device usbdcdc h Define the 6 entry string descriptor table which is used to describe various features of your new device to the host system The following is the string table taken from the usb dev serial example application Edit the actual strings to suit your application and take care to ensure that you also update the length field the first byte of each descriptor to correctly reflect the length of the string and descriptor header The number of string descriptors you include must be 1 5 num languages where the number of languages ag
5. USBDCDInit 0 amp g sMouseDeviceInfo 3 22 USB Device API Definitions Data Structures m tConfigHeader m tConfigSection m tCustomHandlers m tFIFOConfig m tFIFOEntry Defines m USB MAX INTERFACES PER DEVICE Functions void USBODevicelntHandler void void USBDCDInit unsigned long ullndex tDevicelnfo psDevice void USBDCDPowerStatusSet unsigned long ullndex unsigned char ucPower tBoolean USBDCDRemoteWakeupRequest unsigned long ullndex void USBDCDRequestDataEPO unsigned long ullndex unsigned char pucData unsigned long ulSize void USBDCDSendDataEP0 unsigned long ullndex unsigned char pucData unsigned long ulSize void USBDCDSetDefaultConfiguration unsigned long ullndex unsigned long ulDefaultConfig void USBDCDSiallEPO unsigned long ullndex void USBDCDTerm unsigned long ullndex tBoolean USBDeviceConfig tDevicelnstance psDevlInst const tConfigHeader psConfig tBoolean USBDeviceConfigAlternate tDevicelnstance xpsDevinst const tConfigHeader psConfig unsigned char uclnterfaceNum unsigned char ucAlternateSetting Variables m const tFlIFOConfig g sUSBDefaultFIFOConfig September 05 2012 197 Device Functions 3 22 1 3 22 1 1 3 22 1 2 3 22 1 3 198 Data Structure Documentation tConfigHeader Definition typedef struct unsigned char ucNumSections const tConfigSection const xpsSections tConfigHeader Members ucNumSections The number of sections co
6. LIBUSB DEV NTAMD64 HW DelReg libusb del reg hw AddReg libusb add reg hw LIBUSB DEV NT Services AddService libusb0 0x00000002 libusb add service LIBUSB DEV NTAMD64 Services AddService libusb0 0x00000002 libusb add service libusb add reg R DevLoader ntkern R NTMPDriver libusbO0 sys Ier m Older versions of this inf file installed filter drivers They are not needed any more and must be removed libusb_del_reg_hw HKR LowerFilters HKR UpperFilters Device properties libusb_add_reg_hw HKR SurpriseRemovalOK 0x00010001 1 libusb add service DisplayName LibUsb Win32 Kernel Driver 03 20 2007 0 1 12 1 ServiceType 1 September 05 2012 Device Functions StartType 3 ErrorControl 0 ServiceBinary 12 libusb0 sys Devices Generic Bulk Device LIBUSB DEV USB VID_lcbe amp PID_0003 Devices NT Generic Bulk Device LIBUSB DEV USBNVID 1cbe amp PID 0003 Devices NTAMD64 Generic Bulk Device LIBUSB DEV USBNVID 1cbe amp PID 0003 Strings manufacturer Texas Instruments 3 6 Bulk Device Class Driver Definitions Data Structures m tUSBDBulkDevice Defines m COMPOSITE DBULK SIZE Functions m void x USBDBulkCompositelnit unsigned long ullndex const tUSBDBulkDevice psDevice m void x USBDBulklnit unsigned long ullndex const tUSBDBulkDevice psDevice m unsigned long USBDBulkPacketRead void
7. Returns Returns the number of descriptors found in the supplied block of data USBDescGetNumaAlternatelnterfaces Determines the number of different alternate configurations for a given interface within a configura tion descriptor Prototype unsigned long USBDescGetNumAlternateInterfaces tConfigDescriptor xpsConfig unsigned char ucInterfaceNumber Parameters psConfig points to the first byte of a standard USB configuration descriptor ucinterfaceNumber is the interface number for which the number of alternate configurations is to be counted Description This function can be used to count the number of alternate settings for a specific interface within a configuration Returns Returns the number of alternate versions of the specified interface or O if the interface number supplied cannot be found in the config descriptor USBDualModelnit Initializes the USB controller for dual mode operation Prototype void USBDualModeInit unsigned long ulIndex Parameters ullndex specifies the USB controller that is to be initialized for dual mode operation This parameter must be set to 0 Description This function initializes the USB controller hardware into a state suitable for dual mode op eration Applications may use this function to ensure that the controller is in a neutral state and able to receive appropriate interrupts before host or device mode is chosen using a call to USBStackModeSet September 05
8. General Purpose Functions 2 3 2 3 1 26 For successful dual mode mode operation an application must register USBODualModelntHandler as the interrupt handler for the USBO interrupt This han dler is responsible for steering interrupts to the device or host stack depending upon the chosen mode Devices which do not require dual mode capability should reg ister either USBODevicelntHandler or USBOHostIntHandler instead Registering USBODualModelntHandler for a single mode application will result in an application bi nary larger than required since library functions for both USB operating modes will be included even though only one mode is required Single mode applications those offering exclusively USB device or USB host functionality are only required to call this function if they need to force the mode of the controller to Host or Device mode This is usually in the event that the application needs to reused the USBVBUS and or USBID pins as GPIOs Note Forcing of the USB controller mode feature is not available on all Stellaris microcontrollers Consult the data sheet for the microcontroller that the application is using to determine if this feature is available Returns None USB Chapter 9 Definitions Data Structures m tConfigDescriptor m tDescriptorHeader m tDeviceDescriptor m tDeviceQualifierDescriptor m tEndpointDescriptor m tinterfaceDescriptor m tStringODescriptor m tStringDescriptor m tUSB
9. The pvinstance is a pointer to an instance of the device being accessed The ulRequest is USB EVENT COMP IFACE CHANGE The pvRequestData is a pointer to a two byte array where the first value is the old interface number and the second is the new interface number 2 2 3 5 USB EVENT COMP STR CHANGE Definition define USB EVENT COMP STR CHANGE Description This define is used with a device class s pfnDeviceHandler handler function to indicate that the USB library has changed the string index number for a string This event is typically due to the class being included in a composite device The pvinstance is a pointer to an instance of the device being accessed The ulRequest is USB EVENT COMP STR CHANGE The pvHequestData is a pointer to a two byte array where the first value is the old string index and the second is the new string index September 05 2012 11 General Purpose Functions 2 2 3 6 2 2 3 7 2 2 3 8 2 2 3 9 2 2 3 10 12 USB_EVENT_CONNECTED Definition define USB_EVENT_CONNECTED Description The device is now attached to a USB host and ready to begin sending and receiving data used by device classes only USB_EVENT_DATA_REMAINING Definition define USB EVENT DATA REMAINING Description This event is sent by a lower layer to inquire about the amount of unprocessed data buffered in the layers above It is used in cases where a lo
10. amp g_sCDCDeviceA g sCompDevice psCompInfo 1 pvInstance USBDCDCCompositeInit 0 tUSBDCDCDevice amp g_sCDCDeviceB Pass the device information to the USB library and place the device on the bus J USBDCompositeInit 0 amp g sCompDevice COMPOSITE DCDC SIZEx2 pucDesciptorData When calling the USB device classes that were included with the composite device the instance data for that class should be passed into the API In the composite serial example that is being described in this section the USB serial device classes provide the same callback function Con trolHandler The callback information for this was the device class structure which was specified as g_sCDCDeviceA org sCDCDeviceB for the serial devices Since the device instance is different for each serial device the application can simply cast the pointer to a pointer of type tUSBDCD CDevice and use the data directly as shown below and only access the requested device unsigned long ControlHandler void pvCBData unsigned long ulEvent unsigned long ulMsgValue void xpvMsgData tUSBDCDCDevice pCDCDevice pCDCDevice tUSBDCDCDevice x pvCBData Which event are we being asked to process switch ulEvent Composite Device Class Driver Definitions Data Structures m tCompositeEntry m tUSBDCompositeDevice September 05 2012 111 Device Functions 3 10 1 3 10 2 3 10 2 1 3 10 2 2 112 Functions
11. ulPoolSize is the size in bytes of the memory pool provided by the pucHubPool parameter psHubinstance is a pointer to an instance of the private hub data ulNumHubs is the number of hubs to support Description This function is called to open an instance of a host hub device and provides a valid callback function for host hub events in the pfnCallback parameter This function must be called before the USB host code can successfully enumerate a hub device or any devices attached to the hub The pucHubPool is memory provided to the hub class to manage the devices that are connected to the hub The u PoolSize is the number of bytes and should be at least 32 bytes per device including the hub device itself A simple formula for providing memory to the hub class is MAX USB DEVICES 32 bytes of data to allow for proper enumeration of connected devices The value for MAX USB DEVICES is defined in the usblib h file and controls the number of devices supported by the USB library The u NumHubs parameter defaults to one and only one buffer of size tHubInstance is required to be passed in the psHub nstance parameter Note Changing the value of MAX USB DEVICES requires a rebuild of the USB library to have an effect on the library Returns This function returns the driver instance to use for the other host hub functions If there is no instance available at the time of this call this function returns zero USBHMSCBlockRead This function performs
12. General Purpose Functions 2 4 6 5 2 4 6 6 42 Returns None USBBufferEventCallback Called by the USB buffer to notify the client of asynchronous events Prototype unsigned long USBBufferEventCallback void xpvCBData unsigned long ulEvent unsigned long ulMsgValue void xpvMsgData Parameters pvCBDaia is the client supplied callback pointer associated with this buffer instance ulEvent is the identifier of the event being sent This will be a general event identi fier of the form USBD EVENT xxxx or a device class dependent event of the form USBD CDC EVENT xxx or USBD HID EVENT xxx ulMsgValue is an event specific parameter value pvMsgData is an event specific data pointer Description This function is the USB buffer event handler that applications should register with the USB device class driver as the callback for the channel which is to be buffered using this buffer Note This function will never be called by an application It is the handler that allows the USB buffer to be inserted above the device class driver or host pipe driver and below the application to offer buffering support Returns The return value is dependent upon the event being processed USBBufferFlush Flushes a USB buffer discarding any data that it contains Prototype void USBBufferFlush const tUSBBuffer xpsBuffer Parameters psBuffer is the pointer to the buffer instance which is to be flushed Description This
13. None USBDCDCTxPacketAvailable Returns the number of free bytes in the transmit buffer Prototype unsigned long USBDCDCTxPacketAvailable void pvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDCInit Description This function returns the maximum number of bytes that can be passed on a call to USBDCD CPacketWrite and accepted for transmission The value returned will be the maximum USB packet size 64 if no transmission is currently outstanding or 0 if a transmission is in progress Returns Returns the number of bytes available in the transmit buffer Composite Device Class Driver The USB composite device class allows classes that are already defined in the USB library to be combined into a single composite device The device configuration descriptors for the included device classes are merged at run time and returned to the USB host controller during device enumeration as a single composite USB device Since each device class requires some unique September 05 2012 105 Device Functions 3 9 1 106 initialization the device classes provide a separate initialization API that does not touch the USB controller but does perform all other initialization The initialization of the USB controller is deferred until the USB composite device is initialized and has merged the multiple device configuration de scriptors into a single configuration descriptor so that it can p
14. The OTHER_SIZES here are the sizes of the descriptor data for other classes that are part of the composite device ah define DESCRIPTOR DATA SIZE COMPOSITE DHID SIZE OTHER SIZES unsigned char g pucDescriptorData DESCRIPTOR DATA SIZE tCompositeEntry psCompEntries 2 Set the generic HID device information psCompEntries 0 psDevice g sHIDDeviceInfo Save the instance data for this HID mouse device psCompEntries 0 pvInstance USBDHIDMouseCompositeInit 0 amp g sHIDMouseDevice Initialize other devices to add to the composite device Save the device entries in the composite device as g_sCompDevice psDevices psCompEntries USBDCompositeInit 0 amp g sCompDevice DESCRIPTOR DATA SIZE g pucDescriptorData 130 September 05 2012 3 13 4 Device Functions All other API calls to the USB HID mose device class should use the value returned by USBD HIDMouseCompositelnit when the API calls for a pvinstance pointer Also when using the audio device in a composite device the COMPOSITE_DHID_SIZE value should be added to the size of the g_pucDescriptorData array as shown in the example above Handling HID Reports Communication between a HID device and host takes place using data structures known as re ports Input reports are sent from the device to the host in response to device state changes queries from the host or a configurable timeout In the case of a
15. The psPrivateData should be set to point to a tCompositelnstance structure which provides the composite class with memory for its instance data Note It is important to insure that Stellaris microcontroller has enough endpoints to satisfy the number of devices included in the composite class Example tCompositeInstance g CompInstance unsigned long g pulCompWorkspace NUM DEVICES tUSBDCompositeDevice g sCompDevice ff Vendor ID VENDOR_ID Product ID Fi VENDOR_PRODUCT_ID if This is in 2mA increments or 500mA 250 Bus powered device tl USB_CONF_ATTR_BUS_PWR Generic USB handler for the composite device September 05 2012 3 9 2 3 9 2 1 Device Functions CompositeHandler The string table g_pStringDescriptors NUM_STRING_DESCRIPTORS The number of device classes in the composite entry array NUM_DEVICES g_psCompDevices The instance data for the composite class The first value provided here must point to a buffer containing NUM DEVICES unsigned longs This is used by the composite device class to hold a lookup table allowing it to correctly steering callbacks to the relevant interface or endpoint The second value is a pointer to the class instance structure which provides storage for state information required for operation of the class g_pulCompWorkspace amp g_CompInstanc
16. kk kk RRR kk oko ke kk Kok kk ko ok kk Kok kk Kok kk kk kk kk kk kk kk Kok kk kk kk kk kk kk ke kk ko ke kk kk kk ke ke ek e ee const unsigned char g pSerialNumberString 2 8 x 2 USB_DTYPE_STRING eLA Oy tat Uy CASS O ftus Ou COSI Day CE Op aT e Oe ta i Merete eee cee eee ee eee ee eS Pee eee eee ee eee eee eee eee eee ckck ckck ck ck ckckck ck ckck ck eee The control interface description string T A I A kk ko I oe const unsigned char g pControlInterfaceString 2 21 2 USB_DTYPE_STRING A 0 C 0 M 0 fa 0 a Shee 0 ONG 0 n 0 tt 0 EU 0 ro 0 Ear 0 r E 0 rar 0 nf 0 rd 0 re 0 tet Uu ERE ye Uu cate cO TEC Dus tet September 05 2012 89 Device Functions 90 T C IRR ROR IR RR IR I OR IR ke kk ko ke kk ko ke e ke Ke ke oe The configuration description string J kk kk koe kk ko ke kk ke kk kk kk kk OR kk kk IRR RRR IR ORR IR IR IR ke kk ko ke kk ko ke e ke Ke oe const unsigned char g pConfigString 2 26 2 USB_DTYPE_STRING S 0 tet 0 flit 0 f 0 t 0 tB 0 tot 0 wl 0 het 0 JEU 0 i a 0 rar 0 n t 0 Ct 0 o 0 n 0 f 0 Ut 0 g 0 eru 0 xr 0 a 0 ne 0 F5 0 0 0 Tol o Fur r nn J kk ke kk koe kk kk kk kk ke kk ke kk ck ke ke kk kk ckock Sk kk ck kc kck ck kc kck ck kk ck ck kk ck ck ck ck ck ck ck ckckck ck ck kckckckck ck ck ck ckck ck oko The des
17. void USBHCDInit unsigned long ullndex void pvPool unsigned long ulPoolSize Description This function is used to initialize the HCD code Parameters ullndex specifies which USB controller to use pvPool is a pointer to the data to use as a memory pool for this controller ulPoolSize is the size in bytes of the buffer passed in as pvPool This function will perform all the necessary operations to allow the USB host controller to begin enumeration and communication with devices This function should typically be called once at the start of an application once all of the device and class drivers are ready for normal opera tion This call will start up the USB host controller and any connected device will immediately start the enumeration sequence The USBStackModeSet function can be called with USB MODE HOST in order to cause the USB library to force the USB operating mode to a host controller This allows the application to used the USBVBUS and USBID pins as GPIOs on devices that support forcing OTG to operate as a host only controller By default the USB library will assume that the USBVBUS and USBID pins are configured as USB pins and not GPIOs 220 September 05 2012 Host Functions Note Forcing of the USB controller mode feature is not available on all Stellaris microcontrollers Consult the data sheet for the microcontroller that the application is using to determine if this feature is available The memory poo
18. 3 12 3 2 USBD DFU EVENT DETACH Definition define USBD_DFU_EVENT_DETACH 120 September 05 2012 3 12 4 3 12 4 1 3 12 4 2 3 12 4 3 Device Functions Description This value is passed to the client via the callback function provided in the tUSBDDFUDe vice structure and indicates that the host has sent a DETACH request to the DFU interface This request indicates that the device detach from the USB bus and reattach in DFU mode in preparation for a firmware upgrade Currently this is the only event that the DFU runtime class reports to the client When this event is received the client should call USBDDFUUpdateBegin from a non interrupt context at its earliest opportunity Function Documentation USBDDFUCompositelnit Initializes DFU device operation for a given USB controller Prototype void USBDDFUCompositelInit unsigned long ulIndex const tUSBDDFUDevice xpsDevice Parameters ullndex is the index of the USB controller which is to be initialized for DFU runtime device operation psDevice points to a structure containing parameters customizing the operation of the DFU device Returns Returns NULL on failure or the psDevice pointer on success void USBDDFUCompositeTerm void pvinstance Shuts down the DFU device Parameters pvinstance is the pointer to the device instance structure as returned by USBDDFUCompos itelnit Description This function terminates DFU operat
19. Definition define Feature2 usValue Parameters usValue is bit mask to specify the type of a set of feature report items Note that this macro uses a version of the Feature item tag with a two byte payload and allows any of the 8 possible data bits for the tag to be used If USB HID FEATURE BITF bit 8 is not required the Feature macro may be used instead Description This macro takes a value and prepares it to be placed as a Feature entry into a HID report structure This specifies the type of a feature item in a report structure These refer to a bit mask of flags that indicate the type of feature for a set of items Returns Not a function Input This is a macro to assist adding Input entries in HID report descriptors Definition define Input ucValue Parameters ucValue is bit mask to specify the type of a set of input report items Note that if the USB_HID_INPUT_BITF flag is required the Input2 macro which uses a 2 byte version of the Input item tag must be used instead of this macro September 05 2012 139 Device Functions 3 14 3 7 3 14 3 8 Description This macro takes a value and prepares it to be placed as an Input entry into a HID report structure This specifies the type of an input item in a report structure These refer to a bit mask of flags that indicate the type of input for a set of items Returns Not a function Input2 This is a macro to assist adding Input entries in HID report
20. KEYB_MAX_CHARS_PER_REPORT Definition define KEYB MAX CHARS PER REPORT Description The maximum number of simultaneously pressed non modifier keys that the HID BIOS key board protocol can send at once Attempts to send more pressed keys than this will result in a rollover error being reported to the host and KEYB ERR TOO MANY KEYS being returned from USBDHIDKeyboardKeyStateChange KEYB SUCCESS Definition define KEYB SUCCESS Description This return code from USBDHIDKeyboardKeyStateChange indicates success USBD HID KEYB EVENT SET LEDS Definition define USBD HID KEYB EVENT SET LEDS Description This event indicates that the keyboard LED states are to be set The ulMsgValue parameter contains the requested state for each of the LEDs defined as a collection of ORed bits where a 1 indicates that the LED is to be turned on and a 0 indicates that it should be turned off The indi vidual LED bits are defined using labels HID KEYB NUM LOCK HID KEYB CAPS LOCK HID KEYB SCROLL LOCK HID KEYB COMPOSE and HID KEYB KANA Function Documentation USBDHIDKeyboardCompositelnit Initializes HID keyboard device operation for a given USB controller Prototype void x USBDHIDKeyboardCompositeInit unsigned long ulIndex const tUSBDHIDKeyboardDevice xpsDevice Parameters ullndex is the index of the USB controller which is to be initialized for HID keyboard device operat
21. The maximum value for ulLength is 64 bytes the maximum USB packet size for the bulk end points in use by the device Attempts to send more data than this will result in a return code of 0 indicating that the data cannot be sent The bLast parameter allows a client to make multiple calls to this function before scheduling transmission of the packet to the host This can be helpful if for example constructing a packet on the fly or writing a packet which spans the wrap point in a ring buffer September 05 2012 83 Device Functions 3 6 4 5 3 6 4 6 84 Returns Returns the number of bytes actually sent At this level this will either be the number of bytes passed if less than or equal to the maximum packet size for the USB endpoint in use and no outstanding transmission ongoing or 0 to indicate a failure USBDBulkPowerStatusSet Reports the device power status bus or self powered to the USB library Prototype void USBDBulkPowerStatusSet void xpvInstance unsigned char ucPower Parameters pvinstance is the pointer to the bulk device instance structure ucPower indicates the current power status either USB STATUS SELF PWR or USB STATUS BUS PWR Description Applications which support switching between bus or self powered operation should call this function whenever the power source changes to indicate the current power status to the USB library This information is required by the USB library to allow correct resp
22. USB EVENT TX COMPLETE event is sent to the application callback to inform it that another packet may be transmitted Receive Operation An incoming USB data packet will result in a call to the application callback with event USBD EVENT RX AVAILABLE The application must then call USBDBulkPacketRead passing a buffer capable of holding 64 bytes to retrieve the data and acknowledge reception to the USB host Note The application must not make any calls to the low level USB Device API if interacting with USB via the USB bulk device class API Doing so will cause unpredictable though almost certainly unpleasant behavior Returns Returns NULL on failure or the psDevice pointer on success 3 6 4 3 USBDBulkPacketRead Reads a packet of data received from the USB host via the bulk data interface Prototype 82 unsigned long USBDBulkPacketRead void xpvInstance unsigned char pcData unsigned long ulLength tBoolean bLast September 05 2012 3 6 4 4 Device Functions Parameters pvinstance is the pointer to the device instance structure as returned by USBDBulkinit pcData points to a buffer into which the received data will be written ulLength is the size of the buffer pointed to by pcData bLast indicates whether the client will make a further call to read additional data from the packet Description This function reads up to u Length bytes of data received from the USB host into the supplied appl
23. USBDAudioTerm Shuts down the audio device Prototype void USBDAudioTerm void pvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDAudiolnit Description This function terminates audio interface for the instance supplied This function should not be called if the audio device is part of a composite device and instead the USBDCompositeTerm function should be called for the full composite device Following this call the pvinstance instance should not me used in any other calls Returns None September 05 2012 3 5 3 5 1 3 5 1 1 Device Functions Bulk Device Class Driver Although not offering support for a particular standard device class the generic bulk device class driver offers a very simple method for an application to set up USB communication with a paired application running on the USB host system The class driver offers a single bulk receive channel and a single bulk transmit channel and when coupled with USB buffers on each channel provides a straightforward read write interface to the application The device supports a single interface containing bulk IN and bulk OUT endpoints The configu ration and interface descriptors published by the device contain vendor specific class identifiers so an application on the host will have to communicate with the device using either a custom driver or a subsystem such as WinUSB or libusb win32 on Windows to allow the
24. m void x USBDCompositelnit unsigned long ullndex tUSBDCompositeDevice psDevice un signed long ulSize unsigned char pucData m void USBDCompositeTerm void pvlInstance Detailed Description Definitions The macros and functions defined in this section can be found in header file device usbdcomp h Data Structure Documentation tCompositeEntry Definition typedef struct const tDeviceInfo xpsDevice void xpvInstance tCompositeEntry Members psDevice This is the top level device information structure pvinstance This is the instance data for the device structure Description This type is used by an application to describe and instance of a device and an instance data pointer for that class The psDevice pointer should be a pointer to a valid device class to include in the composite device The pvlnstance pointer should be a pointer to an instance pointer for the device in the psDevice pointer tUSBDCompositeDevice Definition typedef struct nsigned short usVID nsigned short usPID nsigned short usMaxPowermA nsigned char ucPwrAttributes USBCallback pfnCallback onst unsigned char const xppStringDescriptors nsigned long ulNumStringDescriptors nsigned long ulNumDevices CompositeEntry xpsDevices nsigned long xpulDeviceWorkspace G t G G0 vt amp Gc Ge September 05 2012 3 10 3 3 10 3 1 Device Functions tCompositeInstance x psPrivateData tUSBDCompo
25. while 1 switch eMouseState fit This state is entered when they mouse is first detected case MOUSE INIT September 05 2012 Host Functions Initialized the newly connected mouse USBHMouseInit g_ulMouselInstance Proceed to the mouse connected state eMouseState MOUSE_CONNECTED break case MOUSE_CONNECTED break case MOUSE_NOT_CONNECTED default break Periodic call the main loop for the Host controller driver USBHCDMain Once the mouse has been configured the application s mouse callback routine is notified any time there is a state change with the mouse This includes the switching to the MOUSE_INIT state when a USB_EVENT_CONNECTED event occurs in order to trigger initialization of the mouse device The USB_EVENT_DISCONNECTED simply switches the state of the application to let it know that the mouse is no longer present The remaining events are mouse state changes that can be used by the application to move a cursor or make a selection based on a mouse click Example Mouse Callback Routine unsigned long MouseCallback void pvCBData unsigned long ulEvent unsigned long ulMsgParam void pvMsgData switch ulEvent New mouse detected case USB_EVENT_CONNECTED eMouseState MOUSE_INIT break Mouse has been unplugged case USB_EVENT_DISCONNECTED eMouseState MOUSE
26. 3 19 Mass Storage Device Class API The USB mass storage device class allows an application to act as a physical storage device for use by another USB application or for a host operating system Because the type of storage can vary per application the mass storage class abstracts the storage with a set of block based APIs that are provided by the application to the USB library These APIs allow the USB mass storage class to call an external set of functions that actually perform the operations on the physical storage media The storage APIs are given to the USB library s mass storage device class initialization function and are called by the USB library whenever it needs to access the physical media The mass storage class implementation does not require any run time calls once it is initialized This is because all interaction with the mass storage class occur through the callback function that is provided to the USB library s mass storage class interface The callback function is used to notify the application when the device is being read written or has gone idle Depending on the operating system and how it accesses the mass storage device these callbacks may occur at a very rapid rate once per block or slower once per file The USB library s mass storage class also provides an interface to inform the USB library when the media status has changed in case the physical media can be ejected This is important for devices like SD cards that can be re
27. 63 Device Functions 3 4 1 3 4 2 3 4 2 1 64 Detailed Description The macros and functions defined in this section can be found in device usbdaudio h Data Structure Documentation tUSBDAudioDevice Definition typedef struct nsigned short usVID nsigned short usPID nsigned char pucVendor 8 nsigned char pucProduct 16 nsigned char pucVersion 4 nsigned short usMaxPowermA nsigned char ucPwrAttributes USBCallback pfnCallback onst unsigned char xconst xppStringDescriptors nsigned long ulNumStringDescriptors hort sVolumeMax hort sVolumeMin hort sVolumeStep tAudioInstance xpsPrivateData OOO GO f G4 G amp Ge UG G tUSBDAudioDevice Members usVID The vendor ID that this device is to present in the device descriptor usPID The product ID that this device is to present in the device descriptor pucVendor 8 byte vendor string pucProduct 16 byte vendor string pucVersion 4 byte vendor string header file usMaxPowermA The maximum power consumption of the device expressed in mA ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wake up Valid values are USB CONF ATTR SELF PWR or USB CONF ATTR BUS PWAR optionally ORed with USB CONF ATTR RWAKE pfnCallback A pointer to the callback function which will be called to notify the application of events relating to the operation of the audio device ppStringDescriptors A p
28. API will note the configuration change internally but not report it to the device code September 05 2012 193 Device Functions 3 21 2 5 3 21 2 6 3 21 2 7 3 21 2 8 3 21 2 9 194 pfnDataReceived This callback informs the device code of the arrival of data following an earlier call to USBDC DRequestDataEPO On this callback the received data will have been written into the buffer provided to the USB Device API in the pucData parameter to USBDCDRequestDataEPO The callback handler does not need to acknowledge the data using a call to USBDevEndpoint DataAck in this case since this acknowledgment is performed within the USB Device API itself If this member of sCallbacks is set to NULL the USB Device API will read endpoint zero data requested via USBDCDRequestDataEPO but not report its availability to the device code De vices making use of the USBDCDRequestDataEPO call must therefore ensure that they supply a p nDataReceived handler pfnDataSent The USBDCDSendDataEP0 function allows device code to send an arbitrarily sized block of data to the host via endpoint zero The maximum packet size that can be sent via endpoint zero is however 64 bytes so larger blocks of data are sent in multiple packets This callback function is used by the USB Device API to inform the device code when all data provided in the buffer passed to USBDCDSendDataEPO has been consumed and scheduled for transmission to the host On
29. All configuration descriptors are 9 bytes long bDescriptorType The type of the descriptor For a configuration descriptor this will be USB DTYPE CONFIGURATION 2 wTotalLength The total length of data returned for this configuration This includes the com bined length of all descriptors configuration interface endpoint and class or vendor specific returned for this configuration bNuminterfaces The number of interface supported by this configuration bConfigurationValue The value used as an argument to the SetConfiguration standard re quest to select this configuration iConfiguration The index of a string descriptor describing this configuration bmAttributes Attributes of this configuration bMaxPower The maximum power consumption of the USB device from the bus in this con figuration when the device is fully operational This is expressed in units of 2mA so for example 100 represents 200mA Description This structure describes the USB configuration descriptor as defined in USB 2 0 specification section 9 6 3 This structure also applies to the USB other speed configuration descriptor defined in section 9 6 4 September 05 2012 27 General Purpose Functions 2 3 2 2 2 3 2 3 28 tDescriptorHeader Definition typedef struct unsigned char bLength unsigned char bDescriptorType tDescriptorHeader Members bLength The length of this descriptor including this length byte expressed in by
30. Deintiens s st es doaa Po eee RR Rx ee eee Ree REOR dee t d deos 26 2 4 USB Buffer and Ring Buffer APIS 2222s 34 3 Deuce FUNCHONS uz oh cee ee he eee eee ee ee El ee eee 53 S o AMRHOOgUDHO eiae yoke Som x So See ee A SE SS OR ER RRA SE Ree 53 3 2 APl choices for USB devices usos uo ooo ek R3 moo ho kom o 33 Ee 54 3 3 Audio Device Class Driver eee s 57 3 4 Audio Device Class Driver Definitions lee 63 3 5 Bulk Device Class Driver x uus a a ee mk o e yo Ro mcn D ee a 69 3 6 Bulk Device Class Driver Definitions Re 79 ar CDC Device Class DVEF 32223 acras ede ee eher mU Re RE Eee dodi a a area 87 3 8 CDC Device Class Driver Definitions e 95 3 9 Composite Device Class Driver aa 105 3 10 Composite Device Class Driver Definitions ee 111 3 11 Device Firmware Upgrade Device Class Driver a 114 3 12 Device Firmware Upgrade Device Class Driver Definitions llle 119 3 139 HID Device Glass Driver sss ee or xk mk RR RR G3 x ee 122 3 14 HID Device Class Driver Definitions i sss komm Rx 132 3 15 HID Mouse Device Class API 2e s 156 3 16 HID Mouse Device Class API Definitions os RR mmm ginis 158 3 17 HID Keyboard Device Class API osos esos Rem eaea RR Roh RR mm m RR down 165 3 18 HID Keyboard Device Class API Definitions aaa aaa 168 3 19 Mass Storage Device Class API lll ss 175 3 20 Mass Storage Device Cl
31. Enumerators USBH HID DEV NONE No device should be used This value should not be used by appli cations USBH HID DEV KEYBOARD This is a keyboard device USBH HID DEV MOUSE This is a mouse device USBH HID DEV VENDOR This is a vendor specific device Function Documentation USBHHIDClose This function is used to release an instance of a HID device Prototype void USBHHIDClose unsigned long ulHIDInstance Parameters ulHIDinstance is the instance value for a HID device to release Description This function releases an instance of a HID device that was created by a call to USBHHI DOpen This call is required to allow other HID devices to be enumerated after another HID device has been disconnected The ulHIDInstance parameter should hold the value that was returned from the previous call to USBHHIDOpen Returns None USBHHIDGetReport This function is used to retrieve a report from a HID device Prototype unsigned long USBHHIDGetReport unsigned long ulInstance unsigned long ulInterface unsigned char x pucData unsigned long ulSize Parameters ullnstance is the value that was returned from the call to USBHHIDOpen ullnterface is the interface to retrieve the report from September 05 2012 247 Host Functions 4 5 4 3 4 5 4 4 248 pucData is the memory buffer to use to store the report ulSize is the size in bytes of the buffer pointed to by pucBuffer Description This fu
32. HID specific report descriptor for the keyboard Note that the value used to initialize the wTotalLength field of the configuration descriptor is irrelevant since the USB library will calculate this based on the content of the sections that are concatenated to build the final descriptor J f kk kk k k ke koe ke kk ke kk kk kk Kok kk kk RR kk kk kk kk ko kk ke kk Kok ko KK Kk kk kk kk K ke kk I kk k K kk ko ke kk k ke ke e HID keyboard device configuration descriptor It is vital that the configuration descriptor bConfigurationValue field byte 6 is 1 for the first configuration and increments by 1 for each additional configuration defined here This relationship is assumed in the device stack for simplicity even though the USB 2 0 specification imposes no such restriction on the bConfigurationValue values J f kk kk k k k k e ke kk ke kk kk kk Kk kk kk kk kk kk kk kk kk kk Sk ko kk k K KK KK kk kk ke k k oko kk I kk IK ke kk k ke ke e const unsigned char g pKeyboardDescriptor if Configuration descriptor header 9 Size of the configuration descriptor USB DTYPE CONFIGURATION Type of this descriptor USBShort 34 The total size of this full structure Value is patched by the USB library so is not important here Ly The number of interfaces in this configuration i The unique value for this configuration 53 The string identifier that describes this configurati
33. NOT CONNECTED break September 05 2012 277 Host Functions New Mouse events detected case USBH_EVENT_ I ID MS PRESS break case USBH_EVENT_HID_MS_REL break case USBH_EVENT_ ID MS X break case USBH_EVENT_HID_MS_Y break return 0 4 8 6 Host HID Keyboard Programming Example The USB library HID keyboard example provides support for HID keyboard devices that support the USB HID keyboard BIOS protocol Since most keyboards support the BIOS protocol most key boards should be able to be connected and be supported The initial call to USBHKeyboardOpen prepares the keyboard device application interface to receive notifications from any USB keyboard device that is connected The keyboard interface needs some basic configuration and needs to set the current state of LEDs on the keyboard the application must wait for the keyboard to be connected and then call the USBHKeyboardlnit function Example Keyboard Configuration 278 Open an instance of the keyboard driver The keyboard does not need to be present at this time this just save a place for it and allows the applications to be notified when a keyboard is present ff g ulKeyboardInstance USBHKeyboardOpen KeyboardCallback g_pucBuffer 12873 The main loop for the application iif while 1 switch eKeyboardState This state is entered when they keyboard
34. NT DISCONNECTED W USB F W USB EVENT TX COMPLETE NT ERROR NT SUSPEND Wm USB F W USB F EEEE W USB EVENT RESUME m USBD HID KEYB EVENT SET LEDS Note The USB EVENT DISCONNECTED event will not be reported to the application if the MCU s PB1 USBOVBUS pin is connected to a fixed 5 Volts rather than directly to the VBUS pin on the USB connector m Add the following header files to the source file s which are to support USB include src usb h include usblib usblib h include usblib device usbdhidkeyb h m Define the string table which is used to describe various features of your new device to the host system The string table found in Using the HID Device Class Driver illustrates the format required This table must include a minimum of 6 entries string descriptor O defining the language s available and 5 strings for each supported language m Define an area of RAM of for the private data for the HID keyboard class driver This structure should never be accessed by the application 166 September 05 2012 Device Functions J kk ke koe kk ko ke kk ke kk kk kk kk kk Kok OR ke kk ke kk kk kk ck ke OR RR IR I kc kk IR A I A ke IA ke e ke Ke oe The HID keyboard device private instance data J kk ke koe kk ko ke kk ke kk kk kk kk kk kk kk kk ke kk ke kk kk kk khe kk kk ok kk Kk kk oko ko kk ko
35. RAM of for the private data for the bulk device class driver This structure should never be accessed by the application J f kk kk ROKR IKK IRR I IRR Kk kk kk ko ko IR OR IR IR IR A I I oe The bulk device private data eee eee CeCe Pee ee eS ee Pe ee eee eee ee eee ee eee ee ee ee ee eee eee tBulkInstance g_sBulkInstance Define a tUSBDBulkDevice structure and initialize all fields as required for your application The following example illustrates a simple case where no USB buffers are in use For an ex ample using USB buffers see the source file usb bulk structs cinthe usb dev bulk example application const tUSBDBulkDevice g sBulkDevice The Vendor ID you have been assigned by USB IF USB_VID_YOUR_VENDOR_ID The product ID you have assigned for this device USB_PID_YOUR_PRODUCT_ID A The power consumption of your device in milliamps POWER CONSUMPTION mA The value to be passed to the host in the USB configuration descriptor s bmAttributes field USB CONF ATTR SELF PWR A pointer to your receive callback event handler YourUSBReceiveEventCallback A value that you want passed to the receive callback alongside every event void amp g_sYourInstanceData A pointer to your transmit callback event handler YourUSBTransmitEventCallback de A value that you want passed to the transmit cal
36. September 05 2012 4 5 4 31 Host Functions unsigned long ulOutPipe unsigned long ulLBA unsigned char xpucData unsigned long x pulSize unsigned long ulNumBlocks Parameters ullnPipe is the USB IN pipe to use for this command ulOutPipe is the USB OUT pipe to use for this command ulLBA is the logical block address to read pucData is the data buffer to return the data pulSize is the size of the buffer on entry and number of bytes read on exit ulNumBlocks is the number of contiguous blocks to read from the device Description This function is used to issue a SCSI Read 10 command to a device The u LBA parameter specifies the logical block address to read from the device The data from this block will be returned in the buffer pointed to by pucData The parameter pulSize should indicate enough space to hold a full block size or only the first pulSize bytes of the LBA will be returned Returns This function returns the results of the SCSI Read 10 command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL USBHSCSIReadCapacities This will issue the SCSI read capacities command to a device Prototype unsigned long USBHSCSIReadCapacities unsigned long ulInPipe unsigned long ulOutPipe unsigned char xpucData unsigned long xpulSize Parameters ullnPipe is the USB IN pipe to use for this command ulOutPipe is the USB OUT pipe to use for this command pucData is the data buffer to return
37. Test Unit Ready command to a device This call will simply return the results of issuing this command Returns This function returns the results of the SCSI Test Unit Ready command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL USBHSCSIWrite10 This function issues a SCSI Write 10 command to a device Prototype unsigned long USBHSCSIWritelO unsigned long ulInPipe unsigned long ulOutPipe unsigned long ulLBA unsigned char xpucData unsigned long xpulSize unsigned long ulNumBlocks Description This function is used to issue a SCSI Write 10 command to a device The u LBA parameter specifies the logical block address on the device The data to write to this block should be in the buffer pointed to by pucData parameter The parameter pulSize should indicate the amount of data to write to the specified LBA Parameters ullnPipe is the USB IN pipe to use for this command ulOutPipe is the USB OUT pipe to use for this command ulLBA is the logical block address to read pucData is the data buffer to write out pulSize is the size of the buffer September 05 2012 265 Host Functions 4 5 5 4 5 5 1 4 5 5 2 4 5 5 3 4 5 5 4 266 ulNumBlocks is the number of contiguous blocks to write to the device Returns This function returns the results of the SCSI Write 10 command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL Variable Documentatio
38. Windows NT Class Ports ClassGuid 4D36E978 E325 11CE BFC1 08002BE10318 Provider MFGNAMES LayoutFile layout inf DriverVer 08 17 2001 5 1 2600 0 September 05 2012 93 Device Functions Manufacturer SMF GNAME S DeviceList DestinationDirs DefaultDestDir 12 SourceDisksFiles SourceDisksNames NOTE Change the VID and PID in the following section to match your device The values with the amp MI_xx values are for the composite serial devices examples DeviceList This entry is for the single serial port example usb dev serial SDESCRIPTION 0 DriverInstall USBNVID 1CBE amp PID 0002 These entries are for the dual serial port composite example usb dev cserial S DESCRIPTION 0 DriverInstall USBNVID lCBE amp PID 0007 amp MI 00 S DESCRIPTION 1 DriverInstall USBNVID lCBE amp PID 0007 amp MI 01 This entry is for the composite hid serial device usb dev chidcdc that the value is MI 01 because the serial device is on interface 1 S DESCRIPTION 1 DriverInstall USBNVID 1CBE amp PID 0009 amp MI 01 DriverInstall nt CopyFiles DriverCopyFiles AddReg DriverInstall nt AddReg DriverCopyFiles usbser sys 0x20 DriverInstall nt AddReg HKR DevLoader ntkern HKR NTMPDriver usbser sys HKR EnumPropPages32 MsPorts dll SerialPortPropPageProvider DriverInstall nt Services AddService usbser 0x00000002 DriverService DriverService DisplayName SE
39. Word sized field that varies according to the request typically used to pass an index or offset wLength The number of bytes to transfer if there is a data stage to the request Description The standard USB request header as defined in section 9 3 of the USB 2 0 specification September 05 2012 2 3 3 2 3 3 1 2 3 3 2 2 3 3 3 General Purpose Functions Define Documentation NEXT_USB_DESCRIPTOR Traverse to the next USB descriptor in a block Definition define NEXT_USB_DESCRIPTOR ptr Parameters ptr points to the first byte of a descriptor in a block of USB descriptors Description This macro aids in traversing lists of descriptors by returning a pointer to the next descriptor in the list given a pointer to the current one Returns Returns a pointer to the next descriptor in the block following ptr USB3Byte Write a 3 byte unsigned long value to a USB descriptor block Definition define USB3Byte ulValue Parameters ulValue is the three byte unsigned value that is to be written to the descriptor Description This helper macro is used in descriptor definitions to write three byte values Since the con figuration descriptor contains all interface and endpoint descriptors in a contiguous block of memory these descriptors are typically defined using an array of bytes rather than as packed structures Returns Not a function USBLong Write a 4 byte unsigned long value to a USB descri
40. a block read to an MSC device Prototype long USBHMSCBlockRead unsigned long ulInstance unsigned long ulLBA unsigned char xpucData unsigned long ulNumBlocks Parameters ullnstance is the device instance to use for this read ulLBA is the logical block address to read on the device pucData is a pointer to the returned data buffer ulNumBlocks is the number of blocks to read from the device September 05 2012 4 5 4 13 4 5 4 14 Host Functions Description This function will perform a block sized read from the device associated with the ullnstance parameter The ulLBA parameter specifies the logical block address to read on the device This function will only perform u NumBlocks block sized reads In most cases this is a read of 512 bytes of data The pucData buffer should be at least ulNumBlocks 512 bytes in size Returns The function returns zero for success and any negative value indicates a failure USBHMSCBlockWrite This function performs a block write to an MSC device Prototype long USBHMSCBlockWrite unsigned long ulInstance unsigned long ulLBA unsigned char xpucData unsigned long ulNumBlocks Parameters ullnstance is the device instance to use for this write ulLBA is the logical block address to write on the device pucData is a pointer to the data to write out ulNumBlocks is the number of blocks to write to the device Description This function will perfo
41. a link from http www ti com stellarisware The DFU driver is common between the USB boot loader boot usb and the runtime DFU in terface provided by the DFU device class It consists of two Stellaris specific DLLs along with the Microsoft supplied co installers for the WinUSB subsystem Support is provided for WindowsXP Windows Vista and Windows7 in both 32 bit and 64 bit flavors The two DLLs are Imusbdll dll A low level interface above WinUSB which provides simple packet transmission and reception and the ability to perform a control transaction on endpoint 0 Applications may be built using this interface without the need to download and install the Windows Device Driver Kit The DLL itself requires the Windows DDK to build since WinUSB headers are not provided in the Windows SDK Imdfu dll A high level API above the DFU function This DLL allows DFU capable devices to be found on the bus and application images to be downloaded to or uploaded from those devices To create a driver for your DFU enabled device either create a new INF file from the boot usb inf example substituting your device s VID PID and DFU interface number for those in the original file or merge the content of this inf with the same changes into a combined inf for your composite device Note that the device will publish PID OxOOFF when in DFU mode so you must ensure that your driver INF file contains an entry to install the driver for devices publishing this P
42. a ring buffer is full or not Prototype tBoolean USBRingBufFull tUSBRingBufObject xptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to empty Description This function is used to determine whether or not a given ring buffer is full The structure is specifically to ensure that we do not see warnings from the compiler related to the order of volatile accesses being undefined Returns Returns true if the buffer is full or false otherwise September 05 2012 2 4 6 21 2 4 6 22 2 4 6 23 General Purpose Functions USBRingBuflnit Initializes a ring buffer object Prototype void USBRingBufInit tUSBRingBufObject xptUSBRingBuf unsigned char xpucBuf unsigned long ulSize Parameters ptUSBRingBuf points to the ring buffer to be initialized pucBuf points to the data buffer to be used for the ring buffer ulSize is the size of the buffer in bytes Description This function initializes a ring buffer object preparing it to store data Returns None USBRingBufRead Reads data from a ring buffer Prototype void USBRingBufRead tUSBRingBufObject ptUSBRingBuf unsigned char xpucData unsigned long ulLength Parameters ptUSBRingBuf points to the ring buffer to be read from pucData points to where the data should be stored ulLength is the number of bytes to be read Description This function reads a sequence of bytes from a ring buffer Returns None USBRingBu
43. also define additional class specific descriptors In cases where the host requests one of these non standard descriptors this callback is made to give the device code an opportunity to provide its own descriptor to satisfy the request If the device can satisfy the request it must call USBDCDSendDataEP0 to provide the requested descriptor data to the host If the request cannot be satisfied the device should call USBDCD StallEPO to indicate that the descriptor request is not supported If this member of scallbacks is set to NULL the USB Device API will stall endpoint zero whenever it receives a request for a non standard descriptor pfnRequestHandler The USB Device API contains handlers for all standard USB requests as defined in Table 9 3 of the USB 2 0 specification where a standard request is indicated by bits 5 and 6 of the request structure bmRequestType field being clear If a request is received with a non standard request type this callback is made to give the device code an opportunity to satisfy the request The callback function receives a pointer to a standard 8 byte request structure of type tUSBRequest containing information on the request type the request identifier and various request specific parameters The structure also contains a length field wLength which indicates September 05 2012 3 21 2 3 3 21 2 4 Device Functions how much if any data will follow in the data stage of the USB transaction No
44. an audio device instance Prototype void USBHostAudioClose unsigned long ulInstance Parameters ullnstance is the device instance that is to be released Description This function is called when a host audio device needs to be released This could be in prepa ration for shutdown or a switch to USB device mode for example Following this call the audio device is available and can be opened again using a call to USBHostAudioOpen After calling this function the host audio driver will no longer provide any callbacks or accept calls to other audio driver APIs Returns None USBHostAudioFormatGet This function is called to determine if an audio format is supported by the connected USB Audio device Prototype unsigned long USBHostAudioFormatGet unsigned long ulInstance unsigned long ulSampleRate unsigned long ulBits u u unsigned long ulChannels unsigned long ulFlags Parameters ullnstance is the device instance for this call ulSampleRate is the sample rate of the audio stream ulBits is the number of bits per sample in the audio stream ulChannels is the number of channels in the audio stream ulFlags is a set of flags to determine what type of interface to retrieve Description This function is called when an application needs to determine which audio formats are sup ported by a USB audio device that has been connected The ullnstance value that is used with thi
45. and removes the device from the USB bus Following this call the psDevice instance may not me used in any other call to the mass storage device other than USBDMSCInit or USBDMSCInitComposite Returns None Using the USB Device API If an existing USB Device Class Driver is not suitable for your application you may choose to develop your device using the lower level USB Device API instead This offers greater flexibility but involves somewhat more work Creating a device application using the USB Device API involves several steps m Build device configuration interface and endpoint descriptor structures to describe your de vice m Write handlers for each of the USB events your device is interested in receiving from the USB library Call the USB Device API to connect the device to the bus and manage standard host interac tion on your behalf The following sections walk through each of these steps offering code examples to illustrate the process Working examples illustrating use of the library can also be found in the DriverLib release for your USB capable evaluation kit The term device code used in the following sections describes all class specific code written above the USB Device API to implement a particular USB device application This may be either application code or a USB device class driver Building Descriptors The USB Device API manages all standard USB descriptors on behalf of the device These de scripto
46. application as the USB pins may not always be on the same physical pins for every part supported by the USB library The macros provided in the pin_map h file included with DriverLib can be used to indicate which pin and peripheral to use for a given part See the DriverLib documentation on pin mapping for more details on how it provides mapping of peripherals to pins on devices The USBHCDRegisterDrivers call passes in the static array of supported USB host class drivers that are supported by the application As shown in the example the application should always call the USB device interfaces open routines before calling USBHCDInit since this call enables the USB host controller and start enumerating any connected device If the device interface has not been called it may miss the connection notification and could miss some state information that occurred before the device interface was ready Example Basic Configuration as Host J kk ke RRR kk khe ke Sk kk KR kk ke ok kk kk Sk kk kk kk OR IORI IR RRR I I ke ke ke ke ee Af The size of the host controller s memory pool in bytes TORK RRR IR ke kk kk kk Kk kk ko ke kk Kok RR OR kk ko koc IKK IRR IR IR I K k k K IIR k k Ke ke ke e define HCD MEMORY SIZE 128 J kk ke kk kk kk kk khe ke Sk ko kk kk kk kk kk kk ko ok kk kk kk Kok kk ko ok Sk kk ok kk ko kk kk kk oko IR kk ko ke ko kk ke ke ke ke ee The memory pool to provide to the Host controller driver J k
47. char pucData unsigned long pulSize unsigned long USBHSCSITestUnitReady unsigned long ullnPipe unsigned long ulOutPipe unsigned long USBHSCSIWrite10 unsigned long ullnPipe unsigned long ulOutPipe un signed long ulLBA unsigned char pucData unsigned long pulSize unsigned long ulNum Blocks Variables 244 const tUSBHostClassDriver g USBHIDClassDriver const tUSBHostClassDriver g USBHostAudioClassDriver const tUSBHostClassDriver g USBHostMSCClassDriver const tUSBHostClassDriver g USBHubClassDriver September 05 2012 4 5 1 4 5 2 4 5 2 1 4 5 2 2 4 5 2 3 4 5 2 4 4 5 2 5 Host Functions Detailed Description The macros and functions defined in this section can be found in header files host usbhhid h host usbhmsc h and host usbhscsi h Define Documentation USB HOST AUDIO INSTANCE SIZE Definition define USB HOST AUDIO INSTANCE SIZE Description This is the size in bytes of the private data for the host audio class USBH AUDIO EVENT CLOSE Definition define USBH AUDIO EVENT CLOSE Description This USB host audio event indicates that the previously connected device has been discon nected The pvBuffer and ulParam values are not used in this event USBH AUDIO EVENT OPEN Definition define USBH AUDIO EVENT OPEN Description This USB host audio event indicates that the device is connected and ready to send or receive buffers The pv
48. descriptor This event is typically due to the class being included in a composite device The pvinstance is a pointer to an instance of the device being accessed The ulRequest is USB EVENT COMP CONFIG The pvRequestData is a pointer to the beginning of the configuration descriptor for the device instance September 05 2012 General Purpose Functions 2 2 3 3 USB EVENT COMP EP CHANGE Definition define USB EVENT COMP EP CHANGE Description This define is used with a device class s pfnDeviceHandler handler function to indicate that the USB library has changed the endpoint number This event is typically due to the class being included in a composite device The pvinstance is a pointer to an instance of the device being accessed The ulRequest is USB EVENT COMP EP CHANGE The pvRequestData is a pointer to a two byte array where the first value is the old endpoint number and the second is the new endpoint number The endpoint numbers should be ex actly as USB specification defines them and bit 7 set indicates an IN endpoint and bit 7 clear indicates an OUT endpoint 2 2 3 4 USB EVENT COMP IFACE CHANGE Definition define USB EVENT COMP IFACE CHANGE Description This define is used with a device class s pfnDeviceHandler handler function to indicate that the USB library has changed the interface number This event is typically due to the class being included in a composite device
49. descriptor string table J kk kk kk kk oko kk Kok kk Kok kk ko kk Kok kk koe kk kk kk kk kk koe ko kk ok kk ko Kk kk ko kc kk oko kc kk ko ke kk Kok kk ke ke ek e ee const unsigned char const g pStringDescriptors g_pLangDescriptor g_pManufacturerString g_pProductString g_pSerialNumberString September 05 2012 125 Device Functions 126 g pHIDInterfaceString g pConfigString un define NUM STRING DESCRIPTORS sizeof g pStringDescriptors X sizeof unsigned char x Define a tHIDInstance structure which the USB HID device class driver uses to store its internal state information This should never be accessed by the application J f kk kk ko ke kk oko ke kk Kok kk Kok kk Kok ke kk ko kk koe ke kk ok kk Kok kk ko ke kk kk RR kk koc ko kk ke kk ko ke kk Kok kk ke ke ko kk ee The HID device private data J kk ke kk ek ck ek khe ee eee ee ee ee eee eee ee ee eee eee ee ee ee ee eee eee tHIDInstance g sHIDInstance Develop the HID report descriptors and if required physical descriptors for your de vice and from these the HID descriptor itself Details of how to do this are beyond the scope of this document other than to say that macros in header file usbdhid h are included to help add the various tags required in the descriptor For informa tion on how these descriptors are constructed please see the USB Device Class Definition for Human Interface Devices version 1 11 which can be
50. device to be accessed An example of this is provided in the usb dev bulk application This class driver is particularly useful for applications which intend passing high volumes of data via USB and where host side application code is being developed in partnership with the device USB Generic Bulk Device Model Receive Channel Bulk OUT E Optional USB 2 Buffer o x o tr o Ee c E sS 85 8 2 2 oO Transmit Channel t en A 3 x TUE 2 o Bulk IN BM N Optional 2 5 2 USB e lt 5 5 Buffer c iere Le Endpoint 0 o The usb dev bulk example application makes use of this device class driver Generic Bulk Device Class Events The generic bulk device class driver sends the following events to the application callback functions Receive Channel Events m USB EVENT RX AVAILABLE USB E USB E NT ERROR NT CONNECTED Wm USB F Wm USB F NT DISCONNECTED ENT SUSPEND FEFE September 05 2012 69 Device Functions 3 5 1 2 3 5 2 70 m USB EVENT RESUME Note The USB EVENT DISCONNECTED event will not be reported to the application if the MCU s PB1 USBOVBUS pin is connected to a fixed 5 Volts rather than directly to the VBUS pin on the USB connector Transmit Channel Events m USB EVENT TX COMPLETE Using the Generic Bulk Device
51. downloaded from http www usb org developers devclass docs HID1 11 pdf The required structures for a BIOS compatible HID mouse are J kk ke kk kk ko ke kk khe kk kk kk kk kk kk kk kk ke kk ke kk kk kk ck he kc Sk kc ok Sk ko Ko kk kk ko kk ko ko kk ke kk ko ke kk ko ke ek Ke ke e The report descriptor for the BIOS mouse class device EA J kk kk koe KR ke kk kk kk kk kk kk kk kk ke Sk kk kk kk kk ck ke ok Sk kk RR IR I OR IR I A I A ke ek e ee static const unsigned char g_pucMouseReportDescriptor UsagePage USB_HID_GENERIC_DESKTOP Usage USB HID MOUSE Collection USB HID APPLICATION Usage USB HID POINTER Collection USB HID PHYSICAL The buttons UsagePage USB HID BUTTONS UsageMinimum 1 UsageMaximum 3 LogicalMinimum 0 LogicalMaximum 1 3 1 bit values for the buttons ReportSize 1 ReportCount 3 Input USB HID INPUT DATA USB HID INPUT VARIABLE USB HID INPUT ABS 1 5 bit unused constant value to fill the 8 bits ReportSize 5 ReportCount 1 Input USB_HID_INPUT_CONSTANT USB_HID_INPUT_ARRAY USB_HID_INPUT_ABS September 05 2012 Device Functions The X and Y axis UsagePage USB HID GENERIC DESKTOP Usage USB HID X Usage USB HID Y LogicalMinimum 127 LogicalMaximum 127 2 8 bit Values for x and y ReportSize 8 ReportCount 2 Input USB_HID_INPUT_DATA USB_HID_INPUT_VARIA
52. event driver using the DECLARE EVENT DRIVER macro and then adding the variable that is declared to the list of drivers supported by the application This event driver allows applications to notify users that an unsupported device has been inserted or to provide notification that a power fault has occurred and power may have been shut off depending on the settings pro vided to the USBHCDPowerConfiglnit function Depending on configuration the following events can occur m USB EVENT CONNECTED indicates that a support device has been connected m USB EVENT UNKNOWN CONNECTED indicates that an unsupported device has been connected September 05 2012 231 Host Functions 232 m USB EVENT DISCONNECTED indicates that an unsupported device has been discon nected m USB EVENT POWER FAULT indicates that a power fault has occurred m USB EVENT POWER ENABLE indicates that power should be enabled by the application since it has requested to manually control the power m USB EVENT POWER DISABLE indicates that power should be enabled by the application since it has requested to manually control the power m USB EVENT SOF indicates that a SOF event has occurred default disabled The USB host library provides the ability to enable or disable any of these events by calling the USB HCDEventEnable or USBHCDEventDisable functions All events except the USB EVENT SOF are enabled by default when the USB host library is initialized The USB E
53. function discards all data currently in the supplied buffer without processing transmitting it via the USB controller or passing it to the client depending upon the buffer mode Returns None September 05 2012 General Purpose Functions 2 4 6 7 USBBufferlnfoGet Returns the current ring buffer indices for this USB buffer Prototype void USBBufferInfoGet const tUSBBuffer xpsBuffer tUSBRingBufObject xpsRingBuf Parameters psBuffer is the pointer to the buffer instance whose information is being queried psRingBuf is a pointer to storage that will be written with the current ring buffer control struc ture for this USB buffer Description This function is provided to aid a client wishing to write data directly into the USB buffer rather than using the USBBufferWrite function This may be necessary to control when the USB Buffer starts transmission of a large block of data for example A transmit buffer will immediately send a new packet on any call to USBBufferWrite if the un derlying layer indicates that a transmission can be started In some cases this is not desirable and a client may wish to wishes to write more data to the buffer in advance of starting trans mission to the lower layer In such cases this function may be called to retrieve the current ring buffer indices and the buffer accessed directly Once the client has written all data it wishes to send it should call function USBBufferDataWritten to indica
54. in the application unsigned char pucDesciptorData COMPOSITE DCDC SIZEx2 The application must also provide separate instance data for each instance of the devices that it is including in the composite device This is true even when including two devices classes of the same type so that the instances can be differentiated by the USB library The USB composite device class can determine which instance to use based on the interface number that is accessed by the host September 05 2012 107 Device Functions 3 9 2 2 3 9 2 3 3 9 3 3 9 3 1 108 controller The application provides the instance data in the array of tCompositeEntry structures passed into the composite class in the psDevices member of the tUSBDCompositeDevice structure Notice in the example below that the device information is common g_sCDCSerDevicelnfo but that each has its own instance data sCDCDeviceA and sCDCDeviceB Example Two serial instances extern tUSBDCDCDevice g sCDCDeviceA extern tUSBDCDCDevice g sCDCDeviceB tCompositeEntry g_psDevices 2 amp g sCDCSerDeviceInfo void amp g_sCDCDeviceA F amp g sCDCSerDeviceInfo void amp g_sCDCDeviceB Interface Handling The device class interfaces will be merged into the composite device descriptor and the composite class modifies the default interface assignments to insure monotonically increasing indexes for all of the included interfaces In the example above for the two serial po
55. is treated as pairs of 16 bit values tHIDReportldle Definition typedef struct unsigned char ucDuration4ms unsigned char ucReportID unsigned short usTimeTillNextmS unsigned long ulTimeSinceReportmsS tHIDReportIdle September 05 2012 135 Device Functions Members ucDuration4mS The idle duration for the report expressed in units of 4mS 0 indicates infinite and informs the class driver not to send the report unless a state change occurs ucReportID The ID of the report which this structure applies to This is the report ID as specified using a ReportlD tag in the report descriptor rather than the index of the report in the HID class descriptor array If only a single Input report is supported and thus no ReportlD tag is present this field should be set to 0 usTimeTillNextmS The number of milliseconds before we need to send a copy of a given report back to the host This field is updated by the HID driver and used to time sending of USBD HID EVENT IDLE TIMEOUT ulTimeSinceHeportmS The number of milliseconds that have passed since the last time this report was sent The HID class driver needs to track this since Set Idle requests are required to take effect as if issued immediately after the last transmission of the report to which they refer Description The structure used to track idle time for reports An array of these structures is passed to the HID device class driver during USBDHIDInit and is used to track
56. k k k k k k k K k k K k k k k ke k k ke k k k k k The array of devices supported by this composite device J kk ke ke k k x ke kk ke e kk che ek eee Pee ee ce eee ee k k k k ee ee k k k k k k k k k ck ck ckck ck ck ckck ck ck ckck eee ee tCompositeEntry g psCompDevices NUM DEVICES HID Mouse Information amp g_sHIDDeviceInfo 0 Device Firmware Upgrade Runtime Interface amp g sDFUDeviceInfo 0 Define the additional structures and storage required by the composite device class For the HID DFU device described above this would look like ETT CT kk ko ke kk e ke kk kk kk kk kk kk k k kk ke kk ke kk kk kk ck k ok A k k k k k K k k k k k k k k k k k k k k k k k k k k k k k k k Additional workspace required by the composite driver to hold a lookup table allowing mapping of composite interface and endpoint numbers to individual device class instances J f kk kk ROK k k k k k RR ke kk ck ke ROKR KR kk ko ko IR RI IIR K k k k k k k I I ek unsigned long g pulCompWorkspace NUM DEVICES J kk kk koe Sk kk ke Sk kk H kk ko ke kk K k kk ke kk A k kk kk Kk Ck ko kk ko ko IR k k kk ke kk I kk ko ko kk Kok kk ko ke kk ke ke k k k k The instance data for this composite device J f kk Sk kk ko ke Sk kk ke kk kk kk ko ke kk K k kk k A kk ko ke ke kk ke KK k K kk ko ko ke kk kk kk ok k kk k k kk ko ke kk K k kk ko ke k k ke ke k ke ek tCompositeInstance g Com
57. k kk k k k k ck k Pe ck ck k k k k k kk k k k k ck ck k k k k kc k k kc k k k k k k k k k ck ckckck ck k k k k ck ckck ck k k k ck ck ok unsigned char g_pcDescriptorBuffer COMPOSITE_DDFU_SIZE COMPOSITE_DHID_SIZE 8 Rework the USB library initialization function calls to use the composite device Again follow ing the HID DFU example Initialize each of the device instances that will form our composite USB device g sCompDevice psDevices 0 pvInstance USBDHIDMouseCompositeInit 0 tUSBDHIDMouseDevice amp g_sMouseDevice September 05 2012 117 Device Functions 3 11 2 3 11 3 118 g sCompDevice psDevices 1 pvInstance USBDDFUCompositeInit 0 tUSBDDFUDevice amp g_sDFUDevice Pass the USB library our device information initialize the USB controller and connect the device to the bus USBDCompositeInit 0 amp g sCompDevice DESCRIPTOR BUFFER SIZE g pcDescriptorBuffer Windows Drivers for DFU Devices Since DFU presents itself as another interface on the USB device a device driver is required even though the interface is essentially static and does nothing other than listen for a single request while in runtime mode No version of Microsoft Windows includes a generic Device Firmware Upgrade driver so any application supporting DFU must provide a suitable driver For Stellaris applications a DFU driver is provided in the SWw USB windrivers xxxx package which may be downloaded via
58. kk kk kk kk kk OR kk K kk kk ko kk kk kk k IR kk ko ke kk kk kk Ke ke ke e The interrupt IN endpoint descriptor for the HID keyboard TR K k k ROKR ORR ORR kk Kok kk kk OR kk ko k IRR IR IR IR IR I IK k k k oe const unsigned char g_pHIDInEndpoint Interrupt IN endpoint descriptor en The size of the endpoint descriptor USB DTYPE ENDPOINT Descriptor type is an endpoint USB EP DESC IN USB EP TO INDEX INT IN ENDPOINT USB EP ATTR INT Endpoint is an interrupt endpoint USBShort INT IN EP MAX SIZE The maximum packet size 16 The polling interval for this endpoint J LK K k k k k k k k KKK ROR ORR RR kk ko ko kk ko koc IR k k k k IR IR k k K Kok K k k K IK k k k k k k k The HID keyboard config descriptor is defined using three sections RA 1 The 9 byte configuration descriptor 2 The interface and HID report descriptors 4 The mandatory interrupt IN endpoint descriptor FLASH ih TK k k k k k k k k k k k k k k k k k k k k I I k k k k k k k k k IR IR k k k k I k k k k k k k kck ck ck k k k const tConfigSection g_sKeyboardConfigSection sizeof g_pKeyboardDescriptor g_pKeyboardDescriptor const tConfigSection g sHIDInterfaceSection sizeof g pHIDInterface g pHIDInterface const tConfigSection g_sHIDInEndpointSection September 05 2012 189 Device Functions 3 21 1 3 190 sizeof g_pHIDInEndpoint g_pHIDInEndpoint TK
59. ko kc kk ke kk ko ke kk ko ke ek Ke ke static tHIDKeyboardInstance g sKeyboardInstance m Define a tUSBDHIDKeyboardDevice structure and initialize all fields as required for your application const tUSBDHIDKeyboardDevice g sKeyboardDevice The Vendor ID you have been assigned by USB IF USB_VID_YOUR_VENDOR_ID The product ID you have assigned for this device USB_PID_YOUR_PRODUCT_ID The power consumption of your device in milliamps POWER_CONSUMPTION_mA ae The value to be passed to the host in the USB configuration descriptor s bmAttributes field USB_CONF_ATTR_SELF_PWR A pointer to your keyboard callback event handler YourKeyboardHandler A value that you want passed to the callback alongside every event void amp g sYourInstanceData Ly A pointer to your string table g_pStringDescriptors The number of entries in your string table This must equal 1 5 num languages NUM_STRING_DESCRIPTORS A A pointer to the private instance data allocated for the API to use amp g sKeyboardInstance m Add a keyboard event handler function YourKeyboardHandler in the previous example to your application A minimal implementation can ignore all events since key information is buffered in the API and sent later if USBDHIDKeyboardKeyStateChange is called while a previous report transmission
60. level device class information as well as the Instance data for that class pulDeviceWorkspace A pointer to per device workspace used by the composite device This buffer must be sized to contain at least ulNumDevices long integers or 4 ulNumDevices bytes It must remain accessible for as long as the composite device is in use and must not be modified by any code outside the composite class driver psPrivateData A pointer to RAM work space for this device instance The client must fill in this field with a pointer to at least sizeof tCompositelnstance bytes of read write storage that the library can use for driver work space This memory must remain accessible for as long as the composite device is in use and must not be modified by any code outside the composite class driver Description The structure used by the application to define operating parameters for the composite device class Function Documentation USBDCompositelnit This function should be called once for the composite class device to initialize basic operation and prepare for enumeration Prototype void USBDCompositeInit unsigned long ulIndex tUSBDCompositeDevice psDevice September 05 2012 113 Device Functions 3 10 3 2 3 11 114 unsigned long ulSize unsigned char xpucData Parameters ullndex is the index of the USB controller to initialize for composite device operation psDevice points to a structure containing parameters
61. loaded for this instance of the HID device pfnCallback is the function that will be called whenever changes are detected for this device ulCBData is the data that will be returned in when the pfnCallback function is called September 05 2012 4 5 4 5 4 5 4 6 Host Functions Description This function creates an instance of an specific type of HID device The eDevice Type parameter is one subclass protocol values of the types specified in enumerated types tHIDSubClassProto col Only devices that enumerate with this type will be called back via the pfnCallback function The pfnCallback parameter is the callback function for any events that occur for this device type The pfnCallback function must point to a valid function of type tUSBCallback for this call to complete successfully To release this device instance the caller of USBHHIDOpen should call USBHHIDClose and pass in the value returned from the USBHHIDOpen call Returns This function returns and instance value that should be used with any other APIs that require an instance value If a value of 0 is returned then the device instance could not be created USBHHIDSetldle This function is used to set the idle timeout for a HID device Prototype unsigned long USBHHIDSetIdle unsigned long ulInstance unsigned char ucDuration unsigned char ucReportID Parameters ullnstance is the value that was returned from the call to USBHHIDOpen ucDuration is the duration
62. made to the transmit channel callback pfnTxCallback bUseOutEndpoint f set to true this field indicates that the device should use a dedicated interrupt OUT endpoint to receive reports from the host In this case reports from the host are passed to the application via the receive callback using USB EVENT RX AVAILABLE events If false reports from the host are received via endpoint zero and passed to the application via USBD HID EVENT REPORT SENT events psHiDDescriptor The HID descriptor that the device is to publish following the standard in terface descriptor and prior to the endpoint descriptors for the interface ppClassDescriptors The HID class descriptors offered by the device are defined in an array of byte pointers and this field points to that array The order and number of elements in the array must match the associated information provided in the HID descriptor in field by psHIDDescriptor ppStringDescriptors A pointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manu facturer name string language 1 Product name string language 1 Serial number string language 1 HID Interface description string language 1 Configuration description string language 1 optionally First HID device specific string language 1 optionally Second HID device specific string language 1 etc If supporting more than 1 language the descr
63. odas DEBE Su cese nda eoet E pp E RAM Libet a teda uet iion du edv iE 231 Host ciass Driver DefiilliGIig osos bI ORPbER DERE RA bap adek PAAR MEN SIE EEREDLPMI HD EU PA 243 Host Denice Metatesis WEE RI E UEM ERE de Eam Md Rid Madgex Mme qVEd M qdduas 267 Hast Device Intartace DetbitiQflS cei bE Ete REED CER RE en EEEQEROHP DERE O RN RA P dud gard 268 Host ProdFanmiming EXAMES saacucasqatidckdosd uada ded REa edo Enn EE UEM UA RR d dod R RA dabd 273 Introduction This chapter covers the support provided by the USB library for the USB controller in host mode In order to simplify the application and the addition of new devices and device classes the USB library provides a layered interface to the USB host controller At the top layer of the USB library there are application interfaces that provide easy access to the various types of peripherals that are supported by the USB library Below this layer are the USB host controller s device interfaces that handle the specifics of each type of device and how to communicate with the USB host class driver The USB host class drivers handle the basics of dealing with whole classes of devices like HID and Mass Storage Class devices The USB host class driver layer communicates with the lowest level of the USB library which is the USB host controller driver This lowest level directly accesses DriverLib functions to provide communications with the USB device that is connected This communication is provided by c
64. of functions relates to standard USB descriptor parsing and host device mode con trol Source for these functions can be found in files usbenum c and usbmode c Header file usblib h contains prototypes for these functions along with all data type definitions which are not device or host specific September 05 2012 9 General Purpose Functions 2 2 2 2 2 2 1 2 2 3 2 2 3 1 2 2 3 2 10 Data Structure Documentation tEventinfo Definition typedef struct unsigned long ulEvent unsigned long ulInstance tEventInfo Members ulEvent ullnstance Description This structure is used to return generic event based information to an applica tion The following events are currently supported USB EVENT CONNECTED USB_EVENT_DISCONNECTED USB_EVENT_POWER_FAULT USB_EVENT_POWER_FAULT USB_EVENT_POWER_ENABLE USB_EVENT_POWER_DISABLE and USB_EVENT_SOF Define Documentation USB_DESC_ANY Definition define USB DESC ANY Description The USB DESC ANY label is used as a wild card in several of the descriptor parsing APIs to determine whether or not particular search criteria should be ignored USB EVENT COMP CONFIG Definition define USB_EVENT_COMP_CONFIG Description This define is used with a device class s pfnDeviceHandler handler function to indicate that the USB library has changed the configuration descriptor This allows the class to make final ad justments to the configuration
65. of the timeout in milliseconds ucReportiD is the report identifier to set the timeout on Description This function will send the Set Idle command to a HID device to set the idle timeout for a given report The length of the timeout is specified by the ucDuration parameter and the report the timeout for is in the ucReportiD value Returns Always returns 0 USBHHIDSetProtocol This function is used to set or clear the boot protocol state of a device Prototype unsigned long USBHHIDSetProtocol unsigned long ulInstance unsigned long ulBootProtocol Parameters ullnstance is the value that was returned from the call to USBHHIDOpen ulBootProtocol is either zero or non zero to indicate which protocol to use for the device September 05 2012 249 Host Functions 4 5 4 7 4 5 4 8 250 Description A USB host device can use this function to set the protocol for a connected HID device This is commonly used to set keyboards and mice into their simplified boot protocol modes to fix the report structure to a know state Returns This function returns 0 USBHHIDSetReport This function is used to send a report to a HID device Prototype unsigned long USBHHIDSetReport unsigned long ulInstance unsigned long ulInterface unsigned char xpucData unsigned long ulSize Parameters ullnstance is the value that was returned from the call to USBHHIDOpen ullnterface is the interface to send
66. parameters pvCBData and ulEvent parameters are valid The pvCBData is the value that was returned when the application called USBDMSCInit and can be used with other APIs The ulEvent parameter is one of the USBD MSC EVENT gt values Misc Features The mass storage class can be configured to use the uDMA or can function without DMA if the application does not require DMA To enable the use of DMA the ulFlags value should have the USBD FLAG USE DMA bit set Note Due to errata on some microcontrollers the uDMA should not be used with mass storage class device the Mass Storage Device Class The following sections has some coding examples for the initialization of the mass storage class structures as well as how to call the initialization function itself Example Device Structure const tUSBDMSCDevice g sMSCDevice Vendor ID if USB_VID_LUMINARY Product ID USB_PID_MSC Vendor Information TI m September 05 2012 177 Device Functions 178 Product Identification Mass Storage v Revision 1 00 500mA 500 EA Bus Powered USB_CONF_ATTR_BUS_PWR A list of string descriptors and the number of descriptors ff g_pStringDescriptors NUM_STRING_DESCRIPTORS The media access functions USBDMSCStorageOpen USBDMSCStorageClose USBDMSCStorageRead USBDMSCStorageWrite USBDMSCStor
67. reception of this callback the device code is free to reuse the outgoing data buffer if required If this member of scallbacks is set to NULL the USB Device API will not inform the device code when a block of EPO data is sent pfnResetHandler The p nResetHandler callback is made by the USB Device API whenever a bus reset is detected This will typically occur during enumeration The device code may use this notification to perform any housekeeping required in preparation for a new configuration being set If this member of scallbacks is set to NULL the USB Device API will not inform the device code when a bus reset occurs pfnSuspendHandler The p nSuspendHandler callback is made whenever the USB Device API detects that suspend has been signaled on the bus Device code may make use of this notification to for example set appropriate power saving modes If this member of scallbacks is set to NULL the USB Device API will not inform the device code when a bus suspend occurs pfnResumeHandler The pfnResumeHandler Callback is made whenever the USB Device API detects that resume has been signaled on the bus Device code may make use of this notification to undo any changes made in response to an earlier call to the pfnSuspendHandler callback September 05 2012 Device Functions If this member of sCcallbacks is set to NULL the USB Device API will not inform the device code when a bus resume occurs 3 21 2 10 pfnDisconnectHand
68. remains unacknowledged September 05 2012 167 Device Functions m From your main initialization function call the HID keyboard device API initialization function to configure the USB controller and place the device on the bus pDevice USBDHIDKeyboardInit 0 amp g sKeyboardDevice m Assuming pDevice returned is not NULL your keyboard device is now ready to communicate with a USB host m Once the host connects your keyboard event handler will be sent USB EVENT CONNECTED after which calls can be made to USBDHIDKeyboardKeyStateChange to inform the host of key press and release events 3 18 HID Keyboard Device Class API Definitions Data Structures m tUSBDHIDKeyboardDevice Defines m KEYB ERR NOT CONFIGURED m KEYB ERR NOT FOUND m KEYB ERR TOO MANY KEYS m KEYB ERR TX ERROR m m u KEYB MAX CHARS PER REPORT KEYB SUCCESS USBD HID KEYB EVENT SET LEDS Functions m void x USBDHIDKeyboardCompositelnit unsigned long ullndex const tUSBDHIDKeyboard Device xpsDevice void x USBDHIDKeyboardInit unsigned long ullndex const tUSBDHIDKeyboardDevice psDevice unsigned long USBDHIDKeyboardKeyStateChange void xpvinstance unsigned char ucMod ifiers unsigned char ucUsageCode tBoolean bPress void USBDHIDKeyboardPowerStatusSet void pvInstance unsigned char ucPower tBoolean USBDHIDKeyboardRemoteWakeupRequest void pvInstance void x USBDHIDKeyboardSetCBData void xpvinstance void pvCB
69. returns the second matching descriptor Description Return a pointer to the n th descriptor of a particular type found in the block of u Size bytes starting at psDesc Returns Returns a pointer to the header of the required descriptor if found or NULL otherwise USBDescGetlnterface Returns a pointer to the n th interface descriptor in a configuration descriptor that applies to the supplied alternate setting number Prototype tInterfaceDescriptor USBDescGet Interface tConfigDescriptor xpsConfig unsigned long ulIndex unsigned long ulAlt Parameters psConfig points to the first byte of a standard USB configuration descriptor ullndex is the zero based index of the interface that is to be found If ulAlt is set to a value other than USB DESC ANY this will be equivalent to the interface number being searched for ulAlt is the alternate setting number which is to be searched for If this value is USB DESC ANY the alternate setting is ignored and all interface descriptors are con sidered in the search Description Return a pointer to the n th interface descriptor found in the supplied configuration descriptor If ulAlt is not USB DESC ANY only interface descriptors which are part of the supplied alter nate setting are considered in the search otherwise all interface descriptors are considered Note that although alternate settings can be applied on an interface by interface basis the number of interfaces offere
70. rr 0 tor J kk ke kk kk e e kk Sk ke ke kk ke KR IR ORI OR ORR ok kk ke kk k k k k k k k k k k ko kk ke k k ke k k ke k e The product string J k H k K ROK ke kk ke ke Sk kk ke kk kk kk kk RR IR ORR I kk kk k k k k k k k k I OR ke ke ke k ke ke k e const unsigned char g pProductString 16 1 2 USB DTYPE STRING eK Oy tet Op y Oy b 0 Col 0 aly Op VE p 0j tdt On t Oy E Q Rp 04 Cary OF Tm py Spl 0 3 e 0r tef TORK RR OK kk kk kk Kk kk kk kk ko ke OR OR OR OR IR IR IR IR I IIR I oe The serial number string J Kk ck koe ke kk ek kk ke kk ee eee Pe eee eee eee ee eee ee ee ck ck ck ck ee ee ee ees const unsigned char g pSerialNumberString 8 1 2 USB_DTYPE_STRING FETU 0 d o 0 Fata 0 rar 0 St s 0 E 0 LET 0 Fg 0 J kk ke k k k ke kk ke kk k k kk ko ke kk kk ke kk he ke Sk kk ke Sk kk kk kk kk ko k k Sk k k ok k k k k kk k ke kk I kc kk oko k k k ke kk ke ke ke ke ke e The array of string descriptors needed by the enumeration code J f kk ke koe ke kk ORR kk kk ke kk ke ke Sk kk RRR IR ROR ok kk kk kk kk kk IR I II ke ke ke ke oe const unsigned char const g ppStringDescriptors g_pLangDescriptor g_pManufacturerString g_pProductString g_pSerialNumberString In this example the ppSt ringDescriptors member of the tDeviceInfo structure would be ini tialized with the value g_ppStringDescriptors and the ulNumStringDesc
71. should be noted that special keys like the Caps Lock key require notifying the actual keyboard device that the host application has detected that the key has been pressed USBH EVENT HID KB REL The ulMsgParam parameter has the USB usage identifier for the key that has been released USBH EVENT HID KB MOD The ulMsgParam parameter has the current state of all of the modifier keys on the connected keyboard This value is a bit mapped representation of the modifier keys that can have any of the following bits set m HID KEYB LEFT CTRL HID KEYB LEFT SHIFT m HID KEYB LEFT ALT HID KEYB LEFT GUI HID KEYB RIGHT CTRL HID KEYB RIGHT SHIFT HID KEYB RIGHT ALT m HID KEYB RIGHT GUI Host Device Interface Definitions Functions m unsigned long USBHKeyboardClose unsigned long ullnstance m unsigned long USBHKeyboardilnit unsigned long ullnstance m unsigned long USBHKeyboardModifierSet unsigned long ullnstance unsigned long ulModi fiers m unsigned long USBHKeyboardOpen tUSBCallback pfnCallback unsigned char pucBuffer unsigned long ulSize September 05 2012 4 7 1 4 7 2 4 7 2 1 4 7 2 2 Host Functions m unsigned long USBHKeyboardPollRateSet unsigned long ullnstance unsigned long ulPoll Rate m unsigned long USBHKeyboardUsageToChar unsigned long ullnstance const tHIDKeyboard UsageTable xpTable unsigned char ucUsagelD unsigned long USBHMouseClose unsigned long ullnstance unsigned long USBHMouselni
72. state change the device sends a new copy of the relevant input report to the host via the interrupt IN endpoint This is accomplished by calling USBDHIDReportWrite Whereas other USB device class drivers require that the application send no more than 1 packet of data in each call to the driver s PacketWrite function the HID device class driver allows a complete report to be sent If the report passed is longer than the maximum packet size for the endpoint 64 bytes the class driver handles the process of breaking it up into multiple USB packets Once a full report has been transmitted to the host and acknowledged the application s transmit event handler receives USB EVENT TX COMPLETE indicating that the application is free to send another report The host may also poll for the latest version of an input report This procedure involves a request on endpoint zero and results in a sequence of events that the application must respond to On receipt of the Get Report request the HID device class driver sends USBD HID EVENT GET REPORT to the application receive callback The application must respond to this by returning a pointer to the latest version of the requested report and the size of the report in bytes This data is then returned to the host via endpoint zero and successful completion of the transmission is notified to the application using USBD HID EVENT REPORT SENT passed to the receive callback
73. structure members These strings may or may not be requested by the USB host controller however they are required The pucVendor member is an 8 byte character string for the Vendor and should be exactly 8 bytes padded with spaces for example TI The pucProduct member is a 16 character string that indicates the product type and it too should be padded out with spaces to 16 bytes for example Mass Storage The last customizable mass storage string is contained in pucVer sion member and is a character based version which should be a 4 bytes padded with spaces for example 1 00 Power Configuration The power configuration for the mass storage class device is held in two of the tUSBDMSCDevice members variables usMaxPowermA and ucPwrAttributes The usMaxPowermA variable holds the maximum power consumption for the device and is expressed in milliamps The power configuration is held in the ucPwrAttributes member variable and indicates whether the device is self or bus powered Valid values are USB CONF ATTR SELF PWR or USB CONF ATTR BUS PWR Device Strings The remaining USB strings are contained in the ppStringDescriptors and are just like the strings that are used in every other device class in the USB library The ppStringDescriptors is a pointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manufacturer name string language 1 P
74. such safety critical applications TI products are neither designed nor intended for use in military aerospace applications or environments unless the TI products are specifi cally designated by TI as military grade or enhanced plastic Only products designated by TI as military grade meet military specifications Buyers acknowledge and agree that any such use of TI products which TI has not designated as military grade is solely at the Buyer s risk and that they are solely responsible for compliance with all legal and regulatory requirements in connection with such use TI products are neither designed nor intended for use in automotive applications or environments unless the specific TI products are designated by TI as compliant with ISO TS 16949 requirements Buyers acknowledge and agree that if they use any non designated products in automotive applications TI will not be responsible for any failure to meet such requirements Following are URLs where you can obtain information on other Texas Instruments products and application solutions Products Applications Audio www ti com audio Automotive and Transportation www ti com automotive Amplifiers amplifier ti com Communications and Telecom www ti com communications Data Converters dataconverter ti com Computers and Peripherals www ti com computers DLP Products www dlp com Consumer Electronics www ti com consumer apps DSP dsp ti com Energy and Lighting www ti co
75. tUSBHostAudioCallback pfnCallback unsigned long USBHostAudioVolumeGet unsigned long ullnstance unsigned long ullnter face unsigned long ulChannel unsigned long USBHostAudioVolumeMaxGet unsigned long ullnstance unsigned long ulln terface unsigned long ulChannel unsigned long USBHostAudioVolumeMinGet unsigned long ullnstance unsigned long ulln terface unsigned long ulChannel unsigned long USBHostAudioVolumeResGet unsigned long ullnstance unsigned long ulln terface unsigned long ulChannel void USBHostAudioVolumeSet unsigned long ullnstance unsigned ullnterface unsigned long ulChannel unsigned long ulValue unsigned long USBHSCSIInquiry unsigned long ullnPipe unsigned long ulOutPipe unsigned char xpucData unsigned long xpulSize unsigned long USBHSCSIModeSense6 unsigned long ullnPipe unsigned long ulOutPipe unsigned long ulFlags unsigned char pucData unsigned long xpulSize unsigned long USBHSCSIRead10 unsigned long ullnPipe unsigned long ulOutPipe un signed long ulLBA unsigned char pucData unsigned long pulSize unsigned long ulNum Blocks unsigned long USBHSCSIReadCapacities unsigned long ullnPipe unsigned long ulOutPipe unsigned char pucData unsigned long pulSize unsigned long USBHSCSIReadCapacity unsigned long ullnPipe unsigned long ulOutPipe unsigned char pucData unsigned long pulSize unsigned long USBHSCSIRequestSense unsigned long ullnPipe unsigned long ulOutPipe unsigned
76. that a mute request has occured The u Param value will either be a 1 to indicate that the audio is now muted and a value of 0 indicates that the audio has been unmuted USBD AUDIO EVENT VOLUME Definition define USBD AUDIO EVENT VOLUME Description This USB audio event indicates that a volume change has occured The u Param value con tains a signed 8 8 fixed point value that represents the current volume gain attenuation in deci bels dB The provided message handler should be prepared to handle negative and positive values with the value 0x8000 indicating maximum attenuation The pvBuffer parameter should be ignored Function Documentation USBAudioBufferOut This function is used to supply buffers to the audio class to be filled from the USB host device Prototype long USBAudioBufferOut void pvInstance void xpvBuffer unsigned long ulSize tUSBAudioBufferCallback pfnCallback September 05 2012 3 4 4 2 Device Functions Parameters pvinstance is the pointer to the device instance structure as returned by USBDAudiolnit or USBDAudiolnitComposite pvBuffer is a pointer to the buffer to fill with audio data ulSize is the size in bytes of the buffer pointed to by the pvBuffer parameter pfnCallback is a callback that will provide notification when this buffer has valid data Description This function fills the buffer pointed to by the pvBuffer parameter with at most ulSize one packet of data from t
77. the current volume setting ulChannel is the 0 based channel number to query Description The function is used to retrieve the current volume setting for an audio device on the channel specified by ulChannel The ullnterface is ignored for now and should be set to 0 to access the default audio control interface The ulChannel value starts with O which is the master audio volume control interface The remaining u Channel values provide access to various other audio channels with 1 and 2 being left and right audio channels Note On devices that do not support volume control interfaces this call returns 0 indicating a Odb setting Returns Returns the current volume setting for the requested interface 4 5 4 24 USBHostAudioVolumeMaxGet This function is used to get the maximum volume setting for a given audio device 258 September 05 2012 4 5 4 25 Host Functions Prototype unsigned long USBHostAudioVolumeMaxGet unsigned long ulInstance unsigned long ullInterface unsigned long ulChannel Parameters ullnstance is an instance of the USB audio device ullnterface is the interface number to use to query the maximum volume control value ulChannel is the 0 based channel number to query Description The function is used to retrieve the maximum volume setting for an audio device on the channel specified by ulChannel The ullnterface is ignored for now and should be set to 0 to access the default audio control int
78. the device instance structure as returned by USBDBUlklnit Description This function returns the maximum number of bytes that can be passed on a call to USBD BulkPacketWrite and accepted for transmission The value returned will be the maximum USB packet size 64 if no transmission is currently outstanding or 0 if a transmission is in progress September 05 2012 3 7 3 7 1 Device Functions Returns Returns the number of bytes available in the transmit buffer CDC Device Class Driver The USB Communication Device Class CDC class driver supports the CDC Abstract Control Model variant and allows a client application to be seen as a virtual serial port to the USB host system The driver provides two channels one transmit and one receive The channels may be used in conjunction with USB buffers to provide a simple read write interface for data transfer to and from the host Additional APIs and events are used to support serial link specific operations such as notification of UART errors sending break conditions and setting communication line parameters The data transmission capabilities of this device class driver are very similar to the generic bulk class but since this is a standard device class the host operating system will likely be able to access the device without the need for any special additional device drivers On Windows for example a simple INF file is all that is required to make the USB de vice appear as a COM p
79. the host audio driver by calling USBHostAudioPlay and September 05 2012 Host Functions including a callback function for the buffer The buffers are returned to the application by the call back to the application provided in the USBHostAudioPlay This allows the application to gain control while the audio is being scheduled for output The audio input is handled by providing buffers to the host audio driver by calling USBHostAudioRecord and passing in a buffer callback as well Buffers are then scheduled to be filled by the USB controller and returned to the application by the callback function that the application provided in the USBHostAudioRecord call The next section provides more detail and examples for each application level API Application Interface The USB host audio application interface provides a basic method for controlling audio output input and some volume control Since the USB host audio provides only a small amount of buffering it is up to the application to provide adequate buffering based on it s other functions to keep the audio stream from starving for data The USB host audio driver requires some initial configuration by the application that is outside of the USB audio driver s control The first of these is to enable the uDMA controller and configure a DMA control table that includes the USB DMA channels The application must also register the USB host audio driver by calling USBHCDRegisterDrive
80. the report data has been read from end point zero into the buffer supplied on the earlier USBD_HID_EVENT_GET_REPORT_BUFFER callback The device class the application may handle driver will not access the report buffer after this event is sent and the memory as it wishes following this point HID Device Class Driver Definitions Data Structures tHIDClassDescriptorlInfo tHIDDescriptor tHIDKeyboardUsageTable tHIDReportldle tUSBDHIDDevice Defines Collection ucValue COMPOSITE DHID SIZE EndCollection Feature ucValue Feature2 usValue Input ucValue Input2 usValue LogicalMaximum cValue LogicalMinimum cValue Output ucValue Output2 usValue PhysicalMaximum sValue PhysicalMinimum sValue ReportCount ucValue ReportlD ucValue ReportSize ucValue Unit ulValue UnitAccelerationSl September 05 2012 Device Functions m UnitAngAccelerationSl m UnitCurrent A m UnitDistance cm m UnitDistance i m UnitEnergySl m UnitExponent cValue m UnitForceSl m UnitMass g m UnitMomentumSI m UnitRotation deg m UnitRotation rad m UnitTemp F m UnitTemp K m UnitTime s m UnitVelocityS m UnitVoltage m Usage ucValue m UsageMaximum ucValue m UsageMinimum ucValue m UsagePage ucValue m USBD HID EVENT GET PROTOCOL m USBD HID EVENT GET REPORT m USBD HID EVENT GET REPORT BUFFER m USBD HID EVENT IDLE TIMEOUT m USBD HID EVENT REPORT SENT m USBD HID EVENT SET PROTOCOL m USBD HID
81. the report to pucData is the memory buffer to use to store the report ulSize is the size in bytes of the buffer pointed to by pucBuffer Description This function is used to send a report to a USB HID device It can be only be called from outside the callback context as this function will not return from the call until the data has been sent successfully Returns Returns the number of bytes sent to the device USBHHubClose This function is used to release a hub device instance Prototype void USBHHubClose unsigned long ulInstance Parameters ullnstance is the hub device instance that is to be released Description This function is called when an instance of the hub device must be released This function is typically made in preparation for shutdown or a switch to function as a USB device when in OTG mode Following this call the hub device is no longer available but it can be opened again using a call to USBHHubOpen After calling USBHHubClose the host hub driver no longer provides any callbacks or accepts calls to other hub driver APIs September 05 2012 4 5 4 9 4 5 4 10 4 5 4 11 Host Functions Returns None USBHHubEnumerationComplete Informs the hub class driver that a downstream device has been enumerated Prototype void USBHHubEnumerationComplete unsigned char ucHub unsigned char ucPort Parameters ucHub is the address of the hub to which the downstream device is attached ucP
82. the results into pulSize is the size of buffer that was passed in on entry and the number of bytes returned Description This function should be used to issue a SCSI Read Capacities command to a mass storage device that is connected To allow for multiple devices the u InPipe and ulOutPipe parameters indicate which USB pipes to use for this call Returns This function returns the SCSI status from the command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL September 05 2012 263 Host Functions 4 5 4 32 4 5 4 33 264 USBHSCSIReadCapacity This will issue the SCSI read capacity command to a device Prototype unsigned long USBHSCSIReadCapacity unsigned long ulInPipe unsigned long ulOutPipe unsigned char xpucData unsigned long xpulSize Parameters ullnPipe is the USB IN pipe to use for this command ulOutPipe is the USB OUT pipe to use for this command pucData is the data buffer to return the results into pulSize is the size of buffer that was passed in on entry and the number of bytes returned Description This function should be used to issue a SCSI Read Capacity command to a mass storage device that is connected To allow for multiple devices the ulInPipe and ulOutPipe parameters indicate which USB pipes to use for this call Note The pucData buffer pointer should have at least SCSI READ CAPACITY SZ bytes of data or this function will overflow the buffer Returns Th
83. the ring buffer ahead of the current read pointer This represents the largest block of data which does not straddle the buffer wrap Returns Returns the number of contiguous bytes available USBRingBufEmpty Determines whether a ring buffer is empty or not Prototype tBoolean USBRingBufEmpty tUSBRingBufObject ptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to empty Description This function is used to determine whether or not a given ring buffer is empty The structure is specifically to ensure that we do not see warnings from the compiler related to the order of volatile accesses being undefined Returns Returns true if the buffer is empty or false otherwise September 05 2012 47 General Purpose Functions 2 4 6 18 2 4 6 19 2 4 6 20 48 USBRingBufFlush Empties the ring buffer Prototype void USBRingBufF lush tUSBRingBufObject ptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to empty Description Discards all data from the ring buffer Returns None USBRingBufFree Returns number of bytes available in a ring buffer Prototype unsigned long USBRingBufFree tUSBRingBufObject ptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to check Description This function returns the number of bytes available in the ring buffer Returns Returns the number of bytes available in the ring buffer USBRingBufFull Determines whether
84. to USB host device or On The Go OTG operation The functions and types described here fall into three main categories m Definitions of USB standard types as found in Chapter 9 of the USB 2 0 specification and functions to parse them Functions relating to host device mode switching for On The Go or dual mode applications m USB device class header files Source Code Overview Source code and headers for the general purpose USB functions can be found in the top level directory of the USB library tree typically DriverLib usblib usblib h The main header file for the USB library containing all data types and def initions which are common across the library as a whole Prototypes for general purpose API functions are also included All clients of the USB Li brary should include this header usb ids h The header file containing labels defining the Texas Instruments Stellaris USB vendor ID VID and product IDs PIDs for each of the example de vices provided in USB capable evaluation kits usbmsc h The header file containing definitions specific to the USB Mass Storage Class usbcdc h The header file containing definitions specific to the USB Communication Device Class usbhid h The header file containing definitions specific to the USB Human Interface Device Class usbdesc c The source code for a set of functions allowing parsing of USB descriptors usbbuffer c The source code for a set of functions use to support bufferi
85. to open an instance of a mass storage device It should be called before any devices are connected to allow for proper notification of drive connection and disconnec tion The u Drive parameter is a zero based index of the drives present in the system There are a constant number of drives and this number should only be greater than 0 if there is a USB hub present in the system The application should also provide the pfnCallback to be notified of mass storage related events like device enumeration and device removal Returns This function will return the driver instance to use for the other mass storage functions If there is no driver available at the time of this call this function will return zero USBHMSCDriveReady This function checks if a drive is ready to be accessed Prototype long USBHMSCDriveReady unsigned long ulInstance Parameters ullnstance is the device instance to use for this read Description This function checks if the current device is ready to be accessed It uses the ullnstance parameter to determine which device to check and will return zero when the device is ready Any non zero return code indicates that the device was not ready Returns This function will return zero if the device is ready and it will return a other value if the device is not ready or if an error occurred September 05 2012 Host Functions 4 5 4 17 USBHostAudioClose 4 5 4 18 This function should be called to release
86. to the function that should be called to determine the size of buffer required to read a newly received packet Using the same example a transmit buffer above the USB generic bulk device class driver would have this field set to point to US BDBulkTxPacketAvailable and a receive buffer above the same driver would set the field to point to USBDBulkRxPacketAvailable pvHandle This field must be set to the handle which should be passed as the first parameter to the functions provided in pfnTransfer and pfnAvailable This will typically be a pointer to the instance structure for the lower layer object in use In the case of the USB generic bulk device class this would be the tUSBDBulkDevice pointer originally passed to and returned from USBDBulkinit pcBuffer This field must be initialized to point to the block of RAM that will be used to buffer data on this channel The buffer will be managed as a ring buffer If the application wishes to access the buffer directly rather than via the USBBufferRead and USBBufferWrite APIs thus avoid ing a copy operation it is vital to ensure that ring wrap conditions are correctly handled in the application code ulBufferSize This field provides the size of the buffer pointed to by pcBuffer in bytes pvWorkspace The USB buffer requires a block of RAM in which it can store state vari ables This field points to application supplied RAM that can be used as workspace by the buffer object This RAM mu
87. type tDFUInstance ensuring that the linker places it in SRAM This will be used as workspace by the DFU class driver 5 Define a structure of type tUSBDFUDevice and initialize it to contain a pointer to your callback function and instance data workspace J kk KK ROKR KR IR IR OR OR kk Ck ke kk Kok kk ko ke OR OR IR I ko kk IR I kk A I I ke ee The DFU runtime interface initialization and customization structures kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk kx tDFUInstance g_sDFUInstance const tUSBDDFUDevice g_sDFUDevice DFUDetachCallback void amp g_sDFUDevice September 05 2012 115 Device Functions 116 amp g_sDFUInstance Create an array of structures of type tCompositeEntry which define the individual device class instances that are to be used in the composite device A structure defining a composite device containing a HID interface and the DFU runtime interface would look like the following J kk kk Sk ko ke k k k ke kk kk kk A k kk ko ke kk k K kk A k kk kk KK kk kk ko ko kk kc kk k k ke kk I ko kk ko kk ko ke kk ko ke kk ke ke k ke ek The number of device class instances that this composite device will use J kk k ke k k k ke k k ee k k k k k k k k k k ee k k k k k k k kk ck k k k k k k k k ee k k k k k k k k kk ck ck ckck ck ck ck k ck ck ckck ck ck ck ck ck k k define NUM_DEVICES 2 J kk K k k ke k k k k k k k RR ORR k k ko RR RRR IR OR k
88. typedef struct September 05 2012 Device Functions tStdRequest pfnGetDescriptor tStdRequest pfnRequestHandler tInterfaceCallback pfnInterfaceChange tInfoCallback pfnConfigChange tInfoCallback pfnDataReceived tInfoCallback pfnDataSent tUSBIntHandler pfnResetHandler tUSBIntHandler pfnSuspendHandler tUSBIntHandler pfnResumeHandler tUSBIntHandler pfnDisconnectHandler tUSBEPIntHandler pfnEndpointHandler tUSBDeviceHandler pfnDeviceHandler tCustomHandlers Members pfnGetDescriptor This callback is made whenever the USB host requests a non standard descriptor from the device pfnRequestHandler This callback is made whenever the USB host makes a non standard request pfninterfaceChange This callback is made in response to a Setlnterface request from the host pfnConfigChange This callback is made in response to a SetConfiguration request from the host pfnDataReceived This callback is made when data has been received following to a call to USBDCDRequestDataEPO pfnDataSent This callback is made when data has been transmitted following a call to USB DCDSenaDataEPO pfnResetHandler This callback is made when a USB reset is detected pfnSuspendHandler This callback is made when the bus has been inactive long enough to trigger a suspend condition pfnResumeHandler This is called when resume signaling is detected pfnDisconnectHandler This callback is made when the device is disconnected from the U
89. will result in a return code of 0 indicating that the data cannot be sent Returns Returns the number of bytes actually sent At this level this will either be the number of bytes passed if less than or equal to the maximum packet size for the USB endpoint in use and no outstanding transmission ongoing or 0 to indicate a failure USBDCDCPowerStatusSet Reports the device power status bus or self powered to the USB library Prototype void USBDCDCPowerStatusSet void pviInstance unsigned char ucPower Parameters pvinstance is the pointer to the CDC device instance structure ucPower indicates the current power status either USB STATUS SELF PWR or USB STATUS BUS PWR Description Applications which support switching between bus or self powered operation should call this function whenever the power source changes to indicate the current power status to the USB September 05 2012 101 Device Functions 3 8 4 6 3 8 4 7 102 library This information is required by the USB library to allow correct responses to be provided when the host requests status from the device Returns None USBDCDCRemoteWakeupRequest Requests a remote wakeup to resume communication when in suspended state Prototype tBoolean USBDCDCRemoteWakeupRequest void pviInstance Parameters pvinstance is the pointer to the CDC device instance structure Description When the bus is suspended an application which supports remote w
90. 1 5 num HID strings num languages sMediaFunctions This structure holds the access functions for the media used by this in stance of the mass storage class device All of the functions in this structure are required to be filled out with valid functions pfnEventCallback This is the callback function for various events that occur during mass stor age class operation psPrivateData A pointer to the private instance data for this device This memory must remain accessible for as long as the MSC device is in use and must not be modified by any code outside the MSC class driver Description The structure used by the application to define operating parameters for the mass storage device 3 20 3 Define Documentation 3 20 3 1 COMPOSITE DMSC SIZE Definition define COMPOSITE_DMSC_SIZE Description The size of the memory that should be allocated to create a configuration descriptor for a single instance of the USB Audio Device This does not include the configuration descriptor which is automatically ignored by the composite device class 3 20 3 2 USBD MSC EVENT IDLE Definition define USBD MSC EVENT IDLE Description This event indicates that the host has completed other operations and is no longer accessing the device 3 20 3 3 USBD MSC EVENT READING Definition define USBD_MSC_EVENT_READING Description This event indicates that the host is reading the storage media Se
91. 10 bytes long bDescriptorType The type of the descriptor For a device descriptor this will be USB_DTYPE_DEVICE_QUAL 6 bcdUSB The USB Specification Release Number in BCD format For USB 2 0 this will be 0x0200 bDeviceClass The device class code bDeviceSubClass The device subclass code This value qualifies the value found in the bDe viceClass field bDeviceProtocol The device protocol code This value is qualified by the values of bDevice Class and bDeviceSubClass bMaxPacketSize0 The maximum packet size for endpoint zero when operating at a speed other than high speed bNumConfigurations The number of other speed configurations supported September 05 2012 29 General Purpose Functions bReserved Reserved for future use Must be set to zero Description This structure describes the USB device qualifier descriptor as defined in the USB 2 0 specifi cation section 9 6 2 2 3 2 5 tEndpointDescriptor Definition typedef struct unsigned char bLength unsigned char bDescriptorType unsigned char bEndpointAddress unsigned char bmAttributes unsigned short wMaxPacketSize unsigned char bInterval t EndpointDescriptor Members bLength The length of this descriptor in bytes All endpoint descriptors are 7 bytes long bDescriptorType The type of the descriptor For an endpoint descriptor this will be USB_DTYPE_ENDPOINT 5 bEndpointAddress The address of the endpoint This field contains th
92. 2 s 2 into a report descriptor 3 14 3 24 UnitExponent This is a macro to assist adding Unit Exponent entries in HID report descriptors Definition define UnitExponent cValue Parameters cValue is the required exponent in the range 8 7 Description This macro takes a value and prepares it to be placed as a Unit Exponent entry into a HID report structure This is the exponent applied to PhysicalMinimum and PhysicalMaximum when scaling and converting control values to real units Returns Not a function 3 14 3 25 UnitForceS Definition define UnitForceSI Description This macro inserts a Unit entry for force in cm grams s 2 into a report descriptor 3 14 3 26 UnitMass_g Definition define UnitMass_g Description This macro inserts a Unit entry for grams into a report descriptor September 05 2012 145 Device Functions 3 14 3 27 UnitMomentumS Definition define UnitMomentumSI Description This macro inserts a Unit entry for momentum in grams cm s into a report descriptor 3 14 3 28 UnitRotation deg Definition define UnitRotation deg Description This macro inserts a Unit entry for degrees into a report descriptor 3 14 3 29 UnitRotation rad Definition define UnitRotation rad Description This macro inserts a Unit entry for radians into a report descriptor 3 14 3 30 UnitTemp F Definition define UnitTemp F Description This macro inserts a Unit
93. 2012 2 2 6 9 2 2 6 10 2 2 6 11 General Purpose Functions Returns None USBDualModeTerm Returns the USB controller to the default mode when in dual mode operation Prototype void USBDualModeTerm unsigned long ulIndex Parameters ullndex specifies the USB controller whose dual mode operation is to be ended This param eter must be set to 0 Description Applications using both host and device modes may call this function to disable interrupts in preparation for shutdown or a change of operating mode Returns None USBOTGMain This function is the main routine for the OTG Controller Driver Prototype void USBOTGMain unsigned long ulMsTicks Parameters ulMsTicks is the number of milliseconds that have passed since the last time this function was called Description This function is the main routine for the USB controller when using the library in OTG mode This routine must be called periodically by the main application outside of a callback context The ulMsTicks value is used for basic timing needed by the USB library when operating in OTG mode This allows for a simple cooperative system to access the the OTG controller driver interface without the need for an RTOS All time critical operations are handled in interrupt context but all longer operations are run from the this function to allow them to block and wait for completion without holding off other interrupts Returns None USBOTGMo
94. API as an array of string descriptors containing the basic descriptor length and type header followed by a Unicode string The various string identifiers passed in other descriptors are indexes into the pStringDescriptor array The first entry of the string descriptor array has a special format and indicates the languages supported by the device The field ulNumStringDescriptors indicates the number of individual string descriptors in the ppStringDescriptors array The string descriptor array provided to the USB Device API for a USB HID keyboard follows J f kk kk k k k k k k k k k k k OR kk k k kk ko ke kk kk k k k k k k k k k k k k k k k k I k k k k k k k k k k k k I II I k k oe The languages supported by this device TKK ROKR RRR ORR kk ko ke kk kk OR IR IR I IR IR I RR I II I oe const unsigned char g_pLangDescriptor 4 USB_DTYPE_STRING USBShort USB_LANG_EN_US J f kk kk oko kk Kok kk kk kk Kk kk Kok kk kk kk ko ke kk kk kk kk kk ck ko kk ko Kk Kok kk Kok kk Kok ko kk oko kk ko ke kk ko ke ek ke e September 05 2012 3 21 2 Device Functions The manufacturer string J kk KORO kk ke ke Sk kk ok kk kk kk kk kk kk kk kk kk Kok ke kk ok kk kk kk I I RR IR kk ko ke I ke ke a ke ke e const unsigned char g pManufacturerString 19 1 2 USB DTYPE STRING L 0 rar 0 m 0 ril 0 Tnt 0 a 0 ery 0 y 0 d y 0 M 0 Pal 0 Por s 0 E 0 Hol 0 r am 0 ia 0 1
95. All support devices must have a host class driver loaded in order to communicate with each type of device that is supported The details of interacting with these host class drivers is explained in the host class driver sections that follow in this document Application Termination When the application needs to shut down the host controller it needs to shutdown all host class drivers and then shut down the host controller itself This gives the host class drivers a chance to close cleanly by calling each host class driver s close function Then the USBHCDTerm function should be called to shut down the host controller This sequence leaves the USB controller and the USB library stack in a state so that it is ready to be re initialized or in order to switch USB mode from host to device Example Application Setup The following example shows the basic setup code needed for any application that is using the USB library in host mode The g_pHCDPool array which is passed in to the USBHCDInit is used as heap memory for by the USB library and thus the memory should not be used by the application In this example the g ppHostClassDrivers array holds both HID and MSC class drivers making it possible for both types of devices to be supported However if the application only needs to include the classes that it needs to support in order to save code and memory space The pin and peripheral September 05 2012 Host Functions configuration is left to the
96. BDHIDKeyboardKeyStat eChange to report key presses and releases to the USB host Note The application must not make any calls to the lower level USB device interfaces if interact ing with USB via the USB HID keyboard device class API Doing so will cause unpredictable though almost certainly unpleasant behavior Returns Returns NULL on failure or the psDevice pointer on success USBDHIDKeyboardKeyStateChange Reports a key state change to the USB host Prototype unsigned long USBDHIDKeyboardKeyStateChange void pvlInstance unsigned char ucModifiers September 05 2012 Device Functions unsigned char ucUsageCode tBoolean bPress Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDKeyboard Init ucModifiers contains the states of each of the keyboard modifiers left right shift ctrl alt or GUI keys Valid values are logical OR combinations of the la bels HID KEYB LEFT CTRL HID KEYB LEFT SHIFT HID KEYB LEFT ALT HID KEYB LEFT GUI HID KEYB RIGHT CTRL HID KEYB RIGHT SHIFT HID KEYB RIGHT ALT and HID KEYB RIGHT GUI Presence of one of these bit flags indicates that the relevant modifier key is pressed and absence indicates that it is released ucUsageCode is the usage code of the key whose state has changed If only modifier keys have changed HID KEYB USAGE RESERVED should be passed in this parameter bPress is true if the key has been pressed or false if it has bee
97. BEndpointStatus for the appropriate endpoint then clear the status by calling USBDevEndpointStatusClear When incoming data is indicated by the flag USB_DEV_RX_PKT_RDy being set in the endpoint status data can be received using a call to USBEndpointDataGet followed by a call to USBDe vEndpointDataAck to acknowledge the reception to the host When an event relating to an IN endpoint data transmitted from the device to the host is received the status read from USBEndpointStatus indicates any errors in transmission If the value read is 0 this implies that the data was successfully transmitted and acknowledged by the host Any device whose configuration descriptor indicates that it uses any endpoint endpoint zero use is assumed must populate the p nEndpointHandler member of tCustomHandlers 3 21 2 12 pfnDeviceHandler Unlike the other calling functions pfnDeviceHandler specifies a generic input handler to the device class Callers of this function should check to insure that the class supports this entry by seeing if the pfnDeviceHandler is non zero This call is provided to allow requests based on a given instance to be passed into a device This is commonly used by a top level composite device that is using multiple instances of the same class USB device classes that need to support being part of a composite device must imple ment this function as the composite device class will need to call this function to in Se
98. BLE USB HID INPUT RELATIVE EndCollection EndCollection he J f kk ke kk ke kk oko ORR IRR RRR RRR IR RR IR IR IR A I I oe The HID class descriptor table For the mouse class we have only a single report descriptor bd J kk ke koe kk ko ke kk ke ke kk kk kk kk kk kk kk ko ke ke kk ke kk kk kk kk kk kk IRR IR I OR ke kk ko A kk A I kk A ke e ke Ke oe static const unsigned char const g pMouseClassDescriptors g_pucMouseReportDescriptor J kk ke ek koh ek koe ek khe ek kc kk ck ck kk ee eee kk ck kc kck ck ck ck ck ck ee skckckckckck ck ckck ck ckckckck ck ck ck ck ck ckck ck ckckck ck ck oko The HID descriptor for the mouse device kkkkkkkkkkkkkkkkkkkkkkkkk xkkkkkkkkkkkkkkk kkkkkkkkkkkkkkkkkxkkkkkkkkkk kkkkkkkkkkx static const tHIDDescriptor g_sMouseHIDDescriptor 9 bLength USB HID DTYPE HID bDescriptorType 0x111 bcdHID version 1 11 compliant 0 bCountryCode not localized um bNumDescriptors USB HID DTYPE REPORT Report descriptor sizeof g pucMouseReportDescriptor Size of report descriptor un m Define an array of cHIDReport Idle structures in RAM with one entry for each input report your device supports Initialize the ucDuration4mS and ucReportID fields in each of the entries to set the default idle report time for each input report Note that ucburation4mS defines the idle time in 4mS increments as used in the USB HID Set Idle and Get
99. Buffer and ulParam values are not used in this event USBH EVENT HID KB MOD Definition define USBH EVENT HID KB MOD Description The HID keyboard detected one of the keyboard modifiers being pressed USBH EVENT HID KB PRESS Definition define USBH EVENT HID KB PRESS September 05 2012 245 Host Functions 4 5 2 6 4 5 2 7 4 5 2 8 4 5 2 9 4 5 2 10 246 Description The HID keyboard detected a key being pressed USBH_EVENT_HID_KB_REL Definition define USBH EVENT HID KB REL Description The HID keyboard detected a key being released USBH EVENT HID MS PRESS Definition define USBH EVENT HID MS PRESS Description A button was pressed on a HID mouse USBH EVENT HID MS REL Definition define USBH EVENT HID MS REL Description A button was released on a HID mouse USBH EVENT HID MS X Definition define USBH EVENT HID MS X Description The HID mouse detected movement in the X direction USBH EVENT HID MS Y Definition define USBH EVENT HID MS Y Description The HID mouse detected movement in the Y direction September 05 2012 4 5 3 4 5 3 1 4 5 4 4 5 4 1 4 5 4 2 Host Functions Enumeration Documentation tHIDSubClassProtocol Description The following values are used to register callbacks to the USB HOST HID device class layer
100. CDCSetRxCBData void pvlnstance void pvCBData void x USBDCDCSetTxCBData void pvlInstance void pvCBData void USBDCDCTerm void pvinstance unsigned long USBDCDCTxPacketAvailable void pvlInstance Detailed Description The macros and functions defined in this section can be found in header file device usbdcdc h Users of the CDC device class driver will also need to include usbcdc h which contains general CDC definitions required by both host and device implementations September 05 2012 95 Device Functions 3 8 2 Data Structure Documentation 3 8 2 1 tLineCoding Definition typedef struct unsigned long ulRate unsigned char ucStop unsigned char ucParity unsigned char ucDatabits tLineCoding Members ulRate The data terminal rate in bits per second ucStop The number of stop bits Valid values are USB CDC STOP BITS 1 USB CDC STOP BITS 1 5or USB CDC STOP BITS 2 ucParity The parity setting Valid values are USB CDC PARITY NONE USB CDC PARITY ODD USB CDC PARITY EVEN USB CDC PARITY MARK and USB CDC PARITY SPACE ucDatabits The number of data bits per character Valid values are 5 6 7 and 8 in this implementation Description USB CDC GET SET LINE CODING request specific data 3 8 2 2 tUSBDCDOC Device Definition typedef struct nsigned short usVID nsigned short usPID nsigned short usMaxPowermA nsigned char ucPwrAttributes USBCallback pfnControlCallback oid x
101. Class To add USB bulk data transmit and receive capability to your application via the Generic Bulk Device Class Driver take the following steps m Add the following header files to the source file s which are to support USB include src usb h include usblib usblib h include usblib device usbdevice h include usblib device usbdbulk h Define the 5 entry string table which is used to describe various features of your new device to the host system The following is the string table taken from the usb dev bulk example application Edit the actual strings to suit your application and take care to ensure that you also update the length field the first byte of each descriptor to correctly reflect the length of the string and descriptor header The number of strings you include must be 5 number of languages listed in string descriptor 0 g_pLangDescriptor and the strings for each language must be grouped together with all the language 1 strings before all the language 2 strings and so on J kk ke kk kk ko ke kk ke kk kk kk kk kk kk kk kk kk kk kk kk kk kk kk kk ok kk Kk Sk kk ko kk kk kc kk kk ko ke kk ko ke e ke e ee The languages supported by this device J kk ke kk ke kk ke kk ke kk kk kk kk kk kk kk kk kk kk kk kk kk kk IR ok Sk ko kk kk koc I IR ke kk ko ke kk ko ke kk ko ke e ke Ke ke const unsigned char g pLangDescriptor 4 USB_DTYPE_STRING USBShort USB_LANG_EN_US J kk kk kk kk
102. ControlHandler void amp g sCDCDeviceA USBBufferEventCallback void amp g sRxBufferA USBBufferEventCallback void amp g sTxBufferA 0 0 amp g sCDCInstanceA Device description for Serial Device B eh const tUSBDCDCDevice g_sCDCDeviceB USB_VID_LUMINARY USB_PID_SERIAL 0 USB CONF ATTR SELF PWR ControlHandler void amp g sCDCDeviceB USBBufferEventCallback void amp g sRxBufferB USBBufferEventCallback void amp g sTxBufferB 0 0 amp g sCDCInstanceB Now the application must allocate the device array so that it can be provided to the USB composite device class The following code shows the two serial devices included above into the array of tCompositeEntry values tCompositeEntry g_psDevices 2 amp g sCDCSerDeviceInfo void x amp g sCDCDeviceA Fy amp g sCDCSerDeviceInfo void amp g_sCDCDeviceB September 05 2012 109 Device Functions 110 Once the array of devices has been allocated this array is included in the USB composite de vice structure when the device structure is allocated and initialized The code below shows this allocation Allocate the composite instance data and workspace storage tCompositeInstance g CompInstance unsigned long g pulCompWorkspace NUM DEVICES Initialize the USB composite device structure tUSBDCompositeDevice g_sCompDevice TI Stellar
103. D MEMORY SIZE while 1 HCDMain HID Class Driver The HID class driver provides access to any type of HID class by leaving the details of the HID device to the layer above the HID class driver The top layer of the HID class driver provides common functions to open or close an instance of a HID device read a device s report descrip tor so that it can be parsed by the HID device code and get and set reports on a HID de vice The lower level interface that is connected to the host controller driver is specified in the g_ USBHIDClassDriver structure This structure is used to register the HID class driver with the host class driver so that it is called when a HID device is connected and enumerated The functions in the g USBHIDClassDriver structure should never be called directly by and application or a host class driver as they are reserved for access by the host controller driver In the following example the generic HID class driver is registered with the USB host controller driver and then a call is made to open an instance of a mouse class device Typically the call to USBHHIDOpen is made from within a device class interface while the USBHCDRegisterDrivers call is made from the main application For instance the USBHHIDOpen for the mouse device provided with the USB library is made in the USBHMouseOpen function which is part of the USB mouse interface Device Interface At the top layer of the HID class driver the d
104. D MEMORY SIZE MAX USB DEVICES J f kk kk k k kk k H kk oko ke kk Kok kk Kk kk kk kk Kok kk kk kk ko ko kk ko koc kk K kk k Kk kk ko ko kk k k k ko Kok kk k K kk Kok kk Ke ke ke e 7 4 The memory pool to provide to the hub driver This pool is used to hold the configuration descriptors of the devices attached to the hub It must be sized to be at least MAX USB DEVICES largest expected configuration descriptor bytes d J f kk kk k k kk oko kk kk kk Kok kk Kok kk kk kk Kok kk kk kk kk kk ko koc kk kk kk k k E kk kk kk ok k kk Kok kk kk ke kk ke kk Ke ke ke e unsigned char g pucHubPool HUB POOL SIZE J f Kk kk ck ke kk ck ke ke kk ke kk kk kk ck ck kc kk ck ke kk ck kc kk ck kc kck ck ck ck ckckckckckckckckckckckckckckckckckckckckckckckckckckckck ck ck kck ck ckckckck Hf The instance data for the hub which is internal data and should not be accessed by the application TKK ROKR KR kk Kk kk Kok kk ok ke RR KR IR kk ko ko KR KR IR IR IR IR IRR k k k k k k tHubInstance g HubInstance J f kk kk k k kk oko ke OR kk Kk kk Kk kk ko ke kk Kok ko kk ok kk ko ko kk ko ke kk ko kk KK kk kk ko kk K k kk Kok kk ko ke kk ko ke kk Ke ke ke e The global that holds all of the host drivers in use in the application In this case the Mass Storage HID and Hub class drivers are present fa TKK k k k k k ORR RRO RRR RRR kk ko ko IR KR IR IR k k RI IR I k k oe static tUSBHostClassDriver const const g
105. D EVENT GET PROTOCOL E USBD HID EVEN SET REPORT E USBD HID EVENT REPORT SENT September 05 2012 123 Device Functions Note The USB_EVENT_DISCONNECTED event will not be reported to the application if the MCU s PB1 USBOVBUS pin is connected to a fixed 5 Volts rather than directly to the VBUS pin on the USB connector 3 13 1 2 Transmit Channel Events W USB EVENT TX COMPLETE 3 13 2 Using the HID Device Class Driver To add a USB HID interface to your application using the HID Device Class Driver take the following steps m Add the following header files to the source file s which are to support USB include src usb h include usblib usblib h include usblib usbhid h include usblib device usbdevice h include usblib device usbdhid h Define the string table which is used to describe various features of your new device to the host system The following is the string table taken from the usb dev mouse example application Edit the actual strings to suit your application and take care to ensure that you also update the length field the first byte of each descriptor to correctly reflect the length of the string and descriptor header The number of strings included will vary depending upon the device but must be at least 5 HID report descriptors may refer to string IDs and if the descriptor for your device includes these additional strings will be required Also if multiple languages are
106. Data void USBDHIDKeyboardTerm void pvlInstance 3 18 1 Detailed Description The macros and functions defined in this section can be found in header file device usbdhidkeyb h 168 September 05 2012 Device Functions 3 18 2 Data Structure Documentation 3 18 2 1 tUSBDHIDKeyboaraDevice Definition typedef struct nsigned short usVID nsigned short usPID nsigned short usMaxPowermA nsigned char ucPwrAttributes USBCallback pfnCallback oid pvCBData onst unsigned char xconst ppStringDescriptors nsigned long ulNumStringDescriptors HIDKeyboardInstance xpsPrivateHIDKbdData c codvndtozdgciBcocc tUSBDHIDKeyboardDevice Members usVID The vendor ID that this device is to present in the device descriptor usPID The product ID that this device is to present in the device descriptor usMaxPowermA The maximum power consumption of the device expressed in milliamps ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wakeup Valid values are USB CONF ATTR SELF PWR or USB CONF ATTR BUS PWhR optionally ORed with USB CONF ATTR RWAKE pfnCallback A pointer to the callback function which will be called to notify the application of general events and those related to reception of Output and Feature reports via the optional interrupt OUT endpoint pvCBData A client supplied pointer which will be sent as the first parameter in all calls made to the keyboard callba
107. E g pucDescriptorData All other API calls to the USB audio device class should use the value returned by USBDAudio Compositelnit when the API calls for a pvinstance pointer Also when using the audio device in a composite device the COMPOSITE DAUDIO SIZE value should be added to the size of the g pucDescriptorData array as shown in the example above 3 3 5 Generic Audio Device Class Events The generic audio device class driver sends the following events to the application callback func tions m USBD AUDIO EVENT IDLE Audio interface is idle m USBD AUDIO EVENT ACTIVE Audio interface is active m USBD AUDIO EVENT DATAOUT Audio playback buffer released m USBD AUDIO EVENT VOLUME Audio playback volume change m USBD AUDIO EVENT MUTE Audio mute change 3 4 Audio Device Class Driver Definitions Data Structures m tUSBDAudioDevice Defines m COMPOSITE DAUDIO SIZE m USB AUDIO INSTANCE SIZE m USBD AUDIO EVENT ACTIVE m USBD AUDIO EVENT DATAOUT m USBD AUDIO EVENT IDLE m USBD AUDIO EVENT MUTE m USBD AUDIO EVENT VOLUME Functions um long USBAudioBufferOut void pvinstance void pvBuffer unsigned long ulSize tUSBAu dioBufferCallback pfnCallback m void x USBDAudioCompositelnit unsigned long ullndex const tUSBDAudioDevice psDevice m void x USBDAudiolnit unsigned long ullndex const tUSBDAudioDevice psDevice m void USBDAudioTerm void pvlInstance September 05 2012
108. ERE Reid 105 Composite Device Class Driver Definitions 0 0 c cece cece I 111 Device Firmware Upgrade Device Class Driver cece cece een eee e eee e ete een een iiutitis 114 Device Firmware Upgrade Device Class Driver Definitions cc cece eee ee eee eee nee eee 119 HID Devre Class DINIBI ccccnncieneeaeaeaoawesamapeaetaeatagt M PM CREME PAM PePCHPSRODMpEERPS 122 AID Device Class Driver Definitions 125 Lp EPUPRPIDERRODRQE I i ohne iaid PP IQPNA rre iS e ii 132 FID Mouse Device Cus API ui uetosaida DE RO RuPHN PRIME REED MisrE pr Spe ORE D Na Era 156 HID Mouse Device Class API Definitions 2 osuere RES E EI OF Dre IPERRERRR ENTERS A EEEo 158 HID Keyboard Device Class AP Liuiiciesstestre Ebr ePRERP PU RR pP RI AY XE REPREEI EPA A ur TEPR 165 HID Keyboard Device Class API Definitions 2csce caesis ehem dem kkh rng rem bmx dee eee 168 Mase Slorade Devices CIS ARI Luuostricas daa axe qd dd dc ph bland dd dpa Fa dd Ed bd Ed Dd IR 175 Mass Storage Device Class API DefinlitioHis uunsice ee nae erbce b dberbtrR Pa key REX Rd tnb u ceeneres 181 singe USB Deleg INI eserinin add du cake E RE A Ede didt Rane d uo 186 Device Function Defihltiphig uxxiceesexsaccsctentxcete ba daa E bU ESO PES EN Sa d dd RARI CIN d pas 197 3 1 Introduction This chapter describes the various API layers within the USB library that offer support for applica tions wishing to present themselves as USB devices Several programming in
109. EVENT SET REPORT Functions void x USBDHIDCompositelnit unsigned long ullndex const tUSBDHIDDevice psDevice void x USBDHIDInit unsigned long ullndex const tUSBDHIDDevice psDevice unsigned long USBDHIDPacketRead void xpvinstance unsigned char pcData unsigned long ulLength tBoolean bLast void USBDHIDPowerStatusSet void pvlInstance unsigned char ucPower m tBoolean USBDHIDRemoteWakeupRequest void pvinstance unsigned long USBDHIDReportWrite void pvlnstance unsigned char pcData unsigned long ulLength tBoolean bLast unsigned long USBDHIDRxPacketAvailable void pvInstance void x USBDHIDSetRxCBData void xpvinstance void pvCBData void x USBDHIDSetTxCBData void pvinstance void pvCBData void USBDHIDTerm void pvInstance unsigned long USBDHIDTxPacketAvailable void pvinstance September 05 2012 133 Device Functions 3 14 1 3 14 2 3 14 2 1 3 14 2 2 134 Detailed Description The macros and functions defined in this section can be found in header file device usbdhid h Users of the HID device class driver will also need to include usbhid h which includes HID related definitions required by both host and device implementations Data Structure Documentation tHIDClassDescriptorlnfo Definition typedef struct unsigned char bDescriptorType unsigned short wDescriptorLength tHIDClassDescriptorInfo Members bDescriptorType The type of HID class descri
110. FOUND Definition define KEYB_ERR_NOT_FOUND Description USBDHIDKeyboardKeyStateChange returns this value if it is called with the bPress parameter set to false but with a ucUsageCode parameter which does does not indicate a key that is currently recorded as being pressed This may occur if an attempt was previously made to report more than 6 pressed keys and the earlier pressed keys are released before the later ones This condition is benign and should not be used to indicate a host disconnection or serious error 3 18 3 KEYB ERR TOO MANY KEYS Definition define KEYB ERR TOO MANY KEYS Description This return code from USBDHIDKeyboardKeyStateChange indicates that an attempt has been made to record more than 6 simultaneously pressed non modifier keys The USB HID BIOS keyboard protocol allows no more than 6 pressed keys to be reported at one time Until at least one key is released the device will report a roll over error to the host each time it is asked for the keyboard input report 3 18 3 4 KEYB ERR TX ERROR Definition define KEYB ERR TX ERROR Description This return code from USBDHIDKeyboardKeyStateChange indicates that an error was reported while attempting to send a report to the host A client should assume that the host has discon nected if this return code is seen 170 September 05 2012 3 18 3 5 3 18 3 6 3 18 3 7 3 18 4 3 18 4 1 Device Functions
111. Flags parameter is a combination of the following three sets of definitions One of the following values must be specified m SCSI MS PC CURRENT request for current settings m SCSI MS PC CHANGEABLE request for changeable settings m SCSI MS PC DEFAULT request for default settings m SCSI MS PC SAVED request for the saved values One of these following values must also be specified to determine the page code for the re quest m SCSI MS PC VENDOR is the vendor specific page code m SCSI MS PC DISCO is the disconnect reconnect page code m SCSI MS PC CONTROL is the control page code m SCSI MS PC LUN is the protocol specific LUN page code m SCSI MS PC PORT is the protocol specific port page code m SCSI MS PC POWER is the power condition page code m SCSI MS PC INFORM is the informational exceptions page code m SCSI MS PC ALL will request all pages codes supported by the device The last value is optional and supports the following global flag m SCSI MS DBD disables returning block descriptors Example Request for all current settings SCSIModeSense6 ulInPipe ulOutPipe SCSI MS PC CURRENT SCSI MS PC ALL pucData pulSize Returns This function returns the SCSI status from the command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL 4 5 4 30 USBHSCSIRead10 This function issues a SCSI Read 10 command to a device Prototype unsigned long USBHSCSIReadl10 unsigned long ulInPipe 262
112. HC DRegisterDrivers function Returns This function returns a non zero number if the event was successfully disabled and returns zero if the event cannot be disabled September 05 2012 219 Host Functions 4 3 4 9 USBHCDEventEnable Definition long USBHCDEventEnable unsigned long ulIndex void pvEventDriver unsigned long ulEvent Description This function is called to enable a specific USB HCD event notification Parameters ullndex specifies which USB controller to use pvEventDriver is the event driver structure that was passed into the USBHCDRegister Drivers function as part of the array of tUSBHostClassDriver structures ulEvent is the event to enable This function is called to enable event callbacks for a specific USB HCD event The requested event is passed in the u Event parameter Not all events can be enables so the function will return zero if the event provided cannot be enabled The pvEventDriver is a pointer to the event driver structure that the caller passed into the USBHCDhRegisterDrivers function This structure is typically declared with the DECLARE EVENT DRIVER macro and included as part of the array of pointers to tUSBHostClassDriver structures that is passed to the USBHC DRegisterDrivers function Returns This function returns a non zero number if the event was successfully enabled and returns zero if the event cannot be enabled 4 3 4 10 USBHCDInit Definition
113. HHubEnumerationComplete unsigned char ucHub unsigned char ucPort void USBHHubEnumerationError unsigned char ucHub unsigned char ucPort unsigned long USBHHubOpen tUSBCallback pfnCallback unsigned char pucHubPool un signed long ulPoolSize tHublnstance psHublnstance unsigned long ulNumHubs long USBHMSCBlockRead unsigned long ullnstance unsigned long ulLBA unsigned char xpucData unsigned long ulNumBlocks long USBHMSCBlockWrite unsigned long ullnstance unsigned long ulLBA unsigned char xpucData unsigned long ulNumBlocks void USBHMSCDriveClose unsigned long ullnstance unsigned long USBHMSCDriveOpen unsigned long ulDrive tUSBHMSCCallback pfnCall back September 05 2012 243 Host Functions long USBHMSCDriveReady unsigned long ullnstance void USBHostAudioClose unsigned long ullnstance unsigned long USBHostAudioFormatGet unsigned long ullnstance unsigned long ulSam pleRate unsigned long ulBits unsigned long ulChannels unsigned long ulFlags unsigned long USBHostAudioFormatSet unsigned long ullnstance unsigned long ulSam pleRate unsigned long ulBits unsigned long ulChannels unsigned long ulFlags unsigned long USBHostAudioOpen unsigned long ullndex tUSBHostAudioCallback pfnCall back long USBHostAudioPlay unsigned long ullnstance void pvBuffer unsigned long ulSize tUS BHostAudioCallback pfnCallback long USBHostAudioRecord unsigned long ullnstance void pvBuffer unsigned long ulSize
114. ICE The application is forcing device mode so that the VBUS and ID pins are not used or seen by the USB controller September 05 2012 2 2 6 2 2 6 1 2 2 6 2 General Purpose Functions Function Documentation USBODualModelntHandler Steers USB interrupts from controller to the correct handler in the USB stack Prototype void USBODualModeIntHandler void Description This interrupt handler is used in applications which require to operate in both host and device mode It steers the USB hardware interrupt to the correct handler in the USB stack depending upon the current operating mode of the application USB device or host For successful dual mode operation an application must register USBODualModelntHandler in the CPU vector table as the interrupt handler for the USBO interrupt This handler is respon sible for steering interrupts to the device or host stack depending upon the chosen mode Note Devices which do not require dual mode capability should register ei ther USBODevicelntHandler or USBOHostIntHandler instead Registering USBODualModelntHandler for a single mode application will result in an application bi nary larger than required since library functions for both USB operating modes will be included even though only one mode is actually required Returns None USBOOTGModelntHandler Handles OTG mode changes and also steers other USB interrupts from the controller to the correct handler in
115. ID in addition to your composite device s standard PID Programming DFU Devices The firmware on a DFU capable USB device may be updated using either the LM Flash Program mer application or the command line dfuprog tool Source code for dfuprog is included in the StellarisWare releases for all USB enabled kits and can be found in C StellarisWare tools dfuprog assuming you installed StellarisWare in the default location The executable for the application is in stalled as part of the Windows side examples for USB kits package SW USB win xxxx which can be downloaded via a link on http www ti com stellarisware By default dfuprog exe can be found in C Program Files Texas Instruments VStellarisvusb examples LM Flash Programmer will only list connected DFU devices which are in DFU mode but the dfuprog tool also allows runtime DFU devices to be enumerated and switched into DFU mode September 05 2012 3 12 3 12 1 Device Functions ready for programming using either LM Flash Programmer or another call to dfuprog The com mand dfuprog e will enumerate all DFU capable devices attached to the host system and provide information on each To switch a device from runtime mode to DFU mode issue the command dfuprog i index m where index is the index of the device as displayed during dfuprog e whose mode is to be switched When a device is switched from runtime mode to DFU mode you will hear Windows usual indi c
116. Idle re quests The times defined in these structures are used to determine how often a given input report is resent to the host in the absence of any device state change For example a device supporting two input reports with IDs 1 and 2 may initialize the array as follows tHIDReportIdle g psReportIdle 2 125 1 0 0 Report 1 polled every 500m5 4 125 Oy 25 0 04 Report 2 is not polled 0mS timeout m Define a tUSBDHIDDevice structure and initialize all fields as required for your application The following example shows a structure suitable for a BIOS compatible mouse device which publishes a single input report September 05 2012 127 Device Functions const tUSBDHIDDevice g_sHIDMouseDevice The Vendor ID you have been assigned by USB IF USB_VID_YOUR_VENDOR_ID The product ID you have assigned for this device USB_PID_YOUR_PRODUCT_ID The power consumption of your device in milliamps POWER_CONSUMPTION_mA The value to be passed to the host in the USB configuration descriptor s bmAttributes field USB CONF ATTR BUS PWR This mouse supports the boot subclass USB HID SCLASS BOOT This device supports the BIOS mouse report protocol USB HID PROTOCOL MOUSE The device has a single input report 1 A pointer to our array of tHIDReportIdle structures For this devi
117. It advances the write index by a given number of bytes Note It is considered an error if the ulNumBytes parameter is larger than the amount of free space in the buffer and a debug build of this function will fail ASSERT if this condition is detected In a release build the buffer read pointer will be advanced if too much data is written but this will of course result in some of the oldest data in the buffer being discarded and also depending upon how data is being read from the buffer may result in a race condition which could corrupt the read pointer Returns None USBRingBufContigFree Returns number of contiguous free bytes available in a ring buffer September 05 2012 2 4 6 16 2 4 6 17 General Purpose Functions Prototype unsigned long USBRingBufContigFree tUSBRingBufObject x xptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to check Description This function returns the number of contiguous free bytes ahead of the current write pointer in the ring buffer Returns Returns the number of contiguous bytes available in the ring buffer USBRingBufContigUsed Returns number of contiguous bytes of data stored in ring buffer ahead of the current read pointer Prototype unsigned long USBRingBufContigUsed tUSBRingBufObject x xptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to check Description This function returns the number of contiguous bytes of data available in
118. K ROKR KKK OR kk kk RR KR OR kk ko ko KR KR IR IR k k RI kk ko ke I k k ke ke e fa This array lists all the sections that must be concatenated to make a single complete HID keyboard configuration descriptor J f kk k k k kk k H KR ROR kk ko ke kk Kok RRR OR OR OR IR IR IR IR IR I I oe const tConfigSection g_psKeyboardSections amp g_sKeyboardConfigSection amp g sHIDInterfaceSection amp g sHIDInEndpointSection E define NUM KEYBOARD SECTIONS sizeof g psKeyboardSections N sizeof tConfigSection x J f kk kk k k kk kk kk kk Kk kk Kok kk ko ke kk Kok kk kk kk ko ko kk ko ko ke kk K kk kk ko kk kk kk k kk ko Kok I kk kk kk ke ke ke e The header for the single configuration we support This is the root of the data structure that defines all the bits and pieces that are pulled together to generate the HID keyboard s config descriptor A pointer to this structure is used to initialize the ppConfigDescriptors field of the tDeviceInfo structure passed to USBDCDInit J Kk kk k k k ke k k k kk k k kk k k k k ck k k k ck k k kk k k k k k k k k k k k k k k k k k k k k k IR k k k k ck ck ck ckckck ck ckckck ck ck kck ck ck k k k const tConfigHeader g_sKeyboardConfigHeader NUM_KEYBOARD_SECTIONS g_psKeyboardSections tDevicelnfo ppStringDescriptors and tDevicelnfo ulNumStringDescriptors Descriptive strings referenced by device and configuration descriptors are provided to the USB Device
119. OT COMP Definition define USBERR HOST IN NOT COMP Description The host did not receive a response from a device September 05 2012 2 2 3 32 2 2 3 33 2 2 3 34 2 2 3 35 2 2 3 36 2 2 3 37 General Purpose Functions USBERR HOST IN PID ERROR Definition define USBERR HOST IN PID ERROR Description The host received an invalid PID in a transaction USBERR HOST IN STALL Definition define USBERR HOST IN STALL Description The host received a stall on an IN endpoint USBERR HOST OUT ERROR Definition define USBERR HOST OUT ERROR Description The host failed to communicate with a device via an OUT endpoint USBERR HOST OUT NAK TO Definition define USBERR HOST OUT NAK TO Description The host received NAK on an OUT endpoint for longer than the specified timeout period bulk interrupt and control modes USBEHR HOST OUT NOT COMP Definition define USBERR_HOST_OUT_NOT_COMP Description The host did not receive a response from a device isochronous mode USBERR_HOST_OUT_STALL Definition define USBERR_HOST_OUT_STALL Description The host received a stall on an OUT endpoint September 05 2012 17 General Purpose Functions 2 2 4 2 2 4 1 2 2 9 2 2 5 1 18 Typedef Documentation tUSBCallback Definition typedef unsigned long tUSBCallback void pvCBData unsigned long ulEvent unsigned long ulMsgParam void xp
120. PI an application can make itself visible to the USB host as a mouse using an extremely simple interface consisting of an initialization call and a call to inform the host of mouse movement or button presses Similarly using the keyboard device class API the application can use a single API to send key make and break information to the host without having to be aware of the underlying HID structures and USB protocols Example applications usb_dev_mouse and usb_dev_keyboard make use of the HID mouse and keyboard device class APIs respectively Audio Device Class Driver The USB audio device class provides a playback interface which allows an application to act as a generic USB audio device to any host operating systems that natively supports USB audio devices Most operating systems provide native support for generic audio class devices which means that no operating system specific drivers are required The USB audio device class provides a single 16 bit stereo playback interface at 48kHz sample rate and also provides volume and mute controls USB Audio Device Model Isochronous OUT Empty Buffer Free E c Filled Buffer Play h USB Host USB Driver USB Device API Audio Class Driver Application Code Audio Playback Audio Endpoint 0 Messages A September 05 2012 57 Device Functions 3 3 1 3 3 2 3 3 3 58 Handling Audio Playback
121. R IR kk ko koc IIR RR IR IR I I K k k I IK k k k k k ke ke const unsigned char g_pLangDescriptor 4 USB_DTYPE_STRING USBShort USB_LANG_EN_US Meet H k e H eee ee eee ee ee eee eee ee ee eee k A k k A k k k k k k k k k k ee k k k k k k k ckckckck ck ckck ck ck ckck ck ck k k k The manufacturer string J f kk k k k ke k e e RIOR ke Sk kk ke ke kk he ke Sk kk ke Sk kk kk kk kk ko ko ORR ok kk kk kk ko IR k k K I I k k k k k k k k k k const unsigned char g pManufacturerString 2 22 2 USB DTYPE STRING PEU 0 tet 0 E wu OF a st 0 Et 0 Bum 0 CU y 0 m 5 0 her 0 PT g 0 ES 0 Cat Qu duce 05 SEE y fa J kk k k k ke kk ke ke kk ke kk ko ke kk kk kk ke he ke Sk kk kk kk kk kk kk ko ko ke Sk kk ok kk kk kk ko ok kk k ok kc kk I ko kk ke kk ko ke kk ke ke ke e LE The product string TOR RRR kk kk ke kk kk Sk kk ke ke kk ke ke Sk kk ROR kk ko OR ok kk RIOR IR k k I I RI IIR kk a k k const unsigned char g pProductString 13 1 gt 2 USB DTYPE STRING A 0 P y 0 ud OF ae 0 rol 0 T y 0 E 0 x 0 al j 0 yt y 0 py 0 rly OF ely 0 TKK k k e k e ke kk ke kk kk Kk Kk kk kk RRR OR IR ko kk KR IR IR II I kk ko k k k k k ke e The serial number string fd Meet H eee eee eee ee ee ee Pee ee ee ee ee ee ee k k k k eee k k k k k k k k eee k k k k k k k k ck ck ckck ck ck ckck ck ck k k k const unsigned char g_pSerialNumberString 8 1 2 USB_DTYPE_
122. RVICE ServiceType 1 StartType 3 ErrorControl 1 ServiceBinary 12 usbser sys String Definitions change for your device Strings MF GNAME Texas Instruments Notice 94 September 05 2012 3 8 3 8 1 Device Functions DESCRIPTION 0 DESCRIPTION 1 SERVICE Stellaris USB Serial Port Stellaris USB Serial Command Port Stellaris USB CDC serial port uo dg og CDC Device Class Driver Definitions Data Structures m tLineCoding m tUSBDCDCDevice Defines m COMPOSITE DCDC SIZE m USBD CDC EVENT CLEAR BREAK m USBD CDC EVENT GET LINE CODING m USBD CDC EVENT SEND BREAK m USBD CDC EVENT SET CONTROL LINE STATE m USBD CDC EVENT SET LINE CODING Functions m void USBDCDCCompositelnit unsigned long ullndex const tUSBDCDCDevice psCDCDevice void x USBDCDClnit unsigned long ullndex const tUSBDCDCDevice psCDCDevice unsigned long USBDCDCPacketRead void pvlnstance unsigned char pcData unsigned long ulLength tBoolean bLast unsigned long USBDCDCPacketWrite void pvinstance unsigned char pcData unsigned long ulLength tBoolean bLast void USBDCDCPowerStatusSet void pvlnstance unsigned char ucPower tBoolean USBDCDCRemoteWakeupRequest void pvInstance unsigned long USBDCDCRxPacketAvailable void pvinstance void USBDCDCSerialStateChange void pvinstance unsigned short usState void x USBDCDCSetControlCBData void pvinstance void pvCBData void x USBD
123. Request Defines m NEXT USB DESCRIPTOR ptr m USB3Byte ulValue m USBLong ulValue m USBShort usValue Detailed Description This section describes the various data structures and labels relating to standard USB descriptors and requests as defined in chapter 9 of the USB 2 0 specification These definitions can be found in usblib h September 05 2012 2 3 2 2 3 2 1 General Purpose Functions For ease of use alongside the USB specification members of the structures defined here are named to according to the equivalent field in the USB documentation Note that this convention departs from the naming convention applied to all other Texas Instruments Stellaris data types It is important to be aware that all the structures described in this section are byte packed Appro priate typedef modifiers are included in usblib h to ensure the correct packing for all currently supported toolchains The USB 2 0 specification may be downloaded from the USB Implementers Forum USB IF web site at http www usb org developers docs Data Structure Documentation tConfigDescriptor Definition typedef struct unsigned char bLength unsigned char bDescriptorType unsigned short wTotalLength unsigned char bNumInterfaces unsigned char bConfigurationValue unsigned char iConfiguration unsigned char bmAttributes unsigned char bMaxPower tConfigDescriptor Members bLength The length of this descriptor in bytes
124. S MANUAL Power control is completely managed by the application the USB library will provide a power callback to request power state changes m USBHCD VBUS AUTO LOW USBEPEN is driven low by the USB controller automati cally if USBOTGSessionRequest has enabled a session m USBHCD VBUS AUTO HIGH USBEPEN is driven high by the USB controller automat ically if USBOTGSessionRequest has enabled a session If USBHCD VBUS MANUAL is used then the application must provide an event driver to re ceive the USB EVENT POWER ENABLE and USB EVENT POWER DISABLE events and enable and disable power to VBUS when requested by the USB library The application should respond to a power control callback by enabling or disabling VBUS as soon as possible and before returning from the callback function Note The following values should no longer be used with the USB li brary USB HOST PWRFLT LOW USB HOST PWRFLT HIGH USB HOST PWRFLT EP NONE USB HOST PWRFLT EP THI USB HOST PWRFLT EP LOW USB HOST PWRFLT EP HIGH USB HOST PWREN LOW USB HOST PWREN HIGH USB HOST PWREN VBLOW and USB HOST PWREN VBHIGH Returns None 4 3 4 5 USBHCDPowerConfigSet Definition unsigned long USBHCDPowerConfigSet unsigned long ullndex unsigned long ulConfig Description This function is used to set the power pin and power fault configuration September 05 2012 227 Host Functions Parameters ullndex specifies which USB controller to use ulConfig specifi
125. SB bus pfnEndpointHandler This callback is made to inform the device of activity on all endpoints other than endpoint zero pfnDeviceHandler This generic handler is provided to allow requests based on a given in stance to be passed into a device This is commonly used by a top level composite device that is using multiple instances of a class Description USB event handler functions used during enumeration and operation of the device stack 3 22 1 4 tFIFOConfig Definition typedef struct tFIFOEntry sIn USBLIB NUM EP 1 tFIFOEntry sOut USBLIB NUM EP 1 September 05 2012 199 Device Functions 3 22 1 5 3 22 2 3 22 2 1 200 tFIFOConfig Members sin An array containing one FIFO entry for each of the IN endpoints Note that endpoint 0 is configured and managed by the USB device stack so is excluded from this array The index 0 entry of the array corresponds to endpoint 1 index 1 to endpoint 2 etc sOut An array containing one FIFO entry for each of the OUT endpoints Note that endpoint 0 is configured and managed by the USB device stack so is excluded from this array The index 0 entry of the array corresponds to endpoint 1 index 1 to endpoint 2 etc Description This structure defines endpoint and FIFO configuration information for all endpoints that the device wishes to use This information cannot be determined by examining the USB configura tion descriptor and is provided to USBDCDConfig by the app
126. SB device The ulDevice specifies the device instance that was returned when the device was connected This call will set the USB device s interface based on the ullnterface and ulAltSet ting Example Set the USB device interface 2 to alternate setting 1 USBHCDSetInterface 0 ulDevice 2 1 Returns None 4 3 4 32 USBHCDSuspend Definition void USBHCDSuspend unsigned long ulIndex Description 230 This function will generate suspend signaling on the USB bus Parameters ullndex specifies which USB controller to use This function is used to generate suspend signaling on the USB bus In order to leave the suspended state the application should call USBHCDResume Returns None September 05 2012 Host Functions 4 3 4 33 USBHCDTerm 4 4 4 4 1 Definition void USBHCDTerm unsigned long ulIndex Description This function is used to terminate the HCD code Parameters ullndex specifies which USB controller to release This function will clean up the USB host controller and disable it in preparation for shutdown or a switch to USB device mode Once this call is made USBHCDInit may be called to reinitialize the controller and prepare for host mode operation Returns None Host Class Driver The host class drivers provide access to devices that use a common USB class interface The USB library currently supports the following two USB class drivers Mass Storage Class MSC and Hum
127. SB controller and place the device on the bus September 05 2012 pDevice USBDHIDMouseInit 0 amp g sHIDMouseDevice 129 Device Functions m Assuming pDevice returned is not NULL your device is now ready to communicate with a USB host Once the host connects your control event handler will be sent USB_EVENT_CONNECTED and the first input report may be sent to the host using USBDHIDReportWrite with following packets transmitted as soon as USB EVENT TX COMPLETE is received via the transmit event handler 3 13 3 Using the Composite HID Mouse Device Class When using the HID mouse device class in a composite device the configuration of the device is very similar to how it is configured as a non composite device Follow all of the configuration steps in the previous section with the exception of calling USBDHIDMouseCompositelnit instead of US BDHIDMouselnit This will prepare an instance of the HID mouse device class to be enumerated as part of a composite device The return value from the USBDHIDMouseCompositelnit function should be placed in the pvinstance member of the tCompositeEntry structure for the HID mouse device The code example below provides an example of how to initialize the tCompositeEntry structure These should be initialized with valid values for each class extern tUSBDCompositeDevice g_sCompDevice extern tUSBDHIDMouseDevice g_sHIDMouseDevice
128. SB device It frees the controller for use by another client It is the caller s responsibility to remove its device from the USB bus prior to calling this function Returns None 3 22 3 10 USBDeviceConfig Configure the USB controller appropriately for the device whose config descriptor is passed Prototype tBoolean USBDeviceConfig tDeviceInstance xpsDevInst const tConfigHeader xpsConfig Parameters psDevinst is a pointer to the device instance being configured psConfig is a pointer to the configuration descriptor that the USB controller is to be set up to support Description This function may be used to initialize a USB controller to operate as the device whose con figuration descriptor is passed The function enables the USB controller partitions the FIFO September 05 2012 205 Device Functions appropriately and configures each endpoint required by the configuration If the supplied con figuration supports multiple alternate settings for any interface the USB FIFO is set up as suming the worst case use largest packet size for a given endpoint in any alternate setting using that endpoint to allow for on the fly alternate setting changes later On return from this function the USB controller is configured for correct operation of the default configuration of the device described by the descriptor passed USBDCDOonfig is an optional call and applications may chose to make direct calls to SysCtlPeripheralEnab
129. SBERR_DEV_RX_FIFO_FULL Definition define USBERR DEV RX FIFO FULL Description The device receive FIFO is full USBERR DEV RX OVERRUN Definition define USBERR DEV RX OVERRUN Description The device was unable to receive a packet from the host since the receive FIFO is full USBERR HOST EPO ERROR Definition define USBERR_HOST_EPO_ERROR Description The host failed to communicate with a device via an endpoint zero September 05 2012 15 General Purpose Functions 2 2 3 26 2 2 3 27 2 2 3 28 2 2 3 29 2 2 3 30 2 2 3 31 16 USBERR HOST EPO NAK TO Definition define USBERR HOST EPO NAK TO Description The host received NAK on endpoint 0 for longer than the configured timeout USBERR HOST IN DATA ERROR Definition define USBERR HOST IN DATA ERROR Description The host detected a CRC or bit stuffing error isochronous mode USBERR HOST IN ERROR Definition define USBERR HOST IN ERROR Description The host failed to communicate with a device via an IN endpoint USBEHRR HOST IN FIFO FULL Definition define USBERR HOST IN FIFO FULL Description The host receive FIFO is full USBERR HOST IN NAK TO Definition define USBERR HOST IN NAK TO Description The host received NAK on an IN endpoint for longer than the specified timeout period interrupt bulk and control modes USBERR HOST IN N
130. SBHMSCDriveReady and waiting for the value returned to go to 0 before attempting to read or write the device Typically the reading and writing of the device is left to a file system layer as is the case in the example application however the calls to directly read or write a block are shown in the example below Example Mass Storage Coding Example 280 Open an instance of the mass storage class driver g ulMSCInstance USBHMSCDriveOpen 0 MSCCallback September 05 2012 Host Functions Wait for the drive to become ready while USBHMSCDriveReady g ulMSCInstance System level delay call should be here to give the device time to become ready SysCtlDelay SysCtlClockGet 100 Block Read example USBHMSCBlockRead g ulMSCInstance ulLBA pucData 1 Block Write example USBHMSCBlockWrite g ulMSCInstance ulLBA pucData 1 September 05 2012 281 IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries Tl reserve the right to make corrections modifications enhancements improvements and other changes to its products and services at any time and to discontinue any product or service without notice Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete All products are sold subject to Tl s terms and conditions of sale supplied at the time of order ack
131. SCDriveClose to disable callbacks This does not actually power down the mass storage device but it stops the driver from calling the application Once the USBHMSCDriveReady call indicates that the flash drive is ready the application can use the USBHMSCBlockRead and USBHMSCBlockWrite functions to access the device These are block based functions that use the logical block address to indicate which block to access It is important to note that the size passed in to these functions is in blocks and not bytes and that the most common block size is 512 bytes These calls always read or write a full block so space must be allocated appropriately The following example shows calls for both reading and writing blocks from the mass storage class device Example Block Read Write Calls 4 Read 1 block starting at logical block O0 ff USBHMSCBlockRead ulMSCDevice 0 pucBuffer 1 Write 2 blocks starting at logical block 500 USBHMSCBlockWrite ulMSCDevice 500 pucBuffer 2 SCSI Functions Since most mass storage class device adhere to the SCSI protocol for block based calls the USB library provides SCSI functions for the mass storage class driver to communicate with flash drives The commands and data pass over the USB pipes provided by the host controller driver The only types of mass storage class devices that are supported are devices that use the SCSI pro tocol Since flash drives only support a limited subset of
132. STRING PIU De CAU D Fale Up 74 gt Oy MO Oe 6 By 3 Op TS Q J f kk ke kk ke kk ke ke kk ke kk Kok kk Kok kk ke ke kk kk kk kk kk kk kk ko ke ok Sk kk KR kk kk kk ok kc kc kk I kk kk kk ko ke ke kk ke ke ke September 05 2012 59 Device Functions The interface description string TORK k k k k e OR OR OR ke kk ke kk Kok RR IR IR IRR IR IR IR III K k k IIR k k k k k ke e const unsigned char g_pHIDInterfaceString 15 ly 2 USB_DTYPE_STRING AtZGQy uly 0y d txt OF Cot Op c6 TO Oy Cnt 0 Et Q4 tet OF rt 0 fft 0 tat 0 6 0 el 0 un J kk ke kk ke kk kk kk ke Sk kk ke Sk kk ke kk kk kk kk kk kk kk ko kk ko kk Kk kk IR kk kk kk ko ke kk ko ke ko kk ke ke ke ke ee ff The configuration description string J kk kk ke khe ke kk ke ke ke khe kk kk kk kk kk kk ee eee ee ee ee ee eee ee ee ee eee eee eee const unsigned char g pConfigString 20 1 2 USB_DTYPE_STRING FAP Oe ut Sale 0 a Pe 0 Eur 0 ET y 0 PT 0 g 0 rufy 0 gt 0 rar 0 CE QUE Oy Ol tn J K k k ke k k k k k k k kk khe ke k k k k k k kk kk ke k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k kkk k k k kk k kkk k k k k ee The descriptor string table Mette eee eee eee ee ee ke kk kk kk kk eee eee ee ee ee ee eee ee ee eee eee eee const unsigned char const g_pStringDescriptors g_pLangDescriptor g_pManufacturerString g_pProductS
133. September 05 2012 Device Functions The value to be passed to the host in the USB configuration descriptor s bmAttributes field USB_CONF_ATTR_SELF_PWR A pointer to your control callback event handler YourUSBControlEventCallback A value that you want passed to the control callback alongside every event void amp g_sYourInstanceData A pointer to your receive callback event handler HL YourUSBReceiveEventCallback A value that you want passed to the receive callback alongside every event void amp g sYourInstanceData A pointer to your transmit callback event handler YourUSBTransmitEventCallback A value that you want passed to the transmit callback alongside every event void amp g_sYourInstanceData A pointer to your string table g_pStringDescriptors The number of entries in your string table NUM_STRING_DESCRIPTORS A pointer to the private structure allocated for the class driver to use amp g sSeriallnstance i m Adda receive event handler function YourUSBReceiveEventCallback in the previous example to your application taking care to handle all messages which require a particular response For the CDC device class USB_EVENT_RX_AVAILABLE and USB_EVENT_DATA_REMAINING MUST be handled by the receive event handler In response to USB_EVENT_RX_AVAILABLE yo
134. Stellaris USB Library USER S GUIDE TEXAS INSTRUMENTS SW USBL UG 9453 Copyright 2008 2012 Texas Instruments Incorporated Copyright Copyright 2008 2012 Texas Instruments Incorporated All rights reserved Stellaris and StellarisWare are registered trademarks of Texas Instruments ARM and Thumb are registered trademarks and Cortex is a trademark of ARM Limited Other names and brands may be claimed as the property of others A Please be aware that an important notice concerning availability standard warranty and use in critical applications of Texas Instruments semicon ductor products and disclaimers thereto appears at the end of this document Texas Instruments 108 Wild Basin Suite 350 Austin TX 78746 IA TEXAS Et nod INSTRUMENTS http www ti com stellaris an m E m EN ortex Intelligent Processors by ARM a lu tc Llu o a Revision Information This is version 9453 of this document last updated on September 05 2012 2 September 05 2012 Table of Contents Table of Contents COMUNGNE a c c uu Gee mue m ee Pew ae ee ee BG eae NUS e Oh Gee eee 2 Revision Information ssec 556 4630 004 Bee dee eee eee ee eee ee ee 2 1 Duiueeibei RU ET 5 2 General Purpose Functions clc 7 21 WPOOUEWBH i 6 2 gt arg e aera ah ee Sh ee oe OR a we A eA OAK bie we ae 7 s Function DENNHIONS iu sso ER be wee xoxo x 3k o9 GU 9 Y we we x amp 8 23 DUSBOhapisr 9
135. The audio playback path is handled by the application passing buffers to be filled to the USB audio class and receiving them back with audio data from the USB host controller The USB audio class only holds one buffer at a time and will return it to the application when it is full Because the USB audio class only holds one buffer it is important to pass in a new buffer to the USB audio class as soon as possible once a buffer is returned to the application to prevent underflow from the USB host controller Since most audio playback methods uses at least two buffers one that is playing and one that is being filled the single buffer in the USB audio class allows for minimal buffering and eliminates copying of data between buffers When the application has an audio buffer that needs to be filled it passes it to the USB audio class using the USBAudioBufferOut function The USB audio class returns the buffer to the application via the audio message handler that the applica tion provided in the pfnHandler member of the tUSBDAudioDevice structure As soon as the audio device is active the application can provide a buffer to the USB audio class with a call to USBAu dioBufferOut This call will only fail if the USB audio class already has a buffer at this point the application must wait for a previous buffer to be returned with a USBD AUDIO EVENT DATAOUT message Once the USBD AUDIO EVENT DATAOUT message is received the buffer has been filled and can be playe
136. USB audio device This function returns a void pointer that must be passed in to all other APIs used by the audio class See the documentation on the tUSBDAudioDevice structure for more information on how to properly fill the structure members Returns Returns 0 on failure or a non zero void pointer on success September 05 2012 67 Device Functions 3 4 4 3 3 4 4 4 68 USBDAudiolnit This function should be called once for the audio class device to initialized basic operation and prepare for enumeration Prototype void x USBDAudioInit unsigned long ulIndex const tUSBDAudioDevice psDevice Parameters ullndex is the index of the USB controller to initialize for audio class device operation psDevice points to a structure containing parameters customizing the operation of the audio device Description In order for an application to initialize the USB audio device class it must first call this function with the a valid audio device class structure in the psDevice parameter This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB audio device This function returns a void pointer that must be passed in to all other APIs used by the audio class See the documentation on the tUSBDAudioDevice structure for more information on how to properly fill the structure members Returns Returns 0 on failure or a non zero void pointer on success
137. USBD_MSC_EVENT_READING Handle read case break case USBD_MSC_EVENT_IDLE Handle idle case default break return 0 September 05 2012 179 Device Functions 3 19 4 Using the Composite Mass Storage Device Class When using the mass storage device class in a composite device the configuration of the device is very similar to how it is configured as a non composite device Follow all of the configuration steps in the previous section with the exception of calling USBDMSCCompositelnit instead of USBDMSClnit This will prepare an instance of the mass storage device class to be enumerated as part of a composite device The return value from the USBDMSCCompositelnit function should be placed in the pvInstance member of the tCompositeEntry structure for the mass storage device The code example below provides an example of how to initialize some of the structures necessary to use the USB mass storage device class in a composite device These should be initialized with valid values for each class Lif extern tUSBDCompositeDevice g_sCompDevice extern tUSBDMSCDevice g_sMSCDevice ii The OTHER_SIZES here are the sizes of the descriptor data for other classes that are part of the composite device define DESCRIPTOR DATA SIZE COMPOSITE DMSC SIZE OTHER SIZES unsigned char g pucDescriptorData DESCRIPTOR DATA SIZE tCompositeEntry psCompEntries 2 Set th
138. USBERR HOST IN ERROR USBERR HOST IN FIFO FULL USBERR HOST IN NAK TO USBERR HOST IN NOT COMP USBERR HOST IN PID ERROR USBERR HOST IN STALL USBERR HOST OUT ERROR USBERR HOST OUT NAK TO USBERR HOST OUT NOT COMP USBERR HOST OUT STALL Enumerations tUSBMode Functions void USBODualModelntHandler void void USBOOTGModelntHandler void tDescriptorHeader USBDescGet tDescriptorHeader psDesc unsigned long ulSize un signed long ulType unsigned long ullndex tInterfaceDescriptor USBDescGetlnterface tConfigDescriptor psConfig unsigned long ullndex unsigned long ulAIt tEndpointDescriptor x USBDescGetlnterfaceEndpoint tlnterfaceDescriptor psInterface un signed long ullndex unsigned long ulSize unsigned long USBDescGetNum tDescriptorHeader psDesc unsigned long ulSize un signed long ulType unsigned long USBDescGetNumAlternatelnterfaces tConfigDescriptor psConfig unsigned char uclnterfaceNumber void USBDualModelnit unsigned long ullndex void USBDualModeTerm unsigned long ullndex void USBOTGMain unsigned long ulMsTicks void USBOTGModelnit unsigned long ullndex unsigned long ulPollRate void pHostData unsigned long ulHostDataSize void USBOTGModeTerm unsigned long ullndex void USBOTGPollRate unsigned long ullndex unsigned long ulPollRate void USBStackModeSet unsigned long ullndex tUSBMode eUSBMode tUSBModeCallback pfnCallback Detailed Description This group
139. USBH_EVENT_HID_KB_PRESS or USBH_EVENT_HID_KB_REL events while hitting keys like the shift ctrl alt and gui keys generate USBH_EVENT_HID_KB_MOD events Example Keyboard Callback unsigned long KeyboardCallback void pvCBData unsigned long ulEvent unsigned long ulMsgParam void xpvMsgData unsigned char ucChar switch ulEvent New keyboard detected case USB_EVENT_CONNECTED September 05 2012 279 Host Functions eKeyboardState KEYBOARD_INIT break Keyboard has been unplugged case USB_EVENT_DISCONNECTED eKeyboardState KEYBOARD_NOT_CONNECTED break New Key press detected case USBH_EVENT_HID_KB_PRESS ulMsgParam holds the USB Usage ID f break case USBH_EVENT_HID_KB_MOD ulMsgParam holds the USB Modifier bit mask break case USBH_EVENT_HID_KB_REL ulMsgParam holds the USB Usage ID Ef break return 0 4 8 7 Host Mass Storage Programming Example The following programming example demonstrates some of the basic interfaces that are available from the USB mass storage class application interface See the Basic Configuration as Host example above for the initial configuration The application should call USBHMSCDriveOpen in order for the application to be ready for a new mass storage device The application should also wait for the mass storage device to be ready to receive commands by calling U
140. VENT SOF event is left disabled by default to avoid the excess overhead because this event occurs once per millisecond Because the USB events driver reuses the interrupt handler callback that is used for a normal host controller drivers the application is required to cast the void pointer that is passed in to the function to a pointer to a tEventInfo structure The following code example shows a basic implementation of a USB library event driver callback function Example A USB Event Driver Callback Function Declare the driver DECLARE EVENT DRIVER g_sEventDriver void USBHCDEvents void pvData tEventInfo pEventInfo 4 Cast this pointer to its actual type pEventInfo tEventInfo pvData switch pEventInfo ulEvent Unknown device connected case USB_EVENT_CONNECTED break Unknown device disconnected case USB_EVENT_DISCONNECTED break Power Fault detected 0 0 USBHCDEvents September 05 2012 4 4 2 Host Functions case USB_EVENT_POWER_FAULT break default break Hub Class Driver The USB Hub class driver provides support for a USB hub device that allows the USB con troller to communicate with multiple USB devices The maximum number of devices that are supported is controlled by the MAX_USB_DEVICES definition in usblib h The value defined by MAX_USB_DEVICES defaults to 5 m
141. XP Windows Vista and Windows7 systems Further information can be obtained from MSDN at http msdn microsoft com en us library aa476426 aspx To develop applications using the WinUSB interface the Windows Driver Development Kit DDK must be installed on your build PC This interface is currently used by the Stellaris Windows example applications LM Oscilloscope and USB Bulk Example These appli cations can be found in package PDL LM3S win which may be downloaded via a link on http www ti com stellaris libusb win32 supports Windows98SE Windows2000 WindowsNT and WindowsXP and can be downloaded from nttp libusb win32 sourceforge net It offers a straightforward method of accessing the device and also provides a very helpful INF file generator 3 5 4 1 Sample WinUSB INF file This file illustrates how to build an INF to associate your device with the WinUSB subsystem on WindowsXP or Vista Note that the driver package for the device must include not only this INF file but the Microsoft supplied coinstallers listed in the files section These can be found within the Windows Driver Development Kit DDK Stellaris Generic Bulk USB device driver installer This INF file may be used as a template when creating customized applications based on the Stellaris generic bulk devices Areas of the file requiring customization for a new device are commented with NOTEs NOTE When you customize this INF for your own device create
142. a new class name Class and a new GUID ClassGuid GUIDs may be created using the guidgen tool from Windows Visual Studio Version Signature SWindows NTS Class StellarisBulkDeviceClass ClassGuid F5450C06 EB58 420e 8F98 A76C5DA4AFB18 Provider ProviderName CatalogFile MyCatFile cat Manufacturer SProviderName S StellarisBulkDevice WinUSB NTx86 NTamd64 NOTE Replace the VID and PID in the following two sections with the correct values for your device StellarisBulkDevice WinUSB NTx86 SUSB StellarisBulkDevice DeviceDesc USB Install USBNVID 1CBE amp PID 0003 StellarisBulkDevice WinUSB NTamd64 SUSB StellarisBulkDevice DeviceDesc USB Install USBNVID 1CBE amp PID 0003 ClassInstall32 September 05 2012 75 Device Functions AddReg AddReg_ClassInstall AddReg ClassInstall HKR DeviceClassDisplayName HKR Icon 20 USB Install Include winusb inf Needs WINUSB NT USB Install Services Include winusb inf AddService WinUSB 0x00000002 WinUSB ServiceInstall WinUSB ServiceInstall DisplayName WinUSB SvcDesc ServiceType 1 StartType 3 ErrorControl 1 ServiceBinary 12 NWinUSB sys USB_Install Wdf KmdfService WINUSB WinUsb Install WinUSB Install KmdfLibraryVersion 1 5 USB Install HW AddReg Dev AddReg NOTE Create a new GUID for your interface and replace the following one when customizing for a new device Dev AddReg USB Install CoIns
143. ace to applications or to other device interface layers With the addition of hub support the application interface layer should take into account multiple instances of a device class if multiple instances of devices are supported September 05 2012 Host Functions 4 5 Host Class Driver Definitions Defines m USB HOST AUDIO INSTANCE SIZE m USBH AUDIO EVENT CLOSE m USBH AUDIO EVENT OPEN m USBH EVENT HID KB MOD m USBH EVENT HID KB PRESS m USBH EVENT HID KB REL m USBH EVENT HID MS PRESS m USBH EVENT HID MS REL m USBH EVENT HID MS X m USBH EVENT HID MS Y Enumerations m tHiDSubClassProtocol Functions void USBHHIDClose unsigned long ulHIDInstance unsigned long USBHHIDGetReport unsigned long ullnstance unsigned long ullnterface un signed char xpucData unsigned long ulSize unsigned long USBHHIDGetReportDescriptor unsigned long ullnstance unsigned char xpucBuffer unsigned long ulSize unsigned long USBHHIDOpen tHIDSubClassProtocol eDeviceType tUSBCallback pfnCall back unsigned long ulCBData unsigned long USBHHIDSetldle unsigned long ullnstance unsigned char ucDuration un signed char ucReportID unsigned long USBHHIDSetProtocol unsigned long ullnstance unsigned long ulBootProto col unsigned long USBHHIDSetReport unsigned long ullnstance unsigned long ullnterface un signed char pucData unsigned long ulSize void USBHHubClose unsigned long ullnstance void USB
144. ack pfnRxCallback pfnTxCallback A pointer to the callback function which will be called to notify the application of events related to the device s data transmit channel pvTxCBData A client supplied pointer which will be sent as the first parameter in all calls made to the transmit channel callback pfnTxCallback ppStringDescriptors A pointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manu facturer name string language 1 Product name string language 1 Serial number string language 1 Control interface description string language 1 Configuration description string language 1 If supporting more than 1 language the strings for indices 1 through 5 must be repeated for each of the other languages defined in the language descriptor ulNumStringDescriptors The number of descriptors provided in the ppStringDescriptors ar ray This must be 1 5 number of supported languages psPrivateCDCSerData A pointer to the private instance data for this device This memory must remain accessible for as long as the CDC device is in use and must not be modified by any code outside the CDC class driver Description The structure used by the application to define operating parameters for the CDC device Define Documentation COMPOSITE_DCDC_SIZE Definition define COMPOSITE DCDC SIZE Description The size of the
145. ack routines to prevent underflow overflow conditions from occuring Using the Generic Audio Device Class To add USB Audio data playback capability to your application via the Audio Device Class Driver take the following steps m Add the following header files to the source file s which are to support USB include src usb h include usblib usblib h include usblib device usbdevice h include usblib device usbdaudio h September 05 2012 Device Functions m Define the six entry string descriptor table which is used to describe various features of your new device to the host system The following is the string table taken from the usb dev audio example application Edit the actual strings to suit your application and take care to ensure that you also update the length field the first byte of each descriptor to cor rectly reflect the length of the string and descriptor header The number of string descriptors you include must be 1 5 num languages where the number of languages agrees with the list published in string descriptor 0 g_pLangDescriptor The strings for each language must be grouped together with all the language 1 strings before all the language 2 strings and so on J f kk kk k k ke kc ke kk ok ke kk Kk Kk Kk kk kk kk Kok kk ko kk kk kk Sk koc ko kk KK Kk Kk kk kk ok ke kk k k kk K K kk Ko ke kk Ke ke ke e HI The languages supported by this device TKK RK kk kk kk kk Kk Kk ke kk ke R
146. ader file containing the definitions needed to interact with the USB host Hub class driver September 05 2012 4 2 4 2 1 Host Functions usbhhidkeyboard c The source code for the USB host HID class keyboard device usbhhidkeyboard h The header file containing the definitions needed to interact with the USB host HID class keyboard device usbhhidmouse c The source code for the USB host HID class mouse device usbhhidmouse h The header file containing the definitions needed to interact with the USB host HID class mouse device usbhmsc c The source code for the USB host Mass Storage class driver usbhmsc h The header file containing Mass Storage class definitions specific to hosts supporting this class of device usbhscsi c The source code for a high level SCSI interface which calls the host Mass Storage class driver Host Controller Driver The USB library host controller driver provides an interface to the host controller s hardware register interface This is the lowest level of the driver interface and it interacts directly with the DriverLib USB APIs The host controller driver provides all of the functionality necessary to provide enumer ation of devices regardless of the type of device that is connected This portion of the enumeration code only enumerates the device and allows the higher level drivers to actually handle normal de vice operations To allow the application to conserve code and data memory the host contr
147. ageNumBlocks hy The event notification call back function USBMSCDEventCallback No DMA in use by this application 0 The per instance private data used by the mass storage class ff amp g_sMSCInstance The initialization and configuration calls for the USB library s mass storage device class are handled by a single call that passes in the tUSBDMSCDevice structure Example Initialization code Pass our device information to the USB library and place the device on the bus USBDMSCInit 0 tUSBDMSCDevice amp g_sMSCDevice September 05 2012 Device Functions Drop into the main loop while 1 The application s event call back function provides the application with notifications of changes in the USB mass storage class The application can use this information to update its own state The events may occur in rapid succession and the application must be careful not to spend much time in this function as it is called from a interrupt handler The application should expect many calls to this function during USB transfers Example Callback handler unsigned long USBDMSCEventCallback void pvCBData unsigned long ulEvent unsigned long ulMsgParam void pvMsgData switch ulEvent Writing to the device case USBD_MSC_EVENT_WRITING Handle write case break Reading from the device case
148. akeup advertised to the host via the config descriptor may call this function to initiate remote wakeup signaling to the host If the remote wakeup feature has not been disabled by the host this will cause the bus to resume operation within 20mS If the host has disabled remote wakeup false will be returned to indicate that the wakeup request was not successful Returns Returns true if the remote wakeup is not disabled and the signaling was started or false if remote wakeup is disabled or if signaling is currently ongoing following a previous call to this function USBDCDCRxPacketAvailable Determines whether a packet is available and if so the size of the buffer required to read it Prototype unsigned long USBDCDCRxPacketAvailable void pvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDCInit Description This function may be used to determine if a received packet remains to be read and allows the application to determine the buffer size needed to read the data Returns Returns 0 if no received packet remains unprocessed or the size of the packet if a packet is waiting to be read September 05 2012 3 8 4 8 3 8 4 9 Device Functions USBDCDCSerialStateChange Informs the CDC module of changes in the serial control line states or receive error conditions Prototype void USBDCDCSerialStateChange void pvInstance unsigned short usState Parameters pvi
149. all this function to initialize the USB controller and attach the device to the USB bus This function performs all required USB initialization On successful completion this function will return the psDevice pointer passed to it This must be passed on all future calls from the application to the HID device class driver The USB HID device class API offers the application a report based transmit interface for Input reports Output reports may be received via the control endpoint or via a dedicated Interrupt OUT endpoint If using the dedicated endpoint report data is delivered to the application packet by packet If the application uses reports longer than 64 bytes and would rather receive full reports it may use a USB buffer above the receive channel to allow full reports to be read Transmit Operation Calls to USBDHIDReportWrite pass complete reports to the driver for transmission These will be transmitted to the host using as many USB packets as are necessary to complete the transmission Once a full Input report has been acknowledged by the USB host a USB EVENT TX COMPLETE event is sent to the application transmit callback to inform it that another report may be transmitted Receive Operation when using a dedicated interrupt OUT endpoint An incoming USB data packet will result in a call to the application callback with event USB EVENT RX AVAILABLE The application must then call USBDHIDPacketRead pass ing a buffer capable
150. allbacks or direct APIs that is discussed in the rest of this chapter Much like the USB library s device programming interface the host interface has the following layers m Device APIs Mouse Keyboard Filesystem m USB Class Driver APIs HID Mass Storage Hub m USB Host Controller APIs m DriverLib USB Driver APIs September 05 2012 209 Host Functions 210 Application 1 Application 3 Application 4 Application 2 Host Class API USB Host Class Driver USB Host Controller Driver USB DriverLib API Source Code Overview Source code and headers for the host specific USB functions can be found in the host directory of the USB library tree typically DriverLib usblib host usb usb usb usb usb usb usb usb host h hostenum c haudio c haudio h hhid c hhid h hhub c hhub h The header file containing host mode function prototypes and data types offered by the USB library The source code for the USB host enumeration functions offered by the li brary The source code for the USB host Audio class driver The header file containing Audio class definitions specific to hosts supporting this class of device The source code for the USB host HID class driver The header file containing the definitions needed to interact with the USB host HID class driver The source code for the USB host Hub class driver The he
151. alling the USBHostAudioRecord function before the previous buffer has been filled can cause the previous input transfer to be interrupted or lost Since the USB host audio driver provides limited buffering it is up to the application to handle the input buffers and provide new buffers The application can safely call USBHostAudioRecord function directly from the call back function to provide a new buffer to the USB audio device however the same buffer should not be passed back until it has been processed or the host audio driver may overwrite the data Example Audio Input void AudioInCallback void pvBuffer unsigned long ulParam unsigned long ulEvent 4 Check if this was a buffer full event and provide a new buffer to the host audio driver 4 if ulEvent USB EVENT RX AVAILABLE USBHostAudioRecord ulAudioInstance pNewBuffer ulSize AudioInCallback void AudioRecord void Wait for USBH_AUDIO_EVENT_OPEN event Set the audio format to 48KHz 16 bit stereo output ff USBHostAudioFormatSet ulAudioInstance 48000 16 2 USBH AUDIO FORMAT IN Start the input of the first buffer and let the callback start the vemaining buffers USBHostAudioRecord ulAudioInstance pBuffer ulSize AudioInCallback 724 Handle filling returned buffers September 05 2012 241 Host Functions 4 4 6 242 Implementing Custom Host Class Drivers This next section co
152. alue is currently reserved and should be set to 0 pfnEvent is the callback that will be called for various USB events Description The first parameter is the actual name of the variable that will be declared by this macro The second and third parameter are reserved for future functionality and are unused and should be set to zero The last parameter is the actual callback function and is specified as a function pointer of the type void pfnEvent void pvData When the pfnEvent function is called the void pointer that is passed in as a parameter should be cast to a pointer to a structure of type tEventlnfo This will contain the event that caused the pfnEvent function to be called Function Documentation 4 3 4 1 void USBOHostIntHandler void 4 3 4 2 216 The USB host mode interrupt handler for controller index 0 This the main USB interrupt handler entry point This handler will branch the interrupt off to the appropriate handlers depending on the current status of the USB controller This function must be placed in the interrupt table in order for the USB Library host stack to function Returns None USBHCDControlTransfer Definition unsigned long USBHCDControlTransfer unsigned long ulIndex tUSBRequest pSetupPacket tUSBHostDevice xpDevice unsigned char pData unsigned long ulSize unsigned long ulMaxPacketSize September 05 2012 Host Functions Description This function comple
153. ameters ullnstance is an instance of the USB audio device ullnterface is the interface number to use to set the current volume setting ulChannel is the 0 based channel number to query ulValue is the value to write to the USB audio device Description The function is used to set the current volume setting for an audio device on the channel specified by u Channel The ullnterface is ignored for now and should be set to 0 to access the default audio control interface The u Channel value starts with O which is the master audio volume control interface The remaining u Channel values provide access to various other audio channels with 1 and 2 being left and right audio channels September 05 2012 4 5 4 28 4 5 4 29 Host Functions Note On devices that do not support volume control interfaces this call returns 0 indicating a Odb setting Returns None USBHSOSIInquiry This will issue the SCSI inquiry command to a device Prototype unsigned long USBHSCSIInquiry unsigned long ulInPipe unsigned long ulOutPipe unsigned char xpucData unsigned long x pulSize Parameters ullnPipe is the USB IN pipe to use for this command ulOutPipe is the USB OUT pipe to use for this command pucData is the data buffer to return the results into pulSize is the size of buffer that was passed in on entry and the number of bytes returned Description This function should be used to issue a SCSI Inquiry command to a mass s
154. an Interface Device HID In order to use these class drivers the application must pro vide a list of the host class drivers that it uses by calling the USBHCDRegisterDrivers function The g_USBHIDClassDriver structure defines the interface for the Host HID class driver and the g USBHostMSCClassbDriver structure defines the interface for the Host MSC class driver The host class driver provides interfaces at its bottom layer to the USB host controller driver and device specific interfaces at it s top layer The lower layer interface to the USB host controller interface is the same for all USB host class drivers while the device interface layer on top is common to all USB host device interface of a given class Thus the top layer of the of the MSC class driver does not need to match the top layer of the HID class driver however the lower layer must be the same for both Aside from enumeration all communication with the host class driver is through its endpoint pipes The host class driver parses and allocate any endpoints that it needs by calling the USBHCDPipeAlloc and USBHCDPipeConfig functions These USB pipes provide the methods to read write and get callback notification from the USB host controller driver layer USB Events Driver The USB host library includes a method to receive non device class specific events in the ap plication by using a USB event driver This driver can be included in applications by declaring an instance of the USB
155. and requests a pointer to the report that must be sent back to the host The ulMsgData value will contain the requested report ID and pvMsgData contains a pointer that must be written with a pointer to the report data that is to be sent The callback must return the number of bytes in the report pointed to by xpvMsgData 3 14 3 43 USBD HID EVENT REPORT SENT Definition define USBD HID EVENT REPORT SENT Description This event indicates that a report previously requested via a USBD HID EVENT GET REPORT has been successfully transmitted to the host The application may now free or reuse the report memory passed on the previous event Although this would seem to be an event that would be passed to the transmit channel callback it is actually passed to the receive channel callback This ensures that all events related to the request and transmission of reports via endpoint zero can be handled in a single function September 05 2012 149 Device Functions 3 14 3 44 USBD_HID_EVENT_SET_PROTOCOL Definition define USBD HID EVENT SET PROTOCOL Description This event is sent in response to a Set Protocol request from the host The ulMsgData value will contain the requested protocol USB HID PROTOCOL BOOT or USB HID PROTOCOL REPORT 3 14 3 45 USBD HID EVENT SET REPORT 3 14 4 3 14 4 1 3 14 4 2 150 Definition define USBD HID EVENT SET REPORT Description This even
156. andler void unsigned long USBHCDControlTransfer unsigned long ullndex tUSBRequest xpSetupPacket tUSBHostDevice pDevice unsigned char pData unsigned long ulSize unsigned long ulMaxPacketSize unsigned char USBHCDDevAddress unsigned long ullnstance unsigned char USBHCDDevClass unsigned long ullnstance unsigned long ullnterface unsigned char USBHCDDevHubPort unsigned long ullnstance unsigned char USBHCDDevProtocol unsigned long ullnstance unsigned long ullnterface unsigned char USBHCDDevSubClass unsigned long ullnstance unsigned long ullnterface long USBHCDEventDisable unsigned long ullndex void pvEventDriver unsigned long ulEvent long USBHCDEventEnable unsigned long ullndex void pvEventDriver unsigned long ulEvent void USBHCDInit unsigned long ullndex void pvPool unsigned long ulPoolSize void USBHCDMain void unsigned long USBHCDPipeAlloc unsigned long ullndex unsigned long ulEndpointType tUS BHostDevice psDevice tHCDPipeCallback pfnCallback unsigned long USBHCDPipeAllocSize unsigned long ullndex unsigned long ulEndpointType tUSBHostDevice psDevice unsigned long ulSize tHCDPipeCallback pfnCallback unsigned long USBHCDPipeConfig unsigned long ulPipe unsigned long ulMaxPayload un signed long ullnterval unsigned long ulTargetEndpoint void USBHCDPipeDataAck unsigned long ulPipe September 05 2012 213 Host Functions void USBHCDPipeFree unsigned long ulPipe unsigne
157. arameters ullndex is the index of the USB controller which is to be initialized for CDC device operation psCDCDevice points to a structure containing parameters customizing the operation of the CDC device Description An application wishing to make use of a USB CDC communication channel and appear as a virtual serial port on the host system must call this function to initialize the USB controller and attach the device to the USB bus This function performs all required USB initialization The value returned by this function is the psCDCDevice pointer passed to it if successful This pointer must be passed to all later calls to the CDC class driver to identify the device instance The USB CDC device class driver offers packet based transmit and receive operation If the application would rather use block based communication with transmit and receive buffers USB buffers on the transmit and receive channels may be used to offer this functionality Transmit Operation Calls to USBDCDCPacketWrite must send no more than 64 bytes of data at a time and may only be made when no other transmission is currently outstanding September 05 2012 99 Device Functions 3 8 4 3 100 Once a packet of data has been acknowledged by the USB host a USB_EVENT_TX_COMPLETE event is sent to the application callback to inform it that another packet may be transmitted Receive Operation An incoming USB data packet will result in a call to the applicati
158. are logical OR combinations of MOUSE REPOHT BUTTON 1 MOUSE REPORT BUTTON 2 and MOUSE REPORT BUTTON 3 Description This function is called to report changes in the mouse state to the USB host These changes can be movement of the pointer reported relative to its previous position or changes in the states of up to 3 buttons that the mouse may support The return code indicates whether or not the mouse report could be sent to the host In cases where a previous report is still being transmitted MOUSE ERR TX ERROR will be returned and the state change will be ignored Returns 164 Returns MOUSE SUCCESS on success MOUSE ERR TX ERROR if an error occurred while attempting to schedule transmission of the mouse report to the host typically due to a previous report which has not yet completed transmission or due to disconnection of the host or MOUSE ERR NOT CONFIGURED if called before a host has connected to and configured the device September 05 2012 Device Functions 3 16 4 7 USBDHIDMouseTerm 3 17 Shuts down the HID mouse device Prototype void USBDHIDMouseTerm void pviInstance Parameters pvinstance is the pointer to the device instance structure Description This function terminates HID mouse operation for the instance supplied and removes the device from the USB bus Following this call the pvinstance instance may not me used in any other call to the HID mouse device other than USBDHIDMouselnit Returns Non
159. ass API Definitions a oaaae a 181 3 21 Using the USB Device API 0 0000 s 186 3 22 USB Device API Definitions osos or Run kk ns 197 4 Most FUMCHONS oco lum bee sow mx RE Oe oS e Ro m ws 209 CM EB S IEEE IESTTATITILITITSOTTIITT TS ae a a a WM i a A G 209 42 Host Controller Driver iusso ssa oro or yX LLEGUE Y komo o3 o a ew ee 211 4 3 Host Controller Driver Definitions 2 2 Rss 213 44 Host Glass Diver 24 bee eee aaa Re RR mmm Rmo omm wala RR EE ERA 231 4 5 Host Class Driver Definitions ess 243 4 6 Host Device Interface llle lle les 267 4 7 Host Device Interface Definitions rA 268 48 Host Programming Examples l llle es 273 IMPORTANT NOTICE scere ens mh om oohoh hoyo ooyo ono oy on non 282 September 05 2012 3 Table of Contents 4 September 05 2012 Introduction 1 Introduction The Texas Instruments Stellaris amp USB Library is a set of data types and functions for creating USB device host or On The Go OTG applications on Stellaris microcontroller based boards The contents of the USB library and its associated header files fall into four main groups m General purpose functions used by both device and host applications These include functions to parse USB descriptors and set the operating mode of the application m Device specific functions providing the class independent features required by all USB de vice applicat
160. ation that a USB device has been disconnected followed immediately by a reconnection as the boot loader starts and publishes is DFU mode descriptors to the host These descriptors use PID OxOOFF rather than the PID published by the composite device as suggested in the USB DFU speci fication Once this mode switch has taken place the device will be visible in LM Flash Programmer s device list shown when Manual Configuration is chosen along with the USB DFU interface If LMFlash was running when the mode switch took place press the Refresh button to search for and display the DFU device To program a device in DFU mode either use LM Flash Programmer s GUI or dfuprog f lt filename gt Device Firmware Upgrade Device Class Driver Defini tions Data Structures m tUSBDDFUDevice Defines m COMPOSITE DDFU SIZE m USBD DFU EVENT DETACH Functions m void x USBDDFUCompositelnit unsigned long ullndex const tUSBDDFUDevice psDevice m void USBDDFUCompositeTerm void pvlnstance m void USBDDFUUpdateBegin void Detailed Description Definitions The macros and functions defined in this section can be found in header file device usbddfu rt h September 05 2012 119 Device Functions 3 12 2 Data Structure Documentation 3 12 2 1 tUSBDDFUDevice Definition typedef struct tUSBCallback pfnCallback void xpvCBData tDFUInstance xpsPrivateDFUData tUSBDDFUDevice Members pfnCallback A pointer to the ca
161. automatic resending of each report if not disabled by the host 3 14 2 5 tUSBDHIDDevice Definition typedef struct nsigned short usVID nsigned short usPID nsigned short usMaxPowermA nsigned char ucPwrAttributes nsigned char ucSubclass nsigned char ucProtocol nsigned char ucNumInputReports HIDReportIdle xpsReportIdle USBCallback pfnRxCallback oid xpvRxCBData USBCallback pfnTxCallback void xpvTxCBData tBoolean bUseOutEndpoint const tHIDDescriptor xpsHIDDescriptor const unsigned char const xppClassDescriptors const unsigned char x const xppStringDescriptors unsigned long ulNumStringDescriptors tHIDInstance psPrivateHIDData QU d vb octo op or C ocG m uu tUSBDHIDDevice Members usVID The vendor ID that this device is to present in the device descriptor usPID The product ID that this device is to present in the device descriptor usMaxPowermA The maximum power consumption of the device expressed in milliamps 136 September 05 2012 Device Functions ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wakeup Valid values are USB_CONF_ATTR_SELF_PWR or USB_CONF_ATTR_BUS_ PWR optionally ORed with USB_CONF_ATTR_RWAKE ucSubclass The interface subclass to publish to the server for this HID device ucProtocol The interface protocol to publish to the server for this HID device ucNuminputReports The number of Input rep
162. aximum power consumption of the device expressed in milliamps ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wakeup Valid values are USB CONF ATTR SELF PWR or USB CONF ATTR BUS PWhR optionally ORed with USB CONF ATTR RWAKE pfnCallback A pointer to the callback function which will be called to notify the application of events relating to the operation of the mouse pvCBData A client supplied pointer which will be sent as the first parameter in all calls made to the mouse callback pfnCallback ppStringDescriptors A pointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manu facturer name string language 1 Product name string language 1 Serial number string language 1 HID Interface description string language 1 Configuration description string language 1 If supporting more than 1 language the descriptor block except for string descriptor 0 must be repeated for each language defined in the language descriptor ulNumStringDescriptors The number of descriptors provided in the ppStringDescriptors ar ray This must be 1 5 num languages psPrivateHIDMouseData pointer to private instance data for this device This memory must remain accessible for as long as the mouse device is in use and must not be modified by any code outside the HID mouse driver Descr
163. be communicating with psDevice is the device instance associated with this endpoint pfnCallback is the function that will be called when events occur on this USB Pipe Since there are a limited number of USB HCD pipes that can be used in the host controller this function is used to temporarily or permanently acquire one of the endpoints It also provides a method to register a callback for status changes on this endpoint If no callbacks are desired then the pfnCallback function should be set to 0 The callback should be used when using the USBHCDPipeSchedule function so that the caller is notified when the action is complete September 05 2012 221 Host Functions Returns This function returns a value indicating which pipe was reserved If the value is 0 then there were no pipes currently available This value should be passed to any USBHCDPipe APIs to indicate which pipe is being accessed 4 3 4 43 USBHCDPipeAllocSize Definition unsigned long USBHCDPipeAllocSize unsigned long ulIndex unsigned long ulEndpointType tUSBHostDevice psDevice unsigned long ulSize tHCDPipeCallback pfnCallback Description This function is used to allocate a USB HCD pipe Parameters ullndex specifies which USB controller to use ulEndpointType is the type of endpoint that this pipe will be communicating with psDevice is the device instance associated with this endpoint ulSize is the size of the FIFO in bytes pfnCallbac
164. between a USB device class driver and the de vice application or between the USB host controller driver and a host class driver in an application and class independent way Driver data transfer APIs all use a common prototype as do event call backs so the USB buffer is inserted into the data path using driver function and instance pointers provided in static structures during application initialization This method has the advantage that the USB buffer is not directly dependent upon any specific functions in the USB library and as a result using it does not pull extraneous code into the final application image During operation events from the layer below the buffer are inspected in the buffers event han dler If they are unrecognized or have no effect on the flow of data they are passed to the higher layer unaltered If they relate to data flow however the buffer intercepts them and performs the necessary actions to transmit or receive data before passing appropriate events to the layer above To insert a buffer for use on a transmit or receive channel or pipe a cUSBBuf fer structure must be initialized as follows bTransmitBuffer This field must be set to true if the buffer is passing data from the appli cation code to the USB controller or false if passing data from the USB controller to the application pfnCallback This field should point to the event handler callback function in the appli cation code Notifications of asynchronous ev
165. boardSetCBData Sets the client specific pointer parameter for the keyboard callback Prototype void USBDHIDKeyboardSetCBData void xpviInstance void xpvCBData Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDKeyboard Init pvCBDaia is the pointer that client wishes to be provided on each event sent to the keyboard callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnCallback function passed on USBDHIDKeyboardinit If a client wants to make runtime changes in the callback pointer it must ensure that the pvin stance structure passed to USBDHIDKeyboardlnit resides in RAM If this structure is in flash callback data changes will not be possible September 05 2012 Device Functions Returns Returns the previous callback pointer that was set for this instance 3 18 4 7 USBDHIDKeyboardTerm Shuts down the HID keyboard device Prototype void USBDHIDKeyboardTerm void xpviInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDKeyboard Init Description This function terminates HID keyboard operation for the instance supplied and removes the device from the USB bus Following this call the pv nstance instance may not me used in any other call to the HID keyboard device other than USBDHIDKeyboardlnit Returns None
166. ce the array must have 1 element matching the value of the previous field g psMouseReportIdle A pointer to your receive callback event handler YourUSBReceiveEventCallback A value that you want passed to the receive callback alongside every event void amp g sYourInstanceData A pointer to your transmit callback event handler YourUSBTransmitEventCallback A value that you want passed to the transmit callback alongside every event void amp g sYourInstanceData 128 September 05 2012 m Add Device Functions EA This device does not want to use a dedicated interrupt OUT endpoint since there are no output or feature reports required false A pointer to the HID descriptor for the device amp g sMouseHIDDescriptor red A pointer to the array of HID class descriptor pointers for this device The number of elements in this array and their order must match the information in the HID descriptor provided above g_pMouseClassDescriptors A pointer to your string table g_pStringDescriptors The number of entries in your string table This must equal 1 5 num HID strings num languages NUM_STRING_DESCRIPTORS A pointer to the private instance data allocated for the class driver to use amp g sHIDInstance a receive event hand
167. ceClass field September 05 2012 General Purpose Functions bDeviceProtocol The device protocol code This value is qualified by the values of bDevice Class and bDeviceSubClass bMaxPacketSize0 The maximum packet size for endpoint zero Valid values are 8 16 32 and 64 idVendor The device Vendor ID VID as assigned by the USB IF idProduct The device Product ID PID as assigned by the manufacturer bcdDevice The device release number in BCD format iManufacturer The index of a string descriptor describing the manufacturer iProduct The index of a string descriptor describing the product iSerialNumber The index of a string descriptor describing the device s serial number bNumConfigurations The number of possible configurations offered by the device This field indicates the number of distinct configuration descriptors that the device offers Description This structure describes the USB device descriptor as defined in USB 2 0 specification section 9 6 1 2 3 2 4 tDeviceQualifierDescriptor Definition typedef struct unsigned char bLength unsigned char bDescriptorType unsigned short bcdUSB unsigned char bDeviceClass unsigned char bDeviceSubClass unsigned char bDeviceProtocol unsigned char bMaxPacketSize0 unsigned char bNumConfigurations unsigned char bReserved tDeviceQualifierDescriptor Members bLength The length of this descriptor in bytes All device qualifier descriptors are
168. ck pfnCallback ppStringDescriptors A pointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manu facturer name string language 1 Product name string language 1 Serial number string language 1 HID Interface description string language 1 Configuration description string language 1 If supporting more than 1 language the descriptor block except for string descriptor 0 must be repeated for each language defined in the language descriptor ulNumStringDescriptors The number of descriptors provided in the ppStringDescriptors ar ray This must be 1 5 num languages psPrivateHIDKbdData A pointer to private instance data for this device This memory must remain accessible for as long as the keyboard device is in use and must not be modified by any code outside the HID keyboard driver Description This structure is used by the application to define operating parameters for the HID keyboard device September 05 2012 169 Device Functions 3 18 3 Define Documentation 3 18 3 1 KEYB ERR NOT CONFIGURED Definition define KEYB ERR NOT CONFIGURED Description USBDHIDKeyboardKeyStateChange returns this value if it is called before the USB host has connected and configured the device Any key usage code passed will be stored and passed to the host once configuration completes 3 18 3 2 KEYB ERR NOT
169. criptor string table J f kk KK ROKR KR RRR kk Kok kk ko ko RR RIOR IR A I I ke ee const unsigned char const g pStringDescriptors g_pLangDescriptor g_pManufacturerString g_pProductString g_pSerialNumberString g pControlInterfaceString g pConfigString define NUM STRING DESCRIPTORS sizeof g pStringDescriptors N sizeof unsigned char Define a tCDCSerlnstance structure which the USB CDC serial device class driver uses to store its internal state information This should never be accessed by the application J k kk kk ko ke kk ke Kk kk kk Kk kk ko kk Kok kk ko ke kk kk kk kk kk ko ko kk kk OR kk kk ko kk ko kk ko ke kk ko ke kk ke ke eo ke ee The CDC serial device private data kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkx tCDCSerInstance g_sSerialInstance Define a tUSBDCDCDevice structure and initialize all fields as required for your application The following example illustrates a simple case where no USB buffers are in use For an exam ple using USB buffers see the source file usb_bulk_structs c in the usb_dev_serial example application const tUSBDCDCDevice g_sCDCDevice The Vendor ID you have been assigned by USB IF USB_VID_YOUR_VENDOR_ID bie The product ID you have assigned for this device USB_PID_YOUR_PRODUCT_ID The power consumption of your device in milliamps POWER_CONSUMPTION_mA
170. ction passed on USBDCDOInit September 05 2012 103 Device Functions 3 8 4 10 3 8 4 11 104 If a client wants to make runtime changes in the callback pointer it must ensure that the psCD CDevice structure passed to USBDCDCInit resides in RAM If this structure is in flash call back pointer changes will not be possible Returns Returns the previous callback pointer that was being used for this instance s control callback USBDCDCSetRxCBData Sets the client specific data parameter for the receive channel callback Prototype void USBDCDCSetRxCBData void x xpvInstance void xpvCBData Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDCInit pvCBDaia is the pointer that client wishes to be provided on each event sent to the receive channel callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnRxCallback function passed on USBDCDChInit If a client wants to make runtime changes in the callback pointer it must ensure that the psCD CDevice structure passed to USBDCDGOInit resides in RAM If this structure is in flash call back data changes will not be possible Returns Returns the previous callback pointer that was being used for this instance s receive callback USBDCDCSetTxCBData Sets the client specific data parameter for the transmit callback Prototype vo
171. cture This is the actual minimum value for a range of values associated with a field Returns Not a function 3 14 3 10 Output This is a macro to assist adding Output entries in HID report descriptors Definition define Output ucValue Parameters ucValue is bit mask to specify the type of a set of output report items Note that if the USB_HID_OUTPUT_BITF flag is required the Output2 macro which uses a 2 byte version of the Output item tag must be used instead of this macro Description This macro takes a value and prepares it to be placed as an Output entry into a HID report structure This specifies the type of an output item in a report structure These refer to a bit mask of flags that indicate the type of output for a set of items Returns Not a function 3 14 3 11 Output2 This is a macro to assist adding Output entries in HID report descriptors Definition define Output2 usValue Parameters usValue is bit mask to specify the type of a set of output report items Note that this macro uses a version of the Output item tag with a two byte payload and allows any of the 8 possible data bits for the tag to be used If USB_HID_OUTPUT_BITF bit 8 is not required the Output macro may be used instead September 05 2012 141 Device Functions Description This macro takes a value and prepares it to be placed as an Output entry into a HID report structure This specifies the type of an output item in a report
172. current power status either USB STATUS SELF PWR or USB STATUS BUS PWR Description Applications which support switching between bus or self powered operation should call this function whenever the power source changes to indicate the current power status to the USB September 05 2012 173 Device Functions 3 18 4 5 3 18 4 6 174 library This information is required by the USB library to allow correct responses to be provided when the host requests status from the device Returns None USBDHIDKeyboardRemoteWakeupRequest Requests a remote wake up to resume communication when in suspended state Prototype tBoolean USBDHIDKeyboardRemoteWakeupRequest void pviInstance Parameters pvinstance is the pointer to the keyboard device instance structure Description When the bus is suspended an application which supports remote wake up advertised to the host via the configuration descriptor may call this function to initiate remote wake up signaling to the host If the remote wake up feature has not been disabled by the host this will cause the bus to resume operation within 20mS If the host has disabled remote wake up false will be returned to indicate that the wake up request was not successful Returns Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previous call to this function USBDHIDKey
173. customizing the operation of the com posite device ulSize is the size in bytes of the data pointed to by the pucData parameter pucData is the data area that the composite class can use to build up descriptors Description In order for an application to initialize the USB composite device class it must first call this function with the a valid composite device class structure in the psDevice parameter This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB composite device The u Size and pucData parameters should be large enough to hold all of the class instances passed in via the psDevice structure This is typically the full size of the configuration descriptor for a device minus its configuration header 9 bytes This function returns a void pointer that must be passed in to all other APIs used by the com posite class See the documentation on the tUSBDCompositeDevice structure for more information on how to properly fill the structure members Returns This function returns O on failure or a non zero void pointer on success USBDCompositeTerm Shuts down the composite device Prototype void USBDCompositeTerm void xpviInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDCompos itelnit Description This function terminates composite device interface for the instance supplied Following this call the pvin
174. d The buffer provided may not be completely full so the application should only play the portion of the buffer indicated by the message To prevent underflow the application should always be sure that the audio device class has an empty buffer to fill as soon as a filled buffer is returned The USB audio class does not provide a way to stop playing audio because typically when the USB host controller stops playing audio the host will simply stop providing data to the USB audio device and playback will stop This will not result in any notification to the application other than USBD AUDIO EVENT DATAOUT messages will stop being received If the application needs to stop receiving data it can simply stop providing buffers to the USB audio class and the audio class will ignore any incoming data from the USB host controller Handling Other Audio Messages The USB audio class also provides a few other notification messages to the application These are the USBD AUDIO EVENT VOLUME and USBD AUDIO EVENT MUTE messages which are both inform the application of volume and mute changes in the playback stream The USBD AUDIO EVENT VOLUME message returns a value that ranges from 0 100 in percent age for the playback volume The USBD AUDIO EVENT MUTE is either zero indicating that the playback path is not muted or 1 indicating that the playback path is muted The application should always take care to defer any lenghty processing of messages to its non callb
175. d long ulInterface Description This function will return the USB class for the requested device instance Parameters ullnstance is a unique value indicating which device to query ullnterface is the interface number to query for the USB class This function returns the USB class for the device that is associated with the ulInstance pa rameter The caller must use a value for ulInstance have been passed to the application when it receives a USB EVENT CONNECTED event The function will return the USB class for the September 05 2012 217 Host Functions interface number specified by the ullnterface parameter If ullnterface is set to OXFFFFFFFF then the function will return the USB class for the first interface that is found in the device s USB descriptors Returns The USB class for the requested interface 4 3 45 USBHCDDevHubPort Definition unsigned char USBHCDDevHubPort unsigned long ulInstance Description This function returns the USB hub port for the requested device instance Parameters ullnstance is a unique value indicating which device to query This function returns the USB hub port for the device that is associated with the ullnstance parameter The caller must use the value for ullnstance was passed to the application when it receives a USB EVENT CONNECTED event The function returns the USB hub port for the interface number specified by the ulInterface parameter Returns The USB hub port for the r
176. d is fixed for a given config descriptor Hence this function will September 05 2012 2 2 6 5 2 2 6 6 General Purpose Functions correctly find the unique interface descriptor for that interface s alternate setting number ulAlt if ullndex is set to the required interface number and ulAlt is set to a valid alternate setting number for that interface Returns Returns a pointer to the required interface descriptor if found or NULL otherwise USBDescGetlnterface Endpoint Return a pointer to the n th endpoint descriptor in the supplied interface descriptor Prototype tEndpointDescriptor x USBDescGetInterfaceEndpoint tInterfaceDescriptor xpsInterface unsigned long ulIndex unsigned long ulSize Parameters psinterface points to the first byte of a standard USB interface descriptor ullndex is the zero based index of the endpoint that is to be found ulSize contains the maximum number of bytes that the function may search beyond psinter face while looking for the requested endpoint descriptor Description Return a pointer to the n th endpoint descriptor found in the supplied interface descriptor If the ulindex parameter is invalid greater than or equal to the bNumEndpoints field of the inter face descriptor or the endpoint cannot be found within u Size bytes of the interface descriptor pointer the function will return NULL Note that although the USB 2 0 specification states that endpoint descr
177. d is issued or non standard descriptor has been requested on endpoint zero If the application needs notification when this is complete tDeviceInfo sCallbacks pfnDataSent should contain a valid function pointer This callback could be used to free up the buffer passed into this function in the pucData parameter The contents of the pucData buffer must remain unchanged until the pfnDataSent callback is received Returns None 3 22 3 7 USBDCDSetDefaultConfiguration This function sets the default configuration for the device Prototype void USBDCDSetDefaultConfiguration unsigned long ulIndex unsigned long ulDefaultConfig Parameters ullndex is the index of the USB controller whose default configuration is to be set ulDefaultConfig is the configuration identifier byte 6 of the standard configuration descrip tor which is to be presented to the host as the default configuration in cases where the configuration descriptor is queried prior to any specific configuration being set Description This function allows a device to override the default configuration descriptor that will be returned to a host whenever it is queried prior to a specific configuration having been set The parameter passed must equal one of the configuration identifiers found in the ppConfigDescriptors array for the device If this function is not called the USB library will return the first configuration in the ppConfigDescriptors array as
178. d long USBHCDPipeRead unsigned long ulPipe unsigned char pucData unsigned long ulSize unsigned long USBHCDPipeReadNonBlocking unsigned long ulPipe unsigned char xpucData unsigned long ulSize unsigned long USBHCDPipeSchedule unsigned long ulPipe unsigned char pucData un signed long ulSize unsigned long USBHCDPipeStatus unsigned long ulPipe unsigned long USBHCDPipeWrite unsigned long ulPipe unsigned char pucData unsigned long ulSize unsigned long USBHCDPowerAutomatic unsigned long ullndex unsigned long USBHCDPowerConfigGet unsigned long ullndex void USBHCDPowerConfiglnit unsigned long ullndex unsigned long ulPwrConfig unsigned long USBHCDPowerConfigSet unsigned long ullndex unsigned long ulConfig void USBHCDRegisterDrivers unsigned long ullndex const tUSBHostClassDriver const ppHClassDrvs unsigned long ulNumDrivers void USBHCDReset unsigned long ullndex void USBHCDResume unsigned long ullndex void USBHCDSetAddress unsigned long ulDevIndex unsigned long ulDevAddress void USBHCDSetConfig unsigned long ullndex unsigned long ulDevice unsigned long ul Configuration void USBHCDSetlnterface unsigned long ullndex unsigned long ulDevice unsigned long ullnterface unsigned ulAltSetting void USBHCDSuspend unsigned long ullndex void USBHCDTerm unsigned long ullndex 4 39 1 Detailed Description The macros and functions defined in this section can be found in header file host usbh
179. d long ullndex unsigned long ulDevice unsigned long ulConfiguration Description This function is used to set the current configuration for a device Parameters ullndex specifies which USB controller to use ulDevice is the USB device for this function September 05 2012 229 Host Functions ulConfiguration is one of the devices valid configurations This function is used to set the current device configuration for a USB device The ulConfig uration value must be one of the configuration indexes that was returned in the configuration descriptor from the device or a value of 0 If 0 is passed in the device will return to it s ad dressed state and no longer be in a configured state If the value is non zero then the device will change to the requested configuration Returns None 4 3 4 34 USBHCDGSetlnterface Definition void USBHCDSetInterface unsigned long ulIndex unsigned long ulDevice unsigned long ulInterface unsigned ulAltSetting Description This function is used to set the current interface and alternate setting for an interface on a device Parameters ullndex specifies which USB controller to use ulDevice is the USB device for this function ullnterface is one of the valid interface numbers for a device ulAltSetting is one of the valid alternate interfaces for the ullnterface number This function is used to change the alternate setting for one of the valid interfaces on a U
180. data available than was requested Returns This function returns the number of bytes that were returned in the pucData buffer 4 3 4 18 USBHCDPipeReadNonBlocking Definition unsigned long USBHCDPipeReadNonBlocking unsigned long ulPipe unsigned char xpucData unsigned long ulSize Description This function is used to read data from a USB HCD pipe Parameters ulPipe is the USB pipe to read data from pucData is a pointer to store the data that is received ulSize is the size in bytes of the buffer pointed to by pucData This function will not block and will only read as much data as requested or as much data is currently available from the USB pipe The caller should have registered a callback with the USBHCDPipeAlloc call in order to be informed when the data has been received The value returned by this function can be less than the u Size requested if the USB pipe has less data available than was requested Returns This function returns the number of bytes that were returned in the pucData buffer 4 3 4 19 USBHCDPipeSchedule Definition unsigned long USBHCDPipeSchedule unsigned long ulPipe unsigned char xpucData unsigned long ulSize 224 September 05 2012 Host Functions Description This function is used to schedule and IN transaction on a USB HCD pipe Parameters ulPipe is the USB pipe to read data from pucData is a pointer to store the data that is received ulSize is the size in b
181. default behavior is to do nothing Some protocols however require that a zero length packet be inserted to signal the end of the data When using such a protocol this function should be called with bSenaZLP set to true to enable the desired behavior Returns None USBRingBufAdvanceRead Removes bytes from the ring buffer by advancing the read index September 05 2012 45 General Purpose Functions 2 4 6 14 2 4 6 15 46 Prototype void USBRingBufAdvanceRead tUSBRingBufObject x xptUSBRingBuf unsigned long ulNumBytes Parameters ptUSBRingBuf points to the ring buffer from which bytes are to be removed ulNumBytes is the number of bytes to be removed from the buffer Description This function advances the ring buffer read index by a given number of bytes removing that number of bytes of data from the buffer If ulNumBytes is larger than the number of bytes currently in the buffer the buffer is emptied Returns None USBRingBufAdvanceWrite Adds bytes to the ring buffer by advancing the write index Prototype void USBRingBufAdvanceWrite tUSBRingBufObject xptUSBRingBuf unsigned long ulNumBytes Parameters ptUSBRingBuf points to the ring buffer to which bytes have been added ulNumBytes is the number of bytes added to the buffer Description This function should be used by clients who wish to add data to the buffer directly rather than via calls to USBRingBufWrite or USBRingBufWriteOne
182. delnit Initializes the USB controller for OTG mode operation September 05 2012 23 General Purpose Functions 2 2 6 12 2 2 6 13 24 Prototype void USBOTGModeInit unsigned long ulIndex unsigned long ulPollingRate void xpvPool unsigned long ulPoolSize Parameters ullndex specifies the USB controller that is to be initialized for OTG mode operation ulPollingRate is the rate in milliseconds to poll the controller for changes in mode pvPool is a pointer to the data to use as a memory pool for this controller ulPoolSize is the size in bytes of the buffer passed in as pvPool Description This function initializes the USB controller hardware into a state suitable for OTG mode oper ation Applications must use this function to ensure that the controller is in a neutral state and able to receive appropriate interrupts before host or device mode is chosen by OTG negotia tion The ulPollingRate parameter is used to set the rate at which the USB library will poll the controller to determine the mode This has the most effect on how quickly the USB library will detect changes when going to host mode The parameters pvPool and ulPoolSize are passed on to the USB host library functions to provide memory for the USB library when it is acting as a host Any device and host initialization should have been called before calling this function to prevent the USB library from attempting to run in device or host mode before the USB libra
183. descriptors Definition define Input2 usValue Parameters usValue is bit mask to specify the type of a set of input report items Note that this macro uses a version of the Input item tag with a two byte payload and allows any of the 8 possible data bits for the tag to be used If USB HID INPUT BITF bit 8 is not required the Input macro may be used instead Description This macro takes a value and prepares it to be placed as an Input entry into a HID report structure This specifies the type of an input item in a report structure These refer to a bit mask of flags that indicate the type of input for a set of items Returns Not a function LogicalMaximum This is a macro to assist adding Logical Maximum entries in HID report descriptors Definition define LogicalMaximum cValue Parameters cValue is the Logical Maximum value Description This macro takes a value and prepares it to be placed as a Logical Maximum entry into a HID report structure This is the actual maximum value for a range of values associated with a field Returns Not a function September 05 2012 Device Functions 3 14 3 9 LogicalMinimum This is a macro to assist adding Logical Minimum entries in HID report descriptors Definition define LogicalMinimum cValue Parameters cValue is the Logical Minimum value Description This macro takes a value and prepares it to be placed as a Logical Minimum entry into a HID report stru
184. dition USBHKeyboardOpen This function is used open an instance of a keyboard Prototype unsigned long USBHKeyboardOpen tUSBCallback pfnCallback unsigned char xpucBuffer unsigned long ulSize September 05 2012 4 7 2 5 4 7 2 6 Host Functions Parameters pfnCallback is the callback function to call when new events occur with the keyboard returned pucBuffer is the memory used by the keyboard to interact with the USB keyboard ulSize is the size of the buffer provided by pucBuffer Description This function is used to open an instance of the keyboard The value returned from this function should be used as the instance identifier for all other USBHKeyboard calls The pucBuffer memory buffer is used to access the keyboard The buffer size required is at least enough to hold a normal report descriptor for the device If there is not enough space only a partial report descriptor will be read out Returns Returns the instance identifier for the keyboard that is attached If there is no keyboard present this will return 0 USBHKeyboardPollRateSet This function is used to set the automatic poll rate of the keyboard Prototype unsigned long USBHKeyboardPollRateSet unsigned long ulInstance unsigned long ulPollRate Parameters ullnstance is the instance value for this keyboard ulPollRate is the rate in ms to cause the keyboard to update the host regardless of no change in key state Description Th
185. dle unsigned char pcData unsigned long ulLength tBoolean bLast September 05 2012 39 General Purpose Functions 2 4 6 2 4 6 1 2 4 6 2 40 Description A function pointer type which describes either a class driver packet read or packet write function both have the same prototype to the USB buffer object Function Documentation USBBufferCallbackDataSet Sets the callback pointer supplied to clients of this buffer Prototype void USBBufferCallbackDataSet tUSBBuffer xpsBuffer void xpvCBData Parameters psBuffer is the pointer to the buffer instance whose callback data is to be changed pvCBDaia is the pointer the client wishes to receive on all future callbacks from this buffer Description This function sets the callback pointer which this buffer will supply to clients as the pvCBData parameter in all future calls to the event callback Note If this function is to be used the application must ensure that the tUSBBuffer structure used to describe this buffer is held in RAM rather than flash The pvCBData value passed is written directly into this structure Returns Returns the previous callback pointer set for the buffer USBBufferDataAvailable Returns the number of bytes of data available in the buffer Prototype unsigned long USBBufferDataAvailable const tUSBBuffer xpsBuffer Parameters psBuffer is the pointer to the buffer instance which is to be queried Description This func
186. e g_pStringDescriptors The number of entries in your string table This must equal 1 5 num languages NUM_STRING_DESCRIPTORS A pointer to the private instance data allocated for the API to use amp g sMouseInstance Add a mouse event handler function YourMouseHandler in the previous example to your ap plication A minimal implementation can ignore all events though USB_EVENT_TX_COMPLETE can be used to ensure that mouse messages are not sent when a previous report is still in transit to the host Attempts to send a new mouse report when the previous report has not yet been acknowledged will result in return code MOUSE_ERR_TX_ERROR from USBDHIDMous eStateChange From your main initialization function call the HID mouse device API initialization function to configure the USB controller and place the device on the bus pDevice USBDHIDMouseInit 0 amp g_sMouseDevice Assuming pDevice returned is not NULL your mouse device is now ready to communicate with a USB host Once the host connects your mouse event handler will be sent USB_EVENT_CONNECTED after which calls can be made to USBDHIDMouseStateChange to inform the host of mouse position and button state changes 3 16 HID Mouse Device Class API Definitions Data Structures m tUSBDHIDMouseDevice 158 September 05 2012 3 16 1 3 16 2 3 16 2 1 Device Func
187. e Allocating Memory The USB composite device class requires three different types of memory allocated to properly enumerate and function with the included device classes The first is the simple instance data that is provided in the tCompositelnstance structure and is shown in the previous section This is a static allocation for the composite device instance and is used internally by the composite device class The second allocation is a block of memory that is used to build up the combined device configuration descriptor for the combination of the desired device classes The individual device classes will provide a size in a COMPOSITE SIZE macro that indicates the size in bytes required to hold the configuration descriptor for the device class This allows the application to provide a large enough buffer to the USBDCompositelnit function for merging the device descriptors The last type of allocation is any data that is needed by the individual device classes Each instance of each class will likely need some memory allocated separately to each instance of a device Defining Device Class Instances When defining a composite device the application must determine the size of the buffer that is passed into the USBDCompositelnit function For example if a composite device is made up of two serial devices then a buffer of size COMPOSITE DCDC SIZE x 2 should be passed into the initialization routine and an array of that size should be declared
188. e HID Keyboard Device Class API As with the HID Mouse Device Class API described above the HID Keyboard Device Class API provides an easy to use high level interface for applications wishing to appear to the USB host as a BIOS compatible keyboard The keyboard supports up to 6 simultaneously pressed non modifier keys and up to 5 state indication LEDs Key press and release notifications along with the state of the modifier keys Shift Ctrl Alt etc are passed to the API in a single API call and a callback informs the application whenever the host requests that the LED states be changed Keys are identified to the API by means of USB HID key usage codes A subset of these are defined in the header file usbhid h and the full set can be found in the doc ument Universal Serial Bus USB HID Usage Tables which can be downloaded from http www usb org developers devclass_docs Hut1_12 pdf September 05 2012 165 Device Functions USB HID Keyboard Device Model Event Callback p Key make break information USB Host USB Driver Interrupt IN A USB Device API HID Class Driver Application Code Endpoint 0 HID Keyboard Class Device API The usb_dev_keyboard example application makes use of this device class API 3 17 1 HID Keyboard Device API Events The HID keyboard device API sends the following events to the application callback function E USB EVENT CONNECTED
189. e Returns Not a function September 05 2012 147 Device Functions 3 14 3 37 UsageMinimum This is a macro to assist adding Usage Minimum entries in HID report descriptors Definition define UsageMinimum ucValue Parameters ucValue is the Usage Minimum value Description This macro takes a value and prepares it to be placed as a Usage Minimum entry into a HID report structure This is the first or minimum value associated with a usage value Returns Not a function 3 14 3 38 UsagePage This is a macro to assist adding Usage Page entries in HID report descriptors Definition define UsagePage ucValue Parameters ucValue is the Usage Page value Description This macro takes a value and prepares it to be placed as a Usage Page entry into a HID report structure These are defined by the USB HID specification Returns Not a function 3 14 3 39 USBD HID EVENT GET PROTOCOL Definition define USBD HID EVENT GET PROTOCOL Description This event is sent in response to a Get Protocol request from the host The callback should provide the current protocol via the return code USB HID PROTOCOL BOOT or USB HID PROTOCOL REPORT 3 14 3 40 USBD HID EVENT GET REPORT Definition define USBD HID EVENT GET REPORT 148 September 05 2012 Device Functions Description This event indicates that the host is requesting a particular report be returned via endpoin
190. e available at the time of this call this function returns zero USBHostAudioPlay This function is called to send an audio buffer to the USB audio device Prototype long USBHostAudioPlay unsigned long ulInstance void xpvBuffer unsigned long ulSize tUSBHostAudioCallback pfnCallback Parameters ullnstance specifies the device instance for this call pvBuffer is the audio buffer to send ulSize is the size of the buffer in bytes pfnCallback is a pointer to a callback function that is called when the buffer can be used again Description This function is called when an application needs to schedule a new buffer for output to the USB audio device Since this call schedules the transfer and returns immediately the application should provide a pfnCallback function to be notified when the buffer can be used again by the application The pfnCallback function provided is called with the pvBuffer parameter set to the pvBuffer provided by this call the u Param can be ignored and the u Event parameter is USB EVENT TX COMPLETE Returns This function returns the number of bytes that were scheduled to be sent If this function returns zero then there was no USB audio device present or the request could not be satisfied at this time USBHostAudioRecord This function is called to provide an audio buffer to the USB audio device for audio input Prototype long USBHostAudioRecord unsigned long ulInstance void xpvBuffe
191. e class drivers Device class drivers are currently provided to allow creation of a generic bulk device a Communi cation Device Class virtual serial port device and a Human Interface Device class device mouse keyboard joystick etc A special class driver for composite devices is also included This acts as a wrapper allowing multiple device class drivers to be used in a single device Detailed information on each of these classes can be found later in this document September 05 2012 3 2 4 3 3 Device Functions USB Device Class APIs In some cases a standard device class may offer the possibility of creating a great number of different and varied devices using the same class and in these cases an additional API layer can be provided to further specialize the device operation and simplify the interface to the application The Human Interface Device HID class is one such class It is used to support a wide variety of devices including keyboards joysticks mice and game controllers but the interface is specified in such a way that it could be used for a huge number of vendor specific devices offering data gathering capability As a result the HID device class driver is extremely general to allow support for as wide a range of devices as possible To simplify the use of the interface specific APIs are provided to support BIOS compatible keyboard and mouse operation Using the mouse class API instead of the base HID class driver A
192. e endpoint number ORed with flag USB_EP_DESC_OUT or USB_EP_DESC_IN to indicate the endpoint di rection bmAttributes The endpoint transfer type USB_EP_ATTR_CONTROL USB_EP_ATTR_ISOC USB EP ATTR BULK or USB EP ATTR INT and if isochronous additional flags indicating usage type and synchronization method wMaxPacketSize The maximum packet size this endpoint is capable of sending or receiving when this configuration is selected For high speed isochronous or interrupt endpoints bits 11 and 12 are used to pass additional information binterval The polling interval for data transfers expressed in frames or micro frames depend ing upon the operating speed Description This structure describes the USB endpoint descriptor as defined in USB 2 0 specification sec tion 9 6 6 2 3 2 6 tlnterfaceDescriptor Definition typedef struct unsigned char bLength unsigned char bDescriptorType unsigned char bInterfaceNumber unsigned char bAlternateSetting unsigned char bNumEndpoints 30 September 05 2012 2 3 2 7 General Purpose Functions unsigned char bInterfaceClass unsigned char bInterfaceSubClass unsigned char bInterfaceProtocol unsigned char ilInterface tInterfaceDescriptor Members bLength The length of this descriptor in bytes All interface descriptors are 9 bytes long bDescriptorType The type of the descriptor For an interface descriptor this will be USB_DTYPE_INTERFACE 4 binterfaceNumber The numbe
193. e for the mass storage class device to initialized basic operation and prepare for enumeration Prototype void USBDMSCInit unsigned long ulIndex const tUSBDMSCDevice xpsDevice Parameters ullndex is the index of the USB controller to initialize for mass storage class device operation September 05 2012 Device Functions psDevice points to a structure containing parameters customizing the operation of the mass storage device Description In order for an application to initialize the USB device mass storage class it must first call this function with the a valid mass storage device class structure in the psDevice parameter This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB mass storage device This function returns a void pointer that must be passed in to all other APIs used by the mass storage class See the documentation on the tUSBDMSCDevice structure for more information on how to properly fill the structure members Returns Returns 0 on failure or a non zero void pointer on success 3 20 4 8 USBDMSOCMediaChange This function is used by an application if it can detect insertion or removal of the media Prototype void USBDMSCMediaChange void xpvInstance tUSBDMSCMediaStatus eMediaStatus Parameters pvinstance is the mass storage device instance that had a media change eMediaStatus is the updated status for the media Descri
194. e generic mass storage device information psCompEntries 0 psDevice g sMSCDeviceInfo Save the instance data for this mass storage device psCompEntries 0 pvInstance USBDAudioCompositeInit 0 amp g sMSCDevice Initialize other devices to add to the composite device ff Save the device entries in the composite device g_sCompDevice psDevices psCompEntries USBDCompositeInit 0 amp g sCompDevice DESCRIPTOR DATA SIZE g pucDescriptorData All other API calls to the USB mass storage device class should use the value returned by US BDAudioCompositelnit when the API calls for a pvlnstance pointer Also when using the audio device in a composite device the COMPOSITE DMSC SIZE value should be added to the size of the g pucDescriptorData array as shown in the example above 180 September 05 2012 Device Functions 3 20 Mass Storage Device Class API Definitions Data Structures m tMSCDMedia m tUSBDMSCDevice Defines m COMPOSITE DMSC SIZE m USBD MSC EVENT IDLE m USBD MSC EVENT READING m USBD MSC EVENT WRITING Functions m void x USBDMSCCompositelnit unsigned long ullndex const tUSBDMSCDevice psDevice m void x USBDMSCInit unsigned long ullndex const tUSBDMSCDevice psDevice m void USBDMSCMediaChange void pvlnstance tUSBDMSCMediaStatus eMediaStatus m void USBDMSCTerm void pvInstance 3 20 1 Detailed Description The macros and functions defined i
195. e is the number of items in a report item Description This macro takes a value and prepares it to be placed as a Report Count entry into a HID report structure This is number of entries of Report Size for a given item Returns Not a function 3 14 3 15 ReportlD This is a macro to assist adding Report ID entries in HID report descriptors Definition define ReportID ucValue Parameters ucValue is the identifier prefix for the current report Description This macro takes a value and prepares it to be placed as a Report ID entry into a HID report structure This value is used as a 1 byte prefix for the report it is contained within Returns Not a function 3 14 3 16 ReportSize This is a macro to assist adding Report Size entries in HID report descriptors Definition define ReportSize ucValue Parameters ucValue is the size in bits of items in a report item Description This macro takes a value and prepares it to be placed as a Report Size entry into a HID report structure This is size in bits of the entries of of a report entry The Report Count specifies how many entries of Report Size are in a given item These can be individual bits or bit fields Returns Not a function 3 14 3 17 Unit This is a macro to assist adding Unit entries for uncommon units in HID report descriptors September 05 2012 143 Device Functions Definition define Unit ulValue Parameters ulValue is the definit
196. e mass storage class driver ff g ulAudioInstance USBHostAudioOpen 0 AudioCallback Audio output is handled by setting the format of the audio stream and then by calling the USB HostAudioPlay function to provide new buffers to the audio device The callback function that is provided with this call returns the buffers when the driver is no longer using them In order for audio output to start the application must first set the audio format with a successful call to USBHostAu dioFormatSet If the format was not supported by the audio device then this function returns a non zero value and USBHostAudioPlay should not be called until a valid format is selected Once a valid format is set the application should provide audio data to the host audio driver by calling USBHostAudioPlay and then always waiting for the callback to indicate that the buffer has been released Calling the USBHostAudioPlay function before the previous buffer has been released can cause the previous transfer to be interrupted or canceled Since the USB host audio driver provides limited buffering it is up to the application to have data ready for output The application can safely call USBHostAudioPlay function directly from the callback function to provide a new buffer to the USB audio device Example Audio Output void AudioOutCallback void pvBuffer unsigned long ulParam unsigned long ulEvent 24 Check if this was a buffer free event and provide a
197. e power status is being reported ucPower indicates the current power status either USB STATUS SELF PWR or USB STATUS BUS PWR Description Applications which support switching between bus or self powered operation should call this function whenever the power source changes to indicate the current power status to the USB library This information is required by the library to allow correct responses to be provided when the host requests status from the device Returns None USBDCDRemoteWakeupRequest Requests a remote wake up to resume communication when in suspended state Prototype tBoolean USBDCDRemoteWakeupRequest unsigned long ulIndex Parameters ullndex is the index of the USB controller that will request a bus wake up Description When the bus is suspended an application which supports remote wake up advertised to the host via the configuration descriptor may call this function to initiate remote wake up signaling September 05 2012 3 22 3 5 3 22 3 6 Device Functions to the host If the remote wake up feature has not been disabled by the host this will cause the bus to resume operation within 20mS If the host has disabled remote wake up false will be returned to indicate that the wake up request was not successful Returns Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previ
198. eaning that the USB library supports one hub and four other devices Cascaded USB hubs are not supported because the USB library only supports a sin gle instance of a USB hub The application level interface to the USB hub class consists of only an initialization function and requires no additional application level changes to handle any of the supported USB classes When USB hub support is enabled non hub devices can still be directly connected to the USB controller with no special handling by the application The next section cov ers the application interfaces to the USB hub class and the memory requirements when enabling the USB hub support Device Interface The application layer of the USB hub class driver provides functions that an application uses to configure or disable the USB hub class driver To initialize the USB hub class driver the application must call USBHHubOpen and provide it with a memory pool suitable to hold the configuration de scriptors of the maximum number of attached devices and a hub instance structure The memory pool allocation is very similar to how an application provides memory to the USBHCDInit function with the exception that that the amount of memory should be multiplied by the number of devices supported This memory pool size should be the expected maximum configuration descriptor size multiplied by MAX USB DEVICES The application also provides a tHublInstance structure that holds private instance data that sh
199. eased USB HID Mouse Device Model Event Callback p Mouse position amp button information USB Host USB Driver Interrupt IN el USB Device API HID Class Driver Application Code Endpoint 0 HID Mouse Class Device API The usb_dev_mouse example application makes use of this device class API HID Mouse Device API Events The HID mouse device API sends the following events to the application callback function m USB EVENT CONNECTED September 05 2012 Device Functions USB_EVENT_DISCONNECTED USB_EVENT_TX_COMPLETE USB_EVENT_ERROR USB_EVENT_SUSPEND USB_EVENT_RESUME Note The USB_EVENT_DISCONNECTED event will not be reported to the application if the MCU s PB1 USBOVBUS pin is connected to a fixed 5 Volts rather than directly to the VBUS pin on the USB connector 3 15 2 Using the HID Mouse Device Class API To add a USB HID mouse interface to your application using the HID Mouse Device Class API take the following steps Add the following header files to the source file s which are to support USB include src usb h include usblib usblib h include usblib device usbdhidmouse h Define the string table which is used to describe various features of your new device to the host system An example of a suitable string table for a mouse device can be found in Using t
200. ed by USBDBulkinit pvCBDaia is the pointer that client wishes to be provided on each event sent to the transmit channel callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnTxCallback function passed on USBDBulklnit If a client wants to make runtime changes in the callback pointer it must ensure that the pv n stance structure passed to USBDBulklnit resides in RAM If this structure is in flash callback pointer changes will not be possible Returns Returns the previous callback pointer that was being used for this instance s transmit callback USBDBulkTerm Shut down the bulk device Prototype void USBDBulkTerm void xpvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDBUlklnit Description This function terminates device operation for the instance supplied and removes the device from the USB bus This function should not be called if the bulk device is part of a composite device and instead the USBDCompositeTerm function should be called for the full composite device Following this call the pvinstance instance should not me used in any other calls Returns None USBDBulkTxPacketAvailable Returns the number of free bytes in the transmit buffer Prototype unsigned long USBDBulkTxPacketAvailable void pvlInstance Parameters pvinstance is the pointer to
201. ed long ulBufferSize void xpvWorkspace tUSBBuffer Members bTransmitBuffer This field sets the mode of the buffer If true the buffer operates as a transmit buffer and supports calls to USBBufferWrite by the client If false the buffer operates as a receive buffer and supports calls to USBBufferRead pfnCallback A pointer to the callback function which will be called to notify the application of all asynchronous events related to the operation of the buffer pvCBData A pointer that the buffer will pass back to the client in the first parameter of all callbacks related to this instance pfnTransfer The function which should be called to transmit a packet of data in transmit mode or receive a packet in receive mode pfnAvailable The function which should be called to determine if the endpoint is ready to accept a new packet for transmission in transmit mode or to determine the size of the buffer required to read a packet in receive mode pvHandle The handle to pass to the low level function pointers provided in the pfn Transfer and pfnAvailable members For USB device use this is the psDevice parameter required by the relevant device class driver APIs For USB host use this is the pipe identifier returned by USBHCDPipeAlloc pcBuffer A pointer to memory to be used as the ring buffer for this instance ulBufferSize The size in bytes of the buffer pointed to by pcBuffer pvWorkspace A pointer to USB BUFFER WORKSPACE SIZE bytes
202. ed to create a configuration descriptor for a single instance of the USB Audio Device This does not include the configuration descriptor which is automatically ignored by the composite device class USB_AUDIO_INSTANCE_SIZE Definition define USB AUDIO INSTANCE SIZF Description This is the size in bytes of the private data for the device audio class USBD AUDIO EVENT ACTIVE Definition define USBD AUDIO EVENT ACTIVE Description This USB audio event indicates that the device is connected and is now active USBD AUDIO EVENT DATAOUT Definition define USBD AUDIO EVENT DATAOUT Description This USB audio event indicates that the device is returning a data buffer provided by the US BAudioBufferOut function back to the application with valid audio data received from the USB host controller The pvBuffer parameter holds the pointer to the buffer with the new audio data September 05 2012 65 Device Functions 3 4 3 5 3 4 3 6 3 4 3 7 3 4 4 3 4 4 1 66 and the u Param value holds the amount of valid data in bytes that are contained in the pvBuffer parameter USBD_AUDIO_EVENT_IDLE Definition define USBD_AUDIO_EVENT_IDLE Description This USB audio event indicates that the device is connected but not active USBD_AUDIO_EVENT_MUTE Definition define USBD AUDIO EVENT MUTE Description This USB audio event indicates
203. eived data will be written ulLength is the size of the buffer pointed to by pucData Description This function reads up to ulLength bytes of data received from the USB host into the supplied application buffer If the receive buffer contains fewer than u Length bytes of data the data that is present will be copied and the return code will indicate the actual number of bytes copied to pucData Returns Returns the number of bytes of data read USBBufferSpaceAvailable Returns the number of free bytes in the buffer Prototype unsigned long USBBufferSpaceAvailable const tUSBBuffer xpsBuffer Parameters psBuffer is the pointer to the buffer instance which is to be queried Description This function returns the number of free bytes in the buffer For a transmit buffer this indicates the maximum number of bytes that can be passed on a call to USBBufferWrite and accepted for transmission For a receive buffer it indicates the number of bytes that can be read from the USB controller before the buffer will be full Returns Returns the number of free bytes in the buffer USBBufferWrite Writes a block of data to the transmit buffer and queues it for transmission to the USB controller Prototype unsigned long USBBufferWrite const tUSBBuffer xpsBuffer September 05 2012 2 4 6 12 2 4 6 13 General Purpose Functions const unsigned char xpucData unsigned long ulLength Parameters psBuffer points to the point
204. emains to be read and allows the application to determine the buffer size needed to read the data Returns Returns 0 if no received packet remains unprocessed or the size of the packet if a packet is waiting to be read USBDBulkSetRxCBData Sets the client specific pointer parameter for the receive channel callback Prototype void x USBDBulkSetRxCBData void xpvInstance void xpvCBData Parameters pvinstance is the pointer to the device instance structure as returned by USBDBUlklnit pvCBDaia is the pointer that client wishes to be provided on each event sent to the receive channel callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnRxCallback function passed on USBDBulkInit If a client wants to make runtime changes in the callback pointer it must ensure that the pvin stance structure passed to USBDBulklnit resides in RAM If this structure is in flash callback pointer changes will not be possible Returns Returns the previous callback pointer that was being used for this instance s receive callback USBDBulkSetTxCBData Sets the client specific pointer parameter for the transmit callback Prototype void USBDBulkSetTxCBData void xpvInstance void xpvCBData September 05 2012 85 Device Functions 3 6 4 10 3 6 4 11 86 Parameters pvinstance is the pointer to the device instance structure as return
205. en ulLength is the number of bytes to be written Description This function write a sequence of bytes into a ring buffer Returns None USBRingBufWriteOne Writes a single byte of data to a ring buffer Prototype void USBRingBufWriteOne tUSBRingBufObject ptUSBRingBuf unsigned char ucData Parameters ptUSBRingBuf points to the ring buffer to be written to ucData is the byte to be written Description This function writes a single byte of data into a ring buffer Returns None September 05 2012 51 General Purpose Functions 52 September 05 2012 Device Functions 3 Device Functions IPR OOUCHON cranks ET AA ANT TAA ERER TEE keen bi Dod bala ub atu daii dau Ad Ext V cocci ri pd thee AERE EU d 53 API cues TUE USB GEN IEBS utis tuse RI bn Mp EIN ad ME mnm E 54 Ando Device Class DITE c pps IRE EFESMDP oe Ee dC NV RNC RERUM ERE 57 Audio Device Class Driver Definitions 0 0 ccc ccc cece nee tenn III mesa 63 Buk Devos Globe DWE sons cssat dare cole ea snee ede bbb rp ADEM ek be DENIED 69 Bulk Device Class Diver Delnil ore sss ee pn pEP PER Ra aiikeiivaehiecadd Ip ADD SP ERU EIFE Qr EODEM 79 CDG Device Class DINE uui cocsuesxar e eR Robbe ep EPA MR ERR ER ERR ERE E PRECES i eS 87 CDG Device Glass Driver DolnillollS 4221424 puxckhkbedpbbEbE ERE ER ER RICE UE OUR RCORUR HD RARE ARR EGRE Rel a 95 Composite Device Class DING 2222ceeiedun et eben RIS Ene Tni ERR R Pete eu ERU DRR RR ERE Pp iu
206. entry for temperature in Fahrenheit into a report descriptor 3 14 3 31 UnitTemp K Definition define UnitTemp K Description This macro inserts a Unit entry for temperature in Kelvin into a report descriptor 3 14 3 32 UnitTime s Definition define UnitTime s Description This macro inserts a Unit entry for seconds into a report descriptor 146 September 05 2012 Device Functions 3 14 3 33 UnitVelocityS Definition define UnitVelocitySI Description This macro inserts a Unit entry for velocity in cm s into a report descriptor 3 14 3 34 UnitVoltage Definition define UnitVoltage Description This macro inserts a Unit entry for voltage into a a report descriptor 3 14 3 35 Usage This is a macro to assist adding Usage entries in HID report descriptors Definition define Usage ucValue Parameters ucValue is the Usage value Description This macro takes a value and prepares it to be placed as a Usage entry into a HID report structure These are defined by the USB HID specification Returns Not a function 3 14 3 36 UsageMaximum This is a macro to assist adding Usage Maximum entries in HID report descriptors Definition define UsageMaximum ucValue Parameters ucValue is the Usage Maximum value Description This macro takes a value and prepares it to be placed as a Usage Maximum entry into a HID report structure This is the last or maximum value associated with a usage valu
207. ents relating to the buffer will be made by calls to this function pvCBData The callback data pointer written to this field will be passed as the first parameter on all future calls to the application event handler set in pfnCallback Typically an application will set this pointer to some value allowing it easy access to data associated with the channel for example a pointer to an internal instance data structure The actual content is application specific and the USB buffer merely stores the value and passes it back to the caller when required pfnTransfer This field informs the USB buffer of the function to call whenever data is to be transferred between the buffer and the lower layer This is used to transmit a packet of data if this is a transmit buffer bTransmitBuffer set to true or to receive a packet of data if this is a receive buffer bTrans mitBuffer set to false Taking the example of a buffer used to transmit data to the USB generic bulk device class driver this would be set to point to USBDBulkPacketWrite A receive buffer used with the same driver would have this field set to point to USBDBulkPacketRead September 05 2012 General Purpose Functions pfnAvailable For a transmit buffer this function pointer must be set to point to the lower layer function that can be called to determine whether the rele vant USB endpoint or pipe is ready to accept a new packet for transmis sion For a receive buffer this field points
208. equested interface 4 3 4 6 USBHCDDevProtocol Definition unsigned char USBHCDDevProtocol unsigned long ulInstance unsigned long ulInterface Description This function will return the USB protocol for the requested device instance Parameters ullnstance is a unique value indicating which device to query ullnterface is the interface number to query for the USB protocol This function returns the USB protocol for the device that is associated with the u Instance pa rameter The caller must use a value for u Instance have been passed to the application when it receives a USB EVENT CONNECTED event The function will return the USB protocol for the interface number specified by the ullnterface parameter If ullnterface is set to OXFFFFFFFF then the function will return the USB protocol for the first interface that is found in the device s USB descriptors Returns The USB protocol for the requested interface 218 September 05 2012 Host Functions 4 3 4 7 USBHCDDevSubClass Definition unsigned char USBHCDDevSubClass unsigned long ullnstance unsigned long ulInterface Description This function will return the USB subclass for the requested device instance Parameters ullnstance is a unique value indicating which device to query ullnterface is the interface number to query for the USB subclass This function returns the USB subclass for the device that is associated with the u Instance parameter The call
209. er instance into which data is to be written pucData points to the first byte of data which is to be written ulLength is the number of bytes of data to write to the buffer Description This function copies the supplied data into the transmit buffer The transmit buffer data will be packetized according to the constraints imposed by the lower layer in use and sent to the USB controller as soon as possible Once a packet is transmitted and acknowledged a USB EVENT TX COMPLETE event will be sent to the application callback indicating the number of bytes that have been sent from the buffer Attempts to send more data than there is space for in the transmit buffer will result in fewer bytes than expected being written The value returned by the function indicates the actual number of bytes copied to the buffer Returns Returns the number of bytes actually written USBBufferZeroLengthPacketlnsert Enables or disables zero length packet insertion Prototype void USBBufferZeroLengthPacketInsert const tUSBBuffer xpsBuffer tBoolean bSendZLP Parameters psBuffer is the pointer to the buffer instance whose information is being queried bSendZLP is true to send zero length packets or false to prevent them from being sent Description This function allows the use of zero length packets to be controlled by an application In cases where the USB buffer has sent a full 64 byte packet and then discovers that the transmit buffer is empty the
210. er must use a value for ullnstance have been passed to the application when it receives a USB EVENT CONNECTED event The function will return the USB sub class for the interface number specified by the ullnterface parameter If ullnterface is set to OxFFFFFFFF then the function will return the USB subclass for the first interface that is found in the device s USB descriptors Returns The USB subclass for the requested interface 4 3 4 8 USBHCDEventDisable Definition long USBHCDEventDisable unsigned long ulIndex void pvEventDriver unsigned long ulEvent Description This function is called to disable a specific USB HCD event notification Parameters ullndex specifies which USB controller to use pvEventDriver is the event driver structure that was passed into the USBHCDRegister Drivers function as part of the array of tUSBHostClassDriver structures ulEvent is the event to disable This function is called to disable event callbacks for a specific USB HCD event The requested event is passed in the u Event parameter Not all events can be enables so the function will return zero if the event provided cannot be enabled The pvEventDriver is a pointer to the event driver structure that the caller passed into the USBHCDRegisterDrivers function This structure is typically declared with the DECLARE EVENT DRIVER macro and included as part of the array of pointers to tUSBHostClassDriver structures that is passed to the USB
211. ered operation should call this function whenever the power source changes to indicate the current power status to the USB library This information is required by the USB library to allow correct responses to be provided when the host requests status from the device Returns None USBDHIDMouseRemoteWakeupRequest Requests a remote wake up to resume communication when in suspended state Prototype tBoolean USBDHIDMouseRemoteWakeupRequest void xpvInstance Parameters pvinstance is the pointer to the mouse device instance structure Description When the bus is suspended an application which supports remote wake up advertised to the host via the configuration descriptor may call this function to initiate remote wake up signaling to the host If the remote wake up feature has not been disabled by the host this will cause the bus to resume operation within 20mS If the host has disabled remote wake up false will be returned to indicate that the wake up request was not successful Returns Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previous call to this function USBDHIDMouseSetCBData Sets the client specific pointer parameter for the mouse callback Prototype void USBDHIDMouseSetCBData void xpvInstance void xpvCBData September 05 2012 163 Device Functions Parameters pvinstance
212. erface The u Channel value starts with O which is the master audio volume control interface The remaining u Channel values provide access to various other audio channels with 1 and 2 being left and right audio channels Note On devices that do not support volume control interfaces this call returns 0 indicating a Odb setting Returns Returns the maximum volume setting for the requested interface USBHostAudioVolumeMinGet This function is used to get the minimum volume setting for a given audio device Prototype unsigned long USBHostAudioVolumeMinGet unsigned long ulInstance unsigned long ullInterface unsigned long ulChannel Parameters ullnstance is an instance of the USB audio device ullnterface is the interface number to use to query the minimum volume control value ulChannel is the 0 based channel number to query Description The function is used to retrieve the minimum volume setting for an audio device on the channel specified by ulChannel The ullnterface is ignored for now and should be set to 0 to access the default audio control interface The u Channe value starts with 0 which is the master audio volume control interface The remaining u Channel values provide access to various other audio channels with 1 and 2 being left and right audio channels Note On devices that do not support volume control interfaces this call returns 0 indicating a Odb setting Returns Returns the minimum volume setting
213. es which USB power configuration to use This function will set the current power control pin configuration as set by the USBHCDPow erConfiglnit function or the defaults if not yet set See the USBHCDPowerConfigInit docu mentation for the meaning of the bits that are set by this function Returns Returns zero to indicate the power setting is now active 4 3 4 6 USBHCDhRegisterDrivers Definition void USBHCDRegisterDrivers unsigned long ullndex const tUSBHostClassDriver xconst xppHClassDrvs unsigned long ulNumDrivers Description This function is used to initialize the HCD class driver list Parameters ullndex specifies which USB controller to use ppHClassDrvs is an array of host class drivers that are supported on this controller ulNumDrivers is the number of entries in the pHostClassDrivers array This function will set the host classes supported by the host controller specified by the ullndex parameter This function should be called before enabling the host controller driver with the USBHCDInit function Returns None 4 3 4 27 USBHCDReset Definition void USBHCDReset unsigned long ulIndex Description This function generates reset signaling on the USB bus Parameters ullndex specifies which USB controller to use This function handles sending out reset signaling on the USB bus After returning from this function any attached device on the USB bus should have returned to it s reset s
214. et 0 i J kk kk kk ke kk koe kk koc kk ck ee eee Ce ee eee ee ee ee ee ee eee eee eee eee ee ck ck ckckck eee es The serial number string TKR kk ko ke kk ko ok kk Kok kk Kok kk Kok kk Kok OR ORR kk kk OR IR IR IR IR IR I AI A ke e ke e ke const unsigned char g pSerialNumberString 8 1 2 USB DTYPE STRING DL VC DE te V Ui ate gs uu Astro Uu Ae Un ptu dro DV Heg de J kk OK ROK RR kk Kok kk Kok kk Kok OR kk ko ke kk kk kk ko ko IR KR IR IR IR I AI I A ek e oe The interface description string J kk kk kk KR KR RR IR I RI IR I IR IR IR I I OK ok const unsigned char g_pHIDInterfaceString X9 Eh x2 USB DTYPE STRING Te gi SEE ee SDS SOG ee S Quo OD Def DW y 3s Sr Oy fab Dip o fud tL D cumst cU Vtt Op Tet OQ Ux V REC S tata Op Vets 10 ek eo 0 J f kk kk ko ke kk oko kk Kok kk Kok kk Kok kk Kok kk ko ke kk kk kk koe kk kk kk kk kk ko Kk kk IR ko kk koe kk Kok ko kk ke ke ke e ee The configuration description string J kk KK RR A A RR RI IR IR IR IR IR I OR ck ck ck kok const unsigned char g_pConfigString 23 1 4 2 USB DTYPE STRING Ag Op AE Oi DE COSS uoa EME SOG tots Dig ta oy stis 0 feta fitu iu tO 0s hop n u Ou ECL OP ILES Ok g 7 ea Oy CEA pati Ope Tb Uus DAP Uy Ot L0 omes 20 un J kk kk RRR kk Kok kk Kok kk Kok kk Kok kk koe kk koe kk kk IR IR ok kk kk kk I kk ko koc kk ko ke kk Kok kk ko ke ke ke e ee The
215. ex 0 as defined in USB 2 0 specifi cation section 9 6 7 Note that the number of language IDs is variable and can be determined by examining bLength The number of language IDs present in the descriptor is given by DLength 2 2 September 05 2012 31 General Purpose Functions 2 3 2 8 2 3 2 9 32 tStringDescriptor Definition typedef struct unsigned char bLength unsigned char bDescriptorType unsigned char bString tStringDescriptor Members bLength The length of this descriptor in bytes This value will be 2 greater than the number of bytes comprising the UNICODE string that the descriptor contains bDescriptorType The type of the descriptor For a string descriptor this will be USB DTYPE STRING 3 bString The first byte of the UNICODE string This string is not NULL terminated Its length in bytes can be computed by subtracting 2 from the value in the bLength field Description This structure describes the USB string descriptor for all string indexes other than 0 as defined in USB 2 0 specification section 9 6 7 tUSBRequest Definition typedef struct unsigned char bmRequestType unsigned char bRequest unsigned short wValue unsigned short wIndex unsigned short wLength tUSBRequest Members bmRequestType Determines the type and direction of the request bRequest Identifies the specific request being made wValue Word sized field that varies according to the request windex
216. fReadOne Reads a single byte of data from a ring buffer Prototype unsigned char USBRingBufReadOne tUSBRingBufObject ptUSBRingBuf September 05 2012 49 General Purpose Functions 2 4 6 24 2 4 6 25 2 4 6 26 50 Parameters ptUSBRingBuf points to the ring buffer to be written to Description This function reads a single byte of data from a ring buffer Returns The byte read from the ring buffer USBRingBufSize Returns the size in bytes of a ring buffer Prototype unsigned long USBRingBufSize tUSBRingBufObject xptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to check Description This function returns the size of the ring buffer Returns Returns the size in bytes of the ring buffer USBRingBufUsed Returns number of bytes stored in ring buffer Prototype unsigned long USBRingBufUsed tUSBRingBufObject ptUSBRingBuf Parameters ptUSBRingBuf is the ring buffer object to check Description This function returns the number of bytes stored in the ring buffer Returns Returns the number of bytes stored in the ring buffer USBRingBufWrite Writes data to a ring buffer September 05 2012 2 4 6 27 General Purpose Functions Prototype void USBRingBufWrite tUSBRingBufObject ptUSBRingBuf const unsigned char pucData unsigned long ulLength Parameters ptUSBRingBuf points to the ring buffer to be written to pucData points to the data to be writt
217. fer directly Returns None USBBufferDataWritten Indicates that a client has written data directly into the buffer and wishes to start transmission Prototype void USBBufferDataWritten const tUSBBuffer xpsBuffer unsigned long ulLength Parameters psBuffer is the pointer to the buffer instance into which data has been written ulLength is the number of bytes of data that the client has written Description This function updates the USB buffer write pointer and starts transmission of the data in the buffer assuming the lower layer is ready to receive a new packet The function is provided to aid a client wishing to write data directly into the USB buffer rather than using the USBBufferWrite function This may be necessary to control when the USB buffer starts transmission of a large block of data for example A transmit buffer will immediately send a new packet on any call to USBBufferWrite if the un derlying layer indicates that a transmission can be started In some cases this is not desirable and a client may wish to write more data to the buffer in advance of starting transmission to the lower layer In such cases USBBufferlnfoGet may be called to retrieve the current ring buffer indices and the buffer accessed directly Once the client has written all data it wishes to send taking care to handle the ring buffer wrap it should call this function to indicate that transmission may begin September 05 2012 41
218. for the requested interface September 05 2012 259 Host Functions 4 5 4 26 4 5 4 27 260 USBHostAudioVolumeResGet This function is used to get the volume control resolution for a given audio device Prototype unsigned long USBHostAudioVolumeResGet unsigned long ulInstance unsigned long ullInterface unsigned long ulChannel Parameters ullnstance is an instance of the USB audio device ullnterface is the interface number to use to query the resolution for the volume control ulChannel is the 0 based channel number to query Description The function is used to retrieve the volume control resolution for an audio device on the channel specified by u Channel The ullnterface is ignored for now and should be set to 0 to access the default audio control interface The ulChannel value starts with 0 which is the master audio volume control interface The remaining u Channel values provide access to various other audio channels with 1 and 2 being left and right audio channels Note On devices that do not support volume control interfaces this call returns 0 indicating a Odb setting Returns Returns the volume control resolution for the requested interface USBHostAudioVolumeSet This function is used to set the current volume setting for a given audio device Prototype void USBHostAudioVolumeSet unsigned long ulInstance unsigned ulInterface unsigned long ulChannel unsigned long ulValue Par
219. g_sCompDevice psDevices psCompEntries USBDCompositeInit 0 amp g sCompDevice DESCRIPTOR DATA SIZE g pucDescriptorData All other API calls to the USB CDC serial device class should use the value returned by USBD CDCCompositelnit when the API calls for a pvInstance pointer Also when using the CDC serial device in a composite device the COMPOSITE DCDC SIZE value should be added to the size of the g pucDescriptorData array as shown in the example above Windows Drivers for CDC Serial Devices Making your CDC serial device visible as a virtual COM port on a Windows system is very straight forward since Windows already includes a device driver supporting USB CDC devices The device developer must merely provide a single INF file to associate the VID and PID of the new device with the Windows USB CDC driver usbser sys When using the serial device in a composite device itis important to remember to append amp MI xx value to the VID PID entry as shown in the example below The actual number used with the MI value is the interface number assigned to the serial device An example INF file is provided below Unlike the case for the generic bulk device class no additional installation files are necessary since the CDC serial driver is already installed by default and does not therefore have to be redistributed by the device developer Texas Instruments Stellaris USB CDC serial driver installation file Version Signature
220. h void USBBufferDataWritten const tUSBBuffer psBuffer unsigned long ulLength unsigned long USBBufferEventCallback void pvCBData unsigned long ulEvent unsigned long ulMsgValue void pvMsgData void USBBufferFlush const tUSBBuffer psBuffer void USBBufferlnfoGet const tUSBBuffer psBuffer tUSBRingBufObject psRingBuf September 05 2012 2 4 1 General Purpose Functions const tUSBBuffer USBBufferlnit const tUSBBuffer psBuffer unsigned long USBBufferRead const tUSBBuffer psBuffer unsigned char pucData un signed long ulLength unsigned long USBBufferSpaceAvailable const tUSBBuffer psBuffer unsigned long USBBufferWrite const tUSBBuffer psBuffer const unsigned char pucData unsigned long ulLength void USBBufferZeroLengthPacketlnsert const tUSBBuffer psBuffer tBoolean bSendZLP void USBRingBufAdvanceRead tUSBRingBufObject ptUSBRingBuf unsigned long ulNum Bytes m void USBRingBufAdvanceWrite tUSBRingBufObject ptUSBRingBuf unsigned long ulNum Bytes unsigned long USBRingBufContigFree tUSBRingBufObject ptUSBRingBuf unsigned long USBRingBufContigUsed tUSBRingBufObject ptUSBRingBuf tBoolean USBRingBufEmpty tUSBRingBufObject ptUSBRingBuf void USBRingBufFlush tUSBRingBufObject ptUSBRingBuf unsigned long USBRingBufFree tUSBRingBufObject ptUSBRingBuf tBoolean USBRingBufFull tUSBRingBufObject ptUSBRingBuf void USBRingBuflnit tUSBRingBufObject ptUSBRingBuf un
221. hanged This assumption is valid if the USB controller was initialized using a previous call to USBDCDConfig In reconfiguring the interface endpoints any additional configuration bits set in the endpoint configuration other than the direction USB EP DEV IN or USB EP DEV OUT and mode USB EP MODE MASK are preserved Returns 206 Returns true on success or false on failure September 05 2012 Device Functions 3 22 4 Variable Documentation 3 22 4 1 g sUSBDefaultFIFOConfig Definition const tFIFOConfig g sUSBDefaultFIFOConfig Description The default USB endpoint FIFO configuration structure This structure contains definitions to set all USB FIFOs into single buffered mode with no DMA use Each endpoint s FIFO is sized to hold the largest maximum packet size for any interface alternate setting in the current configuration descriptor A pointer to this structure may be passed in the psFIFOConfig field of the tDevicelnfo structure passed to USBCDOInit if the application does not require any special handling of the USB controller FIFO September 05 2012 207 Device Functions 208 September 05 2012 4 4 1 Host Functions Host Functions IP OOUGHIN alea aicut Rog aA RO aa ciat dal etico Red utili dines ERE causato E Ran td 209 as canadier DEDE eiu eina debi p PI EORR Edd oca Iesu E MELOS IE 211 Host Controller Driver DefinilliIGPIB i LL ELE p EEXGFREUREG Gp YR PU RR nte e PRI EEEPPLAM RR RREIDPNER ERES 213 Hos
222. he HID Device Class Driver This table must include a minimum of 6 entries string descriptor 0 defining the language s available and 5 strings for each supported language Define an area of RAM of for the private data for the HID mouse class driver This structure should never be accessed by the application J kk Ck e eee eC eee ee ee eS eee ee ee ee eee ee ee ee ee ee eee ee kckck ck kckckckckck ck ckck ck ck oko The HID mouse device private instance data J kk kk Sk ROKR RR RR RR kk ko ke ke kk ke kk Kk kk ko ko OR OR IR I OR IR ke kk A I I oe static tHIDMouseInstance g sMouseInstance Define a tUSBDHIDMouseDevice structure and initialize all fields as required for your appli cation const tUSBDHIDMouseDevice g sMouseDevice The Vendor ID you have been assigned by USB IF USB_VID_YOUR_VENDOR_ID The product ID you have assigned for this device T USB PID YOUR PRODUCT ID The power consumption of your device in milliamps POWER_CONSUMPTION_mA September 05 2012 157 Device Functions The value to be passed to the host in the USB configuration descriptor s bmAttributes field USB_CONF_ATTR_SELF_PWR A pointer to your mouse callback event handler YourMouseHandler A value that you want passed to the callback alongside every event leh void amp g_sYourInstanceData A pointer to your string tabl
223. he USB boot loader via the USBDDFUUpdateBegin function This function removes the application s existing device from the USB bus then reenters the boot loader which in turn publishes DFU mode descriptors and reconnects to the bus as a pure DFU device capable of downloading or uploading application images from the host Using the DFU Device Class The boot_demo_usb application provides an example of an application using the Device Firmware Upgrade class To support DFU in your application do the following 1 Ensure that your application is built to run alongside the USB boot loader boot_usb This requires that it is linked to run from the address defined in label APP_START_ADDRESS defined in the b1_config h used to build the boot loader Typically for the USB boot loader this will be 0x1800 2 Add a function to your application following the prototype unsigned long DFUDetachCallback void xpvCBData unsigned long ulEvent unsigned long ulMsgData void pvMsgData This function need only check ulEvent and if it is USBD_DFU_EVENT_DETACH signal the application main loop that it should exit and pass control back to the USB boot loader in preparation for a firmware upgrade 3 Add a mechanism in your application main loop to detect the signal set in your DFUDetach Callback function and call the USBDDFUUpdateBegin function This function tidies up and passes control to the boot loader 4 Define a structure of
224. he flash drive Since some flash drives require some setup time after enumeration before they are ready for drive access the mass storage class driver provides the USBHMSCDriveReady function to check if the drive is ready for normal operation The mass storage host class driver also provides an interface to the USB library host controller driver to complete enumeration of mass storage class devices The mass storage class driver information is held in the global structure g USBMSCClassDriver This structure should only be referenced by the application and the function pointers in this structure should never called directly by anything other than the host controller driver The USBHMSCOpen and USBHMSCClose provide the interface for the host controller s enumeration code to call when a mass storage class device is detected or removed It is up to the mass storage host class driver to provide a callback to the file system or application for notification of the drive being removed or added To make the the mass storage class driver visible to the host controller driver it must be added in the list of drivers provided in the USBHCDRegisterDrivers function call The class enumeration constant is set to USB_CLASS_MASS_STORAGE so any devices enumerating with value loads this class driver Device Interface This next section covers how an application or file system interacts with the host mass storage class driver provided with the USB library The app
225. he host controller The ulSize has a mini mum value of ISOC OUT EP MAX SIZE since each USB packet can be at most ISOC OUT EP MAX SIZE bytes in size Since the audio data may not be received in amounts that evenly fit in the buffer provided the buffer may not be completely filled The pf nCallback function will provide the amount of valid data that was actually stored in the buffer provided The function will return zero if the buffer could be scheduled to be filled otherwise the function will return a non zero value if there was some reason that the buffer could not be added Returns Returns 0 to indicate success any other value indicates that the buffer will not be filled USBDAudioCompositelnit This function should be called once for the audio class device to initialized basic operation and prepare for enumeration Prototype void USBDAudioCompositelInit unsigned long ulIndex const tUSBDAudioDevice xpsDevice Parameters ullndex is the index of the USB controller to initialize for audio class device operation psDevice points to a structure containing parameters customizing the operation of the audio device Description In order for an application to initialize the USB audio device class it must first call this function with the a valid audio device class structure in the psDevice parameter This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a
226. he ucButtons parameter to USBDHIDMouseStateChange indicates to the USB host that button 3 on the mouse is pressed MOUSE SUCCESS Definition define MOUSE_SUCCESS Description This return code from USBDHIDMouseStateChange indicates success Function Documentation USBDHIDMouseCompositelnit Initializes HID mouse device operation for a given USB controller Prototype void x USBDHIDMouseCompositelInit unsigned long ulIndex const tUSBDHIDMouseDevice psDevice September 05 2012 161 Device Functions 3 16 4 2 3 16 4 3 162 Parameters ullndex is the index of the USB controller which is to be initialized for HID mouse device operation psDevice points to a structure containing parameters customizing the operation of the HID mouse device Description This call is very similar to USBDHIDMouselnit except that it is used for initializing an instance of the HID mouse device for use in a composite device Returns Returns zero on failure or a non zero instance value that should be used with the remaining USB HID Mouse APIs USBDHIDMouselnit Initializes HID mouse device operation for a given USB controller Prototype void x USBDHIDMouseInit unsigned long ulIndex const tUSBDHIDMouseDevice xpsDevice Parameters ullndex is the index of the USB controller which is to be initialized for HID mouse device operation psDevice points to a structure containing parameters customizing the ope
227. he ullnstance value that is used with this call is the value that was returned from the USBHostAudioOpen function The application can use this call to insure that the audio format is supported and set the format at the same time If the application is just checking for supported rates then it should call the USBHostAudioFormatGet Note This function must be called before attempting to send or receive audio with the USBHostAu dioPlay or USBHostAudioRecord functions Returns A non zero value indicates the supplied format is not supported and a zero value indicates that the format was supported and has been configured USBHostAudioOpen This function should be called before any devices are present to enable the host audio class driver Prototype unsigned long USBHostAudioOpen unsigned long ulIndex tUSBHostAudioCallback pfnCallback Parameters ullndex is the audio device to open currently only 0 is supported pfnCallback is the driver call back for host audio events September 05 2012 4 5 4 21 4 5 4 22 Host Functions Description This function is called to open an instance of a host audio device and should provide a valid callback function for host audio events in the pfnCallback parameter This function must be called before the USB host code can successfully enumerate an audio device Returns This function returns the driver instance to use for the other host audio functions If there is no instanc
228. his requires parsing the endpoint descriptors for a device s endpoints and then allocating the USB pipes based on the types and number of endpoints discover The host class drivers provided with the USB library demonstrate how to parse and allocate USB pipes This call is not at made interrupt level so it can be interrupted by other USB events Anything that must be done immediately before any other communications with the device should be done in the pfnOpen function The pfnOpen member should should return a handle that is passed to the remaining functions pfnClose and pfnintHandler This handle should enable the host class driver to differentiate between different instances of the same type of device The value returned can be any value as the USB library simply returns it unmodified to the other host class driver functions The pfnClose structure member is called when the device that was created with pfnOpen call is removed from the system All driver clean up should be done in the pfnClose call as no more calls are made to the host class driver If the host class driver needs to respond to USB interrupts an optional pfnintHandler function pointer is provided This function runs at interrupt time and called for any interrupt that occurs due to this device or for generic USB events This function is not required and should only be implemented if it is necessary It is completely up to the custom USB host class driver to determine it s own upper layer interf
229. host class drivers provided by the application in the USBHCDRegisterDrivers call The details of this structure are covered in the host class drivers section of this document If the host controller driver finds a host class driver that matches the class of the enumerated device it calls the open function for that host class driver If no host class driver is found the host controller driver ignores the device and there is no notification to the application The host controller driver or the host class driver can provide callbacks up through the USB library to inform the application of enumeration events The host class drivers are respon sible for configuring the USB pipes based on the type of device that is discovered The application is notified of events in two ways one is from the host class driver for the connected device and the other is from a non device specific event driver The class specific events come from the host class driver while the generic connection power and other non device class specific events come from the host event driver if it is included in the application The section USB Events Driver covers the host events driver the valid events and how to include the host events driver in an application USB Pipes The host controller driver layer uses interfaces called USB pipes as the primary method of commu nications with USB devices These USB pipes can be dynamically allocated or statically allocated by the USB class driver
230. ication buffer If the driver detects that the entire packet has been read it is acknowledged to the host The bLast parameter is ignored in this implementation since the end of a packet can be deter mined without relying upon the client to provide this information Returns Returns the number of bytes of data read USBDBulkPacketWrite Transmits a packet of data to the USB host via the bulk data interface Prototype unsigned long USBDBulkPacketWrite void pvInstance unsigned char pcData unsigned long ulLength tBoolean bLast Parameters pvinstance is the pointer to the device instance structure as returned by USBDBulkinit pcData points to the first byte of data which is to be transmitted ulLength is the number of bytes of data to transmit bLast indicates whether more data is to be written before a packet should be scheduled for transmission If true the client will make a further call to this function If false no further call will be made and the driver should schedule transmission of a short packet Description This function schedules the supplied data for transmission to the USB host in a single USB packet If no transmission is currently ongoing the data is immediately copied to the relevant USB endpoint FIFO for transmission Whenever a USB packet is acknowledged by the host a USB EVENT TX COMPLETE event will be sent to the transmit channel callback indicating that more data can now be transmitted
231. ice and free up the buffer that it passed to the mouse device Keyboard Device Like the mouse the HID keyboard device interface is controlled mainly through a callback function that is provided as part of the call to open the keyboard device interface In order to open an in stance of the keyboard device the application calls USBHKeyboardOpen and passes in a callback September 05 2012 267 Host Functions 4 7 268 function as well as some buffer data for use by the keyboard device The buffer provided is used internally by the keyboard device and should not be used by the application Once the device has been opened the application should wait fora USB_EVENT_CONNECTED event to indicate that a keyboard has been successfully detected and enumerated At this point the application should call the USBHKeyboardlnit function to initialize the actual keyboard device that is connected After this the application can expect to receive the following events via the callback that was provided in the USBHKeyboardOpen call m USBH EVENT HID KB PRESS m USBH EVENT HID KB REL m USBH EVENT HID KB MOD USBH EVENT HID KB PRESS The ulMsgParam parameter has the USB usage identifier for the key that has been pressed It is up to the application to map this usage identifier to an actual printable character using the USBHKey boardUsageToChar function or it can simple respond to the key press without echoing the key to any output device It
232. id USBDCDCSetTxCBData void xpvInstance void xpvCBData Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDCInit pvCBDaia is the pointer that client wishes to be provided on each event sent to the transmit channel callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnTxCallback function passed on USBDCDClnit If a client wants to make runtime changes in the callback pointer it must ensure that the psCD CDevice structure passed to USBDCDGOInit resides in RAM If this structure is in flash call back data changes will not be possible September 05 2012 3 8 4 12 3 8 4 13 3 9 Device Functions Returns Returns the previous callback pointer that was being used for this instance s transmit callback USBDCDCTerm Shuts down the CDC device instance Prototype void USBDCDCTerm void xpvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDCInit Description This function terminates CDC operation for the instance supplied and removes the device from the USB bus This function should not be called if the CDC device is part of a composite device and instead the USBDCompositeTerm function should be called for the full composite device Following this call the pvinstance instance should not me used in any other calls Returns
233. igital GPIO_PORTH_BASE GPIO PIN 3 GPIO PIN 4 if Register the host class drivers USBHCDRegisterDrivers 0 g_ppUSBHostClassDrivers g_ulNumHostClassDrivers Call any open routines on the device class interfaces here so that they are ready to receive callbacks if the device is already inserted on power on Eg USBHMSCDriveOpen 0 MSCCallback Initialize the host controller USBHCDInit 0 g_pHCDPool HCD_MEMORY_SIZE 4 8 5 Host HID Mouse Programming Example The USB library HID mouse example provides support for HID mouse devices that support the USB HID mouse BIOS protocol Since most mice support the BIOS protocol nearly any mouse should be able to be connected and be supported The initial call to USBHMouseOpen prepares the mouse device application interface to receive notifications from any USB mouse device that is connected Since the mouse interface needs some basic configuration after being connected the application needs to wait for the mouse to be connected and then call the USBHMouselnit function to finish off the mouse configuration Example Mouse Configuration 276 Open an instance of the mouse driver The mouse does not need to be present at this time this just saves a place for it and allows the applications to be notified when a mouse is present g ulMouseInstance USBHMouseOpen MouseCallback g_pucBuffer 128 Main loop of application ff
234. ine the key board s layout and how it reports keys to the USB host controller The ullnstance value is the value that was returned when the application called USBHKeyboardOpen This func tion only needs to be called once per connection event but it should be called every time a USB EVENT CONNECTED event occurs Returns This function returns 0 to indicate success any non zero value indicates an error condition USBHKeyboardModifierSet This function is used to set one of the fixed modifier keys on a keyboard Prototype unsigned long USBHKeyboardModifierSet unsigned long ulInstance unsigned long ulModifiers Parameters ullnstance is the instance value for this keyboard ulModifiers is a bit mask of the modifiers to set on the keyboard Description This function is used to set the modifier key states on a keyboard The ulModifiers value is a bitmask of the following set of values HID KEYB NUM LOCK HID KEYB CAPS LOCK HID KEYB SCROLL LOCK HID KEYB COMPOSE HID KEYB KANA Not all of these will be supported on all keyboards however setting values on a keyboard that does not have them should have no effect The ullnstance value is the value that was returned when the application called USBHKeyboardOpen If the value HID KEYB CAPS LOCK is used it will modify the values returned from the USBHKeyboardUsage ToChar function Returns This function returns 0 to indicate success any non zero value indicates an error con
235. int zero state machine on behalf of the application September 05 2012 55 Device Functions 3 2 3 56 An application using this interface provides the descriptors that it wishes to publish to the host during initialization and these provide the information that the USB Device API requires to configure the hardware Asynchronous events relating to the USB device are notified to the application by means of a collection of callback functions also provided to the USB Device API on initialization This API is used in the development of USB device class drivers and can also be used directly by applications which want to provide USB functionality not supported by an existing class driver Examples of such devices would be those requiring complex alternate interface settings The USB Device API can be thought of as a set of high level device extensions to the USB DriverLib API rather than a wrapper over it When developing to the USB Device API some calls to the underlying USB DriverLib API are still necessary The header file for the USB Device API is device usbdevice h The qs scope example application makes use of the USB Device API to communicate with its paired application on the host Windows PC USB Device Class Driver APIs Device Class Drivers offer high level USB function to applications wishing to offer particular USB features without having to deal with most of the USB transaction handling and connection manage ment that would
236. ion psDevice points to a structure containing parameters customizing the operation of the HID keyboard device September 05 2012 171 Device Functions 3 18 4 2 3 18 4 3 172 Description This call is very similar to USBDKeyboardlnit except that it is used for initializing an instance of the HID keyboard device for use in a composite device Returns Returns zero on failure or a non zero instance value that should be used with the remaining USB HID Keyboard APIs USBDHI DKeyboardlnit Initializes HID keyboard device operation for a given USB controller Prototype void USBDHIDKeyboardInit unsigned long ulIndex const tUSBDHIDKeyboardDevice xpsDevice Parameters ullndex is the index of the USB controller which is to be initialized for HID keyboard device operation psDevice points to a structure containing parameters customizing the operation of the HID keyboard device Description An application wishing to offer a USB HID keyboard interface to a USB host must call this function to initialize the USB controller and attach the keyboard device to the USB bus This function performs all required USB initialization On successful completion this function will return the psDevice pointer passed to it This must be passed on all future calls to the HID keyboard device driver When a host connects and configures the device the application callback will receive USB EVENT CONNECTED after which calls can be made to US
237. ion for the instance supplied and removes the device from the USB bus Following this call the pvinstance instance should not me used in any other calls Returns None USBDDFUUpdateBegin Removes the current USB device from the bus and transfers control to the DFU boot loader September 05 2012 121 Device Functions 3 13 122 Prototype void USBDDFUUpdateBegin void Description This function should be called from the application s main loop i e not in interrupt context following a callback to the USB DFU callback function notifying the application of a DETACH request from the host The function will prepare the system to switch to DFU mode and transfer control to the boot loader in preparation for a firmware upgrade from the host The application must ensure that it has completed all necessary shutdown activities saved any required data etc before making this call since the function will not return Returns This function does not return HID Device Class Driver The USB Human Interface Class device class is an enormously versatile architecture for supporting a wide variety of input output devices regardless of whether or not they actually deal with Human Interfaces Although typically thought of in the context of keyboards mice and joysticks the speci fication can cover practically any device offering user controls or data gathering capabilities Communication between the HID device and host is via a co
238. ion of the unit required as defined in section 6 2 2 7 of the USB HID device class definition document Description This macro takes a value and prepares it to be placed as a Unit entry into a HID report structure Note that individual macros are defined for common units and this macro is intended for use when a complex or uncommon unit is needed It allows entry of a 5 nibble unit definition into the report descriptor Returns Not a function 3 14 3 18 UnitAccelerationS Definition define UnitAccelerationSI Description This macro inserts a Unit entry for acceleration in cm s 2 into a report descriptor 3 14 3 19 UnitAngAccelerationSl Definition define UnitAngAccelerationSI Description This macro inserts a Unit entry for angular acceleration in degrees s 2 into a report descriptor 3 14 3 20 UnitCurrent A Definition define UnitCurrent A Description This macro inserts a Unit entry for voltage into a a report descriptor 3 14 3 21 UnitDistance cm Definition define UnitDistance cm Description This macro inserts a Unit entry for centimeters into a report descriptor 144 September 05 2012 Device Functions 3 14 3 22 UnitDistance_i Definition define UnitDistance_i Description This macro inserts a Unit entry for inches into a report descriptor 3 14 3 23 UnitEnergySl Definition define UnitEnergySI Description This macro inserts a Unit entry for energy in grams cmxx
239. ions such as host connection signaling and responding to standard descriptor requests Host specific functions providing class independent features required by all USB host applica tion such as device detection and enumeration and endpoint management m Class specific functions and data types to aid development of applications conforming to sev eral commonly used USB classes The capabilities and organization of the USB library functions are governed by the following design goals m They are written entirely in C m They are easy to understand m They are reasonably efficient in terms of memory and processor usage m They are as self contained as possible m Where possible computations that can be performed at compile time are done there instead of at run time m They can be built with more than one tool chain Some consequences of these design goals are m To ensure ease of use and understandability the USB functions are not necessarily as efficient as they could be from a code size and or execution speed point of view m The APIs have a means of removing all error checking code Since the error checking is usually only useful during initial program development it can be removed to improve code size and speed The following tool chains are supported m Keil RealView Microcontroller Development Kit m CodeSourcery Sourcery G for Stellaris EABI m IAR Embedded Workbench m Code Red Technologies tools m Texas Inst
240. iption This structure is used by the application to define operating parameters for the HID mouse device 3 16 3 Define Documentation 3 16 3 1 MOUSE ERR NOT CONFIGURED Definition define MOUSE ERR NOT CONFIGURED Description USBDHIDMouseStateChange returns this value if it is called before the USB host has con nected and configured the device All mouse state information passed on the call will have been ignored 3 16 3 2 MOUSE ERR TX ERROR Definition define MOUSE ERR TX ERROR Description 160 This return code from USBDHIDMouseStateChange indicates that an error was reported while attempting to send a report to the host A client should assume that the host has disconnected if this return code is seen September 05 2012 3 16 3 3 3 16 3 4 3 16 3 5 3 16 3 6 3 16 4 3 16 4 1 Device Functions MOUSE REPORT BUTTON 1 Definition define MOUSE REPORT BUTTON 1 Description Setting this bit in the ucButtons parameter to USBDHIDMouseStateChange indicates to the USB host that button 1 on the mouse is pressed MOUSE REPORT BUTTON 2 Definition define MOUSE REPORT BUTTON 2 Description Setting this bit in the ucButtons parameter to USBDHIDMouseStateChange indicates to the USB host that button 2 on the mouse is pressed MOUSE REPORT BUTTON 3 Definition define MOUSE REPORT BUTTON 3 Description Setting this bit in t
241. iptor block except for string descriptor 0 must be repeated for each language defined in the language descriptor The number of HID device specific strings is dependent upon the content of the report descriptor passed to the interface and is thus application controlled ulNumStringDescriptors The number of descriptors provided in the ppStringDescriptors ar ray This must be 1 5 num HID strings num languages psPrivateHIDData A pointer to private instance data for this device instance This memory must remain accessible for as long as the HID device is in use and must not be modified by any code outside the HID class driver September 05 2012 137 Device Functions 3 14 3 3 14 3 1 3 14 3 2 3 14 3 3 138 Description The structure used by the application to define operating parameters for the HID device Define Documentation Collection This is a macro to assist adding Collection entries in HID report descriptors Definition define Collection ucValue Parameters ucValue is the type of Collection Description This macro takes a value and prepares it to be placed as a Collection entry into a HID report structure This is the type of values that are being grouped together for instance input output or features can be grouped together as a collection Returns Not a function COMPOSITE_DHID_SIZE Definition define COMPOSITE DHID SIZE Description The size of the memory that sho
242. iptors must follow the interface descriptor that they relate to it also states that device specific descriptors should follow any standard descriptor that they relate to As a result we cannot assume that each interface descriptor will be followed by nothing but an ordered list of its own endpoints and hence the function needs to be provided ulSize to limit the search range Returns Returns a pointer to the requested endpoint descriptor if found or NULL otherwise USBDescGetNum Determines the number of individual descriptors of a particular type within a supplied buffer Prototype unsigned long USBDescGetNum tDescriptorHeader xpsDesc unsigned long ulSize unsigned long ulType Parameters psDesc points to the first byte of a block of standard USB descriptors ulSize is the number of bytes of descriptor data found at pointer psDesc September 05 2012 21 General Purpose Functions 2 2 6 7 2 2 6 8 22 ulType identifies the type of descriptor that is to be counted If the value is USB_DESC_ANY the function returns the total number of descriptors regardless of type Description This function can be used to count the number of descriptors of a particular type within a block of descriptors The caller can provide a specific type value which the function matches against the second byte of each descriptor or alternatively can specify USB DESC ANY to have the function count all descriptors regardless of their type
243. is VID USB_VID_STELLARIS PID for the composite serial device USB_PID_COMP_SERIAL This is in 2mA increments so 500mA 250 Bus powered device USB_CONF_ATTR_BUS_PWR Generic USB handler for the composite device CompositeHandler The string table g_pStringDescriptors NUM_STRING_DESCRIPTORS NUM_DEVICES g_psCompDevices g_pulCompWorkspace amp g CompInstance The last bit of memory that needs to be allocated is the USB composite device descriptor workspace which is provided at Initialization time The allocation for two serial devices is shown below unsigned char pucDesciptorData COMPOSITE_DCDC_SIZE 2 Once all of the memory has been initialized and the appropriate memory allocated the application must call the initialization functions for each device instance In the case of the serial ports the USB buffers used must also first be initialized before completing initialization September 05 2012 3 10 Device Functions Initialize the transmit and receive buffers ff USBBufferInit tUSBBuffer amp g_sTxBufferA USBBufferInit tUSBBuffer amp g_sRxBufferA USBBufferInit tUSBBuffer amp g_sTxBufferB USBBufferInit tUSBBuffer amp g_sRxBufferB A Initialize the two serial port instances that are part of this composite device g sCompDevice psCompInfo 0 pvInstance USBDCDCCompositeInit 0 tUSBDCDCDevice
244. is first detected case KEYBOARD_INIT Initialized the newly connected keyboard USBHKeyboardInit g ulKeyboardInstance September 05 2012 Host Functions Proceed to the keyboard connected state eKeyboardState KEYBOARD CONNECTED break case KEYBOARD_UPDATE If the application detected a change that required an update to be sent to the keyboard to change the modifier state then call it and return to the connected state eKeyboardState KEYBOARD CONNECTED USBHKeyboardModifierSet g_ulKeyboardInstance g ulModifiers case KEYBOARD_CONNECTED break case KEYBOARD_NOT_CONNECTED default break Periodic call the main loop for the Host controller driver USBHCDMain Much like the mouse the keyboard handles the reception of events entirely in the callback han dler This function should receive and store the keyboard events and handle them in the main program loop when the device is in the connected state The USB_EVENT_CONNECTED lets the main loop know that it is time to call the USBHKeyboardlnit routine to configure the keyboard The USB_EVENT_DISCONNECTED event simply informs the application that the keyboard is not longer present and not to expect any more callbacks until another USB_EVENT_CONNECTED oc curs The remaining events all indicate that a key has been pressed or released Normal key presses releases generate
245. is function returns the SCSI status from the command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL USBHSCSIRequestSense This function issues a SCSI Request Sense command to a device Prototype unsigned long USBHSCSIRequestSense unsigned long ulInPipe unsigned long ulOutPipe unsigned char xpucData unsigned long xpulSize Parameters ullnPipe is the USB IN pipe to use for this command ulOutPipe is the USB OUT pipe to use for this command pucData is the data buffer to return the results into pulSize is the size of the buffer on entry and number of bytes read on exit Description This function is used to issue a SCSI Request Sense command to a device It will return the data in the buffer pointed to by pucData The parameter pulSize should have the allocation size in bytes of the buffer pointed to by pucData September 05 2012 4 5 4 34 4 5 4 35 Host Functions Returns This function returns the results of the SCSI Request Sense command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL USBHSCSITestUnitReady This function issues a SCSI Test Unit Ready command to a device Prototype unsigned long USBHSCSITestUnitReady unsigned long ulInPipe unsigned long ulOutPipe Parameters ullnPipe is the USB IN pipe to use for this command ulOutPipe is the USB OUT pipe to use for this command Description This function is used to issue a SCSI
246. is function will allow an application to tell the keyboard how often it should send updates to the USB host controller regardless of any changes in keyboard state The ullnstance value is the value that was returned when the application called USBHKeyboardOpen The ulPollRate is the new value in ms for the update rate on the keyboard This value is initially set to O which indicates that the keyboard should only to update when the keyboard state changes Any value other than O can be used to force the keyboard to generate auto repeat sequences for the application Returns This function returns O to indicate success any non zero value indicates an error condition USBHKeyboardUsageToChar This function is used to map a USB usage ID to a printable character Prototype unsigned long USBHKeyboardUsageToChar unsigned long ulInstance const tHIDKeyboardUsageTable xpTable unsigned char ucUsageID September 05 2012 271 Host Functions 4 7 2 7 4 7 2 8 272 Parameters ullnstance is the instance value for this keyboard pTable is the table to use to map the usage ID to characters ucUsagelD is the USB usage ID to map to a character Description This function is used to map a USB usage ID to a character The provided pTable is used to perform the mapping and is described by the tHIDKeyboardUsage Table type defined structure See the documentation on the tHIDKeyboardUsageTable structure for more details on the in ternals of thi
247. is the pointer to the mouse device instance structure pvCBDaia is the pointer that client wishes to be provided on each event sent to the mouse callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnCallback function passed on USBDHIDMouselnit If a client wants to make runtime changes in the callback pointer it must ensure that the pvlIn stance structure passed to USBDHIDMouselnit resides in RAM If this structure is in flash callback data changes will not be possible Returns Returns the previous callback pointer that was set for this instance 3 16 4 6 USBDHIDMouseStateChange Reports a mouse state change pointer movement or button press to the USB host Prototype unsigned long USBDHIDMouseStateChange void pvInstance char cDeltaX char cDeltayY unsigned char ucButtons Parameters pvinstance is the pointer to the mouse device instance structure cDeltaX is the relative horizontal pointer movement that the application wishes to report Valid values are in the range 127 127 with positive values indicating movement to the right cDeltaY is the relative vertical pointer movement that the application wishes to report Valid values are in the range 127 127 with positive values indicating downward movement ucButtons is a bit mask indicating which if any of the three mouse buttons is pressed Valid values
248. k event handler YourUSBAudioMessageHandler Ef A pointer to your string table g_pStringDescriptors The number of entries in your string table ft NUM_STRING_DESCRIPTORS T Maximum volume setting expressed as and 8 8 signed fixed point number VOLUME MAX Minimum volume setting expressed as and 8 8 signed fixed point number VOLUME_MIN I Minimum volume step expressed as and 8 8 signed fixed point number 3 VOLUME STEP This is the private instance data for the audio class driver amp g sAudioInstanceData he m From your main initialization function call the audio device class driver initialization function to September 05 2012 61 Device Functions 3 3 4 62 configure the USB controller and place the device on the bus pDevice USBDAudiolInit 0 amp g_sAudioDevice m Assuming pDevice returned is not NULL your device is now ready to communicate with a USB host Once the host connects the audio message handler will be sent the USB_EVENT_CONN event ECT ED m Once the host is configured to use the Audio device the audio message handler will be called with a USBD AUDIO EVENT ACTIVE event Using the Composite Audio Device Class When using the audio device class in a composite device the configuration of the device is very similar to how it is configured as a non composite device Follow all
249. k is the function that will be called when events occur on this USB Pipe Since there are a limited number of USB HCD pipes that can be used in the host controller this function is used to temporarily or permanently acquire one of the endpoints Unlike the USBHCDPipeAlloc function this function allows the caller to specify the size of the FIFO allo cated to this endpoint in the u Size parameter This function also provides a method to register a callback for status changes on this endpoint If no callbacks are desired then the pfn Callback function should be set to 0 The callback should be used when using the USBHCDPipeSched ule function so that the caller is notified when the action is complete Returns This function returns a value indicating which pipe was reserved If the value is 0 then there were no pipes currently available This value should be passed to any USBHCDPipe APIs to indicate which pipe is being accessed 4 3 4 14 USBHCDPipeConfig Definition unsigned long USBHCDPipeConfig unsigned long ulPipe unsigned long ulMaxPayload unsigned long ulInterval unsigned long ulTargetEndpoint Description This function is used to configure a USB HCD pipe This should be called after allocating a USB pipe with a call to USBHCDPipeAlloc It is used to set the configuration associated with an endpoint like the max payload and target endpoint The ulMaxPayload parameter is typically read directly from the devices endp
250. k ko ke khe ke ke khe ke ke kk ke kk ko ke kk kk kk ck ke eee eee eee ee ee ee ee eee ee ee ee ee eee eee unsigned char g pHCDPool HCD MEMORY SIZE J kk ke kk ke kk kk ko ke ke Sk kk ke kk kk kk ke ok kk kk kk kk kk ko kk ko ke kk kk kk ko ke kk kk kk Kok kk kk kk ko ke kk ke ke ke ke ke ee Af The global that holds all of the host drivers in use in the application In this case only the Keyboard class is loaded TKK ROR kk kk Kk Kk kk kk RR RR OR IR IOI RRR IR IR k k K I IK ke ke kk ke ck k ke ke e static tUSBHostClassDriver const const g ppHostClassDrivers amp g_USBHIDClassDriver amp g_USBHostMSCClassDriver J f H k k k k k e k e kk A ROR OR RRR OR IR OK RIOR IR IR I I K k k K k k k k k k k k k This global holds the number of class drivers in the g_ppHostClassDrivers list Af J kk ok ke ROR kk khe ke kk kk kk kk kk ke ok kk ko OR IR IR ke kk Kok kk I RR IR kk ko ke ko kk a ke ke oe Static const unsigned long g ulNumHostClassDrivers sizeof g ppHostClassDrivers sizeof tUSBHostClassDriver Enable Clocking to the USB controller SysCtlPeripheralEnable SYSCTL PERIPH USBO0 Enable the peripherals used by this example SysCtlPeripheralEnable SYSCTL_PERIPH_UARTO SysCtlPeripheralEnable SYSCTL PERIPH GPIOH Set the USBOEPEN and USBOPFLT pins to be controlled by the USB controller September 05 2012 275 Host Functions ff GPIOPinTypeUSBD
251. kk kk kk ke kk koe ke kk kk koe kc kk ck SP ee eee eee ee ee ee eee eee eee eee eee eee ee ck ckokok const unsigned char g pDataInterfaceString 19 1 2 USB_DTYPE_STRING B 0 ru 0 CES 0 et s 0 c E 0 D 0 a 0 DU 0 a 0 Ly 0 dey 0 nes 0 try 0 etg 0 Ery 0 eit 0 at D tet 00 tet ru hi J kk OK RRR kk kk ke kk Kok kk Kok kk Kok OR IRR KR OR IR RR IR IR IR I A A Ik oe The configuration description string J kk Sk ROR ROKR ORR ORR ORR RRR IR ORR OR IR IR I AI IA ke ek oe const unsigned char g_pConfigString IEL 2 USB DTYPE STRING B 0 ut 0 Cp 0 kl 0 r 0 Dr 0 ral 0 PE 0 at arto cy PO COP cof Op een gs Op TEC Du V0 g 0 ac Op CELL 70 ay 0s TE 0 ats operc m 0 J kk kk koe kk oko kk kk ke kk Kok kk Kok kk Kok kk koe kk koe kk kk kk ko ko kk Kok kk ko Kk Kk Kok kk oko ko kk koe kk oko kk ke ke ke ke ee The descriptor string table J k kk kk oko ke Sk kk kk Kok kk Kok kk Kok kk Kok kk koe kk kk kk kk kk IR kk ko Kk kk Kok kk oko IR kk Kok kk ko ke ek Ke ee const unsigned char const g pStringDescriptors g pLangDescriptor g pManufacturerString g pProductString g pSerialNumberString g pDataInterfaceString g pConfigString September 05 2012 71 Device Functions 72 hi define NUM_STRING_DESCRIPTORS sizeof g_pStringDescriptors sizeof unsigned char x Define an area of
252. kk kk koe kk kk ko kk coke kk ee eee kk ck eee ee kk ck ck kk ck ck ck ck kc kc kck ck kckckckck ck ck ckck ck ckckckck ck oko The manufacturer string J f kk ke ROKR KR IRR RR IK RRR kk ko ko IR OR IR I OR IR I I I I ke ee const unsigned char g_pManufacturerString 17 1 2 USB_DTYPE_STRING T 0 Cery 0 x 0 s 0 s 0 Uy 0 PITE 0 n 0 s 0 Pet Oy Ue Up tut Uy m Oe Tey Dy PO OR fot Oy ee Oy J kk ke koe ke kk ke kk ke kk kk kk koe kk kk kk kk ke Sk kk kk koe kk ck koc kk ko ok Sk ko Kk kk ko kk ko ko kc kk ke kk ko ke kk ko ke ek Ke ke September 05 2012 Device Functions The product string def J kk kk koe kk oko kk ko RR kk Kk RR IRR RRR OR ORR IR IR I I A kk ko ke ok Ke ee const unsigned char g pProductString ES bh 27 USB DTYPE STRING G 0 re 0 n 0 re 0 od 0 C 0 Cet 0 f e 0 PBS 0 ru 0 SEES 0 k 0 7 zu 0 B5 0 cery 0 EN Ea 0 ely 0 5e 0 teh up di J kk kk kk ke kk RR A RI IR IR IR IR IR IR IIR I OR OR ok The serial number string J kk kk RRR kk Kok kk Kok kk Kok RR RRR RRR IR RR IR IR IR I AI kk ke ke ek oe const unsigned char g pSerialNumberString 8 1 2 USB DTYPE STRING OI aU EAE Vig ABE SG Dy Pry Uy C50 Ou etu Du Th QV ta Lo hi J kk OK ROR ROKR kk Kok kk Kok kk Kok kk Kok RR RRR IR IRR IR IR IR I A IA Ik oe The data interface description string J
253. l callbacks to the pfnTxCallback function passed on USBDHIDInit If a client wants to make runtime changes in the callback data it must ensure that the pvin stance structure passed to USBDHIDInit resides in RAM If this structure is in flash callback data changes will not be possible Returns Returns the previous callback data pointer that was being used for this instance s transmit callback 3 14 4 10 USBDHIDTerm Shuts down the HID device Prototype void USBDHIDTerm void xpvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDInit Description This function terminates HID operation for the instance supplied and removes the device from the USB bus This function should not be called if the HID device is part of a composite device and instead the USBDCompositeTerm function should be called for the full composite device Following this call the pvinstance instance should not me used in any other calls Returns None 3 14 4 11 USBDHIDTxPacketAvailable Returns the number of free bytes in the transmit buffer Prototype unsigned long USBDHIDTxPacketAvailable void pvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDInit Description This function indicates to the caller whether or not it is safe to send a new report using a call to USBDHIDReportWrite The value returned will be the maximum USB packe
254. l passed to this function must be at least as large as a typical configuration descriptor for devices that are to be supported This value is application dependent however it should never be less than 32 bytes and in most cases should be at least 64 bytes If there is not sufficient memory to load a configuration descriptor from a device the device will not be recognized by the USB library s host controller driver Returns None 4 3 4 11 USBHCDMain Definition void USBHCDMain void Description This function is the main routine for the Host Controller Driver This function is the main routine for the host controller driver and must be called periodically by the main application outside of a callback context This allows for a simple cooperative system to access the the host controller driver interface without the need for an RTOS All time critical operations are handled in interrupt context but all blocking operations are run from the this function to allow them to block and wait for completion without holding off other interrupts Returns None 4 3 4 12 USBHCDPipeAlloc Definition unsigned long USBHCDPipeAlloc unsigned long ulIndex unsigned long ulEndpointType tUSBHostDevice psDevice tHCDPipeCallback pfnCallback Description This function is used to allocate a USB HCD pipe Parameters ullndex specifies which USB controller to use ulEndpointType is the type of endpoint that this pipe will
255. lass there are no events sent to the transmit callback which MUST be handled but applications will usually want to note USB EVENT TX COMPLETE since this is an interlock message indicating that the previous packet sent has been acknowledged by the host and a new packet can now be sent Add a control event handler function YourUSBControlEventCallback in the previous exam ple to your application and ensure that you handle USBD CDC EVENT GET LINE CODING returning a valid line coding configuration even if your device is not actually driving a UART Handle the other control events as required for your application From your main initialization function call the CDC device class driver initialization function to configure the USB controller and place the device on the bus pDevice USBDCDCInit 0 amp g sCDCDevice Assuming pDevice returned is not NULL your device is now ready to communicate with a USB host Once the host connects your control event handler will be sent USB EVENT CONNECTED and the first packet of data may be sent to the host using USBDCDCPacketWrite with following packets transmitted as soon as USB EVENT TX COMPLETE is received via the transmit event handler Using the Composite CDC Serial Device Class When using the CDC serial device class in a composite the configuratio
256. lback alongside every event void amp g_sYourInstanceData September 05 2012 3 5 3 Device Functions T A pointer to your string table g_pStringDescriptors The number of entries in your string table NUM_STRING_DESCRIPTORS red A pointer to the private memroy allocated for the class driver to use amp g_sBulkInstance Add a receive event handler function YourUSBReceiveEventCallback in the previous exam ple to your application taking care to handle all messages which require a particular response For the generic bulk device class only the USB EVENT RX AVAILABLE MUST be handled by the receive event handler In response to USB EVENT RX AVAILABLE your handler should check the amount of data received by calling USBDBulkRxPacketAvailable then read it us ing a call to USBDBulkPacketRead This causes the newly received data to be acknowl edged to the host and instructs the host that it may now transmit another packet If you are unable to read the data immediately return 0 from the callback handler and you will be called back once again a few milliseconds later Although no other events must be handled USB EVENT CONNECTED and USB EVENT DISCONNECTED Will typically be required since these indicate when a host connects or disconnects and allow the application to flush any buffers or reset state as required Attempts to send data when the host is disconnected will fail
257. le SysCtlUSBPLLEnable USBDevEndpointConfigSet and USBFI FOConfigSet instead of using this function If this function is used it must be called prior to USBDCDInit since this call assumes that the low level hardware configuration has been completed before it is made Returns Returns true on success or false on failure 3 22 3 11 USBDeviceConfigAlternate Configure the affected USB endpoints appropriately for one alternate interface setting Prototype tBoolean USBDeviceConfigAlternate tDeviceInstance xpsDevInst const tConfigHeader xpsConfig unsigned char ucInterfaceNum unsigned char ucAlternateSetting Parameters psDevinst is a pointer to the device instance being configured psConfig is a pointer to the configuration descriptor that contains the interface whose alter nate settings is to be configured ucinterfaceNum is the number of the interface whose alternate setting is to be configured This number corresponds to the bInterfaceNumber field in the desired interface descriptor ucAlternateSetting is the alternate setting number for the desired interface This number corresponds to the bAlternateSetting field in the desired interface descriptor Description This function may be used to reconfigure the endpoints of an interface for operation in one of the interface s alternate settings Note that this function assumes that the endpoint FIFO settings will not need to change and only the endpoint mode is c
258. ler 3 21 2 11 The pf nDisconnectHandler callback is made whenever the USB Device API detects that the device has been disconnected from the bus If this member of scallbacks is set to NULL the USB Device API will not inform the device code when a disconnection event occurs Note The USB EVENT DISCONNECTED event will not be reported to the application if the MCU s PB1 USBOVBUS pin is connected to a fixed 5 Volts rather than directly to the VBUS pin on the USB connector pfnEndpointHandler While the use of endpoint zero is standardized and supported via several of the other callbacks al ready listed p nDataSent pfnDataReceived pfnGetDescriptor pfnRequestHandler pfnInterfaceChange and pfnConfigChange the use of other endpoints is entirely depen dent upon the device class being implemented The p nEndpointHandler Callback is therefore made to notify the device code of all activity on any endpoint other than endpoint zero and it is the device code s responsibility to determine the correct action to take in response to each callback The ulStatus parameter passed to the handler provides information on the actual endpoint for which the callback is being made and allows the handler to determine if the event is due to trans mission if an IN endpoint event occurs or reception if an OUT endpoint event occurs of data Having determined the endpoint sourcing the event the device code can determine the actual event by calling US
259. ler function Your USBReceiveEventCallback in the previous example to your application taking care to handle all messages which require a particular response For the HID device class the following receive callback events MUST be handled by the application USB EVENT RX AVAILABLE USBD HID EVENT IDLE TIMEOUT USBD HID EVENT GET REPORT BUFFER USBD HID EVENT GET REPORT USBD HID EVENT SET PROTOCOL for BIOS protocol devices USBD HID EVENT GET PROTOCOL for BIOS protocol devices USBD HID EVENT SET REPORT Although no other events must be handled USB EVENT CONNECTED and EVENT DISCONNECTED Will typically be required since these indicate when a host USB connects or disconnects and allow the application to flush any buffers or reset state as required Attempts to send data when the host is disconnected will fail m Add ple a transmit event handler function YourUSBTransmitEventCallback in the previous exam to your application and use USB EVENT TX COMPLETE to indicate when a new report may be scheduled for transmission While a report is being transmitted attempts to send another report via USBDHIDReportWrite will fail m From your main initialization function call the HID device class driver initialization function to configure the U
260. lication or file system must register the mass storage class driver with a call to USBHCDRegisterDrivers with the g_USBHostMSCClassDriver as a member of the array passed in to the call Once the host mass storage class driver has been registered the application must call USBHMSCDriveOpen to allow the application or file system to be called when a new mass storage device is connected or disconnected or any other mass storage class event occurs Example Adding Mass Storage Class Driver const tUSBHostClassDriver const g_ppUSBHostClassDrivers amp g USBHostMSCClassDriver i Register the host class drivers USBHCDRegisterDrivers 0 g_ppUSBHostClassDrivers 1 fl Initialize the mass storage class driver on controller 0 with the MSCCallback function as the callback for events EA USBHMSCDriveOpen 0 MSCCallback The first callback is a USB_EVENT_CONNECTED event indicating that a mass storage class flash drive was inserted and the USB library host stack has completed enumeration of the device This does not indicate that the flash drive is ready for read write operations but that is has been detected The USBHMSCDriveReady function should be called to determine when the flash drive is ready September 05 2012 237 Host Functions 4 4 5 238 for read write operations When the device has been removed an USB_EVENT_DISCONNECTED event occurs When shutting down the application should call USBHM
261. lication to allow the USB controller endpoints to be correctly configured tFIFOEntry Definition typedef struct tBoolean bDoubleBuffer unsigned short usEPFlags tFIFOEntry Members bDoubleBuffer This field indicates whether to configure an endpoint s FIFO to be double or single buffered If true a double buffered FIFO is created and the amount of required FIFO storage is multiplied by two usEPFlags This field defines endpoint mode flags which cannot be deduced from the configu ration descriptor namely any in the set USB EP AUTO xxx or USB EP DMA MODE x USBDCDConfig adds these flags to the endpoint mode and direction determined from the config descriptor before it configures the endpoint using a call to USBDevEndpointCon figSet Description This structure defines how a given endpoint s FIFO is configured in relation to the maximum packet size for the endpoint as specified in the endpoint descriptor Define Documentation USB MAX INTERFACES PER DEVICE Definition define USB MAX INTERFACES PER DEVICE Description The maximum number of independent interfaces that any single device implementation can support Independent interfaces means interface descriptors with different bInterfaceNumber September 05 2012 Device Functions values several interface descriptors offering different alternative settings but the same inter face number count as a single interface 3 22 3 Function Documentatio
262. llback function which will be called to notify the application of DETACH requests pvCBData A client supplied pointer which will be sent as the first parameter in all calls made to the pfnCallback function psPrivateDFUData pointer to private instance data for this device instance This memory must remain accessible for as long as the DFU device is in use and must not be modified by any code outside the DFU class driver Description The structure used by the application to define operating parameters for the DFU device Note that unlike all other devices this structure does not contain any fields which configure the device descriptor sent back to the host The DFU runtime device class must be used as part of a composite device since all it provides is the capability to signal the device to switch into DFU mode in preparation for a firmware upgrade Creating a device with nothing but DFU runtime mode capability is rather pointless so this is not supported 3 12 3 Define Documentation 3 12 3 14 COMPOSITE DDFU SIZE Definition define COMPOSITE_DDFU_SIZE Description The size of the memory that should be allocated to create a configuration descriptor for a single instance of the DFU runtime device This does not include the configuration descriptor which is automatically ignored by the composite device class This label is used to compute the value which will be passed to the USBDCompositelnit function in the ulSize parameter
263. llback with the USBHCDPipeAlloc call in order to be informed when the data has been transmitted The value returned by this function can be less than the u Size requested if the USB pipe has less space available than this request is making September 05 2012 225 Host Functions Returns This function returns the number of bytes that were scheduled to be sent on the given USB pipe 4 3 4 22 USBHCDPowerAutomatic Definition unsigned long USBHCDPowerAutomatic unsigned long ulIndex Description This function returns if the current power settings will automatically handle enabling and dis abling VBUS power Parameters ullndex specifies which USB controller to query This function returns if the current power control pin configuration will automatically apply power or whether it will be left to the application to turn on power when it is notified Returns A non zero value indicates that power is automatically applied and a value of zero indicates that the application must manually apply power 4 3 4 8 USBHCDPowerConfigGet Definition unsigned long USBHCDPowerConfigGet unsigned long ulIndex Description This function is used to get the power pin and power fault configuration Parameters ullndex specifies which USB controller to use This function will return the current power control pin configuration as set by the USBHCD PowerConfiglnit function or the defaults if not yet set See the USBHCDPowerConfig
264. llection of report structures which are defined by the device in HID report descriptors which the host can query Reports are defined both for communication of device input to the host and for output and feature selection from the host In addition to the flexibility offered by the basic architecture HID devices also benefit from excellent operating system support for the class meaning that no driver writing is necessary and in the case of standard devices such as keyboards and joysticks the device can connect to and operate with the host system without any new host software having to be written Even in the case of a non standard or vendor specific HID device the operating system support makes writing the host side software very much more straightforward than developing the device using a vendor specific class Despite these advantages there is one downside to using HID The interface is limited in the amount of data that can be transferred so is not suitable for use by devices which expect to use a high per centage of the USB bus bandwidth Devices are limited to a maximum of 64KB of data per second for each report they support Multiple reports can be used if necessary but high bandwidth devices may be better implemented using a class which supports bulk rather than interrupt endpoints such as CDC or the generic bulk device class September 05 2012 USB HID Device Model USB Host Optional Interrupt OUT Interrupt IN 8
265. lnit documentation for the meaning of the bits that are returned by this function Returns The configuration of the power control pins 4 3 4 4 USBHCDPowerConfiglnit Definition void USBHCDPowerConfigInit unsigned long ulIndex unsigned long ulPwrConfig Description This function is used to set the power pin and power fault configuration Parameters ullndex specifies which USB controller to use 226 September 05 2012 Host Functions ulPwrConfig is the power configuration to use for the application This function must be called before HCDInit is called so that the power pin configuration can be set before power is enabled The u PwrConfig flags specify the power fault level sensitivity the power fault action and the power enable pin level and source One of the following can be selected as the power fault level sensitivity m USBHCD FAULT LOW An external power fault is indicated by the pin being driven low m USBHCD FAULT HIGH An external power fault is indicated by the pin being driven high One of the following can be selected as the power fault action m USBHCD FAULT VBUS NONE No automatic action when power fault detected m USBHCD FAULT VBUS TRI Automatically Tri state the USBnEPEN pin on a power fault m USBHCD FAULT VBUS DIS Automatically drive the USBnEPEN pin to it s inactive state on a power fault One of the following can be selected as the power enable level and source m USBHCD VBU
266. ls to the USB bulk device class should use the value returned by USBDBulk Compositelnit when the API calls for a pvinstance pointer Also when using the bulk device in a composite device the COMPOSITE DBULK SIZE value should be added to the size of the g pucDescriptorData array as shown in the example above Windows Drivers for Generic Bulk Devices Since generic bulk devices appear to a host operating system as vendor specific devices no device drivers on the host system will be able to communicate with them without some help from the device developer This help may involve writing a specific Windows kernel driver for the device or if kernel driver programming is too daunting steering Windows to use one of several possible generic kernel drivers that can manage the device on behalf of a user mode application Using this second model a device developer need not write any Windows driver code but would need to write an application or DLL that interfaces with the device via the user mode API offered by whichever USB subsystem they chose to manage their device The developer is also responsible for producing a suitable INF file to allow Windows to associate the device identified via its VID PID combination with a particular driver September 05 2012 Device Functions A least two suitable USB subsystems are available for Windows WinUSB from Microsoft or open source project libusb win32 available from SourceForge WinUSB supports Windows
267. m energy Clocks and Timers www ti com clocks Industrial www ti com industrial Interface interface ti com Medical www ti com medical Logic logic ti com Security www ti com security Power Mgmt power ti com Space Avionics and Defense www ti com space avionics defense Microcontrollers microcontroller ti com Video and Imaging www ti com video RFID www ti rfid com OMAP Mobile Processors www ti com omap Wireless Connectivity www ti com wirelessconnectivity TI E2E Community Home Page e2e ti com Mailing Address Texas Instruments Post Office Box 655303 Dallas Texas 75265 Copyright 2008 2012 Texas Instruments Incorporated 282 September 05 2012
268. m power consumption of the device expressed in milliamps ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wakeup Valid values are USB CONF ATTR SELF PWR or USB CONF ATTR BUS PWhR optionally ORed with USB CONF ATTR RWAKE pfnRxCallback A pointer to the callback function which will be called to notify the application of events related to the device s data receive channel pvRxCBData A client supplied pointer which will be sent as the first parameter in all calls made to the receive channel callback pfnRxCallback pfnTxCallback A pointer to the callback function which will be called to notify the application of events related to the device s data transmit channel pvTxCBData A client supplied pointer which will be sent as the first parameter in all calls made to the transmit channel callback pfnTxCallback ppStringDescriptors A pointer to the string descriptor array for this device This array must contain pointers to the following string descriptors in this order Language descriptor Man ufacturer name string language 1 Product name string language 1 Serial number string language 1 Interface description string language 1 and Configuration description string language 1 If supporting more than 1 language the strings for indices 1 through 5 must be repeated for each of the other languages defined in the language descriptor ulNumStringDescriptors The number of descriptors pro
269. m the FIFO size to be defined in terms of a maximum packet size multiplier m the FIFO buffering mode to be set to either single or double buffered and m and special configuration flags such as DMA mode to be specified Interrupt Vector Selection An application using the USB Device API should normally ensure that the interrupt vector for the hardware USB controller is set to call function USBODeviceIntHandler If the target application is intended to allow switching between USB device and USB host mode however this handler should be replaced with USBODualModeIntHandler to allow the USB li brary to perform appropriate interrupt steering depending upon the current mode of operation Hybrid applications must also call USBStackModeSet to indicate the mode they wish to operate in Passing Control to the USB Device API When all previous setup steps have been completed control can be passed to the USB Device API The library will enable the appropriate interrupts and connect the device to the bus in preparation for enumeration by the USB host This operation is initiated using a call to USBDCDInit passing the completed tDevicernfo structure which describes the device Following this call your device code callback functions will be called when USB events specific to your device are detected by the library September 05 2012 Device Functions Pass the USB Device API our device information and connect the device to the bus
270. matic power control is disabled USB EVENT POWER FAULT Definition define USB_EVENT_POWER_FAULT Description The host detected a power fault condition USB_EVENT_REQUEST_BUFFER Definition define USB EVENT REQUEST BUFFER Description This event is sent by a lower layer supporting DMA to request a buffer in which the next received packet may be stored The u MsgValue parameter indicates the maximum size of packet that can be received in this channel and pvMsgData points to storage which should be written with the returned buffer pointer The return value from the callback should be the size of the buffer allocated which may be less than the maximum size passed in ulMsgValue if the client knows that fewer bytes are expected to be received or 0 if no buffer is being returned USB EVENT RESUME Definition define USB EVENT RESUME Description The bus has left suspend state USB EVENT RX AVAILABLE Definition define USB EVENT RX AVAILABLE September 05 2012 13 General Purpose Functions 2 2 3 16 2 2 3 17 2 2 3 18 2 2 3 19 2 2 3 20 14 Description Data has been received and is in the buffer provided USB_EVENT_SCHEDULER Definition define USB_EVENT_SCHEDULER Description A scheduler event has occurred USB_EVENT_SOF Definition define USB EVENT SOF Description A start of frame e
271. memory that should be allocated to create a configuration descriptor for a single instance of the USB Serial CDC Device This does not include the configuration descriptor which is automatically ignored by the composite device class USBD_CDC_EVENT_CLEAR_BREAK Definition define USBD CDC EVENT CLEAR BREAK September 05 2012 97 Device Functions 3 8 3 3 3 8 3 4 3 8 3 5 3 8 3 6 98 Description The host requests that the device stop sending a BREAK condition on its serial communication channel USBD CDC EVENT GET LINE CODING Definition define USBD CDC EVENT GET LINE CODING Description The host is querying the current RS232 communication parameters The pvMsgData parame ter points to a tLineCoding structure that the application must fill with the current settings prior to returning from the callback USBD CDC EVENT SEND BREAK Detinition define USBD CDC EVENT SEND BREAK Description The host requests that the device send a BREAK condition on its serial communication chan nel The BREAK should remain active until a USBD CDC EVENT CLEAR BREAK event is received USBD CDC EVENT SET CONTROL LINE STATE Definition define USBD CDC EVENT SET CONTROL LINE STATE Description The host requests that the device set the RS232 signaling lines to a particular state The ulMsgValue parameter contains the RTS and DTR cont
272. moved before the device is connected or even while the device is running Note Some care must be taken by the application if it wishes to share the media with the mass storage class Proper access protection must be in place as the mass storage class may be using the media access functions during the USB interrupt September 05 2012 175 Device Functions 3 19 1 3 19 2 3 19 2 1 3 19 2 2 3 19 2 3 Initialization The USB library s mass storage class provides a simple interface to initialize the mass storage class and pass it the needed functions to access a device without having any knowledge of the physical media The USBDMSCOInit function is the only initialization required by the mass storage class and it uses the structure tUSBDMSCDevice to hold all customizable values for the mass storage class Customization The USB library s mass storage class provides the ability to customize how the device is reported to the USB host controller in the tUSBDMSCDevice structure The members of this structure contain all of the customizable parameters VID and PID The VID and PID values reported to the host controller are provided in the usVID and usPID mem bers of the tUSBDMSCDevice structure and should be valid for the application and unique for all vendors and devices The mass storage device class also reports some class specific strings to the operating system which can be customized in the pucVendor pucProduct and pucVersion
273. mprising the full descriptor for this configuration psSections A pointer to an array of ucNumSections section pointers which must be concate nated to form the configuration descriptor Description This is the top level structure defining a USB device configuration descriptor A configuration descriptor contains a collection of device specific descriptors in addition to the basic config interface and endpoint descriptors To allow flexibility in constructing the configuration the descriptor is described in terms of a list of data blocks The first block must contain the con figuration descriptor itself and the following blocks are appended to this in order to produce the full descriptor sent to the host in response to a GetDescriptor request for the configuration descriptor tConfigSection Definition typedef struct unsigned short usSize const unsigned char pucData tConfigSection Members usSize The number of bytes of descriptor data pointed to by pucData pucDaita A pointer to a block of data containing an integral number of USB descriptors which form part of a larger configuration descriptor Description This structure defines a contiguous block of data which contains a group of descriptors that form part of a configuration descriptor for a device It is assumed that a config section contains only whole descriptors It is not valid to split a single descriptor across multiple sections tCustomHandlers Definition
274. n 3 22 3 1 3 22 3 2 USBODevicelntHandler The USB device interrupt handler Prototype void USBODeviceIntHandler void Description This the main USB interrupt handler entry point for use in USB device applications This top level handler will branch the interrupt off to the appropriate application or stack handlers depending on the current status of the USB controller Applications which operate purely as USB devices rather than dual mode applications which can operate in either device or host mode at different times must ensure that a pointer to this function is installed in the interrupt vector table entry for the USBO interrupt For dual mode operation the vector should be set to point to USBODualModelntHandler instead Returns None USBDCDInit Initialize the USB library device control driver for a given hardware controller Prototype void USBDCDInit unsigned long ulIndex tDeviceInfo psDevice Parameters ullndex is the index of the USB controller which is to be initialized psDevice is a pointer to a structure containing information that the USB library requires to support operation of this application s device The structure contains event handler call backs and pointers to the various standard descriptors that the device wishes to publish to the host Description This function must be called by any application which wishes to operate as a USB device It initializes the USB device co
275. n g_USBHIDClassDriver Definition const tUSBHostClassDriver g_USBHIDClassDriver Description This constant global structure defines the HID Class Driver that is provided with the USB library g USBHostAudioClassDriver Definition const tUSBHostClassDriver g_USBHostAudioClassDriver Description This constant global structure defines the Audio Class Driver that is provided with the USB library g_USBHostMSCClassDriver Definition const tUSBHostClassDriver g_USBHostMSCClassDriver Description This constant global structure defines the Mass Storage Class Driver that is provided with the USB library g_USBHubClassDriver Definition const tUSBHostClassDriver g_USBHubClassDriver Description This constant global structure defines the Hub Class Driver that is provided with the USB library September 05 2012 4 6 4 6 1 4 6 2 Host Functions Host Device Interface The USB library provides a set of example host device interfaces for a HID mouse a HID keyboard and a mass storage device The next few sections discusses each briefly and explain how their interfaces can be used by an application Mouse Device The HID mouse device interface is controlled mainly through a callback function that is provided as part of the call to open the mouse device interface In order to open an instance of the mouse device the application calls USBHMouseOpen and passes in a callback function as well as some buffer data fo
276. n of the device is very similar to how it is configured as a non composite device Follow all of the configuration steps in the previous section with the exception of calling USBDCDCCompositelnit instead of USBDCDCInit This will prepare an instance of the CDC serial device class to be enumerated as part of a composite device The return value from the USBDCDCCompositelnit function should be placed in the pvinstance member of the tCompositeEntry structure for the CDC serial device The code example below provides an example of how to initialize the tCompositeEntry structure These should be initialized with valid values for each class extern tUSBDCompositeDevice g_sCompDevice extern tUSBDCDCDevice g_sCDCDevice ff The OTHER_SIZES here are the sizes of the descriptor data for other classes that are part of the composite device September 05 2012 3 7 4 Device Functions define DESCRIPTOR DATA SIZE COMPOSITE DCDC SIZE OTHER SIZES unsigned char g pucDescriptorData DESCRIPTOR DATA SIZE tCompositeEntry psCompEntries 2 Set the CDC serial device information psCompEntries 0 psDevice g sCDCSerDeviceInfo Save the instance data for this CDC serial device rod psCompEntries 0 pvInstance USBDCDCCompositeInit 0 amp g sCDCDevice Initialize other devices to add to the composite device Save the device entries in the composite device
277. n released If only modifier keys have changed state this parameter is ignored Description This function adds or removes a key usage code from the list of keys currently pressed and schedules a report transmission to the host to inform it of the new keyboard state If the maximum number of simultaneous key presses are already recorded the report to the host will contain the rollover error code HID KEYB USAGE ROLLOVER instead of key usage codes and the caller will receive return code KEYB ERR TOO MANY KEYS Returns Returns KEYB SUCCESS if the key usage code was added to or removed from the current list successfully KEYB ERR TOO MANY KEYS is returned if an attempt is made to press a 7th key the BIOS keyboard protocol can report no more than 6 si multaneously pressed keys If called before the USB host has configured the device KEYB ERR NOT CONFIGURED is returned and if an error is reported while attempting to transmit the report KEYB ERR TX ERROR is returned If an attempt is made to remove a key from the pressed list by setting parameter bPressed to false but the key usage code is not found KEYB ERR NOT FOUND is returned 3 18 4 4 USBDHIDKeyboardPowerStatusSet Reports the device power status bus or self powered to the USB library Prototype void USBDHIDKeyboardPowerStatusSet void pvlInstance unsigned char ucPower Parameters pvinstance is the pointer to the keyboard device instance structure ucPower indicates the
278. n this section can be found in header file device usbdmsc h 3 20 2 Data Structure Documentation 3 20 2 1 tMSCDMedia Definition typedef struct void x xOpen unsigned long ulDrive void xClose void pvDrive unsigned long BlockRead void pvDrive unsigned char xpucData unsigned long ul unsigned long ul unsigned long BlockWrite void pvDrive unsigned char xpucData unsigned long ul unsigned long ul Sector INumBlocks Sector NumBlocks unsigned long NumBlocks void xpvDrive tMSCDMedia September 05 2012 181 Device Functions Members Open This function is used to initialize and open the physical drive number associated with the parameter ulDrive The function will return zero if the drive could not be opened for some reason In the case of removable device like an SD card this function should return zero if the SD card is not present The function returns a pointer to data that should be passed to other APIs or it will return 0 if no drive was found Close BlockRead BlockWrite NumBlocks Description Media Access functions 3 20 2 2 tUSBDMSCDevice 182 Definition typedef struct nsigned short usVID nsigned short usPID nsigned char pucVendor 8 nsigned char pucProduct 16 nsigned char pucVersion 4 nsigned short usMaxPowermA nsigned char ucPwrAttributes onst unsigned char xconst xppStringDescript
279. nction is used to retrieve a report from a USB pipe It is usually called when the USB HID layer has detected a new data available in a USB pipe The USB HID host device code will receive a USB_EVENT_RX_AVAILABLE event when data is available allowing the callback function to retrieve the data Returns Returns the number of bytes read from report USBHHIDGetReportDescriptor This function can be used to retrieve the report descriptor for a given device instance Prototype unsigned long USBHHIDGetReportDescriptor unsigned long ulInstance unsigned char xpucBuffer unsigned long ulSize Parameters ullnstance is the value that was returned from the call to USBHHIDOpen pucBuffer is the memory buffer to use to store the report descriptor ulSize is the size in bytes of the buffer pointed to by pucBuffer Description This function is used to return a report descriptor from a HID device instance so that it can determine how to interpret reports that are returned from the device indicated by the ullnstance parameter This call is blocking and will return the number of bytes read into the pucBuffer Returns Returns the number of bytes read into the pucBuffer USBHHIDOpen This function is used to open an instance of a HID device Prototype unsigned long USBHHIDOpen tHIDSubClassProtocol eDeviceType tUSBCallback pfnCallback unsigned long ulCBData Parameters eDeviceType is the type of device that should be
280. nd of the USB OTG B side of the cable Note This function should only be called on devices that support OTG functionality Returns None 2 2 6 14 USBStackModeSet Allows dual mode application to switch between USB device and host modes and provides a method to force the controller into the desired mode Prototype void USBStackModeSet unsigned long ulIndex tUSBMode eUSBMode tUSBModeCallback pfnCallback Parameters ullndex specifies the USB controller whose mode of operation is to be set This parameter must be set to 0 eUSBMode indicates the mode that the application wishes to operate in Valid values are USB MODE DEVICE to operate as a USB device and USB MODE HOST to operate as a USB host pfnCallback is a pointer to a function which the USB library will call each time the mode is changed to indicate the new operating mode In cases where eUSBMode is set to either USB MODE DEVICE or USB MODE HOST the callback will be made immediately to allow the application to perform any host or device specific initialization Description This function allows a USB application that can operate in host or device mode to indicate to the USB stack the mode that it wishes to use The caller is responsible for cleaning up the interface and removing itself from the bus prior to making this call and reconfiguring afterwards The pfnCallback function can be a NULL O0 value to indicate that no notification is required September 05 2012 25
281. ndpoint is used Typically host to device traffic is low bandwidth and endpoint zero communication can be used but if a dedicated endpoint is required the field bUseOutEndpoint in the tUSBDHIDDevice structure for the device should be set to true If using a dedicated endpoint for output and feature reports the application receive callback will be called with USB EVENT RX AVAILABLE whenever a report packet is available During this callback the application can call USBDHIDPacketRead to retrieve the packet If it is not possible September 05 2012 131 Device Functions 3 14 132 to read the packet immediately the HID device class driver will call the application back later to give it another opportunity Until the packet is read NAK will be sent to the host preventing more data from being sent In the more typical case where endpoint zero is used to transfer output and feature reports the application can expect the following sequence of events on the receive callback USBD_HID_EVENT_GET_R EPORT_BUFFER indicates that a Set_Report request has been re ceived from the host and th report can be written The e device class driver is requesting a buffer into which the received application must return a pointer to a buffer which is at least as large as required to store the report USBD_HID_EVENT_SET_R EPORT follows next once
282. never it receives a non standard request pfninterfaceChange Based on the configuration descriptor published by the device code several different alternate inter face settings may be supported In cases where the host wishes to change from the default interface configuration and the USB library determines that the requested alternate setting is supported this callback is made to inform the device code of the change The parameters passed provide the new alternate interface ucAlternateSetting and the interface number ucInterfaceNum This callback is only made once the USB Device API has validated the requested alternate setting If the requested setting is not available in the published configuration descriptor the USB Device API will stall endpoint zero to indicate the error to the host and make no callback to the device code If this member of scallbacks is set to NULL the USB Device API will note the interface change internally but not report it to the device code pfnConfigChange When the host enumerates a device it will ultimately select the configuration that is to be used and send a SET_CONFIGURATION request to the device When this occurs the USB Device API validates the configuration number passed against the device code s published configuration de scriptors then calls the pfnConfigChange callback to inform the device code of the configuration that is to be used If this member of scallbacks is set to NULL the USB Device
283. new buffer to the host audio driver if ulEvent USB EVENT TX COMPLETE USBHostAudioPlay ulAudioInstance pNewBuffer ulSize AudioOutCallback void AudioPlay void Wait for USBH_AUDIO_EVENT_OPEN event ff Set the audio format to 48KHz 16 bit stereo output USBHostAudioFormatSet ulAudioInstance 48000 16 2 USBH AUDIO FORMAT OUT bf Start the output of the first buffer and let the callback start the remaining buffers 724 USBHostAudioPlay ulAudioInstance pBuffer ulSize AudioOutCallback September 05 2012 Host Functions Handle filling returned buffers EA Audio input is handled by setting the format of the audio stream and then by calling the USBHostAu dioRecord function to provide a new buffer to be filled by the host audio driver The callback func tion that is provided with this call returns the buffer when the audio driver has new data available In order for audio input to start the application must first set the audio input format with a successful call to USBHostAudioFormatSet If the format was not supported by the audio device then this function returns a non zero value USBHostAudioRecord should not be called until a valid format is selected Once a valid format is set the application should provide an audio buffer to the host audio driver by calling USBHostAudioRecord and wait for the callback to indicate that the buffer has been filled C
284. ng of USB end point data streams in some applications September 05 2012 7 General Purpose Functions 2 2 usbringbuf c The source code for a set of functions implementing simple ring buffers usbmode c The source code for a set of functions related to switching between host and device modes of operation usbtick c The source code for internal USB library tick handler functions This file does not include any functions accessible by applications usblibpriv h The private header file used to share variables and definitions between the various components of the USB Library Client applications must not include this header Function Definitions Data Structures m tEventinfo Defines m USB DESC ANY m USB EVENT COMP CONFIG m USB EVENT COMP EP CHANGE m USB EVENT COMP IFACE CHANGE m USB EVENT COMP STR CHANGE m USB EVENT CONNECTED m USB EVENT DATA REMAINING m USB EVENT DISCONNECTED m USB EVENT ERROR m USB EVENT POWER DISABLE m USB EVENT POWER ENABLE m USB EVENT POWER FAULT m USB EVENT REQUEST BUFFER m USB EVENT RESUME m USB EVENT RX AVAILABLE m USB EVENT SCHEDULER m USB EVENT SOF m USB EVENT STALL m USB EVENT SUSPEND m USB EVENT TX COMPLETE m USB EVENT UNKNOWN CONNECTED m USBERR DEV RX DATA ERROR m USBERR DEV RX FIFO FULL m USBERR DEV RX OVERRUN m USBERR HOST EPO0 ERROR September 05 2012 2 2 1 General Purpose Functions USBERR HOST EPO NAK TO USBERR HOST IN DATA ERROR
285. nowledgment TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with Tl s standard warranty Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty Except where mandated by government requirements testing of all parameters of each product is not necessarily performed Tl assumes no liability for applications assistance or customer product design Customers are responsible for their products and applications using TI components To minimize the risks associated with customer products and applications customers should provide adequate design and operating safeguards TI does not warrant or represent that any license either express or implied is granted under any TI patent right copyright mask work right or other TI intellectual property right relating to any combination machine or process in which TI products or services are used Information published by TI regarding third party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof Use of such information may require a license from a third party under the patents or other intellectual property of the third party or a license from TI under the patents or other intellectual property of TI Reproduction of TI information in TI data books or data sheets is permissible only if reproduction is without altera
286. nst g ppUSBHostClassDrivers amp g_USBHIDClassDriver H if Register the host class drivers USBHCDRegisterDrivers 0 g_ppUSBHostClassDrivers 1 Open an instance of a HID mouse class driver ulMouseInstance USBHHIDOpen USBH_HID_DEV_MOUSE USBHMouseCallback unsigned long amp g_sUSBHMouse Once a HID device has been opened the first callback it receives is a USB EVENT CONNECTED event indicating that a HID device of the type passed into the USBHHIDOpen has been con nected and the USB library host controller driver has completed enumeration of the device When the HID device has been removed a USB EVENT DISCONNECTED event occurs When shut ting down or to release a device the application should call USBHHIDClose to disable call backs This does not actually power down the device but it stops the driver from calling the ap plication During normal operation the host class driver receives USB_EVENT_SCHEDULER and USB EVENT RX AVAILABLE events The USB EVENT SCHEDULER indicates that the HID class driver should schedule a new request if it is ready to do so This done by calling USBJHCD PipeSchedule to request that a new IN request is made on the given Interrupt IN pipe When the USB EVENT RX AVAILABLE occurs this indicates that new data is available due to completion of the previous request for data on the Interrupt IN pipe The USB EVENT RX AVAILABLE is passed on the device class interface to allow it
287. nstance is the pointer to the device instance structure as returned by USBDCDCInit usState indicates the states of the various control lines and any receive errors detected Bit definitions are as for the USB CDC SerialState asynchronous notification and are defined in header file usbcdc h Description The application should call this function whenever the state of any of the incoming RS232 handshake signals changes or in response to a receive error or break condition The usState parameter is the ORed combination of the following flags with each flag indicating the presence of that condition m USB CDC SERIAL STATE OVERRUN m USB CDC SERIAL STATE PARITY m USB CDC SERIAL STATE FRAMING m USB CDC SERIAL STATE RING SIGNAL m USB CDC SERIAL STATE BREAK m USB CDC SERIAL STATE TXCARRIER m USB CDC SERIAL STATE RXCARRIER This function should be called only when the state of any flag changes Returns None USBDCDCSetControlCBData Sets the client specific pointer for the control callback Prototype void x USBDCDCSetControlCBData void pvInstance void xpvCBData Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDOInit pvCBDaia is the pointer that client wishes to be provided on each event sent to the control channel callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnControlCallback fun
288. nterface and determine how it reports events to the USB host controller The ulInstance value is the value that was returned when the appli cation called USBHMouseOpen This function only needs to be called once per connection event but it should be called every time a USB EVENT CONNECTED event occurs Returns Non zero values should be assumed to indicate an error condition USBHMouseOpen This function is used open an instance of a mouse Prototype unsigned long USBHMouseOpen tUSBCallback pfnCallback unsigned char xpucBuffer unsigned long ulSize Parameters pfnCallback is the callback function to call when new events occur with the mouse returned pucBuffer is the memory used by the driver to interact with the USB mouse ulSize is the size of the buffer provided by pucBuffer Description This function is used to open an instance of the mouse The value returned from this function should be used as the instance identifier for all other USBHMouse calls The pucBuffer mem ory buffer is used to access the mouse The buffer size required is at least enough to hold a normal report descriptor for the device Returns Returns the instance identifier for the mouse that is attached If there is no mouse present this will return 0 Host Programming Examples The USB library provides examples for three host applications that can access mass storage de vices and HID keyboard and mouse devices These next sections cover the basics
289. ntrol driver for the given controller and saves the device information for future use Prior to returning from this function the device is connected to the USB bus Following return the caller can expect to receive a callback to the supplied pfnResetHandler function when a host connects to the device The device information structure passed in psDevice must remain unchanged between this call and any matching call to USBDCDTerm since it is not copied by the USB library September 05 2012 201 Device Functions 3 22 3 3 3 22 3 4 202 The USBStackModeSet function can be called with USB MODE FORCE DEVICE in order to cause the USB library to force the USB operating mode to a device controller This allows the application to used the USBVBUS and USBID pins as GPIOs on devices that support forcing OTG to operate as a device only controller By default the USB library will assume that the USBVBUS and USBID pins are configured as USB pins and not GPIOs Note Forcing of the USB controller mode feature is not available on all Stellaris microcontrollers Consult the data sheet for the microcontroller that the application is using to determine if this feature is available Returns None USBDCDPowerStatusSet Reports the device power status bus or self powered to the library Prototype void USBDCDPowerStatusSet unsigned long ulIndex unsigned char ucPower Parameters ullndex is the index of the USB controller whose devic
290. of RAM that the buffer object can use for workspace Description The structure used by the application to initialize a buffer object that will provide buffered access to either a transmit or receive channel tUSBRingBufObject Definition typedef struct September 05 2012 2 4 4 2 4 4 1 2 4 5 2 4 5 1 2 4 5 2 General Purpose Functions unsigned long ulSize unsigned long ulWriteIndex unsigned long ulReadIndex unsigned char xpucBuf tUSBRingBufObject Members ulSize The ring buffer size ulWritelndex The ring buffer write index ulReadIndex The ring buffer read index pucBuf The ring buffer Description The structure used for encapsulating all the items associated with a ring buffer Define Documentation USB_BUFFER_WORKSPACE_ SIZE Definition define USB BUFFER WORKSPACE SIZE Description The number of bytes of workspace that each USB buffer object requires This workspace memory is provided to the buffer on USBBufferlnit in the pvWorkspace field of the tUSBBuffer structure Typedef Documentation tUSBPacketAvailable Definition typedef unsigned long tUSBPacketAvailable void xpvHandle Description A function pointer type which describes either a class driver transmit or receive packet available function both have the same prototype to the USB buffer object tUSBPacketTransfer Definition typedef unsigned long tUSBPacketTransfer void pvHan
291. of each of these three applications and how they interact with the USB library Application Initialization The USB library host stack initialization is handled in the USBHCDInit function This function should be called after registering class drivers using USBHCDRegisterDrivers and optionally configuring power pins using USBHCDPowerConfiglnit Both of these functions are described later The USBHCDiInit function takes three parameters the first of which specifies which USB controller to initialize This value is a zero based index of the host controller to initialize The next two September 05 2012 273 Host Functions 4 8 2 4 8 3 4 8 4 274 parameters specify a memory pool for use by the host controller driver The size of this buffer should be at least large enough to hold a typical configuration descriptor for devices that are going to be supported This value is system dependent so it is left to the application to set the size however it should never be less than 32 bytes and in most cases should be at least 64 bytes If there is not enough memory to load a configuration descriptor from a device the device is not recognized by USB library s host controller driver The USB library also provides a method to shut down an instance of the host controller driver by calling the USBHCDTerm function The USBHCDTerm function should be called any time the application wants to shut down the USB host controller in order to di
292. of holding the received packet The size of the packet may be determined by calling function USBDHIDRxPacketAvailable prior to reading the packet Receive Operation when not using a dedicated OUT endpoint If no dedicated OUT endpoint is used Output and Feature reports are sent from the host using the control endpoint endpoint zero X When such a report is received USBD HID EVENT GET REPORT BUFFER is sent to the application which must respond with a buffer large enough to hold the report The device class driver will then copy the received report into the supplied buffer before sending USBD HID EVENT SET REPORT to indicate that the report is now available Note The application must not make any calls to the low level USB device interface if interacting with USB via the USB HID device class API Doing so will cause unpredictable though almost certainly unpleasant behavior Returns Returns NULL on failure or the psDevice pointer on success USBDHIDPacketRead Reads a packet of data received from the USB host via the interrupt OUT endpoint if in use Prototype unsigned long September 05 2012 151 Device Functions 3 14 4 4 3 14 4 5 152 USBDHIDPacketRead void pviInstance unsigned char pcData unsigned long ulLength tBoolean bLast Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDInit pcData points to a buffer into which the received data will be w
293. of the configuration steps in the previous section with the exception of calling USBDAudioCompositelnit instead of USBDAu diolnit This will prepare an instance of the audio device class to be enumerated as part of a composite device The return value from the USBDAudioCompositelnit function should be placed in the pvInstance member of the tCompositeEntry structure for the audio device The code example below provides an example of how to initialize the tCompositeEntry structure These should be initialized with valid values for each class extern tUSBDCompositeDevice g_sCompDevice extern tUSBDAudioDevice g_sAudioDevice ff The OTHER_SIZES here are the sizes of the descriptor data for other classes that are part of the composite device Ff define DESCRIPTOR DATA SIZE COMPOSITE DAUDIO SIZE OTHER SIZES unsigned char g pucDescriptorData DESCRIPTOR DATA SIZE tCompositeEntry psCompEntries 2 Set the generic audio device information psCompEntries 0 psDevice g sAudioDeviceInfo Save the instance data for this audio device psCompEntries 0 pvInstance USBDAudioCompositeInit 0 amp g sAudioDevice Initialize other devices to add to the composite device Save the device entries in the composite device g_sCompDevice psDevices psCompEntries September 05 2012 Device Functions USBDCompositeInit 0 amp g sCompDevice DESCRIPTOR DATA SIZ
294. oint descriptor and is expressed in bytes Setting the u Interval parameter depends on the type of endpoint being configured For end points that do not need to use the ulInterval parameter ullnterval should be set to 0 For Bulk 222 September 05 2012 Host Functions ullnterval is a value from 2 16 and will set the NAK timeout value as 2 ulInterval 1 frames For interrupt endpoints ullnterval is a value from 1 255 and is the count in frames between polling the endpoint For isochronous endpoints ulIlnterval ranges from 1 16 and is the polling interval in frames represented as 2 ullnterval 1 frames Parameters ulPipe is the allocated endpoint to modify ulMaxPayload is maximum data that can be handled per transaction ullnterval is the polling interval for data transfers expressed in frames ulTargetEndpoint is the target endpoint on the device to communicate with Returns If the call was successful this function returns zero any other value indicates an error 4 3 4 15 USBHCDPipeDataAck Definition void USBHCDPipeDataAck unsigned long ulPipe Description This function acknowledges data received via an interrupt IN pipe Parameters ulPipe is the USB INT pipe whose last packet is to be acknowledged This function is used to acknowledge reception of data on an interrupt IN pipe A transfer on an interrupt IN endpoint is scheduled via a call to USBHCDPipeSchedule and the application is notified when data is received u
295. ointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manu facturer name string language 1 Product name string language 1 Serial number string language 1 Audio Interface description string language 1 Configuration description string language 1 If supporting more than 1 language the descriptor block except for string descriptor 0 must be repeated for each language defined in the language descriptor ulNumStringDescriptors The number of descriptors provided in the ppStringDescriptors ar ray This must be 1 5 number of strings number of languages September 05 2012 3 4 3 3 4 3 1 3 4 3 2 3 4 3 3 3 4 3 4 Device Functions sVolumeMax The maximum volume expressed as an 8 8 signed value sVolumeMin The minimum volume expressed as an 8 8 signed value sVolumeStep The minimum volume step expressed as an 8 8 signed value psPrivateData A pointer to private instance data for the audio device This memory must remain accessible for as long as the audio device is in use and must not be modified by any code outside the audio class driver Description The structure used by the application to define operating parameters for the device audio class Define Documentation COMPOSITE_DAUDIO_SIZE Definition define COMPOSITE DAUDIO SIZE Description The size of the memory that should be allocat
296. oller driver provides a method to allow applications to only include the host class drivers that are needed for each type of USB device This allows an application to handle multiple classes of devices but only include the USB library code that the application needs to communicate with the devices that the application supports While the host controller driver handles the enumeration of devices it re lies on USB pipes that are allocated by the higher level class drivers as the direct communications method with a devices end points Enumeration The USB host controller driver handles all of the details necessary to discover and enumerate any USB device The USB host controller driver only performs enumeration and relies on the host class drivers to perform any other communications with USB devices including the allocation of the end points for the device Most of the code used to enumerate devices is run in interrupt context and is contained in the enumeration handler In order to complete the enumeration process the host con troller driver also requires that the application periodically call the USBHCDMain function When a host class driver or an application needs access to endpoint 0 of a device it uses the USBHCD ControlTransfer interface to send data to the device or receive data from the device During the September 05 2012 211 Host Functions 4 2 2 4 2 3 212 enumeration process the host controller driver searches a list of
297. on USB CONF ATTR SELF PWR Bus Powered Self Powered remote wakeup 125j The maximum power in 2mA increments J fk kk k k k k k e ke kk ke kk kk Sk kk ke kk khe ke Sk kk ke kk ok kk kk kk kk ke Sk ko ko ok kk kk kk ko ok kk k ok kc I IIR I kk ko ke kk ke ke ke ke The interface and HID descriptors for the keyboard device J f kk kk ke kk ke ke kk ok kk kk kk kk kk khe ke Sk kk kk kk kk kk kk ko ko IR ok kk RIOR IR I IRI IIR I k ke ke oe unsigned char g pHIDInterface HID Device Class Interface Descriptor September 05 2012 Device Functions 9 Size of the interface descriptor USB_DTYPE_INTERFACE Type of this descriptor 0 The index for this interface 0 The alternate setting for this interface 1 The number of endpoints used by this interface USB CLASS HID The interface class USB HID SCLASS BOOT The interface sub class USB HID PROTOCOL KEYB The interface protocol for the sub class specified above 4 The string index for this interface HID Descriptor 9 Size of this HID descriptor USB_HID_DTYPE_HID HID descriptor type USBShort 0x101 Version is 1 1 0 Country code is not specified 1 Number of descriptors USB HID DTYPE REPORT Type of this descriptor USBShort sizeof g pucReportDescriptor Length of the Descriptor E J f kk k k k kk ke kk kk kk kk kk Kok kk ko ke kk
298. on callback with event USB_EVENT_RX_AVAILABLE The application must then call USBDCDCPacketRead passing a buffer capable of holding the received packet to retrieve the data and acknowl edge reception to the USB host The size of the received packet may be queried by calling USBDCDCRxPacketAvailable Note The application must not make any calls to the low level USB Device API if interacting with USB via the CDC device class API Doing so will cause unpredictable though almost certainly unpleasant behavior Returns Returns NULL on failure or the psCDCDevice pointer on success USBDCDCPacketRead Reads a packet of data received from the USB host via the CDC data interface Prototype unsigned long USBDCDCPacketRead void pviInstance unsigned char pcData unsigned long ulLength tBoolean bLast Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDCInit pcData points to a buffer into which the received data will be written ulLength is the size of the buffer pointed to by pcData bLast indicates whether the client will make a further call to read additional data from the packet Description This function reads up to ulLength bytes of data received from the USB host into the supplied application buffer Note The bLast parameter is ignored in this implementation since the end of a packet can be deter mined without relying upon the client to provide this information Return
299. on with the exception of calling USBDBulkCompositelnit instead of USBDBulklnit This will prepare an instance of the bulk device class to be enumerated as part of a composite device The return value from the USBDBulkCompositelnit function should be placed in the pvin stance member of the tCompositeEntry structure for the bulk device The code example below provides an example of how to initialize the tCompositeEntry structure September 05 2012 73 Device Functions 3 5 4 74 These should be initialized with valid values for each class Ff extern tUSBDCompositeDevice g_sCompDevice extern tUSBDBulkDevice g_sBulkDevice The OTHER_SIZES here are the sizes of the descriptor data for other classes that are part of the composite device define DESCRIPTOR DATA SIZE COMPOSITE DBULK SIZE OTHER SIZES unsigned char g pucDescriptorData DESCRIPTOR DATA SIZE tCompositeEntry psCompEntries 2 Set the generic bulk device information psCompEntries 0 psDevice g sBulkDeviceInfo Save the instance data for this bulk device psCompEntries 0 pvInstance USBDBulkCompositeInit 0 amp g sBulkDevice Initialize other devices to add to the composite device Save the device entries in the composite device g_sCompDevice psDevices psCompEntries USBDCompositeInit 0 amp g sCompDevice DESCRIPTOR DATA SIZE g pucDescriptorData All other API cal
300. onses to be provided when the host requests status from the device Returns None USBDBulkRemoteWakeupRequest Requests a remote wake up to resume communication when in suspended state Prototype tBoolean USBDBulkRemoteWakeupRequest void xpvInstance Parameters pvinstance is the pointer to the bulk device instance structure Description When the bus is suspended an application which supports remote wake up advertised to the host via the configuration descriptor may call this function to initiate remote wake up signaling to the host If the remote wake up feature has not been disabled by the host this will cause the bus to resume operation within 20mS If the host has disabled remote wake up false will be returned to indicate that the wake up request was not successful Returns Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previous call to this function September 05 2012 3 6 4 7 3 6 4 8 3 6 4 9 Device Functions USBDBulkRxPacketAvailable Determines whether a packet is available and if so the size of the buffer required to read it Prototype unsigned long USBDBulkRxPacketAvailable void pvlInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDBUlklnit Description This function may be used to determine if a received packet r
301. ontal lines represent APIs that are available for application use Four possible applications are shown each using a different programming interface to implement their USB functionality The following sections provide an overview of the features and limitations of each layer and indicate the kinds of application which may choose to use that layer USB DriverLib API The lowest layer in the USB device stack is the USB driver which can be found within the Stellaris Peripheral Driver Library DriverLib with source code in usb c and header file usb n Application 1 in the previous diagram offers device functionality by writing directly to this API Due to the fact that this API is a very thin layer above the USB controllers hardware registers and hence does not offer any higher level USB transaction support such as endpoint zero transaction processing standard descriptor and request processing etc applications would not typically use this API as the only way to access USB functionality This driver would however be a suitable interface to use if developing for example a third party USB stack USB Device API The USB Device API offers a group of functions specifically intended to allow development of fully featured USB device applications with as much of the class independent code as possible con tained in the USB Library The API supports device enumeration via standard requests from the host and handles the endpo
302. ors nsigned long ulNumStringDescriptors SCDMedia sMediaFunctions USBCallback pfnEventCallback SCInstance psPrivateData Gh iG XXn O oque Cr Ope AGS b tUSBDMSCDevice Members usVID The vendor ID that this device is to present in the device descriptor usPID The product ID that this device is to present in the device descriptor pucVendor 8 byte vendor string pucProduct 16 byte vendor string pucVersion 4 byte vendor string usMaxPowermA The maximum power consumption of the device expressed in milliamps ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wakeup Valid values are USB CONF ATTR SELF PWR or USB CONF ATTR BUS PWR optionally ORed with USB CONF ATTR RWAKE ppStringDescriptors A pointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manu facturer name string language 1 Product name string language 1 Serial number string language 1 MSC Interface description string language 1 Configuration description string language 1 If supporting more than 1 language the descriptor block except for string descriptor 0 must be repeated for each language defined in the language descriptor September 05 2012 Device Functions ulNumStringDescriptors The number of descriptors provided in the ppStringDescriptors ar ray This must be
303. ors that this device publishes The actual number of entries in the array is given by the bNumDescriptors field Description The HID descriptor is inserted following the interface descriptor and before the endpoint de scriptors for a HID class device tHIDKeyboardUsage Table Definition typedef struct unsigned char ucBytesPerChar unsigned long pulCapsLock USBH HID CAPS ARRAY SZ void xpCharMapping tHIDKeyboardUsageTable Members ucBytesPerChar Number of bytes per character in the pCharMapping table of this structure pulCapsLock This is a packed bitmasked structure with a one bit flags that indicates if the corresponding Usage ID is affected by the Caps Lock key pCharMapping This is the indexed table of Usage ID to character value It must be at least ucBytesPerChar 2 USBH HID MAX USAGE bytes in size as it is treated as a double indexed array Description This structure defines the mapping of USB usage identifiers to printable characters The struc ture has three members that hold this information The ucBytesPerChar indicates the number of bytes per character in the table The pulCapsLock array holds a packed bit array of usage identifiers that can be modified by the Caps Lock key The pCharMapping array is treated as a double indexed array with two columns In the case of a single byte character it is treated as pairs of 8 bit values for unshifted and shifted values In the case of a double byte characters it
304. ort is the port on the hub to which the downstream device is attached Description This function is called by the host controller driver to inform the hub class driver that a down stream device has been enumerated successfully The hub driver then moves on and continues enumeration of any other newly connected devices Returns None USBHHubEnumerationError Informs the hub class driver that a downstream device failed to enumerate Prototype void USBHHubEnumerationError unsigned char ucHub unsigned char ucPort Parameters ucHub is the address of the hub to which the downstream device is attached ucPort is the port on the hub to which the downstream device is attached Description This function is called by the host controller driver to inform the hub class driver that an attempt to enumerate a downstream device has failed The hub driver then cleans up and continues enumeration of any other newly connected devices Returns None USBHHubOpen This function is used to enable the host hub class driver before any devices are present September 05 2012 251 Host Functions 4 5 4 12 252 Prototype unsigned long USBHHubOpen tUSBCallback pfnCallback unsigned char xpucHubPool unsigned long ulPoolSize tHubInstance xpsHubInstance unsigned long ulNumHubs Parameters pfnCallback is the driver call back for host hub events pucHubPool is the memory pool allocated to the USB hub class
305. ort which can be accessed by any serial terminal application USB CDC Device Model Receive Channel Bulk OUT Optional mm zem gt _ gt USB J a 5 Buffer Interrupt IN a gt neea eet 3 p Sa a s 5 Transmit Channel O z E 8 a c m Bulk IN aj 29 i Optional S o mi A USB e S 2 m 9 Buffer 2 G SENSE E Endpoint 0 Control Channel m This device class uses three endpoints in addition to endpoint zero Two bulk endpoints carry data to and from the host and an interrupt IN endpoint is used to signal any serial errors such as break framing error or parity error detected by the device Endpoint zero carries standard USB requests and also CDC specific requests which translate to events passed to the application via the control channel callback The usb dev serial example application makes use of this device class driver CDC Device Class Events The CDC device class driver sends the following events to the application callback functions September 05 2012 87 Device Functions 3 7 1 1 Receive Channel Events m USB m USB m USB F EVENT RX AVAILABLE EVENT DATA R VENT ERROR EMAINING 3 7 1 2 Transmit Channel Events m USB F VENT TX COMPLETE H 3 7 1 3 Control Channel Events U U
306. orts that this device supports This field must equal the number of reports published in the HID class descriptors for the device and also the number of entries in the array whose first element is pointed to by field psReportldle below psReportldle A pointer to the first element in an array of structures used to track idle time for each Input report When USBDHIDInit is called the ucDuration4mS and ucReportID fields of each of these array members should be initialized to indicate the default idle timeout for each input report This array must be in RAM since the HID device class driver will update values in it in response to requests from the host and to track elapsed time The number of elements in the array must match the number supplied in the ucNumInputReports field above pfnRxCallback A pointer to the callback function which will be called to notify the application of general events events related to report transfers on endpoint zero and events related to reception of Output and Feature reports via the optional interrupt OUT endpoint pvRxCBData A client supplied pointer which will be sent as the first parameter in all calls made to the receive channel callback pfnRxCallback pfnTxCallback A pointer to the callback function which will be called to notify the application of events related to transmission of Input reports via the interrupt IN endpoint pvTxCBData A client supplied pointer which will be sent as the first parameter in all calls
307. ost h 4 3 2 Data Structure Documentation 4 3 2 4 tUSBHostClassDriver Definition typedef struct unsigned long ulInterfaceClass void xpfnOpen tUSBHostDevice xpDevice void xpfnClose void xpvInstance void xpfnIntHandler void pvInstance tUSBHostClassDriver Members 214 ullnterfaceClass The interface class that this device class driver supports pfnOpen The function is called when this class of device has been detected September 05 2012 Host Functions pfnClose The function is called when the device originally opened with a call to the pfnOpen function is disconnected pfnintHandler This is the optional interrupt handler that will be called when an endpoint asso ciated with this device instance generates an interrupt Description This structure defines a USB host class driver interface it is parsed to find a USB class driver once a USB device is enumerated 4 3 2 2 tUSBHostDevice Definition typedef struct unsigned long ulAddress unsigned long ulInterface tBoolean bNotifyInt tBoolean bLowSpeed tBoolean bConfigRead unsigned char ucHub unsigned char ucHubPort tDeviceDescriptor DeviceDescriptor tConfigDescriptor xpConfigDescriptor unsigned long ulConfigDescriptorSize tUSBHostDevice Members ulAddress The current device address for this device ullnterface The current interface for this device bNotifyint A flag used to determine whe
308. otherwise be required These drivers provide high level APIs for several commonly used USB device classes with the following features m Extremely easy to use Device setup involves creating a set of static data structures and calling a single initialization API Configurable VID PID power parameters and string table to allow easy customization of the device without the need to modify any library code Consistent interfaces All device class drivers use similar APIs making it very straightforward to move between them m Minimal application overhead The vast majority of USB handling is performed within the class driver and lower layers leaving the application to deal only with reading and writing data m May be used with optional USB buffer objects to further simplify data transmission and recep tion Using USB buffers interaction with the device class driver can become as simple as a read write API with no state machine required to ensure that data is transmitted or received at the correct time m Device Class Driver APIs completely wrap the underlying USB Device and USB Driver APIs so only a single API interface is used by the application Balancing these advantages application developers should note the following restrictions that apply when using the Device Class Driver APIs m No calls may be made to any other USB layer while the device class driver API is in use m Alternate configurations are not supported by the supplied devic
309. ould not be accessed by the application In order to release an instance of a hub class driver the application must call USBHHubClose This call to USBHHub Close is only made if the application is shutting down the USB interface or when in OTG mode switching roles from host to device Example USB Hub with Keyboard and MSC support J f kk kk k k k k ke kk ko ke kk kk Kk Kk kk ko ke kk ko ke kk kk kk kk ko kk ke kk k K KK CK Kk kk ko ke kk ko I kk k K kk ko ke k k k ke ke e The size of the host controller s memory pool in bytes Mette eee eee eee k k k k k k k k k k k k k k ee k k k k k k k k k k k k k k k k k k k k k kckckckckck ck ckckckckckckckckckck ck ckckck ck ck k k k define HCD_MEMORY_SIZE 128 J f kk k k k k e kk ke kk ke kk kk Kk Kk kk kk kk ko ke KR IR kk K IIR OR IR IR k k k k k K k k IK k k k k k k k September 05 2012 233 Host Functions The memory pool to provide to the Host controller driver J f kk kk RR kk Kok ROR kk ko ke kk Kok RRR kk ko ko RR IR IR I IR IR I IIR k k Ke ke ke e unsigned char g pHCDPool HCD MEMORY SIZE J f kk k k k kk oko ke kk Kok kk Kk kk Kok kk kk kk Kok kk kk kk kk kk ko koc k kk K kk ko Kok kk kk kk k k kk Kok I kk kk kk Ke ke ke e fih The size of the host controller s memory pool in bytes J f kk kk k k k k k ke kk koe kk Kk kk Kok kk ko ke kk Kok kk kk kk ko kk ko ko kk ko Kk Kk Kk kk kk kk K k k II kk kk kk Ke ke ke e define HUB POOL SIZE HC
310. ous call to this function USBDCDhRequestDataEPO This function starts the request for data from the host on endpoint zero Prototype void USBDCDRequestDataEPO unsigned long ulIndex unsigned char xpucData unsigned long ulSize Parameters ullndex is the index of the USB controller from which the data is being requested pucDat a is a pointer to the buffer to fill with data from the USB host ulSize is the size of the buffer or data to return from the USB host Description This function handles retrieving data from the host when a custom command has been is sued on endpoint zero If the application needs notification when the data has been received tDeviceInfo sCallbacks pfnDataReceived should contain valid function pointer In nearly all cases this is necessary because the caller of this function would likely need to know that the data requested was received Returns None USBDCDSenaDataEPO This function requests transfer of data to the host on endpoint zero Prototype void USBDCDSendDataEPO unsigned long ulIndex unsigned char pucData unsigned long ulSize Parameters ullndex is the index of the USB controller which is to be used to send the data pucData is a pointer to the buffer to send via endpoint zero ulSize is the amount of data to send in bytes September 05 2012 203 Device Functions Description This function handles sending data to the host when a custom comman
311. pInstance TTC Sk kk ke kk kk kk kk kk K k ko kk K kk ko ke kk k k k k k K k k K k k K k k K k k k k k k k k k k k K k k k k k k k k k k k k k k k k Allocate the Device Data for the top level composite device class J f kk kk ko ke k k k ke kk k A kk ko ke kk kk kk A kk A k kk k k K k k K K K K k k K k k K k k k k k k k k k k k K k k k k k k k k k k k k k k k k tUSBDCompositeDevice g_sCompDevice September 05 2012 Device Functions Stellaris VID USB_VID_STELLARIS Stellaris PID for composite HID DFU device USB_PID_COMP_HID_DFU This is in milliamps 500 Bus powered device USB_CONF_ATTR_BUS_PWR Device event handler function pointer receives connect disconnect and other device level notifications DeviceHandler The string table This is the string table for the main device no DFU strings are required g_pStringDescriptors NUM_STRING_DESCRIPTORS The Composite device array NUM_DEVICES g_psCompDevices Additional workspace g_pulCompWorkspace Composite device instance data LT amp g CompInstance di J kk kk ko kk k k kk koe kk koe kk Kk kk Kok kk ko ke kk kk kk kk ko kk ko kk kk kk k Kk k k k k k k k k k k k k k k k k k k k k k k A buffer into which the composite device can write the combined config descriptor J kk k k k k k k k k k kk k
312. ppHostClassDrivers amp g_USBHostMSCClassDriver amp g_USBHIDClassDriver amp g_USBHubClassDriver amp g sUSBEventDriver TKK k k k k A H KR IRR kk ko ke RR KR kk Kok OR IR IR IR IR IR K k k IR k k k k k k The global that holds the number of class drivers in the g_ppHostClassDrivers list TKK k k k k k RR kk Kok kk Kok OR kk Kok KR RR KR RR IR IR k k RI K k k IR k k k oe static const unsigned long g_ulNumHostClassDrivers sizeof g_ppHostClassDrivers sizeof tUSBHostClassDriver Initialize the USB stack mode to host II USBStackModeSet 0 USB_MODE_HOST 0 Register the host class drivers USBHCDRegisterDrivers 0 g ppHostClassDrivers g ulNumHostClassDrivers Open the Keyboard and Mass storage interfaces Ju 234 September 05 2012 4 4 3 Host Functions KeyboardOpen MSCOpen Open a hub instance and provide it with the memory required to hold configuration descriptors for each attached device and the private hub instance data USBHHubOpen HubCallback g_pucHubPool HUB_POOL_SIZE amp g_HubInstance Initialize the power configuration by configuring the power enable signal to be active high and not enabling the power fault USBHCDPowerConfigInit 0 USBHCD VBUS AUTO HIGH USBHCD VBUS FILTER 4 Initialize the USB controller for OTG operation with a 2ms polling rate HCDInit 0 g pHCDPool HC
313. pplication or a transmit buffer accepting data from the application and passing it to the USB controller for transmission In each case the buffer handles all packetization or depacketization of data and allows the application to read or write arbitrarily sized blocks of data subject to the space limitations in the buffer of course at times suitable to it Each USB buffer makes use of a ring buffer object to store the buffered data The ring buffer object is not USB specific and does not interact directly with any USB drivers but the API is made available since the functionality may be useful to an application in areas outside USB communication for September 05 2012 35 General Purpose Functions 2 4 2 36 example to buffer data from a UART or other peripheral If attempting to buffer a USB data stream however the USB buffer API should be used since it handles the USB driver side interaction on behalf of the application An application must not mix calls to the two APIs for the same object if using a USB buffer only APIs of the form USBBufferXxx should be used to access that buffer and similarly if using a plain ring buffer only USBRingBufXxx calls must be used Source for the USB buffer and ring buffer functions can be found in files usbbuffer c and usbringbuf c Header file usblib h contains prototypes and data type definitions for these functions Using USB Buffers The USB buffer object is designed to allow insertion
314. ptember 05 2012 183 Device Functions 3 20 3 4 3 20 4 3 20 4 1 3 20 4 2 184 USBD_MSC_EVENT_WRITING Definition define USBD_MSC_EVENT_WRITING Description This event indicates that the host is writing to the storage media Function Documentation USBDMSCCompositelnit This function should be called once for the mass storage class device to initialized basic operation and prepare for enumeration Prototype void x USBDMSCCompositeInit unsigned long ulIndex const tUSBDMSCDevice xpsDevice Parameters ullndex is the index of the USB controller to initialize for mass storage class device operation psDevice points to a structure containing parameters customizing the operation of the mass storage device Description In order for an application to initialize the USB device mass storage class it must first call this function with the a valid mass storage device class structure in the psDevice parameter This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB mass storage device This function returns a void pointer that must be passed in to all other APIs used by the mass storage class See the documentation on the tUSBDMSCDevice structure for more information on how to properly fill the structure members Returns Returns 0 on failure or a non zero void pointer on success USBDMSCInit This function should be called onc
315. ptember 05 2012 195 Device Functions 3 21 3 3 21 4 3 21 5 196 form the class of interface endpoint and string index changes See the documenta tion on the USB EVENT COMP IFACE CHANGE USB EVENT COMP EP CHANGE and USB EVENT COMP STR CHANGE USB FIFO Configuration The USB controller FIFO must be partitioned appropriately between the various endpoints that an application is using Although the actual configuration is performed within the USB library the application must pass a structure to indicate any special sizing or FIFO configuration considerations that need to be taken into account The tFIFOConfig structure contains two arrays the first defining FIFO configuration parameters for each of the 3 IN endpoints and the second containing the same information for the 3 OUT endpoints Endpoint zero is handled independently and uses a fixed FIFO configuration A pointer to this structure is passed to USBCDOInit in the psFIFOConfig field of the tDeviceInfo structure If the application does not wish to use any special features such as DMA or double buffering the field can be initialized using global pointer g_sUSBDefaultFIFOConfig which configures the FIFO to buffer one full packet for each endpoint in use If the default FIFO configuration is not suitable declare a new tFIFOConfig structure and com plete all fields before setting psF 1TFOConfig to point to it For each endpoint the relevant structure entry allows
316. ption This function should be called by an application when it detects a change in the status of the media in use by the USB mass storage class The eMediaStatus parameter will indicate the new status of the media and can also indicate that the application has no knowledge of the media state There are currently the three following values for the eMediaStatus parameter m USBDMSC MEDIA PRESENT indicates that the media is present or has been added m USBDMSC MEDIA NOTPRESENT indicates that the media is not present or was re moved m USBDMSC MEDIA UNKNOWN indicates that the application has no knowledge of the media state and the USB mass storage class It will be left up to the application to call this function whenever it detects a change or simply call it once with USBDMSC MEDIA UNKNOWN and allow the mass storage class to infer the state from the remaining device APIs Note It is recommended that the application use this function to inform the mass storage class of media state changes as it will lead to a more responsive system Returns None September 05 2012 185 Device Functions 3 20 4 4 USBDMSCTerm 3 21 3 21 1 186 Shuts down the mass storage device Prototype void USBDMSCTerm void xpvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDMSCInit or USBDMSClnitComposite Description This function terminates mass storage operation for the instance supplied
317. ptor This will be USB HID DTYPE REPORT or USB HID DTYPE PHYSICAL wDescriptorLength The total length of the HID class descriptor Description The class descriptor information structure is used to announce the presence of HID specific class descriptors within the HID descriptor tHIDDescriptor Definition typedef struct unsigned char bLength unsigned char bDescriptorType unsigned short bcdHID unsigned char bCountryCode unsigned char bNumDescriptors tHIDClassDescriptorInfo sClassDescriptor 1 tHIDDescriptor Members bLength The length of this descriptor in bytes bDescriptorType The type of the descriptor For a HID descriptor this will be USB HID DTYPE HID 0x21 bcdHID A BCD value identifying the HID Class specification release supported by the device For version 1 11 for example this value would be 0x01 11 bCountryCode The country code for which this hardware is localized or O if no localiza tion has been performed Valid country or language codes are in labels of the form USB HID COUNTRY xxx September 05 2012 3 14 2 3 3 14 2 4 Device Functions bNumDescriptors The number of class specific descriptors that exist for this device This indicates the number of class descriptor information structures that are appended to this structure and must be at least 1 since all HID devices must publish at least 1 report descriptor sClassDescriptor A table announcing each of the class specific descript
318. ptor block Definition define USBLong ulValue Parameters ulValue is the four byte unsigned long that is to be written to the descriptor Description This helper macro is used in descriptor definitions to write four byte values Since the con figuration descriptor contains all interface and endpoint descriptors in a contiguous block of September 05 2012 33 General Purpose Functions 2 3 3 4 2 4 34 memory these descriptors are typically defined using an array of bytes rather than as packed structures Returns Not a function USBShort Write a 2 byte unsigned short value to a USB descriptor block Definition define USBShort usValue Parameters usValue is the two byte unsigned short that is to be written to the descriptor Description This helper macro is used in descriptor definitions to write two byte values Since the con figuration descriptor contains all interface and endpoint descriptors in a contiguous block of memory these descriptors are typically defined using an array of bytes rather than as packed structures Returns Not a function USB Buffer and Ring Buffer APIs Data Structures m tUSBBuffer m tUSBRingBufObject Defines m USB BUFFER WORKSPACE SIZE Functions void x USBBufferCallbackDataSet tUSBBuffer psBuffer void pvCBData unsigned long USBBufferDataAvailable const tUSBBuffer psBuffer void USBBufferDataRemoved const tUSBBuffer psBuffer unsigned long ulLengt
319. pvControlCBData USBCallback pfnRxCallback oid xpvRxCBData USBCallback pfnTxCallback oid xpvTxCBData onst unsigned char xconst ppStringDescriptors nsigned long ulNumStringDescriptors tCDCSerInstance xpsPrivateCDCSerData co 4 ct 4 t 4 t amp o oG B tUSBDCDCDevice Members usVID The vendor ID that this device is to present in the device descriptor usPID The product ID that this device is to present in the device descriptor 96 September 05 2012 3 8 3 3 8 3 1 3 8 3 2 Device Functions usMaxPowermA The maximum power consumption of the device expressed in milliamps ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wakeup Valid values are USB_CONF_ATTR_SELF_PWR or USB_CONF_ATTR_BUS_PWR optionally ORed with USB_CONF_ATTR_RWAKE pfnControlCallback A pointer to the callback function which will be called to notify the appli cation of all asynchronous control events related to the operation of the device pvControlCBData A client supplied pointer which will be sent as the first parameter in all calls made to the control channel callback pfnControlCallback pfnRxCallback A pointer to the callback function which will be called to notify the application of events related to the device s data receive channel pvRxCBData A client supplied pointer which will be sent as the first parameter in all calls made to the receive channel callb
320. pvInstance unsigned char pcData unsigned long ulLength tBoolean bLast m unsigned long USBDBulkPacketWrite void pvlnstance unsigned char pcData unsigned long ulLength tBoolean bLast void USBDBulkPowerStatusSet void pvInstance unsigned char ucPower tBoolean USBDBulkRemoteWakeupRequest void pvInstance unsigned long USBDBulkRxPacketAvailable void pvInstance void x USBDBulkSetRxCBData void pvInstance void pvCBData void x USBDBulkSetTxCBData void xpvInstance void pvCBData void USBDBulkTerm void pvinstance unsigned long USBDBulkTxPacketAvailable void pvInstance September 05 2012 79 Device Functions 3 6 1 Detailed Description The macros and functions defined in this section can be found in header file device usbdbulk h 3 6 2 Data Structure Documentation 3 6 2 1 tUSBDBulkDevice Definition typedef struct nsigned short usVID nsigned short usPID nsigned short usMaxPowermA nsigned char ucPwrAttributes USBCallback pfnRxCallback oid xpvRxCBData USBCallback pfnTxCallback oid xpvTxCBData onst unsigned char xconst ppStringDescriptors nsigned long ulNumStringDescriptors tBulkInstance psPrivateBulkData G Q4 tct4 ct oc c c gc tUSBDBulkDevice Members 80 usVID The vendor ID that this device is to present in the device descriptor usPID The product ID that this device is to present in the device descriptor usMaxPowermA The maximu
321. r unsigned long ulSize tUSBHostAudioCallback pfnCallback September 05 2012 257 Host Functions Parameters ullnstance specifies the device instance for this call pvBuffer is the audio buffer to send ulSize is the size of the buffer in bytes pfnCallback is a pointer to a callback function that is called when the buffer has been filled Description This function is called when an application needs to schedule a new buffer for input from the USB audio device Since this call schedules the transfer and returns immediately the application should provide a pfnCallback function to be notified when the buffer has been filled with audio data When the pfnCallback function is called the pvBuffer parameter is set to pvBuffer provided in this call the u Param is the number of valid bytes in the pvBuffer and the ulEvent is set to USB EVENT RX AVAILABLE Returns This function returns the number of bytes that were scheduled to be sent If this function returns zero then there was no USB audio device present or the device does not support audio input 4 5 4 3 USBHostAudioVolumeGet This function is used to get the current volume setting for a given audio device Prototype unsigned long USBHostAudioVolumeGet unsigned long ulInstance unsigned long ulInterface unsigned long ulChannel Parameters ullnstance is an instance of the USB audio device ullnterface is the interface number to use to query
322. r of this interface This is a zero based index into the array of concurrent interfaces supported by this configuration bAlternateSetting The value used to select this alternate setting for the interface defined in bInterfaceNumber bNumEndpoints The number of endpoints used by this interface excluding endpoint zero binterfaceClass The interface class code as assigned by the USB IF binterfaceSubClass The interface subclass code as assigned by the USB IF binterfaceProtocol The interface protocol code as assigned by the USB IF ilnterface The index of a string descriptor describing this interface Description This structure describes the USB interface descriptor as defined in USB 2 0 specification sec tion 9 6 5 tStringODescriptor Definition typedef struct unsigned char bLength unsigned char bDescriptorType unsigned short wLANGID 1 tStringODescriptor Members bLength The length of this descriptor in bytes This value will vary depending upon the number of language codes provided in the descriptor bDescriptorType The type of the descriptor For a string descriptor this will be USB DTYPE STRING 3 WLANGID The language code LANGID for the first supported language Note that this de scriptor may support multiple languages in which case the number of elements in the wLANGID array will increase and bLength will be updated accordingly Description This structure describes the USB string descriptor for ind
323. r use by the mouse device The buffer provided is used internally by the mouse device and should not be used by the application Once the device has been opened the application should wait fora USB EVENT CONNECTED event to indicate that a mouse has been successfully detected and enumerated At this point the application should call the USBHMouselnit function to initialize the actual device that is connected After this the application can expect to start receiving the following events via the callback that was provided in the USBHMouseOpen call m USBH EVENT HID MS PRESS m USBH EVENT HID MS REL m USBH EVENT HID MS X m USBH EVENT HID MS Y USBH EVENT HID MS PRESS The ulMsgParam parameter has one of the following values HID MOUSE BUTTON 1 HID MOUSE BUTTON 2 HID MOUSE BUTTON 3 indicating which buttons have changed to the pressed state USBH EVENT HID MS REL The ulMsgParam parameter has one of the following values HID MOUSE BUTTON 1 HID MOUSE BUTTON 2 HID MOUSE BUTTON 3 indicating which buttons have changed to the released state USBH EVENT HID MS X The ulMsgParam parameter has an 8 bit signed value indicating the delta in the X direction since the last update USBH EVENT HID MS Y The ulMsgParam parameter has an 8 bit signed value indicating the delta in the Y direction since the last update When the application is done using the mouse device it can call USBHMouseClose to release the instance of the mouse dev
324. ration of the HID mouse device Description An application wishing to offer a USB HID mouse interface to a USB host must call this function to initialize the USB controller and attach the mouse device to the USB bus This function performs all required USB initialization On successful completion this function will return the psDevice pointer passed to it This must be passed on all future calls to the HID mouse device driver When a host connects and configures the device the application callback will receive USB EVENT CONNECTED after which calls can be made to USBDHIDMouseStateChange to report pointer movement and button presses to the host Note The application must not make any calls to the lower level USB device interfaces if interacting with USB via the USB HID mouse device API Doing so will cause unpredictable though almost certainly unpleasant behavior Returns Returns NULL on failure or the psDevice pointer on success USBDHIDMousePowerStatusSet Reports the device power status bus or self powered to the USB library September 05 2012 3 16 4 4 3 16 4 5 Device Functions Prototype void USBDHIDMousePowerStatusSet void xpvInstance unsigned char ucPower Parameters pvinstance is the pointer to the mouse device instance structure ucPower indicates the current power status either USB STATUS SELF PWR or USB STATUS BUS PWR Description Applications which support switching between bus or self pow
325. rees with the list published in string descriptor 0 g pLangDescriptor The strings for each language must be grouped together with all the language 1 strings before all the language 2 strings and so on September 05 2012 Device Functions T amp R OK ROR RR OR IR RR kk Kok kk kk RRR OR IRR OR IR I I AI kk A Ik oe The languages supported by this device J kk KOK RRR RRR RRR RRR kk ko ko IR IRR I IR IR IA ke kk ko ke ek Ke ee const unsigned char g pLangDescriptor 4 USB DTYPE STRING USBShort USB LANG EN US di J kk kk RRR RRR kk Kok IRR RRR IR OR IR OR I I A I I ek Ke ee The manufacturer string J kk KOK ROKR KR kk Kok kk Kok RR OR IRR kk kk kk ko ko IR RR RR IR I A I A IK oe const unsigned char g_pManufacturerString 2 19 2 USB_DTYPE_STRING 5 0 iut Oy my 0 I xs 0 n 0 Tat 0 rey 0 LY 0 r a 0 UM 0 ri Cyr tret cp yrs O di J kk kk ROR ROKR ROR OR ORR ROKR IR IR IRR IR IR IR I A kk ko ke ke ke e oe The product string J kk ke kk RK RR RI IR RR IR IR IR IR IR I I I OK kok const unsigned char g_pProductString 2 t 16 2 USB DTYPE STRING PE 0 Ex y 0 ety 0 DEUS 0 qp 0 at 0 LEty 0 i Mer 0 rae ug 0 BON 0 DMU 0 T Ds 0 P 0 Det 0 t y 0 nEES 0 J kk kk kk ke kk oko kk Kok kk Kok kk ck ok kk Kok kk koe ko kk ok kk kk kk kk kk kk kk kk IR IR IR I kk Kok kk ko ke ek Ke ee The serial number string J
326. reported in string descriptor 0 you must ensure that you have strings available for each language with all language 1 strings occurring in order in a block before all language 2 strings and so on J kk ke koe kk ko ke kk ke kk kk kk kk kk Kok kk kk kk kk kk kk kk kk kk ko ko ok kk Kk kk Kock kk ko ke kk ko ke kk ko ke kk ko ke e ke e ee The languages supported by this device J kk ek ko ke ek kk ek khe kk kk ke kk ke ek ee ee ee eee eee ee ee kk ck ck kk ck ck kk ck ck ck ck ck ck kckckckckckckckckck ck ckckck ck oko const unsigned char g pLangDescriptor 4 USB_DTYPE_STRING USBShort USB_LANG_EN_US hi J kk kk ROKR KR IRR RR I ko kk ke kk Kok kk ko ko OR IR IR IIR IR ke kk A I I I ke ee The manufacturer string J f kk kk ROKR KR IRR ke kk ke I ke kk ke Kk Kok RR IR IIR IR I I I oe const unsigned char g_pManufacturerString 2 19 2 USB_DTYPE_STRING L 0 u 0 m 0 i O n O a 0 r 0 y 0 o 0 M Or Tarp O c 0 r 0 o 0 O I O rto up cce Qu futs 124 September 05 2012 Device Functions hi J kk kk kk ke kk oko ke kk kk RR ORR OR IRR RR OR OR RR OR OR IR I A I IK oe The product string J kk KR KR RR RR A RR IR IR I IR IR IR I I OR OK ok const unsigned char g pProductString 13 1 gt 2 USB DTYPE STRING CM 05 Op 0 ps7 ares Qu s 7 0 OS Op oes ou EU 0 xU OP Cats 0 Emig 0 Cp 0 154505
327. riptors member would be set to the number of elements in the g_ppStringDescriptors array USB Event Handlers The majority of the work in a USB device application will be carried out either in the context of or in response to callbacks from the USB Device API These callback functions are made available to the USB Device API in the scallbacks field of the tDeviceInfo structure passed in a call to September 05 2012 191 Device Functions 3 21 2 1 3 21 2 2 192 USBDCDInit Field sCallbacks is a structure of type tCustomHandlers which contains a function pointer for each USB event The application must populate the table with valid function pointers for each event that it wishes to be informed of Setting any function pointer to NULL disables notification for that event The tCustomHandlers structure contains the following fields m pfnGetDescriptor m pfnRequestHandler m pfninterfaceChange m pfnConfigChange m pfnDataReceived m pfnDataSent m pfnResetHandler m pfnSuspendHandler m pfnResumeHandler m pfnDisconnectHandler m pfnEndpointHandler m pfnDeviceHandler Note that all callbacks except the pfnDeviceHandler entry are made in interrupt context It is therefore vital that handlers do not block or make calls to functions which cannot safely be made in an interrupt handler pfnGetDescriptor Standard USB device configuration and string descriptors are handled by the USB Device API internally but some device classes
328. ritten ulLength is the size of the buffer pointed to by pcData bLast indicates whether the client will make a further call to read additional data from the packet Description This function reads up to ulLength bytes of data received from the USB host into the supplied application buffer If the driver detects that the entire packet has been read it is acknowledged to the host The bLast parameter is ignored in this implementation since the end of a packet can be deter mined without relying upon the client to provide this information Returns Returns the number of bytes of data read USBDHIDPowerStatusSet Reports the device power status bus or self powered to the USB library Prototype void USBDHIDPowerStatusSet void xpvInstance unsigned char ucPower Parameters pvinstance is the pointer to the HID device instance structure ucPower indicates the current power status either USB STATUS SELF PWR or USB STATUS BUS PWR Description Applications which support switching between bus or self powered operation should call this function whenever the power source changes to indicate the current power status to the USB library This information is required by the USB library to allow correct responses to be provided when the host requests status from the device Returns None USBDHIDRemoteWakeupRequest Requests a remote wake up to resume communication when in suspended state September 05 2012 Device Function
329. river has a device class interface for used by various HID devices In order for the HID class driver to recognize a device the device class is respon sible for calling the USBHHIDOpen This call specifies the type of device and a callback for this device type so that any events related to this device type can be passed back to the device class driver The defined classes are in the type defined values in the tHIDSubClassProtocol type and are passed into the USBHHIDOpen call via the eDeviceType parameter In order to release an instance of a HID class driver the HID device class or application must call the USBHHIDClose to September 05 2012 235 Host Functions 4 4 4 236 allow a new or different type of device to be connected In the examples provided in the USB library the report descriptors are retrieved but are not used as the examples rely on the boot mode of the USB keyboard and mouse to fix the format of the report descriptors This is accomplished by using the USBHHIDSetReport interface to force the device into its boot protocol mode As this could be limiting or not available in other types of applications or devices the USBHHIDGetReportDe scriptor provides the ability of a generic HID device to query the device for its report descriptor s The last two remaining HID interfaces USBHHIDSetReport and USBHHIDGetReport provide access to the HID reports Example Adding HID Class Driver const tUSBHostClassDriver co
330. rm a block sized write to the device associated with the ullnstance pa rameter The u LBA parameter specifies the logical block address to write on the device This function will only perform u NumBlocks block sized writes In most cases this is a write of 512 bytes of data The pucData buffer should contain at least ulNumBlocks 512 bytes in size to prevent unwanted data being written to the device Returns The function returns zero for success and any negative value indicates a failure USBHMSCDriveClose This function should be called to release a drive instance Prototype void USBHMSCDriveClose unsigned long ullInstance Parameters ullnstance is the device instance that is to be released Description This function is called when an MSC drive is to be released in preparation for shutdown or a switch to USB device mode for example Following this call the drive is available for other clients who may open it again using a call to USBHMSCDriveOpen September 05 2012 253 Host Functions 4 5 4 15 4 5 4 16 254 Returns None USBHMSCDriveOpen This function should be called before any devices are present to enable the mass storage device class driver Prototype unsigned long USBHMSCDriveOpen unsigned long ulDrive tUSBHMSCCallback pfnCallback Parameters ulDrive is the drive number to open pfnCallback is the driver callback for any mass storage events Description This function is called
331. rns Returns zero on failure or a non zero value that should be used with the remaining USB HID Bulk APIs USBDBulklInit Initializes bulk device operation for a given USB controller September 05 2012 81 Device Functions Prototype void x USBDBulkInit unsigned long ulIndex const tUSBDBulkDevice x xpsDevice Parameters ullndex is the index of the USB controller which is to be initialized for bulk device operation psDevice points to a structure containing parameters customizing the operation of the bulk device Description An application wishing to make use of a USB bulk communication channel must call this func tion to initialize the USB controller and attach the device to the USB bus This function performs all required USB initialization On successful completion this function will return the psDevice pointer passed to it This must be passed on all future calls to the device driver related to this device The USBDBulk interface offers packet based transmit and receive operation If the application would rather use block based communication with transmit and receive buffers USB buffers may be used above the bulk transmit and receive channels to offer this functionality Transmit Operation Calls to USBDBulkPacketWrite must send no more than 64 bytes of data at a time and may only be made when no other transmission is currently outstanding Once a packet of data has been acknowledged by the USB host a
332. roduct name string language 1 Serial number string language 1 MSC Interface description string language 1 Configuration description string language 1 If the device is supporting more than 1 language the descriptor block except for string descriptor 0 must be repeated for each language defined in the language descriptor The number of descriptors provided in the ppStringDescriptors array must be 5 num MSC strings num languages 1 September 05 2012 3 19 2 4 3 19 2 5 3 19 2 6 3 19 3 Device Functions Media Access Functions The media access functions are passed in to the USB mass storage device class in the sMedia Functions member variable This structure holds the access functions for the media used by this instance of the mass storage class device All of the functions in this structure are required to be filled out with valid functions These function will be called by the USB mass storage device class whenever it needs to read or write the physical media and will assume fixed block sizes of 512 bytes for the media Event Callbacks In some cases the application may need to be informed when the state of the mass stor age device has changed The pfnEventCallback member of the tUSBDMSCDevice structure provides event notification to applications for the following events USBD MSC EVENT IDLE USBD MSC EVENT READING and USBD MSC WRITING When the function of type tUSB Callback is called only the first two
333. rol line states as defined in table 51 of the USB CDC class definition and is a combination of the following values RTS USB CDC DEACTIVATE CARRIER or USB CDC ACTIVATE CARRIER DTR USB CDC DTE NOT PRESENT or USB CDC DTE PRESENT USBD CDC EVENT SET LINE CODING Definition define USBD CDC EVENT SET LINE CODING Description The host requests that the device set the RS232 communication parameters The pvMsgData parameter points to a tLineCoding structure defining the required number of bits per character parity mode number of stop bits and the baud rate September 05 2012 3 8 4 3 8 4 1 3 8 4 2 Device Functions Function Documentation USBDCDCCompositelnit Initializes CDC device operation when used with a composite device Prototype void x USBDCDCCompositeInit unsigned long ulIndex const tUSBDCDCDevice xpsCDCDevice Parameters ullndex is the index of the USB controller in use psCDCDevice points to a structure containing parameters customizing the operation of the CDC device Description This call is very similar to USBDCDClnit except that it is used for initializing an instance of the serial device for use in a composite device Returns Returns NULL on failure or the psCDCDevice pointer on success USBDCDCOInit Initializes CDC device operation for a given USB controller Prototype void USBDCDCInit unsigned long ulIndex const tUSBDCDCDevice xpsCDCDevice P
334. roperly initialize the USB controller The endpoint numbers interface numbers and string indexes that are included in the device con figuration descriptors are modified by the USB composite device class so that the values are valid in the composite device configuration descriptor Defining a Composite Device The USB composite device class is defined at the top level in the tUSBDCompositeDevice structure which is used to describe the class to the USB library In order for the USB composite device to enumerate and function properly all members of this structure must be filled with valid information The usVID and usPID values should have valid Vendor ID and Product ID values for the composite device The power requirements for the device as specified in the usMaxPowermA and ucPwrAt tributes and should take into account the power requirements and settings for all devices classes that the composite device is using The only truly optional member of the tUSBDCompositeDe vice structure is the pfnCallback function which provides notifications to the application that are not handled by the individual device classes The device specific strings should be included in the ppStringDescriptors and ulNumStringDescriptors members This list of strings should include the following three strings in the following order Manufacturer Product and Product serial number All other strings used by the classes are specified and are sourced from the included device classes
335. rs with the g USBHostAudioClassDriver structure pointer in the list of supported drivers Finally the application must create an instance of the USB host audio device by calling the USBHostAudioOpen function and provide it with a callback for basic USB audio events saving the value returned for use with other APIs Example Initial USB Audio Setup The instance data for the USB host audio driver unsigned long g ulAudioInstance 0 RA The control table used by the uDMA controller This table must be aligned to a 1024 byte boundary When using USB with uDMA if it is only used for USB then only first 6 channels are needed 77 Note If other DMA channels are used then the table must be large enough to hold all channels in use tDMAControlTable g sDMAControlTable 6 The global that holds all of the host drivers in use in the application In this case only the host audio class is loaded static tUSBHostClassDriver const const g ppHostClassDrivers amp g_USBHostAudioClassDriver amp g_SUSBEventDriver Enable the uDMA controller and set up the control table base 4 SysCtlPeripheralEnable SYSCTL PERIPH UDMA uDMAEnable uDMAControlBaseSet g sDMAControlTable September 05 2012 239 Host Functions 240 AA Register the host class drivers USBHCDRegisterDrivers 0 g_ppHostClassDrivers g_ulNumHostClassDrivers Open an instance of th
336. rs are provided to the library via four fields in the tDeviceInfo structure which is passed on a call to USBDCDInit The relevant fields are W pDeviceDescriptor September 05 2012 3 21 1 1 3 21 1 2 Device Functions m ppConfigDescriptors E ppStringDescriptors mg ulNumStringDescriptors All descriptors are provided as pointers to arrays of unsigned characters where the contents of the individual descriptor arrays are USB 2 0 compliant descriptors of the appropriate type For examples of particular descriptors see the main source files for each of the USB device class drivers for example device usbdbulk c for the generic bulk device class driver or the file usbdescriptors cinthe qs scope example application tDevicelnfo pDeviceDescriptor This array must hold the device descriptor that the USB Device API will return to the host in re sponse to a GET DESCRIPTOR DEVICE request The following example contains the device descriptor provided by a USB HID keyboard device const unsigned char g pDeviceDescriptor 18 Size of this structure USB DTYPE DEVICE Type of this structure USBShort 0x200 USB version 2 0 USB CLASS DEVICE USB Device Class 0 USB Device Sub class USB HID PROTOCOL NONE USB Device protocol 64 Maximum packet size for default pipe USBShort USB VID LUMINARY Vendor ID VID USBShort USB PID KEYBOARD Product ID PID USBShort 0x100 Device Ve
337. rsion BCD Ly Manufacturer string identifier 2 Product string identifier 3 Product serial number 1 Number of configurations Header file usblib h contains macros and labels to help in the construction of descriptors and individual device class header files such as usbhid h and device usbdhid h for the Human Interface Device class provide class specific values and labels tDevicelnfo ppConfigDescriptors While only a single device descriptor is required multiple configuration descriptors may be offered so the ppConfigDescriptors field is an array of pointers to tConfigHeader structures each defining the descriptor for a single configuration The number of entries in this array must agree with the number of configurations specified in the final byte of the device descriptor provided in the pDeviceDescriptor field To allow flexibility when defining composite devices individual configuration descriptors are also defined in terms of an array of structures In this case the tconfigHeader structure contains a count and a pointer to an array of cConfigSection structures each of which contains a pointer to a block of bytes and a size indicating the number of bytes in the section The sections described in this array are concatenated to generate the full config descriptor published to the host Config descriptors are somewhat more complex than device descriptors due to the amount of ad ditional information passed alongside
338. rts the first serial device would be interface 0 and the second would enumerate as interface 1 String Handling The device class strings will be merged into the composite device descriptor which will require that the composite class modify the default string indexes In doing this it will always ignore the three default string indexes in the device descriptor The remaining string indexes will be modified to match in the configuration descriptor Example Composite Device This section will continue with the example above that used two USB device serial classes in a single device This will include more detailed examples and code that demonstrate the configuration and setup needed for a composite serial device Composite Device Instance The application must first allocate two serial device structures and pass them into the composite initialization function for the USB serial CDC device The allocation and initialization are shown below A Instance and buffers for Serial Device A September 05 2012 Device Functions tCDCSerInstance g sCDCInstanceA const tUSBBuffer g sTxBufferA const tUSBBuffer g sRxBufferA f Instance and buffers for Serial Device B Bh tCDCSerInstance g sCDCInstanceB const tUSBBuffer g sTxBufferB const tUSBBuffer g sRxBufferB Device description for Serial Device A He const tUSBDCDCDevice g_sCDCDeviceA USB_VID_LUMINARY USB_PID_SERIAL 0 USB CONF ATTR SELF PWR
339. ruments Code Composer Studio Directory Structure Overview The following is an overview of the organization of the USB library source code along with refer ences to where each portion is described in detail September 05 2012 5 Introduction usblib The main directory under DriverLib contains the Makefile used to build the library and also source files and headers for functions and data types which are of general use to device and host applications The contents of this directory are described in chapter 2 usblib device This directory contains source code and header files relating to operation as a USB device The contents of this directory are described in chapter 3 usblib host This directory contains source code and header files relating to operation as a USB host The contents of this directory are described in chapter 4 6 September 05 2012 2 1 General Purpose Functions General Purpose Functions IMPROOUGCHION 25 2155 cod anata dbtictasicd dd baa a eura a oou MA Furia oin Dhaene ede p dubai Gr d quede 7 FUNCION DEINO S aena a Stu Eae AEE a EEEE 8 ISB Chaber o DERI siissieresiiero tniii nna ia a bead a sqq Md d 26 USE Buller and Rina BUITer AP Becuuo saca tee dree Eni EEE E E EE E EERE 34 Introduction This chapter describes the set of USB library data types and functions which are of general use in the development of USB applications running on Stellaris microcontroller based boards These elements are not specific
340. ry is fully configured Returns None USBOTGModeTerm Returns the USB controller to and inactive state when in OTG mode operation Prototype void USBOTGModeTerm unsigned long ulIndex Parameters ullndex specifies the USB controller to end OTG mode operations Description Applications using OTG mode may call this function to disable interrupts in preparation for shutdown or a change of operating mode Returns None USBOTGPollRate This call sets the USB OTG controllers poll rate when checking for the mode of the controller September 05 2012 General Purpose Functions Prototype void USBOTGPollRate unsigned long ulIndex unsigned long ulPollRate Parameters ullndex specifies which USB controller to set the polling rate ulPollRate is the rate in milliseconds to poll for changes in the controller mode Description This function is called to set the USB OTG libraries polling rate when checking the status of the cable The u PollRate value used sets the rate in milliseconds that the USB OTG library will poll the cable to see if the controller should enter host mode This value has no effect on device detection rate as the controller will detect being connected to a host controller automatically The ulPollRate can be set to 0 to disable polling The USB OTG library can still function with the polling rate set to zero however it will fail to detect host mode properly when no device is present at the e
341. s Prototype tBoolean USBDHIDRemoteWakeupRequest void xpviInstance Parameters pvinstance is the pointer to the HID device instance structure Description When the bus is suspended an application which supports remote wake up advertised to the host via the configuration descriptor may call this function to initiate remote wake up signaling to the host If the remote wake up feature has not been disabled by the host this will cause the bus to resume operation within 20mS If the host has disabled remote wake up false will be returned to indicate that the wake up request was not successful Returns Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previous call to this function 3 14 4 USBDHIDReportWrite Transmits a HID device report to the USB host via the HID interrupt IN endpoint Prototype unsigned long USBDHIDReportWrite void x xpvInstance unsigned char pcData unsigned long ulLength tBoolean bLast Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDInit pcData points to the first byte of data which is to be transmitted ulLength is the number of bytes of data to transmit bLast is ignored in this implementation This parameter is required to ensure compatibility with other device class drivers and USB buffers Description This function
342. s Returns the number of bytes of data read September 05 2012 3 8 4 4 3 8 4 5 Device Functions USBDCDCPacketWrite Transmits a packet of data to the USB host via the CDC data interface Prototype unsigned long USBDCDCPacketWrite void xpvInstance unsigned char pcData unsigned long ulLength tBoolean bLast Parameters pvinstance is the pointer to the device instance structure as returned by USBDCDCInit pcData points to the first byte of data which is to be transmitted ulLength is the number of bytes of data to transmit bLast indicates whether more data is to be written before a packet should be scheduled for transmission If true the client will make a further call to this function If false no further call will be made and the driver should schedule transmission of a short packet Description This function schedules the supplied data for transmission to the USB host in a single USB packet If no transmission is currently ongoing the data is immediately copied to the relevant USB endpoint FIFO If the bLast parameter is true the newly written packet is then scheduled for transmission Whenever a USB packet is acknowledged by the host a USB EVENT TX COMPLETE event will be sent to the application transmit callback indicat ing that more data can now be transmitted The maximum value for ulLength is 64 bytes the maximum USB packet size for the bulk end points in use by CDC Attempts to send more data than this
343. s call is the value that was returned from the USBHostAudioOpen function This call checks the USB audio device to determine if it can support the values provided in the ul SampleRate ulBits and ulChannels values The ulFlags currently only supports either the USBH AUDIO FORMAT IN or USBH AUDIO FORMAT OUT values that indicates if a re quest is for an audio input and an audio output If the format is supported this function returns zero and this function returns a non zero value if the format is not supported This function does not set the current output or input format September 05 2012 255 Host Functions 4 5 4 19 4 5 4 20 256 Returns A value of zero indicates the supplied format is supported and a non zero value indicates that the format is not supported USBHostAudioFormatSet This function is called to set the current sample rate on an audio interface Prototype unsigned long USBHostAudioFormatSet unsigned long ulInstance unsigned long ulSampleRate unsigned long ulBits u u unsigned long ulChannels unsigned long ulFlags Parameters ullnstance specifies the device instance for this call ulSampleRate is the sample rate in Hz ulBits is the number of bits per sample ulChannels is then number of audio channels ulFlags is a set of flags that determine the access type Description This function is called when to set the current audio output or input format for a USB audio device T
344. s during enumeration The USB pipes are usually only used within the USB library or by host class drivers and are not usually directly accessed by applications The USB pipes are allocated and freed by calling the USBHCDPipeAlloc and USBHCDPipeFree functions and are initially configured by calling the USBHCDPipeConfig The USBHCDPipeAlloc and US BHCDPipeConfig functions are used during USB device enumeration to allocate USB pipes to specific endpoints of the USB device On disconnect the USBHCDPipeFree function is called to free up the USB pipe for use by a new USB device While in use the USB pipes can provide status and perform read and write operations Calling USBHCDPipeStatus allows a host class driver to check the status of a pipe However most access to the USB pipes occurs through USB HCDPipeWrite and USBHCDPipeRead and the callback function provided when the USB pipe was allocated These are used to read or write to endpoints on USB devices on endpoints other than the control endpoint on endpoint 0 Since endpoint 0 is shared with all devices the host con troller interface does not use USB pipes for communications over endpoint 0 and instead uses the USBHCDOontrolTransfer function Control Transactions All USB control transactions are handled through the USBHCDOontrolTransfer function This function is primarily used inside the host controller driver itself during enumeration however some devices may require using con
345. s structure This function uses the current state of the shift keys and the Caps Lock key to modify the data returned by this function The pTable structure has values indicat ing which keys are modified by Caps Lock and alternate values for shifted cases The number of bytes returned from this function depends on the pTable structure passed in as it holds the number of bytes per character in the table Returns Returns the character value for the given usage id USBHMouseClose This function is used close an instance of a mouse Prototype unsigned long USBHMouseClose unsigned long ullInstance Parameters ullnstance is the instance value for this mouse Description This function is used to close an instance of the mouse that was opened with a call to USBH MouseOpen The ullnstance value is the value that was returned when the application called USBHMouseOpen Returns Returns 0 USBHMouselnit This function is used to initialize a mouse interface after a mouse has been detected Prototype unsigned long USBHMouseInit unsigned long ulInstance Parameters ullnstance is the instance value for this mouse Description This function should be called after receiving a USB EVENT CONNECTED event in the call back function provided by USBHMouseOpen however it should only be called outside of the September 05 2012 4 7 2 9 4 8 4 8 1 Host Functions callback function This will initialize the mouse i
346. sable it or possibly switch modes in the case of a dual role controller The USB library assumes that the power pin configuration has an active high signal for controlling the external power If this is not the case or if the application wants control over the power fault logic provided by the library then the application should call the USBHCDPowerConfigInit function before calling USBHCDInit in order to properly configure the power control pins The polarity of the power pin the polarity of the the power fault pin and any actions taken in response to a power fault are all controlled by passing a combination of sets of values in the u PwrConfig parameter See the documentation for the USBHCDPowerConfiglnit function for more details on this function Application Interface The USB library host stack requires some portion of the code to not run in the interrupt handler so it provides the USBHCDMain function that must be called periodically in the main application This can be as a result of a timer tick or just once per main loop in a simple application It should not be called in an interrupt handler Calling the function too often is harmless as it simply returns if the USB host stack has nothing to do Calling USBHCDMain too infrequently can cause enu meration to take longer than normal It is up to the application to prioritize the importance of USB communications by calling USBHCDMain at a rate that is reasonable to the application
347. sb cat CatalogFile NTAMD64 usb_dev_bulk_libusb_x64 cat Class LibUsbDevices ClassGUID EB781AAF 9C70 4523 A5DF 642A87ECA567 ClassInstall AddReg libusb_class_install_add_reg ClassInstall32 AddReg libusb class install add reg libusb class install add reg HKR LibUSB Win32 Devices HKR Icon 20 Manufacturer manufacturer Devices NT NTAMD64 SourceDisksNames 1 Libusb Win32 Driver Installation Disk SourceDisksFiles libusb0O sys 1 libusb0 dll 1 libusb0_x64 sys 1 libusb0 x64 dll Lpy DestinationDirs libusb_files_sys 10 system32 drivers libusb_files_sys_x64 10 system32 drivers libusb files dll 10 system32 libusb files dll wow64 10 syswow64 libusb files dll x64 10 system32 libusb files sys libusb0 sys September 05 2012 77 Device Functions 78 libusb_files_sys_x64 libusb0 sys libusb0 x64 sys n o H libu files dll libusb0 dll libusb files dll wow64 libusb0 dll libusb files dll x64 libusb0 dll libusbO0 x64 dll LIBUSB DEV CopyFiles libusb files sys libusb files dll AddReg libusb add reg LIBUSB DEV NT CopyFiles libusb files sys libusb files dll LIBUSB DEV NTAMD64 CopyFiles libusb files sys x64 libusb files dll wow64 libusb files dll x64 LIBUSB DEV HW DelReg libusb del reg hw AddReg libusb add reg hw LIBUSB DEV NT HW DelReg libusb del reg hw AddReg libusb add reg hw
348. schedules the supplied data for transmission to the USB host in a single USB transaction using as many packets as it takes to send all the data in the report If no trans mission is currently ongoing the first packet of data is immediately copied to the relevant USB endpoint FIFO for transmission Whenever all the report data has been acknowledged by the host a USB EVENT TX COMPLETE event will be sent to the application transmit callback indicating that another report can now be transmitted The caller must ensure that the data pointed to by pucData remains accessible and unaltered until the USB EVENT TX COMPLETE is received Returns Returns the number of bytes actually scheduled for transmission At this level this will either be the number of bytes passed or 0 to indicate a failure September 05 2012 153 Device Functions 3 14 4 7 USBDHIDRxPacketAvailable 3 14 4 8 3 14 4 9 154 Determines whether a packet is available and if so the size of the buffer required to read it Prototype unsigned long USBDHIDRxPacketAvailable void pvInstance Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDInit Description This function may be used to determine if a received packet remains to be read and allows the application to determine the buffer size needed to read the data Returns Returns 0 if no received packet remains unprocessed or the size of the packet if a packet is waiting
349. se configuration descriptors defined in terms of an array of sections as used with the USB Device API The source code for the USB generic bulk device class driver The source code for the USB Communication Device Class CDC device class driver The source code for the USB Human Interface Device HID device class driver The source code for the USB HID keyboard device class The source code for the USB HID keyboard device class The private header file containing definitions shared between various source files in the device directory Applications must not include this header API choices for USB devices The USB library contains four API layers relevant to the development of USB device applications Moving down the stack each API layer offers greater flexibility to an application but this is balanced by the greater effort required to use the lower layers The available programming interfaces starting at the highest level and working downwards are m Device Class Driver APIs m The USB Device API m The USB DriverLib API September 05 2012 3 2 1 3 2 2 Device Functions Device Class Driver API I 1 M CN I 1 S S f Application 3 1 Application 4 dea 42 i w w 1 i 2 oO I l 1 I m I f lt lt i USB Device Class 1 Buffer API L m U RR L L L L L L USB Device API USB DriverLib API In the above diagram bold horiz
350. signed char pucBuf unsigned long ulSize void USBRingBufRead tUSBRingBufObject ptUSBRingBuf unsigned char pucData un signed long ulLength unsigned char USBRingBufReadOne tUSBRingBufObject ptUSBRingBuf unsigned long USBRingBufSize tUSBRingBufObject ptUSBRingBuf unsigned long USBRingBufUsed tUSBRingBufObject ptUSBRingBuf void USBRingBufWrite tUSBRingBufObject ptUSBRingBuf const unsigned char pucData unsigned long ulLength m void USBRingBufWriteOne tUSBRingBufObject ptUSBRingBuf unsigned char ucData Detailed Description At the lowest level USB communication is packet based with the size of each packet dependent upon the configuration of the USB endpoint In addition when a packet is in transit no more data may be sent on that endpoint until the transmission completes so state machines are required to ensure that data is only sent when it is safe to do so This model is suitable for some applications but in other cases a simple read write model allowing arbitrarily sized blocks of data to be received or transmitted at times suitable to the application is more appropriate The USB buffer API allows an application to chose this type of operation when used in conjunction with particular host or device class drivers A USB buffer provides a unidirectional buffer for a single endpoint and may be configured for op eration as either a receive buffer accepting data from the USB controller and passing it to an a
351. sing a USB EVENT RX AVAILABLE event In the handler for this event the application must call USBHCDPipeDataAck to have the USB controller ACK the data from the device and complete the transaction Returns None 4 3 4 16 USBHCDPipeFree Definition void USBHCDPipeFree unsigned long ulPipe Description This function is used to release a USB pipe Parameters ulPipe is the allocated USB pipe to release This function is used to release a USB pipe that was allocated by a call to USBHCDPipeAlloc for use by some other device endpoint in the system Freeing an unallocated or invalid pipe will not generate an error and will instead simply return Returns None September 05 2012 223 Host Functions 4 3 4 17 USBHCDPipeRead Definition unsigned long USBHCDPipeRead unsigned long ulPipe unsigned char xpucData unsigned long ulSize Description This function is used to read data from a USB HCD pipe Parameters ulPipe is the USB pipe to read data from pucData is a pointer to store the data that is received ulSize is the size in bytes of the buffer pointed to by pucData This function will block and will only return when it has read as much data as requested from the USB pipe The caller should have registered a callback with the USBHCDPipeAlloc call in order to be informed when the data has been received The value returned by this function can be less than the u Size requested if the USB pipe has less
352. siteDevice Members usVID The vendor ID that this device is to present in the device descriptor usPID The product ID that this device is to present in the device descriptor usMaxPowermA The maximum power consumption of the device expressed in mA ucPwrAttributes Indicates whether the device is self or bus powered and whether or not it supports remote wake up Valid values are USB CONF ATTR SELF PWR or USB CONF ATTR BUS PWhR optionally ORed with USB CONF ATTR RWAKE pfnCallback A pointer to the callback function which will be called to notify the application of events relating to the operation of the composite device ppStringDescriptors A pointer to the string descriptor array for this device This array must contain the following string descriptor pointers in this order Language descriptor Manu facturer name string language 1 Product name string language 1 Serial number string language 1 Composite device interface description string language 1 Configuration description string language 1 If supporting more than 1 language the descriptor block except for string descriptor 0 must be repeated for each language defined in the language descriptor ulNumStringDescriptors The number of descriptors provided in the ppStringDescriptors ar ray This must be 1 5 number of strings number of languages ulNumDevices The number of devices in the psDevices array psDevices This application supplied array holds the the top
353. st not be accessed by the application and must remain accessible to the USB buffer for as long as the buffer exists between calls to USBBufferlnit and USB BufferTerm The label USB BUFFER WORKSPACE SIZE defines the number of bytes of workspace required Once a transmit buffer is initialized the application can write data to it using function USBBuffer Write whenever space is available and the USB buffer driver will handle packet transmission to the lower layer Similarly USBBufferRead can be called to read received data from a receive buffer at any time In both cases the USB buffer uses the same event protocol that the lower layers use to indicate to the application when more data can be transferred or when data has been sent When data from the USB controller is added to a receive buffer USB EVENT RX AVAILABLE is passed to the application and when data is removed from a transmit buffer after having been sent to the lower layer USB EVENT TX COMPLETE is sent Applications usb dev bulk and usb dev serial provide examples of how to use USB buffers in a device application September 05 2012 37 General Purpose Functions 2 4 3 2 4 3 1 2 4 3 2 38 Data Structure Documentation tUSBBuffer Definition typedef struct tBoolean bTransmitBuffer tUSBCallback pfnCallback void xpvCBData tUSBPacketTransfer pfnTransfer tUSBPacketAvailable pfnAvailable V u u oid xpvHandle nsigned char pcBuffer nsign
354. stance instance should not me used in any other calls Returns None Device Firmware Upgrade Device Class Driver Although USB Device Firmware Upgrade functionality is provided primarily by the USB boot loader boot_usb applications which want to support DFU funcionality should publicize this in their September 05 2012 3 11 1 Device Functions configuration descriptor and be able to receive a request from the host indicating that they should switch into DFU mode to receive an upgrade The DFU device class supports this runtime DFU capability providing a simple method for an application to indicate to the host that it is DFU capable and to be signalled that a USB based firmware upgrade is being requested The device class is unusual in that it must be used as part of a composite device Runtime DFU capability makes no sense on its own since it is basically only an indication that the DFU USB boot loader is present and usable The USB boot loader must also be used by any device supporting the DFU runtime device class since it implements all DFU mode operation and performs the actual upgrade operation The run time device class adds two sections to the configuration descriptor for the main application a DFU Interface Descriptor and a DFU Functional Descriptor Standard DFU DETACH requests sent to the DFU interface from the host result in a callback being made to the client application indicating that it must transfer control back to t
355. structure These refer to a bit mask of flags that indicate the type of output for a set of items Returns Not a function 3 14 3 12 PhysicalMaximum This is a macro to assist adding Physical Maximum entries in HID report descriptors Definition define PhysicalMaximum sValue Parameters sValue is the Physical Maximum value It is a signed 16 bit number Description This macro takes a value and prepares it to be placed as a Physical Maximum entry into a HID report structure This is value is used in conversion of the control logical value as returned to the host in the relevant report to a physical measurement in the appropriate units Returns Not a function 3 14 3 13 PhysicalMinimum This is a macro to assist adding Physical Minimum entries in HID report descriptors Definition define PhysicalMinimum sValue Parameters sValue is the Physical Minimum value It is a signed 16 bit number Description This macro takes a value and prepares it to be placed as a Physical Minimum entry into a HID report structure This is value is used in conversion of the control logical value as returned to the host in the relevant report to a physical measurement in the appropriate units Returns Not a function 3 14 3 14 ReportCount This is a macro to assist adding Report Count entries in HID report descriptors Definition define ReportCount ucValue 142 September 05 2012 Device Functions Parameters ucValu
356. t unsigned long ullnstance unsigned long USBHMouseOpen tUSBCallback pfnCallback unsigned char pucBuffer un signed long ulSize Detailed Description The macros and functions defined in this section can be found in header files host usbhhidkeyboard h and host usbhhidmouse h Function Documentation USBHKeyboardClose This function is used close an instance of a keyboard Prototype unsigned long USBHKeyboardClose unsigned long ullInstance Parameters ullnstance is the instance value for this keyboard Description This function is used to close an instance of the keyboard that was opened with a call to US BHKeyboardOpen The ullnstance value is the value that was returned when the application called USBHKeyboardOpen Returns This function returns 0 to indicate success any non zero value indicates an error condition USBHKeyboardlnit This function is used to initialize a keyboard interface after a keyboard has been detected Prototype unsigned long USBHKeyboardInit unsigned long ullInstance Parameters ullnstance is the instance value for this keyboard September 05 2012 269 Host Functions 4 7 2 3 4 7 2 4 270 Description This function should be called after receiving a USB_EVENT_CONNECTED event in the call back function provided by USBHKeyboardOpen however this function should only be called outside the callback function This will initialize the keyboard interface and determ
357. t 0 the control endpoint The ulMsgValue parameter contains the requested report type in the high byte and report ID in the low byte as passed in the wValue field of the USB request structure The pvMsgData parameter contains a pointer which must be written with the address of the first byte of the requested report The callback must return the size in bytes of the report pointed to by xpvMsgData The memory returned in response to this event must remain unaltered until USBD HID EVENT REPORT SENT is sent 3 14 3 41 USBD HID EVENT GET REPORT BUFFER Definition define USBD HID EVENT GET REPORT BUFFER Description This event indicates that the host has sent a Set Report request to the device and requests that the device provide a buffer into which the report can be written The ulMsgValue parameter contains the received report type in the high byte and report ID in the low byte as passed in the wValue field of the USB request structure The pvMsgData parameter contains the length of buffer requested Note that this is the actual length value cast to a void x type and not a pointer in this case The callback must return a pointer to a suitable buffer cast to the standard unsigned long return type for the callback 3 14 3 42 USBD HID EVENT IDLE TIMEOUT Definition define USBD HID EVENT IDLE TIMEOUT Description This event indicates to an application that a report idle timeout has occurred
358. t indicates that the host has sent the device a report via endpoint 0 the control endpoint The ulMsgValue field indicates the size of the report and pyMsgData points to the first byte of the report The report buffer will previously have been returned in response to an earlier USBD HID EVENT GET REPORT BUFFER callback The HID device class driver will not access the memory pointed to by pvMsgData after this callback is made so the application is free to reuse or free it at this point Function Documentation USBDHIDCompositelnit Initializes HID device operation for a given USB controller Prototype void USBDHIDCompositeInit unsigned long ulIndex const tUSBDHIDDevice psDevice Parameters ullndex is the index of the USB controller which is to be initialized for HID device operation psDevice points to a structure containing parameters customizing the operation of the HID device Returns Returns NULL on failure or the psDevice pointer on success void x USBDHIDInit unsigned long ulIndex const tUSBDHIDDevice psDevice Initializes HID device operation for a given USB controller Parameters ullndex is the index of the USB controller which is to be initialized for HID device operation September 05 2012 3 14 4 3 Device Functions psDevice points to a structure containing parameters customizing the operation of the HID device Description An application wishing to offer a USB HID interface to a host system must c
359. t size 64 if no September 05 2012 155 Device Functions 3 15 3 15 1 transmission is currently outstanding or 0 if a transmission is in progress Since the function USBDHIDReportWrite can accept full reports longer than a single USB packet the caller should be aware that the returned value from this class driver unlike others does not indicate the maximum size of report that can be written but is merely an indication that another report can be written Returns Returns 0 if an outgoing report is still being transmitted or 64 if no transmission is currently in progress HID Mouse Device Class API The USB HID device class is extremely versatile but somewhat daunting For applications which want to offer a mouse like appearance to a USB host however the HID Mouse Device Class API may be used without the need to develop any HID specific software This high level interface completely encapsulates the USB stack and USB HID device class driver and allows an application to simply instantiate a USB mouse device and call a single function to notify the USB host of mouse movement and button presses The USB mouse device uses the BIOS mouse subclass and protocol so is recognized by the vast majority of host operating systems and BIOSs without the need for additional host side software The mouse provides two axis movement reported to the host in terms of relative position changes and up to three buttons which may be either pressed or rel
360. tallers AddReg CoInstallers AddReg CopyFiles CoInstallers CopyFiles CoInstallers AddReg CoInstallers_CopyFiles WinUSBCoInstaller dll WdfCoInstaller01005 d11 DestinationDirs CoInstallers CopyFiles 11 SourceDisksNames 1 DISK NAME i386 2 DISK_NAME amd64 SourceDisksFiles x86 WinUSBCoInstaller dll 1 WdfCoInstaller01005 dl1 21 SourceDisksFiles amd64 WinUSBCoInstaller dll 2 WdfCoInstaller01005 d11 2 HKR DeviceInterfaceGUIDs 0x10000 6E45736A 2B1B 4078 B772 B3AF2B6FDEI1C HKR CoInstallers32 0x00010000 WdfCoInstaller01005 dll WdfCoInstaller WinUSBCoInstaller dll 76 September 05 2012 Device Functions Note Replace these as appropriate to describe your device Strings ProviderName Texas Instruments USB StellarisBulkDevice DeviceDesc Generic Bulk Device WinUSB_SvcDesc WinUSB DISK_NAME Stellaris Install Disk DeviceClassDisplayName Stellaris Bulk Devices 3 5 4 2 Sample libusb win32 INF File The following is an example of an INF file that can be used to associate the usb_dev_bulk ex ample device with the libusb win32 subsystem on Windows systems and to install the necessary drivers This was created using the INF Wizard application which is included in the libusb win32 download package Version Signature Chicago provider manufacturer DriverVer 03 20 2007 0 1 12 1 CatalogFile usb_dev_bulk_libusb cat CatalogFile NT usb_dev_bulk_libu
361. tate Returns None 228 September 05 2012 Host Functions 4 3 4 28 USBHCDResume Definition void USBHCDResume unsigned long ulIndex Description This function will generate resume signaling on the USB bus Parameters ullndex specifies which USB controller to use This function is used to generate resume signaling on the USB bus in order to cause USB devices to leave their suspended state This call should not be made unless a preceding call to USBHCDSuspend has been made Returns None 4 3 4 9 USBHCDSetAddress Definition void USBHCDSetAddress unsigned long ulDevIndex unsigned long ulDevAddress Description This function is used to send the set address command to a device Parameters ulDevindex is the index of the device whose address is to be set This value must be 0 to indicate that the device is connected directly to the host controller Higher values indicate devices connected via a hub ulDevAddress is the new device address to use for a device The USBHCDSetAddress function is used to set the USB device address once a device has been discovered on the bus This call is typically issued following a USB reset triggered by a call the USBHCDReset The address passed into this function via the u DevAddress parameter is used for all further communications with the device after this function returns Returns None 4 3 4 30 USBHCDSetConfig Definition void USBHCDSetConfig unsigne
362. te that this data is not available at the time the callback is made and the device code is responsible for requesting it using a call to USBDCDRequestDataEP0 if required The sequence required when additional data is attached to the request is as follows m Parse the request to determine the request type and verify that it is handled by the device If not call USBDCDStallEPO to indicate the problem m f the request is to be handled and wLength is non zero indicating that additional data is required call USBDCDRequestDataEPO passing a pointer to the buffer into which the data is to be written and the number of bytes of data to receive m Call USBDevEndpointDataAck to acknowledge reception of the initial request transmission This function is found in the Stellaris Peripheral Driver Library USB driver API Note that it is important to call USBDCDRequestDataEPO prior to acknowledging the initial request since the acknowledgment frees the host to send the additional data By making the calls in this order the USB Device API is guaranteed to be in the correct state to receive the data when it arrives Making the calls in the opposite order creates a race condition which could result in loss of data Data received as a result of a call to USBDCDRequestDataEPO will be delivered asynchronously via the p nDataReceived callback described below If this member of scallbacks is set to NULL the USB Device API will stall endpoint zero whe
363. te that transmission may begin Returns None 2 4 6 8 USBBufferlnit Initializes a USB buffer object to be used with a given USB controller and device or host class driver Prototype const tUSBBuffer x USBBufferInit const tUSBBuffer xpsBuffer Parameters psBuffer points to a structure containing information on the buffer memory to be used and the underlying device or host class driver whose data is to be buffered This structure must remain accessible for as long as the buffer is in use Description This function is used to initialize a USB buffer object and insert it into the function and callback interfaces between an underlying driver and the application The caller supplies information on both the RAM to be used to buffer data the type of buffer to be created transmit or receive and the functions to be called in the lower layer to transfer data to or from the USB controller Returns Returns the original buffer structure pointer if successful or NULL if an error is detected September 05 2012 43 General Purpose Functions 2 4 6 9 2 4 6 10 2 4 6 11 44 USBBufferRead Reads a block of data from a USB receive buffer into storage supplied by the caller Prototype unsigned long USBBufferRead const tUSBBuffer xpsBuffer unsigned char xpucData unsigned long ulLength Parameters psBuffer is the pointer to the buffer instance from which data is to be read pucData points to a buffer into which the rec
364. terfaces are provided ranging from the thinnest layer which merely abstracts the underlying USB controller hardware to high level interfaces offering simple APIs supporting specific devices Source Code Overview Source code and headers for the device specific USB functions can be found in the device directory of the USB library tree typically DriverLib usblib device usbdevice h The header file containing device mode function prototypes and data types offered by the library This file is the main header file defining the USB Device API usbdbulk h The header file defining the USB generic bulk device class driver API usbdcdc h The header file defining the USB Communication Device Class CDC device class driver API September 05 2012 53 Device Functions 3 2 54 usbdhid h usbdhidkeyb h usbdhidmouse h usbdenum c usbdhandler c usbdconfig c usbdcdesc c usbdbulk c usbdcdc c usbdhid c usbdhidkeyb c usbdhidmouse c usbdevicepriv h m Device Class APIs The header file defining the USB Human Interface Device HID device class driver API The header file defining the USB HID keyboard device class API The header file defining the USB HID keyboard device class API The source code for the USB device enumeration functions offered by the library The source code for the USB device interrupt handler The source code for the USB device configuration functions The source code for functions used to par
365. tes bDescriptorType The type identifier of the descriptor whose information follows For stan dard descriptors this field could contain for example USB DTYPE DEVICE to identify a device descriptor or USB DTYPE ENDPOINT to identify an endpoint descriptor Description This structure describes a generic descriptor header These fields are to be found at the beginning of all valid USB descriptors tDeviceDescriptor Definition typedef struct nsig nsig nsig nsig Cx E Ge Gs Ge Cue Gas Cr ICI Cua c Cae Ci Cs nsig nsigned nsigned nsigned nsigned ned nsigned ned nsigned ned nsigned ned nsigned nsigned ned C C S o e o C S S S C C o C har bLength har bDescriptorType hort bcdUSB har bDeviceClass har bDeviceSubClass har bDeviceProtocol har bMaxPacketSize0 hort idVendor hort idProduct hort bcdDevice har iManufacturer har iProduct har iSerialNumber har bNumConfigurations tDeviceDescriptor Members bLength The length of this descriptor in bytes All device descriptors are 18 bytes long bDescriptorType The type of the descriptor For a device descriptor this will be USB DTYPE DEVICE 1 bcdUSB The USB Specification Release Number in BCD format For USB 2 0 this will be 0x0200 bDeviceClass The device class code bDeviceSubClass The device subclass code This value qualifies the value found in the bDe vi
366. tes a control transaction to a device Parameters ullndex is the controller index to use for this transfer pSetupPacket is the setup request to be sent pDevice is the device instance pointer for this request pData is the data to send for OUT requests or the receive buffer for IN requests ulSize is the size of the buffer in pData ulMaxPacketSize is the maximum packet size for the device for this request This function handles the state changes necessary to send a control transaction to a device This function should not be called from within an interrupt callback as it is a blocking function Returns The number of bytes of data that were sent or received as a result of this request 4 3 4 3 USBHCDDevAddress Definition unsigned char USBHCDDevAddress unsigned long ulInstance Description This function will return the USB address for the requested device instance Parameters ullnstance is a unique value indicating which device to query This function returns the USB address for the device that is associated with the u Instance pa rameter The caller must use a value for ulInstance have been passed to the application when it receives a USB EVENT CONNECTED event The function will return the USB address for the interface number specified by the ullnterface parameter Returns The USB address for the requested interface 4 3 4 4 USBHCDDevClass Definition unsigned char USBHCDDevClass unsigned long ulInstance unsigne
367. the SCSI protocol only the SCSI func tions needed by mass storage class to mount and access flash drives are implemented The SCSIRead10 and SCSIWrite10 functions are the two functions used for reading and writing to the mass storage class devices The remaining SCSI functions are used to get information about the mass storage devices like the size of the blocks on the device and the number of blocks present Others are used for error handling or testing if the device is ready for a new command Audio Class Driver The USB audio host class driver provides access to devices that support the USB audio class protocol This driver provides access to both audio in and audio out interfaces The appli cation opens an instance of the audio device by calling USBHostAudioOpen and providing a callback function to receive events notifications when an audio device has been enumerated and is ready for normal operation USBH AUDIO EVENT OPEN or when an active audio de vice has been disconnected USBH AUDIO EVENT CLOSE The application should not access any other APIs that use the interface returned from the USBHostAudioOpen function until an USBH AUDIO EVENT OPEN event is received and not after a USBH AUDIO EVENT CLOSE event is received When the application no longer needs the audio interface it can call USBHostAu dioClose to stop the audio device and no longer be notified of changes to the audio device Audio output is handled by providing buffers to
368. the USB stack Prototype void USBOOTGModeIntHandler void Description This interrupt handler is used in applications which require to operate in both host and device mode using OTG When in host or device mode it steers the USB hardware interrupt to the correct handler in the USB stack depending upon the current operating mode It also handles other OTG related interrupt events For successful OTG mode operation an application must register USBOOTGModelntHandler in the CPU vector table as the interrupt handler for the USBO interrupt Note This interrupt handler should only be used on controllers that support OTG functionality Returns None September 05 2012 19 General Purpose Functions 2 2 6 3 2 2 6 4 20 USBDescGet Determines the number of individual descriptors of a particular type within a supplied buffer Prototype tDescriptorHeader x USBDescGet tDescriptorHeader psDesc unsigned long ulSize unsigned long ulType unsigned long ulIndex Parameters psDesc points to the first byte of a block of standard USB descriptors ulSize is the number of bytes of descriptor data found at pointer psDesc ulType identifies the type of descriptor that is to be found If the value is USB DESC ANY the function returns a pointer to the n th descriptor regardless of type ullndex is the zero based index of the descriptor whose pointer is to be returned For example passing value 1 in ulIndex
369. the basic configuration descriptor In addition to USB 2 0 September 05 2012 187 Device Functions 188 standard descriptors for the configuration interfaces and endpoints in use additional class spe cific descriptors may also be included The USB Device API imposes one restriction on configuration descriptors that devices must be aware of While the USB 2 0 specification does not restrict the values that can be specified in the bConfigurationValue field byte 6 of the configuration descriptor the USB Device API requires that individual configurations are numbered consecutively starting at 1 for the first configuration The following example contains the configuration descriptor structures provided for a USB HID keyboard This example offers a single configuration containing one interface and using a single interrupt endpoint In this case in addition to the standard portions of the descriptor a Human Interface Device HID class descriptor is also included Due to the use of a standard format for descriptor headers the USB Device API is capable of safely skipping device specific descriptors when parsing these structures In this example we illustrate the use of multiple sections to build the configuration descriptor The content of the config descriptor given here is however static so it could easily have been defined in terms of a single tConfigSection entry instead The label g_pucReportDescriptor is assumed to be a pointer to a
370. the default configuration Note The USB device stack assumes that the configuration IDs byte 6 of the configura tion descriptor bConfigurationValue stored within the configuration descriptor array ppConfigDescriptors are equal to the array index 1 In other words the first entry in the array must contain a descriptor with bCon igurationValue 1 the second must have bConfigurationValue 2 and soon Returns None 3 22 3 8 USBDCDStallEPO This function generates a stall condition on endpoint zero Prototype 204 void USBDCDStallEPO unsigned long ulIndex September 05 2012 Device Functions Parameters ullndex is the index of the USB controller whose endpoint zero is to be stalled Description This function is typically called to signal an error condition to the host when an unsupported request is received by the device It should be called from within the callback itself in interrupt context and not deferred until later since it affects the operation of the endpoint zero state machine in the USB library Returns None 3 22 3 9 USBDCDTerm Free the USB library device control driver for a given hardware controller Prototype void USBDCDTerm unsigned long ulIndex Parameters ullndex is the index of the USB controller which is to be freed Description This function should be called by an application if it no longer requires the use of a given USB controller to support its operation as a U
371. ther we need to pass an interrupt notification on to this device as a result of endpoint activity bLowSpeed A flag used to record whether this is a low speed or a full speed device bConfigRead A flag indicating whether or not we have read the device s configuration descrip tor yet ucHub The hub number to which this device is attached ucHubPort The hub port number to which the device is attached DeviceDescriptor The device descriptor for this device pConfigDescriptor A pointer to the configuration descriptor for this device ulConfigDescriptorSize The size of the buffer allocated to pConfigDescriptor Description This is the structure that holds all of the information for devices that are enumerated in the system It is passed in to Open function of USB host class drivers so that they can allocate any endpoints and parse out other information that the device class needs to complete enumera tion September 05 2012 215 Host Functions 4 3 3 4 3 3 1 4 3 4 Define Documentation DECLARE_EVENT_DRIVER This macro is used to declare an instance of an Event driver for the USB library Definition define DECLARE EVENT DRIVER VarName pfnOpen pfnClose pfnEvent Parameters VarName is the name of the variable pfnOpen is the callback for the Open call to this driver This value is currently reserved and should be set to 0 pfnClose is the callback for the Close call to this driver This v
372. tion and is accompanied by all associated warranties conditions limitations and notices Reproduction of this information with alteration is an unfair and deceptive business practice TI is not responsible or liable for such altered documentation Information of third parties may be subject to additional restrictions Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice TI is not responsible or liable for any such statements TI products are not authorized for use in safety critical applications such as life support where a failure of the TI product would reasonably be expected to cause severe personal injury or death unless officers of the parties have executed an agreement specifically governing such use Buyers represent that they have all necessary expertise in the safety and regulatory ramifications of their applications and acknowledge and agree that they are solely responsible for all legal regulatory and safety related requirements concerning their products and any use of TI products in such safety critical applications notwithstanding any applications related information or support that may be provided by TI Further Buyers must fully indemnify TI and its representatives against any damages arising out of the use of TI products in
373. tion may be used to determine the number of bytes of data in a buffer For a receive buffer this indicates the number of bytes that the client can read from the buffer using USB BufferRead For a transmit buffer this indicates the amount of data that remains to be sent to the USB controller Returns Returns the number of bytes of data in the buffer September 05 2012 2 4 6 3 2 4 6 4 General Purpose Functions USBBufferDataRemoved Indicates that a client has read data directly out of the buffer Prototype void USBBufferDataRemoved const tUSBBuffer psBuffer unsigned long ulLength Parameters psBuffer is the pointer to the buffer instance from which data has been read ulLength is the number of bytes of data that the client has read Description This function updates the USB buffer read pointer to remove data that the client has read di rectly rather than via a call to USBBufferRead The function is provided to aid a client wishing to minimize data copying To read directly from the buffer a client must call USBBufferlnfoGet to retrieve the current buffer indices With this information the data following the current read index can be read Once the client has processed much data as it needs USBBufferDataRe moved must be called to advance the read pointer past the data that has been read and free up that section of the buffer The client must take care to correctly handle the wrap point if accessing the buf
374. tions Defines MOUSE_ERR_NOT_CONFIGURED MOUSE_ERR_TX_ERROR MOUSE_REPORT_BUTTON_1 MOUSE_REPORT_BUTTON_2 MOUSE_REPORT_BUTTON_3 MOUSE_SUCCESS Functions m void x USBDHIDMouseCompositelnit unsigned long ullndex const tUSBDHIDMouseDevice psDevice void x USBDHIDMouselnit unsigned long ullndex const tUSBDHIDMouseDevice psDevice void USBDHIDMousePowerStatusSet void pvinstance unsigned char ucPower tBoolean USBDHIDMouseRemoteWakeupRequest void pvinstance void x USBDHIDMouseSetCBData void pvInstance void pvCBData unsigned long USBDHIDMouseStateChange void xpvinstance char cDeltaX char cDeltaY unsigned char ucButtons m void USBDHIDMouseTerm void pvInstance Detailed Description The macros and functions defined in this section can be found in header file device usbdhidmouse h Data Structure Documentation tUSBDHIDMouseDevice Definition typedef struct nsigned short usVID nsigned short usPID nsigned short usMaxPowermA nsigned char ucPwrAttributes USBCallback pfnCallback oid xpvCBData onst unsigned char xconst xppStringDescriptors nsigned long ulNumStringDescriptors HIDMouselInstance psPrivateHIDMouseData tea gt aa aoe tUSBDHIDMouseDevice Members usVID The vendor ID that this device is to present in the device descriptor September 05 2012 159 Device Functions usPID The product ID that this device is to present in the device descriptor usMaxPowermA The m
375. to be read USBDHIDSetRxCBData Sets the client specific pointer parameter for the receive channel callback Prototype void x USBDHIDSetRxCBData void xpvInstance void xpvCBData Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDInit pvCBDaia is the pointer that client wishes to be provided on each event sent to the receive channel callback function Description The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnRxCallback function passed on USBDHIDInit If a client wants to make runtime changes in the callback pointer it must ensure that the pvin stance structure passed to USBDHIDInit resides in RAM If this structure is in flash callback data changes will not be possible Returns Returns the previous callback pointer that was being used for this instance s receive callback USBDHIDSetTxCBData Sets the client specific data pointer for the transmit callback Prototype void USBDHIDSetTxCBData void xpvInstance void xpvCBData September 05 2012 Device Functions Parameters pvinstance is the pointer to the device instance structure as returned by USBDHIDInit pvCBDaia is the pointer that client wishes to be provided on each event sent to the transmit channel callback function Description The client uses this function to change the callback data pointer passed in the first parameter on al
376. to request the data via a call to USBHHIDGetReport It is up to the device class driver to interpret the data in the report structure that is returned In some cases like the keyboard example the device class may also need to call the host class driver to issue a set report to send data to the device This is done by calling the USBHHIDSetReport interface of the host class driver This sends data to the device by using the correct USB OUT pipe Mass Storage Class Driver The mass storage host class driver provides access to devices that support the mass storage class protocol The most common of these devices are USB flash drives This host class driver provides a simple block based interface to the devices that can be matched up with an application s file system A USB host class driver for mass storage devices is included with the USB library It provides a September 05 2012 Host Functions simple block based interface that can be used with an application s file system as it provides direct block interface to mass storage devices based on logical block address The mass storage host class driver provides an application API for access to USB flash drives The API provided is meant to match with file systems that need block based read write access to flash drives The USBHMSCBlockRead and USBHMSCBlockWrite functions provide the block read and block write device access These function performs block operations at the size specified by t
377. torage device To allow for multiple devices the u nPipe and ulOutPipe parameters indicate which USB pipes to use for this call Note The pucData buffer pointer should have at least SCSI INQUIRY DATA SZ bytes of data or this function will overflow the buffer Returns This function returns the SCSI status from the command The value will be either SCSI CMD STATUS PASS or SCSI CMD STATUS FAIL USBHSCSIModeSense6 This will issue the SCSI Mode Sense 6 command to a device Prototype unsigned long USBHSCSIModeSense6 unsigned long ulInPipe unsigned long ulOutPipe unsigned long ulFlags unsigned char xpucData unsigned long xpulSize Parameters ullnPipe is the USB IN pipe to use for this command September 05 2012 261 Host Functions ulOutPipe is the USB OUT pipe to use for this command ulFlags is a combination of flags defining the exact query that is to be made pucData is the data buffer to return the results into pulSize is the size of the buffer on entry and number of bytes read on exit Description This function should be used to issue a SCSI Mode Sense 6 command to a mass storage device To allow for multiple devices the u InPipe and ulOutPipe parameters indicate which USB pipes to use for this call The call will return at most the number of bytes in the pulSize parameter however it can return less and change the pu Size parameter to the number of valid bytes in the pulSize buffer The ul
378. tring g_pSerialNumberString g_pHIDInterfaceString g_pConfigString define NUM STRING DESCRIPTORS sizeof g_pStringDescriptors b sizeof unsigned char x m Define an area of RAM of for the private instance data for the audio class driver This structure should never be accessed by the application kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk x The audio device private instance data J RKO ROKR ORR RR RR KR OR IR IR IR IR I kk ko ke I I ke ee static tAudioInstance g sAudioInstance m Define a tUSBDAudioDevice structure and initialize all fields as required for your application const tUSBDAudioDevice g sAudioDevice The Vendor ID you have been assigned by USB IF USB VID YOUR VENDOR ID The product ID you have assigned for this device 60 September 05 2012 Device Functions USB_PID_YOUR_PRODUCT_ID The vendor string for your device 8 chars USB_YOUR_VENDOR_STRING The product string for your device 16 chars USB_YOUR_PRODUCT_STRING The revision string for your device 4 chars BCD USB_YOUR_REVISION_STRING The power consumption of your device in milliamps POWER_CONSUMPTION_mA The value to be passed to the host in the USB configuration descriptor s bmAttributes field USB CONF ATTR SELF PWR A pointer to your control callbac
379. trol transactions through endpoint 0 The HID class drivers are a good example of a USB class driver that uses control transactions to send data to a USB device The USBHCDOControlTransfer function should not be called from within interrupt context as control transfers are a blocking operation that relies on interrupts to proceed Since most callbacks occur in interrupt context any calls to USBHCDOControlTransfer should be deferred until running outside the callback event The USB host HID keyboard example is a good example of performing a control transaction outside of a callback function September 05 2012 4 2 4 4 3 Host Functions Interrupt Handling All interrupt handling is done by the USB library host controller driver and most callbacks are done in interrupt context and like interrupt handlers should defer any real processing of events to occur outside the interrupt context The callbacks are used to notify the upper layers of events that occur during enumeration or during normal operation Because most of enumeration code is handled by interrupt handlers the enumeration code does require that the application call the USBHCDMain function in order to progress through the enumeration states without running all code in interrupt context Host Controller Driver Definitions Data Structures tUSBHostClassDriver tUSBHostDevice Defines DECLARE_EVENT_DRIVER VarName pfnOpen pfnClose pfnEvent Functions void USBOHostIntH
380. uld be allocated to create a configuration descriptor for a single instance of the USB HID Device This does not include the configuration descriptor which is automatically ignored by the composite device class EndCollection Definition define EndCollection Description This is a macro to assist adding End Collection entries in HID report descriptors This macro can be used to place an End Collection entry into a HID report structure This is a tag to indicate that a collection of entries has ended in the HID report structure This terminates a previous Collection entry Returns Not a function September 05 2012 3 14 3 4 3 14 3 5 3 14 3 6 Device Functions Feature This is a macro to assist adding Feature entries in HID report descriptors Definition define Feature ucValue Parameters ucValue is bit mask to specify the type of a set of feature report items Note that if the USB HID FEATURE BITF flag is required the Feature2 macro which uses a 2 byte ver sion of the Feature item tag must be used instead of this macro Description This macro takes a value and prepares it to be placed as a Feature entry into a HID report structure This specifies the type of a feature item in a report structure These refer to a bit mask of flags that indicate the type of feature for a set of items Returns Not a function Feature2 This is a macro to assist adding Feature entries in HID report descriptors
381. ur handler should check the amount of data received by calling USBDCDCRxPacketAvailable then read it using a call to USBDCDCPack etRead This causes the newly received data to be acknowledged to the host and instructs the host that it may now transmit another packet If you are unable to read the data im mediately return 0 from the callback handler and you will be called back once again a few September 05 2012 91 Device Functions 3 7 3 92 milliseconds later On USB_EVENT_DATA_REMAINING the application should return the number of bytes of data it currently has buffered This event controls timing of some incoming requests to for example send break conditions or change line transmission parameters These requests are held off until all previously received data has been processed so it is important to ensure that this event returns 0 only once any application buffers are empty Although no other events must be handled USB EVENT CONNECTED and USB EVENT DISCONNECTED Will typically be required since these indicate when a host connects or disconnects and allow the application to flush any buffers or reset state as required Attempts to send data when the host is disconnected will fail Add a transmit event handler function YourUSBTransmitEventCallback in the previous exam ple to your application taking care to handle all messages which require a particular response For the CDC device c
382. vMsgData Description USB callback function Parameters pvCBDaia is the callback pointer associated with the instance generating the callback This is a value provided by the client during initialization of the instance making the callback ulEvent is the identifier of the asynchronous event which is being notified to the client ulMsgParam is an event specific parameter pvMsgData is an event specific data pointer A function pointer provided to the USB layer by the application which will be called to notify it of all asynchronous events relating to data transmission or reception This callback is used by device class drivers and host pipe functions Returns Returns an event dependent value Enumeration Documentation tUSBMode Description The operating mode required by the USB library client This type is used by applications which wish to be able to switch between host and device modes by calling the USBStackModeSet API Enumerators USB_MODE_DEVICE The application wishes to operate as a USB device USB_MODE_HOST The application wishes to operate as a USB host USB_MODE_OTG The application wishes to operate as both a host and device using On The Go protocols to negotiate USB MODE NONE A marker indicating that no USB mode has yet been set by the applica tion USB MODE FORCE HOST The application is forcing host mode so that the VBUS and ID pins are not used or seen by the USB controller USB MODE FORCE DEV
383. vent has occurred This event is disabled by default and must be enabled via a call from the application to USBHCDEventEnable USB EVENT STALL Definition define USB_EVENT_STALL Description A device or host has detected a stall condition USB_EVENT_SUSPEND Definition define USB_EVENT_SUSPEND Description The bus has entered suspend state USB_EVENT_TX_COMPLETE Definition define USB EVENT TX COMPLETE H Description Data has been sent and acknowledged If this event is received via the USB buffer callback the ulMsg Value parameter indicates the number of bytes from the transmit buffer that have been successfully transmitted and acknowledged September 05 2012 2 2 3 21 2 2 3 22 2 2 3 23 2 2 3 24 2 2 3 25 General Purpose Functions USB EVENT UNKNOWN CONNECTED Definition define USB_EVENT_UNKNOWN_CONNECTED Description An unknown device is now attached to a USB host This value is only valid for the generic event handler and not other device handlers It is useful for applications that want to know when an unknown device is connected and what the class is of the unknown device The ullnstance is actually the class of the unsupported device that was connected USBERR_DEV_RX_DATA_ERROR Definition define USBERR_DEV_RX DATA ERROR Description The device detected a CRC error in received data U
384. vers how to implement a custom host class driver and how the host controller driver finds the driver All host class drivers must provide their own driver interface that is visible to the host controller driver As with the host class drivers that are included with the USB library this means exposing a driver interface of the type tUSBClassDriver In the example below the USBGenericOpen function is called when the host controller driver enumerates a device that matches the USB CLASS SOMECLASS interface class The USBGenericClose function is called when the device of this class is removed The following example shows a definition of a custom host class driver Example Custom Host Class Driver Interface tUSBClassDriver USBGenericClassDriver USB_CLASS_SOMECLASS USBGenericOpen USBGenericClose USBGenericIntHandler The ullnterfaceClass member of the tUSBClassDriver structure is the class read from the device s interface descriptor during enumeration This number is used to as the primary search value for a host class driver If a device is connected that matches this structure member then that host class driver is loaded The pfnOpen member of the tUSBClassDriver structure is called when a device with a matching interface class is detected This function should do whatever is necessary to handle device detection and initial configuration of the device this includes allocating any USB pipes that the device may need for communications T
385. vided in the ppStringDescriptors ar ray This must be 1 5 number of supported languages September 05 2012 3 6 3 3 6 3 1 3 6 4 3 6 4 1 3 6 4 2 Device Functions psPrivateBulkData A pointer to private instance data for this device This memory must re main accessible for as long as the bulk device is in use and must not be modified by any code outside the bulk class driver Description The structure used by the application to define operating parameters for the bulk device Define Documentation COMPOSITE_DBULK_SIZE Definition define COMPOSITE DBULK SIZE Description The size of the memory that should be allocated to create a configuration descriptor for a single instance of the USB Bulk Device This does not include the configuration descriptor which is automatically ignored by the composite device class Function Documentation USBDBulkCompositelnit Initializes bulk device operation for a given USB controller Prototype void USBDBulkCompositelnit unsigned long ulIndex const tUSBDBulkDevice x psDevice Parameters ullndex is the index of the USB controller which is to be initialized for bulk device operation psDevice points to a structure containing parameters customizing the operation of the bulk device Description This call is very similar to USBDBulklnit except that it is used for initializing an instance of the bulk device for use in a composite device Retu
386. w level driver needs to ensure that all preceding data has been processed prior to performing some action or making some notification Clients receiving this event should return the number of bytes of data that are unprocessed or 0 if no outstanding data remains USB EVENT DISCONNECTED Definition define USB_EVENT_DISCONNECTED Description The device has been disconnected from the USB host used by device classes only Note In device mode the USB EVENT DISCONNECTED will not be reported if the MCU s PB1 USBOVBUS pin is connected to a fixed 5 Volts rather than directly to the VBUS pin on the USB connector USB_EVENT_ERROR Definition define USB_EVENT_ERROR Description An error has been reported on the channel or pipe The u Msg Value parameter indicates the source s of the error and is the logical OR combination of USBERR flags defined below USB EVENT POWER DISABLE Definition define USB_EVENT_POWER_DISABLE September 05 2012 2 2 3 11 2 2 3 12 2 2 3 13 2 2 3 14 2 2 3 15 General Purpose Functions Description The controller needs power removed This is only generated on OTG parts if automatic power control is disabled USB EVENT POWER ENABLE Definition define USB EVENT POWER ENABLE Description The controller has detected a A Side cable and needs power applied This is only generated on OTG parts if auto
387. ytes of the buffer pointed to by pucData This function will not block depending on the type of pipe passed in will schedule either a send of data to the device or a read of data from the device In either case the amount of data will be limited to what will fit in the FIFO for a given endpoint Returns This function returns the number of bytes that were sent in the case of a transfer of data or it will return O for a request on a USB IN pipe 4 3 4 0 USBHCDPipeStatus Definition unsigned long USBHCDPipeStatus unsigned long ulPipe Description This function is used to return the current status of a USB HCD pipe This function will return the current status for a given USB pipe If there is no status to report this call will simply return USBHCD_PIPE_NO_CHANGE Parameters ulPipe is the USB pipe for this status request Returns This function returns the current status for the given endpoint This will be one of the USBHCD PIPE values 4 3 4 21 USBHCDPipeWrite Definition unsigned long USBHCDPipeWrite unsigned long ulPipe unsigned char xpucData unsigned long ulSize Description This function is used to write data to a USB HCD pipe Parameters ulPipe is the USB pipe to put data into pucData is a pointer to the data to send ulSize is the amount of data to send This function will block until it has sent as much data as was requested using the USB pipe s FIFO The caller should have registered a ca

Stellaris USB Library User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents