| # Digital Audio Interface (DAI) | |
| Caution: This page contains information for the deprecated DAI API. | |
| The DAI interface is a FIDL protocol exposed by DAI drivers. The DAI interface | |
| controls the configuration of a DAI link for audio data transfer. | |
| ## Notation and terminology | |
| - All indices start from 0. | |
| - Vectors of n elements are represented as `<x0,x1,...,xn-1>`, for example a | |
| vector with two elements 5 and 6 as `<5,6>`. | |
| - Vectors can be nested, i.e. `<<5,6>,<7,8>>` represents a vector with 2 | |
| vectors in it. | |
| | Term | Definition | | |
| | ---------- | -------------------------------------------------------------- | | |
| | DAI | Digital Audio Interface. Interface between audio HW, for : | |
| : : instance a TDM or PDM link between controllers and codecs. : | |
| | Frame Sync | A DAI signal that marks frame boundaries, a.k.a. LRCLK, SYNC. | | |
| | Sclk | A DAI signal used to mark the data line(s) bits transferring, : | |
| : : a.k.a. SCK, BCLK. : | |
| | Mclk | Master clock, a DAI signal sometimes needed to provide a clock | | |
| : : to DAIs. Sometimes Sclk is used as the Mclk (or Mclk is : | |
| : : derived from the Sclk within the DAI). : | |
| | Frame | The representation of a single moment in time across data, : | |
| : : frame sync and sclk in the DAI. : | |
| | Frame format | A frame's data, frame sync and sclk arrangement, e.g. location | | |
| : : of the frame sync w.r.t. samples in the data line(s). : | |
| | Slot | Within a frame, the bits reserved for a sample. A slot may be | | |
| : : bigger than needed to hold the samples, e.g. 32 bits slot : | |
| : : holding 24 or 16 bits samples. : | |
| | Channel | A single source or destination of audio samples, usually | | |
| : : to be rendered by a single speaker or captured by a single : | |
| : : microphone. Every frame will contain samples in a fixed number : | |
| : : of slots for the same fixed number of channels. : | |
| | Sample | A digital representation of sound taken at a particular time. | | |
| ## Basic operation | |
| The DAI client is responsible for configuring the DAI. The driver providing the | |
| DAI interface (from here on the DAI driver) advertises supported formats and | |
| allows the creation of a Ring Buffer for audio sample transferring. | |
| Note that the DAI drivers are expected to perform their own shutdown, just like | |
| any other driver (see the [Drivers](/docs/concepts/drivers/README.md) section). | |
| ## Protocol definition | |
| The DAI protocol is defined in FIDL at | |
| [dai.fidl](/sdk/fidl/fuchsia.hardware.audio/dai.fidl) and | |
| [dai_format.fidl](/sdk/fidl/fuchsia.hardware.audio/dai_format.fidl). | |
| Direct connection to a DAI protocol server is provided by | |
| [dai_connector.fidl](/sdk/fidl/fuchsia.hardware.audio/dai_connector.fidl). | |
| ### Reset {#reset} | |
| A DAI can be reset by a client at any time by issuing the `Reset` function. | |
| ### GetInfo {#get-info} | |
| The `GetInfo` function retrieves information from the DAI including: | |
| 1. The manufacturer name. | |
| 1. The product name. | |
| ### GetDaiFormats {#get-dai-formats} | |
| The `GetDaiFormats` function allows the DAI driver to list its supported formats | |
| for the DAI. The supported formats may include multiple sample formats, rates, | |
| etc. DAI driver provides the supported formats and their clients mandate which | |
| format is to be used in the `CreateRingBuffer` function. | |
| The DAI driver replies with a vector of `DaiSupportedFormats`, where each | |
| `DaiSupportedFormats` includes: | |
| 1. A vector of number of channels. This lists the number of channels supported | |
| by the DAI, for example `<2,4,6,8>`. A stereo DAI reports a vector with | |
| one element `<2>`. Note that a DAI that takes one channel and inputs/outputs | |
| its contents in all its inputs/outputs (e.g. 2 for a stereo amplifier) would | |
| report a vector with one element `<1>`, if it supports either one or two | |
| input channels, it would report a vector with two elements `<1,2>`. | |
| 2. A vector of sample formats. DAI sample formats, e.g. `PCM_SIGNED`. | |
| 3. A vector of frame formats, For example `I2S` or `TDM1`, or the `CUSTOM` | |
| option where `DaiFrameFormatCustom` specifies each parameter of the frame | |
| configuration individually, e.g. `frame_sync_size` and `sclk_on_raising`. | |
| 4. A vector of rates. Frame rates, for example 44100, 48000, and 96000. | |
| 5. A number of bits per slot. Number of bits in each slot in the DAI, | |
| e.g. 32 bits per slot. | |
| 6. A vector of bits per sample. Sample widths, e.g. 24 bits per sample. | |
| Within a single `DaiSupportedFormats`, any combination of provided parameters is | |
| supported. | |
| When not all combinations supported by the DAI can be described with one | |
| `DaiSupportedFormats`, the DAI 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 DAI will reply with 2 `DaiSupportedFormats`: | |
| `<<32bits>,<48KHz>>` and `<<16bits>,<96KHz>>`. For simplicity, this example | |
| ignores parameters other than rate and bits per sample. In the case where the | |
| DAI supports either 16 or 32 bits samples at either 48 or 96KHz, the DAI would | |
| reply with 1 `DaiSupportedFormats`: `<<16bits,32bits>,<48KHz,96KHz>>`. | |
| Additionally, it is assumed that bits per sample is always smaller or equal to | |
| bits per slot. Hence, a DAI can report | |
| `<<16bits_per_slot,32bits_per_slot>,<16bits_per_sample,32bits_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: | |
| 1. 16 bits slot with 16 bits samples | |
| 2. 32 bits slot with 32 bits samples | |
| 3. 32 bits slot with 16 bits samples | |
| ### GetRingBufferFormats {#get-ring-buffer-formats} | |
| Same as the streaming interface `GetSupportedFormats` function, see | |
| [Audio Streaming Interface](streaming.md). | |
| ### CreateRingBuffer {#create-ring-buffer} | |
| The client specifies both the format to use in the DAI and the format to use in | |
| the ring buffer as part of the creating of the ring buffer in the | |
| `CreateRingBuffer` function. | |
| The DAI format parameter specifies: | |
| 1. A number of channels. This is the number of channels in the DAI | |
| (for instance number of channels on a TDM bus, i.e. "on the wire"). | |
| 2. A channels to use bitmask. These are the channels in the DAI to be used for | |
| data transfer. For example to specify that both channels in an I2S DAI this | |
| must be 3. | |
| 3. A sample format. | |
| 4. A frame format. | |
| 5. A frame rate. | |
| 6. A number of bits per slot. | |
| 7. A number of bits per sample. | |
| The ring buffer format parameter is the same as the streaming interface | |
| `CreateRingBuffer` function, see | |
| [Audio Streaming Interface](streaming.md). | |
| Once `CreateRingBuffer` is successful, the DAI format configuration is considered | |
| completed and samples can be sent across the DAI once the `RingBuffer` protocol | |
| configuration is completed and the `RingBuffer` `Start` function has been called. | |
| For a description of the ring buffer functionality, see the [Audio Streaming | |
| Interface](streaming.md). | |
| {% comment %} | |
| > TODO(https://fxbug.dev/42142036): Add support for power control. | |
| > TODO(https://fxbug.dev/42142037): Add support for content protection. | |
| {% endcomment %} | |
| ## Signal processing {#signal-processing} | |
| Defined at [Audio Signal Processing](signal-processing.md). | |