esp-idf/docs/zh_CN/api-reference/system/misc_system_api.rst
Laukik Hase ae932c8c4e
docs: Added migration guide for app_update
- Deprecated functions and alternatives
2022-08-17 10:59:31 +05:30

225 lines
9.8 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

杂项系统 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_app_get_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
.. include-build-file:: inc/esp_app_desc.inc