Endpoint Synchronization Types

To maintain glitch-free audio, AppleUSBAudio must regularly present timestamps to Core Audio that accurately represent the audio data rate of the engine (see “The Audio I/O Model Up Close” in the Audio Device Driver Programming Guide for more details.) When the device publishes the correct endpoint synchronization types in its configuration descriptors, AppleUSBAudio can pick the appropriate stream from which to generate the most accurate timestamps for the engine.

The driver supports all three synchronization types defined by the USB 2.0 Specification (see Section 5.12.4.1 Synchronization Type and Table 5-12):

• Synchronous: synced to host via SOF

• Asynchronous: not synced to host, data rate is locked to a free-running internal clock on the device or an external source like S/PDIF

• Adaptive: synced to host via data rate

Table 3 below lists synchronization type combinations that work well with Mac OS X.

If a device supports multiple clock domains, USB Audio 2.0 clock entity descriptors should be used to clearly communicate its clock architecture to AppleUSBAudio. Please see the Clock Entities section later in this article for information about these descriptors.

Feedback for Asynchronous Output Streams

To stream audio via an asynchronous sink endpoint, a device must continuously update the host of its desired data rate relative to the SOF frequency (see Section 5.10.4 of the USB 1.0 Spec and Section 5.12.4 of the USB 2.0 Spec.) AppleUSBAudio supports two feedback mechanisms:

1. Explicit feedback endpoint: The device provides an associated isochronous feedback endpoint which sends packets containing the number of samples per USB (micro)frame (see Section 3.7.2.2 of the USB Audio 1.0 Spec and Section 3.16.2.2 of the USB Audio 2.0 Spec.)

2. Implicit feedback: The driver uses the number of sample frames in the main input stream's packets to construct the packets for all output streams within the engine.  No feedback endpoint is required (see Section 5.12.4.3 of the USB 2.0 Spec.)

In order to use implicit feedback, the device must satisfy the following requirements:

• Asynchronous input and output streams reside on one engine (i.e. needs to meet criteria for the Unified Engine Model.)

• The polling intervals (bInterval) for the stream endpoints must match.

• Either the input stream endpoint “Usage type” is set to “Implicit feedback data endpoint” (USB Audio 2.0 only, Section 4.10.1.1) and/or the sync feedback endpoint is omitted (see Table 4.)

Table 4 illustrates the synchronization method used by the driver in various scenarios. If indicated by the “Usage type” field, the driver will treat the input stream as implicit feedback and ignore an additional sync feedback endpoint if present (Config 2.) This allows a device to implement both feedback mechanisms if needed for compatibility reasons. Config 3 is only recommended for USB Audio 1.0 devices where endpoint “Usage type” is not available.

Maximum Packet Size

It is very important to specify the correct value for each endpoint’s maximum packet size because an incorrect value could result in audio corruption. The packet size cannot exceed 1023 bytes for full speed devices and 1024 bytes for high speed devices (Section 5.6.3 of the USB 2.0 Specification.) To determine the exact value, one needs to identify the supported format and sample rate configuration that consumes the largest possible bandwidth for the endpoint.

The amount of audio data contained in each packet may vary depending on the speed of the device. If the device is full speed, each packet contains 1 millisecond (ms) of data. On high speed USB devices, each USB frame is split into eight 125 microsecond segments called microframes. Endpoints can specify the polling interval at which transfers can occur, i.e. every microframe, every other microframe, etc. This frequency must be taken into account when calculating the max packet size. (At this time, AppleUSBAudio supports at most one transaction per microframe. See the High Speed Streaming section for more information.)

Calculation Examples

The following full and high speed examples illustrate the calculation procedure:

A) 48 kHz / 24-bit / 2 channel / full speed

Each sample frame contains 2 channels of 3 byte samples which is 6 bytes per sample frame. The packet size is calculated as follows:

This value assumes that the data rate will never vary, as is the case when the stream is synchronous to SOF. If the endpoint is adaptive or asynchronous, one additional sample frame should be added to accommodate adjustments in the data rate. Section 2.3.1.1 of the Audio Data Formats 2.0 Specification limits variation in the packet size by +/- 1 sample frame.

Synchronous: Max packet size = 288 bytes

Adaptive or asynchronous: Max packet size = 288 + 6 = 294 bytes

B) 44.1 kHz / 16-bit / 8 channel / full speed

Each sample frame contains 8 channels of 2 byte samples which is 16 bytes per sample frame. The packet size is calculated as follows:

Packets cannot contain partial sample frames. So, while most packets will contain 44 sample frames, every tenth packet will contain 45 sample frames.

Synchronous, adaptive or asynchronous*: Max packet size = 720 bytes

*The extra permitted sample frame has already been included.

C) 192 kHz / 32-bit / 10 channel / high speed

This example assumes one transaction every microframe (i.e. the polling interval is 1 microframe.)

Each sample frame contains 10 channels of 4 byte samples which is 40 bytes per sample frame. The packet size is calculated as follows:

Synchronous:

Adaptive or asynchronous: Max packet size = 960 + 40 = 1000 bytes

Table 5  Summary of max packet size calculation examples. “Sync” indicates synchronous endpoints, “adapt” indicates adaptive endpoints, and “async” refers to asynchronous endpoints.

