diff --git a/docs/zh_CN/api-reference/system/ulp-fsm.rst b/docs/zh_CN/api-reference/system/ulp-fsm.rst index 89ad383547..aa827a4953 100644 --- a/docs/zh_CN/api-reference/system/ulp-fsm.rst +++ b/docs/zh_CN/api-reference/system/ulp-fsm.rst @@ -47,9 +47,9 @@ ULP FSM 协处理器代码由汇编语言编写,使用 `binutils-esp32ulp 工 set(ulp_s_sources ulp/ulp_assembly_source_file.S) set(ulp_exp_dep_srcs "ulp_c_source_file.c") - ulp_embed_binary(${ulp_app_name} "${ulp_s_sources}" "${ulp_exp_dep_srcs}") + ulp_embed_binary(${ulp_app_name} "${ulp_s_sources}" "${ulp_exp_dep_srcs}" TYPE fsm) -``ulp_embed_binary`` 的第一个参数用于指定 ULP FSM 二进制文件的名称,该名称也用于生成的其他文件,如:ELF 文件、.map 文件、头文件和链接器导出文件。第二个参数指定 ULP FSM 汇编源文件。最后,第三个参数指定组件源文件列表,这些源文件中会包含要生成的头文件。此列表用于建立正确的依赖项,并确保在编译这些文件之前先创建生成的头文件。有关 ULP FSM 应用程序生成的头文件等相关概念,请参考下文。 +``ulp_embed_binary`` 的第一个参数用于指定 ULP FSM 二进制文件的名称,该名称也用于生成的其他文件,如:ELF 文件、.map 文件、头文件和链接器导出文件。第二个参数指定 ULP FSM 汇编源文件。第三个参数指定组件源文件列表,这些源文件中会包含要生成的头文件。此列表用于建立正确的依赖项,并确保在编译这些文件之前先创建生成的头文件。第四个参数 ``TYPE`` 为可选项,但在 menuconfig 的 ``ULP Coprocessor types`` 中同时勾选 ``CONFIG_ULP_COPROC_TYPE_FSM`` 与 ``CONFIG_ULP_COPROC_TYPE_RISCV`` 时,必须填写为 ``TYPE fsm`` 才能使用 FSM 工具链编译。有关 ULP FSM 应用程序生成的头文件等相关概念,请参考下文。 在这个生成的头文件中,ULP 代码中的变量默认以 ``ulp_`` 作为前缀。 @@ -135,7 +135,7 @@ ULP FSM 协处理器代码由汇编语言编写,使用 `binutils-esp32ulp 工 要运行 ULP FSM 程序,主应用程序需要调用 :cpp:func:`ulp_load_binary` 函数将 ULP 程序加载到 RTC 内存中,然后调用 :cpp:func:`ulp_run` 函数,启动 ULP 程序。 -注意,在 menuconfig 中必须启用 ``Enable Ultra Low Power (ULP) Coprocessor`` 选项,以便正常运行 ULP,并且必须设置 ``ULP Co-processor type`` 选项,以便选择要使用的 ULP 类型。 ``RTC slow memory reserved for coprocessor`` 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序,则 RTC 内存必须足以容纳最大的程序。 +注意,在 menuconfig 中必须启用 ``Enable Ultra Low Power (ULP) Coprocessor`` 选项才能使用 ULP。要选择 ULP 的 FSM 类型,请进入 menu 选项 ``ULP Coprocessor types`` 并勾选 ``CONFIG_ULP_COPROC_TYPE_FSM``。``RTC slow memory reserved for coprocessor`` 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序,则 RTC 内存必须足以容纳最大的程序。 每个 ULP 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB,并以下面的方式加载此 BLOB(假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``):: @@ -200,6 +200,10 @@ ULP FSM 协处理器代码由汇编语言编写,使用 `binutils-esp32ulp 工 * :example:`system/ulp/ulp_fsm/ulp_adc` 展示了主处理器处于 Deep-sleep 状态时,ULP FSM 协处理器测量特定 ADC 通道上的输入电压,将其与设定的阈值进行比较,电压超出阈值时唤醒系统。 +.. only:: esp32s2 or esp32s3 + + * :example:`system/ulp/ulp_fsm_riscv_combined/counter` 展示了如何在同一个应用程序中依次使用 ULP FSM 和 ULP RISC-V 协处理器:使用 FSM 从 0 计数到 100,再使用 RISC-V 协处理器从 100 计数到 500。期间,HP 内核保持休眠模式,直到计数完成。 + API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/ulp-lp-core.rst b/docs/zh_CN/api-reference/system/ulp-lp-core.rst index 2a51dd9618..87b3ce21b3 100644 --- a/docs/zh_CN/api-reference/system/ulp-lp-core.rst +++ b/docs/zh_CN/api-reference/system/ulp-lp-core.rst @@ -105,7 +105,7 @@ ULP LP 内核代码会与 ESP-IDF 项目共同编译,生成一个单独的二 若想编译和构建项目,请执行以下操作: -1. 在 menuconfig 中启用 :ref:`CONFIG_ULP_COPROC_ENABLED` 和 :ref:`CONFIG_ULP_COPROC_TYPE` 选项,并将 :ref:`CONFIG_ULP_COPROC_TYPE` 设置为 ``CONFIG_ULP_COPROC_TYPE_LP_CORE``。:ref:`CONFIG_ULP_COPROC_RESERVE_MEM` 选项为 ULP 保留 RTC 内存,因此必须设置为一个足够大的值,以存储 ULP LP 内核代码和数据。如果应用程序组件包含多个 ULP 程序,那么 RTC 内存的大小必须足够容纳其中最大的程序。 +1. 在 menuconfig 中启用 :ref:`CONFIG_ULP_COPROC_ENABLED`,并在 ``ULP Coprocessor types`` 菜单中勾选 :ref:`CONFIG_ULP_COPROC_TYPE_LP_CORE`。:ref:`CONFIG_ULP_COPROC_RESERVE_MEM` 选项为 ULP 保留 RTC 内存,因此必须设置为一个足够大的值,以存储 ULP LP 内核代码和数据。如果应用程序组件包含多个 ULP 程序,那么 RTC 内存的大小必须足够容纳其中最大的程序。 2. 按照常规步骤构建应用程序(例如 ``idf.py app``)。 @@ -299,7 +299,7 @@ ULP LP 内核的时钟源来自系统时钟 ``LP_FAST_CLK``,详情请参见 ` * 通过共享变量共享程序状态:如 :ref:`ulp-lp-core-access-variables` 所述,主 CPU 和 ULP 内核都可以轻松访问 RTC 内存中的全局变量。若想了解 ULP 内核的运行状态,可以将状态信息从 ULP 写入变量中,并通过主 CPU 读取信息。这种方法的缺点在于它需要主 CPU 一直处于唤醒状态,而这通常很难实现。另外,若主 CPU 一直处于唤醒状态,可能会掩盖某些问题,因为部分问题只会在特定电源域断电时发生。 -* 紧急处理程序:当检测到异常时,LP 内核的紧急处理程序会把 LP 内核寄存器的状态通过 LP UART 发送出去。将 :ref:`CONFIG_ULP_PANIC_OUTPUT_ENABLE` 选项设置为 ``y``,可以启用紧急处理程序。禁用此选项将减少 LP 内核应用程序的 LP-RAM 使用量。若想从紧急转储中解析栈回溯,可以使用 ``idf.py monitor``。 +* 紧急处理程序:当检测到异常时,LP 内核的紧急处理程序会把 LP 内核寄存器的状态通过 LP UART 发送出去。将 ``CONFIG_ULP_PANIC_OUTPUT_ENABLE`` 选项设置为 ``y``,可以启用紧急处理程序。禁用此选项将减少 LP 内核应用程序的 LP-RAM 使用量。若想从紧急转储中解析栈回溯,可以使用 ``idf.py monitor``。 .. warning:: diff --git a/docs/zh_CN/api-reference/system/ulp-risc-v.rst b/docs/zh_CN/api-reference/system/ulp-risc-v.rst index 9599e5122b..089d2f7410 100644 --- a/docs/zh_CN/api-reference/system/ulp-risc-v.rst +++ b/docs/zh_CN/api-reference/system/ulp-risc-v.rst @@ -36,9 +36,9 @@ ULP RISC-V 协处理器代码以 C 语言(或汇编语言)编写,使用基 set(ulp_sources "ulp/ulp_c_source_file.c" "ulp/ulp_assembly_source_file.S") set(ulp_exp_dep_srcs "ulp_c_source_file.c") - ulp_embed_binary(${ulp_app_name} "${ulp_sources}" "${ulp_exp_dep_srcs}") + ulp_embed_binary(${ulp_app_name} "${ulp_sources}" "${ulp_exp_dep_srcs}" TYPE riscv) -``ulp_embed_binary`` 的第一个参数指定生成的 ULP 二进制文件名。该文件名也用于其他生成的文件,如 ELF 文件、映射文件、头文件和链接器导出文件。第二个参数指定 ULP 源文件。第三个参数指定组件源文件列表,其中包括生成的头文件。此列表用以正确构建依赖,并确保在编译这些文件前创建要生成的头文件。有关 ULP 应用程序生成头文件的概念,请参阅本文档后续章节。 +``ulp_embed_binary`` 的第一个参数指定生成的 ULP 二进制文件名。该文件名也用于其他生成的文件,如 ELF 文件、映射文件、头文件和链接器导出文件。第二个参数指定 ULP 源文件。第三个参数指定组件源文件列表,其中包括生成的头文件。此列表用以正确构建依赖,并确保在编译这些文件前创建要生成的头文件。第四个参数 ``TYPE`` 为可选项,但在 menu 选项 ``ULP Coprocessor types`` 中同时勾选 :ref:`CONFIG_ULP_COPROC_TYPE_FSM` 与 :ref:`CONFIG_ULP_COPROC_TYPE_RISCV` 时,必须填写为 ``TYPE riscv`` 才能使用 RISC-V 工具链编译。有关 ULP 应用程序生成头文件的概念,请参阅本文档后续章节。 在这个生成的头文件中,ULP 代码中的变量默认以 ``ulp_`` 作为前缀。 @@ -108,7 +108,7 @@ ULP RISC-V 协处理器代码以 C 语言(或汇编语言)编写,使用基 若想编译和构建项目,请执行以下操作: -1. 在 menuconfig 中启用 :ref:`CONFIG_ULP_COPROC_ENABLED` 和 :ref:`CONFIG_ULP_COPROC_TYPE` 选项,并将 :ref:`CONFIG_ULP_COPROC_TYPE` 设置为 ``CONFIG_ULP_COPROC_TYPE_LP_CORE``。:ref:`CONFIG_ULP_COPROC_RESERVE_MEM` 选项为 ULP 保留 RTC 内存,因此必须设置为一个足够大的值,以存储 ULP LP-Core 代码和数据。如果应用程序组件包含多个 ULP 程序,那么 RTC 内存的大小必须足够容纳其中最大的程序。 +1. 在 menuconfig 中启用 :ref:`CONFIG_ULP_COPROC_ENABLED`,并在 ``ULP Coprocessor types`` 菜单中勾选 `CONFIG_ULP_COPROC_TYPE_RISCV`。:ref:`CONFIG_ULP_COPROC_RESERVE_MEM` 选项为 ULP 保留 RTC 内存,因此必须设置为一个足够大的值,以存储 ULP RISC-V 代码和数据。如果应用程序组件包含多个 ULP 程序,那么 RTC 内存的大小必须足够容纳其中最大的程序。 2. 按照常规步骤构建应用程序(例如 ``idf.py app``)。 @@ -193,7 +193,7 @@ ULP 中的所有硬件指令都不支持互斥,所以 Lock API 需通过一种 要运行 ULP RISC-V 程序,主程序需要调用 :cpp:func:`ulp_riscv_load_binary` 函数,将 ULP 程序加载到 RTC 内存中,然后调用 :cpp:func:`ulp_riscv_run` 函数,启动 ULP RISC-V 程序。 -注意,必须在 menuconfig 中启用 ``CONFIG_ULP_COPROC_ENABLED`` 和 ``CONFIG_ULP_COPROC_TYPE_RISCV`` 选项,以便正常运行 ULP RISC-V 程序。``RTC slow memory reserved for coprocessor`` 选项设置的值必须足够存储 ULP RISC-V 代码和数据。如果应用程序组件包含多个 ULP 程序,RTC 内存必须足以容纳最大的程序。 +注意,必须在 menuconfig 中启用 :ref:`CONFIG_ULP_COPROC_ENABLED` 和 :ref:`CONFIG_ULP_COPROC_TYPE_RISCV` 选项才能使用 ULP RISC-V。 ``RTC slow memory reserved for coprocessor`` 选项设置的值必须足够存储 ULP RISC-V 代码和数据。如果应用程序组件包含多个 ULP 程序,RTC 内存必须足以容纳最大的程序。 每个 ULP RISC-V 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB,并以下面的方式加载此 BLOB(假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``): @@ -339,6 +339,10 @@ ULP RISC-V 的中断处理尚在开发中,还不支持针对内部中断源的 * :example:`system/ulp/ulp_riscv/touch` 演示了如何使用 ULP RISC-V 协处理器定期扫描和读取触摸传感器,并在触摸传感器被激活时唤醒主 CPU。 +.. only:: esp32s2 or esp32s3 + + * :example:`system/ulp/ulp_fsm_riscv_combined/counter` 展示了如何在同一个应用程序中依次使用 ULP FSM 和 ULP RISC-V 协处理器:使用 FSM 从 0 计数到 100,再使用 RISC-V 协处理器从 100 计数到 500。期间,HP 内核保持休眠模式,直到计数完成。 + API 参考 ------------- diff --git a/docs/zh_CN/api-reference/system/ulp.rst b/docs/zh_CN/api-reference/system/ulp.rst index 1bbc0fc405..08c4a8e076 100644 --- a/docs/zh_CN/api-reference/system/ulp.rst +++ b/docs/zh_CN/api-reference/system/ulp.rst @@ -17,6 +17,8 @@ ULP(Ultra Low Power,超低功耗)协处理器可在主 CPU 处于深度睡 - **ULP RISC-V**:基于 RISC-V 架构的协处理器。提供更强的计算能力和灵活性,适合运行用 C 语言编写的复杂应用。ESP32-S2 和 ESP32-S3 支持此类型。 - **ULP LP Core**:基于 RISC-V 架构的增强型协处理器,兼具 **ULP RISC-V** 的优势,并新增扩展内存访问、更广泛的外设访问、调试模块和中断控制器等功能。该处理器甚至可在全系统运行时工作。ESP32-C5、ESP32-C6、ESP32-P4 及后续芯片支持此类型。 + 注意:ESP32-S2、ESP32-S3 等芯片同时支持 **ULP FSM** 和 **ULP RISC-V**。用户可在编译时在 menuconfig 中同时启用二者,并在运行时选择使用其中一种。 + .. toctree:: :maxdepth: 1