2.3.4.5 USB_DEVICE_AUDIO_StatusSend Function

C 

USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_StatusSend(
    USB_DEVICE_AUDIO_INDEX instanceIndex, 
    USB_DEVICE_AUDIO_TRANSFER_HANDLE* transferHandle, 
    USB_AUDIO_INTERRUPT_STATUS_WORD* status
);

Summary

This function requests a status write to the USB Device Audio Function Driver Layer. The function places a requests with driver to arm the status interrupt Endpoint with the status provided, the request will get serviced as data is requested by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_AUDIO_EVENT_STATUS_SEND_COMPLETE event.

The transfer handle expires when event handler for the USB_DEVICE_AUDIO_EVENT_STATUS_SEND_COMPLETE exits. If the Status Send request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID.

Description

Description of the function.

Precondition

The USB Device should be in a configured state. The USB Configuration descriptor must contain Status interrupt Endpoint descriptor.

Parameters

Parameters Description
instance USB Device Audio Function Driver instance.
transferHandle Pointer to a USB_DEVICE_AUDIO_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the write request was successful.
status pointer to the data buffer contains the Status. In case of PIC32MZ device, this buffer should be located in coherent memory and should be aligned a 16 byte boundary.

Returns

  • USB_DEVICE_AUDIO_RESULT_OK - The Status send request was successful. transferHandle contains a valid transfer handle.
  • USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The status send request could not be added.
  • USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet.
  • USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid.

Example 

 // Shows an example of how to Submit Status Send request to Host. This assumes 
 // that device has been configured. 

 USB_DEVICE_AUDIO_INDEX instanceIndex;
 USB_DEVICE_AUDIO_TRANSFER_HANDLE transferHandle;
 // Following must have __attribute__((coherent, aligned(16))) for PIC32MZ 
 USB_AUDIO_INTERRUPT_STATUS_WORD statusWord; 
 USB_DEVICE_AUDIO_RESULT statusSendResult; 

 //specify the Audio Function driver instance number.
 instanceIndex = 0; 

 // Fill in Status Word 
 statusWord.bOriginator = 0x01; //ID of the terminal  
 statusWord.originator =  0x00; //Audio Control interface 
 statusWord.memoryContentsChanged = 1; //Memory contents changed 
 statusWord.interruptPending = 1; //Interrupt is pending 

 statusSendResult = USB_DEVICE_AUDIO_StatusSend ( instanceIndex, &transferHandle,
                         &statusWord);

 if(USB_DEVICE_AUDIO_RESULT_OK != statusSendResult)
 {
     //Do Error handling here
 }

 // The completion of the read request will be indicated by the
 // USB_DEVICE_AUDIO_EVENT_STATUS_SEND event. The transfer handle
 // will be returned along with the event.

Remarks

While the using the Audio Function Driver with PIC32MZ USB module, the audio buffer provided to the USB_DEVICE_AUDIO_StatusSend function should be placed in coherent memory and aligned at a 16 byte boundary. This can be done by declaring the buffer using the __attribute__((coherent, aligned(16))) attribute. An example is shown here 

USB_AUDIO_INTERRUPT_STATUS_WORD statusWord __attribute__((coherent, aligned(16)));