pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add cn trans for system.rst

Browse Source
This commit is contained in:
mofeifei
2022-03-30 10:31:50 +08:00
parent 5bb59b00e7
commit 485cdd9a74
6 changed files with 341 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/system/app_image_format.rst
+7 -7
View File
@@ -15,11 +15,11 @@ The count of each segment is defined in the ``segment_count`` field that is stor
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
::
.. code-block::
esptool.py v2.3.1
Image version: 1
@@ -40,9 +40,9 @@ To get the list of your image segments, please run the following command:
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 IDF logs while your application is booting:
::
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
@@ -80,7 +80,7 @@ The ``DROM`` segment starts with the :cpp:type:`esp_app_desc_t` structure which
* ``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/system>`. ``*``
* ``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. ``*``
@@ -96,7 +96,7 @@ Adding a Custom Structure to an Application
Users also have the opportunity to have similar structure with a fixed offset relative to the beginning of the image.
The following pattern can be used to add a custom structure to your image:
::
.. code-block::
const __attribute__((section(".rodata_custom_desc"))) esp_custom_app_desc_t custom_app_desc = { ... }
docs/en/api-reference/system/index.rst
+2 -3
View File
@@ -23,14 +23,14 @@ System API
:not CONFIG_FREERTOS_UNICORE: ipc
intr_alloc
log
system
soc_caps
misc_system_api
ota
:CONFIG_IDF_TARGET_ARCH_XTENSA: perfmon
power_management
pthread
random
sleep_modes
soc_caps
system_time
:SOC_ASYNC_MEMCPY_SUPPORTED: async_memcpy
:esp32: himem
@@ -39,5 +39,4 @@ System API
wdts
Code examples for this API section are provided in the :example:`system` directory of ESP-IDF examples.
docs/en/api-reference/system/system.rst
+106 -91
View File
@@ -1,126 +1,139 @@
Miscellaneous System APIs
=========================
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_BASE_MAC_BLOCK: default="BLK1", esp32="BLK0"}
{IDF_TARGET_CPU_RESET_DES: default="both CPUs are reset", esp32c3="the CPU is reset", esp32c2="the CPU is reset"}
Software reset
Software Reset
--------------
To perform software reset of the chip, :cpp:func:`esp_restart` function is provided. When the function is called, execution of the program will stop, both CPUs will be reset, application will be loaded by the bootloader and started again.
To perform software reset of the chip, the :cpp:func:`esp_restart` function is provided. When the function is called, execution of the program stops, {IDF_TARGET_CPU_RESET_DES}, and the application is loaded by the bootloader and starts execution again.
Additionally, :cpp:func:`esp_register_shutdown_handler` function is provided to register a routine which needs to be called prior to restart (when done by :cpp:func:`esp_restart`). This is similar to the functionality of ``atexit`` POSIX function.
Additionally, the :cpp:func:`esp_register_shutdown_handler` function can register a routine that will be automatically called before a restart (that is triggered by :cpp:func:`esp_restart`) occurs. This is similar to the functionality of ``atexit`` POSIX function.
Reset reason
Reset Reason
------------
ESP-IDF application can be started or restarted due to a variety of reasons. To get the last reset reason, call :cpp:func:`esp_reset_reason` function. See description of :cpp:type:`esp_reset_reason_t` for the list of possible reset reasons.
ESP-IDF applications can be started or restarted due to a variety of reasons. To get the last reset reason, call :cpp:func:`esp_reset_reason` function. See description of :cpp:type:`esp_reset_reason_t` for the list of possible reset reasons.
Heap memory
Heap Memory
-----------
Two heap memory related functions are provided:
Two heap-memory-related functions are provided:
* :cpp:func:`esp_get_free_heap_size` returns the current size of free heap memory
* :cpp:func:`esp_get_minimum_free_heap_size` returns the minimum size of free heap memory that was available during program execution.
* :cpp:func:`esp_get_free_heap_size` returns the current size of free heap memory.
* :cpp:func:`esp_get_minimum_free_heap_size` returns the minimum size of free heap memory that has ever been available (i.e., the smallest size of free heap memory in the applications lifetime).
Note that ESP-IDF supports multiple heaps with different capabilities. Functions mentioned in this section return the size of heap memory which can be allocated using ``malloc`` family of functions. For further information about heap memory see :doc:`Heap Memory Allocation <mem_alloc>`.
Note that ESP-IDF supports multiple heaps with different capabilities. The functions mentioned in this section return the size of heap memory that can be allocated using the ``malloc`` family of functions. For further information about heap memory, see :doc:`Heap Memory Allocation <mem_alloc>`.
.. _MAC-Address-Allocation:
MAC Address
-----------
These APIs allow querying and customizing MAC addresses for different network interfaces that supported (e.g. Wi-Fi, Bluetooth, Ethernet).
These APIs allow querying and customizing MAC addresses for different supported network interfaces (e.g., Wi-Fi, Bluetooth, Ethernet).
.. only:: SOC_BT_SUPPORTED
To fetch the MAC address for a specific network interface (e.g., Wi-Fi, Bluetooth, Ethernet), call the function :cpp:func:`esp_read_mac`.
To fetch MAC address for a specific interface (e.g. Wi-Fi, Bluetooth, Ethernet), call the function :cpp:func:`esp_read_mac` function.
.. only:: not SOC_BT_SUPPORTED
To fetch MAC address for a specific interface (e.g. Wi-Fi Station, Wi-Fi SoftAP), call the function :cpp:func:`esp_read_mac` function.
In ESP-IDF these addresses are calculated from a single *Base MAC address*. By default, the Espressif base MAC address is used. This MAC is pre-programmed into {IDF_TARGET_NAME} eFuse from the factory.
In ESP-IDF, the MAC addresses for the various network interfaces are calculated from a single *base MAC address*. By default, the Espressif base MAC address is used. This base MAC address is pre-programmed into the {IDF_TARGET_NAME} eFuse in the factory during production.
.. only:: not esp32s2
+---------------+---------------------------------------+-----------------------------------------------+
| Interface | MAC address | MAC address |
| | (4 universally administered, default) | (2 universally administered) |
+===============+=======================================+===============================================+
| Wi-Fi Station | base_mac | base_mac |
+---------------+---------------------------------------+-----------------------------------------------+
| Wi-Fi SoftAP | base_mac, +1 to the last octet | :ref:`Local MAC <local-mac-addresses>` |
| | | derived from Wi-Fi Station MAC) |
+---------------+---------------------------------------+-----------------------------------------------+
| Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet |
+---------------+---------------------------------------+-----------------------------------------------+
| Ethernet | base_mac, +3 to the last octet | :ref:`Local MAC <local-mac-addresses>` |
| | | (derived from Bluetooth MAC) |
+---------------+---------------------------------------+-----------------------------------------------+
.. list-table::
:widths: 20 40 40
:header-rows: 1
* - Interface
- MAC Address (4 universally administered, default)
- MAC Address (2 universally administered)
* - Wi-Fi Station
- base_mac
- base_mac
* - Wi-Fi SoftAP
- base_mac, +1 to the last octet
- :ref:`Local MAC <local-mac-addresses>` (derived from Wi-Fi Station MAC)
* - Bluetooth
- base_mac, +2 to the last octet
- base_mac, +1 to the last octet
* - Ethernet
- base_mac, +3 to the last octet
- :ref:`Local MAC <local-mac-addresses>` (derived from Bluetooth MAC)
.. note::
The default :ref:`configuration <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>`
is 4 universally administered MAC addresses, and this is recommended when using
Espressif-provided MAC addresses.
The :ref:`configuration <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>` configures the number of universally administered MAC addresses that are provided by Espressif.
.. only:: esp32s2
+---------------+---------------------------------------+-----------------------------------------------+
| Interface | MAC address | MAC address |
| | (2 universally administered, default) | (1 universally administered) |
+===============+=======================================+===============================================+
| Wi-Fi Station | base_mac | base_mac |
+---------------+---------------------------------------+-----------------------------------------------+
| Wi-Fi SoftAP | base_mac, +1 to the last octet | :ref:`Local MAC <local-mac-addresses>` |
| | | (derived from Wi-Fi Station MAC) |
+---------------+---------------------------------------+-----------------------------------------------+
| Ethernet | :ref:`Local MAC <local-mac-addresses>`| :ref:`Local MAC <local-mac-addresses>` |
| (see note) | (derived from Wi-Fi SoftAP MAC | (derived from base_mac with +1 to last octet. |
| | | Not recommended.) |
+---------------+---------------------------------------+-----------------------------------------------+
.. list-table::
:widths: 20 40 40
:header-rows: 1
* - Interface
- MAC Address (2 universally administered, default)
- MAC Address (1 universally administered)
* - Wi-Fi Station
- base_mac
- base_mac
* - Wi-Fi SoftAP
- base_mac, +1 to the last octet
- :ref:`Local MAC <local-mac-addresses>` (derived from Wi-Fi Station MAC)
* - Ethernet
- :ref:`Local MAC <local-mac-addresses>` (derived from Wi-Fi SoftAP MAC)
- :ref:`Local MAC <local-mac-addresses>` (derived from base_mac with +1 to last octet. Not recommended.)
.. note::
The default :ref:`configuration <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>`
is 2 universally administered MAC addresses, and this is recommended when using
Espressif-provided MAC addresses.
The :ref:`configuration <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>` configures the number of universally administered MAC addresses that are provided by Espressif.
.. only:: not SOC_EMAC_SUPPORTED
.. note:: {IDF_TARGET_NAME} has no integrated Ethernet MAC, but it's still possible to calculate an Ethernet MAC address. This MAC address can only be used with an external interface such as an SPI-Ethernet device, see :doc:`/api-reference/network/esp_eth`.
.. note:: Although {IDF_TARGET_NAME} has no integrated Ethernet MAC, it is still possible to calculate an Ethernet MAC address. However, this MAC address can only be used with an external ethernet interface such as an SPI-Ethernet device. See :doc:`/api-reference/network/esp_eth`.
Custom Base MAC
^^^^^^^^^^^^^^^
The default Base MAC is pre-programmed by Espressif in eFuse {IDF_TARGET_BASE_MAC_BLOCK}. To set a custom Base MAC instead, call the function :cpp:func:`esp_base_mac_addr_set` before initializing any network interfaces or calling the :cpp:func:`esp_read_mac` function. The customized MAC address can be stored in any supported storage device (e.g. Flash, NVS, etc).
The default base MAC is pre-programmed by Espressif in eFuse {IDF_TARGET_BASE_MAC_BLOCK}. To set a custom base MAC instead, call the function :cpp:func:`esp_base_mac_addr_set` before initializing any network interfaces or calling the :cpp:func:`esp_read_mac` function. The custom MAC address can be stored in any supported storage device (e.g., flash, NVS).
The custom base MAC addresses should be allocated such that derived MAC addresses will not overlap. Configure the option :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` to set the number of valid universal MAC addresses that can be derived from the custom base MAC, according to the table above.
The custom base MAC addresses should be allocated such that derived MAC addresses will not overlap. Based on the table above, users can configure the option :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` to set the number of valid universal MAC addresses that can be derived from the custom base MAC.
.. note::
It is also possible to call the function :cpp:func:`esp_netif_set_mac` to set the specific MAC used by a network interface, after network initialization. It's recommended to use the Base MAC approach documented here instead, to avoid the possibility of the original MAC address briefly appearing on the network before it is changed.
It is also possible to call the function :cpp:func:`esp_netif_set_mac` to set the specific MAC used by a network interface after network initialization. But it is recommended to use the base MAC approach documented here to avoid the possibility of the original MAC address briefly appearing on the network before being changed.
Custom MAC address in eFuse
Custom MAC Address in eFuse
@@@@@@@@@@@@@@@@@@@@@@@@@@@
When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function :cpp:func:`esp_efuse_mac_get_custom`. This loads the MAC address from eFuse BLK3. This function assumes that the custom base MAC address is stored in the following format:
.. only:: esp32
+-----------------+-----------+---------------+------------------------------+
| Field | # of bits | Range of bits | Notes |
+=================+===========+===============+==============================+
| Version | 8 | 191:184 | 0: invalid, others — valid |
+-----------------+-----------+---------------+------------------------------+
| Reserved | 128 | 183:56 | |
+-----------------+-----------+---------------+------------------------------+
| MAC address | 48 | 55:8 | |
+-----------------+-----------+---------------+------------------------------+
| MAC address CRC | 8 | 7:0 | CRC-8-CCITT, polynomial 0x07 |
+-----------------+-----------+---------------+------------------------------+
.. list-table::
:widths: 20 15 20 45
:header-rows: 1
* - Field
- # of bits
- Range of bits
- Notes
* - Version
- 8
- 191:184
- 0: invalid, others — valid
* - Reserved
- 128
- 183:56
-
* - MAC address
- 48
- 55:8
-
* - MAC address CRC
- 8
- 7:0
- CRC-8-CCITT, polynomial 0x07
.. note::
@@ -128,49 +141,53 @@ When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function
.. only:: not esp32
+-----------------+-----------+---------------+
| Field | # of bits | Range of bits |
+=================+===========+===============+
| MAC address | 48 | 200:248 |
+-----------------+-----------+---------------+
.. list-table::
:widths: 30 30 30
:header-rows: 1
* - Field
- # of bits
- Range of bits
* - MAC address
- 48
- 200:248
.. note::
The eFuse BLK3 uses RS-coding during a burn operation it means that all eFuse fields in this block must be burnt at the same time.
The eFuse BLK3 uses RS-coding during a burn operation, which means that all eFuse fields in this block must be burnt at the same time.
Once MAC address has been obtained using :cpp:func:`esp_efuse_mac_get_custom`, call :cpp:func:`esp_base_mac_addr_set` to set this MAC address as base MAC address.
.. _local-mac-addresses:
Local vs Universal MAC addresses
Local vs Universal MAC Addresses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{IDF_TARGET_NAME} comes pre-programmed with enough valid Espressif universally administered MAC addresses for all internal interfaces. The specific calculations to derive an interface's MAC address from the base MAC address is shown in the table above.
{IDF_TARGET_NAME} comes pre-programmed with enough valid Espressif universally administered MAC addresses for all internal interfaces. The table above shows how to calculate and derive the MAC address for a specific interface according to the base MAC address.
When using a custom MAC address scheme, it's possible that not all interfaces can be assigned a universally administered MAC address. In these cases, a locally administered MAC address is assigned. Note that these addresses are intended for use on a single local network, only.
When using a custom MAC address scheme, it is possible that not all interfaces can be assigned with a universally administered MAC address. In these cases, a locally administered MAC address is assigned. Note that these addresses are intended for use on a single local network only.
See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local_(U/L_bit)>`_ for the definition of local and universally administered MAC addresses.
See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local_(U/L_bit)>`_ for the definition of locally and universally administered MAC addresses.
Function :cpp:func:`esp_derive_local_mac` is called internally to derive a local MAC address from a universal MAC address. The process is as follows:
1. The U/L bit (bit value 0x2) is set in the first octet of the universal MAC address, creating a local MAC address.
2. If this bit is already set in the supplied universal MAC address (meaning: the supplied "universal" MAC address was in fact already a local MAC address), then the first octet of the local MAC address is XORed with 0x4.
2. If this bit is already set in the supplied universal MAC address (i.e., the supplied "universal" MAC address was in fact already a local MAC address), then the first octet of the local MAC address is XORed with 0x4.
Chip version
Chip Version
------------
:cpp:func:`esp_chip_info` function fills :cpp:class:`esp_chip_info_t` structure with information about the chip. This includes the chip revision, number of CPU cores, and a bit mask of features enabled in the chip.
.. _idf-version-h:
SDK version
SDK Version
-----------
:cpp:func:`esp_get_idf_version` returns a string describing the IDF version which was used to compile the application. This is the same value as the one available through ``IDF_VER`` variable of the build system. The version string generally has the format of ``git describe`` output.
:cpp:func:`esp_get_idf_version` returns a string describing the ESP-IDF version which is used to compile the application. This is the same value as the one available through ``IDF_VER`` variable of the build system. The version string generally has the format of ``git describe`` output.
To get the version at build time, additional version macros are provided. They can be used to enable or disable parts of the program depending on IDF version.
To get the version at build time, additional version macros are provided. They can be used to enable or disable parts of the program depending on the ESP-IDF version.
* :c:macro:`ESP_IDF_VERSION_MAJOR`, :c:macro:`ESP_IDF_VERSION_MINOR`, :c:macro:`ESP_IDF_VERSION_PATCH` are defined to integers representing major, minor, and patch version.
@@ -181,22 +198,20 @@ To get the version at build time, additional version macros are provided. They c
#include "esp_idf_version.h"
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
// enable functionality present in IDF v4.0
// enable functionality present in ESP-IDF v4.0
#endif
.. _app-version:
App version
App Version
-----------
Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file.
The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars.
To set version in your project manually you need to set ``PROJECT_VER`` variable in your project CMakeLists.txt/Makefile:
The application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The type of the field version is string and it has a maximum length of 32 chars.
* In application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including ``project.cmake``.
To set the version in your project manually, you need to set the ``PROJECT_VER`` variable in the ``CMakeLists.txt`` of your project. In application ``CMakeLists.txt``, put ``set(PROJECT_VER "0.1.0.1")`` before including ``project.cmake``.
If :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used. Otherwise, if ``PROJECT_VER`` variable is not set in the project then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions.
If the :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used. Otherwise, if the ``PROJECT_VER`` variable is not set in the project, it will be retrieved either from the ``$(PROJECT_PATH)/version.txt`` file (if present) or using git command ``git describe``. If neither is available, ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions.
API Reference
-------------