blackbeard420/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf synced 2025-03-10 09:39:10 -04:00
Code Issues Projects Releases Wiki Activity

Merge branch 'docs/add_cn_trans_system.rst' into 'master'

Browse Source 
Docs: Add CN trans for system.rst

Closes DOC-2875

See merge request espressif/esp-idf!17672
This commit is contained in:
Mo Fei Fei 2022-04-20 13:19:50 +08:00
commit 041c1ed3df
8 changed files with 458 additions and 221 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/en/api-reference/system/app_image_format.rst
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 = { ... }

5
docs/en/api-reference/system/index.rst
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.

223
docs/en/api-reference/system/misc_system_api.rst Normal file
View File

@ -0,0 +1,223 @@
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
--------------
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, 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
------------
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
-----------
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 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. 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 supported network interfaces (e.g., Wi-Fi, Bluetooth, Ethernet).
To fetch the MAC address for a specific network interface (e.g., Wi-Fi, Bluetooth, Ethernet), call the function :cpp:func:`esp_read_mac`.
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
.. 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 :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
.. 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 :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:: 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 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. 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. 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
@@@@@@@@@@@@@@@@@@@@@@@@@@@
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
.. 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::
If the 3/4 coding scheme is enabled, all eFuse fields in this block must be burnt at the same time.
.. only:: not esp32
.. 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, 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{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 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 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 (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
------------
: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
-----------
: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 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.
* :c:macro:`ESP_IDF_VERSION_VAL` and :c:macro:`ESP_IDF_VERSION` can be used when implementing version checks:
.. code-block:: c
#include "esp_idf_version.h"
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
// enable functionality present in ESP-IDF v4.0
#endif
.. _app-version:
App Version
-----------
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.
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 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
-------------
.. include-build-file:: inc/esp_system.inc
.. include-build-file:: inc/esp_idf_version.inc
.. include-build-file:: inc/esp_mac.inc
.. include-build-file:: inc/esp_chip_info.inc
.. include-build-file:: inc/esp_cpu.inc

208
docs/en/api-reference/system/system.rst
View File

@ -1,208 +0,0 @@
Miscellaneous System APIs
=========================
{IDF_TARGET_BASE_MAC_BLOCK: default="BLK1", esp32="BLK0"}
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.
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.
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.
Heap memory
-----------
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.
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>`.
.. _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).
.. only:: SOC_BT_SUPPORTED
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.
.. 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) |
+---------------+---------------------------------------+-----------------------------------------------+
.. 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.
.. 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.) |
+---------------+---------------------------------------+-----------------------------------------------+
.. 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.
.. 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`.
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 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.
.. 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.
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 |
+-----------------+-----------+---------------+------------------------------+
.. note::
If the 3/4 coding scheme is enabled, all eFuse fields in this block must be burnt at the same time.
.. only:: not esp32
+-----------------+-----------+---------------+
| 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.
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{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.
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.
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.
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.
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
-----------
: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.
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.
* :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.
* :c:macro:`ESP_IDF_VERSION_VAL` and :c:macro:`ESP_IDF_VERSION` can be used when implementing version checks:
.. code-block:: c
#include "esp_idf_version.h"
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
// enable functionality present in IDF v4.0
#endif
.. _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:
* 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.
API Reference
-------------
.. include-build-file:: inc/esp_system.inc
.. include-build-file:: inc/esp_idf_version.inc
.. include-build-file:: inc/esp_mac.inc
.. include-build-file:: inc/esp_chip_info.inc
.. include-build-file:: inc/esp_cpu.inc

1
docs/page_redirects.txt
View File

@ -63,6 +63,7 @@ api-guides/ulp_macros.rst api-reference/system/ulp_macros.
api-guides/ulp-risc-v.rst api-reference/system/ulp-risc-v.rst
api-reference/network/tcpip_adapter migration-guides/tcpip-adapter
api-reference/system/system api-reference/system/misc_system_api
# The 'secure boot' guides are now 'secure boot v1' guides
security/secure-boot security/secure-boot-v1

4
docs/zh_CN/api-reference/system/index.rst
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

223
docs/zh_CN/api-reference/system/misc_system_api.rst Normal file
View File

@ -0,0 +1,223 @@
杂项系统 API
=========================
:link_to_translation:`en:[English]`
{IDF_TARGET_BASE_MAC_BLOCK: default="BLK1", esp32="BLK0"}
{IDF_TARGET_CPU_RESET_DES: default="两个 CPU 复位", esp32c3="CPU 复位", esp32c2="CPU 复位"}
软件复位
------------
函数 :cpp:func:`esp_restart` 用于执行芯片的软件复位。调用此函数时，程序停止执行，{IDF_TARGET_CPU_RESET_DES}，应用程序由 bootloader 加载并重启。
函数 :cpp:func:`esp_register_shutdown_handler` 用于注册复位前会自动调用的例程（复位过程由 :cpp:func:`esp_restart` 函数触发），这与 ``atexit`` POSIX 函数的功能类似。
复位原因
------------
ESP-IDF 应用程序启动或复位的原因有多种。调用 :cpp:func:`esp_reset_reason` 函数可获取最近一次复位的原因。复位的所有可能原因，请查看 :cpp:type:`esp_reset_reason_t` 中的描述。
堆内存
---------
ESP-IDF 中有两个与堆内存相关的函数：
* 函数 :cpp:func:`esp_get_free_heap_size` 用于查询当前可用的堆内存大小。
* 函数 :cpp:func:`esp_get_minimum_free_heap_size` 用于查询整个过程中可用的最小堆内存大小（例如应用程序生命周期内可用的最小堆内存大小）。
请注意，ESP-IDF 支持功能不同的的多个堆。上文中函数返回的堆内存大小可使用 ``malloc`` 函数族来进行分配。有关堆内存的更多信息，请参阅 :doc:`堆内存分配 <mem_alloc>`。
.. _MAC-Address-Allocation:
MAC 地址
-----------
以下 API 用于查询和自定义支持的网络接口（如 Wi-Fi、蓝牙、以太网）的 MAC 地址。
要获取特定接口（如 Wi-Fi、蓝牙、以太网）的 MAC 地址，请调用函数 :cpp:func:`esp_read_mac`。
在 ESP-IDF 中，各个网络接口的 MAC 地址是根据单个 *基准 MAC 地址 (Base MAC address)* 计算出来的。默认情况下使用乐鑫指定的基准 MAC 地址，该基准地址在产品生产过程中已预烧录至 {IDF_TARGET_NAME} eFuse。
.. only:: not esp32s2
.. list-table::
:widths: 20 40 40
:header-rows: 1
* - 接口
- MAC 地址（默认 4 个全局地址)
- MAC 地址（2 个全局地址）
* - Wi-Fi Station
- base_mac
- base_mac
* - Wi-Fi SoftAP
- base_mac 最后一组字节后加 1
- :ref:`本地 MAC <local-mac-addresses>` （由 Wi-Fi Station MAC 生成）
* - 蓝牙
- base_mac 最后一组字节后加 2
- base_mac 最后一组字节后加 1
* - 以太网
- base_mac 最后一组字节后加 3
- :ref:`本地 MAC <local-mac-addresses>` （由蓝牙 MAC 生成）
.. note::
:ref:`配置选项 <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>` 配置了乐鑫提供的全局 MAC 地址的数量。
.. only:: esp32s2
.. list-table::
:widths: 20 40 40
:header-rows: 1
* - 接口
- MAC 地址（默认 2 个全局地址)
- MAC 地址（1 个全局地址）
* - Wi-Fi Station
- base_mac
- base_mac
* - Wi-Fi SoftAP
- base_mac 最后一组字节后加 1
- :ref:`本地 MAC <local-mac-addresses>` （由 Wi-Fi Station MAC 生成）
* - 以太网
- :ref:`本地 MAC <local-mac-addresses>` （由 Wi-Fi SoftAP MAC 生成）
- :ref:`本地 MAC <local-mac-addresses>` （在 base_mac 最后一组字节后加 1 生成，不推荐）
.. note::
:ref:`配置选项 <CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES>` 配置了乐鑫提供的全局 MAC 地址的数量。
.. only:: not SOC_EMAC_SUPPORTED
.. note:: {IDF_TARGET_NAME} 内部未集成以太网 MAC 地址，但仍可以计算得出该地址。不过，以太网 MAC 地址只能与外部以太网接口（如 SPI 以太网设备）一起使用，具体请参阅 :doc:`/api-reference/network/esp_eth`。
自定义基准 MAC
^^^^^^^^^^^^^^^
乐鑫已将默认的基准 MAC 地址预烧录至 eFuse {IDF_TARGET_BASE_MAC_BLOCK} 中。如需设置自定义基准 MAC 地址，请在初始化任一网络接口或调用 :cpp:func:`esp_read_mac` 函数前调用 :cpp:func:`esp_base_mac_addr_set` 函数。自定义基准 MAC 地址可以存储在任何支持的存储设备中（例如 flash、NVS）。
分配自定义基准 MAC 地址时，应避免 MAC 地址重叠。请根据上面的表格配置选项 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES`，设置可从自定义基准 MAC 地址生成的有效全局 MAC 地址。
.. note::
也可以调用函数 :cpp:func:`esp_netif_set_mac`，在网络初始化后设置网络接口使用的特定 MAC。但建议使用此处介绍的自定义基准 MAC 地址的方法，以避免原始 MAC 地址在更改前短暂出现在网络上。
eFuse 中的自定义 MAC 地址
@@@@@@@@@@@@@@@@@@@@@@@@@@@
ESP-IDF 提供了 :cpp:func:`esp_efuse_mac_get_custom` 函数。从 eFuse 读取自定义 MAC 地址时，调用该函数将从 eFuse BLK3 加载 MAC 地址。此函数假定自定义基准 MAC 地址的存储格式如下：
.. only:: esp32
.. list-table::
:widths: 20 15 20 45
:header-rows: 1
* - 字段
- 比特数
- 比特范围
- 说明
* - Version
- 8
- 191:184
- 0：无效；其他：有效
* - Reserved
- 128
- 183:56
-
* - MAC address
- 48
- 55:8
-
* - MAC address CRC
- 8
- 7:0
- CRC-8-CCITT，多项式 0x07
.. note::
如果启用了 3/4 编码方案，则必须同时烧写该块中的所有 eFuse 字段。
.. only:: not esp32
.. list-table::
:widths: 30 30 30
:header-rows: 1
* - 字段
- 比特数
- 比特范围
* - MAC address
- 48
- 200:248
.. note::
eFuse BLK3 在烧写时使用 RS 编码，这意味着必须同时烧写该块中的所有 eFuse 字段。
调用 :cpp:func:`esp_efuse_mac_get_custom` 函数获得 MAC 地址后，请调用 :cpp:func:`esp_base_mac_addr_set` 函数将此 MAC 地址设置为基准 MAC 地址。
.. _local-mac-addresses:
本地 MAC 地址和全局 MAC 地址
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
在 {IDF_TARGET_NAME} 中，乐鑫已预烧录足够数量的有效乐鑫全局 MAC 地址，供所有内部接口使用。上文中的表格已经介绍了如何根据基准 MAC 地址计算出具体接口的 MAC 地址。
当使用自定义 MAC 地址时，可能并非所有接口都能被分配到一个全局 MAC 地址。此时，接口会被分配一个本地 MAC 地址。请注意，这些地址仅用于单个本地网络。
本地 MAC 地址和全局 MAC 地址的定义，请参见 `此处 <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local_(U/L_bit)>`_。
内部调用函数 :cpp:func:`esp_derive_local_mac`，可从全局 MAC 地址生成本地 MAC 地址。具体流程如下：
1. 在全局 MAC 地址的第一个字节组中设置 U/L 位（位值为 0x2），创建本地 MAC 地址。
2. 如果该位已存在于全局 MAC 地址中（即现有的 “全局” MAC 地址实际上已经是本地 MAC 地址），则本地 MAC 地址的第一个字节组与 0x4 异或。
芯片版本
------------
:cpp:func:`esp_chip_info` 函数用于填充 :cpp:class:`esp_chip_info_t` 结构体中的芯片信息，包括芯片版本、CPU 数量和芯片中已启用功能的位掩码。
.. _idf-version-h:
SDK 版本
----------
调用函数 :cpp:func:`esp_get_idf_version` 可返回一个字符串，该字符串包含了用于编译应用程序的 ESP-IDF 版本，与构建系统中通过 ``IDF_VER`` 变量所获得的值相同。该版本字符串的格式即 ``git describe`` 命令的运行结果。
也有其它的版本宏可用于在构建过程中获取 ESP-IDF 版本，它们可根据 ESP-IDF 版本启用或禁用部分程序。
* :c:macro:`ESP_IDF_VERSION_MAJOR`、 :c:macro:`ESP_IDF_VERSION_MINOR` 和 :c:macro:`ESP_IDF_VERSION_PATCH` 分别被定义为代表主要版本、次要版本和补丁版本的整数。
* :c:macro:`ESP_IDF_VERSION_VAL` 和 :c:macro:`ESP_IDF_VERSION` 可在确认版本时使用：
.. code-block:: c
#include "esp_idf_version.h"
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
// 启用 ESP-IDF v4.0 中的功能
#endif
.. _app-version:
应用程序版本
-------------
应用程序版本存储在 :cpp:class:`esp_app_desc_t` 结构体中。该结构体位于 DROM 扇区，有一个从二进制文件头部计算的固定偏移值。该结构体位于 :cpp:class:`esp_image_header_t` 和 :cpp:class:`esp_image_segment_header_t` 结构体之后。字段 Version 类型为字符串，最大长度为 32 字节。
若需手动设置版本，需要在项目的 ``CMakeLists.txt`` 文件中设置 ``PROJECT_VER`` 变量，即在 ``CMakeLists.txt`` 文件中，在包含 ``project.cmake`` 之前添加 ``set(PROJECT_VER "0.1.0.1")``。
如果设置了 :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` 选项，则将使用 :ref:`CONFIG_APP_PROJECT_VER` 的值。否则，如果在项目中未设置 ``PROJECT_VER`` 变量，则该变量将从 ``$(PROJECT_PATH)/version.txt`` 文件（若有）中检索，或使用 git 命令 ``git describe`` 检索。如果两者都不可用，则 ``PROJECT_VER`` 将被设置为 “1”。应用程序可通过调用 :cpp:func:`esp_ota_get_app_description` 或 :cpp:func:`esp_ota_get_partition_description` 函数来获取应用程序的版本信息。
API 参考
-------------
.. include-build-file:: inc/esp_system.inc
.. include-build-file:: inc/esp_idf_version.inc
.. include-build-file:: inc/esp_mac.inc
.. include-build-file:: inc/esp_chip_info.inc
.. include-build-file:: inc/esp_cpu.inc

1
docs/zh_CN/api-reference/system/system.rst
View File

@ -1 +0,0 @@
.. include:: ../../../en/api-reference/system/system.rst