docs(pcnt,mcpwm): document new features for esp32p4

2025-09-29 16:40:57 +02:00 · 2023-09-13 18:20:15 +08:00
parent c1342d3347
commit 608fca9d31
6 changed files with 41 additions and 23 deletions
--- a/docs/docs_not_updated/esp32p4.txt
+++ b/docs/docs_not_updated/esp32p4.txt
@@ -111,13 +111,9 @@ api-reference/peripherals/gpio.rst
 api-reference/peripherals/sdspi_host.rst
 api-reference/peripherals/dac.rst
 api-reference/peripherals/spi_slave.rst
-api-reference/peripherals/etm.rst
 api-reference/peripherals/i2s.rst
-api-reference/peripherals/gptimer.rst
-api-reference/peripherals/pcnt.rst
 api-reference/peripherals/touch_element.rst
 api-reference/peripherals/lcd.rst
-api-reference/peripherals/mcpwm.rst
 api-reference/peripherals/ana_cmpr.rst
 api-reference/peripherals/secure_element.rst
 api-reference/peripherals/ledc.rst
@@ -167,7 +163,6 @@ api-reference/system/ulp-lp-core.rst
 api-reference/system/ulp.rst
 api-reference/system/esp_function_with_shared_stack.rst
 api-reference/system/ulp_instruction_set.rst
-api-reference/system/async_memcpy.rst
 api-reference/system/random.rst
 api-reference/system/esp_event.rst
 api-reference/system/system_time.rst
--- a/docs/doxygen/Doxyfile
+++ b/docs/doxygen/Doxyfile
@@ -95,6 +95,7 @@ INPUT = \
    $(PROJECT_PATH)/components/driver/ledc/include/driver/ledc.h \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_cap.h \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_cmpr.h \
+    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_etm.h \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_fault.h \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_gen.h \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_oper.h \
--- a/docs/en/api-reference/peripherals/mcpwm.rst
+++ b/docs/en/api-reference/peripherals/mcpwm.rst
@@ -111,6 +111,10 @@ The :cpp:func:`mcpwm_new_comparator` will return a pointer to the allocated comp

 On the contrary, calling the :cpp:func:`mcpwm_del_comparator` function will free the allocated comparator object.

+.. only:: SOC_MCPWM_SUPPORT_EVENT_COMPARATOR
+
+    There's another kind of comparator called "Event Comparator", which **can not** control the final PWM directly but only generates the ETM events at a configurable time stamp. You can allocate an event comparator by calling the :cpp:func:`mcpwm_new_event_comparator` function. This function will return the same handle type as :cpp:func:`mcpwm_new_comparator`, but with a different configuration structure :cpp:type:`mcpwm_event_comparator_config_t`. For more information, please refer to :ref:`mcpwm-etm-event-and-task`.
+
 MCPWM Generators
 ~~~~~~~~~~~~~~~~

@@ -187,7 +191,7 @@ To allocate a capture timer, you can call the :cpp:func:`mcpwm_new_capture_timer
 - :cpp:member:`mcpwm_capture_timer_config_t::clk_src` sets the clock source of the capture timer.
 - :cpp:member:`mcpwm_capture_timer_config_t::resolution_hz` The driver internally will set a proper divider based on the clock source and the resolution. If it is set to ``0``, the driver will pick an appropriate resolution on its own, and you can subsequently view the current timer resolution via :cpp:func:`mcpwm_capture_timer_get_resolution`.

-.. only:: not SOC_MCPWM_CAPTURE_CLK_FROM_GROUP 
+.. only:: not SOC_MCPWM_CAPTURE_CLK_FROM_GROUP

    .. note::

@@ -279,6 +283,12 @@ The parameter ``user_data`` of :cpp:func:`mcpwm_comparator_register_event_callba

 This function will lazy the installation of interrupt service for the MCPWM comparator, whereas the service can only be removed in :cpp:type:`mcpwm_del_comparator`.

+.. only:: SOC_MCPWM_SUPPORT_EVENT_COMPARATOR
+
+    .. note::
+
+        It is not supported to register event callbacks for an **Event Comparator** because it can not generate any interrupt.
+
 Set Compare Value
 ~~~~~~~~~~~~~~~~~

@@ -335,7 +345,7 @@ One generator can set action on fault based trigger events, by calling :cpp:func

 When no free trigger slot is left in the operator to which the generator belongs, this function will return the :c:macro:`ESP_ERR_NOT_FOUND` error. [1]_

-The trigger only support GPOI fault. when the input is not a GPIO fault, this function will return the :c:macro:`ESP_ERR_NOT_SUPPORTED` error. 
+The trigger only support GPOI fault. when the input is not a GPIO fault, this function will return the :c:macro:`ESP_ERR_NOT_SUPPORTED` error.

 There is a helper macro :c:macro:`MCPWM_GEN_FAULT_EVENT_ACTION` to simplify the construction of a trigger event action entry.

@@ -1026,6 +1036,7 @@ API Reference
 .. include-build-file:: inc/mcpwm_fault.inc
 .. include-build-file:: inc/mcpwm_sync.inc
 .. include-build-file:: inc/mcpwm_cap.inc
+.. include-build-file:: inc/mcpwm_etm.inc
 .. include-build-file:: inc/components/driver/mcpwm/include/driver/mcpwm_types.inc
 .. include-build-file:: inc/components/hal/include/hal/mcpwm_types.inc

--- a/docs/en/api-reference/peripherals/pcnt.rst
+++ b/docs/en/api-reference/peripherals/pcnt.rst
@@ -27,7 +27,7 @@ Description of the PCNT functionality is divided into the following sections:
    - :ref:`pcnt-watch-points` - describes how to configure PCNT watch points (i.e., tell PCNT unit to trigger an event when the count reaches a certain value).
    - :ref:`pcnt-register-event-callbacks` - describes how to hook your specific code to the watch point event callback function.
    - :ref:`pcnt-set-glitch-filter` - describes how to enable and set the timing parameters for the internal glitch filter.
-    :SOC_PCNT_SUPPORT_CLEAR_SIGNAL: - :ref:`pcnt-set-clear-signal` - describes how to set the parameters for the zero signal.
+    :SOC_PCNT_SUPPORT_CLEAR_SIGNAL: - :ref:`pcnt-set-clear-signal` - describes how to set the parameters for the external clear signal.
    - :ref:`pcnt-enable-disable-unit` - describes how to enable and disable the PCNT unit.
    - :ref:`pcnt-unit-io-control` - describes IO control functions of PCNT unit, like enable glitch filter, start and stop unit, get and clear count value.
    - :ref:`pcnt-power-management` - describes what functionality will prevent the chip from going into low power mode.
@@ -205,16 +205,16 @@ This function should be called when the unit is in the init state. Otherwise, it

    .. _pcnt-set-clear-signal:

-    Set Clear Signal
-    ^^^^^^^^^^^^^^^^
+    Use External Clear Signal
+    ^^^^^^^^^^^^^^^^^^^^^^^^^

-    The PCNT unit can receive a zero signal from the GPIO. The parameters that can be configured for the zero signal are listed in :cpp:type:`pcnt_clear_signal_config_t`:
+    The PCNT unit can receive a clear signal from the GPIO. The parameters that can be configured for the clear signal are listed in :cpp:type:`pcnt_clear_signal_config_t`:

-        -  :cpp:member:`pcnt_clear_signal_config_t::zero_input_gpio_num` specify the GPIO numbers used by **zero** signal. The default active level is high, and the input mode is pull-down enabled.
-        -  :cpp:member:`pcnt_clear_signal_config_t::invert_zero_input` is used to decide whether to invert the input signal before it going into PCNT hardware. The invert is done by GPIO matrix instead of PCNT hardware. The input mode is pull-up enabled when the input signal is invert.
-        -  :cpp:member:`pcnt_clear_signal_config_t::io_loop_back` is for debug only, which enables both the GPIO's input and output paths. This can help to simulate the zreo pulse signals by function :cpp:func:`gpio_set_level` on the same GPIO.
+        -  :cpp:member:`pcnt_clear_signal_config_t::clear_signal_gpio_num` specify the GPIO numbers used by **clear** signal. The default active level is high, and the input mode is pull-down enabled.
+        -  :cpp:member:`pcnt_clear_signal_config_t::invert_clear_signal` is used to decide whether to invert the input signal before it going into PCNT hardware. The invert is done by GPIO matrix instead of PCNT hardware. The input mode is pull-up enabled when the input signal is inverted.
+        -  :cpp:member:`pcnt_clear_signal_config_t::io_loop_back` is for debug only, which enables both the GPIO's input and output paths. This can help to simulate the clear signal by function :cpp:func:`gpio_set_level` for the same GPIO.

-    This signal acts in the same way as calling :cpp:func:`pcnt_unit_clear_count`, but is not subject to software latency, and is suitable for use in situations with high latency requirements.
+    This signal acts in the same way as calling :cpp:func:`pcnt_unit_clear_count`, but is not subject to software latency, and is suitable for use in situations with low latency requirements. Also please note, the flip frequency of this signal can not be too high.

    .. code:: c

--- a/docs/zh_CN/api-reference/peripherals/mcpwm.rst
+++ b/docs/zh_CN/api-reference/peripherals/mcpwm.rst
@@ -111,6 +111,10 @@ MCPWM 比较器

 反之，调用 :cpp:func:`mcpwm_del_comparator` 函数将释放已分配的比较器。

+.. only:: SOC_MCPWM_SUPPORT_EVENT_COMPARATOR
+
+    MCPWM 中还有另外一种比较器 —— “事件比较器”，它不能直接控制 PWM 的输出，只能用来产生 EMT 子系统中使用到的事件。事件比较器能够设置的阈值也是可配的。调用 :cpp:func:`mcpwm_new_event_comparator` 函数可以申请一个事件比较器，该函数返回的句柄类型和 :cpp:func:`mcpwm_new_comparator` 函数一样，但是需要的配置结构体是不同的。事件比较器的配置位于 :cpp:type:`mcpwm_event_comparator_config_t`。更多相关内容请参阅 :ref:`mcpwm-etm-event-and-task`。
+
 MCPWM 生成器
 ~~~~~~~~~~~~~~~~

@@ -187,7 +191,7 @@ MCPWM 组有一个专用定时器，用于捕获特定事件发生时的时间
 - :cpp:member:`mcpwm_capture_timer_config_t::clk_src` 设置捕获定时器的时钟源。
 - :cpp:member:`mcpwm_capture_timer_config_t::resolution_hz` 设置捕获定时器的预期分辨率。内部驱动将根据时钟源和分辨率设置合适的分频器。设置为 ``0`` 时，驱动会自己选取一个适当的分辨率，后续你可以通过 :cpp:func:`mcpwm_capture_timer_get_resolution` 查看当前定时器的分辨率。

-.. only:: not SOC_MCPWM_CAPTURE_CLK_FROM_GROUP 
+.. only:: not SOC_MCPWM_CAPTURE_CLK_FROM_GROUP

    .. note::

@@ -279,6 +283,12 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若

 此函数会延迟安装 MCPWM 比较器的中断服务。中断服务只能通过 :cpp:type:`mcpwm_del_comparator` 移除。

+.. only:: SOC_MCPWM_SUPPORT_EVENT_COMPARATOR
+
+    .. note::
+
+        对于事件比较器，你无法通过该函数来注册回调函数，因为事件比较器触发产生任何中断事件。
+
 设置比较值
 ~~~~~~~~~~~~~~~~~

@@ -1026,6 +1036,7 @@ API Reference
 .. include-build-file:: inc/mcpwm_fault.inc
 .. include-build-file:: inc/mcpwm_sync.inc
 .. include-build-file:: inc/mcpwm_cap.inc
+.. include-build-file:: inc/mcpwm_etm.inc
 .. include-build-file:: inc/components/driver/mcpwm/include/driver/mcpwm_types.inc
 .. include-build-file:: inc/components/hal/include/hal/mcpwm_types.inc

--- a/docs/zh_CN/api-reference/peripherals/pcnt.rst
+++ b/docs/zh_CN/api-reference/peripherals/pcnt.rst
@@ -27,7 +27,7 @@ PCNT 的功能从以下几个方面进行说明：
    - :ref:`pcnt-watch-points` - 说明如何配置观察点，即当计数达到某个数值时，命令 PCNT 单元触发某个事件。
    - :ref:`pcnt-register-event-callbacks` - 说明如何将您的代码挂载到观察点事件的回调函数上。
    - :ref:`pcnt-set-glitch-filter` - 说明如何使能毛刺滤波器并设置其时序参数。
-    :SOC_PCNT_SUPPORT_CLEAR_SIGNAL: - :ref:`pcnt-set-clear-signal` - 说明如何使能清零信号并设置其参数。
+    :SOC_PCNT_SUPPORT_CLEAR_SIGNAL: - :ref:`pcnt-set-clear-signal` - 说明如何使能外部清零信号并设置其参数。
    - :ref:`pcnt-enable-disable-unit` - 说明如何使能和关闭 PCNT 单元。
    - :ref:`pcnt-unit-io-control` - 说明 PCNT 单元的 IO 控制功能，例如使能毛刺滤波器，开启和停用 PCNT 单元，获取和清除计数。
    - :ref:`pcnt-power-management` - 说明哪些功能会阻止芯片进入低功耗模式。
@@ -205,16 +205,16 @@ PCNT 单元的滤波器可滤除信号中的短时毛刺，:cpp:type:`pcnt_glitc

    .. _pcnt-set-clear-signal:

-    设置清零信号
+    使用外部清零信号
    ^^^^^^^^^^^^^^^^

    PCNT 单元的可以接收来自 GPIO 的清零信号，:cpp:type:`pcnt_clear_signal_config_t` 中列出了清零信号的配置参数：

-        -  :cpp:member:`pcnt_clear_signal_config_t::zero_input_gpio_num` 用于指定 **清零** 信号对应的 GPIO 编号。默认有效电平为高，使能下拉输入。
-        -  :cpp:member:`pcnt_clear_signal_config_t::invert_zero_input` 用于确定信号在输入 PCNT 之前是否需要被翻转，信号翻转由 GPIO 矩阵 (不是 PCNT 单元) 执行。翻转时使能上拉输入。
-        -  :cpp:member:`pcnt_clear_signal_config_t::io_loop_back` 仅用于调试，它可以使能 GPIO 的输入和输出路径。这样，就可以通过调用位于同一 GPIO 上的函数 :cpp:func:`gpio_set_level` 来模拟脉冲清零信号。
+        -  :cpp:member:`pcnt_clear_signal_config_t::clear_signal_gpio_num` 用于指定 **清零** 信号对应的 GPIO 编号。默认有效电平为高，使能下拉输入。
+        -  :cpp:member:`pcnt_clear_signal_config_t::invert_clear_signal` 用于确定信号在输入 PCNT 之前是否需要被翻转，信号翻转由 GPIO 矩阵 (不是 PCNT 单元) 执行。驱动会使能上拉输入，以确保信号在未连接时保持高电平。
+        -  :cpp:member:`pcnt_clear_signal_config_t::io_loop_back` 仅用于调试，它可以使能 GPIO 的输入和输出路径。这样，就可以通过 :cpp:func:`gpio_set_level` 函数来模拟外部输入的清零信号。

-    该信号作用与调用 :cpp:func:`pcnt_unit_clear_count` 相同，但不受软件延迟的限制，适用于对延迟要求较高的场合。
+    该输入信号的作用与调用 :cpp:func:`pcnt_unit_clear_count` 函数相同，但它不受软件延迟的限制，更适用于需要低延迟的场合。请注意，该信号的翻转频率不能太高。

    .. code:: c

@@ -227,7 +227,7 @@ PCNT 单元的滤波器可滤除信号中的短时毛刺，:cpp:type:`pcnt_glitc

 .. only:: not SOC_PCNT_SUPPORT_CLEAR_SIGNAL

-    .. _pcnt-enable-disable-unit:  
+    .. _pcnt-enable-disable-unit:

 使能和禁用单元
 ^^^^^^^^^^^^^^^^^