docs: Provide Chinese translation for bootloader_image_format, log, random, and internal-unstable.rst
This commit is contained in:
renpeiying
@@ -1 +1,81 @@
|
||||
.. include:: ../../../en/api-reference/system/bootloader_image_format.rst
|
||||
引导加载程序镜像的格式
|
||||
=======================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
引导加载程序镜像与应用程序镜像具有相同的结构，参见 :ref:`app-image-structures`。二者唯一的区别在于 :ref:`描述引导加载程序的结构体 <image-format-bootloader-description>` 不同。
|
||||
|
||||
要查看关于引导加载程序镜像的更多内容，请运行以下命令：
|
||||
|
||||
.. code-block::
|
||||
|
||||
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/bootloader/bootloader.bin --version 2
|
||||
|
||||
输出结果如下形式所示：
|
||||
|
||||
.. code-block::
|
||||
|
||||
File size: 26576 (bytes)
|
||||
|
||||
ESP32 image header
|
||||
==================
|
||||
Image version: 1
|
||||
Entry point: 0x40080658
|
||||
Segments: 4
|
||||
Flash size: 2MB
|
||||
Flash freq: 40m
|
||||
Flash mode: DIO
|
||||
|
||||
ESP32 extended image header
|
||||
===========================
|
||||
WP pin: 0xee
|
||||
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
|
||||
Chip ID: 0
|
||||
Minimal chip revision: v0.0, (legacy min_rev = 0)
|
||||
Maximal chip revision: v3.99
|
||||
|
||||
Segments information
|
||||
====================
|
||||
Segment Length Load addr File offs Memory types
|
||||
------- ------- ---------- ---------- ------------
|
||||
1 0x01bb0 0x3fff0030 0x00000018 BYTE_ACCESSIBLE, DRAM, DIRAM_DRAM
|
||||
2 0x03c90 0x40078000 0x00001bd0 CACHE_APP
|
||||
3 0x00004 0x40080400 0x00005868 IRAM
|
||||
4 0x00f2c 0x40080404 0x00005874 IRAM
|
||||
|
||||
ESP32 image footer
|
||||
==================
|
||||
Checksum: 0x65 (valid)
|
||||
Validation hash: 6f31a7f8512f26f6bce7c3b270f93bf6cf1ee4602c322998ca8ce27433527e92 (valid)
|
||||
|
||||
Bootloader information
|
||||
======================
|
||||
Bootloader version: 1
|
||||
ESP-IDF: v5.1-dev-4304-gcb51a3b-dirty
|
||||
Compile time: Mar 30 2023 19:14:17
|
||||
|
||||
|
||||
.. _image-format-bootloader-description:
|
||||
|
||||
引导加载程序描述
|
||||
----------------------
|
||||
|
||||
引导加载程序二进制文件的 ``DRAM0`` 段起始位置为 :cpp:type:`esp_bootloader_desc_t` 结构体，其中包含描述引导加载程序的特定字段。此结构体位置具有固定偏移量，大小为 sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`)。
|
||||
|
||||
* ``magic_byte``：esp_bootloader_desc 结构体的魔术字节
|
||||
* ``reserved``：保留供 IDF 未来使用
|
||||
* ``version``：引导加载程序版本，参见 :ref:`CONFIG_BOOTLOADER_PROJECT_VER`
|
||||
* ``idf_ver``：IDF 版本。[#f1]_
|
||||
* ``date`` 和 ``time``：编译日期和时间
|
||||
* ``reserved2``：保留供 IDF 未来使用
|
||||
|
||||
.. [#f1] 最大长度为 32 个字符，包括空终止符。
|
||||
|
||||
如需从正在运行的引导加载程序中获取 :cpp:type:`esp_bootloader_desc_t` 结构体，请使用 :cpp:func:`esp_bootloader_get_description`。
|
||||
|
||||
如需从正在运行的应用程序中获取 :cpp:type:`esp_bootloader_desc_t` 结构体，请使用 :cpp:func:`esp_ota_get_bootloader_description`。
|
||||
|
||||
API参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_bootloader_desc.inc
|
||||
|
||||
@@ -1 +1,12 @@
|
||||
.. include:: ../../../en/api-reference/system/internal-unstable.rst
|
||||
内部 API 和不稳定的 API
|
||||
==========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
该文档列举了一些 API，这些 API 供内部使用或可能在 ESP-IDF 后续版本中被更改或删除。
|
||||
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_rom_sys.inc
|
||||
|
||||
@@ -1 +1,137 @@
|
||||
.. include:: ../../../en/api-reference/system/log.rst
|
||||
日志库
|
||||
===============
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
日志库提供了三种设置日志级别的方式：
|
||||
|
||||
- **编译时**：在 menuconfig 中，使用选项 :ref:`CONFIG_LOG_DEFAULT_LEVEL` 来设置日志级别。
|
||||
- 另外，还可以选择在 menuconfig 中使用选项 :ref:`CONFIG_LOG_MAXIMUM_LEVEL` 设置最高日志级别。这个选项默认被配置为默认级别，但这个选项也可以被配置为更高级别，将更多的可选日志编译到固件中。
|
||||
- **运行时**：默认启用所有级别低于 :ref:`CONFIG_LOG_DEFAULT_LEVEL` 的日志。:cpp:func:`esp_log_level_set` 函数可以为各个模块分别设置不同的日志级别，可通过人类可读的 ASCII 零终止字符串标签来识别不同的模块。
|
||||
- **运行时**：启用 :ref:`CONFIG_LOG_MASTER_LEVEL` 时，可以使用 :cpp:func:`esp_log_set_level_master` 函数设置 ``主日志级别`` (Master logging level)。该选项会为所有已编译的日志添加额外的日志级别检查。注意，使用此选项会增加应用程序大小。如果希望在运行时编译大量可选日志，同时避免在不需要日志输出时查找标签及其级别带来的性能损耗，此功能会非常有用。
|
||||
|
||||
以下是不同的日志级别：
|
||||
|
||||
- 错误（Error，最低级别）
|
||||
- 警告 (Warning)
|
||||
- 普通 (Info)
|
||||
- 调试 (Debug)
|
||||
- 冗余（Verbose，最高级别）
|
||||
|
||||
.. note::
|
||||
|
||||
注意，函数 :cpp:func:`esp_log_level_set` 无法将日志级别设置为高于 :ref:`CONFIG_LOG_MAXIMUM_LEVEL` 指定的级别。如需在编译时将特定文件的日志级别提高到此最高级别以上，请使用 `LOG_LOCAL_LEVEL` 宏（详细信息见下文）。
|
||||
|
||||
|
||||
如何使用日志库
|
||||
-----------------------
|
||||
|
||||
在使用日志功能的所有 C 文件中，将 TAG 变量定义如下：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
static const char* TAG = "MyModule";
|
||||
|
||||
然后使用一个日志宏进行输出，例如：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
|
||||
|
||||
可使用下列宏来定义不同的日志级别：
|
||||
|
||||
* ``ESP_LOGE`` - 错误（最低级别）
|
||||
* ``ESP_LOGW`` - 警告
|
||||
* ``ESP_LOGI`` - 普通
|
||||
* ``ESP_LOGD`` - 调试
|
||||
* ``ESP_LOGV`` - 冗余（最高级别）
|
||||
|
||||
此外，上述宏还有对应的 ``ESP_EARLY_LOGx`` 版本，如 :c:macro:`ESP_EARLY_LOGE`。这些版本的宏必须在堆分配器和系统调用初始化之前，在早期启动代码中显式使用。通常情况下，编译引导加载程序时也可以使用普通的 ``ESP_LOGx`` 宏，但其最终实现与 ``ESP_EARLY_LOGx`` 宏相同。
|
||||
|
||||
上述宏还有对应的 ``ESP_DRAM_LOGx`` 版本，如 :c:macro:`ESP_DRAM_LOGE`。在禁用中断或无法访问 flash cache 的情况下需要输出日志时，可以使用这些版本的宏。但是，应尽量避免使用这些宏版本，因为在上述情况下输出日志可能会影响性能。
|
||||
|
||||
.. note::
|
||||
|
||||
在关键部分中断被禁用，因此只能使用 ``ESP_DRAM_LOGx``（首选）或 ``ESP_EARLY_LOGx`` 宏。尽管这样可以输出日志，但最好可以调整程序使其不用输出日志。
|
||||
|
||||
如需在文件或组件范围内覆盖默认的日志级别，请定义 ``LOG_LOCAL_LEVEL`` 宏。
|
||||
|
||||
在文件中，该宏应在包含 ``esp_log.h`` 文件前进行定义，例如：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
|
||||
#include "esp_log.h"
|
||||
|
||||
在组件中，该宏应在组件的 CMakeList 中进行定义：
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_compile_definitions(${COMPONENT_LIB} PUBLIC "-DLOG_LOCAL_LEVEL=ESP_LOG_VERBOSE")
|
||||
|
||||
如需在运行时按模块配置日志输出，请按如下方式调用 :cpp:func:`esp_log_level_set` 函数：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_log_level_set("*", ESP_LOG_ERROR); // 将所有组件的日志级别设置为错误 (ERROR) 级别
|
||||
esp_log_level_set("wifi", ESP_LOG_WARN); // 启用来自 WiFi 堆栈的警告 (WARN) 日志
|
||||
esp_log_level_set("dhcpc", ESP_LOG_INFO); // 启用来自 DHCP 客户端的普通 (INFO) 日志
|
||||
|
||||
.. note::
|
||||
|
||||
上文介绍的 "DRAM" 和 "EARLY" 日志宏变型不支持按照模块设置日志级别。这些宏始终以“默认”级别记录日志，且只能在运行时调用 ``esp_log_level("*", level)`` 对日志级别进行更改。
|
||||
|
||||
即使已通过标签名称禁用日志输出，每个条目仍需约 10.9 微秒的处理时间。
|
||||
|
||||
主日志级别
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
要启用主日志级别功能，须启用 :ref:`CONFIG_LOG_MASTER_LEVEL` 选项。该功能在调用 :cpp:func:`esp_log_write` 之前为 ``ESP_LOGx`` 宏添加了额外的级别检查。这样就可以设置更高的 :ref:`CONFIG_LOG_MAXIMUM_LEVEL`，并且不会在正常操作期间对性能造成影响（仅在有指示时）。应用程序可以全局设置主日志级别（:cpp:func:`esp_log_set_level_master`）以强制执行最高日志级别。高于此级别的 ``ESP_LOGx`` 宏将直接跳过，不会调用 :cpp:func:`esp_log_write` 并进行标签查找。建议只在顶层应用程序中使用此功能，不要在共享组件中使用，因为这将覆盖所有使用该组件的用户的全局日志级别。默认情况下，启动时主日志级别是 :ref:`CONFIG_LOG_DEFAULT_LEVEL`。
|
||||
|
||||
注意，由于此功能为所有 ``ESP_LOGx`` 宏添加了额外的检查，会导致应用程序的大小增加。
|
||||
|
||||
以下代码片段展示了主日志级别的运行方式。将主日志级别设置为 ``ESP_LOG_NONE`` 将在全局范围内禁用所有日志记录。:cpp:func:`esp_log_level_set` 目前不会影响日志记录。但在主日志级别释放后，日志将按照 :cpp:func:`esp_log_level_set` 中的设置打印输出。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// 在启动时，主日志级别为 CONFIG_LOG_DEFAULT_LEVEL，并等于ESP_LOG_INFO
|
||||
ESP_LOGI("lib_name", "用于打印的消息"); // 打印普通 (INFO) 级别消息
|
||||
esp_log_level_set("lib_name", ESP_LOG_WARN); // 启用 lib_name 的警告 (WARN) 日志
|
||||
|
||||
esp_log_set_level_master(ESP_LOG_NONE); // 全局禁用所有日志。esp_log_level_set 目前没有生效
|
||||
|
||||
ESP_LOGW("lib_name", "用于打印的消息"); // 主日志级别阻止了打印
|
||||
esp_log_level_set("lib_name", ESP_LOG_INFO); // 启用 lib_name 的 INFO 日志
|
||||
ESP_LOGI("lib_name", "用于打印的消息"); // 主日志级别阻止了打印
|
||||
|
||||
esp_log_set_level_master(ESP_LOG_INFO); // 全局启用所有 INFO 日志
|
||||
|
||||
ESP_LOGI("lib_name", "用于打印的消息"); // 打印一条 INFO 消息
|
||||
|
||||
通过 JTAG 将日志记录到主机
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
默认情况下，日志库使用类似 vprintf 的函数将格式化输出写入专用 UART。通过调用一个简单的 API，即可将所有日志通过 JTAG 输出，将日志输出速度提高数倍。如需了解详情，请参阅 :ref:`app_trace-logging-to-host`。
|
||||
|
||||
线程安全
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
日志字符串首先被写入内存 buffer，然后发送到 UART 打印。日志调用是线程安全的，即不同线程的日志不会互相冲突。
|
||||
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
大多数 ESP-IDF 组件和示例都会使用日志库。如需查看有关日志功能的应用示例，请前往 ESP-IDF 的 :idf:`examples` 目录。与日志最相关的示例如下：
|
||||
|
||||
* :example:`system/ota`
|
||||
* :example:`storage/sd_card`
|
||||
* :example:`protocols/https_request`
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_log.inc
|
||||
|
||||
@@ -1 +1,87 @@
|
||||
.. include:: ../../../en/api-reference/system/random.rst
|
||||
随机数发生器
|
||||
========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
{IDF_TARGET_RF_NAME: default="Wi-Fi 或蓝牙", esp32s2="Wi-Fi", esp32h2="蓝牙或 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee"}
|
||||
{IDF_TARGET_RF_IS: default="已启用", esp32s2="已启用"}
|
||||
{IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE: default="", esp32="I2S、"}
|
||||
|
||||
{IDF_TARGET_NAME} 中包含一个硬件随机数发生器 (RNG)，可以调用 API :cpp:func:`esp_random` 和 :cpp:func:`esp_fill_random` 从中获取随机数值。
|
||||
|
||||
满足下列任意一个或多个条件时，硬件 RNG 会产生真随机数：
|
||||
|
||||
- RF 子系统已启用，即 {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS}。
|
||||
- 调用 :cpp:func:`bootloader_random_enable` 启用了内部熵源，并且熵源尚未被 :cpp:func:`bootloader_random_disable` 禁用。
|
||||
- 在 ESP-IDF :ref:`second-stage-bootloader` 运行时。这是因为默认的 ESP-IDF 引导加载程序启动时会调用 :cpp:func:`bootloader_random_enable`，并在执行应用程序前调用 :cpp:func:`bootloader_random_disable`。
|
||||
|
||||
当上述任一条件为真时，物理噪声样本会连续混合到内部硬件 RNG 状态中来提供熵。如需了解详情，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **随机数发生器 (RNG)** [`PDF <{IDF_TARGET_TRM_CN_URL}#rng>`__] 章节。
|
||||
|
||||
如果上述条件都不满足，那么 RNG 的输出仅应被看作伪随机数。
|
||||
|
||||
启动
|
||||
-------
|
||||
|
||||
在启动过程中，ESP-IDF 引导加载程序暂时会启用一个非 RF 熵源（内部参考电压噪声），为首次生成的启动密钥提供熵。当应用程序开始执行后，一直到 {IDF_TARGET_RF_NAME} 初始化完成前，通常只有伪随机数可用。
|
||||
|
||||
如需在应用程序启动期间临时重启熵源，或为不使用 {IDF_TARGET_RF_NAME} 的应用程序临时重启熵源，请调用函数 :cpp:func:`bootloader_random_enable` 重启内部熵源。在使用 ADC、{IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE} 或使用 {IDF_TARGET_RF_NAME} 前，必须调用函数 :cpp:func:`bootloader_random_disable` 以禁用熵源。
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-IDF 第二阶段引导加载程序在启动过程中启用的熵源会用熵来初始化内部 RNG 状态。但是，内部硬件 RNG 状态的大小并不足以提供连续的真随机数流。因此，在需要真随机数时必须启用连续的熵源。
|
||||
|
||||
.. note::
|
||||
|
||||
如果应用程序需要真随机数源，但无法永久性地启用硬件熵源，可以考虑使用软件 DRBG （确定性随机数发生器）来实现，如 mbedTLS CTR-DRBG 或 HMAC-DRBG，并使用来自硬件 RNG 真随机数来获取初始熵。
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
二级熵源
|
||||
-----------------
|
||||
|
||||
{IDF_TARGET_NAME} RNG 包含一个基于异步 8 MHz 内部振荡器采样的二级熵源（详情请参阅技术参考手册）。该熵源在 ESP-IDF 中始终处于启用状态，并通过硬件持续混合到 RNG 状态中。在测试中，即使在不启用主熵源时，这个二级熵源也足以通过 `Dieharder`_ 随机数测试套件（测试输入数据是通过连续重置 {IDF_TARGET_NAME} 生成短样本并将其拼接来创建的）。但是，目前只有在同时启用上文所述的主熵源时，才能保证产生真随机数。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_random.inc
|
||||
.. include-build-file:: inc/bootloader_random.inc
|
||||
|
||||
``getrandom()``
|
||||
---------------
|
||||
|
||||
为方便移植，还提供了与 Linux 的 ``getrandom()`` 函数兼容的版本：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <sys/random.h>
|
||||
|
||||
ssize_t getrandom(void *buf, size_t buflen, unsigned int flags);
|
||||
|
||||
此函数通过内部调用 :cpp:func:`esp_fill_random` 来实现。
|
||||
|
||||
``flags`` 参数将被忽略。该函数始终是非阻塞的，但随机数的强度取决于本文档所述条件。
|
||||
|
||||
如果 ``buf`` 参数为 NULL，返回值为 -1，并将 ``errno`` 设置为 ``EFAULT``。否则返回 ``buflen``。
|
||||
|
||||
``getentropy()``
|
||||
----------------
|
||||
|
||||
为了便于移植，还提供了与 Linux 的 ``getentropy()`` 函数兼容的版本：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <unistd.h>
|
||||
|
||||
int getentropy(void *buffer, size_t length);
|
||||
|
||||
此函数通过内部调用 :cpp:func:`getrandom` 实现。
|
||||
|
||||
随机数强度取决于本文档所述条件。
|
||||
|
||||
如果执行成功则返回 0，否则返回 -1，同时：
|
||||
|
||||
- 如果 ``buffer`` 参数为 NULL，``errno`` 设置为 ``EFAULT``。
|
||||
- 如果 ``length`` 超过 256，``errno`` 设置为 ``EIO``。
|
||||
|
||||
.. _Dieharder: https://webhome.phy.duke.edu/~rgb/General/dieharder.php
|
||||
|
||||
Reference in New Issue
Block a user