2.3.4.4 USB_DEVICE_AUDIO_Write Function

C

USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_Write(
    USB_DEVICE_AUDIO_INDEX instanceIndex, 
    USB_DEVICE_AUDIO_TRANSFER_HANDLE * transferHandle, 
    uint8_t interfaceNumber, 
    void * data, 
    size_t size
);

Summary

This function requests a data write to the USB Device Audio Function Driver Layer. The function places a requests with driver, 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_WRITE_COMPLETE event. The amount of data written and the transfer handle associated with the request is returned along with the event in writeCompleteData member of the pData parameter in the event handler.

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

Precondition

The function driver should have been configured.

Parameters

Parameters Description
instanceIndex 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.
interfaceNumber The USB Audio streaming interface number on which the write request is to placed.
data pointer to the data buffer contains the data to be written. 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.

Returns

  • USB_DEVICE_AUDIO_RESULT_OK - The read request was successful. transferHandle contains a valid transfer handle.
  • USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The write 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

// interface . This assumes that device is configured and the audio
// streaming interface is 1.

USB_DEVICE_AUDIO_INDEX instanceIndex;
USB_DEVICE_AUDIO_TRANSFER_HANDLE transferHandle;
unit8_t interfaceNumber;
unit8_t txBuffer[192]; // Use this attribute for PIC32MZ __attribute__((coherent, aligned(16)))
USB_DEVICE_AUDIO_RESULT writeRequestResult;

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

writeRequestResult = USB_DEVICE_AUDIO_Write ( instanceIndex, &transferHandle,
                            interfaceNumber, &txBuffer, 192);

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

// The completion of the write request will be indicated by the
// USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE event. The transfer handle
// and transfer size is provided along with this event.

Remarks

While the using the Audio Function Driver with the PIC32MZ USB module, the audio buffer provided to the USB_DEVICE_AUDIO_Write 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:

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