diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 1ba519de07..93d58549dd 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -13,15 +13,15 @@ This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and d :ref:`jtag-debugging-setup-openocd` Procedure to install OpenOCD and verify that it is installed. :ref:`jtag-debugging-configuring-target` - Configuration of OpenOCD software and set up JTAG adapter hardware that will make together a debugging target. + Configuration of OpenOCD software and setting up of JTAG adapter hardware, which together make up the debugging target. :ref:`jtag-debugging-launching-debugger` Steps to start up a debug session with GDB from :ref:`jtag-debugging-using-debugger-eclipse` and from :ref:`jtag-debugging-using-debugger-command-line`. :ref:`jtag-debugging-examples` If you are not familiar with GDB, check this section for debugging examples provided from :ref:`jtag-debugging-examples-eclipse` as well as from :ref:`jtag-debugging-examples-command-line`. :ref:`jtag-debugging-building-openocd` - Procedure to build OpenOCD from sources for :doc:`Windows `, :doc:`Linux ` and :doc:`MacOS ` operating systems. + Procedure to build OpenOCD from sources for :doc:`Windows `, :doc:`Linux ` and :doc:`macOS ` operating systems. :ref:`jtag-debugging-tips-and-quirks` - This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB. + This section provides collection of tips and quirks related to JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB. .. include:: {IDF_TARGET_PATH_NAME}.inc @@ -36,24 +36,24 @@ Introduction .. only:: esp32 - The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive multithreading, allowing for an intuitive way of writing software. + The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive scheduling, allowing for an intuitive way of writing software. - The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over a debug port. + The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are ``printf()`` statements. A better (and in many cases quicker) way to debug such problems is by using a debugger, connected to the processors over a debug port. -Espressif has ported OpenOCD to support the {IDF_TARGET_NAME} processor and the multicore FreeRTOS, which will be the foundation of most {IDF_TARGET_NAME} apps, and has written some tools to help with features OpenOCD does not support natively. +Espressif has ported OpenOCD to support the {IDF_TARGET_NAME} processor and the multi-core FreeRTOS （which is the foundation of most {IDF_TARGET_NAME} apps). Additionally, some extra tools have been written to provide extra features that OpenOCD does not support natively. -This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems. +This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB under Linux, Windows and macOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems. .. note:: - Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTS. There may be some small differences in what a particular user interface looks like, depending on whether you are using Windows, MacOS or Linux and / or a different release of Eclipse. + Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTS. There may be some small differences in what a particular user interface looks like, depending on whether you are using Windows, macOS or Linux and / or a different release of Eclipse. .. _jtag-debugging-how-it-works: How it Works? ------------- -The key software and hardware to perform debugging of {IDF_TARGET_NAME} with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb debugger, OpenOCD on chip debugger and JTAG adapter connected to {IDF_TARGET_NAME} target. +The key software and hardware components that perform debugging of {IDF_TARGET_NAME} with OpenOCD over JTAG (Joint Test Action Group) interface is presented in the diagram below under the "Debugging With JTAG" label. These components include {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb debugger, OpenOCD on chip debugger, and the JTAG adapter connected to {IDF_TARGET_NAME} target. .. figure:: ../../../_static/jtag-debugging-overview.jpg :align: center @@ -62,27 +62,26 @@ The key software and hardware to perform debugging of {IDF_TARGET_NAME} with Ope JTAG debugging - overview diagram -Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to {IDF_TARGET_NAME}, as well as to provide means to monitor diagnostic messages from {IDF_TARGET_NAME}. +Likewise, the "Application Loading and Monitoring" label indicates the key software and hardware components that allow an application to be compiled, built, and flashed to {IDF_TARGET_NAME}, as well as to provide means to monitor diagnostic messages from {IDF_TARGET_NAME}. -Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse `_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms. +"Debugging With JTAG" and "Application Loading and Monitoring" is integrated under the `Eclipse `_ IDE in order to provide a quick and easy transition between writing/compiling/loading/debugging code. The Eclipse IDE (and the integrated debugging software) is available for Windows, Linux and macOS platforms. .. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED - If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection. + If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the other for UART connection. .. only:: SOC_USB_SERIAL_JTAG_SUPPORTED - The connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the {IDF_TARGET_NAME} chip itself, which provides two USB channels, one for JTAG and one for the USB terminal connection. The USB cable should be connected the D+/D- USB pins of {IDF_TARGET_NAME} and not to the serial RxD/TxD throught an USB-to-UART chip. The proper connection is explained later in subsection :ref:`jtag-debugging-configuring-target`. + The connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the {IDF_TARGET_NAME} chip itself, which provides two USB channels, one for JTAG and the other for the USB terminal connection. The USB cable should be connected to the D+/D- USB pins of {IDF_TARGET_NAME} and not to the serial RxD/TxD through a USB-to-UART chip. The proper connection is explained later in subsection :ref:`jtag-debugging-configuring-target`. .. only:: esp32c3 .. note:: - Debugging through the USB interface implemented in ESP32-C3 requires to have a chip with revision 3 or newer. Please use other debugging options (e.g. with ESP-Prog) for chip revision 1 and 2. The easiest way to determine the chip revision is to look for the `Chip is ESP32-C3 (revision 3)` message near the end of a successful chip flashing done by `idf.py flash`. + Debugging through the USB interface implemented in {IDF_TARGET_NAME} requires to have a chip with revision 3 or newer. Please use other debugging options (e.g. with ESP-Prog) for chip revision 1 and 2. The easiest way to determine the chip revision is to look for the `Chip is ESP32-C3 (revision 3)` message near the end of a successful chip flashing done by `idf.py flash`. Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse. - .. _jtag-debugging-selecting-jtag-adapter: Selecting JTAG Adapter @@ -94,7 +93,7 @@ Selecting JTAG Adapter .. only:: SOC_USB_SERIAL_JTAG_SUPPORTED - The quickest and most convenient way to start with JTAG debugging is through an USB cable connected to the D+/D- USB pins of {IDF_TARGET_NAME}. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. + The quickest and most convenient way to start with JTAG debugging is through a USB cable connected to the D+/D- USB pins of {IDF_TARGET_NAME}. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range. @@ -137,7 +136,7 @@ If any of these steps do not work, please go back to the :ref:`setting up the to Configuring {IDF_TARGET_NAME} Target ------------------------------------- -Once OpenOCD is installed, move to configuring {IDF_TARGET_NAME} target (i.e {IDF_TARGET_NAME} board with JTAG interface). You will do it in the following three steps: +Once OpenOCD is installed, you can proceed to configuring the {IDF_TARGET_NAME} target (i.e {IDF_TARGET_NAME} board with JTAG interface). Configuring the target is split into the following three steps: * Configure and connect JTAG interface * Run OpenOCD @@ -147,7 +146,7 @@ Once OpenOCD is installed, move to configuring {IDF_TARGET_NAME} target (i.e {ID Configure and connect JTAG interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the two cases described below. +This step depends on the JTAG and {IDF_TARGET_NAME} board you are using (see the two cases described below). .. toctree:: :maxdepth: 1 @@ -175,12 +174,11 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se .. note:: - The files provided after ``-f`` above are specific for |run-openocd-device-name|. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`. + The files provided after ``-f`` above are specific for |run-openocd-device-name|. You may need to provide different files depending on the hardware that is used. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`. .. only:: esp32c3 - For example, ``board/esp32c3-ftdi.cfg`` can be used for a custom board with an FT2232H or FT232H chip used for JTAG connection, - or with ESP-Prog. + For example, ``board/esp32c3-ftdi.cfg`` can be used for a custom board with an FT2232H or FT232H chip used for JTAG connection, or with ESP-Prog. .. highlight:: none @@ -190,10 +188,9 @@ You should now see similar output (this log is for |run-openocd-device-name|): :start-after: run-openocd-output :end-before: --- -* If there is an error indicating permission problems, please see the "Permissions delegation" bit in the OpenOCD README file in ``~/esp/openocd-esp32`` directory. -* In case there is an error finding configuration files, e.g. |run-openocd-cfg-file-err|, check ``OPENOCD_SCRIPTS`` environment variable is set correctly. This variable is used by OpenOCD to look for the files specified after ``-f``. See :ref:`jtag-debugging-setup-openocd` section for details. Also check if the file is indeed under provided path. -* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on. - +* If there is an error indicating permission problems, please see section on "Permissions delegation" in the OpenOCD README file located in the ``~/esp/openocd-esp32`` directory. +* In case there is an error in finding the configuration files, e.g. |run-openocd-cfg-file-err|, check if the ``OPENOCD_SCRIPTS`` environment variable is set correctly. This variable is used by OpenOCD to look for the files specified after the ``-f`` option. See :ref:`jtag-debugging-setup-openocd` section for details. Also check if the file is indeed under the provided path. +* If you see JTAG errors (e.g., ``...all ones`` or ``...all zeroes``), please check your JTAG connections, whether other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on correctly. .. _jtag-upload-app-debug: @@ -218,7 +215,7 @@ OpenOCD flashing command ``program_esp`` has the following format: - ``reset`` - Optional. Reset target after programing. - ``exit`` - Optional. Finally exit OpenOCD. -You are now ready to start application debugging. Follow steps described in section below. +You are now ready to start application debugging. Follow the steps described in the section below. .. _jtag-debugging-launching-debugger: @@ -268,7 +265,7 @@ Please refer to separate documents listed below, that describe build process. Windows Linux - MacOS + macOS The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section :ref:`jtag-debugging-setup-openocd`. diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index a33df04d7e..d195388716 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -56,15 +56,18 @@ Power management locks have acquire/release counters. If the lock has been acqui {IDF_TARGET_NAME} supports three types of locks described in the table below. -============================ ====================================================== -Lock Description -============================ ====================================================== -``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For {IDF_TARGET_NAME}, this value can be set to 80 MHz, 160 MHz, or 240 MHz. +.. list-table:: + :header-rows: 1 + :widths: 25 60 -``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is 80 MHz. - -``ESP_PM_NO_LIGHT_SLEEP`` Disables automatic switching to light sleep. -============================ ====================================================== + * - Lock + - Description + * - ``ESP_PM_CPU_FREQ_MAX`` + - Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For {IDF_TARGET_NAME}, this value can be set to 80 MHz, 160 MHz, or 240 MHz. + * - ``ESP_PM_APB_FREQ_MAX`` + - Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is 80 MHz. + * - ``ESP_PM_NO_LIGHT_SLEEP`` + - Disables automatic switching to light sleep. {IDF_TARGET_NAME} Power Management Algorithm --------------------------------------- diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index faf74c79fa..c29b6c719e 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -2,24 +2,24 @@ JTAG 调试 ========= :link_to_translation:`en:[English]` -本文将指导安装 {IDF_TARGET_NAME} 的 OpenOCD 调试环境，并介绍如何使用 GDB 来调试 {IDF_TARGET_NAME} 的应用程序。本文的组织结构如下： +本文将介绍如何安装 {IDF_TARGET_NAME} 的 OpenOCD 调试环境，以及如何使用 GDB 来调试 {IDF_TARGET_NAME} 的应用程序。本文结构如下： :ref:`jtag-debugging-introduction` 介绍本指南主旨。 :ref:`jtag-debugging-how-it-works` - 介绍 {IDF_TARGET_NAME}，JTAG（Joint Test Action Group）接口，OpenOCD 和 GDB 是如何相互连接从而实现 {IDF_TARGET_NAME} 的调试功能。 + 介绍 {IDF_TARGET_NAME}、JTAG（Joint Test Action Group）接口、OpenOCD 和 GDB 如何相互连接，从而实现 {IDF_TARGET_NAME} 的调试功能。 :ref:`jtag-debugging-selecting-jtag-adapter` 介绍有关 JTAG 硬件适配器的选择及参照标准。 :ref:`jtag-debugging-setup-openocd` 介绍如何安装官方预编译好的 OpenOCD 软件包并验证是否安装成功。 :ref:`jtag-debugging-configuring-target` - 介绍如何设置 OpenOCD 软件并安装 JTAG 硬件适配器，这两者共同组成最终的调试目标。 + 介绍如何设置 OpenOCD 软件并安装 JTAG 硬件，两项共同构成调试目标. :ref:`jtag-debugging-launching-debugger` 介绍如何从 :ref:`Eclipse 集成开发环境 ` 和 :ref:`命令行终端 ` 启动 GDB 调试会话。 :ref:`jtag-debugging-examples` - 如果你对 GDB 不太熟悉，本小节会分别针对 :ref:`Eclipse 集成开发环境 ` 和 :ref:`命令行终端 ` 来讲解调试的范例。 + 如果您不熟悉 GDB，请查看此小节以获取 :ref:`Eclipse 集成开发环境 ` 以及 :ref:`命令行终端 ` 提供的调试示例。 :ref:`jtag-debugging-building-openocd` - 介绍如何在 :doc:`Windows `，:doc:`Linux ` 和 :doc:`MacOS ` 操作系统上从源码构建 OpenOCD。 + 介绍如何在 :doc:`Windows `，:doc:`Linux ` 和 :doc:`macOS ` 操作系统上从源码构建 OpenOCD。 :ref:`jtag-debugging-tips-and-quirks` 介绍使用 OpenOCD 和 GDB 通过 JTAG 接口调试 {IDF_TARGET_NAME} 时的注意事项和补充内容。 @@ -36,25 +36,24 @@ JTAG 调试 .. only:: esp32 - ESP32 具有两个强大的 Xtensa 内核，支持多种程序架构。ESP-IDF 自带的 FreeRTOS 操作系统具有多核抢占式多线程的功能，它允许用户以更加直观的方式编写软件。 + ESP32 具有两个强大的 Xtensa 内核，支持多种程序架构。ESP-IDF 自带的 FreeRTOS 操作系统支持多核抢占式调度，允许用户以更加直观的方式编写软件。 + + 与此相对地，由于缺乏合适的工具，简便的编程方式也会给程序的调试带来困难，比如找出由两个线程引起的错误，并且这两个线程在单独的 CPU 核上同时运行，那么仅凭 ``printf`` 语句会花费很长时间来定位该错误。调试此类问题更好(往往也更快)的方法是使用调试器，将其连接到处理器的调试端口。 - 与此相对地，简便的编程方式会给程序的调试带来困难（如果没有合适的工具），比如找出由两个线程引起的错误，并且这两个线程在单独的 CPU 核上同时运行，仅凭 ``printf`` 语句会花费很长的时间来定位到该错误。在大多数情况下，调试此类问题更快的方法是使用调试器，连接到处理器的调试端口。 +乐鑫已完成 OpenOCD 移植，以支持 {IDF_TARGET_NAME} 处理器和多核 FreeRTOS 架构（此作为大多数 {IDF_TARGET_NAME} 应用程序的基础）。此外，乐鑫还提供了一些 OpenOCD 本身并不支持的工具，以进一步丰富调试功能。 -乐鑫已经为 {IDF_TARGET_NAME} 处理器和多核 FreeRTOS 架构移植好了 OpenOCD，它将成为大多数 {IDF_TARGET_NAME} 应用程序的基础。此外，乐鑫还提供了一些 OpenOCD 本身并不支持的工具来进一步丰富调试的功能。 - -本文将指导如何在 Linux，Windows 和 MacOS 环境下为 {IDF_TARGET_NAME} 安装 OpenOCD，并使用 GDB 进行软件调试。除了个别操作系统的安装过程有所差别以外，软件用户界面和使用流程都是一样的。 +本文将介绍如何在 Linux、Windows 和 macOS 环境下为 {IDF_TARGET_NAME} 安装 OpenOCD，并使用 GDB 进行软件调试。除部分安装流程有所不同外，所有操作系统的软件用户界面和使用流程都是相同的。 .. note:: - 本文使用的图片素材来自于 Ubuntu 16.04 LTS 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。 + 本文使用的图片素材来自于 Ubuntu 16.04 LTS 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows、macOS 或 Linux）或不同的 Eclipse 软件版本在用户界面上可能会有细微差别。 .. _jtag-debugging-how-it-works: 工作原理 -------- -通过 JTAG（Joint Test Action Group）接口使用 OpenOCD 调试 {IDF_TARGET_NAME} 时所需要的一些关键的软件和硬件包括 **{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -调试器**，**OpenOCD 片上调试器** 和连接到 **{IDF_TARGET_NAME}** 目标的 **JTAG 适配器**。 +通过 JTAG（Joint Test Action Group）接口使用 OpenOCD 调试 {IDF_TARGET_NAME} 时所需要的关键软件和硬件包括 **{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb 调试器**、**OpenOCD 片上调试器** 和连接到 **{IDF_TARGET_NAME}** 目标的 **JTAG 适配器**，如下图 “Application Loading and Monitoring” 标志所示。 .. figure:: ../../../_static/jtag-debugging-overview_zh.jpg :align: center @@ -63,27 +62,46 @@ JTAG 调试 JTAG 调试 - 概述图 -在 “Application Loading and Monitoring” 下还有另外一组软件和硬件，它们用来编译、构建和烧写应用程序到 {IDF_TARGET_NAME} 上，以及监视来自 {IDF_TARGET_NAME} 的运行诊断信息。 +“Application Loading and Monitoring” 标志显示一组关键的软件和硬件组件，可用于编译、构建和烧写应用程序到 {IDF_TARGET_NAME} 上，以及监视来自 {IDF_TARGET_NAME} 的运行诊断信息。 -`Eclipse `__ 环境集成了 JTAG 调试和应用程序加载、监视的功能，它使得软件从编写、编译、加载到调试的迭代过程变得更加快速而简单。所有的软件均适用于 Windows，Linux 和 MacOS 平台。 +`Eclipse `__ 环境集成了 JTAG 调试和应用程序加载、监视的功能，使得软件从编写、编译、加载到调试的迭代过程变得更加快速简单。Eclipse IDE 及其集成的调试软件均适用于 Windows、Linux 和 macOS 平台。 -如果你使用的是 |devkit-name-with-link|，得益于板载的 FT232H 芯片，PC 和 {IDF_TARGET_NAME} 的连接仅仅需要一根 USB 线即可完成。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。 +.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED + + 若使用 |devkit-name-with-link|，由于其板载 FT232H 芯片，仅需一根 USB 线即可连接 PC 与 {IDF_TARGET_NAME}。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。 -根据用户的喜好，除了使用 Eclipse 集成开发环境，还可以直接在命令行终端运行 `debugger` 和 `idf.py build`。 +.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED + + 仅需一根 USB 线即可高效连接 PC 与 {IDF_TARGET_NAME}，因为 {IDF_TARGET_NAME} 芯片本身提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 USB 终端。应将 USB 线连接到 {IDF_TARGET_NAME} 的 D+/D- USB 管脚，而非通过 USB-UART 芯片连接到串行 RxD/TxD。后文中 :ref:`jtag-debugging-configuring-target` 小节将对此进行解释。 + +.. only:: esp32c3 + + .. note:: + + {IDF_TARGET_NAME} 中的 USB 接口只能用于调试版本 3 或更新版本的芯片，对于版本 1 或 2 的芯片，请使用其他调试板（例如 ESP-Prog）。确定芯片版本最简单的方法是通过 `idf.py flash` 完成芯片烧写，并在底部寻找 `芯片为 ESP32-C3 (版本 3)` 信息。 + +根据用户喜好，除了使用 Eclipse 集成开发环境，还可以直接在命令行终端运行 `debugger` 和 `idf.py build`。 .. _jtag-debugging-selecting-jtag-adapter: 选择 JTAG 适配器 ---------------- -上手 JTAG 最快速便捷的方式是使用 |devkit-name-with-link|，因为它板载了 JTAG 调试接口，无需使用外部的 JTAG 硬件适配器和额外的线缆来连接 JTAG 与 {IDF_TARGET_NAME}。|devkit-name| 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。 +.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED -如果你想使用单独的 JTAG 适配器，请确保其与 {IDF_TARGET_NAME} 的电平电压和 OpenOCD 软件都兼容。{IDF_TARGET_NAME} 使用的是业界标准的 JTAG 接口，它省略了（实际上也并不需要）TRST 信号脚。JTAG 使用的 IO 引脚由 VDD_3P3_RTC 电源引脚供电（通常连接到外部 3.3 V 的电源轨），因此 JTAG 硬件适配器的引脚需要能够在该电压范围内正常工作。 + 上手 JTAG 最快速便捷的方式是使用 |devkit-name-with-link|，因为它板载了 JTAG 调试接口，无需使用外部 JTAG 硬件适配器和额外线缆来连接 JTAG 与 {IDF_TARGET_NAME}。|devkit-name| 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。 -在软件方面，OpenOCD 支持相当多数量的 JTAG 适配器，可以参阅 `OpenOCD 支持的适配器列表 `_ （尽管上面显示的器件不太完整），这个页面还列出了兼容 SWD 接口的适配器，但是请注意，{IDF_TARGET_NAME} 目前并不支持 SWD。此外那些被硬编码为只支持特定产品线的 JTAG 适配器也不能在 {IDF_TARGET_NAME} 上工作，比如用于 STM32 产品家族的 ST-LINK 适配器。 +.. only:: not SOC_USB_SERIAL_JTAG_SUPPORTED -JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 GND。某些 JTAG 适配器还需要 {IDF_TARGET_NAME} 提供一路电源到适配器的某个引脚上（比如 Vtar）用以设置适配器的工作电压。SRST 信号线是可选的，它可以连接到 {IDF_TARGET_NAME} 的 CH_PD 引脚上，尽管目前 OpenOCD 对该信号线的支持还非常有限。 + 上手 JTAG 最快速便捷的方式是将一根 USB 线连接到 {IDF_TARGET_NAME} 的 D+/D- USB 管脚，无需使用外部 JTAG 适配器和额外线缆。 +如果您想使用单独的 JTAG 适配器，请确保其与 {IDF_TARGET_NAME} 的电平电压和 OpenOCD 软件都兼容。{IDF_TARGET_NAME} 使用的是业界标准的 JTAG 接口，它未使用（实际上也并不需要）TRST 信号脚。JTAG 使用的 IO 管脚由 VDD_3P3_RTC 电源管脚供电（通常连接到外部 3.3 V 的电源轨），因此 JTAG 硬件适配器的管脚需要能够在该电压范围内正常工作。 + +在软件方面，OpenOCD 支持相当多数量的 JTAG 适配器，请参阅 `OpenOCD 支持的适配器列表 `_ （请注意这一列表并不完整），其中还列出了兼容 SWD 接口的适配器，但请注意，{IDF_TARGET_NAME} 目前并不支持 SWD。此外，被硬编码为只支持特定产品线的 JTAG 适配器也无法在 {IDF_TARGET_NAME} 上工作，例如仅针对 STM32 系列产品的 ST-LINK 适配器。 + +JTAG 正常工作至少需要连接的信号线有：TDI、TDO、TCK、TMS 和 GND。一些 JTAG 适配器还需要 {IDF_TARGET_NAME} 提供一路电源到适配器的某个管脚上（比如 Vtar），用于设置适配器的工作电压。您也可以选择将 SRST 信号线连接到 {IDF_TARGET_NAME} 的 CH_PD 管脚上，但请注意，目前 OpenOCD 对该信号线提供的支持相当有限。 + +`ESP-Prog `_ 中展示了使用外部电路板进行调试的实例，方法是将其连接到 {IDF_TARGET_NAME} 的 JTAG 管脚上。 .. _jtag-debugging-setup-openocd: @@ -92,33 +110,33 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G .. highlight:: bash -如果你已经按照 :doc:`快速入门 <../../get-started/index>` 一文中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 OpenOCD 已经被默认安装到了你的开发系统中。在 :ref:`设置开发环境 ` 结束后，你应该能够在终端中运行如下 OpenOCD 命令:: +如果您已经按照 :doc:`快速入门 <../../get-started/index>` 完成了 ESP-IDF 及其 CMake 构建系统的安装，那么 OpenOCD 已经被默认安装到了您的开发系统中。在 :ref:`设置开发环境 ` 结束后，您应该能够在终端中运行如下 OpenOCD 命令:: openocd --version .. highlight:: none -终端会输出以下信息（实际版本号可能会比这里列出的更新）:: +终端会输出以下信息（实际版本号可能会更新）:: Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html -你还可以检查 ``OPENOCD_SCRIPTS`` 环境变量的值来确认 OpenOCD 配置文件的路径，Linux 和 macOS 用户可以在终端输入 ``echo $OPENOCD_SCRIPTS``，Windows 用户需要输入 ``echo %OPENOCD_SCRIPTS%``。如果终端打印了有效的路径，则表明 OpenOCD 已经被正确安装。 +您还可以检查 ``OPENOCD_SCRIPTS`` 环境变量的值，以确认 OpenOCD 配置文件的路径，Linux 和 macOS 用户可以在终端输入 ``echo $OPENOCD_SCRIPTS``，Windows 用户需要输入 ``echo %OPENOCD_SCRIPTS%``。如果终端输出了有效路径，则表明您已经正确安装 OpenOCD。 -如果上述步骤没有成功执行，请返回快速入门手册，参考其中 :ref:`设置安装工具 ` 章节的说明。 +如果无法执行上述步骤，请再次阅读快速入门手册，参考 :ref:`设置安装工具 ` 章节。 .. note:: - 另外，我们还可以从源代码编译 OpenOCD 工具，相关详细信息请参阅 :ref:`jtag-debugging-building-openocd` 章节。 + 另外也可以从源代码编译 OpenOCD 工具，详细信息请参阅 :ref:`jtag-debugging-building-openocd` 章节。 .. _jtag-debugging-configuring-target: 配置 {IDF_TARGET_NAME} 目标板 ---------------------------- -安装好 OpenOCD 之后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG 接口的 {IDF_TARGET_NAME} 板），具体可以通过以下三个步骤进行： +OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG 接口的 {IDF_TARGET_NAME} 板），具体分为以下三个步骤： - 配置并连接 JTAG 接口 - 运行 OpenOCD @@ -128,7 +146,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 配置并连接 JTAG 接口 ~~~~~~~~~~~~~~~~~~~~ -此步骤取决于您使用的 JTAG 和 {IDF_TARGET_NAME} 板，请参考以下两种情况。 +此步骤取决于使用的 JTAG 和 {IDF_TARGET_NAME} 板，请参考以下两种情况。 .. toctree:: :maxdepth: 1 @@ -148,7 +166,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G .. highlight:: bash -打开终端，按照快速入门中的指南 :ref:`设置好开发环境 ` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）: +打开终端，按照快速入门指南中的 :ref:`设置好开发环境 ` 章节进行操作，然后运行如下命令，以启动 OpenOCD（该命令适用于 Windows、Linux 和 macOS）: .. include:: {IDF_TARGET_PATH_NAME}.inc :start-after: run-openocd @@ -156,45 +174,48 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G .. note:: - 上述命令中 ``-f`` 选项后跟的配置文件专用于 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 + 上述命令中 ``-f`` 选项后跟的配置文件专用于 |run-openocd-device-name|。基于具体使用的硬件，您可能需要选择不同的配置文件，具体内容请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 + + .. only:: esp32c3 + + 例如，对于带有用于 JTAG 连接的 FT2232H 或 FT232H 芯片的定制板，或带有 ESP-Prog 的定制板，可使用 ``board/esp32c3-ftdi.cfg``。 .. highlight:: none -现在应该可以看到如下输入（此日志来自 |run-openocd-device-name|）: +现在您应该可以看到如下输出（此日志来自 |run-openocd-device-name|）: .. include:: {IDF_TARGET_PATH_NAME}.inc :start-after: run-openocd-output :end-before: --- -- 如果出现指示权限问题的错误，请参阅 ``~/esp/openocd-esp32`` 目录下 OpenOCD README 文件中关于 “Permissions delegation” 的说明。 -- 如果发现配置文件有错误，例如 |run-openocd-cfg-file-err|，请检查 ``-s`` 后面的路径，OpenOCD 会根据此路径来查找 ``-f`` 指定的文件。此外，还需要检查配置文件是否确实位于该路径下。 -- 如果看到 JTAG 错误（输出全是 1 或者全是 0），请检查硬件连接，除了 {IDF_TARGET_NAME} 的引脚之外是否还有其他信号连接到了 JTAG，并查看是否所有器件都已经上电。 - +* 如果出现指示权限问题的错误，请打开 ``~/esp/openocd-esp32`` 目录，参阅 OpenOCD README 文件中关于 “Permissions delegation” 的说明。 +* 如果遇到无法找到配置文件的错误，例如 |run-openocd-cfg-file-err|，请检查 ``OPENOCD_SCRIPTS`` 环境变量是否设置正确，OpenOCD 根据此变量来查找 ``-f`` 指定的文件，详见 :ref:`jtag-debugging-setup-openocd`。此外，还需要检查配置文件是否确实位于该路径下。 +* 如果出现 JTAG 错误（例如输出为 ``...all ones`` 或 ``...all zeroes``），请检查硬件连接是否正确，除了 {IDF_TARGET_NAME} 的管脚之外是否还有其他信号连接到了 JTAG，并查看是否所有器件都已经上电。 .. _jtag-upload-app-debug: 上传待调试的应用程序 ~~~~~~~~~~~~~~~~~~~~ -您可以像往常一样构建并上传 {IDF_TARGET_NAME} 应用程序，具体请参阅 :ref:`get-started-build` 章节。 +按照正常步骤构建并上传 {IDF_TARGET_NAME} 应用程序，具体请参阅 :ref:`get-started-build` 章节。 -除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下: +除此以外，您还可以使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下: .. include:: {IDF_TARGET_PATH_NAME}.inc :start-after: run-openocd-upload :end-before: --- -其中 OpenOCD 的烧写命令 ``program_esp`` 具有以下格式： +其中 OpenOCD 的烧写命令 ``program_esp`` 格式如下： ``program_esp [verify] [reset] [exit]`` - - ``image_file`` - 程序镜像文件存放的路径 - - ``offset`` - 镜像烧写到闪存中的偏移地址 - - ``verify`` - 烧写完成后校验闪存中的内容（可选） - - ``reset`` - 烧写完成后重启目标（可选） - - ``exit`` - 烧写完成后退出 OpenOCD（可选） +- ``image_file`` - 程序镜像文件存放的路径 +- ``offset`` - 镜像烧写到闪存中的偏移地址 +- ``verify`` - 烧写完成后校验闪存中的内容（可选） +- ``reset`` - 烧写完成后重启目标（可选） +- ``exit`` - 烧写完成后退出 OpenOCD（可选） -现在可以进行应用程序的调试了，请按照以下章节中讲解的步骤进行操作。 +现在可以调试应用程序了，请按照以下章节中的步骤进行操作。 .. _jtag-debugging-launching-debugger: @@ -202,14 +223,14 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 启动调试器 ---------- -{IDF_TARGET_NAME} 的工具链中带有 GNU 调试器（简称 GDB） ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb``，它和其它工具链软件存放在同一个 bin 目录下。除了直接在命令行终端中调用并操作 GDB 外，还可以在 IDE (例如 Eclipse，Visual Studio Code 等）中调用它，在图形用户界面的帮助下间接操作 GDB，无需在终端中输入任何命令。 +{IDF_TARGET_NAME} 的工具链中带有 GNU 调试器（简称 GDB），它和其它工具链软件共同存放于 {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb 中。除了直接在命令行终端中调用并操作 GDB 外，也可以在 IDE (例如 Eclipse、Visual Studio Code 等）中进行调用，使用图形用户界面间接操作 GDB，这一方法无需在终端中输入任何命令。 关于以上两种调试器的使用方法，详见以下链接。 * :ref:`jtag-debugging-using-debugger-eclipse` * :ref:`jtag-debugging-using-debugger-command-line` -建议首先检查调试器是否能在 :ref:`命令行终端 ` 下正常工作，然后再转到使用 Eclipse 等 :ref:`集成开发环境 ` 下进行调试工作。 +建议首先检查调试器能否在 :ref:`命令行终端 ` 下正常工作，然后再使用 Eclipse :ref:`集成开发环境 ` 进行调试工作。 .. _jtag-debugging-examples: @@ -217,7 +238,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 调试范例 -------- -本节适用于不熟悉 GDB 的用户，将使用 :example:`get-started/blink` 下简单的应用程序来演示 :ref:`调试会话的工作流程 `，同时会介绍以下常用的调试操作： +本节适用于不熟悉 GDB 的用户，下文将使用 :example:`get-started/blink` 下简单的应用程序来演示 :ref:`调试会话的工作流程 `，同时会介绍以下常用的调试操作： 1. :ref:`jtag-debugging-examples-eclipse-01` 2. :ref:`jtag-debugging-examples-eclipse-02` @@ -227,9 +248,9 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 6. :ref:`jtag-debugging-examples-eclipse-06` 7. :ref:`jtag-debugging-examples-eclipse-07` -此外还会提供 :ref:`在命令行终端进行调试 ` 的案例。 +此外还会提供在 :ref:`在命令行终端进行调试 ` 下使用 GDB 调试的案例。 -在演示之前，请设置好 {IDF_TARGET_NAME} 目标板并加载 :example:`get-started/blink` 至 {IDF_TARGET_NAME} 中。 +在演示之前，请完成 {IDF_TARGET_NAME} 目标板设置并加载 :example:`get-started/blink` 至 {IDF_TARGET_NAME} 中。 .. _jtag-debugging-building-openocd: @@ -237,18 +258,18 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 从源码构建 OpenOCD ------------------ -请参阅以下文档，它们分别介绍了在各大操作系统平台上从源码构建 OpenOCD 的流程。 +以下文档分别介绍了如何在各操作系统平台上从源码构建 OpenOCD。 .. toctree:: :maxdepth: 1 Windows Linux - MacOS + macOS -本文档演示所使用的 OpenOCD 是 :ref:`jtag-debugging-setup-openocd` 章节中介绍的预编译好的二进制发行版。 +本文档在演示中所使用的 OpenOCD 是预编译好的二进制发行版，在 :ref:`jtag-debugging-setup-openocd` 章节中有所介绍。 -如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，这样 OpenOCD 才能找到配置文件。Linux 和 macOS 用户可以执行: +如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，使得 OpenOCD 能够找到配置文件。Linux 和 macOS 用户可以执行: .. code-block:: bash @@ -262,13 +283,13 @@ Windows 用户可以执行: cd %USERPROFILE%\esp\openocd-esp32 set "OPENOCD_SCRIPTS=%CD%\tcl" -运行本地编译的 OpenOCD 的示例如下（Linux 和 macOS 用户）: +针对 Linux 和 macOS 用户，运行本地编译的 OpenOCD 的示例: .. include:: {IDF_TARGET_PATH_NAME}.inc :start-after: run-openocd-src-linux :end-before: --- -Windows 用户: +Windows 用户的示例如下: .. include:: {IDF_TARGET_PATH_NAME}.inc :start-after: run-openocd-src-win @@ -279,7 +300,7 @@ Windows 用户: 注意事项和补充内容 -------------------- -本节列出了本指南中提到的所有注意事项和补充内容的链接。 +本节列出了上文中提到的所有注意事项和补充内容的链接。 .. toctree:: :maxdepth: 2 diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst index 8e770a104b..c3d83a3c87 100644 --- a/docs/zh_CN/api-reference/system/power_management.rst +++ b/docs/zh_CN/api-reference/system/power_management.rst @@ -6,7 +6,7 @@ 概述 -------- -ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，调整外围总线 (APB) 频率、CPU 频率，并使芯片进入 Light-sleep 模式，尽可能减少运行应用程序的功耗。 +ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，调整外围总线 (APB) 频率和 CPU 频率，并使芯片进入 Light-sleep 模式，尽可能减少运行应用程序的功耗。 应用程序组件可以通过创建和获取电源管理锁来控制功耗。 @@ -16,7 +16,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， - RTOS 可以要求 CPU 在有任务准备开始运行时以最高配置频率工作。 - 一些外设可能需要中断才能启用，因此其驱动也会要求禁用 Light-sleep 模式。 -因为请求较高的 APB 频率或 CPU 频率，以及禁用 Light-sleep 模式会增加功耗，请将组件使用的电源管理锁降到最少。 +请求较高的 APB 频率或 CPU 频率以及禁用 Light-sleep 模式会增加功耗，因此请将组件使用的电源管理锁降到最少。 电源管理配置 ------------- @@ -25,20 +25,27 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， 启用电源管理功能将会增加中断延迟。额外延迟与多个因素有关，例如：CPU 频率、单/双核模式、是否需要进行频率切换等。CPU 频率为 240 MHz 且未启用频率调节时，最小额外延迟为 0.2 us；如果启用频率调节，且在中断入口将频率由 40 MHz 调节至 80 MHz，则最大额外延迟为 40 us。 -应用程序可以通过调用 :cpp:func:`esp_pm_configure` 函数启用动态调频 (DFS) 功能和自动 Light-sleep 模式。此函数的参数为 :cpp:class:`esp_pm_config_{IDF_TARGET_PATH_NAME}_t`，定义了频率调节的相关设置。在此参数结构中，需要初始化下面三个字段： +通过调用 :cpp:func:`esp_pm_configure` 函数可以在应用程序中启用动态调频 (DFS) 功能和自动 Light-sleep 模式。此函数的参数 :cpp:class:`esp_pm_config_{IDF_TARGET_PATH_NAME}_t` 定义了频率调节的相关设置。在此参数结构中，需要初始化以下三个字段： - ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ`。 - - ``min_freq_mhz``：最小 CPU 频率 (MHz)，即仅获取 ``ESP_PM_APB_FREQ_MAX`` 锁后所使用的频率。该字段可设置为晶振 (XTAL) 频率值，或者 XTAL 频率值除以整数。注意，10 MHz 是生成 1 MHz 的 REF_TICK 默认时钟所需的最小频率。 - - ``light_sleep_enable``：没有获取任何管理锁时，决定系统是否需要自动进入 Light-sleep 状态 (``true``/``false``)。 -或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 + + 如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 .. note:: - 1. 自动 Light-sleep 模式基于 FreeRTOS Tickless Idle 功能，因此如果在 menuconfig 中没有启用 :ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE` 选项，在请求自动 Light-sleep 时，:cpp:func:`esp_pm_configure` 将会返回 `ESP_ERR_NOT_SUPPORTED` 错误。 - 2. 在 Light-sleep 状态下，外设设有时钟门控，不会产生来自 GPIO 和内部外设的中断。:doc:`sleep_modes` 文档中所提到的唤醒源可用于从 Light-sleep 状态触发唤醒。例如，EXT0 和 EXT1 唤醒源就可以通过 GPIO 唤醒芯片。 + 自动 Light-sleep 模式基于 FreeRTOS Tickless Idle 功能，因此如果在 menuconfig 中没有启用 :ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE` 选项，在请求自动 Light-sleep 时，:cpp:func:`esp_pm_configure` 将会返回 `ESP_ERR_NOT_SUPPORTED` 错误。 + +.. note:: + + Light-sleep 状态下，外设设有时钟门控，不会产生来自 GPIO 和内部外设的中断。:doc:`sleep_modes` 文档中所提到的唤醒源可用于从 Light-sleep 状态触发唤醒。 + +.. only:: SOC_PM_SUPPORT_EXT_WAKEUP + + 例如，EXT0 和 EXT1 唤醒源可以通过 GPIO 唤醒芯片。 + 电源管理锁 ---------------------- @@ -47,24 +54,26 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， 电源管理锁设有获取/释放计数器，如果已多次获取电源管理锁，则需要将电源管理锁释放相同次数以解除限制。 -{IDF_TARGET_NAME} 支持下表中所述的三种电源管理锁。 +{IDF_TARGET_NAME} 支持下表中三种电源管理锁。 -============================ ====================================================== -电源管理锁 描述 -============================ ====================================================== -``ESP_PM_CPU_FREQ_MAX`` 请求使用 :cpp:func:`esp_pm_configure` 将 CPU 频率设置为最大值。{IDF_TARGET_NAME} 可以将该值设置为 80 MHz、160 MHz 或 240 MHz。 +.. list-table:: + :header-rows: 1 + :widths: 25 60 -``ESP_PM_APB_FREQ_MAX`` 请求将 APB 频率设置为最大值，{IDF_TARGET_NAME} 支持的最大频率为 80 MHz。 - -``ESP_PM_NO_LIGHT_SLEEP`` 禁止自动切换至 Light-sleep 模式。 -============================ ====================================================== + * - 电源管理锁 + - 描述 + * - ``ESP_PM_CPU_FREQ_MAX`` + - 请求使用 :cpp:func:`esp_pm_configure` 将 CPU 频率设置为最大值。{IDF_TARGET_NAME} 可以将该值设置为 80 MHz、160 MHz 或 240 MHz。 + * - ``ESP_PM_APB_FREQ_MAX`` + - 请求将 APB 频率设置为最大值，{IDF_TARGET_NAME} 支持的最大频率为 80 MHz。 + * - ``ESP_PM_NO_LIGHT_SLEEP`` + - 禁止自动切换至 Light-sleep 模式。 {IDF_TARGET_NAME} 电源管理算法 -------------------------------- 下表列出了启用动态调频时如何切换 CPU 频率和 APB 频率。您可以使用 :cpp:func:`esp_pm_configure` 或者 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` 指定 CPU 最大频率。 - .. only:: esp32 .. include:: inc/power_management_esp32.rst @@ -73,6 +82,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， .. include:: inc/power_management_esp32s2_and_later.rst + 如果没有获取任何管理锁，调用 :cpp:func:`esp_pm_configure` 将启动 Light-sleep 模式。 Light-sleep 模式持续时间由以下因素决定： - 处于阻塞状态的 FreeRTOS 任务数（有限超时） @@ -80,12 +90,15 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， 您也可以设置 Light-sleep 模式在最近事件（任务解除阻塞，或计时器超时）之前持续多久才唤醒芯片。 +为了跳过不必要的唤醒，可以将 `skip_unhandled_events` 选项设置为 true 来初始化 esp_timer。带有此标志的定时器不会唤醒系统，有助于减少功耗。 + + 动态调频和外设驱动 ------------------------------------------------ 启用动态调频后，APB 频率可在一个 RTOS 滴答周期内多次更改。有些外设不受 APB 频率变更的影响，但有些外设可能会出现问题。例如，Timer Group 外设定时器会继续计数，但定时器计数的速度将随 APB 频率的变更而变更。 -下面的外设不受 APB 频率变更的影响： +以下外设不受 APB 频率变更的影响： - **UART**：如果 REF_TICK 用作时钟源，则 UART 不受 APB 频率变更影响。请查看 :cpp:class:`uart_config_t` 中的 `use_ref_tick`。 - **LEDC**：如果 REF_TICK 用作时钟源，则 LEDC 不受 APB 频率变更影响。请查看 :cpp:func:`ledc_timer_config` 函数。 @@ -100,14 +113,14 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， 启用以下驱动程序时，将占用 ``ESP_PM_APB_FREQ_MAX`` 锁： - .. list:: - **SPI slave**：从调用 :cpp:func:`spi_slave_initialize` 至 :cpp:func:`spi_slave_free` 期间。 - **Ethernet**：从调用 :cpp:func:`esp_eth_driver_install` 至 :cpp:func:`esp_eth_driver_uninstall` 期间。 - **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。 - **TWAI**：从调用 :cpp:func:`twai_driver_install` 至 :cpp:func:`twai_driver_uninstall` 期间。 - :SOC_BT_SUPPORTED: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。 + :SOC_BT_SUPPORTED and esp32: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁，除非将 :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` 选项设置为 “外部 32 kHz 晶振”。 + :SOC_BT_SUPPORTED and esp32c3: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。 以下外设驱动程序无法感知动态调频，应用程序需自己获取/释放管理锁： @@ -118,7 +131,6 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， - Timer group :esp32: - MCPWM - API 参考 -------------