Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 03:00:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(i2s): release i2s tx sync APIs

Browse Source
This commit is contained in:
Chen Chen
2026-07-13 14:43:55 +08:00
parent f44f4a82e6
commit c27bd91874
14 changed files with 746 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/esp_driver_i2s/include/driver/i2s_common.h
+99
View File
@@ -290,6 +290,105 @@ esp_err_t i2s_channel_preload_data(i2s_chan_handle_t tx_handle, const void *src,
*/
esp_err_t i2s_channel_tune_rate(i2s_chan_handle_t handle, const i2s_tuning_config_t *tune_cfg, i2s_tuning_info_t *tune_info);
#if SOC_I2S_SUPPORTS_TX_SYNC_CNT
/**
* @brief Get TX synchronization counters
*
* @note `fifo_count` reflects how many data have been read from TX FIFO.
* Normally, `bclk_count = fifo_count * slot_bit_width`.
* Both counters are reset automatically when `I2S_ETM_TASK_SYNC_FIFO` is triggered.
*
* @param[in] tx_handle I2S TX channel handle
* @param[out] bclk_count Pointer to receive BCLK sync counter, set NULL to ignore
* @param[out] fifo_count Pointer to receive FIFO sync counter, set NULL to ignore
* @param[in] reset Whether to reset both counters after reading
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Invalid handle or channel is not TX
*/
esp_err_t i2s_channel_get_sync_count(i2s_chan_handle_t tx_handle, uint32_t *bclk_count, uint32_t *fifo_count,
bool reset);
#if SOC_I2S_SUPPORTS_TX_FIFO_SYNC
/**
* @brief Get TX FIFO synchronization difference counter
*
* @note `diff_count` is a signed 31-bit value equal to `I2S_TX_FIFO_CNT - I2S_TX_FIFO_IDEAL_CNT`.
*
* @param[in] tx_handle I2S TX channel handle
* @param[out] diff_count Pointer to receive signed difference counter, set NULL to ignore
* @param[in] reset Whether to reset the difference counter after reading
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Invalid handle or channel is not TX
*/
esp_err_t i2s_channel_get_sync_diff_count(i2s_chan_handle_t tx_handle, int32_t *diff_count, bool reset);
/**
* @brief TX FIFO synchronization configuration
*/
typedef struct {
uint32_t auto_suppl_thresh; /*!< Threshold to enable automatic FIFO data supplement;
* 0 disables automatic supplement
*/
uint32_t manual_suppl_thresh; /*!< Threshold to trigger the callback for manual FIFO data supplement */
uint32_t ideal_cnt; /*!< Ideal FIFO count when ETM sync task is triggered */
i2s_tx_fifo_sync_suppl_mode_t suppl_mode; /*!< Data supplement mode for automatic supplement */
uint32_t suppl_data; /*!< Static supplement data, valid when suppl_mode is
* I2S_TX_FIFO_SYNC_SUPPL_MODE_STATIC_DATA
*/
} i2s_tx_fifo_sync_config_t;
/**
* @brief Group of I2S peripheral interrupt event callbacks
*
* @note The callbacks are all running under ISR environment.
*/
typedef struct {
i2s_sync_callback_t on_tx_sync; /*!< Callback when the sync difference count exceeds
* `manual_suppl_thresh`
*/
} i2s_intr_event_callbacks_t;
/**
* @brief Configure TX FIFO synchronization
*
* @note Set `auto_suppl_thresh` to 0 to disable automatic hardware supplementation.
* @note When automatic hardware supplementation is enabled, `auto_suppl_thresh` must be smaller than
* `manual_suppl_thresh`.
* @note Only allowed when channel state is REGISTERED or READY (before channel starts).
*
* @param[in] tx_handle I2S TX channel handle
* @param[in] config TX FIFO synchronization configuration
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Invalid handle, channel is not TX, or invalid configuration
* - ESP_ERR_INVALID_STATE Channel is already running
*/
esp_err_t i2s_channel_config_tx_fifo_sync(i2s_chan_handle_t tx_handle, const i2s_tx_fifo_sync_config_t *config);
/**
* @brief Register I2S peripheral interrupt event callbacks
*
* @note `on_tx_sync` is invoked when `tx_cnt_diff` exceeds `manual_suppl_thresh`.
* @note Only allowed when channel state is REGISTERED or READY (before channel starts).
* @note When CONFIG_I2S_ISR_IRAM_SAFE is enabled, the callback and user_data must reside in internal RAM.
* @note Set `callbacks->on_tx_sync` to NULL to deregister the callback and uninstall the TX sync interrupt.
*
* @param[in] tx_handle I2S TX channel handle
* @param[in] callbacks Group of I2S peripheral interrupt callbacks
* @param[in] user_data User context passed to callback
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Invalid handle or channel is not TX
* - ESP_ERR_INVALID_STATE Channel is already running
* - ESP_ERR_NO_MEM Failed to allocate interrupt
*/
esp_err_t i2s_channel_register_intr_event_callback(i2s_chan_handle_t tx_handle,
const i2s_intr_event_callbacks_t *callbacks, void *user_data);
#endif // SOC_I2S_SUPPORTS_TX_FIFO_SYNC
#endif // SOC_I2S_SUPPORTS_TX_SYNC_CNT
#ifdef __cplusplus
}
#endif
components/esp_driver_i2s/include/driver/i2s_types.h
+23 -3
View File
@@ -106,6 +106,29 @@ typedef struct {
uint32_t water_mark; /*!< The water mark of the internal buffer, in percent */
} i2s_tuning_info_t;
typedef struct i2s_channel_obj_t *i2s_chan_handle_t; /*!< I2S channel object handle, the control unit of the I2S driver*/
typedef struct lp_i2s_channel_obj_t *lp_i2s_chan_handle_t; /*!< I2S channel object handle, the control unit of the I2S driver*/
#if SOC_I2S_SUPPORTS_TX_FIFO_SYNC
/**
* @brief TX synchronization event data passed to sync callback
*/
typedef struct {
int32_t diff_count; /*!< Signed difference: I2S_TX_FIFO_CNT - I2S_TX_FIFO_IDEAL_CNT */
} i2s_sync_event_data_t;
/**
* @brief TX synchronization event callback
*
* @param[in] handle I2S TX channel handle
* @param[in] event TX synchronization event data
* @param[in] user_ctx User context registered via `i2s_channel_register_intr_event_callback()`
*
* @return Whether a high priority task has been waken up by this callback function
*/
typedef bool (*i2s_sync_callback_t)(i2s_chan_handle_t handle, const i2s_sync_event_data_t *event, void *user_ctx);
#endif // SOC_I2S_SUPPORTS_TX_FIFO_SYNC
/**
* @brief Event data structure for LP I2S
*/
@@ -113,9 +136,6 @@ typedef struct {
lp_i2s_trans_t trans; ///< LP I2S transaction
} lp_i2s_evt_data_t;
typedef struct i2s_channel_obj_t *i2s_chan_handle_t; /*!< I2S channel object handle, the control unit of the I2S driver*/
typedef struct lp_i2s_channel_obj_t *lp_i2s_chan_handle_t; /*!< I2S channel object handle, the control unit of the I2S driver*/
/**
* @brief I2S event callback
* @param[in] handle I2S channel handle, created from `i2s_new_channel()`
components/esp_driver_i2s/include/esp_private/i2s_sync.h
-146
View File
@@ -1,146 +0,0 @@
/*
* SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
// DO NOT USE THESE APIS IN YOUR APPLICATIONS
// The following APIs are for internal use, public to other IDF components, but not for users' applications.
/**
* This file is used for getting the bclk and fifo sending count
* for the synchronization among different I2S ports.
*
* The APIs in this file might be called frequently, so they are made light-weight and flexible to be called
*
* NOTE: These APIs are private for ESP internal usages.
* Please be aware of the risk that APIs might be changed regarding the use case.
*/
#pragma once
#include <stdint.h>
#include "driver/i2s_types.h"
#include "esp_err.h"
#ifdef __cplusplus
extern "C" {
#endif
#if SOC_I2S_SUPPORTS_TX_SYNC_CNT
/**
* @brief Get the counter number of BCLK ticks
* @note The BCLK tick count reflects the real data that have sent on line
* @note It will be reset automatically when `I2S_ETM_TASK_SYNC_FIFO` is triggered
*
* @param[in] tx_handle The I2S tx channel handle
* @return
* - BCLK tick count
*/
uint32_t i2s_sync_get_bclk_count(i2s_chan_handle_t tx_handle);
/**
* @brief Get the counter number of fifo
* @note The FIFO count reflects how many slots have processed
* Normally, fifo_cnt = slot_bit_width * bclk_cnt
* If fifo_cnt < slot_bit_width * bclk_cnt, that means some data are still stuck in the I2S controller
* @note It will be reset automatically when `I2S_ETM_TASK_SYNC_FIFO` is triggered
*
* @param[in] tx_handle The I2S tx channel handle
* @return
* - FIFO slot count
*/
uint32_t i2s_sync_get_fifo_count(i2s_chan_handle_t tx_handle);
/**
* @brief Reset the bclk counter
*
* @param[in] tx_handle The I2S tx channel handle
*/
void i2s_sync_reset_bclk_count(i2s_chan_handle_t tx_handle);
/**
* @brief Reset the fifo counter
*
* @param[in] tx_handle The I2S tx channel handle
*/
void i2s_sync_reset_fifo_count(i2s_chan_handle_t tx_handle);
#endif // SOC_I2S_SUPPORTS_TX_SYNC_CNT
#if SOC_I2S_SUPPORTS_TX_FIFO_SYNC
/**
* @brief I2S hardware FIFO synchronization supplement mode
* @note When the FIFO sync difference count is out of threshold, the hardware will supplement data automatically
* This type is to specify which data will be supplemented
*/
typedef enum {
I2S_SYNC_SUPPL_MODE_LAST_DATA = 0, /*!< Supplement with the last transmitted data */
I2S_SYNC_SUPPL_MODE_STATIC_DATA = 1, /*!< Supplement with static data specified in config */
} i2s_sync_suppl_mode_t;
/**
* @brief I2S hardware FIFO synchronization configuration
* @note This configuration is used for multi I2S port synchronization via ETM
*/
typedef struct {
uint32_t hw_low_thresh; /*!< Lower threshold for FIFO sync difference counter
- If difference count < hw_low_thresh, do nothing
- If difference count >= hw_low_thresh, the hardware will supplement data automatically */
uint32_t sw_high_thresh; /*!< Upper threshold for FIFO sync difference counter
- If difference count <= sw_high_thresh, the hardware supplement data automatically
- If difference count > sw_high_thresh, sync interrupt triggered and
the software is responsible to decide how to handle this severe asynchronization */
uint32_t ideal_cnt; /*!< Ideal count for FIFO sync difference counter, it depends on the ETM sync task interval and the data rate */
i2s_sync_suppl_mode_t suppl_mode; /*!< Data supplement mode when FIFO sync difference is out of threshold */
uint32_t suppl_data; /*!< Static supplement data, only valid when suppl_mode is I2S_SYNC_SUPPL_MODE_STATIC_DATA */
} i2s_sync_fifo_sync_config_t;
/**
* @brief Get the counter number of FIFO sync difference
* @note The FIFO sync difference count reflects the difference between current FIFO count and ideal count
*
* @param[in] tx_handle The I2S tx channel handle
* @return
* - FIFO sync difference count
*/
uint32_t i2s_sync_get_fifo_sync_diff_count(i2s_chan_handle_t tx_handle);
/**
* @brief Reset the FIFO sync difference counter
*
* @param[in] tx_handle The I2S tx channel handle
*/
void i2s_sync_reset_fifo_sync_diff_count(i2s_chan_handle_t tx_handle);
/**
* @brief Enable or disable hardware FIFO synchronization
* @note When enabled, hardware will automatically supplement data when FIFO sync difference is greater than hw_low_thresh
*
* @param[in] tx_handle The I2S tx channel handle
* @param[in] enable true to enable, false to disable
* @return
* - ESP_OK on success
* - ESP_ERR_NOT_SUPPORTED if called on RX channel
*/
esp_err_t i2s_sync_enable_hw_fifo_sync(i2s_chan_handle_t tx_handle, bool enable);
/**
* @brief Configure hardware FIFO synchronization parameters
* @note This function configures the thresholds and supplement mode for hardware FIFO sync
*
* @param[in] tx_handle The I2S tx channel handle
* @param[in] config Configuration for hardware FIFO synchronization
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if invalid arguments
* - ESP_ERR_NOT_SUPPORTED if called on RX channel
*/
esp_err_t i2s_sync_config_hw_fifo_sync(i2s_chan_handle_t tx_handle, const i2s_sync_fifo_sync_config_t *config);
#endif
#ifdef __cplusplus
}
#endif