Audio_device_class_api

Data Structures
struct	tAudioInstance
struct	tUSBDAudioDevice

Macros
#define	AUDIO_IN_TERMINAL_ID   1
#define	AUDIO_OUT_TERMINAL_ID   2
#define	AUDIO_CONTROL_ID   3
#define	AUDIO_INTERFACE_CONTROL   0
#define	AUDIO_INTERFACE_OUTPUT   1
#define	ISOC_OUT_ENDPOINT   USB_EP_1
#define	ISOC_OUT_EP_MAX_SIZE   ((48000*4)/1000)
#define	NUM_AUDIO_SECTIONS
#define	AUDIODESCRIPTOR_SIZE   (8)
#define	CONTROLINTERFACE_SIZE   (52)
#define	STREAMINTERFACE_SIZE   (52)
#define	COMPOSITE_DAUDIO_SIZE
#define	USBD_AUDIO_EVENT_IDLE   (USBD_AUDIO_EVENT_BASE + 0)
	This USB audio event indicates that the device is connected but not active. More...
#define	USBD_AUDIO_EVENT_ACTIVE   (USBD_AUDIO_EVENT_BASE + 1)
#define	USBD_AUDIO_EVENT_DATAOUT   (USBD_AUDIO_EVENT_BASE + 2)
#define	USBD_AUDIO_EVENT_VOLUME   (USBD_AUDIO_EVENT_BASE + 4)
#define	USBD_AUDIO_EVENT_MUTE   (USBD_AUDIO_EVENT_BASE + 5)

Typedefs
typedef void(*	tUSBAudioBufferCallback) (void *pvBuffer, uint32_t ui32Param, uint32_t ui32Event)

Functions
void *	USBDAudioInit (uint32_t ui32Index, tUSBDAudioDevice *psAudioDevice)
void *	USBDAudioCompositeInit (uint32_t ui32Index, tUSBDAudioDevice *psAudioDevice, tCompositeEntry *psCompEntry)
void	USBDAudioTerm (void *pvAudioDevice)
int32_t	USBAudioBufferOut (void *pvAudioDevice, void *pvBuffer, uint32_t ui32Size, tUSBAudioBufferCallback pfnCallback)

Variables
uint8_t	g_pui8IADAudioDescriptor [AUDIODESCRIPTOR_SIZE]
const tConfigSection	g_sIADAudioConfigSection
const uint8_t	g_pui8AudioControlInterface [CONTROLINTERFACE_SIZE]
const uint8_t	g_pui8AudioStreamInterface [STREAMINTERFACE_SIZE]
const tConfigSection	g_sAudioConfigSection
const tConfigSection	g_sAudioStreamInterfaceSection
const tConfigSection	g_sAudioControlInterfaceSection
const tConfigSection *	g_psAudioSections []
const tConfigHeader	g_sAudioConfigHeader
const tConfigHeader *const	g_ppAudioConfigDescriptors []

Detailed Description

Macro Definition Documentation

AUDIO_IN_TERMINAL_ID

#define AUDIO_IN_TERMINAL_ID   1

AUDIO_OUT_TERMINAL_ID

#define AUDIO_OUT_TERMINAL_ID   2

AUDIO_CONTROL_ID

#define AUDIO_CONTROL_ID   3

AUDIO_INTERFACE_CONTROL

#define AUDIO_INTERFACE_CONTROL   0

AUDIO_INTERFACE_OUTPUT

#define AUDIO_INTERFACE_OUTPUT   1

ISOC_OUT_ENDPOINT

#define ISOC_OUT_ENDPOINT   USB_EP_1

ISOC_OUT_EP_MAX_SIZE

#define ISOC_OUT_EP_MAX_SIZE   ((48000*4)/1000)

Referenced by USBAudioBufferOut().

NUM_AUDIO_SECTIONS

#define NUM_AUDIO_SECTIONS

Value:

(sizeof(g_psAudioSections) /                  \
                                 sizeof(g_psAudioSections[0]))

AUDIODESCRIPTOR_SIZE

#define AUDIODESCRIPTOR_SIZE   (8)

CONTROLINTERFACE_SIZE

#define CONTROLINTERFACE_SIZE   (52)

STREAMINTERFACE_SIZE

#define STREAMINTERFACE_SIZE   (52)

COMPOSITE_DAUDIO_SIZE

#define COMPOSITE_DAUDIO_SIZE

Value:

