2.4.5.2 USB_DEVICE_AUDIO_V2_Read Function

C 

USB_DEVICE_AUDIO_V2_RESULT USB_DEVICE_AUDIO_V2_Read(
    USB_DEVICE_AUDIO_V2_INDEX instanceIndex, 
    USB_DEVICE_AUDIO_V2_TRANSFER_HANDLE* transferHandle, 
    uint8_t interfaceNumber, 
    void * data, 
    size_t size
);

Summary

This function requests a data read from the USB Device Audio v2.0 Function Driver Layer. The function places a requests with driver, the request will get serviced as data is made available 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_V2_EVENT_READ_COMPLETE event. The amount of data read and the transfer handle associated with the request is returned along with the event. The transfer handle expires when event handler for the USB_DEVICE_AUDIO_V2_EVENT_READ_COMPLETE exits. If the read request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_AUDIO_V2_TRANSFER_HANDLE_INVALID.

Precondition

The function driver should have been configured.

Parameters

Parameters Description
instanceIndex USB Device Audio v2.0 Function Driver instance.
transferHandle Pointer to a USB_DEVICE_AUDIO_V2_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the read request was successful.
interfaceNum The USB Audio v2.0 streaming interface number on which read request is to placed.
data pointer to the data buffer where read data will be stored. In case of PIC32MZ device, this buffer should be located in coherent memory and should be aligned a 16 byte boundary.
size Size of the data buffer. Refer to the description section for more details on how the size affects the transfer.

Returns

  • USB_DEVICE_AUDIO_V2_RESULT_OK - The read request was successful. transferHandle contains a valid transfer handle.
  • USB_DEVICE_AUDIO_V2_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The read request could not be added.
  • USB_DEVICE_AUDIO_V2_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet.
  • USB_DEVICE_AUDIO_V2_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid.

Example 

// Shows an example of how to read. This assumes that
// device had been configured. The example attempts to read
// data from interface 1.

USB_DEVICE_AUDIO_V2_INDEX instanceIndex;
USB_DEVICE_AUDIO_V2_TRANSFER_HANDLE transferHandle;
unit8_t interfaceNumber;
// Use this attribute for PIC32MZ __attribute__((coherent, aligned(16)))
unit8_t rxBuffer[192]; 
USB_DEVICE_AUDIO_V2_RESULT readRequestResult;

instanceIndex = 0; //specify the Audio v2.0 Function driver instance number.
interfaceNumber = 1; //Specify the Audio v2.0 Streaming interface number.

readRequestResult = USB_DEVICE_AUDIO_V2_Read ( instanceIndex, &transferHandle,
                        interfaceNumber, &rxBuffer, 192);

if(USB_DEVICE_AUDIO_V2_RESULT_OK != readRequestResult)
{
    //Do Error handling here
}

// The completion of the read request will be indicated by the
// USB_DEVICE_AUDIO_V2_EVENT_READ_COMPLETE event. The transfer handle
// and the amount of data read 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_V2_Read 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, as shown in the following example:

uint8_t data[256] __attribute__((coherent, aligned(16)));