Merge branch 'docs/add_CN_trans_for_docs_in_api-reference/systems' into 'master'
docs: Provide Chinese translation for docs in api-reference/system Closes DOC-6184 See merge request espressif/esp-idf!25727
This commit is contained in:
Ren Pei Ying
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user