change(i2s): allow config tx sync params while tx channel is running

docs/en/api-reference/peripherals/i2s.rst

@@ -331,27 +331,30 @@ To satisfy the high quality audio requirement, following advanced APIs are provi
     - :cpp:func:`i2s_channel_get_sync_count`: Read the TX synchronization counters through :cpp:type:`i2s_sync_count_t`.
       When TX FIFO synchronization is supported, ``diff_count`` is also returned as ``I2S_TX_FIFO_CNT - I2S_TX_FIFO_IDEAL_CNT``.
     - :cpp:func:`i2s_channel_config_tx_fifo_sync`: Configure the expected count, automatic supplement threshold,
-      manual supplement threshold, and hardware supplement mode.
+      manual supplement threshold, and hardware supplement mode. It can be called while the TX channel is running,
+      but TX FIFO synchronization must be disabled.
     - :cpp:func:`i2s_channel_enable_tx_fifo_sync`: Enable or disable TX FIFO synchronization. When enabled,
       both automatic hardware data supplementation and manual interrupt are activated simultaneously.
-      When disabled, both are deactivated. This API must be called after
-      :cpp:func:`i2s_channel_config_tx_fifo_sync`.
+      When disabled, both are deactivated. Enabling TX FIFO synchronization resets the TX FIFO/BCLK synchronization
+      counters. This API must be called after :cpp:func:`i2s_channel_config_tx_fifo_sync`.
     - :cpp:func:`i2s_channel_register_event_callback`: Register the manual supplement threshold interrupt callback. When
       ``diff_count`` exceeds the manual supplement threshold, the driver calls this callback in the ISR and provides
-      ``diff_count`` through :cpp:type:`i2s_sync_event_data_t`.
+      ``diff_count`` through :cpp:type:`i2s_sync_event_data_t`. Registering the callback only updates the handler;
+      the TX sync interrupt's enable/disable is controlled by :cpp:func:`i2s_channel_enable_tx_fifo_sync`.
 
     The typical usage steps are:
 
     1. Create and initialize an I2S TX channel.
     2. Call :cpp:func:`i2s_channel_config_tx_fifo_sync` to configure :cpp:type:`i2s_tx_fifo_sync_config_t`. ``ideal_cnt``
-       is the expected number of transmitted data units at each ETM synchronization check. ``auto_suppl_thresh`` is
+       is the expected number of transmitted data units at each ETM synchronization check. This step can be performed while the TX channel is running, but TX FIFO synchronization must be disabled before reconfiguration. ``auto_suppl_thresh`` is
        the automatic hardware supplement threshold and must be smaller than ``manual_suppl_thresh``.
        ``manual_suppl_thresh`` is the threshold for triggering the callback for manual handling. If the difference
        exceeds the automatic supplement threshold but has not reached the manual supplement threshold, hardware
        automatically supplements or deletes the corresponding amount of data to synchronize with ``ideal_cnt``.
     3. To handle severe out-of-sync conditions, call :cpp:func:`i2s_channel_register_event_callback` to register a callback.
     4. Call :cpp:func:`i2s_channel_enable_tx_fifo_sync` with ``enable`` set to ``true`` to activate both automatic
-       hardware supplementation and manual interrupt simultaneously.
+       hardware supplementation and manual interrupt simultaneously. This call resets the TX FIFO/BCLK synchronization
+       counters, so the first ETM synchronization check uses a new count window.
     5. Call :cpp:func:`i2s_new_etm_task` to create the ``I2S_ETM_TASK_SYNC_FIFO`` task, and connect an external ETM event to this task.
     6. Enable the ETM channel and I2S TX channel, so that ETM events periodically trigger synchronization checks.
 
@@ -409,6 +412,9 @@ To satisfy the high quality audio requirement, following advanced APIs are provi
     .. note::
 
         After ``I2S_ETM_TASK_SYNC_FIFO`` is triggered, hardware automatically clears the TX FIFO/BCLK synchronization counters.
+        To avoid a synchronization check using partially updated configuration, call :cpp:func:`i2s_channel_enable_tx_fifo_sync`
+        with ``enable`` set to ``false`` before reconfiguring TX FIFO synchronization. If an ETM event source may still
+        trigger during reconfiguration, disable the ETM channel or pause the event source as needed.
 
 .. _i2s-iram-safe:
 

docs/zh_CN/api-reference/peripherals/i2s.rst

