mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 03:00:34 +03:00
Merge branch 'feat/i2s_tx_sync_esp31s31_v6.1' into 'release/v6.1'
feat(i2s): support TX FIFO sync (v6.1) See merge request espressif/esp-idf!50338
This commit is contained in:
morris
@@ -53,6 +53,9 @@ typedef struct {
|
||||
i2s_isr_callback_t on_send_q_ovf; /**< Callback of sending queue overflowed event, only for TX channel
|
||||
* The event data includes buffer size that has been overwritten
|
||||
*/
|
||||
#if SOC_I2S_SUPPORTS_TX_FIFO_SYNC
|
||||
i2s_tx_fifo_sync_callback_t on_tx_sync_evt; /**< Callback when the TX sync difference count exceeds the manual threshold */
|
||||
#endif
|
||||
} i2s_event_callbacks_t;
|
||||
|
||||
/**
|
||||
@@ -232,7 +235,10 @@ esp_err_t i2s_channel_read(i2s_chan_handle_t handle, void *dest, size_t size, si
|
||||
/**
|
||||
* @brief Set event callbacks for I2S channel
|
||||
*
|
||||
* @note Only allowed to be called when the channel state is REGISTERED / READY, (i.e., before channel starts)
|
||||
* @note DMA event callbacks can only be registered or deregistered before the channel is enabled.
|
||||
* @note The TX FIFO sync callback can be registered, updated, or deregistered while the channel is running.
|
||||
* @note Registering the TX FIFO sync callback only updates the handler; the TX sync interrupt is controlled by
|
||||
* i2s_channel_enable_tx_fifo_sync().
|
||||
* @note User can deregister a previously registered callback by calling this function and setting the callback member in the `callbacks` structure to NULL.
|
||||
* @note When CONFIG_I2S_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM.
|
||||
* The variables used in the function should be in the SRAM as well. The `user_data` should also reside in SRAM or internal RAM as well.
|
||||
@@ -243,8 +249,8 @@ esp_err_t i2s_channel_read(i2s_chan_handle_t handle, void *dest, size_t size, si
|
||||
* @return
|
||||
* - ESP_OK Set event callbacks successfully
|
||||
* - ESP_ERR_INVALID_ARG Set event callbacks failed because of invalid argument
|
||||
* - ESP_ERR_INVALID_STATE Set event callbacks failed because the current channel state is not REGISTERED or READY
|
||||
* - ESP_ERR_NOT_SUPPORTED Set event callbacks failed because the channel does not use the DMA data path
|
||||
* - ESP_ERR_INVALID_STATE Set event callbacks failed because DMA event callbacks are changed while the channel is running
|
||||
* - ESP_ERR_NOT_SUPPORTED Set event callbacks failed because the requested event is not supported by this channel
|
||||
*/
|
||||
esp_err_t i2s_channel_register_event_callback(i2s_chan_handle_t handle, const i2s_event_callbacks_t *callbacks, void *user_data);
|
||||
|
||||
@@ -290,6 +296,85 @@ 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 TX synchronization counter values
|
||||
*/
|
||||
typedef struct {
|
||||
uint32_t bclk_count; /*!< BCLK sync counter */
|
||||
uint32_t fifo_count; /*!< FIFO sync counter */
|
||||
#if SOC_I2S_SUPPORTS_TX_FIFO_SYNC
|
||||
int32_t diff_count; /*!< Signed difference: I2S_TX_FIFO_CNT - I2S_TX_FIFO_IDEAL_CNT */
|
||||
#endif
|
||||
} i2s_sync_count_t;
|
||||
|
||||
/**
|
||||
* @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`.
|
||||
* BCLK/FIFO counters are reset automatically when `I2S_ETM_TASK_SYNC_FIFO` is triggered.
|
||||
* @note When `SOC_I2S_SUPPORTS_TX_FIFO_SYNC` is supported, `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] count Pointer to receive TX synchronization counters
|
||||
* @param[in] reset Whether to reset the counters after reading
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Invalid handle, channel is not TX, or NULL count pointer
|
||||
*/
|
||||
esp_err_t i2s_channel_get_sync_count(i2s_chan_handle_t tx_handle, i2s_sync_count_t *count, bool reset);
|
||||
|
||||
#if SOC_I2S_SUPPORTS_TX_FIFO_SYNC
|
||||
/**
|
||||
* @brief TX FIFO synchronization configuration
|
||||
*/
|
||||
typedef struct {
|
||||
uint32_t auto_suppl_thresh; /*!< Threshold for automatic FIFO data 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 Configure TX FIFO synchronization
|
||||
*
|
||||
* @note `auto_suppl_thresh` must be smaller than `manual_suppl_thresh`.
|
||||
* @note Use i2s_channel_enable_tx_fifo_sync() to activate/deactivate after configuration.
|
||||
* @note Can be called while the channel is running, but only when TX FIFO synchronization is disabled.
|
||||
*
|
||||
* @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 TX FIFO synchronization is enabled
|
||||
*/
|
||||
esp_err_t i2s_channel_config_tx_fifo_sync(i2s_chan_handle_t tx_handle, const i2s_tx_fifo_sync_config_t *config);
|
||||
|
||||
/**
|
||||
* @brief Enable or disable TX FIFO synchronization
|
||||
*
|
||||
* @note When enabled, both automatic hardware data supplementation and manual interrupt
|
||||
* are activated simultaneously. When disabled, both are deactivated.
|
||||
* @note Must be called after i2s_channel_config_tx_fifo_sync().
|
||||
*
|
||||
* @param[in] tx_handle I2S TX channel handle
|
||||
* @param[in] enable true to enable, false to disable
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Invalid handle or channel is not TX
|
||||
* - ESP_ERR_INVALID_STATE FIFO sync not configured, or TX channel is not initialized
|
||||
*/
|
||||
esp_err_t i2s_channel_enable_tx_fifo_sync(i2s_chan_handle_t tx_handle, bool enable);
|
||||
|
||||
#endif // SOC_I2S_SUPPORTS_TX_FIFO_SYNC
|
||||
#endif // SOC_I2S_SUPPORTS_TX_SYNC_CNT
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
@@ -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_event_callback()`
|
||||
*
|
||||
* @return Whether a high priority task has been waken up by this callback function
|
||||
*/
|
||||
typedef bool (*i2s_tx_fifo_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()`
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user