DAI Interface

DAI Interface More...

Data Structures
struct	dai_properties
	DAI properties. More...
struct	dai_config
	Main DAI config structure. More...
struct	dai_ts_cfg
	DAI timestamp configuration. More...
struct	dai_ts_data
	DAI timestamp data. More...

Macros
#define	DAI_FORMAT_CLOCK_PROVIDER_MASK   0xf000
	Used to extract the clock configuration from the format attribute of struct dai_config.
#define	DAI_FORMAT_PROTOCOL_MASK   0x000f
	Used to extract the protocol from the format attribute of struct dai_config.
#define	DAI_FORMAT_CLOCK_INVERSION_MASK   0x0f00
	Used to extract the clock inversion from the format attribute of struct dai_config.

Enumerations
enum	dai_clock_provider { DAI_CBP_CFP = (0 << 12) , DAI_CBC_CFP = (2 << 12) , DAI_CBP_CFC = (3 << 12) , DAI_CBC_CFC = (4 << 12) }
	DAI clock configurations. More...
enum	dai_protocol {   DAI_PROTO_I2S = 1 , DAI_PROTO_RIGHT_J , DAI_PROTO_LEFT_J , DAI_PROTO_DSP_A ,   DAI_PROTO_DSP_B , DAI_PROTO_PDM }
	DAI protocol. More...
enum	dai_clock_inversion { DAI_INVERSION_NB_NF = 0 , DAI_INVERSION_NB_IF = (2 << 8) , DAI_INVERSION_IB_NF = (3 << 8) , DAI_INVERSION_IB_IF = (4 << 8) }
	DAI clock inversion. More...
enum	dai_type {   DAI_LEGACY_I2S = 0 , DAI_INTEL_SSP , DAI_INTEL_DMIC , DAI_INTEL_HDA ,   DAI_INTEL_ALH , DAI_IMX_SAI , DAI_IMX_ESAI , DAI_AMD_BT ,   DAI_AMD_SP , DAI_AMD_DMIC , DAI_MEDIATEK_AFE , DAI_INTEL_SSP_NHLT ,   DAI_INTEL_DMIC_NHLT , DAI_INTEL_HDA_NHLT , DAI_INTEL_ALH_NHLT }
	Types of DAI. More...
enum	dai_dir { DAI_DIR_TX = 0 , DAI_DIR_RX , DAI_DIR_BOTH }
	DAI Direction. More...
enum	dai_state {   DAI_STATE_NOT_READY = 0 , DAI_STATE_READY , DAI_STATE_RUNNING , DAI_STATE_PRE_RUNNING ,   DAI_STATE_PAUSED , DAI_STATE_STOPPING , DAI_STATE_ERROR }
	Interface state. More...
enum	dai_trigger_cmd {   DAI_TRIGGER_START = 0 , DAI_TRIGGER_PRE_START , DAI_TRIGGER_STOP , DAI_TRIGGER_PAUSE ,   DAI_TRIGGER_POST_STOP , DAI_TRIGGER_DRAIN , DAI_TRIGGER_DROP , DAI_TRIGGER_PREPARE ,   DAI_TRIGGER_RESET , DAI_TRIGGER_COPY }
	Trigger command. More...

Functions
static int	dai_probe (const struct device *dev)
	Probe operation of DAI driver.
static int	dai_remove (const struct device *dev)
	Remove operation of DAI driver.
static int	dai_config_set (const struct device *dev, const struct dai_config *cfg, const void *bespoke_cfg)
	Configure operation of a DAI driver.
static int	dai_config_get (const struct device *dev, struct dai_config *cfg, enum dai_dir dir)
	Fetch configuration information of a DAI driver.
static const struct dai_properties *	dai_get_properties (const struct device *dev, enum dai_dir dir, int stream_id)
	Fetch properties of a DAI driver.
static int	dai_trigger (const struct device *dev, enum dai_dir dir, enum dai_trigger_cmd cmd)
	Send a trigger command.
static int	dai_ts_config (const struct device *dev, struct dai_ts_cfg *cfg)
	Configures timestamping in attached DAI.
static int	dai_ts_start (const struct device *dev, struct dai_ts_cfg *cfg)
	Starts timestamping.
static int	dai_ts_stop (const struct device *dev, struct dai_ts_cfg *cfg)
	Stops timestamping.
static int	dai_ts_get (const struct device *dev, struct dai_ts_cfg *cfg, struct dai_ts_data *tsd)
	Gets timestamp.
static int	dai_config_update (const struct device *dev, const void *bespoke_cfg, size_t size)
	Update DAI configuration at runtime.

Detailed Description

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.

Macro Definition Documentation

DAI_FORMAT_CLOCK_INVERSION_MASK

#define DAI_FORMAT_CLOCK_INVERSION_MASK   0x0f00

#include <zephyr/drivers/dai.h>

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

DAI_FORMAT_CLOCK_PROVIDER_MASK

#define DAI_FORMAT_CLOCK_PROVIDER_MASK   0xf000

#include <zephyr/drivers/dai.h>

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

DAI_FORMAT_PROTOCOL_MASK

#define DAI_FORMAT_PROTOCOL_MASK   0x000f

#include <zephyr/drivers/dai.h>

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

Enumeration Type Documentation

dai_clock_inversion

enum dai_clock_inversion

#include <zephyr/drivers/dai.h>

DAI clock inversion.

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

Enumerator
DAI_INVERSION_NB_NF	no BCLK inversion, no FSYNC inversion no BCLK inversion, FSYNC inversion
DAI_INVERSION_NB_IF	BCLK inversion, no FSYNC inversion.
DAI_INVERSION_IB_NF	BCLK inversion, FSYNC inversion.
DAI_INVERSION_IB_IF