@@ -331,27 +331,29 @@ I2S 的数据传输（包括数据发送和接收）由 DMA 实现。在传输
     - :cpp:func:`i2s_channel_get_sync_count`：通过 :cpp:type:`i2s_sync_count_t` 读取 TX 同步计数器。
       当支持 TX FIFO 同步时，也会返回 ``diff_count``，其含义为 ``I2S_TX_FIFO_CNT - I2S_TX_FIFO_IDEAL_CNT``。
     - :cpp:func:`i2s_channel_config_tx_fifo_sync`：配置期望计数、自动补偿阈值、
-      手动补偿阈值以及硬件补偿方式。
+      手动补偿阈值以及硬件补偿方式。该 API 可在 TX 通道运行时调用，
+      但此时 TX FIFO 同步功能必须处于关闭状态。
     - :cpp:func:`i2s_channel_enable_tx_fifo_sync`：使能或关闭 TX FIFO 同步功能。使能后，
       硬件自动补偿和手动补偿中断同时激活。
-      关闭后，两者同时停用。该 API 必须在
-      :cpp:func:`i2s_channel_config_tx_fifo_sync` 之后调用。
+      关闭后，两者同时停用。使能 TX FIFO 同步时会重置 TX FIFO/BCLK 同步计数器。
+      该 API 必须在 :cpp:func:`i2s_channel_config_tx_fifo_sync` 之后调用。
     - :cpp:func:`i2s_channel_register_event_callback`：注册手动补偿阈值中断回调。当
       ``diff_count`` 超过手动补偿阈值时，驱动会在 ISR 中调用该回调，并通过
-      :cpp:type:`i2s_sync_event_data_t` 提供 ``diff_count``。
+      :cpp:type:`i2s_sync_event_data_t` 提供 ``diff_count``。注册回调只更新 handler；
+      TX sync 中断的开关由 :cpp:func:`i2s_channel_enable_tx_fifo_sync` 控制。
 
     使用该功能的一般步骤如下：
 
     1. 创建并初始化 I2S TX 通道。
     2. 调用 :cpp:func:`i2s_channel_config_tx_fifo_sync` 配置 :cpp:type:`i2s_tx_fifo_sync_config_t`。``ideal_cnt``
-       为每次 ETM 同步检查时期望发送的数据个数；``auto_suppl_thresh`` 为
-       硬件自动补偿阈值，必须小于 ``manual_suppl_thresh``。
+       为每次 ETM 同步检查时期望发送的数据个数。该步骤可在 TX 通道运行时执行，但重新配置前必须先关闭 TX FIFO 同步功能。``auto_suppl_thresh`` 为硬件自动补偿阈值，
+       必须小于 ``manual_suppl_thresh``。
        ``manual_suppl_thresh`` 为触发回调并交由软件手动处理的阈值。如果偏差
        超过自动补偿阈值但尚未达到手动补偿阈值，硬件会自动补充或删除相应数量的数据，
        以实现与 ``ideal_cnt`` 同步。
     3. 如需处理严重不同步场景，调用 :cpp:func:`i2s_channel_register_event_callback` 注册回调。
     4. 调用 :cpp:func:`i2s_channel_enable_tx_fifo_sync` 并将 ``enable`` 设为 ``true``，同时激活硬件自动补偿
-       和手动补偿中断。
+       和手动补偿中断。该调用会重置 TX FIFO/BCLK 同步计数器，因此第一次 ETM 同步检查会使用新的计数窗口。
     5. 调用 :cpp:func:`i2s_new_etm_task` 创建 ``I2S_ETM_TASK_SYNC_FIFO`` 任务，并将外部 ETM 事件连接到该任务。
     6. 使能 ETM 通道和 I2S TX 通道，由 ETM 事件周期性触发同步检查。
 
@@ -409,6 +411,9 @@ I2S 的数据传输（包括数据发送和接收）由 DMA 实现。在传输
     .. note::
 
         ``I2S_ETM_TASK_SYNC_FIFO`` 触发后，硬件会自动清零 TX FIFO/BCLK 同步计数器。
+        为避免同步检查使用到正在更新中的配置，重新配置 TX FIFO 同步前应调用
+        :cpp:func:`i2s_channel_enable_tx_fifo_sync` 并将 ``enable`` 设为 ``false``。
+        如果重新配置期间 ETM 事件源仍可能触发，可根据需要关闭 ETM 通道或暂停事件源。
 
 .. _i2s-iram-safe: