Digital Audio Interface (DAI)

Overview

The DAI (Digital Audio Interface) is a generic high level API for audio drivers. It can be configured with bespoke data for vendor specific configuration.

Configuration Options

Related configuration options:

CONFIG_DAI

API Reference

group dai_interface

DAI Interface.

Since: 3.1
Version: 0.1.0

The DAI API provides support for the standard I2S (SSP) and its common variants. It supports also DMIC, HDA and SDW backends. The API has a config function with bespoke data argument for device/vendor specific config. There are also optional timestamping functions to get device specific audio clock time.

Defines

DAI_FORMAT_CLOCK_PROVIDER_MASK: Used to extract the clock configuration from the format attribute of struct dai_config.

DAI_FORMAT_PROTOCOL_MASK: Used to extract the protocol from the format attribute of struct dai_config.

DAI_FORMAT_CLOCK_INVERSION_MASK: Used to extract the clock inversion from the format attribute of struct dai_config.

Enums

enum dai_clock_provider

DAI clock configurations.

This is used to describe all of the possible clock-related configurations w.r.t the DAI and the codec.

Values:

enumerator DAI_CBP_CFP = (0 << 12)

codec BLCK provider, codec FSYNC provider

codec BCLK consumer, codec FSYNC provider

enumerator DAI_CBC_CFP = (2 << 12): codec BCLK provider, codec FSYNC consumer

enumerator DAI_CBP_CFC = (3 << 12): codec BCLK consumer, codec FSYNC consumer

enumerator DAI_CBC_CFC = (4 << 12)

enum dai_protocol

DAI protocol.

The communication between the DAI and the CODEC may use different protocols depending on the scenario.

Values:

enumerator DAI_PROTO_I2S = 1: I2S.

enumerator DAI_PROTO_RIGHT_J: Right Justified.

enumerator DAI_PROTO_LEFT_J: Left Justified.

enumerator DAI_PROTO_DSP_A: TDM, FSYNC asserted 1 BCLK early.

enumerator DAI_PROTO_DSP_B: TDM, FSYNC asserted at the same time as MSB.

enumerator DAI_PROTO_PDM: Pulse Density Modulation.

enum dai_clock_inversion

DAI clock inversion.

Some applications may require a different clock polarity (FSYNC/BCLK) compared to the default one chosen based on the protocol.

Values:

enumerator DAI_INVERSION_NB_NF = 0

no BCLK inversion, no FSYNC inversion

no BCLK inversion, FSYNC inversion

enumerator DAI_INVERSION_NB_IF = (2 << 8): BCLK inversion, no FSYNC inversion.

enumerator DAI_INVERSION_IB_NF = (3 << 8): BCLK inversion, FSYNC inversion.

enumerator DAI_INVERSION_IB_IF = (4 << 8)

enum dai_type

Types of DAI.

The type of the DAI. This ID type is used to configure bespoke DAI HW settings.

DAIs have a lot of physical link feature variability and therefore need different configuration data to cater for different use cases. We usually need to pass extra bespoke configuration prior to DAI start.

Values:

enumerator DAI_LEGACY_I2S = 0: Legacy I2S compatible with i2s.h.

enumerator DAI_INTEL_SSP: Intel SSP.

enumerator DAI_INTEL_DMIC: Intel DMIC.

enumerator DAI_INTEL_HDA: Intel HD/A.

enumerator DAI_INTEL_ALH: Intel ALH.

enumerator DAI_IMX_SAI: i.MX SAI

enumerator DAI_IMX_ESAI: i.MX ESAI

enumerator DAI_AMD_BT: Amd BT.

enumerator DAI_AMD_SP: Amd SP.

enumerator DAI_AMD_DMIC: Amd DMIC.

enumerator DAI_MEDIATEK_AFE: Mtk AFE.

enumerator DAI_INTEL_SSP_NHLT: nhlt ssp

enumerator DAI_INTEL_DMIC_NHLT: nhlt ssp

enumerator DAI_INTEL_HDA_NHLT: nhlt Intel HD/A

enumerator DAI_INTEL_ALH_NHLT: nhlt Intel ALH

enum dai_dir

DAI Direction.

Values:

enumerator DAI_DIR_TX = 0: Transmit data.

enumerator DAI_DIR_RX: Receive data.

enumerator DAI_DIR_BOTH: Both receive and transmit data.

enum dai_state

Interface state.

Values:

enumerator DAI_STATE_NOT_READY = 0

