alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: Provide CN Translation for four docs in api-guides

Browse Source
This commit is contained in:
shenmengjing 2024-04-19 15:02:22 +08:00 committed by BOT
parent f375125e28
commit acbf7ac735
8 changed files with 925 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/en/api-guides/bluetooth.rst
View File

@ -7,11 +7,11 @@ This document provides an architecture overview of the Bluetooth stack in ESP-ID
.. only:: esp32
{IDF_TARGET_NAME} supports Dual-Mode Bluetooth 4.2 and is certified for Bluetooth 4.2.
{IDF_TARGET_NAME} supports Dual-Mode Bluetooth 4.2 and is certified for Dual-Mode Bluetooth 4.2 and Bluetooth LE 5.0.
.. only:: esp32c3 or esp32s3
{IDF_TARGET_NAME} supports Bluetooth 5.0 (LE) and is certified for Bluetooth LE 5.0.
{IDF_TARGET_NAME} supports Bluetooth 5.0 (LE) and is certified for Bluetooth LE 5.4.
.. only:: esp32c2 or esp32c6 or esp32h2

20
docs/en/api-guides/current-consumption-measurement-modules.rst
View File

@ -1,9 +1,11 @@
Current Consumption Measurement of Modules
==========================================
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_SOC_BOOT_PIN:default="Not updated", esp32="IO0", esp32s2="IO0", esp32s3="IO0", esp32c3="IO9", esp32c2="IO9", "esp32c6"="IO9", "esp32h2"="IO9"}
You may want to know the current consumption of a `module <https://www.espressif.com/en/products/modules>`__ in deep-sleep mode, :doc:`other power-saving modes </api-reference/system/sleep_modes>`, and active mode to develop some applications sensitive to power consumption. This section introduces how to measure the current consumption of a module running such an application.
You may want to know the current consumption of a `module <https://www.espressif.com/en/products/modules>`__ in Deep-sleep mode, :doc:`other power-saving modes </api-reference/system/sleep_modes>`, and Active mode to develop some applications sensitive to power consumption. This section introduces how to measure the current consumption of a module running such an application.
Notes to Measurement
@ -22,7 +24,7 @@ Can We Use a Development Board?
.. only:: esp32c6 or esp32h2
With such development boards, you can measure current consumption of modules in deep-sleep mode by flashing chips with the :example:`deep_sleep <system/deep_sleep>` example. However, you can also measure current of bare modules equipped with {IDF_TARGET_NAME} chip using the following method.
With such development boards, you can measure current consumption of modules in Deep-sleep mode by flashing chips with the :example:`deep_sleep <system/deep_sleep>` example. However, you can also measure current of bare modules equipped with {IDF_TARGET_NAME} chip using the following method.
.. only:: esp32 or esp32s2 or esp32s3 or esp32c2 or esp32c3
@ -32,17 +34,17 @@ Can We Use a Development Board?
How to Choose an Appropriate Ammeter?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the :example:`deep_sleep <system/deep_sleep>` example, the module will be woken up every 20 seconds. In deep-sleep mode, the current in the module is just several microamps (μA), while in active mode, the current is in the order of milliamps (mA). The high dynamic current range makes accurate measurement difficult. Ordinary ammeters cannot dynamically switch the measurement range fast enough.
In the :example:`deep_sleep <system/deep_sleep>` example, the module will be woken up every 20 seconds. In Deep-sleep mode, the current in the module is just several microamps (μA), while in active mode, the current is in the order of milliamps (mA). The high dynamic current range makes accurate measurement difficult. Ordinary ammeters cannot dynamically switch the measurement range fast enough.
Additionally, ordinary ammeters have a relatively high internal resistance, resulting in a significant voltage drop. This may cause the module to enter an unstable state, as it is powered by a voltage smaller than the minimum required voltage supply.
Therefore, an ammeter suitable for measuring current in deep-sleep mode should have low internal resistance and, ideally, switch current ranges dynamically. We recommend two options: the `Joulescope ammeter <https://www.joulescope.com/>`__ and the `Power Profiler Kit II from Nordic <https://www.nordicsemi.com/Products/Development-hardware/Power-Profiler-Kit-2.?lang=en>`__.
Therefore, an ammeter suitable for measuring current in Deep-sleep mode should have low internal resistance and, ideally, switch current ranges dynamically. We recommend two options: the `Joulescope ammeter <https://www.joulescope.com/>`__ and the `Power Profiler Kit II from Nordic <https://www.nordicsemi.com/Products/Development-hardware/Power-Profiler-Kit-2.?lang=en>`__.
Joulescope Ammeter
""""""""""""""""""
The Joulescope ammeter combines high-speed sampling and rapid dynamic current range switching to provide accurate and seamless current and energy measurements, even for devices with rapidly varying current consumption. Joulescope accurately measures electrical current over nine orders of magnitude from amps down to nanoamps. This wide range allows for accurate and precise current measurements for devices. Additionally, Joulescope has a total voltage drop of 25 mV at 1 A, which keeps the module running normally. These two features make Joulescope a perfect option for measuring the module switching between deep-sleep mode and wake-up mode.
The Joulescope ammeter combines high-speed sampling and rapid dynamic current range switching to provide accurate and seamless current and energy measurements, even for devices with rapidly varying current consumption. Joulescope accurately measures electrical current over nine orders of magnitude from amps down to nanoamps. This wide range allows for accurate and precise current measurements for devices. Additionally, Joulescope has a total voltage drop of 25 mV at 1 A, which keeps the module running normally. These two features make Joulescope a perfect option for measuring the module switching between Deep-sleep mode and wake-up mode.
Joulescope has no display screen. You need to connect it to a PC to visualize the current waveforms of the measured module. For specific instructions, please follow the documentation provided by the manufacturer.
@ -50,7 +52,7 @@ Joulescope has no display screen. You need to connect it to a PC to visualize th
Nordic Power Profiler Kit II
""""""""""""""""""""""""""""
The Nordic Power Profiler Kit II has an advanced analog measurement unit with a high dynamic measurement range. This allows for accurate power consumption measurements for the entire range typically seen in low-power embedded applications, all the way from single μAs to 1 A. The resolution varies between 100 nA and 1 mA, depending on the measurement range, and is high enough to detect small spikes often seen in low-power optimized systems.
The Nordic Power Profiler Kit II has an advanced analog measurement unit with a high dynamic measurement range. This allows for accurate power consumption measurements for the entire range typically seen in low-power embedded applications, all the way from several microamps to 1 A. The resolution varies between 100 nA and 1 mA, depending on the measurement range, and is high enough to detect small spikes often seen in low-power optimized systems.
Hardware Connection
@ -113,7 +115,7 @@ Measurement Steps
ESP32-S3-WROOM-1 is used as an example in the measurement, and other modules can be measured similarly. For the specific current consumption of chips in different modes, please refer to the Current Consumption subsection in the corresponding `chip datasheet <https://www.espressif.com/en/support/download/documents/chips?keys=&field_download_document_type_tid%5B%5D=510>`__.
You can refer to the following steps to measure the current in deep-sleep mode.
You can refer to the following steps to measure the current in Deep-sleep mode.
- Connect the aforementioned devices according to the hardware connection.
@ -125,13 +127,13 @@ You can refer to the following steps to measure the current in deep-sleep mode.
.. only:: esp32
For modules with an external resistor on GPIO12 (such as ESP32-WROVER-E/IE), you should call :cpp:func:`rtc_gpio_isolate` before going into deep sleep. This is to isolate the GPIO12 pin from external circuits to further minimize current consumption. Please note, for other modules, you do not have to call this function, otherwise, you may get abnormal results.
For modules with an external resistor on GPIO12 (such as ESP32-WROVER-E/IE), you should call :cpp:func:`rtc_gpio_isolate` before going into Deep-sleep. This is to isolate the GPIO12 pin from external circuits to further minimize current consumption. Please note, for other modules, you do not have to call this function, otherwise, you may get abnormal results.
- By default, the module will be woken up every 20 seconds (you can change the timing by modifying the code of this example). To check if the example runs as expected, you can monitor the module operation by running ``idf.py -p PORT monitor`` (please replace PORT with your serial port name).
- Open the Joulescope software to see the current waveform as shown in the image below.
From the waveforms, you can obtain that the current of the module in deep-sleep mode is 8.14 μA. In addition, you can also see the current of the module in active mode, which is about 23.88 mA. The waveforms also show that the average power consumption during deep-sleep mode is 26.85 μW, and the average power consumption during active mode is 78.32 mW.
From the waveforms, you can obtain that the current of the module in Deep-sleep mode is 8.14 μA. In addition, you can also see the current of the module in active mode, which is about 23.88 mA. The waveforms also show that the average power consumption during Deep-sleep mode is 26.85 μW, and the average power consumption during active mode is 78.32 mW.
.. figure:: /../_static/current_measure_waveform.png
:align: center

22
docs/en/api-guides/deep-sleep-stub.rst
View File

@ -1,16 +1,18 @@
Deep Sleep Wake Stubs
Deep-sleep Wake Stubs
=====================
:link_to_translation:`zh_CN:[中文]`
Introduction
------------
The wakeup time from Deep-sleep mode is much longer, compared to Light-sleep and Modem-sleep modes as ROM and RAM are both powered down in this case, and the CPU needs more time for SPI booting. However, {IDF_TARGET_NAME} supports running a “deep sleep wake stub” when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialization, bootloader, or ESP-IDF code has run.
The wakeup time from Deep-sleep mode is much longer, compared to Light-sleep and Modem-sleep modes as ROM and RAM are both powered down in this case, and the CPU needs more time for SPI booting. However, {IDF_TARGET_NAME} supports running a “Deep-sleep wake stub” when coming out of Deep-sleep. This function runs immediately as soon as the chip wakes up - before any normal initialization, bootloader, or ESP-IDF code has run.
Specifically, after waking up from Deep-sleep mode, {IDF_TARGET_NAME} starts partial initialization. Then RTC fast memory will be validated with CRC. If validation passes, the wake stub code will be executed.
As {IDF_TARGET_NAME} has just woken up from deep sleep, most of the peripherals are in the reset state. The SPI flash has not been mapped. Thus, wake stub code can only call functions implemented in ROM or loaded into RTC fast memory, which retains content during deep sleep.
As {IDF_TARGET_NAME} has just woken up from Deep-sleep, most of the peripherals are in the reset state. The SPI flash has not been mapped. Thus, wake stub code can only call functions implemented in ROM or loaded into RTC fast memory, which retains content during Deep-sleep.
From the above, utilizing the wake stub functionality in an application you can quickly run some code when waking up from Deep-sleep mode, without having to wait for the whole boot-up process. However, the stub size is restricted by the size of RTC fast memory.
From the above, by utilizing the wake stub functionality in an application, you can quickly run some code when waking up from Deep-sleep mode, without having to wait for the whole boot-up process. However, the stub size is restricted by the size of RTC fast memory.
.. only:: SOC_RTC_SLOW_MEM_SUPPORTED
@ -25,9 +27,9 @@ Next we will introduce how to implement the wake stub code in an application.
Implement wake stub
-------------------
The wake stub in esp-idf is realized by the function :cpp:func:`esp_wake_deep_sleep()`. This function is executed whenever the SoC wakes from deep sleep. As this function is weakly-linked to the default function :cpp:func:`esp_default_wake_deep_sleep()`, if your application contains a function with the name ``esp_wake_deep_sleep()``, the default version :cpp:func:`esp_default_wake_deep_sleep()` in esp-idf will be overridden.
The wake stub in esp-idf is realized by the function :cpp:func:`esp_wake_deep_sleep()`. This function is executed whenever the SoC wakes from Deep-sleep. As this function is weakly-linked to the default function :cpp:func:`esp_default_wake_deep_sleep()`, if your application contains a function with the name ``esp_wake_deep_sleep()``, the default version :cpp:func:`esp_default_wake_deep_sleep()` in esp-idf will be overridden.
Please note that implementing the function :cpp:func:`esp_wake_deep_sleep()` in your application is not mandatory for utilizing the deep sleep functionality. It becomes necessary only if you want to introduce certain behavior immediately upon the SoC's wake-up.
Please note that implementing the function :cpp:func:`esp_wake_deep_sleep()` in your application is not mandatory for utilizing the Deep-sleep functionality. It becomes necessary only if you want to introduce certain behavior immediately upon the SoC's wake-up.
When you develop a customized wake stub, the first step it should do is to call the default function :cpp:func:`esp_default_wake_deep_sleep()`.
@ -44,7 +46,7 @@ Implementing the wake stub function in your application includes the following s
Load Wake Stub Code into RTC Fast Memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The wake stub code can only call functions present in ROM or loaded into RTC fast memory. All other RAM locations are unintiailized and contain random data. While the wake stub code can use other RAM areas for temporary storage, the contents of these areas will be overwritten either upon returning to deep sleep mode or upon initiating esp-idf.
The wake stub code can only call functions present in ROM or loaded into RTC fast memory. All other RAM locations are unintiailized and contain random data. While the wake stub code can use other RAM areas for temporary storage, the contents of these areas will be overwritten either upon returning to Deep-sleep mode or upon initiating esp-idf.
Wake stub code is a part of the main esp-idf application. During regular execution of esp-idf, functions can call the wake stub code or access RTC memory, treating them as a regular part of the application.
@ -70,7 +72,7 @@ The second method is preferable when writing longer code segments in RTC fast me
Load Wake Stub Data into RTC memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RTC memory must include read-only data used by the wake stub code. Data in RTC memory is initialized whenever the SoC restarts, except when waking from deep sleep. In such cases, the data retained before entering to deep sleep are kept. Data used by the wake stub code must be resident in RTC memory, i.e. RTC fast memory or in RTC slow memory.
RTC memory must include read-only data used by the wake stub code. Data in RTC memory is initialized whenever the SoC restarts, except when waking from Deep-sleep. In such cases, the data retained before entering to Deep-sleep are kept. Data used by the wake stub code must be resident in RTC memory, i.e. RTC fast memory or in RTC slow memory.
The data can be specified in the following two methods:
@ -143,7 +145,7 @@ However, any string constants used in this way must be declared as arrays and ma
The second approach is advisable when incorporating strings or more complex code segments.
You can enable the Kconfig option :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` to reduce wake-up time. See more information in :doc:`Fast boot from Deep Sleep <bootloader>`.
You can enable the Kconfig option :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` to reduce wake-up time. See more information in :doc:`Fast boot from Deep-sleep <bootloader>`.
All of the above functions are declared in :component_file:`esp_hw_support/include/esp_sleep.h`.
@ -152,6 +154,6 @@ Example
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
ESP-IDF provides an example to show how to implement the deep sleep wake stub.
ESP-IDF provides an example to show how to implement the Deep-sleep wake stub.
- :example:`system/deep_sleep_wake_stub`

176
docs/en/api-guides/flash_psram_config.rst
View File

@ -1,7 +1,9 @@
SPI Flash and External SPI RAM Configuration
============================================
This page is a guide for configuring SPI Flash and external SPI RAM. Supported frequency and mode combination, error handling are also elaborated.
:link_to_translation:`zh_CN:[中文]`
This page is a guide for configuring SPI flash and external SPI RAM. Supported frequency and mode combination, error handling are also elaborated.
Terminology
-----------
@ -24,11 +26,11 @@ Terminology
* - **line mode**
- Number of signals used to transfer data in the data phase of SPI transactions. e.g., for 4-bit-mode, the speed of the data phase would be 4 bit per clock cycle.
* - **FxRx**
- F stands for Flash, R stands for PSRAM, x stands for line mode. e.g., F4R4 stands for an {IDF_TARGET_NAME} with Quad Flash and Quad PSRAM.
- F stands for flash, R stands for PSRAM, x stands for line mode. e.g., F4R4 stands for an {IDF_TARGET_NAME} with Quad flash and Quad PSRAM.
.. note::
On {IDF_TARGET_NAME}, MSPI stands for the SPI0/1. SPI0 and SPI1 share a common SPI bus. The main Flash and PSRAM are connected to the MSPI peripheral. CPU accesses them via Cache.
On {IDF_TARGET_NAME}, MSPI stands for the SPI0/1. SPI0 and SPI1 share a common SPI bus. The main flash and PSRAM are connected to the MSPI peripheral. CPU accesses them via Cache.
.. _flash-psram-configuration:
@ -41,13 +43,13 @@ How to Configure Flash and PSRAM
Configure the Flash
^^^^^^^^^^^^^^^^^^^
The Flash related configurations are under ``Serial flasher config`` menu.
The flash related configurations are under ``Serial flasher config`` menu.
1. Flash type used on the board. For Octal Flash, select :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`. For Quad Flash, uncheck this configuration.
1. Flash type used on the board. For Octal flash, select :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`. For Quad flash, uncheck this configuration.
2. Flash line mode. Select a line mode in :ref:`CONFIG_ESPTOOLPY_FLASHMODE`. The higher the line mode is, the faster the SPI speed is. See terminology above about the line mode.
3. Flash sample mode. Select a sample mode in :ref:`CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE`. DDR mode is faster than SDR mode. See terminology above about SDR and DDR mode.
4. Flash speed. Select a Flash frequency in :ref:`CONFIG_ESPTOOLPY_FLASHFREQ`.
5. Flash size. Flash size, in megabytes. Select a Flash size in :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`.
5. Flash size. Flash size, in megabytes. Select a flash size in :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`.
Configure the PSRAM
^^^^^^^^^^^^^^^^^^^
@ -59,19 +61,19 @@ To enable PSRAM, please enable the :ref:`CONFIG_SPIRAM` under ``Component config
.. note::
Configuration 1 of Flash and PSRAM should be selected according to your actual hardware.
Configuration 1 of flash and PSRAM should be selected according to your actual hardware.
For the reset of the above configurations:
- Flash and PSRAM share the same internal clock.
- Quad Flash only supports STR mode. Octal Flash may support either/both STR/DTR modes under OPI mode, depending on the flash model and the vendor.
- Quad flash only supports STR mode. Octal flash may support either/both STR/DTR modes under OPI mode, depending on the flash model and the vendor.
- Quad PSRAM only supports STR mode, while Octal PSRAM only supports DTR mode.
Therefore, some limitations should be noticed when configuring configuration 2, 3 and 4 of Flash, and configuration 2 of PSRAM. Please refer to :ref:`All Supported Modes and Speeds <flash-psram-combination>`
Therefore, some limitations should be noticed when configuring configuration 2, 3 and 4 of flash, and configuration 2 of PSRAM. Please refer to :ref:`All Supported Modes and Speeds <flash-psram-combination>`.
.. note::
If a board with Octal Flash resets before the second-stage bootloader, please refer to :ref:`Error Handling Chapter <flash-psram-error>`
If a board with Octal flash resets before the second-stage bootloader, please refer to :ref:`Error Handling Chapter <flash-psram-error>`.
.. _flash-psram-combination:
@ -81,7 +83,7 @@ All Supported Modes and Speeds
.. note::
For MSPI DDR mode, the data are sampled on both the positive edge and the negative edge. e.g., if a Flash is set to 80 MHz and DDR mode, then the final speed of the Flash is 160 MHz. This is faster than the Flash setting to 120 Mhz and STR mode.
For MSPI DDR mode, the data are sampled on both the positive edge and the negative edge. e.g., if a flash is set to 80 MHz and DDR mode, then the final speed of the flash is 160 MHz. This is faster than the flash setting to 120 Mhz and STR mode.
.. important::
@ -93,62 +95,128 @@ All Supported Modes and Speeds
Risks:
If your chip powers on at a certain temperature, then after the temperature increases or decreases over 20 celsius degree, the accesses to/from PSRAM/Flash will crash randomly. Flash access crash will lead to program crash.
If your chip powers on at a certain temperature, then after the temperature increases or decreases over 20 celsius degree, the accesses to/from PSRAM/flash will crash randomly. Flash access crash will lead to program crash.
Note 20 celsius degree is not a totally correct number. This value may changes among chips.
F8R8 Hardware
^^^^^^^^^^^^^
======= =============== ======= =============
Group Flash mode Group PSRAM mode
======= =============== ======= =============
A 120 MHz DDR A 120 MHz DDR
A 120 MHz SDR A
B 80 MHz DDR B 80 MHz DDR
C 80 MHz SDR C 40 MHz DDR
C 40 MHz DDR C
C < 40 MHz C
D D disable
======= =============== ======= =============
.. list-table::
:header-rows: 1
:widths: 20 30 20 30
:align: center
1. Flash mode in group A works with PSRAM mode in group A/D
2. Flash mode in group B/C works with PSRAM mode in group B/C/D
* - Group
- Flash mode
- Group
- PSRAM mode
* - A
- 120 MHz DDR
- A
- 120 MHz DDR
* - A
- 120 MHz SDR
- A
-
* - B
- 80 MHz DDR
- B
- 80 MHz DDR
* - C
- 80 MHz SDR
- C
- 40 MHz DDR
* - C
- 40 MHz DDR
- C
-
* - C
- < 40 MHz
- C
-
* - D
-
- D
- disable
1. Flash mode in group A works with PSRAM mode in group A/D.
2. Flash mode in group B/C works with PSRAM mode in group B/C/D.
F4R8 Hardware
^^^^^^^^^^^^^
======= =============== ======= ============
Group Flash mode Group PSRAM mode
======= =============== ======= ============
A 120 MHz SDR A 120 MHz DDR
B 80 MHz SDR B 80 MHz DDR
C 40 MHz SDR C 40 MHz DDR
C 20 MHz SDR C
D D disable
======= =============== ======= ============
.. list-table::
:header-rows: 1
:widths: 20 30 20 30
:align: center
1. Flash mode in group A works with PSRAM mode in group A/D
2. Flash mode in group B/C works with PSRAM mode in group B/C/D
* - Group
- Flash mode
- Group
- PSRAM mode
* - A
- 120 MHz SDR
- A
- 120 MHz DDR
* - B
- 80 MHz SDR
- B
- 80 MHz DDR
* - C
- 40 MHz SDR
- C
- 40 MHz DDR
* - C
- 20 MHz SDR
- C
-
* - D
-
- D
- disable
1. Flash mode in group A works with PSRAM mode in group A/D.
2. Flash mode in group B/C works with PSRAM mode in group B/C/D.
F4R4 Hardware
^^^^^^^^^^^^^
====== =============== ====== ============
Type Flash Type PSRAM
====== =============== ====== ============
A 120 MHz A 120 MHz
B 80 MHz B 80 MHz
C 40 MHz C 40 MHz
C 20 MHz C
D D disable
====== =============== ====== ============
.. list-table::
:header-rows: 1
:widths: 20 30 20 30
:align: center
1. Flash in A works with PSRAM in A/C/D
2. Flash in B works with PSRAM in B/C/D
3. Flash in C works with PSRAM in A/B/C/D
* - Group
- Flash mode
- Group
- PSRAM mode
* - A
- 120 MHz
- A
- 120 MHz
* - B
- 80 MHz
- B
- 80 MHz
* - C
- 40 MHz
- C
- 40 MHz
* - C
- 20 MHz
- C
-
* - D
-
- D
- disable
1. Flash mode in group A works with PSRAM in group A/C/D.
2. Flash mode in group B works with PSRAM in group B/C/D.
3. Flash mode in group C works with PSRAM in group A/B/C/D.
.. _flash-psram-error:
@ -156,7 +224,7 @@ F4R4 Hardware
Error Handling
--------------
1. If a board with Octal Flash resets before the second-stage bootloader:
1. If a board with Octal flash resets before the second-stage bootloader:
.. code-block:: c
@ -171,18 +239,18 @@ Error Handling
this may mean that the necessary efuses are not correctly burnt. Please check the eFuse bits of the chip using command ``espefuse.py summary``.
The ROM bootloader relies on an eFuse bit ``FLASH_TYPE`` to reset the Flash into the default mode (SPI mode). If this bit is not burnt and the flash is working in OPI mode, ROM bootloader may not be able to read from the flash and load the following images.
The ROM bootloader relies on an eFuse bit ``FLASH_TYPE`` to reset the flash into the default mode (SPI mode). If this bit is not burnt and the flash is working in OPI mode, ROM bootloader may not be able to read from the flash and load the following images.
2. If you enabled :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`, and there's an error log saying:
.. code-block:: c
Octal Flash option selected, but EFUSE not configured!
Octal flash option selected, but EFUSE not configured!
this means:
- either you're using a board with a Quad Flash
- or you're using a board with an Octal Flash, but the eFuse bit ``FLASH_TYPE`` isn't burnt. Espressif guarantees this bit is burnt during module manufacturing, but if the module is manufactured by others, this may happen.
- either you're using a board with a Quad flash,
- or you're using a board with an Octal flash, but the eFuse bit ``FLASH_TYPE`` isn't burnt. Espressif guarantees this bit is burnt during module manufacturing, but if the module is manufactured by others, this may happen.
Here is a method to burn the eFuse bit:
@ -193,4 +261,4 @@ Here is a method to burn the eFuse bit:
.. note::
This step is irreversible. Please do check if your hardware is actually using an Octal Flash.
This step is irreversible. Please do check if your hardware is actually using an Octal flash.

202
docs/zh_CN/api-guides/bluetooth.rst
View File

@ -1 +1,201 @@
.. include:: ../../en/api-guides/bluetooth.rst
蓝牙®概述
=========
:link_to_translation:`en:[English]`
此文档概述了 ESP-IDF 中蓝牙协议栈的架构，并提供了一些相关文档和应用示例的快速链接。
.. only:: esp32
{IDF_TARGET_NAME} 支持双模蓝牙 4.2，并且已经获得双模蓝牙 4.2 认证和蓝牙 LE 5.0 认证
.. only:: esp32c3 or esp32s3
{IDF_TARGET_NAME} 支持蓝牙 5.0 (LE)，并且已经获得蓝牙 LE 5.4 认证。
.. only:: esp32c2 or esp32c6 or esp32h2
{IDF_TARGET_NAME} 支持蓝牙 5.0 (LE)，并且已经获得蓝牙 LE 5.3 认证。
ESP-IDF 中的蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME} 系列芯片上实现蓝牙功能，详见下。
.. only:: esp32 or esp32s3 or esp32c3 or esp32c6
.. figure:: ../../_static/bluetooth-architecture.png
:align: center
:scale: 90%
:alt: {IDF_TARGET_NAME} 蓝牙协议栈架构
{IDF_TARGET_NAME} 蓝牙协议栈架构
.. only:: esp32c2
.. figure:: ../../_static/bluetooth-architecture-no-ble-mesh.png
:align: center
:scale: 90%
:alt: {IDF_TARGET_NAME} 蓝牙协议栈架构
{IDF_TARGET_NAME} 蓝牙协议栈架构
.. only:: esp32h2
.. figure:: ../../_static/bluetooth-architecture-no-blufi.png
:align: center
:scale: 90%
:alt: {IDF_TARGET_NAME} 蓝牙协议栈架构
{IDF_TARGET_NAME} 蓝牙协议栈架构
参考下表可知特定芯片是否支持蓝牙模块。
.. list-table::
:width: 100%
:widths: auto
:header-rows: 1
* - 芯片系列
- 控制器
- ESP-Bluedroid
- ESP-NimBLE
- ESP-BLE-MESH
- BluFi
* - ESP32
- Y
- Y
- Y
- Y
- Y
* - ESP32-S2
- \–
- \–
- \–
- \–
- \–
* - ESP32-S3
- Y
- Y
- Y
- Y
- Y
* - ESP32-C2
- Y
- Y
- Y
- \–
- Y
* - ESP32-C3
- Y
- Y
- Y
- Y
- Y
* - ESP32-C6
- Y
- Y
- Y
- Y
- Y
* - ESP32-H2
- Y
- Y
- Y
- Y
- \–
以下各节简要介绍了每个层，并提供了相关文档和应用示例的快速链接。
ESP 蓝牙控制器
--------------
底层为 ESP 蓝牙控制器，包含 PHY、基带、链路控制器、链路管理器、设备管理器和 HCI 等各种模块。该层管理硬件接口和链路，以库的形式提供功能，并通过 API 访问，且直接与硬件和低级别蓝牙协议交互。
- :doc:`API 参考 <../api-reference/bluetooth/controller_vhci>`
- :example:`应用示例 <bluetooth/hci>`
主机
----
有 ESP-Bluedroid 和 ESP-NimBLE 两个主机，其主要区别如下：
- 虽然两者都支持低功耗蓝牙，但 ESP-NimBLE 需要的堆和 flash 空间更少。
.. only:: esp32
- ESP-Bluedroid 支持经典蓝牙和低功耗蓝牙，而 ESP-NimBLE 仅支持低功耗蓝牙。
ESP-Bluedroid
^^^^^^^^^^^^^
ESP-Bluedroid 是原生 Android 蓝牙协议栈 Bluedroid 的修改版，由两层组成：蓝牙上层 (BTU) 和蓝牙传输控制器层 (BTC)。BTU 层负责处理 L2CAP、GATT/ATT、SMP、GAP 等底层蓝牙协议以及其他配置文件，提供以 "bta" 为前缀的接口。BTC 层主要负责向应用层提供以 "esp" 为前缀的支持接口，并处理基于 GATT 的配置文件以及其他任务。所有的 API 都位于 ESP_API 层，开发者应使用以 "esp" 为前缀的蓝牙 API。
.. only:: esp32
{IDF_TARGET_NAME} 的 ESP-Bluedroid 支持经典蓝牙和低功耗蓝牙。
.. only:: not esp32
{IDF_TARGET_NAME} 的 ESP-Bluedroid 仅支持低功耗蓝牙，不支持经典蓝牙。
- API 参考
- :doc:`../api-reference/bluetooth/bt_common`
- :doc:`低功耗蓝牙 <../api-reference/bluetooth/bt_le>`
.. only:: esp32
- :doc:`../api-reference/bluetooth/classic_bt`
- :example:`应用程序示例 <bluetooth/bluedroid>`
ESP-NimBLE
^^^^^^^^^^
ESP-NimBLE 是建立在 Apache Mynewt 开发的 NimBLE 主机协议栈之上的主机协议栈，已经为 {IDF_TARGET_NAME} 系列芯片和 FreeRTOS 进行了移植。通过维持现有 NimBLE API，并添加一个单独的 ESP-NimBLE API 进行初始化，使端口层保持简洁，也便于开发者操作。
ESP-NimBLE 仅支持低功耗蓝牙，不支持经典蓝牙。
- `Apache Mynewt NimBLE 用户指南 <https://mynewt.apache.org/latest/network/index.html>`__
- API 参考
- `NimBLE API 参考 <https://mynewt.apache.org/latest/network/ble_hs/ble_hs.html>`__
- :doc:`ESP-NimBLE 初始化 API 参考 initialization <../api-reference/bluetooth/nimble/index>`
- :example:`应用程序示例 <bluetooth/nimble>`
配置文件
--------
主机协议层之上是 Espressif 的配置文件实现和一些常见的配置文件。根据具体配置，这些配置文件可以在 ESP-Bluedroid 或 ESP-NimBLE 上运行。
.. only:: SOC_BLE_MESH_SUPPORTED
ESP-BLE-MESH
^^^^^^^^^^^^
ESP-BLE-MESH 基于 Zephyr 蓝牙 Mesh 协议栈，其实现支持设备配网和节点控制，还支持代理、中继、低功耗和朋友等节点功能。
- :doc:`ESP-BLE-MESH 文档 <esp-ble-mesh/ble-mesh-index>`：功能列表、快速入门、架构、应用示例描述、常见问题等。
- :example:`应用示例 <bluetooth/esp_ble_mesh>`
.. only:: SOC_BLUFI_SUPPORTED
BluFi
^^^^^
{IDF_TARGET_NAME} 的 BluFi 是通过蓝牙信道进行的 Wi-Fi 网络配置功能。BluFi 提供了将 Wi-Fi 配置和凭据传递给 {IDF_TARGET_NAME} 的安全协议，从而使 {IDF_TARGET_NAME} 连接到 AP 或搭建软 AP。
- :doc:`BluFi 文档 <blufi>`
- :example:`应用示例 <bluetooth/blufi>`
应用
----
最上层是应用层。利用上述 API 和配置文件，可以在 ESP-Bluedroid 和 ESP-NimBLE 协议栈之上创建特定用例的蓝牙应用程序。

155
docs/zh_CN/api-guides/current-consumption-measurement-modules.rst
View File

@ -1 +1,154 @@
.. include:: ../../en/api-guides/current-consumption-measurement-modules.rst
测量模组功耗
============
:link_to_translation:`en:[English]`
{IDF_TARGET_SOC_BOOT_PIN:default="Not updated", esp32="IO0", esp32s2="IO0", esp32s3="IO0", esp32c3="IO9", esp32c2="IO9", "esp32c6"="IO9", "esp32h2"="IO9"}
开发功耗敏感型应用时，需要了解 `模组 <https://www.espressif.com/en/products/modules>`__ 在 Deep-sleep 模式、:doc:`其他节能模式 </api-reference/system/sleep_modes>` 和 Active 模式下的功耗。本节介绍如何测量运行此类应用程序时模组的功耗。
测量注意事项
------------
可以使用开发板进行测量吗？
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. only:: esp32c6
对于 {IDF_TARGET_NAME}，可以使用 `ESP32-C6-DevKitC-1 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32c6/esp32-c6-devkitc-1/index.html>`__ 和 `ESP32-C6-DevKitM-1 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32c6/esp32-c6-devkitm-1/index.html>`__ 等开发板。这些开发板配有排针，可以用来测量模组的功耗。
.. only:: esp32h2
对于 {IDF_TARGET_NAME}，可以使用 `ESP32-H2-DevKitM-1 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32h2/esp32-h2-devkitm-1/index.html>`__ 等开发板。这些开发板配有排针，可以用来测量模组的功耗。
.. only:: esp32c6 or esp32h2
使用上述开发板，可以烧写 :example:`deep_sleep <system/deep_sleep>` 示例来测量模组在 Deep-sleep 模式下的功耗。也可以使用以下方法来测量配有 {IDF_TARGET_NAME} 芯片的裸模组的电流。
.. only:: esp32 or esp32s2 or esp32s3 or esp32c2 or esp32c3
对于 {IDF_TARGET_NAME}，不建议直接使用开发板来测量相应模组的功耗，因为即使烧写 :example:`deep_sleep <system/deep_sleep>` 示例，板上的某些电路仍会产生功耗。因此，在测量模组的电流前需要先切断电源电路。这种方法非常不便，测量成本高。
如何选择合适的电流表？
^^^^^^^^^^^^^^^^^^^^^^
在 :example:`deep_sleep <system/deep_sleep>` 示例中，模组每 20 秒被唤醒一次。在 Deep-sleep 模式下，模组中的电流仅为几微安 (μA)，而在 Active 模式下，电流的量级为毫安 (mA)。普通电流表无法快速动态切换测量范围，因此很难在如此大的动态范围内进行准确测量。
此外，普通电流表的内阻相对较高，压降较大，提供的电压可能会小于模组的最低电压，从而导致模组状态不稳定。
因此，用于测量 Deep-sleep 模式下电流的电流表应具有较小内阻，最好能够动态切换电流范围。我们推荐使用 `Joulescope 电流表 <https://www.joulescope.com/>`__ 和 Nordic 发布的 `Power Profiler Kit II <https://www.nordicsemi.com/Products/Development-hardware/Power-Profiler-Kit-2.?lang=en>`__。
Joulescope 电流表
"""""""""""""""""
Joulescope 电流表既能高速采样，又可以快速切换动态电流范围，即使测量设备的功耗变化很快，也可以准确测量其电流和功耗。Joulescope 可以精确测量从 A 到 nA 共九个数量级的设备电流。此外，Joulescope 在 1 A 时的总压降为 25 mV，可以保证模组正常运行。拥有以上两大特性， Joulescope 是测量模组在 Deep-sleep 模式和 wake-up 模式之间切换时电流的理想选择。
Joulescope 没有显示屏，如果需要查看所测模组的电流波形，请将其连接到计算机。具体请参照制造商提供的文档操作。
Nordic Power Profiler Kit II
""""""""""""""""""""""""""""
Nordic Power Profiler Kit II (PPK2) 具有先进模拟测量单元，动态测量范围大。低功耗嵌入式应用的功耗通常在几微安到 1 A 之间，PPK2 能够准确测量这个范围内的电流。根据测量范围的不同，分辨率在 100 nA 到 1 mA 之间变化。如此精准的分辨率足以检测到低功耗优化系统中常见的小波动。
硬件连接
--------
要测量裸模组的功耗，需要用 `ESP-Prog <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/other/esp-prog/user_guide.html>`__ 来为模组烧写 :example:`deep_sleep <system/deep_sleep>` 示例，并在测量期间为模组供电。此外还需要一个合适的电流表（这里我们使用 Joulescope 电流表），一台计算机，当然还有一个带有必要跳线的裸模组。请参阅以下图示连接硬件。
.. figure:: /../_static/hardware_connection_power_measure.png
:align: center
:scale: 80%
:alt: 硬件连接（点击放大）
硬件连接（点击放大）
请将所测模组的 **UART TX**、 **UART RX**、 **SPI Boot**、 **Enable** 以及 **GND** 管脚与 ESP-Prog 上的相应管脚连接。将 ESP-Prog 上的 **VPROG** 管脚连接到 Joulescope 电流表的 **IN+** 端口，并将 **OUT+** 端口连接到所测模组的 **3.3 V** 管脚。有关不同模组中管脚的具体名称，请参考下面的列表。
.. list-table:: 基于 {IDF_TARGET_NAME} 芯片的模组管脚名称
:header-rows: 1
:widths: 50 50
:align: center
* - 模组管脚功能
- 管脚名称
* - UART TX
- TXD0
* - UART RX
- RXD0
* - SPI Boot
- {IDF_TARGET_SOC_BOOT_PIN}
* - Enable
- EN
* - 供电
- 3V3
* - 接地
- GND
.. only:: esp32
对于基于 ESP32 芯片的模组，UART TX 和 UART RX 管脚也可能是 U0TXD 和 U0RXD。
.. only:: esp32c2
对于基于 ESP32-C2 芯片的模组，UART TX 和 UART RX 管脚也可能是 TXD 和 RXD。
.. only:: esp32c3
对于基于 ESP32-C3 芯片的模组，UART TX 和 UART RX 管脚也可能是 TXD 和 RXD、TX 和 RX 或 TX0 和 RX0。
有关管脚名称的详细信息，请参阅 `模组技术规格书 <https://www.espressif.com/en/support/download/documents/modules>`__。
测量步骤
--------
下面以 ESP32-S3-WROOM-1 为例进行电流测量，其他模组也可参照以下步骤。芯片在不同模式下的具体功耗，请参阅相应 `芯片技术规格书 <https://www.espressif.com/en/support/download/documents/chips?keys=&field_download_document_type_tid%5B%5D=510>`__ 中的功耗章节。
参照以下步骤，可以测量 Deep-sleep 模式下的电流情况。
- 按照硬件连接章节的提示，连接上述设备。
- 将 :example:`deep_sleep <system/deep_sleep>` 示例烧写到模组中。详情请参阅 :doc:`在 Linux 和 macOS 系统中创建工程 </get-started/linux-macos-start-project>` （适用于运行 Linux 或 macOS 系统的计算机），也可以参考 :doc:`在 Windows 系统中创建工程 </get-started/windows-start-project>` （适用于运行 Windows 系统的计算机）。
.. only:: esp32 or esp32s2 or esp32s3
请注意，在运行 ``idf.py menuconfig`` 配置示例时，需要先在 ``Example Configuration`` 中禁用 ``Enable touch wake up``，以降低底电流。
.. only:: esp32
部分模组在 GPIO12 上连接了外部电阻（例如 ESP32-WROVER-E/IE），所以在进入 Deep-sleep 模式之前要调用 :cpp:func:`rtc_gpio_isolate`，将 GPIO12 管脚与外部电路隔离，从而进一步减小功耗。请注意，其他模组并不需要调用此函数，否则可能会显示结果异常。
- 默认情况下，模组每 20 秒唤醒一次（可以通过修改示例的代码来更改定时）。想要检查示例是否按照预期运行，可以运行 ``idf.py -p PORT monitor`` （请用你的串行端口名称替换 PORT）来监视模组的情况。
- 打开 Joulescope 软件查看如下图所示的电流波形。
观察波形可知，模组在 Deep-sleep 模式下的电流为 8.14 μA，在 Active 模式下的电流约为 23.88 mA。此外，Deep-sleep 模式下的平均功耗为 26.85 μW，Active 模式下的平均功耗则为 78.32 mW。
.. figure:: /../_static/current_measure_waveform.png
:align: center
:scale: 100%
:alt: ESP32-S3-WROOM-1 的电流波形（点击放大）
ESP32-S3-WROOM-1 的电流波形（点击放大）
观察下图可知，该模组在一个周期内的总功耗为 6.37 mW。
.. figure:: /../_static/power_measure_waveform.png
:align: center
:scale: 100%
:alt: ESP32-S3-WROOM-1 的功耗（点击放大）
ESP32-S3-WROOM-1 的功耗（点击放大）
通过参考不同模式下的功耗，可以估算应用程序的功耗，从而选择合适的电源。

160
docs/zh_CN/api-guides/deep-sleep-stub.rst
View File

@ -1 +1,159 @@
.. include:: ../../en/api-guides/deep-sleep-stub.rst
Deep-sleep 唤醒存根
===================
:link_to_translation:`en:[English]`
简介
----
与 Light-sleep 和 Modem-sleep 模式相比，Deep-sleep 模式的唤醒时间要长得多，因为在这种情况下 ROM 和 RAM 都被关闭，而 CPU 需要更多时间进行 SPI 引导。不过 {IDF_TARGET_NAME} 支持在退出 Deep-sleep 模式时运行“Deep-sleep 唤醒存根”，此功能在芯片被唤醒后，在任何正常初始化、引导加载程序或 ESP-IDF 代码运行之前会立即运行。
具体来说，从 Deep-sleep 模式中唤醒后，{IDF_TARGET_NAME} 开始部分初始化，然后使用 CRC 对 RTC 快速内存进行验证，如果验证通过，则执行唤醒存根代码。
由于 {IDF_TARGET_NAME} 刚刚从 Deep-sleep 模式唤醒，大多数外设处于复位状态，SPI flash 也未被映射，因此，唤醒存根代码只能调用在 ROM 中实现或加载到 RTC 快速内存中的函数，后者在 Deep-sleep 期间保留内容。
综上所述，通过在应用程序中调用唤醒存根功能，可以在从 Deep-sleep 模式中唤醒时快速运行一些代码，而无需等待整个启动过程。但是，存根大小受 RTC 快速内存大小的限制。
.. only:: SOC_RTC_SLOW_MEM_SUPPORTED
{IDF_TARGET_NAME} 支持 RTC 快速内存和 RTC 慢速内存。唤醒存根代码应加载到 RTC 快速内存中，代码使用的数据应存储到 RTC 快速内存或 RTC 慢速内存中。
.. only:: not SOC_RTC_SLOW_MEM_SUPPORTED
{IDF_TARGET_NAME} 仅支持 RTC 快速内存，唤醒存根代码及其使用的数据应加载到 RTC 快速内存中。
接下来介绍如何在应用程序中实现唤醒存根代码。
唤醒存根的实现
--------------
调用函数 :cpp:func:`esp_wake_deep_sleep()` 可在 esp-idf 中实现唤醒存根。每当 SoC 从 Deep-sleep 中唤醒时，都会执行此函数。此函数与默认函数 :cpp:func:`esp_default_wake_deep_sleep()` 弱链接，因此如果应用程序包含名为 ``esp_wake_deep_sleep()`` 的函数，则会覆盖 esp-idf 中的默认函数。
请注意，如果只想调用 Deep-sleep 功能，则不必在应用程序中实现 :cpp:func:`esp_wake_deep_sleep()` 函数，只有当希望在 SoC 唤醒后立即做一些特殊行为时才需要用到该函数。
在开发自定义的唤醒存根时，首先应调用默认函数 :cpp:func:`esp_default_wake_deep_sleep()`。
此外，如果想在运行时切换不同的唤醒存根，可以调用函数 :cpp:func:`esp_set_deep_sleep_wake_stub()`。
参照以下步骤，可以在应用程序中实现唤醒存根函数：
.. list::
- 将唤醒存根代码加载到 RTC 快速内存中
:SOC_RTC_SLOW_MEM_SUPPORTED: - 将数据加载到 RTC 内存中
:not SOC_RTC_SLOW_MEM_SUPPORTED: - 将数据加载到 RTC 快速内存中
将唤醒存根代码加载到 RTC 快速内存中
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
唤醒存根代码只能调用存放在 ROM 中或加载到 RTC 快速内存中的函数，其他所有 RAM 位置都未初始化，且包含随机数据。虽然唤醒存根代码可以使用其他 RAM 区域进行临时存储，但这些区域的内容在回到 Deep-sleep 模式或启动 esp-idf 时将被覆盖。
唤醒存根代码是主 esp-idf 应用程序的一部分。在 esp-idf 正常运行期间，函数可以像常规程序一样调用唤醒存根代码或访问 RTC 内存。
唤醒存根代码必须驻留在 RTC 快速内存中，这可以通过两种方式实现。
- 使用 ``RTC_IRAM_ATTR`` 属性将 :cpp:func:`esp_wake_deep_sleep()` 函数放到 RTC 快速内存中：
.. code:: c
void RTC_IRAM_ATTR esp_wake_deep_sleep(void) {
esp_default_wake_deep_sleep();
// Add additional functionality here
}
第一种方法适用于简短的代码段或包含“常规”代码和 "RTC" 代码的源文件。
- 将函数 :cpp:func:`esp_wake_deep_sleep()` 放到任何名字以 ``rtc_wake_stub`` 开头的源文件中。以 ``rtc_wake_stub*`` 为名的文件中的内容会由链接器自动放入 RTC 快速内存中。
在 RTC 快速内存中编写较长的代码段时，建议使用第二种方法。
.. only:: SOC_RTC_SLOW_MEM_SUPPORTED
将唤醒存根数据加载到 RTC 内存中
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RTC 内存必须包含唤醒存根代码使用的只读数据。除非是从 Deep-sleep 中唤醒，其他所有 SoC 重新启动时，RTC 内存中的数据会被初始化。从 Deep-sleep 中唤醒时，将保留进入睡眠前存在的数据。唤醒存根代码使用的数据必须驻留在 RTC 内存（RTC 快速内存或 RTC 慢速内存）中。
有两种方法可以指定此数据：
- 使用 ``RTC_DATA_ATTR`` 和 ``RTC_RODATA_ATTR`` 属性分别指定可写和只读数据。
.. code:: c
RTC_DATA_ATTR int wake_count;
void RTC_IRAM_ATTR esp_wake_deep_sleep(void) {
esp_default_wake_deep_sleep();
static RTC_RODATA_ATTR const char fmt_str[] = "Wake count %d\n";
esp_rom_printf(fmt_str, wake_count++);
}
这些数据被存放在 RTC 内存区域中，可以通过名为 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_RTCDATA_IN_FAST_MEM` 的 menuconfig 选项进行配置，且此选项允许为 ULP 程序保留慢速内存区域。在默认选项中，这些数据被放入 RTC 慢速内存中，一旦启用上述选项，标记有 ``RTC_DATA_ATTR`` 和 ``RTC_RODATA_ATTR`` 的数据将被放入 RTC 快速内存中。此选项依赖于 :ref:`CONFIG_FREERTOS_UNICORE` 选项，因为 RTC 快速内存只能由 PRO_CPU 访问。
.. only:: esp32
此选项依赖于 :ref:`CONFIG_FREERTOS_UNICORE` 选项，因为只有 PRO_CPU 才能访问 RTC 快速内存。
``RTC_FAST_ATTR`` 和 ``RTC_SLOW_ATTR`` 属性可分别用于指定被强制放入 RTC 快速内存和 RTC 慢速内存中的数据。对标记为 ``RTC_FAST_ATTR`` 的数据的任何访问都仅由 PRO_CPU 允许。
.. only:: esp32s2 or esp32s3
``RTC_FAST_ATTR`` 和 ``RTC_SLOW_ATTR`` 属性分别可用于指定被强制放入 RTC 快速内存和 RTC 慢速内存中的数据。
.. only:: not SOC_RTC_SLOW_MEM_SUPPORTED
将唤醒存根数据加载到 RTC 快速内存中
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
唤醒存根代码使用的数据必须驻留在 RTC 快速内存中。
有两种方法可以指定此数据：
- 使用 ``RTC_DATA_ATTR`` 和 ``RTC_RODATA_ATTR`` 属性分别指定可写和只读数据。
.. code:: c
RTC_DATA_ATTR int wake_count;
void RTC_IRAM_ATTR esp_wake_deep_sleep(void) {
esp_default_wake_deep_sleep();
static RTC_RODATA_ATTR const char fmt_str[] = "Wake count %d\n";
esp_rom_printf(fmt_str, wake_count++);
}
``RTC_FAST_ATTR`` 和 ``RTC_SLOW_ATTR`` 属性可分别用于指定将被强制放入 RTC 快速内存和 RTC 慢速内存中的数据。但 {IDF_TARGET_NAME} 仅支持 RTC 快速内存，因此上述两个属性都将映射到 RTC 快速内存中。
然而，以这种方式使用的任何字符串常量都必须被声明为数组，且使用 ``RTC_RODATA_ATTR`` 进行标记，如上文例子所示。
- 将数据放到任何名字以 ``rtc_wake_stub`` 开头的源文件中，如示例源文件 :example_file:`system/deep_sleep_wake_stub/main/rtc_wake_stub_example.c`。
.. code:: c
if (s_count >= s_max_count) {
// Reset s_count
s_count = 0;
// Set the default wake stub.
// There is a default version of this function provided in esp-idf.
esp_default_wake_deep_sleep();
// Return from the wake stub function to continue
// booting the firmware.
return;
}
在包含字符串或更复杂的代码段时，建议使用第二种方法。
启用 Kconfig 选项 :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` 可以减少唤醒时间。更多信息请参阅 :doc:`从 Deep-sleep 模式快速启动 <bootloader>`。
上述所有函数在 :component_file:`esp_hw_support/include/esp_sleep.h` 中声明。
示例
----
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
ESP-IDF 提供了一个实现 Deep-sleep 唤醒存根的示例。
- :example:`system/deep_sleep_wake_stub`

265
docs/zh_CN/api-guides/flash_psram_config.rst
View File

@ -1 +1,264 @@
.. include:: ../../en/api-guides/flash_psram_config.rst
SPI Flash 和片外 SPI RAM 配置
=============================
:link_to_translation:`en:[English]`
本文档提供配置 SPI flash 和片外 SPI RAM 的指南，还详细说明了支持的频率和模式组合，以及错误处理。
术语表
------
.. list-table::
:header-rows: 1
:widths: 20 80
:align: center
* - 术语
- 定义
* - **SPI**
- 串行外设接口
* - **MSPI**
- 存储器 SPI 外设，专用于存储器的 SPI 外设
* - **SDR**
- 单倍数据传输速率 (SDR)，也被称为 STR（单次传输速率）
* - **DDR**
- 双倍数据传输速率 (DDR)，也被称为 DTR（双次传输速率）
* - **行模式**
- 在 SPI 事务的数据阶段，用来传输数据的信号数量。例如，4 位模式下，数据阶段的速度为每个时钟周期内加载 4 位数据。
* - **FxRx**
- F 代表 flash，R 代表 PSRAM，x 代表行模式。例如，F4R4 指的是具有四线 flash 和四线 PSRAM 的 {IDF_TARGET_NAME}。
.. note::
在 {IDF_TARGET_NAME}上，MSPI 代表 SPI0/1，SPI0 和 SPI1 共享一个公共 SPI 总线。主 flash 和 PSRAM 连接到 MSPI 外设，CPU 通过 Cache 访问它们。
.. _flash-psram-configuration:
如何配置 Flash 和 PSRAM
-----------------------
运行 ``idf.py menuconfig``，打开配置菜单。
配置 Flash
^^^^^^^^^^
在 ``Serial flasher config`` 菜单下，可以找到 flash 相关的配置。
1. 选择在板上使用的 flash 类型。如果是八线 flash，请选择 :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`；如果是四线 flash，则不必选择此配置。
2. 选择 flash 的行模式。在 :ref:`CONFIG_ESPTOOLPY_FLASHMODE` 中选择行模式，线模式越高，SPI 速度越快。有关行模式的术语，请参阅上述术语表。
3. 选择 flash 的采样模式。在 :ref:`CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE` 中选择采样模式，DDR 模式比 SDR 模式速度更快。有关 SDR 和 DDR 模式的术语，请参阅上述术语表。
4. 选择 flash 的速度。在 :ref:`CONFIG_ESPTOOLPY_FLASHFREQ` 中选择 flash 频率。
5. 选择 flash 的大小。在 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` 中选择 flash 的大小，以兆字节为单位。
配置 PSRAM
^^^^^^^^^^
要启动 PSRAM，请在 ``Component config / Hardware Settings`` 菜单下启用 :ref:`CONFIG_SPIRAM`。在 ``SPI RAM config`` 菜单下可以看到所有与 PSRAM 相关的配置。
1. 选择在板上使用的 PSRAM 类型。在 :ref:`CONFIG_SPIRAM_MODE` 中可以选择四线或八线 PSRAM。
2. 选择 PSRAM 的速度。在 :ref:`CONFIG_SPIRAM_SPEED` 中选择 PSRAM 的频率。
.. note::
应根据实际硬件选择 flash 和 PSRAM 的配置 1。
如果要重置上述配置：
- flash 和 PSRAM 共享相同的内部时钟。
- 四线 flash 仅支持 STR 模式。八线 flash 在 OPI 模式下可能支持 STR/DTR 模式中的一种或两种，具体取决于 flash 的型号和供应商。
- 四线 PSRAM 仅支持 STR 模式，而八线 PSRAM 仅支持 DTR 模式。
因此，在选择 flash 的配置 2、3、4 以及 PSRAM 的配置 2 时，应留意上述限制。更多信息请参阅 :ref:`所有支持的模式和速度 <flash-psram-combination>`。
.. note::
如果配有八线 flash 的开发板在第二阶段引导加载程序之前复位，请参考 :ref:`错误处理章节 <flash-psram-error>`。
.. _flash-psram-combination:
所有支持的模式和速度
--------------------
.. note::
在 MSPI DDR 模式下，数据在正边沿和负边沿都会被采样。例如，将 flash 设置为 80 MHz，DDR 模式，则 flash 的最终速度为 160 MHz，比直接将 flash 设置为 120 MHz，STR 模式更快。
.. important::
120 MHz DDR 模式为实验性功能，仅在启用下述选项时才能实现：
- :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES`
通过上述步骤，就能看到 120 MHz 的选项。
风险：
如果芯片在某个温度下上电，当温度上升或下降超过 20 摄氏度后，访问 PSRAM/flash 或是从 PSRAM/flash 获取数据的操作将随机崩溃，而 flash 访问的崩溃将导致程序崩溃。
请注意，20 摄氏度并不是一个完全准确的数字，这个值在不同芯片间可能会有所不同。
F8R8 硬件
^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 20 30 20 30
:align: center
* - 组别
- Flash 模式
- 组别
- PSRAM 模式
* - A
- 120 MHz DDR
- A
- 120 MHz DDR
* - A
- 120 MHz SDR
- A
-
* - B
- 80 MHz DDR
- B
- 80 MHz DDR
* - C
- 80 MHz SDR
- C
- 40 MHz DDR
* - C
- 40 MHz DDR
- C
-
* - C
- < 40 MHz
- C
-
* - D
-
- D
- 禁用
1. 组别 A 中的 flash 模式与组别 A/D 中的 PSRAM 模式配对。
2. 组别 B/C 中的 flash 模式与组别 B/C/D 中的 PSRAM 模式配对。
F4R8 硬件
^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 20 30 20 30
:align: center
* - 组别
- Flash 模式
- 组别
- PSRAM 模式
* - A
- 120 MHz SDR
- A
- 120 MHz DDR
* - B
- 80 MHz SDR
- B
- 80 MHz DDR
* - C
- 40 MHz SDR
- C
- 40 MHz DDR
* - C
- 20 MHz SDR
- C
-
* - D
-
- D
- 禁用
1. 组别 A 中的 flash 模式与组别 A/D 中的 PSRAM 模式配对。
2. 组别 B/C 中的 flash 模式与组别 B/C/D 中的 PSRAM 模式配对。
F4R4 硬件
^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 20 30 20 30
:align: center
* - 组别
- Flash 模式
- 组别
- PSRAM 模式
* - A
- 120 MHz
- A
- 120 MHz
* - B
- 80 MHz
- B
- 80 MHz
* - C
- 40 MHz
- C
- 40 MHz
* - C
- 20 MHz
- C
-
* - D
-
- D
- disable
1. 组别 A 中的 flash 模式 与组别 A/C/D 的 PSRAM 模式配对。
2. 组别 B 中的 flash 模式 与组别 B/C/D 的 PSRAM 模式配对。
3. 组别 C 中的 flash 模式 与组别 A/B/C/D 的 PSRAM 模式配对。
.. _flash-psram-error:
错误处理
--------
1. 如果配有八线 flash 的开发板在第二阶段引导加载程序之前复位:
.. code-block:: c
ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x7 (TG0WDT_SYS_RST),boot:0x18 (SPI_FAST_FLASH_BOOT)
Saved PC:0x400454d5
SPIWP:0xee
mode:DOUT, clock div:1
load:0x3fcd0108,len:0x171c
ets_loader.c 78
这可能意味着必要的 efuse 未得到正确烧录。请使用命令 ``espefuse.py summary``，检查芯片的 eFuse 位。
ROM 引导加载程序可通过 eFuse 位 ``FLASH_TYPE`` 将 flash 复位为默认模式（SPI 模式）。如果未烧录此位，且 flash 处于 OPI 模式，则 ROM 引导加载程序可能无法从 flash 中读取并加载以下图像。
2. 如果启用 :ref:`CONFIG_ESPTOOLPY_OCT_FLASH` 后出现如下错误日志：
.. code-block:: c
Octal Flash option selected, but EFUSE not configured!
这意味着：
- 要么当前正在使用配有四线 flash 的开发板，
- 要么当前正在使用带有八线 flash 的板，但未烧录 eFuse 位 ``FLASH_TYPE``。乐鑫保证在制造模组时烧录此位，但如果模组由其他公司制造，则可能遇到上述情况。
以下是烧录 eFuse 位的方法：
.. code-block:: python
python3 ./espefuse.py -p /dev/<serial_device> --do-not-confirm burn_efuse FLASH_TYPE 1
.. note::
此步骤不可逆，请确保使用配有八线 flash 的开发板。