kopia lustrzana https://github.com/espressif/esp-idf
docs: Provide Chinese translation for docs in api-reference/system
renpeiying
rodzic
0171beab7c
commit
69a1a09195
|
|
@ -1,20 +1,22 @@
|
|||
App Image Format
|
||||
================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. _app-image-structures:
|
||||
|
||||
Application Image Structures
|
||||
----------------------------
|
||||
|
||||
An application image consists of the following structures:
|
||||
An application image consists of the following:
|
||||
|
||||
1. The :cpp:type:`esp_image_header_t` structure describes the mode of SPI flash and the count of memory segments.
|
||||
2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in {IDF_TARGET_NAME}'s memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way:
|
||||
|
||||
* offset for 0 Segment = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`).
|
||||
* offset for 1 Segment = offset for 0 Segment + length of 0 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`).
|
||||
* offset for 2 Segment = offset for 1 Segment + length of 1 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`).
|
||||
* ...
|
||||
* offset for 0 Segment = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`)
|
||||
* offset for 1 Segment = offset for 0 Segment + length of 0 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`)
|
||||
* offset for 2 Segment = offset for 1 Segment + length of 1 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`)
|
||||
* ...
|
||||
|
||||
The count of each segment is defined in the ``segment_count`` field that is stored in :cpp:type:`esp_image_header_t`. The count cannot be more than :c:macro:`ESP_IMAGE_MAX_SEGMENTS`.
|
||||
|
||||
|
|
@ -22,48 +24,48 @@ To get the list of your image segments, please run the following command:
|
|||
|
||||
.. code-block::
|
||||
|
||||
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin
|
||||
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin
|
||||
|
||||
.. code-block::
|
||||
|
||||
esptool.py v2.3.1
|
||||
Image version: 1
|
||||
Entry point: 40080ea4
|
||||
13 segments
|
||||
esptool.py v2.3.1
|
||||
Image version: 1
|
||||
Entry point: 40080ea4
|
||||
13 segments
|
||||
|
||||
Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM
|
||||
Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM
|
||||
Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM
|
||||
Segment 4: len 0x028e0 load 0x3ffb0000 file_offs 0x00013d10 DRAM
|
||||
Segment 5: len 0x00000 load 0x3ffb28e0 file_offs 0x000165f8 DRAM
|
||||
Segment 6: len 0x00400 load 0x40080000 file_offs 0x00016600 SOC_IRAM
|
||||
Segment 7: len 0x09600 load 0x40080400 file_offs 0x00016a08 SOC_IRAM
|
||||
Segment 8: len 0x62e4c load 0x400d0018 file_offs 0x00020010 SOC_IROM
|
||||
Segment 9: len 0x06cec load 0x40089a00 file_offs 0x00082e64 SOC_IROM
|
||||
Segment 10: len 0x00000 load 0x400c0000 file_offs 0x00089b58 SOC_RTC_IRAM
|
||||
Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA
|
||||
Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA
|
||||
Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA
|
||||
Checksum: e8 (valid)
|
||||
Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
|
||||
Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM
|
||||
Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM
|
||||
Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM
|
||||
Segment 4: len 0x028e0 load 0x3ffb0000 file_offs 0x00013d10 DRAM
|
||||
Segment 5: len 0x00000 load 0x3ffb28e0 file_offs 0x000165f8 DRAM
|
||||
Segment 6: len 0x00400 load 0x40080000 file_offs 0x00016600 SOC_IRAM
|
||||
Segment 7: len 0x09600 load 0x40080400 file_offs 0x00016a08 SOC_IRAM
|
||||
Segment 8: len 0x62e4c load 0x400d0018 file_offs 0x00020010 SOC_IROM
|
||||
Segment 9: len 0x06cec load 0x40089a00 file_offs 0x00082e64 SOC_IROM
|
||||
Segment 10: len 0x00000 load 0x400c0000 file_offs 0x00089b58 SOC_RTC_IRAM
|
||||
Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA
|
||||
Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA
|
||||
Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA
|
||||
Checksum: e8 (valid)
|
||||
Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
|
||||
|
||||
You can also see the information on segments in the ESP-IDF logs while your application is booting:
|
||||
|
||||
.. code-block::
|
||||
|
||||
I (443) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x13ce0 ( 81120) map
|
||||
I (489) esp_image: segment 1: paddr=0x00033d08 vaddr=0x3ff80000 size=0x00000 ( 0) load
|
||||
I (530) esp_image: segment 2: paddr=0x00033d10 vaddr=0x3ff80000 size=0x00000 ( 0) load
|
||||
I (571) esp_image: segment 3: paddr=0x00033d18 vaddr=0x3ffb0000 size=0x028e0 ( 10464) load
|
||||
I (612) esp_image: segment 4: paddr=0x00036600 vaddr=0x3ffb28e0 size=0x00000 ( 0) load
|
||||
I (654) esp_image: segment 5: paddr=0x00036608 vaddr=0x40080000 size=0x00400 ( 1024) load
|
||||
I (695) esp_image: segment 6: paddr=0x00036a10 vaddr=0x40080400 size=0x09600 ( 38400) load
|
||||
I (737) esp_image: segment 7: paddr=0x00040018 vaddr=0x400d0018 size=0x62e4c (405068) map
|
||||
I (847) esp_image: segment 8: paddr=0x000a2e6c vaddr=0x40089a00 size=0x06cec ( 27884) load
|
||||
I (888) esp_image: segment 9: paddr=0x000a9b60 vaddr=0x400c0000 size=0x00000 ( 0) load
|
||||
I (929) esp_image: segment 10: paddr=0x000a9b68 vaddr=0x50000000 size=0x00004 ( 4) load
|
||||
I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
I (443) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x13ce0 ( 81120) map
|
||||
I (489) esp_image: segment 1: paddr=0x00033d08 vaddr=0x3ff80000 size=0x00000 ( 0) load
|
||||
I (530) esp_image: segment 2: paddr=0x00033d10 vaddr=0x3ff80000 size=0x00000 ( 0) load
|
||||
I (571) esp_image: segment 3: paddr=0x00033d18 vaddr=0x3ffb0000 size=0x028e0 ( 10464) load
|
||||
I (612) esp_image: segment 4: paddr=0x00036600 vaddr=0x3ffb28e0 size=0x00000 ( 0) load
|
||||
I (654) esp_image: segment 5: paddr=0x00036608 vaddr=0x40080000 size=0x00400 ( 1024) load
|
||||
I (695) esp_image: segment 6: paddr=0x00036a10 vaddr=0x40080400 size=0x09600 ( 38400) load
|
||||
I (737) esp_image: segment 7: paddr=0x00040018 vaddr=0x400d0018 size=0x62e4c (405068) map
|
||||
I (847) esp_image: segment 8: paddr=0x000a2e6c vaddr=0x40089a00 size=0x06cec ( 27884) load
|
||||
I (888) esp_image: segment 9: paddr=0x000a9b60 vaddr=0x400c0000 size=0x00000 ( 0) load
|
||||
I (929) esp_image: segment 10: paddr=0x000a9b68 vaddr=0x50000000 size=0x00004 ( 4) load
|
||||
I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
|
|
@ -77,10 +79,10 @@ You can also see the information on segments in the ESP-IDF logs while your appl
|
|||
4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of the SHA256 hash is calculated on the range from the first byte and up to this field. The length of this field is 32 bytes.
|
||||
5. If the option :ref:`CONFIG_SECURE_SIGNED_APPS_SCHEME` is set to ECDSA then the application image will have an additional 68 bytes for an ECDSA signature, which includes:
|
||||
|
||||
* version word (4 bytes),
|
||||
* signature data (64 bytes).
|
||||
* version word (4 bytes)
|
||||
* signature data (64 bytes)
|
||||
|
||||
6. If the option :ref:`CONFIG_SECURE_SIGNED_APPS_SCHEME` is set to RSA or ECDSA (V2) then the application image will have an additional signature sector of 4K size. For more details on the format of this signature sector, please refer to :ref:`signature-block-format`.
|
||||
6. If the option :ref:`CONFIG_SECURE_SIGNED_APPS_SCHEME` is set to RSA or ECDSA (V2) then the application image will have an additional signature sector of that is 4K bytes in size. For more details on the format of this signature sector, please refer to :ref:`signature-block-format`.
|
||||
|
||||
.. _app-image-format-application-description:
|
||||
|
||||
|
|
@ -89,15 +91,15 @@ Application Description
|
|||
|
||||
The ``DROM`` segment of the application binary starts with the :cpp:type:`esp_app_desc_t` structure which carries specific fields describing the application:
|
||||
|
||||
* ``magic_word`` - the magic word for the esp_app_desc structure.
|
||||
* ``secure_version`` - see :doc:`Anti-rollback </api-reference/system/ota>`.
|
||||
* ``version`` - see :doc:`App version </api-reference/system/misc_system_api>`. ``*``
|
||||
* ``project_name`` is filled from ``PROJECT_NAME``. ``*``
|
||||
* ``time`` and ``date`` - compile time and date.
|
||||
* ``idf_ver`` - version of ESP-IDF. ``*``
|
||||
* ``app_elf_sha256`` - contains sha256 hash for the application ELF file.
|
||||
* ``magic_word``: the magic word for the :cpp:type:`esp_app_desc_t` structure
|
||||
* ``secure_version``: see :doc:`Anti-rollback </api-reference/system/ota>`
|
||||
* ``version``: see :doc:`App version </api-reference/system/misc_system_api>` [#f1]_
|
||||
* ``project_name``: filled from ``PROJECT_NAME`` [#f1]_
|
||||
* ``time`` and ``date``: compile time and date
|
||||
* ``idf_ver``: version of ESP-IDF [#f1]_
|
||||
* ``app_elf_sha256``: contains SHA256 hash for the application ELF file
|
||||
|
||||
``*`` - The maximum length is 32 characters, including null-termination character. For example, if the length of ``PROJECT_NAME`` exceeds 31 characters, the excess characters will be disregarded.
|
||||
.. [#f1] The maximum length is 32 characters, including null-termination character. For example, if the length of ``PROJECT_NAME`` exceeds 31 characters, the excess characters will be disregarded.
|
||||
|
||||
This structure is useful for identification of images uploaded via Over-the-Air (OTA) updates because it has a fixed offset = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`). As soon as a device receives the first fragment containing this structure, it has all the information to determine whether the update should be continued with or not.
|
||||
|
||||
|
|
@ -115,7 +117,7 @@ The following pattern can be used to add a custom structure to your image:
|
|||
|
||||
.. code-block:: c
|
||||
|
||||
const __attribute__((section(".rodata_custom_desc"))) esp_custom_app_desc_t custom_app_desc = { ... }
|
||||
const __attribute__((section(".rodata_custom_desc"))) esp_custom_app_desc_t custom_app_desc = { ... }
|
||||
|
||||
Offset for custom structure is sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`) + sizeof(:cpp:type:`esp_app_desc_t`).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,20 +1,21 @@
|
|||
Application Level Tracing
|
||||
=========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP-IDF provides a useful feature for program behavior analysis called **Application Level Tracing**. The feature can be enabled in menuconfig and allows transfer of arbitrary data between the host and {IDF_TARGET_NAME} via JTAG interface with minimal overhead on program execution.
|
||||
ESP-IDF provides a useful feature for application behavior analysis called **Application Level Tracing**. The feature can be enabled in menuconfig and allows transfer of arbitrary data between the host and {IDF_TARGET_NAME} via JTAG interface with minimal overhead on program execution.
|
||||
|
||||
Developers can use this library to send application specific state of execution to the host and receive commands or other type of information in the opposite direction at runtime. The main use cases of this library are:
|
||||
Developers can use this library to send application specific state of execution to the host, and receive commands or other types of information in the opposite direction at runtime. The main use cases of this library are:
|
||||
|
||||
1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing`
|
||||
2. Lightweight logging to the host, see :ref:`app_trace-logging-to-host`
|
||||
3. System behaviour analysis, see :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`
|
||||
1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing`.
|
||||
2. Lightweight logging to the host, see :ref:`app_trace-logging-to-host`.
|
||||
3. System behaviour analysis, see :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_app_trace.inc
|
||||
.. include-build-file:: inc/esp_sysview_trace.inc
|
||||
|
||||
.. include-build-file:: inc/esp_sysview_trace.inc
|
||||
|
|
@ -1,16 +1,21 @@
|
|||
The Himem Allocation API
|
||||
========================
|
||||
Himem
|
||||
=====
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ESP32 can access external SPI RAM transparently, so you can use it as normal memory in your program code. However, because the address space for external memory is limited in size, only the first 4 MiB can be used as such. Access to the remaining memory is still possible, however this needs to go through a bankswitching scheme controlled by the himem API.
|
||||
For external memories that are <= 4 MiB, the MMU is configured to use a "unity mapping", meaning that each CPU address is mapped 1-to-1 to the external SPI RAM address, thus allowing external memory to be accessed transparently. However, because the address space for external memory is limited to 4 MiB, only SPI RAM chips that are <= 4 MiB in size can be used fully transparently.
|
||||
|
||||
Specifically, what is implemented by the himem API is a bankswitching scheme. Hardware-wise, the 4 MiB region for external SPI RAM is mapped into the CPU address space by a MMU, which maps a configurable 32 K bank/page of external SPI RAM into each of the 32 K pages in the 4 MiB region accessed by the CPU. For external memories that are <= 4 MiB, this MMU is configured to unity mapping, effectively mapping each CPU address 1-to-1 to the external SPI RAM address.
|
||||
It is still possible for ESP32 to use SPI RAM chips >= 4 MiB in size. However, the memory on these chips needs to be accessed using a bank switching scheme. ESP-IDF provides the **Himem API** to control this bank switching. More specifically, the Himem API allows particular 32 K banks within 4 MiB address switch mappings at run time, thus allowing access to more than 4 MiB of external memory.
|
||||
|
||||
In order to use the himem API, you have to enable it in the menuconfig using :ref:`CONFIG_SPIRAM_BANKSWITCH_ENABLE`, as well as set the amount of banks reserved for this in :ref:`CONFIG_SPIRAM_BANKSWITCH_RESERVE`. This decreases the amount of external memory allocated by functions like ``malloc()``, but it allows you to use the himem api to map any of the remaining memory into the reserved banks.
|
||||
Usage
|
||||
-----
|
||||
|
||||
The himem API is more-or-less an abstraction of the bankswitching scheme: it allows you to claim one or more banks of address space (called 'regions' in the API) as well as one or more of banks of memory to map into the ranges.
|
||||
In order to use the Himem API, you have to enable it in the menuconfig using :ref:`CONFIG_SPIRAM_BANKSWITCH_ENABLE`, as well as set the amount of banks reserved for this in :ref:`CONFIG_SPIRAM_BANKSWITCH_RESERVE`. This decreases the amount of external memory allocated by functions like ``malloc()``, but it allows you to use the Himem API to map any of the remaining memory into the reserved banks.
|
||||
|
||||
The Himem API is more-or-less an abstraction of the bank switching scheme: it allows you to claim one or more banks of address space (called 'regions' in the API) as well as one or more of banks of memory to map into the ranges.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
@ -21,4 +26,4 @@ An example doing a simple memory test of the high memory range is available in E
|
|||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/himem.inc
|
||||
.. include-build-file:: inc/himem.inc
|
||||
|
|
@ -1,14 +1,14 @@
|
|||
Performance Monitor
|
||||
===================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The Performance Monitor component provides APIs to use {IDF_TARGET_NAME} internal performance counters to profile functions and applications.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
An example which combines performance monitor is provided in ``examples/system/perfmon`` directory.
|
||||
|
||||
This example initializes the performance monitor structure and execute them with printing the statistics.
|
||||
An example which combines performance monitor is provided in ``examples/system/perfmon`` directory. This example initializes the performance monitor structure and execute them with printing the statistics.
|
||||
|
||||
High-Level API Reference
|
||||
------------------------
|
||||
|
|
@ -23,4 +23,3 @@ API Reference
|
|||
|
||||
.. include-build-file:: inc/xtensa_perfmon_access.inc
|
||||
.. include-build-file:: inc/xtensa_perfmon_apis.inc
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
SoC Capabilities
|
||||
================
|
||||
|
||||
This section lists definitions of the {IDF_TARGET_NAME}'s SoC hardware capabilities. These definitions are commonly used in ESP-IDF to control which hardware dependent features are supported and thus compiled into the binary.
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. note::
|
||||
This section lists the macro definitions of the {IDF_TARGET_NAME}'s SoC hardware capabilities. These macros are commonly used by conditional-compilation directives (e.g., ``#if``) in ESP-IDF to determine which hardware-dependent features are supported, thus control what portions of code are compiled.
|
||||
|
||||
These defines are currently not considered to be part of the public API, and may be changed at any time.
|
||||
.. warning::
|
||||
|
||||
These macro definitions are currently not considered to be part of the public API, and may be changed in a breaking manner (see :doc:`../../../versions` for more details).
|
||||
|
||||
|
||||
API Reference
|
||||
|
|
|
|||
|
|
@ -1 +1,129 @@
|
|||
.. include:: ../../../en/api-reference/system/app_image_format.rst
|
||||
应用程序镜像格式
|
||||
================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. _app-image-structures:
|
||||
|
||||
应用程序镜像结构
|
||||
----------------------------
|
||||
|
||||
应用程序镜像包含以下内容：
|
||||
|
||||
1. :cpp:type:`esp_image_header_t` 结构体描述了 SPI flash 的模式和内存段的数量。
|
||||
2. :cpp:type:`esp_image_segment_header_t` 结构体描述了每个段、每个段的长度及其在 {IDF_TARGET_NAME} 内存中的位置，此描述后接长度为 ``data_len`` 的数据。镜像中每个段的数据偏移量的计算方式如下：
|
||||
|
||||
* 0 段的偏移量 = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`)
|
||||
* 1 段的偏移量 = 0 段的偏移量 + 0 段长度 + sizeof(:cpp:type:`esp_image_segment_header_t`)
|
||||
* 2 段的偏移量 = 1 段的偏移量 + 1 段长度 + sizeof(:cpp:type:`esp_image_segment_header_t`)
|
||||
* ...
|
||||
|
||||
``segment_count`` 字段定义了每个段的数量，存储在 :cpp:type:`esp_image_header_t` 中。各段段数量不能超过 :c:macro:`ESP_IMAGE_MAX_SEGMENTS`。
|
||||
|
||||
运行以下命令，获取镜像段列表：
|
||||
|
||||
.. code-block::
|
||||
|
||||
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin
|
||||
|
||||
.. code-block::
|
||||
|
||||
esptool.py v2.3.1
|
||||
Image version: 1
|
||||
Entry point: 40080ea4
|
||||
13 segments
|
||||
|
||||
Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM
|
||||
Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM
|
||||
Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM
|
||||
Segment 4: len 0x028e0 load 0x3ffb0000 file_offs 0x00013d10 DRAM
|
||||
Segment 5: len 0x00000 load 0x3ffb28e0 file_offs 0x000165f8 DRAM
|
||||
Segment 6: len 0x00400 load 0x40080000 file_offs 0x00016600 SOC_IRAM
|
||||
Segment 7: len 0x09600 load 0x40080400 file_offs 0x00016a08 SOC_IRAM
|
||||
Segment 8: len 0x62e4c load 0x400d0018 file_offs 0x00020010 SOC_IROM
|
||||
Segment 9: len 0x06cec load 0x40089a00 file_offs 0x00082e64 SOC_IROM
|
||||
Segment 10: len 0x00000 load 0x400c0000 file_offs 0x00089b58 SOC_RTC_IRAM
|
||||
Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA
|
||||
Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA
|
||||
Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA
|
||||
Checksum: e8 (valid)
|
||||
Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
|
||||
|
||||
应用程序启动时，ESP-IDF 日志中也会包含段的相关信息：
|
||||
|
||||
.. code-block::
|
||||
|
||||
I (443) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x13ce0 ( 81120) map
|
||||
I (489) esp_image: segment 1: paddr=0x00033d08 vaddr=0x3ff80000 size=0x00000 ( 0) load
|
||||
I (530) esp_image: segment 2: paddr=0x00033d10 vaddr=0x3ff80000 size=0x00000 ( 0) load
|
||||
I (571) esp_image: segment 3: paddr=0x00033d18 vaddr=0x3ffb0000 size=0x028e0 ( 10464) load
|
||||
I (612) esp_image: segment 4: paddr=0x00036600 vaddr=0x3ffb28e0 size=0x00000 ( 0) load
|
||||
I (654) esp_image: segment 5: paddr=0x00036608 vaddr=0x40080000 size=0x00400 ( 1024) load
|
||||
I (695) esp_image: segment 6: paddr=0x00036a10 vaddr=0x40080400 size=0x09600 ( 38400) load
|
||||
I (737) esp_image: segment 7: paddr=0x00040018 vaddr=0x400d0018 size=0x62e4c (405068) map
|
||||
I (847) esp_image: segment 8: paddr=0x000a2e6c vaddr=0x40089a00 size=0x06cec ( 27884) load
|
||||
I (888) esp_image: segment 9: paddr=0x000a9b60 vaddr=0x400c0000 size=0x00000 ( 0) load
|
||||
I (929) esp_image: segment 10: paddr=0x000a9b68 vaddr=0x50000000 size=0x00004 ( 4) load
|
||||
I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
有关内存段类型和地址范围的更多详细信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **系统和存储器** > **片上存储器** [`PDF <{IDF_TARGET_TRM_CN_URL}#sysmem>`__]。
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
有关内存段类型和地址范围的详细信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **系统和存储器** > **内部存储器** [`PDF <{IDF_TARGET_TRM_CN_URL}#sysmem>`__]。
|
||||
|
||||
3. 镜像有一个校验和字节，位于最后一个段之后。此字节写在一个十六字节填充边界上，因此应用程序镜像可能需要填充。
|
||||
4. 如果在 :cpp:type:`esp_image_header_t` 中设置了 ``hash_appended`` 字段，则会附加 SHA256 校验和字段。SHA256 哈希值的计算范围是从第一个字节开始，到这个字段为止。该字段长度为 32 字节。
|
||||
5. 如果选项 :ref:`CONFIG_SECURE_SIGNED_APPS_SCHEME` 设置为 ECDSA，那么应用程序镜像将有额外的 68 字节用于 ECDSA 签名，其中包括：
|
||||
|
||||
* 版本号（4 字节）
|
||||
* 签名数据（64 字节）
|
||||
|
||||
6. 如果选项 :ref:`CONFIG_SECURE_SIGNED_APPS_SCHEME` 设置为 RSA 或 ECDSA (V2)，则应用程序镜像将有一个额外的签名扇区，大小为 4K 字节。关于此签名扇区格式的更多内容，请参考 :ref:`signature-block-format`。
|
||||
|
||||
.. _app-image-format-application-description:
|
||||
|
||||
应用程序描述
|
||||
-----------------------
|
||||
|
||||
应用程序二进制文件的 ``DROM`` 段从 :cpp:type:`esp_app_desc_t` 结构体开始，该结构体中包含了用于描述应用程序的特定字段，如下所示：
|
||||
|
||||
* ``magic_word``：:cpp:type:`esp_app_desc_t` 结构体的魔术词
|
||||
* ``secure_version``：参见 :doc:`防回滚 </api-reference/system/ota>`
|
||||
* ``version``：参见 :doc:`应用程序版本 </api-reference/system/misc_system_api>` [#f1]_
|
||||
* ``project_name``：通过 ``PROJECT_NAME`` 填充 [#f1]_
|
||||
* ``time`` 和 ``date``：编译时间和日期
|
||||
* ``idf_ver``：ESP-IDF 的版本 [#f1]_
|
||||
* ``app_elf_sha256``：包含应用程序 ELF 文件的 sha256 哈希
|
||||
|
||||
.. [#f1] 最大长度为 32 个字符，其中包括 null 终止符。也就是说，如果 ``PROJECT_NAME`` 的长度超过 31 个字符，超出的字符将被忽略。
|
||||
|
||||
这个结构体有助于识别通过空中升级 (OTA) 上传的镜像，因为其中包含一个固定的偏移量，大小为 sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`)。一旦设备接收到包含此结构体的第一个段，就能根据其中的充分信息来确定是否应继续更新。
|
||||
|
||||
要获取当前运行的应用程序的 :cpp:type:`esp_app_desc_t` 结构体，请调用 :cpp:func:`esp_app_get_description`。
|
||||
|
||||
要获取另一个 OTA 分区的 :cpp:type:`esp_app_desc_t` 结构体，请调用 :cpp:func:`esp_ota_get_partition_description`。
|
||||
|
||||
|
||||
向应用程序添加自定义结构体
|
||||
-------------------------------------------
|
||||
|
||||
也可以自定义类似的结构体，并使其相对于镜像起始位置有一个固定的偏移量。
|
||||
|
||||
采用以下方式向镜像添加自定义结构体：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
const __attribute__((section(".rodata_custom_desc"))) esp_custom_app_desc_t custom_app_desc = { ... }
|
||||
|
||||
自定义结构体的偏移量为 sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`) + sizeof(:cpp:type:`esp_app_desc_t`)。
|
||||
|
||||
需在 ``CMakeLists.txt`` 中添加 ``target_link_libraries(${COMPONENT_TARGET} "-u custom_app_desc")``，确保自定义结构体在未使用时也位于镜像中。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_app_format.inc
|
||||
|
|
|
|||
|
|
@ -1 +1,21 @@
|
|||
.. include:: ../../../en/api-reference/system/app_trace.rst
|
||||
应用级追踪
|
||||
=========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
ESP-IDF 支持用于程序行为分析的 **应用级追踪** 功能。在 menuconfig 中启用该功能后，即可通过 JTAG 接口在主机和 {IDF_TARGET_NAME} 之间传输任意数据，最小化程序的执行开销。
|
||||
|
||||
在程序运行时，开发人员可使用该库向主机发送应用程序的特定执行状态，并接收来自应用程序的命令或其他信息。该库的主要用例包括：
|
||||
|
||||
1. 收集特定应用程序的数据，参见 :ref:`app_trace-application-specific-tracing`。
|
||||
2. 向主机发送轻量级日志，参见 :ref:`app_trace-logging-to-host`。
|
||||
3. 系统行为分析，参见 :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_app_trace.inc
|
||||
.. include-build-file:: inc/esp_sysview_trace.inc
|
||||
|
|
@ -1 +1,29 @@
|
|||
.. include:: ../../../en/api-reference/system/himem.rst
|
||||
Himem
|
||||
=====
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
对于小于等于 4 MiB 大小的外部内存，MMU 配置为使用“统一映射”，即每个 CPU 地址一对一地映射到外部 SPI RAM 地址，从而透明地访问外部内存。但是，由于外部内存的地址空间只有 4 MiB，因此只有小于等于 4 MiB 大小的 SPI RAM 芯片才能完全透明地使用。
|
||||
|
||||
ESP32 仍可使用大于等于 4 MiB 大小的 SPI RAM 芯片。不过，这些芯片上的内存需要通过存储体切换方案 (bank switching) 来访问。ESP-IDF 提供了 **Himem API** 来控制此类存储体切换。具体而言，Himem API 允许在运行时切换地址映射，将特定的 32 K 存储体映射到 4 MiB 地址空间中，从而访问超过 4 MiB 的外部内存。
|
||||
|
||||
使用注意事项
|
||||
--------------
|
||||
|
||||
使用 Himem API 前，必须在 menuconfig 中启用 :ref:`CONFIG_SPIRAM_BANKSWITCH_ENABLE`，并在 :ref:`CONFIG_SPIRAM_BANKSWITCH_RESERVE` 中设置为此预留的储存体数量。这会减少由 ``malloc()`` 等函数分配的外部内存量，但允许使用 Himem API 将任何剩余内存映射到预留的存储体中。
|
||||
|
||||
Himem API 可以看作是存储体切换方案的一个抽象。具体而言，该 API 允许声明一个或多个地址空间存储体（在 API 中称为“regions”），以及一个或多个需映射到此范围的内存存储体。
|
||||
|
||||
示例
|
||||
-------
|
||||
|
||||
ESP-IDF 中提供了对大内存范围进行简单内存测试的示例，请前往 :example:`system/himem` 查看。
|
||||
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/himem.inc
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
System API
|
||||
**********
|
||||
系统 API
|
||||
********
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1,25 @@
|
|||
.. include:: ../../../en/api-reference/system/perfmon.rst
|
||||
性能监视器
|
||||
===================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
性能监视器组件提供了多个 API，可以通过这些 API 来使用 {IDF_TARGET_NAME} 的内部性能计数器，分析函数和应用程序。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
在目录 ``examples/system/perfmon`` 下提供了一个结合性能监视器的示例。此示例初始化并执行了性能监视器，同时打印了统计信息。
|
||||
|
||||
高级 API 参考
|
||||
------------------------
|
||||
|
||||
头文件
|
||||
^^^^^^^^^^^^
|
||||
|
||||
* :component_file:`perfmon/include/perfmon.h`
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/xtensa_perfmon_access.inc
|
||||
.. include-build-file:: inc/xtensa_perfmon_apis.inc
|
||||
|
|
|
|||
|
|
@ -1 +1,16 @@
|
|||
.. include:: ../../../en/api-reference/system/soc_caps.rst
|
||||
SoC 功能
|
||||
================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
此文档介绍了 {IDF_TARGET_NAME} SoC 硬件功能的宏定义。ESP-IDF 中的条件编译指令通常使用这些宏来确定哪些依赖于硬件的功能受到支持，从而控制需编译的代码内容。
|
||||
|
||||
.. note::
|
||||
|
||||
目前，这些宏定义不属于公共 API，未来可能发生重大更改。如需了解详情，请前往 :doc:`../../../versions`。
|
||||
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/soc_caps.inc
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue