Merge branch 'docs/translate_ana_cmpr' into 'master'

Docs/Provide Chinese translation for  ana_cmpr.rst

Closes DOC-8106

See merge request espressif/esp-idf!31585

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

@@ -1,6 +1,8 @@
 Analog Comparator
 =================
 
+:link_to_translation:`zh_CN:[中文]`
+
 {IDF_TARGET_ANA_CMPR_SRC_CHAN0: default="NOT UPDATED", esp32h2="GPIO11", esp32p4="GPIO52"}
 {IDF_TARGET_ANA_CMPR_EXT_REF_CHAN0: default="NOT UPDATED", esp32h2="GPIO10", esp32p4="GPIO51"}
 {IDF_TARGET_ANA_CMPR_SRC_CHAN1: default="NOT UPDATED", esp32p4="GPIO54"}
@@ -9,17 +11,17 @@ Analog Comparator
 Introduction
 ------------
 
-Analog Comparator is a peripheral that can be used to compare a source signal with the internal reference voltage or an external reference signal.
+Analog comparator is a peripheral that can be used to compare a source signal with the internal reference voltage or an external reference signal.
 
-It is a cost effective way to replace an amplifier comparator in some scenarios. But unlike the continuous comparing of the amplifier comparator, ESP Analog Comparator is driven by a source clock, which decides the sampling frequency.
+Under the scenario of comparing the analog signals, the integrated analog comparator is a cost effective scheme to replace an operational amplifier. But unlike the continuous comparing of the operational amplifier, ESP analog comparator is driven by a source clock, which decides the sampling frequency.
 
-Analog Comparator on {IDF_TARGET_NAME} has {IDF_TARGET_SOC_ANA_CMPR_NUM} unit(s), the channels in the unit(s) are:
+Analog comparator on {IDF_TARGET_NAME} has {IDF_TARGET_SOC_ANA_CMPR_NUM} unit(s), the channels in the unit(s) are:
 
 **UNIT0**
 
 - Source Channel: {IDF_TARGET_ANA_CMPR_SRC_CHAN0}
 - External Reference Channel: {IDF_TARGET_ANA_CMPR_EXT_REF_CHAN0}
-- Internal Reference Channel: Range 0% ~ 70% of the VDD, the step is 10% of the VDD
+- Internal Reference Channel: Range is 0% ~ 70% of the VDD, and the step is 10% of the VDD
 
 .. only:: esp32p4
 
@@ -32,33 +34,35 @@ Analog Comparator on {IDF_TARGET_NAME} has {IDF_TARGET_SOC_ANA_CMPR_NUM} unit(s)
 Functional Overview
 -------------------
 
-The following sections of this document cover the typical steps to install and operate an Analog Comparator unit:
+The following sections of this document cover the typical steps to install and operate an analog comparator unit:
 
--  `Resource Allocation <#resource-allocation>`__ - covers which parameters should be set up to get a unit handle and how to recycle the resources when it finishes working.
+- :ref:`anacmpr-resource-allocation` - covers which parameters should be set up to get a unit handle and how to recycle the resources when it finishes working.
--  `Further Configurations <#further-configurations>`__ - covers the other configurations that might need to specific and what they are used for.
+- :ref:`anacmpr-further-configurations` - covers the other configurations that might need to specify and what they are used for.
--  `Enable and Disable Unit <#enable-and-disable-unit>`__ - covers how to enable and disable the unit.
+- :ref:`anacmpr-enable-and-disable-unit` - covers how to enable and disable the unit.
--  `Power Management <#power-management>`__ - describes how different source clock selections can affect power consumption.
+- :ref:`anacmpr-power-management` - describes how different source clock selections can affect power consumption.
--  `IRAM Safe <#iram-safe>`__ - lists which functions are supposed to work even when the cache is disabled.
+- :ref:`anacmpr-iram-safe` - lists which functions are supposed to work even when the cache is disabled.
--  `Thread Safety <#thread-safety>`__ - lists which APIs are guaranteed to be thread safe by the driver.
+- :ref:`anacmpr-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
--  `Kconfig Options <#kconfig-options>`__ - lists the supported Kconfig options that can be used to make a different effect on driver behavior.
+- :ref:`anacmpr-kconfig-options` - lists the supported Kconfig options that can be used to make a different effect on driver behavior.
 
 .. only:: SOC_ANA_CMPR_SUPPORT_ETM
 
