事件任务矩阵 (ETM) ======================= :link_to_translation:`en:[English]` 简介 ------------ 如果外设 X 需要向外设 Y 发起事件通知，一般只能通过 CPU 中断实现。在此过程中，CPU 会代表外设 X，给外设 Y 发送通知。然而，在对时间敏感的应用程序中，CPU 中断引发的延迟不容忽视。 通过引入事件任务矩阵 (ETM) 模块，部分外设可以直接通过预先设置的连接关系，将事件通知发送给其他外设，无需 CPU 中断介入。由此，外设实现精确、低延迟同步，并减轻 CPU 负担。 .. blockdiag:: /../_static/diagrams/etm/etm_channel.diag :caption: ETM 通道概述 :align: center ETM 模块具有多个通道，这些通道支持用户根据需要进行配置，连接特定 **事件** 与 **任务**。激活某一事件时，ETM 将自动触发相应任务。 支持 ETM 功能的外设向 ETM 提供其事件和任务的连接关系。ETM 通道可以连接任意事件和任务，事件和任务甚至可以来自于同一个外设。然而，对于一个 ETM 通道，一次只能将一个事件与一个任务连接（即 1 对 1 关系）。如果要使用不同事件触发同一任务，则需申请多条 ETM 通道。 使用 ETM 通常可实现以下功能： - 当定时器报警事件发生时，翻转 GPIO 电平 - 当在 GPIO 上监测到脉冲边沿时，启动 ADC 转换 功能概述 ------------------- 下文将分节概述 ETM 的功能，并介绍配置和使用 ETM 模块的基本步骤： - :ref:`etm-channel-allocation` - 介绍如何安装和卸载 ETM 通道。 - :ref:`etm-event` - 介绍如何分配新的 ETM 事件句柄，以及如何从不同外设获取现有句柄。 - :ref:`etm-task` - 介绍如何分配新的 ETM 任务句柄，以及如何从不同外设获取现有句柄。 - :ref:`etm-channel-control` - 介绍常见的 ETM 通道控制函数。 - :ref:`etm-thread-safety` - 列出了驱动程序中始终线程安全的 API。 - :ref:`etm-kconfig-options` - 列出了 ETM 支持的 Kconfig 选项，这些选项对驱动程序的行为会产生不同影响。 .. _etm-channel-allocation: ETM 通道分配 ^^^^^^^^^^^^^^^^^^^^^^ 在 {IDF_TARGET_NAME} 中，存在许多相同的 ETM 通道 [1]_，各通道在软件中由 :cpp:type:`esp_etm_channel_handle_t` 表示。可用硬件资源汇集在资源池内，由 ETM 核心驱动程序管理，无需手动管理通道的分配和释放。ETM 核心驱动程序会在调用 :cpp:func:`esp_etm_new_channel` 时自动分配通道，在调用 :cpp:func:`esp_etm_del_channel` 时删除通道。分配通道的要求通过 :cpp:type:`esp_etm_channel_config_t` 配置。 在删除 ETM 通道前，请调用 :cpp:func:`esp_etm_channel_disable` 禁用要删除的通道，或确保该通道尚未由 :cpp:func:`esp_etm_channel_enable` 启用，再继续删除操作。 .. _etm-event: ETM 事件 ^^^^^^^^^ ETM 事件对其事件源进行了抽象，屏蔽了具体事件源的细节，并在软件中表示为 :cpp:type:`esp_etm_event_handle_t`，使应用程序可以更便捷地处理不同类型的事件。ETM 事件可以由各种外设产生，因此获取事件句柄的方法因外设而异。当不再需要某个事件时，请调用 :cpp:func:`esp_etm_channel_connect`，并传递一个 ``NULL`` 事件句柄，断开与事件的连接，随后调用 :cpp:func:`esp_etm_del_event`，释放事件资源。 GPIO 事件 ~~~~~~~~~~~ GPIO **边沿** 事件是最常见的事件类型，任何 GPIO 管脚均可触发这类事件。要创建 GPIO 事件句柄，请调用 :cpp:func:`gpio_new_etm_event`，并使用 :cpp:type:`gpio_etm_event_config_t` 提供的配置信息： - :cpp:member:`gpio_etm_event_config_t::edge` 或 :cpp:member:`gpio_etm_event_config_t::edges` 决定触发事件的边沿类型，支持的边沿类型已在 :cpp:type:`gpio_etm_event_edge_t` 中列出。 接下来，请调用 :cpp:func:`gpio_etm_event_bind_gpio` 函数，连接 GPIO ETM 事件句柄与 GPIO 管脚。注意，要设置 GPIO 管脚，只能使用由 :cpp:func:`gpio_new_etm_event` 函数创建的 ETM 事件句柄。对于其他类型的 ETM 事件，调用此函数，将返回 :c:macro:`ESP_ERR_INVALID_ARG` 错误。该函数也无法完成 GPIO 的初始化，在使用 GPIO ETM 事件之前，仍需调用 :cpp:func:`gpio_config` 函数，设置 GPIO 管脚的属性，如方向、高/低电平模式等。 其他外设事件 ~~~~~~~~~~~~~~~~~~~~~~~ .. list:: :SOC_SYSTIMER_SUPPORT_ETM: - 调用 :cpp:func:`esp_systick_new_etm_alarm_event` 可以从 RTOS Systick 获取 ETM 事件句柄，每个 CPU 核心可以获取一个事件句柄。 :SOC_SYSTIMER_SUPPORT_ETM: - 要了解如何从 esp_timer 获取 ETM 事件句柄，请参阅 :doc:`/api-reference/system/esp_timer`。 :SOC_TIMER_SUPPORT_ETM: - 要了解如何从 GPTimer 获取 ETM 事件句柄，请参阅 :doc:`/api-reference/peripherals/gptimer`。 :SOC_GDMA_SUPPORT_ETM: - 要了解如何从 async memcpy 获取 ETM 事件句柄，请参阅 :doc:`/api-reference/system/async_memcpy`。 :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: ETM 任务 ^^^^^^^^ ETM 任务对其操作进行了抽象，在软件中表示为 :cpp:type:`esp_etm_task_handle_t`，使任务得以用同一方式管理和表示。ETM 任务可以分配给不同外设，因此获取任务句柄的方式因外设而异。当不再需要某个任务时，请调用 :cpp:func:`esp_etm_channel_connect`，并传递一个 ``NULL`` 事件句柄，断开与任务的连接，随后调用 :cpp:func:`esp_etm_del_event`，释放任务资源。 GPIO 任务 ~~~~~~~~~~ GPIO 任务是最常见的任务类型。一个 GPIO 可以采取一个或多个 GPIO 操作，而一个 GPIO 任务也可以同时管理多个 GPIO 管脚。当 ETM 通道激活任务时，任务可以同时设置管理的所有 GPIO 引脚，使其设置/清除/切换状态。要创建 GPIO 任务句柄，请调用 :cpp:func:`gpio_new_etm_task`，并使用 :cpp:type:`gpio_etm_task_config_t` 提供的配置信息： - :cpp:member:`gpio_etm_task_config_t::action` 或 :cpp:member:`gpio_etm_task_config_t::actions` 决定 ETM 任务将采取的 GPIO 操作，支持的操作类型在 :cpp:type:`gpio_etm_task_action_t` 中列出。如果一个 GPIO 需要采取多个 GPIO 操作，这些操作任务的创建必须通过配置 :cpp:member:`gpio_etm_task_config_t::actions` 的数组并在一次 :cpp:func:`gpio_new_etm_task` 调用中一并完成。 接下来，需要连接 GPIO ETM 任务句柄与 GPIO 管脚。为此，请调用 :cpp:func:`gpio_etm_task_add_gpio` 函数。如果需要任务句柄管理更多的 GPIO 管脚，可以重复调用以上函数，注意，要设置 GPIO 管脚，只能使用由 :cpp:func:`gpio_new_etm_task` 函数创建的 ETM 任务句柄。对于其他类型的 ETM 任务，调用此函数，将返回 :c:macro:`ESP_ERR_INVALID_ARG` 错误。该函数也无法完成 GPIO 的初始化，在使用 GPIO ETM 任务之前，仍需调用 :cpp:func:`gpio_config` 函数，设置 GPIO 管脚的属性，如方向、高/低电平模式等。 要删除 GPIO ETM 任务，请调用 :cpp:func:`esp_etm_del_task`。在此之前，请确保已经调用过 :cpp:func:`gpio_etm_task_rm_gpio`，删除了所有先前添加的 GPIO 管脚。 其他外设任务 ~~~~~~~~~~~~~~~~~~~~~~ .. list:: :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: ETM 通道控制 ^^^^^^^^^^^^^^^^^^^ 映射事件与任务 ~~~~~~~~~~~~~~~~~~~~~~ 在调用 :cpp:func:`esp_etm_channel_connect` 将它们连接到同一个 ETM 通道之前，ETM 事件与 ETM 任务之间没有任何映射关系。注意，使用 ``NULL`` 任务/事件句柄调用该函数时，会将通道与任何任务或事件解除映射。此函数可以在通道启用之前或之后调用，但在运行时调用此函数更改映射关系存在一定风险，因为此时通道可能正处于周期的中间阶段，新的映射可能无法立即生效。 启用及禁用通道 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 调用 :cpp:func:`esp_etm_channel_enable` 启用 ETM 通道，调用 :cpp:func:`esp_etm_channel_disable` 禁用 ETM 通道。 ETM 通道分析 ~~~~~~~~~~~~~~~~~~~~~ 要检查是否为 ETM 通道设置了正确的事件和任务，可以调用 :cpp:func:`esp_etm_dump`，输出所有工作中的 ETM 通道及其关联的事件和任务。输出格式如下： :: ===========ETM Dump Start========== channel 0: event 48 ==> task 17 channel 1: event 48 ==> task 90 channel 2: event 48 ==> task 94 ===========ETM Dump End============ 以上输出信息打印的数字 ID 在 ``soc/soc_etm_source.h`` 文件中定义。 .. _etm-thread-safety: 线程安全 ^^^^^^^^^^^^^ ETM 驱动程序会确保工厂函数 :cpp:func:`esp_etm_new_channel` 和 :cpp:func:`gpio_new_etm_task` 的线程安全。使用时，可以直接从不同的 RTOS 任务中调用此类函数，无需额外锁保护。 在 ISR 环境中，不支持运行任何函数。 其他以 :cpp:type:`esp_etm_channel_handle_t`、:cpp:type:`esp_etm_task_handle_t` 和 :cpp:type:`esp_etm_event_handle_t` 作为首个位置参数的函数，则非线程安全，应避免从不同任务中调用此类函数。 .. _etm-kconfig-options: Kconfig 选项 ^^^^^^^^^^^^^^^ - :ref:`CONFIG_ETM_ENABLE_DEBUG_LOG` 用于启用调试日志输出，启用此选项将增加固件的二进制文件大小。 API 参考 ------------- .. include-build-file:: inc/esp_etm.inc .. include-build-file:: inc/gpio_etm.inc .. include-build-file:: inc/esp_systick_etm.inc .. [1] 不同 ESP 芯片系列的 ETM 通道数量可能不同。要了解更多详情，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **事件任务矩阵 (ETM)** [`PDF <{IDF_TARGET_TRM_EN_URL}#evntaskmatrix>`__]。驱动程序对通道申请数量不做限制，但当硬件资源用尽时，驱动程序将返回错误。因此，每次进行通道分配（即调用 :cpp:func:`esp_etm_new_channel`）时，请注意检查返回值。