docs: update system API-guides for ESP32-C2

pull/9408/head
Marius Vikhammer 2022-07-11 17:11:27 +08:00
rodzic f78d13398e
commit d62421619c
25 zmienionych plików z 141 dodań i 149 usunięć

Wyświetl plik

@ -79,6 +79,10 @@ config SOC_RTC_SLOW_MEM_SUPPORTED
bool
default y
config SOC_RTC_MEM_SUPPORTED
bool
default y
config SOC_I2S_SUPPORTED
bool
default y

Wyświetl plik

@ -77,8 +77,9 @@
#define SOC_EMAC_SUPPORTED 1
#define SOC_ULP_SUPPORTED 1
#define SOC_CCOMP_TIMER_SUPPORTED 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_RTC_SLOW_MEM_SUPPORTED 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_RTC_SLOW_MEM_SUPPORTED 1
#define SOC_RTC_MEM_SUPPORTED 1
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1

Wyświetl plik

@ -59,6 +59,10 @@ config SOC_RTC_FAST_MEM_SUPPORTED
bool
default y
config SOC_RTC_MEM_SUPPORTED
bool
default y
config SOC_I2S_SUPPORTED
bool
default y

Wyświetl plik

@ -36,9 +36,10 @@
#define SOC_XT_WDT_SUPPORTED 1
#define SOC_WIFI_SUPPORTED 1
#define SOC_SUPPORTS_SECURE_DL_MODE 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_EFUSE_HAS_EFUSE_RST_BUG 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_EFUSE_HAS_EFUSE_RST_BUG 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_RTC_MEM_SUPPORTED 1
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1

Wyświetl plik

@ -51,6 +51,10 @@ config SOC_RTC_FAST_MEM_SUPPORTED
bool
default y
config SOC_RTC_MEM_SUPPORTED
bool
default y
config SOC_I2S_SUPPORTED
bool
default y

Wyświetl plik

@ -41,10 +41,11 @@
#define SOC_ESP_NIMBLE_CONTROLLER 1
#define SOC_ASYNC_MEMCPY_SUPPORTED 1
#define SOC_USB_SERIAL_JTAG_SUPPORTED 1
#define SOC_SUPPORTS_SECURE_DL_MODE 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_TEMP_SENSOR_SUPPORTED 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_SUPPORTS_SECURE_DL_MODE 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_TEMP_SENSOR_SUPPORTED 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_RTC_MEM_SUPPORTED 1
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1

Wyświetl plik

@ -75,6 +75,10 @@ config SOC_RTC_SLOW_MEM_SUPPORTED
bool
default y
config SOC_RTC_MEM_SUPPORTED
bool
default y
config SOC_PSRAM_DMA_CAPABLE
bool
default y

Wyświetl plik

@ -52,13 +52,14 @@
#define SOC_ULP_SUPPORTED 1
#define SOC_CCOMP_TIMER_SUPPORTED 1
#define SOC_ASYNC_MEMCPY_SUPPORTED 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_TEMP_SENSOR_SUPPORTED 1
#define SOC_CACHE_SUPPORT_WRAP 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_TEMP_SENSOR_SUPPORTED 1
#define SOC_CACHE_SUPPORT_WRAP 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_RTC_SLOW_MEM_SUPPORTED 1
#define SOC_PSRAM_DMA_CAPABLE 1
#define SOC_XT_WDT_SUPPORTED 1
#define SOC_RTC_MEM_SUPPORTED 1
#define SOC_PSRAM_DMA_CAPABLE 1
#define SOC_XT_WDT_SUPPORTED 1
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1

Wyświetl plik

@ -127,6 +127,10 @@ config SOC_RTC_SLOW_MEM_SUPPORTED
bool
default y
config SOC_RTC_MEM_SUPPORTED
bool
default y
config SOC_PSRAM_DMA_CAPABLE
bool
default y

Wyświetl plik