(AUDIODESCRIPTOR_SIZE +                       \
                                 CONTROLINTERFACE_SIZE + STREAMINTERFACE_SIZE)

The size of the memory that should be allocated to create a configuration descriptor for a single instance of the USB Audio Device. This does not include the configuration descriptor which is automatically ignored by the composite device class.

USBD_AUDIO_EVENT_IDLE

#define USBD_AUDIO_EVENT_IDLE   (USBD_AUDIO_EVENT_BASE + 0)

This USB audio event indicates that the device is connected but not active.

USBD_AUDIO_EVENT_ACTIVE

#define USBD_AUDIO_EVENT_ACTIVE   (USBD_AUDIO_EVENT_BASE + 1)

This USB audio event indicates that the device is connected and is now active.

USBD_AUDIO_EVENT_DATAOUT

#define USBD_AUDIO_EVENT_DATAOUT   (USBD_AUDIO_EVENT_BASE + 2)

This USB audio event indicates that the device is returning a data buffer provided by the USBAudioBufferOut() function back to the application with valid audio data received from the USB host controller. The pvBuffer parameter holds the pointer to the buffer with the new audio data and the ui32Param value holds the amount of valid data in bytes that are contained in the pvBuffer parameter.

USBD_AUDIO_EVENT_VOLUME

#define USBD_AUDIO_EVENT_VOLUME   (USBD_AUDIO_EVENT_BASE + 4)

This USB audio event indicates that a volume change has occurred. The ui32Param value contains a signed 8.8 fixed point value that represents the current volume gain/attenuation in decibels(dB). The provided message handler should be prepared to handle negative and positive values with the value 0x8000 indicating maximum attenuation. The pvBuffer parameter should be ignored.

USBD_AUDIO_EVENT_MUTE

#define USBD_AUDIO_EVENT_MUTE   (USBD_AUDIO_EVENT_BASE + 5)

This USB audio event indicates that a mute request has occurred. The ui32Param value will either be a 1 to indicate that the audio is now muted, and a value of 0 indicates that the audio has been unmuted.

Typedef Documentation

tUSBAudioBufferCallback

typedef void(* tUSBAudioBufferCallback) (void *pvBuffer, uint32_t ui32Param, uint32_t ui32Event)

Function Documentation

USBDAudioInit()

void * USBDAudioInit	(	uint32_t	ui32Index,
		tUSBDAudioDevice *	psAudioDevice
	)

This function should be called once for the audio class device to initialized basic operation and prepare for enumeration.

Parameters

ui32Index	is the index of the USB controller to initialize for audio class device operation.
psAudioDevice	points to a structure containing parameters customizing the operation of the audio device.

In order for an application to initialize the USB audio device class, it must first call this function with the a valid audio device class structure in the psAudioDevice parameter. This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB audio device.

This function returns a void pointer that must be passed in to all other APIs used by the audio class.

See the documentation on the tUSBDAudioDevice structure for more information on how to properly fill the structure members.

Returns

Returns 0 on failure or a non-zero void pointer on success.

References tUSBDAudioDevice::ppui8StringDescriptors, and USBDAudioCompositeInit().

USBDAudioCompositeInit()

void * USBDAudioCompositeInit	(	uint32_t	ui32Index,
		tUSBDAudioDevice *	psAudioDevice,
		tCompositeEntry *	psCompEntry
	)

This function should be called once for the audio class device to initialized basic operation and prepare for enumeration.

Parameters

ui32Index	is the index of the USB controller to initialize for audio class device operation.
psAudioDevice	points to a structure containing parameters customizing the operation of the audio device.
psCompEntry	is the composite device entry to initialize when creating a composite device.

In order for an application to initialize the USB audio device class, it must first call this function with the a valid audio device class structure in the psAudioDevice parameter. This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB audio device. When this audio device is part of a composite device, then the psCompEntry should point to the composite device entry to initialize. This is part of the array that is passed to the USBDCompositeInit() function.

This function returns a void pointer that must be passed in to all other APIs used by the audio class.

See the documentation on the tUSBDAudioDevice structure for more information on how to properly fill the structure members.

Returns

Returns zero on failure or a non-zero instance value that should be used with the remaining USB audio APIs.

References tUSBDAudioDevice::ppui8StringDescriptors, tDeviceInfo::psCallbacks, tCompositeEntry::psDevInfo, tCompositeEntry::pvInstance, tAudioInstance::sDevInfo, tUSBDAudioDevice::sPrivateData, and tAudioInstance::ui32USBBase.