The interface is not ready.

   The interface was initialized but is not yet ready to receive /
   transmit data. Call dai_config_set() to configure interface and change
   its state to READY.

enumerator DAI_STATE_READY: The interface is ready to receive / transmit data.

enumerator DAI_STATE_RUNNING: The interface is receiving / transmitting data.

enumerator DAI_STATE_PRE_RUNNING: The interface is clocking but not receiving / transmitting data.

enumerator DAI_STATE_PAUSED: The interface paused.

enumerator DAI_STATE_STOPPING: The interface is draining its transmit queue.

enumerator DAI_STATE_ERROR: TX buffer underrun or RX buffer overrun has occurred.

enum dai_trigger_cmd

Trigger command.

Values:

enumerator DAI_TRIGGER_START = 0

Start the transmission / reception of data.

   If DAI_DIR_TX is set some data has to be queued for transmission by
   the dai_write() function. This trigger can be used in READY state
   only and changes the interface state to RUNNING.

enumerator DAI_TRIGGER_PRE_START

Optional - Pre Start the transmission / reception of data.

   Allows the DAI and downstream codecs to prepare for audio Tx/Rx by
   starting any required clocks for downstream PLL/FLL locking.

enumerator DAI_TRIGGER_STOP

Stop the transmission / reception of data.

   Stop the transmission / reception of data at the end of the current
   memory block. This trigger can be used in RUNNING state only and at
   first changes the interface state to STOPPING. When the current TX /
   RX block is transmitted / received the state is changed to READY.
   Subsequent START trigger will resume transmission / reception where
   it stopped.

enumerator DAI_TRIGGER_PAUSE

Pause the transmission / reception of data.

   Pause the transmission / reception of data at the end of the current
   memory block. Behavior is implementation specific but usually this
   state doesn't completely stop the clocks or transmission. The DAI could
   be transmitting 0's (silence), but it is not consuming data from outside.

enumerator DAI_TRIGGER_POST_STOP

Optional - Post Stop the transmission / reception of data.

   Allows the DAI and downstream codecs to shutdown cleanly after audio
   Tx/Rx by stopping any required clocks for downstream audio completion.

enumerator DAI_TRIGGER_DRAIN

Empty the transmit queue.

   Send all data in the transmit queue and stop the transmission.
   If the trigger is applied to the RX queue it has the same effect as
   DAI_TRIGGER_STOP. This trigger can be used in RUNNING state only and
   at first changes the interface state to STOPPING. When all TX blocks
   are transmitted the state is changed to READY.

enumerator DAI_TRIGGER_DROP

Discard the transmit / receive queue.

   Stop the transmission / reception immediately and discard the
   contents of the respective queue. This trigger can be used in any
   state other than NOT_READY and changes the interface state to READY.

enumerator DAI_TRIGGER_PREPARE

Prepare the queues after underrun/overrun error has occurred.

   This trigger can be used in ERROR state only and changes the
   interface state to READY.

enumerator DAI_TRIGGER_RESET

Reset.

   This trigger frees resources and moves the driver back to initial
   state.

enumerator DAI_TRIGGER_COPY

Copy.

   This trigger prepares for data copying.

Functions

static inline int dai_probe(const struct device *dev)

Probe operation of DAI driver.

The function will be called to power up the device and update for example possible reference count of the users. It can be used also to initialize internal variables and memory allocation.

Parameters:

dev – Pointer to the device structure for the driver instance.

Return values:

0 – If successful.

static inline int dai_remove(const struct device *dev)

Remove operation of DAI driver.

The function will be called to unregister/unbind the device, for example to power down the device or decrease the usage reference count.

Parameters:

dev – Pointer to the device structure for the driver instance.

Return values:

0 – If successful.

static inline int dai_config_set(const struct device *dev, const struct dai_config *cfg, const void *bespoke_cfg)

Configure operation of a DAI driver.

The dir parameter specifies if Transmit (TX) or Receive (RX) direction will be configured by data provided via cfg parameter.

The function can be called in NOT_READY or READY state only. If executed successfully the function will change the interface state to READY.

If the function is called with the parameter cfg->frame_clk_freq set to 0 the interface state will be changed to NOT_READY.

Parameters:

dev – Pointer to the device structure for the driver instance.
cfg – Pointer to the structure containing configuration parameters.
bespoke_cfg – Pointer to the structure containing bespoke config.

Return values:

0 – If successful.
-EINVAL – Invalid argument.
-ENOSYS – DAI_DIR_BOTH value is not supported.

static inline int dai_config_get(const struct device *dev, struct dai_config *cfg, enum dai_dir dir)

Fetch configuration information of a DAI driver.

Parameters:

dev – Pointer to the device structure for the driver instance
cfg – Pointer to the config structure to be filled by the instance
dir – Stream direction: RX or TX as defined by DAI_DIR_*

Return values:

0 – if success, negative if invalid parameters or DAI un-configured

static inline const struct dai_properties *dai_get_properties(const struct device *dev, enum dai_dir dir, int stream_id)

Fetch properties of a DAI driver.

Parameters:

dev – Pointer to the device structure for the driver instance
dir – Stream direction: RX or TX as defined by DAI_DIR_*
stream_id – Stream id: some drivers may have stream specific properties, this id specifies the stream.

Return values:

Pointer – to the structure containing properties, or NULL if error or no properties

static inline int dai_trigger(const struct device *dev, enum dai_dir dir, enum dai_trigger_cmd cmd)

Send a trigger command.

Parameters:

dev – Pointer to the device structure for the driver instance.
dir – Stream direction: RX, TX, or both, as defined by DAI_DIR_*. The DAI_DIR_BOTH value may not be supported by some drivers. For those, triggering need to be done separately for the RX and TX streams.
cmd – Trigger command.

Return values:

0 – If successful.
-EINVAL – Invalid argument.
-EIO – The trigger cannot be executed in the current state or a DMA channel cannot be allocated.
-ENOMEM – RX/TX memory block not available.
-ENOSYS – DAI_DIR_BOTH value is not supported.

static inline int dai_ts_config(const struct device *dev, struct dai_ts_cfg *cfg)

Configures timestamping in attached DAI.

Optional method.

Parameters:

dev – Component device.
cfg – Timestamp config.

Return values:

0 – If successful.

static inline int dai_ts_start(const struct device *dev, struct dai_ts_cfg *cfg)

Starts timestamping.

Optional method

Parameters:

dev – Component device.
cfg – Timestamp config.

Return values:

0 – If successful.

static inline int dai_ts_stop(const struct device *dev, struct dai_ts_cfg *cfg)

Stops timestamping.

Optional method.

Parameters:

dev – Component device.
cfg – Timestamp config.

Return values:

0 – If successful.

static inline int dai_ts_get(const struct device *dev, struct dai_ts_cfg *cfg, struct dai_ts_data *tsd)

Gets timestamp.

Optional method.

Parameters:

dev – Component device.
cfg – Timestamp config.
tsd – Receives timestamp data.

Return values:

0 – If successful.

struct dai_properties

#include <dai.h>

DAI properties.

This struct is used with APIs get_properties function to query DAI properties like fifo address and dma handshake. These are needed for example to setup dma outside the driver code.

Public Members

uint32_t fifo_address

Fifo hw address for e.g.

when connecting to dma.

uint32_t fifo_depth: Fifo depth.

uint32_t dma_hs_id: DMA handshake id.

uint32_t reg_init_delay: Delay for initializing registers.

int stream_id: Stream ID.

struct dai_config

#include <dai.h>

Main DAI config structure.

Generic DAI interface configuration options.

Public Members

enum dai_type type: Type of the DAI.

uint32_t dai_index: Index of the DAI.

uint8_t channels: Number of audio channels, words in frame.

uint32_t rate: Frame clock (WS) frequency, sampling rate.

uint16_t format: DAI specific data stream format.

uint8_t options: DAI specific configuration options.

uint8_t word_size: Number of bits representing one data word.

size_t block_size: Size of one RX/TX memory block (buffer) in bytes.

uint16_t link_config: DAI specific link configuration.

struct dai_ts_cfg

#include <dai.h>

DAI timestamp configuration.

Public Members

uint32_t walclk_rate

Rate in Hz, e.g.

19200000

int type: Type of the DAI (SSP, DMIC, HDA, etc.).

int direction: Direction (playback/capture)

int index: Index for SSPx to select correct timestamp register.

int dma_id: DMA instance id.

int dma_chan_index: Used DMA channel index.

int dma_chan_count: Number of channels in single DMA.

struct dai_ts_data

#include <dai.h>

DAI timestamp data.

Public Members

uint64_t walclk: Wall clock.

uint64_t sample: Sample count.

uint32_t walclk_rate

Rate in Hz, e.g.

19200000