This document describes the codec interface to be used between controllers and codecs in Zircon. It is meant to serve as a reference for driver-authors, and to define the interface contract which codec drivers must implement and that controllers can use. The codec interface is a Banjo protocol exposed by codec drivers.
Notes:
Term | Definition |
---|---|
Codec | A real or virtual device that encodes/decodes a signal from digital/analog to/from analog/digital including all combinations, e.g. digital to digital. Example codecs include DAC-Amplifiers combos and ADC converters. |
Controller | The part of a system that manages the audio signals, for example an SOC's audio subsystem or an independent sound card. |
DAI | Digital Audio Interface. Interface between controllers and Codecs. For example an I2S or HDA link. |
We divide the functionality provided by codecs into:
The controller and codecs function in a primary/secondary mode, with the controller being primary. Codecs advertize capabilities and a controller determines how they are used as described below. Note that the codec drivers are expected to perform initialization and shutdown as any other driver, the controller has control over the codec's state for example via the reset function but is not required to get codecs to an initialized state.
Codecs are composite devices that provide the codec protocol to controllers. It is expected that only one controller uses a codec's protocol, and one controller may use multiple codecs at once.
The codec protocol is defined in Banjo at ddk.protocol.codec.
Many Codec protocol operations are fire-and-forget, i.e. they do not expect a reply. Codec protocol operations with a reply are not considered completed until the reply of the function is received, and not considered completed successfully unless the reply contains a status ZX_OK.
A codec can be reset by a controller at any time by issuing the Reset function.
The GetInfo function retrieves information from the codec including:
Before specifying the DAI format the controller must query the codec for its bridging capabilites. If the codec is bridgeable, then the controller must enable or disable bridging based on its knowledge of the system configuration. Note that this is a singular property of a codec, i.e. a codec either supports bridging or not, and it can be set in bridged mode or not. This protocol allows configuring as bridged only 2 channel stereo codecs, with the 2 outputs of the codec electrically bridged.
The DAI Format related protocol functions allow the codec to list its supported formats for the DAI. The supported formats may include multiple sample formats, rates, etc. Each codec advertises what it can support and the controller mandates what DAI Format is to be used for each codec.
To find out what formats are supported by a given codec, the controller uses the GetDaiFormats function. The codec replies with a vector of DaiSupportedFormats, where each DaiSupportedFormats includes:
When not all combinations supported by the codec can be described with one DaiSupportedFormats, the codec returns more than one DaiSupportedFormats in the returned vector. For example, if one DaiSupportedFormats allows for 32 bits samples at 48KHz, and 16 bits samples at 96KHz, but not 32 bits samples at 96KHz, then the codec will reply with 2 DaiSupportedFormats <<32bits>,<48KHz>> and <<16bits>,<96KHz>> (for simplicity in this example we ignore parameters other than rate and bits per sample) as opposed to a case where the codec supports either 16 or 32 bits samples at either 48 or 96KHz in which case the codec would reply with 1 DaiSupportedFormats <<16bits,32bits>,<48KHz,96KHz>>.
It is assumed that bits per sample is always smaller or equal to bits per channel, hence a codec can report <<16bits_per_channel,32bits_per_channel>,<16bits_per_sample,32bits_per_sample>> (for simplicity in this example we ignore parameters other than bits per channel and bits per sample) and this does not imply that it is reporting that 32 bits per sample on 16 bits samples is valid, it specifies only the 3 valid combinations:
Using the information provided by the codec in IsBridgeable and GetDaiFormat, what is supported by the controller, and any other requirements, the controller specifies the format to use in the DAI via the SetDaiFormat function. This functions takes a parameter that specifies:
Once SetDaiFormat is successful, the DAI format configuration is considered completed and samples can be sent across the DAI. TODO(andresoportus): Add DAI format loss notification support once asynchronous notifications are added to Banjo.
Gain related support by any given codec is returned by the codec in response to a GetGainFormat function in the GainFormat structure. The controller can control gain, mute and AGC states in a codec using the SetGainState function and the corresponding GetGainState function allows retrieving the current state for the same.
The controller can query the plug detect state with the GetPlugState function. The plug state includes hardwired and plugged states. TODO(andresoportus): Add can_notify bool to PlugState once asynchronous notifications are added to Banjo.
TODO(andresoportus).
TODO(andresoportus).
TODO(andresoportus).
TODO(andresoportus).