Example	Sample rate (Hz)	Bit depth	Channels	Average sample frames per ms	Max sample frames per ms (sync)	Trans-actions per ms	Max packet size, sync (bytes)	Max packet size, adapt & async (bytes)
A (full)	48000	24	2	48	48	1	288	294
B (full)	44100	16	8	44.1	45	1	720	720
C (high)	192000	32	10	7680	7680	8	960	1000

Control Publishing Rules

Since multiple Feature Units can exist in an audio path, AppleUSBAudio uses a special algorithm to select the Feature Unit that contains the logical controls to expose to the Audio HAL. The algorithm seeks to accommodate the most common cases and to minimize undesirable side effects. The rules are as follows:

* Volume/mute for input sources: AppleUSBAudio will publish the controls contained in the Feature Unit closest to the selector unit on the Input Terminal side as shown in Figure 3.

* Volume/mute for output sources: AppleUSBAudio will publish the controls contained in the Feature Unit closest to the Output Terminal as shown in Figure 4.

* Hardware play through with Mixer Unit in path: AppleUSBAudio will publish controls contained in a Feature Unit between the Input Terminal and the Mixer Unit.  Searching from the Input Terminal to the Mixer Unit, the driver selects the first Feature Unit that isn't shared with another audio path. An example is shown in Figure 5.

* Hardware play through without Mixer Unit in path: AppleUSBAudio will publish controls contained in the Feature Unit closest to the Input Terminal that isn't shared with another audio path.

Device Name

The device name will appear in many places on the Mac, including in Audio MIDI Setup, Sound Preferences, and in third party audio applications. Core Audio represents each engine as a device in the system. If an engine has a name, Core Audio will use that as the device name, otherwise it will use the USB device name. Figure 6 shows how AppleUSBAudio and Core Audio will determine the descriptive name assigned to the device, depending on the number of streams associated with the engine, and the presence of the control and stream interface names, and USB device name.

Channel Names

AppleUSBAudio supports the Audio Cluster Descriptors as described in section 3.7.2.3 “Audio Channel Cluster Format” of the USB Audio 1.0 specification and section 4.1 “Audio Channel Cluster Descriptor” in the USB Audio 2.0 specification. These descriptors allow device developers to name the channels in a stream, using either predefined names (such as “Front Left”, or “Low Frequency Effects”, etc.) or custom names. Listing 1 shows the descriptor fields of interest, as represented in AppleUSBAudio. Please refer to the USB Audio specification sections previously mentioned for a thorough explanation of the use of these fields.

Listing 1  Structure representing the Audio Cluster Descriptor in AppleUSBAudio

typedef struct AudioClusterDescriptor {

    UInt8		bNrChannels;

    UInt32		bmChannelConfig;

    UInt8		iChannelNames;

} AudioClusterDescriptor, *AudioClusterDescriptorPtr;

Audio Cluster Descriptors can be embedded in Input Terminal, Mixer, Processing, and Extension Unit descriptors. AppleUSBAudio searches for the Audio Cluster Descriptor on an audio path starting from the Output Terminal to the Input Terminal and uses the first one it finds.

High Speed Streaming

(USB 2.0, Sections 5.6 and 9.6.6)

Mac OS X supports high speed streaming, up to 1024 bytes per microframe for each isochronous endpoint, including overhead.

For example, Snow Leopard (and later) is able to stream 10 channels of 32-bit audio at 192 kHz to and from a USB Audio 2.0 device. Additional information pertaining to isochronous data transfer can be found in the USB Device Interface Guide.

Interface Association Descriptor

(USB Audio 2.0, Section 4.6)

This required descriptor identifies an Audio Interface Collection. The interfaces grouped in the collection must be contiguously numbered and in the following order:

1. AudioControl Interface (mandatory)

2. AudioStreaming Interface(s)

3. MIDIStreaming Interface(s)

Clock Entities

(USB Audio 2.0, Sections 3.13.11, 4.7.2.1 - 4.7.2.3)

Clock Domains are described using the new 2.0 Clock Entities: Clock Source, Clock Selector, and Clock Multiplier. The AppleUSBAudio driver also supports the associated clock related AudioControl Requests as specified in Sections 5.2.5.1 through 5.2.5.3.

Unlike USB Audio 1.0 devices, the use of switching the Alternate Setting to control the sampling frequency is prohibited for USB Audio 2.0 devices. Instead, a Clock Source entity serves as the master clock for a clock domain, which can provide a sampling signal frequency. Clock Selectors enable both the host and the audio function to switch clock inputs. Figure 7 shows how a Clock Selector appears in AMS. The Clock Multiplier provides a mechanism to derive additional sampling frequencies within a clock domain that are synchronous to the input clock signal.

Status Interrupt Control Endpoint

(USB Audio 2.0, Section 4.8.2.1, 6)

AppleUSBAudio contains additional support for parsing the Interrupt Data Message Format in Section 6.1. The only additional 2.0 status interrupt support added to the driver was for the Clock Source unit.

AppleUSBAudio responds in various ways to an interrupt generated from a Clock Source unit that is currently driving the data rate. If the clock validity bit indicates the clock is invalid and the audio topology contains a Clock Selector, the driver searches for an alternate valid Clock Source and switches to that (as described in Table 6.) If the Clock Source is valid, then it assumes the sample rate has changed. In this case, it republishes the available rates and updates the current device sample rate on the host.