Audio Topology Configuration

1 Terminals
- 1.1 Input Terminal
- 1.2 Output Terminal
2 Units
- 2.1 Feature Unit
- 2.2 Mixer Unit
- 2.3 Selector Unit
3 Streams
- 3.1 General Stream Configuration
- 3.2 AudioStreaming Interface

The audio class provides several structures that can be used to build an audio function topology. These structures relate to units, terminals and streams. They will be declared and initialized in usbd_audio_dev_cfg.h and usbd_audio_dev_cfg.c files. Table - User Configurable Structures for Creating Audio Function Topology presents all configurable structures and the associated function that will use the structure. Functions are described in Class Instance Configuration section.

Table - User Configurable Structures for Creating Audio Function Topology

Structure	Description	Associated Function
USBD_AUDIO_IT_CFG	Configures an Input terminal.	USBD_Audio_IT_Add()
USBD_AUDIO_OT_CFG	Configures an Output terminal.	USBD_Audio_OT_Add()
USBD_AUDIO_FU_CFG	Configures a Feature Unit.	USBD_Audio_FU_Add()
USBD_AUDIO_MU_CFG	Configures a Mixer Unit.	USBD_Audio_MU_Add()
USBD_AUDIO_SU_CFG	Configures a Selector Unit.	USBD_Audio_SU_Add()
USBD_AUDIO_AS_ALT_CFG	Configures an operational AudioStreaming interface.	USBD_Audio_AS_IF_Cfg()
USBD_AUDIO_AS_IF_CFG	Gathers information about all alternate settings configuration for a given AudioStreaming interface.	USBD_Audio_AS_IF_Add() USBD_Audio_AS_IF_AddUSBD_Audio_AS_IF_Cfg()
USBD_AUDIO_STREAM_CFG	Configures stream in terms of buffers and built-in stream correction.	USBD_Audio_AS_IF_Cfg()

The use of these structures makes the audio function topology highly configurable. It allows to describe any type of audio topology.

Several tables will follow describing all fields of all units, terminals and streams structures. All units, terminals structures and some stream structures' fields follow the associated descriptor content defined in audio 1.0 specification. That's why some tables will indicate which audio 1.0 specification section to refer to for more details when it is relevant. Matching the descriptor content defined in the audio 1.0 specification allows to easily understand the audio function topology configuration.

The file usbd_audio_dev_cfg.c located in

\Micrium\Software\uC-USB-Device-V4\Cfg\Template\

It shows a typical example of terminal, unit and stream structures configuration:

Two Inputs terminals
Two Ouput terminals
Two Feature units
Two AudioStreaming interfaces

Figure - usbd_audio_dev_cfg.c - Typical Topologies Example gives a visual representation of the possible topologies that can be built with the 6 terminals and units.

Figure - usbd_audio_dec_cfg.c - Typical Topologies Example

Terminals

All terminals must have a unique ID within a given audio function. The terminals ID assignment is handled by the audio class using the functions USBD_Audio_IT_Assoc and USBD_Audio_OT_Assoc.

Input Terminal

Table - USBD_AUDIO_IT_CFG Structure Fields Description presents the Input terminal structure. Refer to audio 1.0 specification, section "4.3.2.1 Input Terminal Descriptor" for more details about certain fields.

Table - USBD_AUDIO_IT_CFG Structure Fields Description

Field	Description	Example of value	Available Predefined Value
`TerminalType`	Terminal type.	`USBD_AUDIO_TERMINAL_TYPE_MIC`	There are many terminal type defined by Audio 1.0 Terminal Types specification. Thus, there are many predefined values available in `usbd_audio.h`. Some of them typical for IT are: `USBD_AUDIO_TERMINAL_TYPE_USB_STREAMING` `USBD_AUDIO_TERMINAL_TYPE_IT_UNDEFINED` `USBD_AUDIO_TERMINAL_TYPE_MIC` `USBD_AUDIO_TERMINAL_TYPE_DESKTOP_MIC` `USBD_AUDIO_TERMINAL_TYPE_OMNI_DIR_MIC` `USBD_AUDIO_TERMINAL_TYPE_PERSONAL_MIC` `USBD_AUDIO_TERMINAL_TYPE_MIC_ARRAY` `USBD_AUDIO_TERMINAL_TYPE_PROC_MIC_ARRAY` Refer to `usbd_audio.h` for the complete list.
`LogChNbr`	Number of logical output channels in the terminal output.	`USBD_AUDIO_MONO`	`USBD_AUDIO_MONO` `USBD_AUDIO_STEREO` `USBD_AUDIO_5_1` `USBD_AUDIO_7_1`
`LogChCfg`	Spatial location of logical channel.	`USBD_AUDIO_SPATIAL_LOCATION_LEFT_FRONT`	A `OR` combination of: `USBD_AUDIO_SPATIAL_LOCATION_LEFT_FRONT` `USBD_AUDIO_SPATIAL_LOCATION_RIGHT_FRONT` `USBD_AUDIO_SPATIAL_LOCATION_CENTER_FRONT` `USBD_AUDIO_SPATIAL_LOCATION_LFE` `USBD_AUDIO_SPATIAL_LOCATION_LEFT_SURROUND` `USBD_AUDIO_SPATIAL_LOCATION_RIGHT_SURROUND` `USBD_AUDIO_SPATIAL_LOCATION_LEFT_CENTER` `USBD_AUDIO_SPATIAL_LOCATION_RIGHT_CENTER` `USBD_AUDIO_SPATIAL_LOCATION_SURROUND` `USBD_AUDIO_SPATIAL_LOCATION_SIDE_LEFT` `USBD_AUDIO_SPATIAL_LOCATION_SIDE_RIGHT` `USBD_AUDIO_SPATIAL_LOCATION_TOP`
`CopyProtEn`	Enables or disables Copy Protection.	`DEF_DISABLED`	`DEF_DISABLED` `DEF_ENABLED`
`CopyProtLevel`	Copy Protection Level.	`USBD_AUDIO_CPL_NONE`	`USBD_AUDIO_CPL_NONE` `USBD_AUDIO_CPL0` `USBD_AUDIO_CPL1` `USBD_AUDIO_CPL2`
`StrPtr`	Pointer to a string describing the Input Terminal.	"IT Microphone"	-

Output Terminal

Table - USBD_AUDIO_OT_CFG Structure Fields Description presents the Output terminal structure. Refer to audio 1.0 specification, section "4.3.2.2 Output Terminal Descriptor" for more details about certain fields.

Table - USBD_AUDIO_OT_CFG Structure Fields Description

Field	Description	Example of value	Available Predefined Value
`TerminalType`	Terminal type.	`USBD_AUDIO_TERMINAL_TYPE_USB_STREAMING`	There are many terminal type defined by Audio 1.0 Terminal Types specification. Thus, there are many predefined values available in `usbd_audio.h`. Some of them typical for OT are: `USBD_AUDIO_TERMINAL_TYPE_USB_STREAMING` `USBD_AUDIO_TERMINAL_TYPE_SPEAKER` `USBD_AUDIO_TERMINAL_TYPE_HEADPHONES` `USBD_AUDIO_TERMINAL_TYPE_HEAD_MOUNTED` `USBD_AUDIO_TERMINAL_TYPE_DESKTOP_SPEAKER` `USBD_AUDIO_TERMINAL_TYPE_ROOM_SPEAKER` `USBD_AUDIO_TERMINAL_TYPE_COMM_SPEAKER` `USBD_AUDIO_TERMINAL_TYPE_LOW_FREQ_SPEAKER` Refer to `usbd_audio.h` for the complete list.
`SourceID`	Unit or Terminal ID to which Terminal is connected to.	7	-
`CopyProtEn`	Enables or disables Copy Protection.	`DEF_DISABLED`	`DEF_DISABLED` `DEF_ENABLED`
`StrPtr`	Pointer to a string describing the Output Terminal.	"OT Speaker"	-

Units

All units must have a unique ID within a given audio function. The units ID assignment is handled by the audio class using the functions USBD_Audio_FU_Assoc , USBD_Audio_MU_Assoc() and USBD_Audio_SU_Assoc.

Feature Unit

Table - USBD_AUDIO_FU_CFG Structure Fields Description presents the Feature Unit structure. Refer to audio 1.0 specification, section "4.3.2.5 Feature Unit Descriptor" for more details about certain fields.

Table - USBD_AUDIO_FU_CFG Structure Fields Description

Field	Description	Example of value	Available Predefined Value
`LogChNbr`	Number of logical channels.	`USBD_AUDIO_STEREO`	`USBD_AUDIO_MONO` `USBD_AUDIO_STEREO` `USBD_AUDIO_5_1` `USBD_AUDIO_7_1`
`LogChCtrlPtr`	Pointer to Feature Unit Controls table	`&FU_LogChCtrlTbl[0u]`	-
`StrPtr`	Pointer to a string describing the Feature Unit.	"FU Microphone"	-

LogChCtrlPtr points to a table of 16-bit unsigned integers. These integers are used as bitmaps to describe which Feature Unit controls are supported by a certain logical channel. Refer to Table - Units and Terminals Description, Controls and Requests for the complete list of Feature Unit controls. An audio stream encodes several logical channels forming a cluster. For instance, in a stereo stream, left and right channel are two logical channels. Each Feature Unit can apply a certain control to a specific logical channel or to all channels at once. The master channel is used to designate all channels. The code snippet below shows an example of Feature Unit controls table. The table index represents the logical channel number.

CPU_INT16U  FU_LogChCtrlTbl[] = {
   (USBD_AUDIO_FU_CTRL_MUTE | USBD_AUDIO_FU_CTRL_VOL),          (1)
    USBD_AUDIO_FU_CTRL_NONE,                                    (2)
    USBD_AUDIO_FU_CTRL_NONE                                     (3)
};

(1) Controls supported by the master channel. In this example, mute and volume controls are supported. If the host sends a class-specific request to mute, muting will be applied on left and right channels at the same time. All the possible #define for Feature Unit controls are available in usbd_audio.h.

