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:

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.

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