From 1c52462a4d8a97f82e3d13a5cc413e8f945fb569 Mon Sep 17 00:00:00 2001 From: laokaiyao Date: Fri, 2 Aug 2024 16:21:41 +0800 Subject: [PATCH] docs(i2s): update programming guide for I2S ETM feature --- components/esp_driver_i2s/i2s_private.h | 4 +- docs/en/api-reference/peripherals/etm.rst | 2 + docs/en/api-reference/peripherals/i2s.rst | 73 ++++++++++++++++++++ docs/zh_CN/api-reference/peripherals/etm.rst | 2 + docs/zh_CN/api-reference/peripherals/i2s.rst | 73 ++++++++++++++++++++ 5 files changed, 152 insertions(+), 2 deletions(-) diff --git a/components/esp_driver_i2s/i2s_private.h b/components/esp_driver_i2s/i2s_private.h index 5295300196..40ff52fce5 100644 --- a/components/esp_driver_i2s/i2s_private.h +++ b/components/esp_driver_i2s/i2s_private.h @@ -147,8 +147,8 @@ struct i2s_channel_obj_t { /* Stored configurations */ int intr_prio_flags;/*!< i2s interrupt priority flags */ void *mode_info; /*!< Slot, clock and gpio information of each mode */ - bool is_etm_start; /*!< Whether start/stop by etm tasks */ - bool is_etm_stop; /*!< Whether start/stop by etm tasks */ + bool is_etm_start; /*!< Whether start by etm tasks */ + bool is_etm_stop; /*!< Whether stop by etm tasks */ #if SOC_I2S_SUPPORTS_APLL bool apll_en; /*!< Flag of whether APLL enabled */ #endif diff --git a/docs/en/api-reference/peripherals/etm.rst b/docs/en/api-reference/peripherals/etm.rst index 467ed590ad..b5a6a963dd 100644 --- a/docs/en/api-reference/peripherals/etm.rst +++ b/docs/en/api-reference/peripherals/etm.rst @@ -72,6 +72,7 @@ Other Peripheral Events :SOC_MCPWM_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/mcpwm` for how to get the ETM event handle from MCPWM. :SOC_ANA_CMPR_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/ana_cmpr` for how to get the ETM event handle from analog comparator. :SOC_TEMPERATURE_SENSOR_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/temp_sensor` for how to get the ETM event handle from temperature sensor. + :SOC_I2S_SUPPORTS_ETM: - Refer to :doc:`/api-reference/peripherals/i2s` for how to get the ETM event handle from I2S. .. _etm-task: @@ -98,6 +99,7 @@ Other Peripheral Tasks :SOC_TIMER_SUPPORT_ETM: - Refer to :doc:`GPTimer ` for how to get the ETM task handle from GPTimer. :SOC_TEMPERATURE_SENSOR_SUPPORT_ETM: - Refer to :doc:`/api-reference/peripherals/temp_sensor` for how to get the ETM task handle from temperature sensor. + :SOC_I2S_SUPPORTS_ETM: - Refer to :doc:`/api-reference/peripherals/i2s` for how to get the ETM task handle from I2S. .. _etm-channel-control: diff --git a/docs/en/api-reference/peripherals/i2s.rst b/docs/en/api-reference/peripherals/i2s.rst index 2659546bb7..80f2842447 100644 --- a/docs/en/api-reference/peripherals/i2s.rst +++ b/docs/en/api-reference/peripherals/i2s.rst @@ -979,6 +979,79 @@ Here is an example of how to allocate a pair of full-duplex channels: i2s_channel_init_std_mode(rx_handle, &std_rx_cfg); i2s_channel_enable(rx_handle); +.. only:: SOC_I2S_SUPPORTS_ETM + + I2S ETM Usage + ^^^^^^^^^^^^^ + + {IDF_TARGET_NAME} supports I2S ETM (Event Task Matrix), which allows to trigger other ETM tasks via I2S ETM events, or to control the start/stop by I2S ETM tasks. + + The I2S ETM APIs can be found in ``driver/i2s_etm.h``, the following example shows how to use GPIO to start/stop I2S channel via ETM: + + .. code-block:: c + + #include "driver/i2s_etm.h" + // ... + i2s_chan_handle_t tx_handle; + // Initialize I2S channel + // ...... + int ctrl_gpio = 4; + // Initialize GPIO + // ...... + /* Register GPIO ETM events */ + gpio_etm_event_config_t gpio_event_cfg = { + .edges = {GPIO_ETM_EVENT_EDGE_POS, GPIO_ETM_EVENT_EDGE_NEG}, + }; + esp_etm_event_handle_t gpio_pos_event_handle; + esp_etm_event_handle_t gpio_neg_event_handle; + gpio_new_etm_event(&gpio_event_cfg, &gpio_pos_event_handle, &gpio_neg_event_handle); + gpio_etm_event_bind_gpio(gpio_pos_event_handle, ctrl_gpio); + gpio_etm_event_bind_gpio(gpio_neg_event_handle, ctrl_gpio); + /* Register I2S ETM tasks */ + i2s_etm_task_config_t i2s_start_task_cfg = { + .task_type = I2S_ETM_TASK_START, + }; + esp_etm_task_handle_t i2s_start_task_handle; + i2s_new_etm_task(tx_handle, &i2s_start_task_cfg, &i2s_start_task_handle); + i2s_etm_task_config_t i2s_stop_task_cfg = { + .task_type = I2S_ETM_TASK_STOP, + }; + esp_etm_task_handle_t i2s_stop_task_handle; + i2s_new_etm_task(tx_handle, &i2s_stop_task_cfg, &i2s_stop_task_handle); + /* Bind GPIO events to I2S ETM tasks */ + esp_etm_channel_config_t etm_config = {}; + esp_etm_channel_handle_t i2s_etm_start_chan = NULL; + esp_etm_channel_handle_t i2s_etm_stop_chan = NULL; + esp_etm_new_channel(&etm_config, &i2s_etm_start_chan); + esp_etm_new_channel(&etm_config, &i2s_etm_stop_chan); + esp_etm_channel_connect(i2s_etm_start_chan, gpio_pos_event_handle, i2s_start_task_handle); + esp_etm_channel_connect(i2s_etm_stop_chan, gpio_neg_event_handle, i2s_stop_task_handle); + esp_etm_channel_enable(i2s_etm_start_chan); + esp_etm_channel_enable(i2s_etm_stop_chan); + /* Enable I2S channel first before starting I2S channel */ + i2s_channel_enable(tx_handle); + // (Optional) Able to load the data into the internal DMA buffer here, + // but tx_channel does not start yet, will timeout when the internal buffer is full + // i2s_channel_write(tx_handle, data, data_size, NULL, 0); + /* Start I2S channel by setting the GPIO to high */ + gpio_set_level(ctrl_gpio, 1); + // Write data ...... + // i2s_channel_write(tx_handle, data, data_size, NULL, 1000); + /* Stop I2S channel by setting the GPIO to low */ + gpio_set_level(ctrl_gpio, 0); + + /* Free resources */ + i2s_channel_disable(tx_handle); + esp_etm_channel_disable(i2s_etm_start_chan); + esp_etm_channel_disable(i2s_etm_stop_chan); + esp_etm_del_event(gpio_pos_event_handle); + esp_etm_del_event(gpio_neg_event_handle); + esp_etm_del_task(i2s_start_task_handle); + esp_etm_del_task(i2s_stop_task_handle); + esp_etm_del_channel(i2s_etm_start_chan); + esp_etm_del_channel(i2s_etm_stop_chan); + // De-initialize I2S and GPIO + // ...... Application Notes ----------------- diff --git a/docs/zh_CN/api-reference/peripherals/etm.rst b/docs/zh_CN/api-reference/peripherals/etm.rst index c18c506e1e..9c1967dcad 100644 --- a/docs/zh_CN/api-reference/peripherals/etm.rst +++ b/docs/zh_CN/api-reference/peripherals/etm.rst @@ -72,6 +72,7 @@ GPIO **边沿** 事件是最常见的事件类型，任何 GPIO 管脚均可触 :SOC_MCPWM_SUPPORT_ETM: - 要了解如何从 MCPWM 中获取 ETM 事件句柄，请参阅 :doc:`/api-reference/peripherals/mcpwm`。 :SOC_ANA_CMPR_SUPPORT_ETM: - 要了解如何从模拟比较器获取 ETM 事件句柄，请参阅 :doc:`/api-reference/peripherals/ana_cmpr`。 :SOC_TEMPERATURE_SENSOR_SUPPORT_ETM: - 要了解如何从温度传感器获取 ETM 事件句柄，请参阅 :doc:`/api-reference/peripherals/temp_sensor`。 + :SOC_I2S_SUPPORTS_ETM: - 要了解如何从 I2S 获取 ETM 事件句柄，请参阅 :doc:`/api-reference/peripherals/i2s`。 .. _etm-task: @@ -98,6 +99,7 @@ GPIO 任务是最常见的任务类型。一个 GPIO 可以采取一个或多个 :SOC_TIMER_SUPPORT_ETM: - 要了解如何从 GPTimer 获取 ETM 任务句柄，请参阅 :doc:`/api-reference/peripherals/gptimer`。 :SOC_TEMPERATURE_SENSOR_SUPPORT_ETM: - 要了解如何从温度传感器获取 ETM 任务句柄，请参阅 :doc:`/api-reference/peripherals/temp_sensor`。 + :SOC_I2S_SUPPORTS_ETM: - 要了解如何从 I2S 获取 ETM 任务句柄，请参阅 :doc:`/api-reference/peripherals/i2s`。 .. _etm-channel-control: diff --git a/docs/zh_CN/api-reference/peripherals/i2s.rst b/docs/zh_CN/api-reference/peripherals/i2s.rst index 3b70174581..9b25759aa1 100644 --- a/docs/zh_CN/api-reference/peripherals/i2s.rst +++ b/docs/zh_CN/api-reference/peripherals/i2s.rst @@ -979,6 +979,79 @@ STD RX 模式 i2s_channel_init_std_mode(rx_handle, &std_rx_cfg); i2s_channel_enable(rx_handle); +.. only:: SOC_I2S_SUPPORTS_ETM + + I2S ETM 用法 + ^^^^^^^^^^^^^^^^^^^^^^^^^ + + {IDF_TARGET_NAME} 支持 I2S ETM （Event Task Matrix，事件任务矩阵）。 它可以通过 I2S 事件触发一个其他的 ETM 任务，或者通过其他的 ETM 事件来控制 I2S 的启停任务。 + + 头文件 ``driver/i2s_etm.h`` 中可以找到 I2S ETM 所需的接口函数，下面示例代码将展示如何通过 GPIO 的 ETM 事件控制 I2S 的启停。 + + .. code-block:: c + + #include "driver/i2s_etm.h" + // ... + i2s_chan_handle_t tx_handle; + // 初始化 I2S 通道 + // ...... + int ctrl_gpio = 4; + // 初始化 GPIO 用于控制 + // ...... + /* 注册 GPIO ETM 事件 */ + gpio_etm_event_config_t gpio_event_cfg = { + .edges = {GPIO_ETM_EVENT_EDGE_POS, GPIO_ETM_EVENT_EDGE_NEG}, + }; + esp_etm_event_handle_t gpio_pos_event_handle; + esp_etm_event_handle_t gpio_neg_event_handle; + gpio_new_etm_event(&gpio_event_cfg, &gpio_pos_event_handle, &gpio_neg_event_handle); + gpio_etm_event_bind_gpio(gpio_pos_event_handle, ctrl_gpio); + gpio_etm_event_bind_gpio(gpio_neg_event_handle, ctrl_gpio); + /* 注册 I2S ETM 任务 */ + i2s_etm_task_config_t i2s_start_task_cfg = { + .task_type = I2S_ETM_TASK_START, + }; + esp_etm_task_handle_t i2s_start_task_handle; + i2s_new_etm_task(tx_handle, &i2s_start_task_cfg, &i2s_start_task_handle); + i2s_etm_task_config_t i2s_stop_task_cfg = { + .task_type = I2S_ETM_TASK_STOP, + }; + esp_etm_task_handle_t i2s_stop_task_handle; + i2s_new_etm_task(tx_handle, &i2s_stop_task_cfg, &i2s_stop_task_handle); + /* 绑定 GPIO 事件和 I2S ETM 任务 */ + esp_etm_channel_config_t etm_config = {}; + esp_etm_channel_handle_t i2s_etm_start_chan = NULL; + esp_etm_channel_handle_t i2s_etm_stop_chan = NULL; + esp_etm_new_channel(&etm_config, &i2s_etm_start_chan); + esp_etm_new_channel(&etm_config, &i2s_etm_stop_chan); + esp_etm_channel_connect(i2s_etm_start_chan, gpio_pos_event_handle, i2s_start_task_handle); + esp_etm_channel_connect(i2s_etm_stop_chan, gpio_neg_event_handle, i2s_stop_task_handle); + esp_etm_channel_enable(i2s_etm_start_chan); + esp_etm_channel_enable(i2s_etm_stop_chan); + /* 通过 ETM 启动 I2S 前需要先使能这个通道 */ + i2s_channel_enable(tx_handle); + // （可选）这里可以把要发送的数据先加载到内部的发送缓冲区中 + // 但是由于 tx_channel 还没有启动，所以当内部缓冲区加载满后，再写入会超时 + // i2s_channel_write(tx_handle, data, data_size, NULL, 0); + /* 通过拉高 GPIO 启动 I2S tx 通道 */ + gpio_set_level(ctrl_gpio, 1); + // 写数据 ...... + // i2s_channel_write(tx_handle, data, data_size, NULL, 1000); + /* 通过拉低 GPIO 停止 I2S tx 通道 */ + gpio_set_level(ctrl_gpio, 0); + + /* 释放 ETM 相关资源 */ + i2s_channel_disable(tx_handle); + esp_etm_channel_disable(i2s_etm_start_chan); + esp_etm_channel_disable(i2s_etm_stop_chan); + esp_etm_del_event(gpio_pos_event_handle); + esp_etm_del_event(gpio_neg_event_handle); + esp_etm_del_task(i2s_start_task_handle); + esp_etm_del_task(i2s_stop_task_handle); + esp_etm_del_channel(i2s_etm_start_chan); + esp_etm_del_channel(i2s_etm_stop_chan); + // 去初始化 I2S 和 GPIO + // ...... 应用注意事项 ------------