USB Host Audio 1.0 APIs for Harmony v2

Files added to implement Audio (v1.0) Host functions:

  • usb-host-audio-v1_0.h
  • usb-host-audio-v1_0.c

Application Programming Interfaces (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 send 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 v1.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 Object: pointer to Stream 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 Stream Info oObject

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 returns 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.
TransferHandle: 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.
TransferHandle: 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 !
}


© 2019 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
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.