USB Host Audio 1.0 APIs

Files added to implement Audio (v1.0) Host functions:
usb-host-audio-v1_0.h
usb-host-audio-v1_0.c

APIs provided:

Client Access:

Audio Stream Access :


USB_HOST_AUDIO_V1_0_AttachEventHandlerSet

Description Parameters* Returns
USB_HOST_AUDIO_V1_0_AttachEventHandlerSet sets an attach event handler. The attach event handler is called each time an Audio v1.0 device has been attached or detached. The context can be modified and returned by the event handler. This function should be called before the bus is enabled. event handler context USB_HOST_AUDIO_V1_0_RESULT

*Parameters:
event handler - Pointer to the attach event handler
context - An application defined context that can be modified
by the event handler.

Example of Setting an Attach Event Handler

USB_HOST_AUDIO_V1_RESULT result;
USB_HOST_AUDIO_V1_0_OBJ audioObj;
USB_HOST_AUDIO_V1_0_EVENT event;

// create the attach event handler
void App_MyAttachHandler(audioObj, event , 0)

{ … }

//set the attach event handler

result = USB_HOST_AUDIO_V1_0_AttachEventHandlerSet( &App_MyAttachHandler, 0 );


if(result != USB_HOST_AUDIO_V1_0_RESULT_SUCCESS)
{
//Handle error.

}


USB_HOST_AUDIO_V1_0_DeviceObjHandleGet

Description Parameters Returns
USB_HOST_AUDIO_V1_0_DeviceObjHandleGet returns the Device Object Handle for an Audio v1.0 device. This returned Device Object Handle is used by the application to perform device level operations such as getting the string descriptors. Audio device object USB_HOST_DEVICE_OBJ_HANDLE

Example of Getting a Device Handle

USB_HOST_DEVICE_OBJ_HANDLE MyHandle;
USB_HOST_AUDIO_V1_0_OBJ audioObj;

MyHandle = USB_HOST_AUDIO_V1_0_DeviceObjHandleGet(audioObj) ;

if ( MyHandle == USB_HOST_DEVICE_OBJ_HANDLE_INVALID)
// process error


USB_HOST_AUDIO_V1_0_ControlRequest

Description Parameters* Returns
USB_HOST_AUDIO_V1_0_ControlRequest schedules an Audio v1.0 control transfer. audioObject
request handle
setup packet
data
callback
context
USB_HOST_AUDIO_V1_0_RESULT

*Parameters:

audioObj - Audio v1.0 client driver object

request handle - output parameter that will contain the handle for the transfer

setup packet - Pointer to the setup packet to sent to the device in the setup

data - For control transfer with a data stage, this points to data to be sent

callback - pointer to the callback function that will be called

context - user defined parameter that is passed to the callback function

Example of scheduling an audio 1.0 control transfer

USB_HOST_AUDIO_V1_RESULT result;

USB_HOST_AUDIO_V1_0_OBJ audioObj;
USB_HOST_AUDIO_V1_0_REQUEST_HANDLE requestHandle ;
USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST setupPacket;


result = USB_HOST_AUDIO_V1_0_ControlRequest (audioObj, &requestHandle,
(USB_SETUP_PACKET *)&setupPacket, mute,
App_MyAudioControlRequestCallback,
(uintptr_t)context );

if( result != USB_HOST_AUDIO_V1_0_RESULT_SUCCESS)
{
//Handle error.
}


USB_HOST_AUDIO_V1_0_NumberOfStreamGroupsGet

Description Parameters Returns
USB_HOST_AUDIO_V1_0_NumberOfStreamGroupsGet returns the number of stream groups present in an attached Audio v1.0 device. Audio device object uint8_t

Example of Getting a Number of Stream Groups


USB_HOST_AUDIO_V1_0_OBJ audioObj;

/* Get Number of Stream Groups */
*numberofStreamGroups = USB_HOST_AUDIO_V1_0_NumberOfStreamGroupsGet(audioObj);


USB_HOST_AUDIO_V1_0_StreamGetFirst

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StreamGetFirst retrieves information from
the first audio stream in the specified audio stream index. The object
pointed to by the USB_HOST_AUDIO_V1_0_STREAM_INFO input parameter is loaded with the stream information.
Audio device object
stream group index
*stream info
USB_HOST_AUDIO_V1_RESULT

*Parameters:
audio device object - Audio v1.0 client driver object
stream group index - Stream Group Index.
*stream info - Pointer to streamInfo object

Example of Getting the first stream in the device


USB_HOST_AUDIO_V1_0_OBJ audioObj;
USB_HOST_AUDIO_STREAM_FORTMAT audioStream;
USB_HOST_AUDIO_V1_RESULT result;

. . .

result = USB_HOST_AUDIO_V1_0_StreamGetFirst*(audioObj,0 , &audioStream);

if( result != USB_HOST_AUDIO_V1_0_RESULT_SUCCESS)
{
//Handle error.
}


USB_HOST_AUDIO_V1_0_StreamGetNext

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StreamGetNext returns information about next audio stream in the specified Audio stream group. The function USB_HOST_AUDIO_V1_0_StreamGetFirst() should have been called before calling this function. Audio device object
*stream info
USB_HOST_AUDIO_V1_RESULT


Parameters:
audio device object - Audio v1.0 client driver object
*stream info - Pointer to streamInfo object

Example of Getting the next stream in the device