dai_clock_provider

enum dai_clock_provider

#include <zephyr/drivers/dai.h>

DAI clock configurations.

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

Enumerator
DAI_CBP_CFP	codec BLCK provider, codec FSYNC provider codec BCLK consumer, codec FSYNC provider
DAI_CBC_CFP	codec BCLK provider, codec FSYNC consumer
DAI_CBP_CFC	codec BCLK consumer, codec FSYNC consumer
DAI_CBC_CFC

dai_dir

enum dai_dir

#include <zephyr/drivers/dai.h>

DAI Direction.

Enumerator
DAI_DIR_TX	Transmit data.
DAI_DIR_RX	Receive data.
DAI_DIR_BOTH	Both receive and transmit data.

dai_protocol

enum dai_protocol

#include <zephyr/drivers/dai.h>

DAI protocol.

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

Enumerator
DAI_PROTO_I2S	I2S.
DAI_PROTO_RIGHT_J	Right Justified.
DAI_PROTO_LEFT_J	Left Justified.
DAI_PROTO_DSP_A	TDM, FSYNC asserted 1 BCLK early.
DAI_PROTO_DSP_B	TDM, FSYNC asserted at the same time as MSB.
DAI_PROTO_PDM	Pulse Density Modulation.

dai_state

enum dai_state

#include <zephyr/drivers/dai.h>

Interface state.

Enumerator
DAI_STATE_NOT_READY	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.
DAI_STATE_READY	The interface is ready to receive / transmit data.
DAI_STATE_RUNNING	The interface is receiving / transmitting data.
DAI_STATE_PRE_RUNNING	The interface is clocking but not receiving / transmitting data.
DAI_STATE_PAUSED	The interface paused.
DAI_STATE_STOPPING	The interface is draining its transmit queue.
DAI_STATE_ERROR	TX buffer underrun or RX buffer overrun has occurred.

dai_trigger_cmd

enum dai_trigger_cmd

#include <zephyr/drivers/dai.h>

Trigger command.

Enumerator
DAI_TRIGGER_START	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.
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.
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.
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.
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.
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.
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.
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.
DAI_TRIGGER_RESET	Reset. This trigger frees resources and moves the driver back to initial state.
DAI_TRIGGER_COPY	Copy. This trigger prepares for data copying.

dai_type

enum dai_type

#include <zephyr/drivers/dai.h>

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.

Enumerator
DAI_LEGACY_I2S	Legacy I2S compatible with i2s.h.
DAI_INTEL_SSP	Intel SSP.
DAI_INTEL_DMIC	Intel DMIC.
DAI_INTEL_HDA	Intel HD/A.
DAI_INTEL_ALH	Intel ALH.
DAI_IMX_SAI	i.MX SAI
DAI_IMX_ESAI	i.MX ESAI
DAI_AMD_BT	Amd BT.
DAI_AMD_SP	Amd SP.
DAI_AMD_DMIC	Amd DMIC.
DAI_MEDIATEK_AFE	Mtk AFE.
DAI_INTEL_SSP_NHLT	nhlt ssp
DAI_INTEL_DMIC_NHLT	nhlt ssp
DAI_INTEL_HDA_NHLT	nhlt Intel HD/A
DAI_INTEL_ALH_NHLT	nhlt Intel ALH

Function Documentation

dai_config_get()

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

inlinestatic

#include <zephyr/drivers/dai.h>

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

dai_config_set()

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

inlinestatic

#include <zephyr/drivers/dai.h>

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.

dai_config_update()

static int dai_config_update ( const struct device * dev, const void * bespoke_cfg, size_t size )

inlinestatic

#include <zephyr/drivers/dai.h>

Update DAI configuration at runtime.

This function updates the configuration of a DAI interface at runtime. It allows setting bespoke configuration parameters that are specific to the DAI implementation, enabling updates outside of the regular flow with the full configuration blob. The details of the bespoke configuration are specific to each DAI implementation. This function should only be called when the DAI is in the READY state, ensuring that the configuration updates are applied before data transmission or reception begins.

Parameters

dev	Pointer to the device structure for the driver instance.
bespoke_cfg	Pointer to the buffer containing bespoke configuration parameters.
size	Size of the bespoke_cfg buffer in bytes.

Return values

0	If successful.
-ENOSYS	If the configuration update operation is not implemented.
Negative	errno code if failure.

dai_get_properties()

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

inlinestatic

#include <zephyr/drivers/dai.h>

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

dai_probe()

static int dai_probe ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/dai.h>

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.

dai_remove()

static int dai_remove ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/dai.h>

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.

dai_trigger()

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

inlinestatic

#include <zephyr/drivers/dai.h>

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.

dai_ts_config()

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

inlinestatic

#include <zephyr/drivers/dai.h>

Configures timestamping in attached DAI.

Parameters

dev	Component device.
cfg	Timestamp config.

Optional method.

Return values

0	If successful.

dai_ts_get()

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

inlinestatic

#include <zephyr/drivers/dai.h>

Gets timestamp.

Parameters

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

Optional method.

Return values

0	If successful.

dai_ts_start()

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

inlinestatic

#include <zephyr/drivers/dai.h>

Starts timestamping.

Parameters

dev	Component device.
cfg	Timestamp config.

Optional method

Return values

0	If successful.

dai_ts_stop()

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

inlinestatic

#include <zephyr/drivers/dai.h>

Stops timestamping.

Parameters

dev	Component device.
cfg	Timestamp config.

Optional method.

Return values

0	If successful.