-    - `ETM Events <#etm-events>`__ -
+    - :ref:`anacmpr-etm-events` - covers how to create an analog comparator cross event.
+
+.. _anacmpr-resource-allocation:
 
 Resource Allocation
 ^^^^^^^^^^^^^^^^^^^
 
-An Analog Comparator unit channel is represented by :cpp:type:`ana_cmpr_handle_t`. Each unit can support either an internal or an external reference.
+An analog comparator unit channel is represented by :cpp:type:`ana_cmpr_handle_t`. Each unit can support either an internal or an external reference.
 
-To allocate the resource of the Analog Comparator unit, :cpp:func:`ana_cmpr_new_unit` need to be called to get the handle of the unit. Configurations :cpp:type:`ana_cmpr_config_t` need to be specified while allocating the unit:
+To allocate the resource of the analog comparator unit, :cpp:func:`ana_cmpr_new_unit` need to be called to get the handle of the unit. Configurations :cpp:type:`ana_cmpr_config_t` need to be specified while allocating the unit:
 
-- :cpp:member:`ana_cmpr_config_t::unit` selects the Analog Comparator unit.
+- :cpp:member:`ana_cmpr_config_t::unit` selects the analog comparator unit.
-- :cpp:member:`ana_cmpr_config_t::clk_src` selects the source clock for Analog Comparator, it can affect the sampling frequency. Note that the clock source of the Analog Comparator comes from the io mux, it is shared with GPIO extension peripherals like SDM (Sigma-Delta Modulation) and Glitch Filter. The configuration will fail if you specific different clock sources for multiple GPIO extension peripherals. The default clock sources of these peripherals are same, typically, we select :cpp:enumerator:`soc_periph_ana_cmpr_clk_src_t::ANA_CMPR_CLK_SRC_DEFAULT` as the clock source.
+- :cpp:member:`ana_cmpr_config_t::clk_src` selects the source clock for analog comparator, and it can affect the sampling frequency. Note that the clock source of the analog comparator comes from the IO MUX. It is shared with GPIO extension peripherals like SDM (Sigma-Delta Modulation) and Glitch Filter. The configuration will fail if you specify different clock sources for multiple GPIO extension peripherals. The default clock sources of these peripherals are same, and typically, we select :cpp:enumerator:`soc_periph_ana_cmpr_clk_src_t::ANA_CMPR_CLK_SRC_DEFAULT` as the clock source.
 - :cpp:member:`ana_cmpr_config_t::ref_src` selects the reference source from internal voltage or external signal.
 - :cpp:member:`ana_cmpr_config_t::cross_type` selects which kind of cross type can trigger the interrupt.
 
-The function :cpp:func:`ana_cmpr_new_unit` can fail due to various errors such as insufficient memory, invalid arguments, etc. If a previously created Analog Comparator unit is no longer required, you should recycle it by calling :cpp:func:`ana_cmpr_del_unit`. It allows the underlying HW channel to be used for other purposes. Before deleting an Analog Comparator unit handle, you should disable it by :cpp:func:`ana_cmpr_unit_disable` in advance, or make sure it has not enabled yet by :cpp:func:`ana_cmpr_unit_enable`.
+The function :cpp:func:`ana_cmpr_new_unit` can fail due to various errors such as insufficient memory, invalid arguments, etc. If a previously created analog comparator unit is no longer required, you should recycle it by calling :cpp:func:`ana_cmpr_del_unit`. It allows the underlying HW channel to be used for other purposes. Before deleting an analog comparator unit handle, you should disable it by :cpp:func:`ana_cmpr_disable` in advance, or make sure it has not enabled yet by :cpp:func:`ana_cmpr_enable`.
 
 .. code:: c
 
@@ -75,12 +79,14 @@ The function :cpp:func:`ana_cmpr_new_unit` can fail due to various errors such a
     // ...
     ESP_ERROR_CHECK(ana_cmpr_del_unit(cmpr));
 
+.. _anacmpr-further-configurations:
+
 Further Configurations
 ^^^^^^^^^^^^^^^^^^^^^^
 
-- :cpp:func:`ana_cmpr_set_intl_reference` - Specify the internal reference voltage when :cpp:enumerator:`ana_cmpr_ref_source_t::ANA_CMPR_REF_SRC_INTERNAL` is selected as reference source.
+- :cpp:func:`ana_cmpr_set_internal_reference` - Specify the internal reference voltage when :cpp:enumerator:`ana_cmpr_ref_source_t::ANA_CMPR_REF_SRC_INTERNAL` is selected as reference source.
 
-It requires :cpp:member:`ana_cmpr_internal_ref_config_t::ref_volt` to specify the voltage. The voltage related to the VDD power supply, which can only support a certain fixed percentage of VDD. Currently on {IDF_TARGET_NAME}, the internal reference voltage can be range to 0 ~ 70% VDD with a step 10%.
+It requires :cpp:member:`ana_cmpr_internal_ref_config_t::ref_volt` to specify the voltage. The voltage is related to the VDD power supply, which can only support a certain fixed percentage of VDD. Currently on {IDF_TARGET_NAME}, the internal reference voltage can be range to 0 ~ 70% VDD with a step 10%.
 
 .. code:: c
 
@@ -93,7 +99,7 @@ It requires :cpp:member:`ana_cmpr_internal_ref_config_t::ref_volt` to specify th
 
 - :cpp:func:`ana_cmpr_set_debounce` - Set the debounce configuration.
 
-It requires :cpp:member:`ana_cmpr_debounce_config_t::wait_us` to set the interrupt waiting time. The interrupt is disabled temporarily for :cpp:member:`ana_cmpr_debounce_config_t::wait_us` micro seconds, so that the frequent triggering can be avoid while the source signal crossing the reference signal. That is, the waiting time is supposed to be inverse ratio to the relative frequency between the source and reference. If the waiting time is set too short, it can not bypass the jitter totally, but if too long, the next crossing interrupt might be missed.
+It requires :cpp:member:`ana_cmpr_debounce_config_t::wait_us` to set the interrupt waiting time. The interrupt is disabled temporarily for :cpp:member:`ana_cmpr_debounce_config_t::wait_us` microseconds, so that the frequent triggering can be avoid while the source signal is crossing the reference signal. That is, the waiting time is supposed to be inverse ratio to the relative frequency between the source and reference. If the waiting time is set too short, it can not bypass the jitter totally, but if too long, the next crossing interrupt might be missed.
 
 .. code:: c
 
@@ -106,7 +112,7 @@ It requires :cpp:member:`ana_cmpr_debounce_config_t::wait_us` to set the interru
 
 - :cpp:func:`ana_cmpr_set_cross_type` - Set the source signal cross type.
 
-The initial cross type is set int :cpp:func:`ana_cmpr_new_unit`, this function can update the cross type, even in ISR context.
+The initial cross type is set in :cpp:func:`ana_cmpr_new_unit`. This function can update the cross type, even in ISR context.
 
 .. code:: c
 
@@ -116,7 +122,7 @@ The initial cross type is set int :cpp:func:`ana_cmpr_new_unit`, this function c
 
 - :cpp:func:`ana_cmpr_register_event_callbacks` - Register the callbacks.
 
-Currently it supports :cpp:member:`ana_cmpr_event_callbacks_t::on_cross`, it will be called when the crossing event (specified by :cpp:member:`ana_cmpr_config_t::cross_type`) occurs.
+Currently it supports :cpp:member:`ana_cmpr_event_callbacks_t::on_cross`, and it will be called when the crossing event (specified by :cpp:member:`ana_cmpr_config_t::cross_type`) occurs.
 
 .. code:: c
 
@@ -136,35 +142,41 @@ Currently it supports :cpp:member:`ana_cmpr_event_callbacks_t::on_cross`, it wil
 
 .. note::
 
-    When :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` is enabled, you should guarantee the callback context and involved data to be in internal RAM by add the attribute ``IRAM_ATTR``. (See more in `IRAM Safe <#iram-safe>`__)
+    When :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` is enabled, you should guarantee that the callback context and involved data are in internal RAM by adding the attribute ``IRAM_ATTR`` (See more in :ref:`anacmpr-iram-safe`).
+
+.. _anacmpr-enable-and-disable-unit:
 
 Enable and Disable Unit
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-- :cpp:func:`ana_cmpr_enable` - Enable the Analog Comparator unit.
+- :cpp:func:`ana_cmpr_enable` - Enable the analog comparator unit.
-- :cpp:func:`ana_cmpr_disable` - Disable the Analog Comparator unit.
+- :cpp:func:`ana_cmpr_disable` - Disable the analog comparator unit.
 
-After the Analog Comparator unit is enabled and the crossing event interrupt is enabled, a power management lock will be acquired if the power management is enabled (see `Power Management <#power-management>`__). Under the **enable** state, only :cpp:func:`ana_cmpr_set_intl_reference` and :cpp:func:`ana_cmpr_set_debounce` can be called, other functions can only be called after the unit is disabled.
+After the analog comparator unit is enabled and the crossing event interrupt is enabled, a power management lock will be acquired if the power management is enabled (see :ref:`anacmpr-power-management`). Under the **enable** state, only :cpp:func:`ana_cmpr_set_internal_reference` and :cpp:func:`ana_cmpr_set_debounce` can be called, other functions can only be called after the unit is disabled.
 
 Calling :cpp:func:`ana_cmpr_disable` does the opposite.
 
+.. _anacmpr-power-management:
+
 Power Management
 ^^^^^^^^^^^^^^^^
 
-When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the system will adjust the APB frequency before going into light sleep, thus potentially changing the resolution of the Analog Comparator.
+When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the system will adjust the APB frequency before going into Light-sleep mode, thus potentially changing the resolution of the analog comparator.
 
-However, the driver can prevent the system from changing APB frequency by acquiring a power management lock of type :cpp:enumerator:`ESP_PM_NO_LIGHT_SLEEP`. Whenever the driver creates a Analog Comparator unit instance that has selected the clock source like :cpp:enumerator:`ANA_CMPR_CLK_SRC_DEFAULT` or :cpp:enumerator:`ANA_CMPR_CLK_SRC_XTAL` as its clock source, the driver guarantees that the power management lock is acquired when enable the channel by :cpp:func:`ana_cmpr_enable`. Likewise, the driver releases the lock when :cpp:func:`ana_cmpr_disable` is called for that channel.
+However, the driver can prevent the system from changing APB frequency by acquiring a power management lock of type :cpp:enumerator:`ESP_PM_NO_LIGHT_SLEEP`. Whenever the driver creates an analog comparator unit instance that has selected the clock source like :cpp:enumerator:`ANA_CMPR_CLK_SRC_DEFAULT` or :cpp:enumerator:`ANA_CMPR_CLK_SRC_XTAL`, the driver guarantees that the power management lock is acquired when enable the channel by :cpp:func:`ana_cmpr_enable`. Likewise, the driver releases the lock when :cpp:func:`ana_cmpr_disable` is called for that channel.
+
+.. _anacmpr-iram-safe:
 
 IRAM Safe
 ^^^^^^^^^
 
-By default, the Analog Comparator interrupt will be deferred when the Cache is disabled for reasons like programming/erasing Flash. Thus the alarm interrupt will not get executed in time, which is not expected in a real-time application.
+By default, the analog comparator interrupt will be deferred when the cache is disabled for reasons like programming or erasing the flash. Thus the alarm interrupt will not get executed in time, which is not expected in a real-time application.
 
 There is a Kconfig option :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` that:
 
-1. Enables the interrupt being serviced even when cache is disabled
+1. Enables the interrupt being serviced even when cache is disabled.
-2. Places all functions that used by the ISR into IRAM [1]_
+2. Places all functions that used by the ISR into IRAM. [1]_
-3. Places driver object into DRAM (in case it is allocated on PSRAM)
+3. Places driver object into DRAM (in case it is allocated on PSRAM).
 
 This allows the interrupt to run while the cache is disabled but comes at the cost of increased IRAM consumption.
 
@@ -174,27 +186,34 @@ There is a Kconfig option :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM` that can put
 - :cpp:func:`ana_cmpr_set_debounce`
 - :cpp:func:`ana_cmpr_set_cross_type`
 
+.. _anacmpr-thread-safety:
+
 Thread Safety
 ^^^^^^^^^^^^^
 
-The factory function :cpp:func:`ana_cmpr_new_unit` is guaranteed to be thread safe by the driver, which means, user can call it from different RTOS tasks without protection by extra locks.
+The factory function :cpp:func:`ana_cmpr_new_unit` is guaranteed to be thread safe by the driver, which means, it can be called from different RTOS tasks without protection by extra locks.
-The following functions are allowed to run under ISR context, the driver uses a critical section to prevent them being called concurrently in both task and ISR.
+
+The following functions are allowed to run under ISR context. The driver uses a critical section to prevent them being called concurrently in both task and ISR:
 
 - :cpp:func:`ana_cmpr_set_internal_reference`
 - :cpp:func:`ana_cmpr_set_debounce`
 - :cpp:func:`ana_cmpr_set_cross_type`
 
-Other functions that take the :cpp:type:`ana_cmpr_handle_t` as the first positional parameter, are not treated as thread safe. Which means the user should avoid calling them from multiple tasks.
+Other functions that take :cpp:type:`ana_cmpr_handle_t` as the first positional parameter, are not treated as thread safe. As a result, users should avoid calling them from multiple tasks.
+
+.. _anacmpr-kconfig-options:
 
 Kconfig Options
 ^^^^^^^^^^^^^^^
 
-- :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see `IRAM Safe <#iram-safe>`__ for more information.
+- :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled. See :ref:`anacmpr-iram-safe` for more information.
-- :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM` controls where to place the Analog Comparator control functions (IRAM or Flash), see `IRAM Safe <#iram-safe>`__ for more information.
+- :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM` controls where to place the analog comparator control functions (IRAM or flash). See :ref:`anacmpr-iram-safe` for more information.
-- :ref:`CONFIG_ANA_CMPR_ENABLE_DEBUG_LOG` is used to enabled the debug log output. Enabling this option increases the firmware binary size.
+- :ref:`CONFIG_ANA_CMPR_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enabling this option increases the firmware binary size.
 
 .. only:: SOC_ANA_CMPR_SUPPORT_ETM
 
+    .. _anacmpr-etm-events:
+
     ETM Events
     ^^^^^^^^^^
 
@@ -212,4 +231,4 @@ API Reference
 .. include-build-file:: inc/ana_cmpr_types.inc
 
 .. [1]
-   :cpp:member:`ana_cmpr_event_callbacks_t::on_cross` callback and the functions invoked by itself should also be placed in IRAM, you need to take care of them by themselves.
+   :cpp:member:`ana_cmpr_event_callbacks_t::on_cross` callback and the functions invoked by it should also be placed in IRAM. Please take care of them.

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