Referenced by USBDAudioInit().

USBDAudioTerm()

void USBDAudioTerm

(

void *

pvAudioDevice

)

Shuts down the audio device.

Parameters

pvAudioDevice

is the pointer to the device instance structure as returned by USBDAudioInit().

This function terminates audio interface for the instance supplied. This function should not be called if the audio device is part of a composite device and instead the USBDCompositeTerm() function should be called for the full composite device. Following this call, the pvAudioDevice instance should not me used in any other calls.

Returns

None.

References USBDCDTerm().

USBAudioBufferOut()

int32_t USBAudioBufferOut	(	void *	pvAudioDevice,
		void *	pvBuffer,
		uint32_t	ui32Size,
		tUSBAudioBufferCallback	pfnCallback
	)

This function is used to supply buffers to the audio class to be filled from the USB host device.

Parameters

pvAudioDevice	is the pointer to the device instance structure as returned by USBDAudioInit() or USBDAudioCompositeInit().
pvBuffer	is a pointer to the buffer to fill with audio data.
ui32Size	is the size in bytes of the buffer pointed to by the pvBuffer parameter.
pfnCallback	is a callback that will provide notification when this buffer has valid data.

This function fills the buffer pointed to by the pvBuffer parameter with at most ui32Size one packet of data from the host controller. The ui32Size has a minimum value of ISOC_OUT_EP_MAX_SIZE since each USB packet can be at most ISOC_OUT_EP_MAX_SIZE bytes in size. Since the audio data may not be received in amounts that evenly fit in the buffer provided, the buffer may not be completely filled. The pfnCallback function will provide the amount of valid data that was actually stored in the buffer provided. The function will return zero if the buffer could be scheduled to be filled, otherwise the function will return a non-zero value if there was some reason that the buffer could not be added.

Returns

Returns 0 to indicate success any other value indicates that the buffer will not be filled.

References ISOC_OUT_EP_MAX_SIZE, tAudioInstance::pfnCallback, tAudioInstance::pvData, tAudioInstance::sBuffer, tUSBDAudioDevice::sPrivateData, tAudioInstance::ui32NumBytes, and tAudioInstance::ui32Size.

Variable Documentation

g_pui8IADAudioDescriptor

uint8_t g_pui8IADAudioDescriptor[AUDIODESCRIPTOR_SIZE]

Initial value:

=
{

    8,                          
    USB_DTYPE_INTERFACE_ASC,    
    0x0,                        
    0x2,                        
    USB_CLASS_AUDIO,            
    USB_SUBCLASS_UNDEFINED,     
    USB_PROTOCOL_UNDEFINED,     
    0                           
}

g_sIADAudioConfigSection

const tConfigSection g_sIADAudioConfigSection

Initial value:

=
{
    sizeof(g_pui8IADAudioDescriptor),
    g_pui8IADAudioDescriptor
}

g_pui8AudioControlInterface

const uint8_t g_pui8AudioControlInterface[CONTROLINTERFACE_SIZE]

g_pui8AudioStreamInterface

const uint8_t g_pui8AudioStreamInterface[STREAMINTERFACE_SIZE]

g_sAudioConfigSection

const tConfigSection g_sAudioConfigSection

Initial value:

=
{
    sizeof(g_pui8AudioDescriptor),
    g_pui8AudioDescriptor
}

g_sAudioStreamInterfaceSection

const tConfigSection g_sAudioStreamInterfaceSection

Initial value:

=
{
    sizeof(g_pui8AudioStreamInterface),
    g_pui8AudioStreamInterface
}

g_sAudioControlInterfaceSection

const tConfigSection g_sAudioControlInterfaceSection

Initial value:

=
{
    sizeof(g_pui8AudioControlInterface),
    g_pui8AudioControlInterface
}

g_psAudioSections

const tConfigSection* g_psAudioSections[]

Initial value:

=
{
    &g_sAudioConfigSection,
    &g_sIADAudioConfigSection,
    &g_sAudioControlInterfaceSection,
    &g_sAudioStreamInterfaceSection
}

g_sAudioConfigHeader

const tConfigHeader g_sAudioConfigHeader

Initial value:

=
{
    NUM_AUDIO_SECTIONS,
    g_psAudioSections
}

g_ppAudioConfigDescriptors

const tConfigHeader* const g_ppAudioConfigDescriptors[]

Initial value:

=
{
    &g_sAudioConfigHeader
}