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.

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.

Enums

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_RX = 1: Receive data

enumerator DAI_DIR_TX: Transmit 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 const struct dai_config *dai_config_get(const struct device *dev, enum dai_dir dir)

Fetch configuration information 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_*

Return values

Pointer – to the structure containing configuration parameters, or NULL if 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>

Properties of DAI.

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.

Param fifo_address: Fifo hw address for e.g. when connecting to dma.
Param fifo_depth: Fifo depth.
Param dma_hs_id: Dma handshake id.
Param reg_init_delay: Delay for initializing registers.
Param stream_id: Stream ID.

struct dai_config

#include <dai.h>

Generic Dai interface configuration options.

Main dai config struct

Param dai_type: Type of the dai.
Param dai_index: Index of the dai.
Param channels: Number of audio channels, words in frame.
Param rate: Frame clock (WS) frequency, sampling rate.
Param format: Dai specific data stream format.
Param options: Dai specific configuration options.
Param word_size: Number of bits representing one data word.
Param block_size: Size of one RX/TX memory block (buffer) in bytes.

struct dai_ts_cfg: #include <dai.h>

struct dai_ts_data: #include <dai.h>