@@ -1 +1,234 @@
-.. include:: ../../../en/api-reference/peripherals/ana_cmpr.rst
+模拟比较器
+==========
+
+:link_to_translation:`en:[English]`
+
+{IDF_TARGET_ANA_CMPR_SRC_CHAN0: default="未更新", esp32h2="GPIO11", esp32p4="GPIO52"}
+{IDF_TARGET_ANA_CMPR_EXT_REF_CHAN0: default="未更新", esp32h2="GPIO10", esp32p4="GPIO51"}
+{IDF_TARGET_ANA_CMPR_SRC_CHAN1: default="未更新", esp32p4="GPIO54"}
+{IDF_TARGET_ANA_CMPR_EXT_REF_CHAN1: default="未更新", esp32p4="GPIO53"}
+
+简介
+----
+
+模拟比较器是一种用于比较信号源与内部参考电压或外部参考信号的外设。
+
+当用于比较模拟信号时，集成模拟比较器可以低成本替代运算放大器。不同于运算放大器的连续比较，ESP 模拟比较器由时钟源驱动，其采样频率取决于时钟的频率。
+
+{IDF_TARGET_NAME} 上的模拟比较器有 {IDF_TARGET_SOC_ANA_CMPR_NUM} 个单元，单元中的通道如下：
+
+**UNIT0**
+
+- 源通道：{IDF_TARGET_ANA_CMPR_SRC_CHAN0}
+- 外部参考通道：{IDF_TARGET_ANA_CMPR_EXT_REF_CHAN0}
+- 内部参考通道：电压范围是 VDD 的 0% ~ 70%，步长为 VDD 的 10%
+
+.. only:: esp32p4
+
+    **UNIT1**
+
+    - 源通道：{IDF_TARGET_ANA_CMPR_SRC_CHAN1}
+    - 外部参考通道：{IDF_TARGET_ANA_CMPR_EXT_REF_CHAN1}
+    - 内部参考通道：电压范围是 VDD 的 0% ~ 70%，步长为 VDD 的 10%
+
+功能概述
+--------
+
+本文中的以下章节涵盖了安装及操作模拟比较器单元的基本步骤：
+
+- :ref:`anacmpr-resource-allocation` - 涵盖了应设置哪些参数以获取单元句柄，以及完成工作后如何回收资源。
+- :ref:`anacmpr-further-configurations` - 涵盖了可能需要指定的其他配置及其用途。
+- :ref:`anacmpr-enable-and-disable-unit` - 涵盖了如何启用和禁用单元。
+- :ref:`anacmpr-power-management` - 描述了不同时钟源对功耗的影响。
+- :ref:`anacmpr-iram-safe` - 列出了在 cache 被禁用时也能起效的函数。
+- :ref:`anacmpr-thread-safety` - 列出了驱动程序中线程安全的 API。
+- :ref:`anacmpr-kconfig-options` - 列出了支持的 Kconfig 选项，这些选项可以对驱动程序产生不同影响。
+
+.. only:: SOC_ANA_CMPR_SUPPORT_ETM
+
+    - :ref:`anacmpr-etm-events` - 介绍了如何创建一个模拟比较器跨越事件。
+
+.. _anacmpr-resource-allocation:
+
+资源分配
+^^^^^^^^
+
+模拟比较器单元由 :cpp:type:`ana_cmpr_handle_t` 表示，每个单元都可支持内部或外部的参考信号。
+
+通过调用 :cpp:func:`ana_cmpr_new_unit` 来获取单元句柄以分配资源。在分配单元时需要指定 :cpp:type:`ana_cmpr_config_t` 配置：
+
+- :cpp:member:`ana_cmpr_config_t::unit` 选择模拟比较器单元。
+- :cpp:member:`ana_cmpr_config_t::clk_src` 选择模拟比较器的时钟源，这将影响采样频率。请注意，模拟比较器的时钟源来自 IO MUX，与 Sigma-Delta 调制器 (SDM) 和毛刺过滤器 (Glitch Filter) 等 GPIO 扩展外设共享时钟源。如果为多个 GPIO 扩展外设指定不同的时钟源，则配置将失败。这些外设的默认时钟源是相同的，通常选择 :cpp:enumerator:`soc_periph_ana_cmpr_clk_src_t::ANA_CMPR_CLK_SRC_DEFAULT` 即可。
+- :cpp:member:`ana_cmpr_config_t::ref_src` 选择内部参考电压或外部参考信号为参考信号源。
+- :cpp:member:`ana_cmpr_config_t::cross_type` 选择哪种类型的跨零信号可以触发中断。
+
+函数 :cpp:func:`ana_cmpr_new_unit` 可能因内存不足、参数无效等各种错误而失败。如果不再需要先前创建的模拟比较器单元，可通过调用 :cpp:func:`ana_cmpr_del_unit` 来回收资源，从而释放底层硬件通道的资源供其他用途。在删除模拟比较器单元句柄之前，首先应通过 :cpp:func:`ana_cmpr_disable` 禁用句柄，或者确保尚未通过 :cpp:func:`ana_cmpr_enable` 启用该单元。
+
+.. code:: c
+
+    #include "driver/ana_cmpr.h"
+
+    ana_cmpr_handle_t cmpr = NULL;
+    ana_cmpr_config_t config = {
+        .unit = 0,
+        .clk_src = ANA_CMPR_CLK_SRC_DEFAULT,
+        .ref_src = ANA_CMPR_REF_SRC_INTERNAL,
+        .cross_type = ANA_CMPR_CROSS_ANY,
+    };
+    ESP_ERROR_CHECK(ana_cmpr_new_unit(&config, &cmpr));
+    // ...
+    ESP_ERROR_CHECK(ana_cmpr_del_unit(cmpr));
+
+.. _anacmpr-further-configurations:
+
+进一步配置
+^^^^^^^^^^
+
+- :cpp:func:`ana_cmpr_set_internal_reference` - 选择 :cpp:enumerator:`ana_cmpr_ref_source_t::ANA_CMPR_REF_SRC_INTERNAL` 作为参考源时，该函数可以指定内部参考电压。
+
+需要由 :cpp:member:`ana_cmpr_internal_ref_config_t::ref_volt` 来指定电压。该电压受 VDD 电源电压限制，只能支持固定百分比的 VDD。目前在 {IDF_TARGET_NAME} 上，内部参考电压范围是 VDD 的 0% ~ 70%，步长为 VDD 的 10%。
+
+.. code:: c
+
+    #include "driver/ana_cmpr.h"
+
+    ana_cmpr_internal_ref_config_t ref_cfg = {
+        .ref_volt = ANA_CMPR_REF_VOLT_50_PCT_VDD,
+    };
+    ESP_ERROR_CHECK(ana_cmpr_set_internal_reference(cmpr, &ref_cfg));
+
+- :cpp:func:`ana_cmpr_set_debounce` - 设置去抖配置。
+
+通过 :cpp:member:`ana_cmpr_debounce_config_t::wait_us` 可设置中断等待时间。跨零中断触发后，中断将暂时禁用 :cpp:member:`ana_cmpr_debounce_config_t::wait_us` 微秒，这样可以避免信号源跨越参考信号时频繁触发中断。因此，等待时间应与信号源和参考信号之间的相对频率成反比。如果中断等待时间设置得太短，则无法完全避免抖动，但如果设置得太长，则可能会错过下一个跨越中断。
+
+.. code:: c
+
+    #include "driver/ana_cmpr.h"
+
+    ana_cmpr_debounce_config_t dbc_cfg = {
+        .wait_us = 1,
+    };
+    ESP_ERROR_CHECK(ana_cmpr_set_debounce(cmpr, &dbc_cfg));
+
+- :cpp:func:`ana_cmpr_set_cross_type` - 设置信号源跨越类型。
+
+初始跨越类型在 :cpp:func:`ana_cmpr_new_unit` 中设置。即便在中断服务程序 (ISR) 的上下文中，此函数也可以更新跨越类型。
+
+.. code:: c
+
+    #include "driver/ana_cmpr.h"
+
+    ESP_ERROR_CHECK(ana_cmpr_set_cross_type(cmpr, ANA_CMPR_CROSS_POS));
+
+- :cpp:func:`ana_cmpr_register_event_callbacks` - 注册回调函数。
+
+目前支持 :cpp:member:`ana_cmpr_event_callbacks_t::on_cross`。当发生跨越事件（由 :cpp:member:`ana_cmpr_config_t::cross_type` 指定）时，将调用该回调函数。
+
+.. code:: c
+
+    #include "driver/ana_cmpr.h"
+
+    static bool IRAM_ATTR example_ana_cmpr_on_cross_callback(ana_cmpr_handle_t cmpr,
+                                                         const ana_cmpr_cross_event_data_t *edata,
+                                                         void *user_ctx)
+    {
+        // ...
+        return false;
+    }
+    ana_cmpr_event_callbacks_t cbs = {
+        .on_cross = example_ana_cmpr_on_cross_callback,
+    };
+    ESP_ERROR_CHECK(ana_cmpr_register_event_callbacks(cmpr, &cbs, NULL));
+
+.. note::
+
+    当启用 :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` 时，应添加属性 ``IRAM_ATTR``，确保回调上下文和涉及的数据位于内部 RAM 中（详情请参阅 :ref:`anacmpr-iram-safe`）。
+
+.. _anacmpr-enable-and-disable-unit:
+
+启用和禁用单元
+^^^^^^^^^^^^^^^^
+
+- :cpp:func:`ana_cmpr_enable` - 启用模拟比较器单元。
+- :cpp:func:`ana_cmpr_disable` - 禁用模拟比较器单元。
+
+启用模拟比较器单元与跨越事件中断后，若同时启用了电源管理（详见 :ref:`anacmpr-power-management`），则将获得电源管理锁。在 **启用** 状态下，只能调用 :cpp:func:`ana_cmpr_set_internal_reference` 和 :cpp:func:`ana_cmpr_set_debounce`，其他函数可在禁用单元后调用。
+
+调用 :cpp:func:`ana_cmpr_disable` 则会执行与上述过程相反的操作。
+
+.. _anacmpr-power-management:
+
+电源管理
+^^^^^^^^
+
+当启用电源管理时（即开启 :ref:`CONFIG_PM_ENABLE`），系统会在进入 Light-sleep 模式前调整 APB 频率，因此模拟比较器的分辨率也可能随之更改。
+
+通过获取类型为 :cpp:enumerator:`ESP_PM_NO_LIGHT_SLEEP` 的电源管理锁，驱动程序可以防止系统更改 APB 频率。只要驱动程序创建的模拟比较器单元实例选择 :cpp:enumerator:`ANA_CMPR_CLK_SRC_DEFAULT` 或 :cpp:enumerator:`ANA_CMPR_CLK_SRC_XTAL` 作为其时钟源，驱动程序会确保通过 :cpp:func:`ana_cmpr_enable` 启用通道，并获取电源管理锁。同理，当为该通道调用 :cpp:func:`ana_cmpr_disable` 时，驱动程序会释放锁。
+
+.. _anacmpr-iram-safe:
+
+IRAM 安全
+^^^^^^^^^
+
+默认情况下，当 cache 因写入或擦除 flash 等原因而被禁用时，模拟比较器的中断服务将会延迟，造成警报中断无法及时执行。在实时应用程序中通常需要避免这一情况发生。
+
+Kconfig 选项 :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` 支持：
+
+1. 即使 cache 被禁用也能启用中断服务。
+2. 将 ISR 使用的所有函数放入 IRAM。 [1]_
+3. 将驱动程序对象放入 DRAM（以防它被分配到 PSRAM上）。
+
+启用上述 Kconfig 选项以保证在禁用 cache 时可以正常使用函数，但这会增加 IRAM 消耗。
+
+另一个 Kconfig 选项 :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM` 也支持将常用的 IO 控制函数放入 IRAM 中，以保证在禁用 cache 时可以正常使用函数。IO 控制函数如下所示：
+
+- :cpp:func:`ana_cmpr_set_internal_reference`
+- :cpp:func:`ana_cmpr_set_debounce`
+- :cpp:func:`ana_cmpr_set_cross_type`
+
+.. _anacmpr-thread-safety:
+
+线程安全
+^^^^^^^^
+
+驱动程序会确保工厂函数 :cpp:func:`ana_cmpr_new_unit` 的线程安全。使用时，可以直接从不同的 RTOS 任务中调用此类函数，无需额外锁保护。
+
+驱动程序设置了临界区，以防函数同时在任务和 ISR 中被调用。因此，以下函数支持在 ISR 上下文运行：
+
+- :cpp:func:`ana_cmpr_set_internal_reference`
+- :cpp:func:`ana_cmpr_set_debounce`
+- :cpp:func:`ana_cmpr_set_cross_type`
+
+其他以 :cpp:type:`ana_cmpr_handle_t` 为第一个位置参数的函数均非线程安全，因此应避免从多个任务中调用这类函数。
+
+.. _anacmpr-kconfig-options:
+
+Kconfig 选项
+^^^^^^^^^^^^
+
+- :ref:`CONFIG_ANA_CMPR_ISR_IRAM_SAFE` 控制默认的 ISR 句柄在 cache 被禁用时是否可以正常工作，详见 :ref:`anacmpr-iram-safe`。
+- :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM` 控制模拟比较器控制函数的存放位置（IRAM 或 flash），详见 :ref:`anacmpr-iram-safe`。
+- :ref:`CONFIG_ANA_CMPR_ENABLE_DEBUG_LOG` 用于启用调试日志输出。启用此选项将增加固件的二进制文件大小。
+
+.. only:: SOC_ANA_CMPR_SUPPORT_ETM
+
+    .. _anacmpr-etm-events:
+
+    ETM 事件
+    ^^^^^^^^
+
+    创建一个模拟比较器跨越事件，需要额外包含头文件 ``driver/ana_cmpr_etm.h``，并调用函数 :cpp:func:`ana_cmpr_new_etm_event` 来分配事件。有关如何将事件连接到任务，请参考 :doc:`ETM </api-reference/peripherals/etm>`。
+
+应用示例
+--------
+
+* :example:`peripherals/analog_comparator` 展示了模拟比较器的基本用法以及其他用途（如迟滞比较器和 SPWM 发生器）。
+
+API 参考
+--------
+
+.. include-build-file:: inc/ana_cmpr.inc
+.. include-build-file:: inc/ana_cmpr_types.inc
+
+.. [1]
+   :cpp:member:`ana_cmpr_event_callbacks_t::on_cross` 回调函数，以及由其调用的其他函数也应放置在 IRAM 中，请妥善处理。