mirror of
https://github.com/espressif/esp-idf.git
synced 2025-11-01 23:51:49 +01:00
Docs: Update cn trans api guides (backport v5.1)
This commit is contained in:
Mo Fei Fei
morris
@@ -18,7 +18,7 @@ For a full description of the startup process including the ESP-IDF bootloader,
|
||||
|
||||
.. _bootloader-compatibility:
|
||||
|
||||
Bootloader compatibility
|
||||
Bootloader Compatibility
|
||||
------------------------
|
||||
|
||||
It is recommended to update to newer :doc:`versions of ESP-IDF </versions>`: when they are released. The OTA (over the air) update process can flash new apps in the field but cannot flash a new bootloader. For this reason, the bootloader supports booting apps built from newer versions of ESP-IDF.
|
||||
@@ -59,7 +59,7 @@ The default bootloader log level is "Info". By setting the :ref:`CONFIG_BOOTLOAD
|
||||
|
||||
Reducing bootloader log verbosity can improve the overall project boot time by a small amount.
|
||||
|
||||
Factory reset
|
||||
Factory Reset
|
||||
-------------
|
||||
|
||||
Sometimes it is desirable to have a way for the device to fall back to a known-good state, in case of some problem with an update.
|
||||
@@ -88,11 +88,16 @@ In addition, the following configuration options control the reset condition:
|
||||
|
||||
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
Sometimes an application needs to know if the Factory Reset has occurred. For this purpose, there is a function :cpp:func:`bootloader_common_get_rtc_retain_mem_factory_reset_state`, which returns its status, after reading the status is reset to false. This feature reserves some RTC FAST memory (the same size as the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` feature).
|
||||
If an application needs to know if the factory reset has occurred, users can call the function :cpp:func:`bootloader_common_get_rtc_retain_mem_factory_reset_state`.
|
||||
|
||||
- If the status is read as true, the function will return the status, indicating that the factory reset has occurred. The function then resets the status to false for subsequent factory reset judgement.
|
||||
- If the status is read as false, the function will return the status, indicating that the factory reset has not occurred, or the memory where this status is stored is invalid.
|
||||
|
||||
Note that this feature reserves some RTC FAST memory (the same size as the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` feature).
|
||||
|
||||
.. only:: not SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
Sometimes an application needs to know if the Factory Reset has occurred. The {IDF_TARGET_NAME} chip does not have RTC FAST memory, so there is no API to detect it. Instead, there is a workaround: you need an NVS partition that will be erased by bootloader while Factory Reset (add this partition to :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET`). In this NVS partition, create a "factory_reset_state" token that will be increased in the application. If the "factory_reset_state" is 0 then the factory reset has occurred.
|
||||
Sometimes an application needs to know if the factory reset has occurred. The {IDF_TARGET_NAME} chip does not have RTC FAST memory, so there is no API to detect it. Instead, there is a workaround: you need an NVS partition that will be erased by the bootloader if factory reset occurs (add this partition to :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET`). In this NVS partition, create a "factory_reset_state" token that will be increased in the application. If the "factory_reset_state" is 0 then the factory reset has occurred.
|
||||
|
||||
.. _bootloader_boot_from_test_firmware:
|
||||
|
||||
@@ -132,7 +137,7 @@ By default, the hardware RTC Watchdog timer remains running while the bootloader
|
||||
Bootloader Size
|
||||
---------------
|
||||
|
||||
{IDF_TARGET_MAX_BOOTLOADER_SIZE:default = "64KB (0x10000 bytes)", esp32 = "48KB (0xC000 bytes)"}
|
||||
{IDF_TARGET_MAX_BOOTLOADER_SIZE:default = "64 KB (0x10000 bytes)", esp32 = "48 KB (0xC000 bytes)"}
|
||||
{IDF_TARGET_MAX_PARTITION_TABLE_OFFSET:default = "0x12000", esp32 = "0xE000"}
|
||||
.. Above is calculated as 0x1000 at start of flash + IDF_TARGET_MAX_BOOTLOADER_SIZE + 0x1000 signature sector
|
||||
|
||||
@@ -152,12 +157,12 @@ When Secure Boot V2 is enabled, there is also an absolute binary size limit of {
|
||||
|
||||
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
|
||||
|
||||
Fast boot from Deep Sleep
|
||||
Fast Boot from Deep-Sleep
|
||||
-------------------------
|
||||
|
||||
The bootloader has the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` option which allows the wake-up time from deep sleep to be reduced (useful for reducing power consumption). This option is available when :ref:`CONFIG_SECURE_BOOT` option is disabled. Reduction of time is achieved due to the lack of image verification. During the first boot, the bootloader stores the address of the application being launched in the RTC FAST memory. And during the awakening, this address is used for booting without any checks, thus fast loading is achieved.
|
||||
The bootloader has the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` option which allows the wake-up time from Deep-sleep to be reduced (useful for reducing power consumption). This option is available when :ref:`CONFIG_SECURE_BOOT` option is disabled. Reduction of time is achieved due to the lack of image verification. During the first boot, the bootloader stores the address of the application being launched in the RTC FAST memory. And during the awakening, this address is used for booting without any checks, thus fast loading is achieved.
|
||||
|
||||
Custom bootloader
|
||||
Custom Bootloader
|
||||
-----------------
|
||||
|
||||
The current bootloader implementation allows a project to extend it or modify it. There are two ways of doing it: by implementing hooks or by overriding it. Both ways are presented in :example:`custom_bootloader` folder in ESP-IDF examples:
|
||||
|
||||
@@ -97,7 +97,7 @@ Because some buffers can only be allocated in internal memory, a second configur
|
||||
|
||||
.. _external_ram_config_bss:
|
||||
|
||||
Allow .bss Segment to be Placed in External Memory
|
||||
Allow .bss Segment to Be Placed in External Memory
|
||||
--------------------------------------------------
|
||||
|
||||
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`.
|
||||
@@ -116,7 +116,7 @@ Remaining external RAM can also be added to the capability heap allocator using
|
||||
|
||||
.. _external_ram_config_noinit:
|
||||
|
||||
Allow .noinit Segment to be Placed in External Memory
|
||||
Allow .noinit Segment to Be Placed in External Memory
|
||||
--------------------------------------------------------------
|
||||
|
||||
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY`. If enabled, a region of the address space provided in external RAM will be used to store non-initialized data. The values placed in this segment will not be initialized or modified even during startup or restart.
|
||||
@@ -164,14 +164,14 @@ External RAM use has the following restrictions:
|
||||
|
||||
.. only:: SOC_PSRAM_DMA_CAPABLE and not esp32s3
|
||||
|
||||
* External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Therefore when External RAM is enabled, any buffer that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` and can be freed using a standard ``free()`` call. Note, although {IDF_TARGET_NAME} has hardware support for DMA to / from external RAM, this is not yet supported in ESP-IDF.
|
||||
* External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Therefore when External RAM is enabled, any buffer that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL)`` and can be freed using a standard ``free()`` call. Note, although {IDF_TARGET_NAME} has hardware support for DMA to or from external RAM, this is not yet supported in ESP-IDF.
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
* Although {IDF_TARGET_NAME} has hardware support for DMA to / from external RAM, there are still limitations:
|
||||
* Although {IDF_TARGET_NAME} has hardware support for DMA to or from external RAM, there are still limitations:
|
||||
|
||||
- The bandwidth that DMA accesses external RAM is very limited, especially when CPU is trying to access the external RAM at the same time.
|
||||
- You can configure :ref:`CONFIG_SPIRAM_SPEED` as 120 MHz for an Octal PSRAM. The bandwidth will be improved. However there are still restrictions for this option, see :ref:`All Supported PSRAM Modes and Speeds <flash-psram-combination>` for more details.
|
||||
- You can configure :ref:`CONFIG_SPIRAM_SPEED` as 120 MHz for an octal PSRAM. The bandwidth will be improved. However there are still restrictions for this option. See :ref:`All Supported PSRAM Modes and Speeds <flash-psram-combination>` for more details.
|
||||
|
||||
* External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can "push out" cached flash, possibly making the execution of code slower afterwards.
|
||||
|
||||
@@ -180,7 +180,7 @@ External RAM use has the following restrictions:
|
||||
The option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` can be used to allow placing task stacks into external memory. In these cases :cpp:func:`xTaskCreateStatic` must be used to specify a task stack buffer allocated from external memory, otherwise task stacks will still be allocated from internal memory.
|
||||
|
||||
|
||||
Failure to initialize
|
||||
Failure to Initialize
|
||||
=====================
|
||||
|
||||
By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`.
|
||||
@@ -195,7 +195,7 @@ Failure to initialize
|
||||
Encryption
|
||||
==========
|
||||
|
||||
It is possible to enable automatic encryption for data stored in external RAM. When this is enabled any data read and written through the cache will automatically be encrypted/decrypted by the external memory encryption hardware.
|
||||
It is possible to enable automatic encryption for data stored in external RAM. When this is enabled any data read and written through the cache will automatically be encrypted or decrypted by the external memory encryption hardware.
|
||||
|
||||
This feature is enabled whenever flash encryption is enabled. For more information on how to enable and how it works see :doc:`Flash Encryption </security/flash-encryption>`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user