Zephyr API Documentation 4.0.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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_propertiesdai_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

#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

#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

#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

#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
devPointer to the device structure for the driver instance
cfgPointer to the config structure to be filled by the instance
dirStream direction: RX or TX as defined by DAI_DIR_*
Return values
0if 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
devPointer to the device structure for the driver instance.
cfgPointer to the structure containing configuration parameters.
bespoke_cfgPointer to the structure containing bespoke config.
Return values
0If successful.
-EINVALInvalid argument.
-ENOSYSDAI_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
devPointer to the device structure for the driver instance.
bespoke_cfgPointer to the buffer containing bespoke configuration parameters.
sizeSize of the bespoke_cfg buffer in bytes.
Return values
0If successful.
-ENOSYSIf the configuration update operation is not implemented.
Negativeerrno 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
devPointer to the device structure for the driver instance
dirStream direction: RX or TX as defined by DAI_DIR_*
stream_idStream id: some drivers may have stream specific properties, this id specifies the stream.
Return values
Pointerto 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
devPointer to the device structure for the driver instance.
Return values
0If 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
devPointer to the device structure for the driver instance.
Return values
0If 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
devPointer to the device structure for the driver instance.
dirStream 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.
cmdTrigger command.
Return values
0If successful.
-EINVALInvalid argument.
-EIOThe trigger cannot be executed in the current state or a DMA channel cannot be allocated.
-ENOMEMRX/TX memory block not available.
-ENOSYSDAI_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
devComponent device.
cfgTimestamp config.

Optional method.

Return values
0If 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
devComponent device.
cfgTimestamp config.
tsdReceives timestamp data.

Optional method.

Return values
0If 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
devComponent device.
cfgTimestamp config.

Optional method

Return values
0If 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
devComponent device.
cfgTimestamp config.

Optional method.

Return values
0If successful.