@ -42,17 +42,18 @@
#define SOC_CCOMP_TIMER_SUPPORTED 1
#define SOC_ASYNC_MEMCPY_SUPPORTED 1
#define SOC_SUPPORTS_SECURE_DL_MODE 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_SDMMC_HOST_SUPPORTED 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_RTC_SLOW_MEM_SUPPORTED 1
#define SOC_PSRAM_DMA_CAPABLE 1
#define SOC_XT_WDT_SUPPORTED 1
#define SOC_EFUSE_KEY_PURPOSE_FIELD 1
#define SOC_SDMMC_HOST_SUPPORTED 1
#define SOC_RTC_FAST_MEM_SUPPORTED 1
#define SOC_RTC_SLOW_MEM_SUPPORTED 1
#define SOC_RTC_MEM_SUPPORTED 1
#define SOC_PSRAM_DMA_CAPABLE 1
#define SOC_XT_WDT_SUPPORTED 1
#define SOC_I2S_SUPPORTED 1
#define SOC_RMT_SUPPORTED 1
#define SOC_SIGMADELTA_SUPPORTED 1
#define SOC_SUPPORT_COEXISTENCE 1
#define SOC_TEMP_SENSOR_SUPPORTED 1
#define SOC_TEMP_SENSOR_SUPPORTED 1
#define SOC_AES_SUPPORTED 1
#define SOC_MPI_SUPPORTED 1
#define SOC_SHA_SUPPORTED 1

Wyświetl plik

