|
MPLAB Harmony USB Stack
|
USB Device Audio v2.0 Function Driver Events
These events are specific to a USB Device Audio v2.0 Function Driver instance. An event may have some data associated with it. This is provided to the event handling function. Each event description contains details about this event data (pData) and other parameters passed along with the event, to the event handler.
Events associated with the Audio v2.0 Function Driver Specific Control Transfers require application response. The application should respond to these events by using the USB_DEVICE_ControlReceive(), USB_DEVICE_ControlSend() and USB_DEVICE_ControlStatus() functions.
Calling the USB_DEVICE_ControlStatus() function with a USB_DEVICE_CONTROL_STATUS_ERROR will stall the control transfer request. The application would do this if the control transfer request is not supported. Calling the USB_DEVICE_ControlStatus() function with a USB_DEVICE_CONTROL_STATUS_OK will complete the status stage of the control transfer request. The application would do this if the control transfer request is supported.
The following code shows an example of a possible event handling scheme.
// This code example shows all USB Audio v2.0 Function Driver possible // events and a possible scheme for handling these events. // In this case event responses are not deferred. void APP_USBDeviceAudioEventHandler ( USB_DEVICE_AUDIO_V2_INDEX instanceIndex , USB_DEVICE_AUDIO_V2_EVENT event , void * pData, uintptr_t context ) { switch (event) { case USB_DEVICE_AUDIO_V2_EVENT_READ_COMPLETE: // This event indicates that a Audio v2.0 Read Transfer request // has completed. pData should be interpreted as a // USB_DEVICE_AUDIO_V2_EVENT_DATA_READ_COMPLETE pointer type. // This contains the transfer handle of the read transfer // that completed and amount of data that was read. break; case USB_DEVICE_AUDIO_V2_EVENT_WRITE_COMPLETE: // This event indicates that a Audio v2.0 Write Transfer request // has completed. pData should be interpreted as a // USB_DEVICE_AUDIO_V2_EVENT_DATA_WRITE_COMPLETE pointer type. // This contains the transfer handle of the write transfer // that completed and amount of data that was written. break; case USB_DEVICE_AUDIO_V2_EVENT_INTERFACE_SETTING_CHANGED: // This event occurs when the host sends Set Interface request // to the Audio v2.0 USB Device. pData will be a pointer to a // USB_DEVICE_AUDIO_V2_EVENT_DATA_INTERFACE_SETTING_CHANGED. This // contains the interface number whose setting was // changed and the index of the alternate setting. // The application should typically enable the audio function // if the interfaceAlternateSettting member of pData is greater // than 0. break; case USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_UNKNOWN: // This event indicates that the Audio v2.0 function driver has // received a control transfer which it cannot decode. pData // will be a pointer to USB_SETUP_PACKET type pointer. The // application should decode the packet and take the required // action using the USB_DEVICE_ControlStatus(), // USB_DEVICE_ControlSend() and USB_DEVICE_ControlReceive() // functions. break; case USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_DATA_SENT: // This event indicates the data send request associated with // the latest USB_DEVICE_ControlSend() function was // completed. pData will be NULL. case USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_DATA_RECEIVED: // This event indicates the data receive request associated with // the latest USB_DEVICE_ControlReceive() function was // completed. pData will be NULL. The application can either // acknowledge the received data or reject it by calling the // USB_DEVICE_ControlStatus() function. break; case USB_DEVICE_AUDIO_V2_CUR_ENTITY_SETTINGS_RECEIVED: // This event indicates the Current entity request has been // received. USB_AUDIO_CONTROL_INTERFACE_REQUEST* controlRequest; controlRequest = (USB_AUDIO_CONTROL_INTERFACE_REQUEST*) setupPkt; switch(controlRequest->entityID) { case APP_ID_CLOCK_SOURCE: USB_AUDIO_CLOCKSOURCE_CONTROL_REQUEST* clockSourceRequest; clockSourceRequest = (USB_AUDIO_CLOCKSOURCE_CONTROL_REQUEST*) controlRequest; if (clockSourceRequest->bRequest == CUR) { switch(clockSourceRequest->controlSelector) { case CS_SAM_FREQ_CONTROL: { if ((controlRequest->bmRequestType & 0x80) == 0) { //A control write transfer received //from Host. Now receive data from Host. USB_DEVICE_ControlReceive( appData.usbDevHandle, void *) &(appData.clockSource), 4 ); appData.currentAudioControl = APP_USB_AUDIO_CLOCKSOURCE_CONTROL; } else { //Handle Get request USB_DEVICE_ControlSend( appData.usbDevHandle, (void *)&(appData.clockSource), 4 ); appData.currentAudioControl = APP_USB_CONTROL_NONE; } } break; case CS_CLOCK_VALID_CONTROL: { if ((controlRequest->bmRequestType & 0x80) == 0x80) { //Handle Get request USB_DEVICE_ControlSend( appData.usbDevHandle, (void *)&(appData.clockValid), 1); } else { USB_DEVICE_ControlStatus( appData.usbDevHandle, USB_DEVICE_CONTROL_STATUS_ERROR); } } break; default: //This USB Audio Speaker application does //not support any other feature unit request //from Host. So Stall if any other feature //unit request received from Host. USB_DEVICE_ControlStatus ( appData.usbDevHandle, USB_DEVICE_CONTROL_STATUS_ERROR); break; } } case USB_DEVICE_AUDIO_V2_RANGE_ENTITY_SETTINGS_RECEIVED: // This event indicates the Range entity request has been // received. USB_AUDIO_CONTROL_INTERFACE_REQUEST* controlRequest; controlRequest = (USB_AUDIO_CONTROL_INTERFACE_REQUEST*)setupPkt; switch(controlRequest->entityID) { case APP_ID_CLOCK_SOURCE: USB_AUDIO_CLOCKSOURCE_CONTROL_REQUEST* clockSourceRequest; clockSourceRequest = (USB_AUDIO_CLOCKSOURCE_CONTROL_REQUEST*) controlRequest; if (clockSourceRequest->bRequest == RANGE) { switch(clockSourceRequest->controlSelector) { case CS_SAM_FREQ_CONTROL: { if ((controlRequest->bmRequestType & 0x80) == 0x80) { //A control read transfer received from // Host. Now send data to Host. USB_DEVICE_ControlSend( appData.usbDevHandle, void *) &(appData.clockSourceRange), sizeof(appData.clockSourceRange)); } else { //Handle Get request // USB_DEVICE_ControlReceive( appData.usbDevHandle, (void *)&(appData.clockSourceRange[0]), sizeof(appData.clockSourceRange) ); USB_DEVICE_ControlStatus( appData.usbDevHandle, USB_DEVICE_CONTROL_STATUS_ERROR); } } break; default: //This USB Audio Speaker application does // not support any other feature unit // request from Host. So Stall if any other // feature unit request received from Host. USB_DEVICE_ControlStatus ( appData.usbDevHandle, USB_DEVICE_CONTROL_STATUS_ERROR); break; } } }
typedef enum { USB_DEVICE_AUDIO_V2_EVENT_WRITE_COMPLETE, USB_DEVICE_AUDIO_V2_EVENT_READ_COMPLETE, USB_DEVICE_AUDIO_V2_EVENT_INTERFACE_SETTING_CHANGED, USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_DATA_RECEIVED, USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_DATA_SENT, USB_DEVICE_AUDIO_V2_CUR_ENTITY_SETTINGS_RECEIVED, USB_DEVICE_AUDIO_V2_RANGE_ENTITY_SETTINGS_RECEIVED, USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_UNKNOWN } USB_DEVICE_AUDIO_V2_EVENT;
|
Members |
Description |
|
USB_DEVICE_AUDIO_V2_EVENT_WRITE_COMPLETE |
This event occurs when a write operation scheduled by calling the USB_DEVICE_AUDIO_V2_Write function has completed. The pData member in the event handler will point to USB_DEVICE_AUDIO_V2_EVENT_WRITE_COMPLETE_DATA type. |
|
USB_DEVICE_AUDIO_V2_EVENT_READ_COMPLETE |
This event occurs when a read operation scheduled by calling the USB_DEVICE_AUDIO_V2_Read function has completed. The pData member in the event handler will point to USB_DEVICE_AUDIO_V2_EVENT_READ_COMPLETE_DATA type. |
|
USB_DEVICE_AUDIO_V2_EVENT_INTERFACE_SETTING_CHANGED |
This event occurs when the Host requests the Audio v2.0 USB Device to set an alternate setting on an interface present in this audio function. An Audio v2.0 USB Device will typically feature a default interface setting and one or more alternate interface settings. The pData member in the event handler will point to the USB_DEVICE_AUDIO_V2_EVENT_DATA_INTERFACE_SETTING_CHANGED type. This contains the index of the interface whose setting must be changed and the index of the alternate setting. The application may enable or disable audio functions based on the interface setting. |
|
USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_DATA_RECEIVED |
This event occurs when the data stage of a control write transfer has completed. This would occur after the application would respond with a USB_DEVICE_ControlReceive function, which may possibly have been called in response to a USB_DEVICE_AUDIO_V2_EVENT_ENTITY_SETTINGS_RECEIVED event This event notifies the application that the data is received from Host and is available at the location passed by the USB_DEVICE_ControlReceive function. If the received data is acceptable to the application, it should acknowledge the data by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_OK flag.The application can reject the received data by calling the USB_DEVICE_ControlStatus function with the USB_DEVICE_CONTROL_STATUS_ERROR flag. The pData parameter will be NULL. |
|
USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_DATA_SENT |
This event occurs when the data stage of a control read transfer has completed. This would occur when the application has called the USB_DEVICE_ControlSend function to complete the data stage of a control transfer. The event indicates that the data has been transmitted to the host. The pData parameter will be NULL. |
|
USB_DEVICE_AUDIO_V2_CUR_ENTITY_SETTINGS_RECEIVED |
This event occurs when the Host sends an Audio 2.0 Control specific Set Current Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with the USB_DEVICE_ControlStatus and USB_DEVICE_ControlReceive functions. |
|
USB_DEVICE_AUDIO_V2_RANGE_ENTITY_SETTINGS_RECEIVED |
This event occurs when the Host sends an Audio 2.0 Control specific Set Range Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlReceive functions. |
|
USB_DEVICE_AUDIO_V2_EVENT_CONTROL_TRANSFER_UNKNOWN |
This event occurs when the Audio v2.0 function driver receives a control transfer request that could not be decoded by Audio Function driver.The pData parameter will point to a USB_SETUP_PACKET type containing the setup packet. The application must analyze this Setup packet and use the USB_DEVICE_ControlSend, USB_DEVICE_ControlReceive, or the USB_DEVICE_ControlStatus function to advance the control transfer or complete it. |
The application can defer responses to events triggered by control transfers. In that, the application can respond to the control transfer event after exiting the event handler. This allows the application some time to obtain the response data rather than having to respond to the event immediately. Note that a USB host will typically wait for an event response for a finite time duration before timing out and canceling the event and associated transactions. Even when deferring response, the application must respond promptly if such time-out have to be avoided.
|
MPLAB Harmony USB Stack
|