(2) Controls supported by the logical channel #1, i.e. left channel. Here, USBD_AUDIO_FU_CTRL_NONE indicates that no controls are supported for the left channel. For example, the host cannot change the volume on the left channel only. It has to change it via the master channel.

(3) Controls supported by the logical channel #2, i.e. right channel. As for the left channel, no controls are supported.

Mixer Unit

Table - USBD_AUDIO_MU_CFG Structure Fields Description presents the Mixer Unit structure. Refer to audio 1.0 specification, section "4.3.2.3 Mixer Unit Descriptor" for more details about certain fields.

Table - USBD_AUDIO_MU_CFG Structure Fields Description

Field	Description	Example of value	Available Predefined Value
`NbrInPins`	Number of Input Pins.	3	-
`LogInChNbr`	Number of logical input channels.	`(3 * USBD_AUDIO_STEREO)`	`USBD_AUDIO_MONO` `USBD_AUDIO_STEREO` `USBD_AUDIO_5_1` `USBD_AUDIO_7_1`
`LogOutChNbr`	Number of logical output channels.	`USBD_AUDIO_STEREO`	`USBD_AUDIO_MONO` `USBD_AUDIO_STEREO` `USBD_AUDIO_5_1` `USBD_AUDIO_7_1`
`LogOutChCfg`	Spatial location of logical output channels.	`(USBD_AUDIO_SPATIAL_LOCATION_LEFT_FRONT \|` `USBD_AUDIO_SPATIAL_LOCATION_RIGHT_FRONT)`	A `OR` combination of: `USBD_AUDIO_SPATIAL_LOCATION_LEFT_FRONT` `USBD_AUDIO_SPATIAL_LOCATION_RIGHT_FRONT` `USBD_AUDIO_SPATIAL_LOCATION_CENTER_FRONT` `USBD_AUDIO_SPATIAL_LOCATION_LFE` `USBD_AUDIO_SPATIAL_LOCATION_LEFT_SURROUND` `USBD_AUDIO_SPATIAL_LOCATION_RIGHT_SURROUND` `USBD_AUDIO_SPATIAL_LOCATION_LEFT_CENTER` `USBD_AUDIO_SPATIAL_LOCATION_RIGHT_CENTER` `USBD_AUDIO_SPATIAL_LOCATION_SURROUND` `USBD_AUDIO_SPATIAL_LOCATION_SIDE_LEFT` `USBD_AUDIO_SPATIAL_LOCATION_SIDE_RIGHT` `USBD_AUDIO_SPATIAL_LOCATION_TOP`
`StrPtr`	Pointer to a string describing the Mixer Unit.	"Mixer unit 11"	-

The total number of logical input channels (LogInChNbr) is equal to the addition of all logical input channels that composes each input pin. For instance, if a Mixer Unit has 3 inputs pins with the following logical input channels characteristics:

Input pin #1: stereo
Input pin #2: mono
Input pin #3: stereo

Thus the total number would be 5 in this example.

A Mixer Unit can have programmable and non-programmable mixing controls. If you need to set some programmable mixing controls, you need to use the function USBD_Audio_MU_MixingCtrlSet during the audio function initialization.

Selector Unit

Table - USBD_AUDIO_SU_CFG Structure Fields Description presents the Selector Unit structure. Refer to audio 1.0 specification, section "4.3.2.4 Selector Unit Descriptor" for more details about certain fields.

Table - USBD_AUDIO_SU_CFG Structure Fields Description

Field	Description	Example of value
`NbrInPins`	Number of Input Pins.	2
`StrPtr`	Pointer to a string describing the Selector Unit.	"Selector unit 12"

Streams

General Stream Configuration

Table - USBD_AUDIO_STREAM_CFG Structure Fields Description presents the general stream configuration structure.

Table - USBD_AUDIO_STREAM_CFG Structure Fields Description

Field	Description	Example of value	Available Predefined Value
`MaxBufNbr`	Maximum number of buffers allocated for the given stream.	40	`USBD_AUDIO_STREAM_NBR_BUF_6` `USBD_AUDIO_STREAM_NBR_BUF_12` `USBD_AUDIO_STREAM_NBR_BUF_18` `USBD_AUDIO_STREAM_NBR_BUF_24` `USBD_AUDIO_STREAM_NBR_BUF_30` `USBD_AUDIO_STREAM_NBR_BUF_36` `USBD_AUDIO_STREAM_NBR_BUF_42`
`CorrPeriodMs`	Period at which the built-in stream correction must be possibly applied. Expressed in milliseconds. For this field and the two followings, refer to section Stream Correction for more details about the built-in correction for playback and record streams.	2	-

AudioStreaming Interface

Table - USBD_AUDIO_AS_ALT_CFG Structure Fields Description presents the AudioStreaming interface configuration structure. Each AudioStreaming interface has one unique associated isochronous endpoint. Hence, there is a one-to-one relation between an AudioStreaming interface and its associated endpoint.