@ -104,6 +104,8 @@ SIGMADELTA_DOCS = ['api-reference/peripherals/sigmadelta.rst']
I2S_DOCS = ['api-reference/peripherals/i2s.rst']
RTC_MEM_DOCS = ['api-guides/deep-sleep-stub.rst']
ESP32_DOCS = ['api-reference/system/himem.rst',
'api-guides/romconsole.rst',
'api-reference/system/ipc.rst',
@ -111,7 +113,6 @@ ESP32_DOCS = ['api-reference/system/himem.rst',
'api-reference/peripherals/secure_element.rst',
'api-reference/peripherals/dac.rst',
'hw-reference/esp32/**',
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst'] + FTDI_JTAG_DOCS
@ -122,20 +123,17 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-reference/peripherals/temp_sensor.rst',
'api-reference/system/async_memcpy.rst',
'api-reference/peripherals/touch_element.rst',
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst'] + FTDI_JTAG_DOCS
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
'api-reference/system/ipc.rst',
'api-guides/flash_psram_config.rst',
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst']
# No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
ESP32C3_DOCS = ['hw-reference/esp32c3/**',
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst']
@ -166,6 +164,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
'SOC_TWAI_SUPPORTED':TWAI_DOCS,
'SOC_I2S_SUPPORTED':I2S_DOCS,
'SOC_SIGMADELTA_SUPPORTED':SIGMADELTA_DOCS,
'SOC_RTC_MEM_SUPPORTED': RTC_MEM_DOCS,
'esp32':ESP32_DOCS,
'esp32s2':ESP32S2_DOCS,
'esp32s3':ESP32S3_DOCS,

Wyświetl plik

@ -1,9 +1,3 @@
api-guides/core_dump_internals
api-guides/event-handling
api-guides/performance/speed
api-guides/performance/size
api-guides/performance/ram-usage
api-guides/performance/index
api-guides/jtag-debugging/debugging-examples
api-guides/jtag-debugging/configure-ft2232h-jtag
api-guides/jtag-debugging/tips-and-quirks
@ -14,55 +8,14 @@ api-guides/jtag-debugging/configure-other-jtag
api-guides/jtag-debugging/building-openocd-windows
api-guides/jtag-debugging/index
api-guides/jtag-debugging/configure-builtin-jtag
api-guides/partition-tables
api-guides/ulps2_instruction_set
api-guides/app_trace
api-guides/ulp_macros
api-guides/thread-local-storage
api-guides/ulp
api-guides/error-handling
api-guides/tools/idf-tools
api-guides/tools/idf-component-manager
api-guides/tools/idf-windows-installer
api-guides/tools/idf-monitor
api-guides/tools/idf-docker-image
api-guides/tools/index
api-guides/startup
api-guides/hlinterrupts
api-guides/RF_calibration
api-guides/unit-tests
api-guides/deep-sleep-stub
api-guides/ulp_instruction_set
api-guides/blufi
api-guides/lwip
api-guides/flash_psram_config
api-guides/usb-serial-jtag-console
api-guides/linker-script-generation
api-guides/usb-otg-console
api-guides/wireshark-user-guide
api-guides/bootloader
api-guides/ulp-legacy
api-guides/build-system
api-guides/freertos-smp
api-guides/core_dump
api-guides/inc/external-ram-esp32-notes
api-guides/dfu
api-guides/linux-host-testing
api-guides/esp-ble-mesh/ble-mesh-index
api-guides/esp-ble-mesh/ble-mesh-feature-list
api-guides/esp-ble-mesh/ble-mesh-terminology
api-guides/esp-ble-mesh/ble-mesh-architecture
api-guides/esp-ble-mesh/ble-mesh-faq
api-guides/external-ram
api-guides/ulp-risc-v
api-guides/hardware-abstraction
api-guides/wifi-security
api-guides/openthread
api-guides/unit-tests-legacy
api-guides/fatal-errors
api-guides/memory-types
api-guides/build-system-legacy
api-guides/general-notes
api-reference/api-conventions
api-reference/template
api-reference/provisioning/protocomm
@ -163,15 +116,3 @@ api-reference/protocols/esp_spi_slave_protocol
api-reference/protocols/esp_tls
api-reference/protocols/index
api-reference/protocols/asio
get-started/establish-serial-connection
get-started/macos-setup-scratch
get-started/vscode-setup
get-started/linux-setup-scratch
get-started/eclipse-setup
get-started/windows-setup
get-started/toolchain-setup-scratch
get-started/windows-setup-scratch
get-started/linux-setup
get-started/index
get-started/windows-setup-update
get-started/macos-setup

Wyświetl plik

@ -143,10 +143,12 @@ Options to work around this are:
When Secure Boot V2 is enabled, there is also an absolute binary size limit of {IDF_TARGET_MAX_BOOTLOADER_SIZE} (excluding the 4 KB signature), because the bootloader is first loaded into a fixed size buffer for verification.
Fast boot from Deep Sleep
-------------------------
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
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.
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.
Custom bootloader
-----------------

Wyświetl plik

@ -1,7 +1,7 @@
Core Dump
=========
{IDF_TARGET_ROM_ELF:default="https://dl.espressif.com/dl/esp32_rom.elf", esp32="https://dl.espressif.com/dl/esp32_rom.elf", esp32s2="https://dl.espressif.com/dl/esp32s2_rom.elf", esp32s3="https://dl.espressif.com/dl/esp32s3_rom.elf", esp32c3="https://dl.espressif.com/dl/esp32c3_rev3_rom.elf"}
{IDF_TARGET_ROM_ELF:default="(File for this target is not published yet)", esp32="https://dl.espressif.com/dl/esp32_rom.elf", esp32s2="https://dl.espressif.com/dl/esp32s2_rom.elf", esp32s3="https://dl.espressif.com/dl/esp32s3_rom.elf", esp32c3="https://dl.espressif.com/dl/esp32c3_rev3_rom.elf"}
Overview
--------
@ -37,7 +37,7 @@ There are a number of core dump related configuration options which user can cho
The ELF format contains extended features and allow to save more information about broken tasks and crashed software but it requires more space in the flash memory.
This format of core dump is recommended for new software designs and is flexible enough to extend saved information for future revisions.
The Binary format is kept for compatibility standpoint, it uses less space in the memory to keep data and provides better performance.
The Binary format is kept for compatibility reasons, it uses less space in the memory to keep data and provides better performance.
**Core dump data integrity check (Components -> Core dump -> Core dump data integrity check)**
@ -134,7 +134,7 @@ ROM Functions in Backtraces
It is possible situation that at the moment of crash some tasks or/and crashed task itself have one or more ROM functions in their callstacks.
Since ROM is not part of the program ELF it will be impossible for GDB to parse such callstacks, because it tries to analyse functions' prologues to accomplish that.
In that case callstack printing will be broken with error message at the first ROM function.
To overcome this issue you can use ROM ELF provided by Espressif ({IDF_TARGET_ROM_ELF}) and pass it to 'espcoredump.py'.
To overcome this issue you can use ROM ELF provided by Espressif ({IDF_TARGET_ROM_ELF}) and pass it to ``espcoredump.py``.
Dumping variables on demand
---------------------------
@ -145,9 +145,11 @@ Core dump supports retrieving variable data over GDB by attributing special nota
Supported notations and RAM regions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``COREDUMP_DRAM_ATTR`` places variable into DRAM area which will be included into dump.
* ``COREDUMP_RTC_ATTR`` places variable into RTC area which will be included into dump.
* ``COREDUMP_RTC_FAST_ATTR`` places variable into RTC_FAST area which will be included into dump.
.. list::
* ``COREDUMP_DRAM_ATTR`` places variable into DRAM area which will be included into dump.
:SOC_RTC_FAST_MEM_SUPPORTED or SOC_RTC_SLOW_MEM_SUPPORTED: * ``COREDUMP_RTC_ATTR`` places variable into RTC area which will be included into dump.
:SOC_RTC_FAST_MEM_SUPPORTED: * ``COREDUMP_RTC_FAST_ATTR`` places variable into RTC_FAST area which will be included into dump.
Example
^^^^^^^
@ -190,7 +192,7 @@ Generic command syntax: ``espcoredump.py [options] command [args]``
:Script Options:
--chip {auto,esp32,esp32s2,esp32s3,esp32c3}
--chip {auto,esp32,esp32s2,esp32s3,esp32c2,esp32c3}
Target chip type. Default value is "auto"
--port PORT, -p PORT Serial port device. Either "chip" or "port" need to be specified to determine the port when you have multi-target connected at the same time.

Wyświetl plik

@ -98,7 +98,7 @@ The primary purpose of the LL Layer is to abstract away register field access in
The code snippet above illustrates typical LL functions for a peripheral ``xxx``. LL functions typically have the following characteristics:
- All LL functions are defined as ``static inline`` so that there is minimal overhead when calling these functions due to compiler optimization.
- All LL functions are defined as ``static inline`` so that there is minimal overhead when calling these functions due to compiler optimization. These functions are not guaranteed to be inlined by the compiler, so any LL function that will be called when the cache is disabled (e.g. from an IRAM ISR context) should be marked with ``__attribute__((always_inline))``.
- The first argument should be a pointer to a ``xxx_dev_t`` type. The ``xxx_dev_t`` type is a structure representing the peripheral's registers, thus the first argument is always a pointer to the starting address of the peripheral's registers. Note that in some cases where the peripheral has multiple channels with identical register layouts, ``xxx_dev_t *hw`` may point to the registers of a particular channel instead.
- LL functions should be short and in most cases are deterministic. In other words, the worst case runtime of the LL function can be determined at compile time. Thus, any loops in LL functions should be finite bounded; however, there are currently a few exceptions to this rule.
- LL functions are not thread safe, it is the responsibility of the upper layers (driver layer) to ensure that registers or register fields are not accessed concurrently.
@ -109,7 +109,7 @@ The code snippet above illustrates typical LL functions for a peripheral ``xxx``
HAL (Hardware Abstraction Layer)
--------------------------------
The HAL layer models the operational process of a peripheral as a set of general steps, where each step has an associated function. For each step, the details of a peripheral's register implementation (i.e., which registers need to be set/read) are hidden (abstracted away) by the HAL. By modelling peripheral operation as a set of functional steps, any minor hardware implementation differences of the peripheral between different targets or chip versions can be abstracted away by the HAL (i.e., handled transparently). In other words, the HAL API for a particular peripheral will remain mostly the same across multiple targets/chip versions.
The HAL layer models the operational process of a peripheral as a set of general steps, where each step has an associated function. For each step, the details of a peripheral's register implementation (i.e., which registers need to be set/read) are hidden (abstracted away) by the HAL. By modeling peripheral operation as a set of functional steps, any minor hardware implementation differences of the peripheral between different targets or chip versions can be abstracted away by the HAL (i.e., handled transparently). In other words, the HAL API for a particular peripheral will remain mostly the same across multiple targets/chip versions.
The following HAL function examples are selected from the Watchdog Timer HAL as each function maps to one of the steps in a WDT's operation life cycle, thus illustrating how a HAL abstracts a peripheral's operation into functional steps.

Wyświetl plik

@ -11,7 +11,7 @@ API Guides
bootloader
build-system
core_dump
deep-sleep-stub
:SOC_RTC_MEM_SUPPORTED: deep-sleep-stub
:SOC_USB_OTG_SUPPORTED: dfu
error-handling
:SOC_BT_SUPPORTED: esp-ble-mesh/ble-mesh-index
@ -30,7 +30,7 @@ API Guides
openthread
partition-tables
performance/index
:not esp32c2: RF_calibration
RF_calibration
:esp32: ../security/secure-boot-v1
../security/secure-boot-v2
:SOC_SPIRAM_SUPPORTED: external-ram

Wyświetl plik

@ -7,13 +7,14 @@ Overview
There are several :ref:`memory regions<memory-layout>` where code and data can be placed. Code and read-only data are placed by default in flash, writable data in RAM, etc. However, it is sometimes necessary to change these default placements.
.. only:: SOC_ULP_SUPPORTED
For example, it may be necessary to place:
For example, it may be necessary to place critical code in RAM for performance reasons or to place code in RTC memory for use in a wake stub or the ULP coprocessor.
.. list::
.. only:: not SOC_ULP_SUPPORTED
For example, it may be necessary to place critical code in RAM for performance reasons or to place code in RTC memory for use in a wake stub.
* critical code in RAM for performance reasons.
* executable code in IRAM so that it can be ran while cache is disabled.
:SOC_RTC_MEM_SUPPORTED: * code in RTC memory for use in a wake stub or the ULP coprocessor.
:SOC_ULP_SUPPORTED: * code in RTC memory for use by the ULP coprocessor.
With the linker script generation mechanism, it is possible to specify these placements at the component level within ESP-IDF. The component presents information on how it would like to place its symbols, objects or the entire archive. During build, the information presented by the components are collected, parsed and processed; and the placement rules generated is used to link the app.

Wyświetl plik

@ -123,21 +123,6 @@ If a function is not explicitly placed into :ref:`iram` or RTC memory, it is pla
During :doc:`startup`, the bootloader (which runs from IRAM) configures the MMU flash cache to map the app's instruction code region to the instruction space. Flash accessed via the MMU is cached using some internal SRAM and accessing cached flash data is as fast as accessing other types of internal memory.
RTC FAST memory
^^^^^^^^^^^^^^^
The same region of RTC FAST memory can be accessed as both instruction and data memory. Code which has to run after wake-up from deep sleep mode has to be placed into RTC memory. Please check detailed description in :doc:`deep sleep <deep-sleep-stub>` documentation.
.. only:: esp32
RTC FAST memory can only be accessed by the PRO CPU.
In single core mode, remaining RTC FAST memory is added to the heap unless the option :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access and not DMA capable.
.. only:: not esp32 and not esp32c2
Remaining RTC FAST memory is added to the heap unless the option :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access.
.. _drom:
DROM (data stored in flash)
@ -165,6 +150,24 @@ The ``DRAM_ATTR`` attribute can be used to force constants from DROM into the :r
RTC_NOINIT_ATTR uint32_t rtc_noinit_data;
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
RTC FAST memory
^^^^^^^^^^^^^^^
The same region of RTC FAST memory can be accessed as both instruction and data memory. Code which has to run after wake-up from deep sleep mode has to be placed into RTC memory. Please check detailed description in :doc:`deep sleep <deep-sleep-stub>` documentation.
.. only:: esp32
RTC FAST memory can only be accessed by the PRO CPU.
In single core mode, remaining RTC FAST memory is added to the heap unless the option :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access and not DMA capable.
.. only:: not esp32
Remaining RTC FAST memory is added to the heap unless the option :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access.
DMA Capable Requirement
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Wyświetl plik

@ -361,6 +361,14 @@ Enabling Nano formatting also reduces the stack usage of each function that call
"Nano" formatting doesn't support 64-bit integers, or C99 formatting features. For a full list of restrictions, search for ``--enable-newlib-nano-formatted-io`` in the `Newlib README file`_.
.. only:: esp32c2
.. note::
:ref:`CONFIG_NEWLIB_NANO_FORMAT` is enabled by default on {IDF_TARGET_NAME}
.. _Newlib README file: https://sourceware.org/newlib/README
.. _minimizing_binary_mbedtls:

Wyświetl plik

@ -31,11 +31,13 @@ First stage bootloader
Startup code called from the reset vector determines the boot mode by checking ``GPIO_STRAP_REG`` register for bootstrap pin states. Depending on the reset reason, the following takes place:
1. Reset from deep sleep: if the value in ``RTC_CNTL_STORE6_REG`` is non-zero, and CRC value of RTC memory in ``RTC_CNTL_STORE7_REG`` is valid, use ``RTC_CNTL_STORE6_REG`` as an entry point address and jump immediately to it. If ``RTC_CNTL_STORE6_REG`` is zero, or ``RTC_CNTL_STORE7_REG`` contains invalid CRC, or once the code called via ``RTC_CNTL_STORE6_REG`` returns, proceed with boot as if it was a power-on reset. **Note**: to run customized code at this point, a deep sleep stub mechanism is provided. Please see :doc:`deep sleep <deep-sleep-stub>` documentation for this.
.. list::
2. For power-on reset, software SOC reset, and watchdog SOC reset: check the ``GPIO_STRAP_REG`` register if a custom boot mode (such as UART Download Mode) is requested. If this is the case, this custom loader mode is executed from ROM. Otherwise, proceed with boot as if it was due to software CPU reset. Consult {IDF_TARGET_NAME} datasheet for a description of SoC boot modes and how to execute them.
:SOC_RTC_MEM_SUPPORTED: #. Reset from deep sleep: if the value in ``RTC_CNTL_STORE6_REG`` is non-zero, and CRC value of RTC memory in ``RTC_CNTL_STORE7_REG`` is valid, use ``RTC_CNTL_STORE6_REG`` as an entry point address and jump immediately to it. If ``RTC_CNTL_STORE6_REG`` is zero, or ``RTC_CNTL_STORE7_REG`` contains invalid CRC, or once the code called via ``RTC_CNTL_STORE6_REG`` returns, proceed with boot as if it was a power-on reset. **Note**: to run customized code at this point, a deep sleep stub mechanism is provided. Please see :doc:`deep sleep <deep-sleep-stub>` documentation for this.
3. For software CPU reset and watchdog CPU reset: configure SPI flash based on EFUSE values, and attempt to load the code from flash. This step is described in more detail in the next paragraphs.
#. For power-on reset, software SOC reset, and watchdog SOC reset: check the ``GPIO_STRAP_REG`` register if a custom boot mode (such as UART Download Mode) is requested. If this is the case, this custom loader mode is executed from ROM. Otherwise, proceed with boot as if it was due to software CPU reset. Consult {IDF_TARGET_NAME} datasheet for a description of SoC boot modes and how to execute them.
#. For software CPU reset and watchdog CPU reset: configure SPI flash based on EFUSE values, and attempt to load the code from flash. This step is described in more detail in the next paragraphs.
.. note::

Wyświetl plik

@ -143,10 +143,13 @@ ROM 中的 :ref:`first-stage-bootloader` 从 flash 中读取 :ref:`second-stage-
当启用 Secure Boot V2 时,由于引导加载程序最先加载到固定大小的缓冲区中进行验证,对二进制文件大小的绝对限制为 {IDF_TARGET_MAX_BOOTLOADER_SIZE}(不包括 4 KB 签名)。
从深度睡眠中快速启动
----------------------
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
从深度睡眠中快速启动
----------------------
引导加载程序有 :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` 选项,可以减少从深度睡眠中唤醒的时间(有利于降低功耗)。当 :ref:`CONFIG_SECURE_BOOT` 选项禁用时,该选项可用。由于无需镜像校验,唤醒时间减少。在第一次启动时,引导加载程序将启动的应用程序的地址存储在 RTC FAST 存储器中。而在唤醒过程中,这个地址用于启动而无需任何检查,从而实现了快速加载。
引导加载程序有 :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` 选项,可以减少从深度睡眠中唤醒的时间(有利于降低功耗)。当 :ref:`CONFIG_SECURE_BOOT` 选项禁用时,该选项可用。由于无需镜像校验,唤醒时间减少。在第一次启动时,引导加载程序将启动的应用程序的地址存储在 RTC FAST 存储器中。而在唤醒过程中,这个地址用于启动而无需任何检查,从而实现了快速加载。
自定义引导加载程序
----------------------

Wyświetl plik

@ -11,7 +11,7 @@ API 指南
bootloader
build-system
core_dump
deep-sleep-stub
:SOC_RTC_MEM_SUPPORTED: deep-sleep-stub
:SOC_USB_OTG_SUPPORTED: dfu
error-handling
:SOC_BT_SUPPORTED: esp-ble-mesh/ble-mesh-index
@ -30,7 +30,7 @@ API 指南
openthread
partition-tables
performance/index
:not esp32c2: RF_calibration
RF_calibration
:esp32: ../security/secure-boot-v1
../security/secure-boot-v2
:SOC_SPIRAM_SUPPORTED: external-ram

Wyświetl plik

@ -9,11 +9,11 @@
.. only:: SOC_ULP_SUPPORTED
例如为了提高性能,将关键代码存放到 RAM 中,或者将代码存放到 RTC 存储器中以便在 :doc:`唤醒桩 <deep-sleep-stub>` 和 ULP 协处理器中使用。
例如为了提高性能,将关键代码存放到 RAM 中,或者将代码存放到 RTC 存储器中以便在 wake up stub 和 ULP 协处理器中使用。
.. only:: not SOC_ULP_SUPPORTED
例如为了提高性能,将关键代码存放到 RAM 中,或者将代码存放到 RTC 存储器中以便在 :doc:`唤醒桩 <deep-sleep-stub>` 中使用。
例如为了提高性能,将关键代码存放到 RAM 中,或者将代码存放到 RTC 存储器中以便在wake up stub 中使用。
链接器脚本生成机制可以让用户指定代码和数据在 ESP-IDF 组件中的存放区域。组件包含如何存放符号、目标或完整库的信息。在构建应用程序时,组件中的这些信息会被收集、解析并处理;生成的存放规则用于链接应用程序。

Wyświetl plik

@ -123,20 +123,6 @@ IROM代码从 flash 中运行)
:doc:`启动 <startup>` 过程中,从 IRAM 中运行的引导加载程序配置 MMU flash 缓存,将应用程序的指令代码区域映射到指令空间。通过 MMU 访问的 flash 使用一些内部 SRAM 进行缓存,访问缓存的 flash 数据与访问其他类型的内部存储器一样快。
RTC FAST memoryRTC 快速存储器)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RTC FAST memory 的同一区域既可以作为指令存储器也可以作为数据存储器进行访问。从深度睡眠模式唤醒后必须要运行的代码要放在 RTC 存储器中,更多信息请查阅文档 :doc:`深度睡眠 <deep-sleep-stub>`
.. only:: esp32
RTC FAST memory 只可以被 PRO CPU 访问。
在单核模式下,除非禁用 :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` 选项,否则剩余的 RTC FAST memory 会被添加到堆中。该部分内存可以和 :ref:`DRAM` 互换使用,但是访问速度稍慢,且不具备 DMA 功能。
.. only:: not esp32 and not esp32c2
除非禁用 :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` 选项,否则剩余的 RTC FAST memory 会被添加到堆中。该部分内存可以和 :ref:`DRAM` 互换使用,但是访问速度稍慢一点。
.. _drom:
@ -165,6 +151,24 @@ DROM数据存储在 flash 中)
RTC_NOINIT_ATTR uint32_t rtc_noinit_data;
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
RTC FAST memoryRTC 快速存储器)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RTC FAST memory 的同一区域既可以作为指令存储器也可以作为数据存储器进行访问。从深度睡眠模式唤醒后必须要运行的代码要放在 RTC 存储器中,更多信息请查阅文档 :doc:`深度睡眠 <deep-sleep-stub>`
.. only:: esp32
RTC FAST memory 只可以被 PRO CPU 访问。
在单核模式下,除非禁用 :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` 选项,否则剩余的 RTC FAST memory 会被添加到堆中。该部分内存可以和 :ref:`DRAM` 互换使用,但是访问速度稍慢,且不具备 DMA 功能。
.. only:: not esp32
除非禁用 :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` 选项,否则剩余的 RTC FAST memory 会被添加到堆中。该部分内存可以和 :ref:`DRAM` 互换使用,但是访问速度稍慢一点。
具备 DMA 功能
^^^^^^^^^^^^^^^^^^^

Wyświetl plik

@ -31,11 +31,13 @@
复位向量调用的启动代码会根据 ``GPIO_STRAP_REG`` 寄存器的值来确定 {IDF_TARGET_NAME} 的启动模式,该寄存器保存着复位后 bootstrap 引脚的电平状态。根据不同的复位原因,程序会执行如下操作:
1. 从深度睡眠模式复位:如果 ``RTC_CNTL_STORE6_REG`` 寄存器的值非零,且 ``RTC_CNTL_STORE7_REG`` 寄存器中的 RTC 内存的 CRC 校验值有效,那么程序会使用 ``RTC_CNTL_STORE6_REG`` 寄存器的值作为入口地址,并立即跳转到该地址运行。如果 ``RTC_CNTL_STORE6_REG`` 的值为零,或 ``RTC_CNTL_STORE7_REG`` 中的 CRC 校验值无效,又或通过 ``RTC_CNTL_STORE6_REG`` 调用的代码返回,那么则像上电复位一样继续启动。 **注意**:如果想在这里运行自定义的代码,可以参考 :doc:`深度睡眠 <deep-sleep-stub>` 文档里面介绍的深度睡眠存根机制方法。
.. list::
2. 上电复位、软件 SoC 复位、看门狗 SoC 复位:检查 ``GPIO_STRAP_REG`` 寄存器,判断是否请求自定义启动模式,如 UART 下载模式。如果是ROM 会执行此自定义加载器模式。否则程会像软件 CPU 复位一样继续启动。请参考 {IDF_TARGET_NAME} 技术规格书了解 SoC 启动模式以及具体执行过程。
:SOC_RTC_MEM_SUPPORTED: #. 从深度睡眠模式复位:如果 ``RTC_CNTL_STORE6_REG`` 寄存器的值非零,且 ``RTC_CNTL_STORE7_REG`` 寄存器中的 RTC 内存的 CRC 校验值有效,那么程序会使用 ``RTC_CNTL_STORE6_REG`` 寄存器的值作为入口地址,并立即跳转到该地址运行。如果 ``RTC_CNTL_STORE6_REG`` 的值为零,或 ``RTC_CNTL_STORE7_REG`` 中的 CRC 校验值无效,又或通过 ``RTC_CNTL_STORE6_REG`` 调用的代码返回,那么则像上电复位一样继续启动。 **注意**:如果想在这里运行自定义的代码,可以参考 :doc:`深度睡眠 <deep-sleep-stub>` 文档里面介绍的深度睡眠存根机制方法。
3. 软件 CPU 复位、看门狗 CPU 复位:根据 EFUSE 中的值配置 SPI flash然后尝试从 flash 中加载代码,这部分将会在后面一小节详细介绍。
#. 上电复位、软件 SoC 复位、看门狗 SoC 复位:检查 ``GPIO_STRAP_REG`` 寄存器,判断是否请求自定义启动模式,如 UART 下载模式。如果是ROM 会执行此自定义加载器模式。否则程会像软件 CPU 复位一样继续启动。请参考 {IDF_TARGET_NAME} 技术规格书了解 SoC 启动模式以及具体执行过程。
#. 软件 CPU 复位、看门狗 CPU 复位:根据 EFUSE 中的值配置 SPI flash然后尝试从 flash 中加载代码,这部分将会在后面一小节详细介绍。
.. note::
@ -44,14 +46,14 @@
.. only:: esp32
二级引导程序二进制镜像会从 flash 的 ``0x1000`` 偏移地址处加载。如果正在使用 :doc:`/security/secure-boot-v1`,则 flash 的第一个 4 kB 扇区用于存储安全启动 IV 以及引导程序镜像的摘要,否则不使用该扇区。
.. only:: esp32s2
二级引导程序二进制镜像会从 flash 的 ``0x1000`` 偏移地址处加载。该地址前面的 flash 4 kB 扇区未使用。
.. only:: not (esp32 or esp32s2)
二级引导程序二进制镜像会从 flash 的 `` 0x0`` 偏移地址处加载。
二级引导程序二进制镜像会从 flash 的 `` 0x0`` 偏移地址处加载。
.. TODO: describe application binary image format, describe optional flash configuration commands.
@ -93,7 +95,7 @@
.. note::
通常不需要了解 ESP-IDF 应用程序初始化的所有阶段。如果需要仅从应用程序开发人员的角度了解初始化,请跳至 :ref:`app-main-task`
端口初始化
------------------