USB_HOST_AUDIO_V1_0_STREAM_OBJ audioStreamObj;
USB_HOST_AUDIO_STREAM_INFO audioStream;
USB_HOST_AUDIO_V1_RESULT result;

. . .

// put next stream info in structure pointed to by audioStream
result = USB_HOST_AUDIO_V1_0_StreamGetNext*(audioObj, &audioStream);

if( result != USB_HOST_AUDIO_V1_0_RESULT_END_OF_STREAM_LIST)
{
//There are more streams
}


USB_HOST_AUDIO_V1_0_StreamOpen

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StreamOpen opens the specified Audio Stream and return a handle to access the stream. Audio Stream Object USB_HOST_AUDIO_V1_0_STREAM_HANDLE

Example of Obtaining a Stream handle


USB_HOST_AUDIO_V1_0_STREAM_OBJ audioStreamObj;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE audioStreamHandle;

. . .

audioStreamHandle = USB_HOST_AUDIO_V1_0_StreamOpen( audioStreamObj) ;


USB_HOST_AUDIO_V1_0_StreamEventHandlerSet

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StreamEventHandlerSet registers an event handler to be called in response to events occurring during transfers with the attached device. handle
eventFunction
context
USB_HOST_AUDIO_V1_0_STREAM_RESULT

Parameters:
handle - Handle to the Audio Stream
eventFunction - Pointer to the desired event handler function
context - User-defined parameter passed to event handler

Example of Setting an Event handler for Host Audio

USB_HOST_AUDIO_V1_0_STREAM_HANDLE MyStreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_RESULT result;

. . .

// user written event handler function
USB_HOST_AUDIO_V1_0_STREAM_EVENT_RESPONSE MyEventHandler

( USB_HOST_AUDIO_V1_0_STREAM_HANDLE streamHandle,
USB_HOST_AUDIO_V1_0_STREAM_EVENT event,
void * eventData,
uintptr_t context ) { … }

. . .

result = USB_HOST_AUDIO_V1_0_StreamEventHandlerSet( MyStreamHandle,
&MyEventHandler , 0);


if ( result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_TRUE)
// process error


USB_HOST_AUDIO_V1_0_StreamEnable

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StreamEnable opens the specified Audio Stream and return a handle to access the stream. Audio Stream Object USB_HOST_AUDIO_V1_0_STREAM_HANDLE

Example of Enabling a Stream


USB_HOST_AUDIO_V1_0_STREAM_OBJ audioStreamObj;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE audioStreamHandle;

. . .

audioStreamHandle = USB_HOST_AUDIO_V1_0_StreamOpen( audioStreamObj) ;


USB_HOST_AUDIO_V1_0_StreamDisable

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StreamDisable Schedules an Audio stream disable request Audio Stream Handle
*requestHandle
USB_HOST_AUDIO_V1_0_STREAM_RESULT

Parameters:
Audio Stream Handle - Handle to the Audio Stream.
*requestHandle - Handle to the Stream Disable request.

Example of Disabling a Stream


USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE audioStreamHandle;

. . .

result= USB_HOST_AUDIO_V1_0_StreamDisable( audioStreamHandle, &StreamRequest) ;

if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// The disable request was unsuccessful !
}


USB_HOST_AUDIO_V1_0_StreamSampleRateSet

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StreamSampleRateSet sets the sample rate for an audio stream StreamHandle
*requestHandle
rate
USB_HOST_AUDIO_V1_0_STREAM_RESULT

Parameters:
StreamHandle - Handle to the Audio Stream
*requestHandle - Handle to the Stream Write request
source - Pointer to the buffer containing data to be written to the device
length - length of transfer

Example of Setting a Sampling Rate


USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE StreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;

. . .

result= USB_HOST_AUDIO_V1_0_StreamSampleRateSet( StreamHandle, &StreamRequest, 440) ;

if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// function request was unsuccessful !
}


USB_HOST_AUDIO_V1_0_StreamWrite

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StremWrite schedules a write to an audio stream StreamHandle
*TransferHandle
source
length
USB_HOST_AUDIO_V1_0_STREAM_RESULT

Parameters:
StreamHandle - Handle to the Audio Stream.
*requestHandle - Handle to the write transfer request.
source - Location of output buffer
length - Amount of data (in bytes)

Example of Writing a Stream


uint16_t audioSamples[96] = { } // 192 bytes of initialized data

USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE StreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;
. . .
result= USB_HOST_AUDIO_V1_0_StreamWrite( StreamHandle, &StreamRequest, &audoSemples,192) ;

if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// Write Function was unsuccessful !
}


USB_HOST_AUDIO_V1_0_StreamRead

Description Parameters Returns
USB_HOST_AUDIO_V1_0_StremRead schedules a read from an audio stream StreamHandle
*TransferHandle
destination
length
USB_HOST_AUDIO_V1_0_STREAM_RESULT

Parameters:
StreamHandle - Handle to the Audio Stream
*requestHandle - Handle to the write transfer request
destination - Location of input buffer
length - Amount of data (in bytes)

Example of Reading a Stream


uint16_t audioSamples[96]; // 192 bytes of uninitialized data

USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE StreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;
. . .
result= USB_HOST_AUDIO_V1_0_StreamRead( StreamHandle, &StreamRequest, &audoSemples,192) ;

if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// Write Function was unsuccessful !
}


20th Annual
Microchip MASTERs Conference 2016

JW Marriott Desert Ridge Resort-Phoenix, AZ

© 2016 Microchip Technology, Inc.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.