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

docs: Provide Chinese translation for bootloader_image_format, log, random, and internal-unstable.rst

Browse Source
This commit is contained in:
renpeiying
2023-09-26 15:47:19 +08:00
committed by Linda
parent b486466339
commit cf03d6341e
11 changed files with 482 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/system/bootloader_image_format.rst
+14 -9
View File
@@ -1,13 +1,17 @@
Bootloader Image Format
=======================
The bootloader image consists of the same structures as the application image, see :ref:`Application Image Structures <app-image-structures>`. The only difference is in the :ref:`Bootloader Description <image-format-bootloader-description>` structure.
:link_to_translation:`zh_CN:[中文]`
The bootloader image consists of the same structures as the application image, see :ref:`Application Image Structures <app-image-structures>`. The only difference is in the :ref:`image-format-bootloader-description` structure.
To get information about the bootloader image, please run the following command:
.. code-block::
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/bootloader/bootloader.bin --version 2
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/bootloader/bootloader.bin --version 2
The resultant output will resemble the following:
.. code-block::
@@ -50,6 +54,7 @@ To get information about the bootloader image, please run the following command:
ESP-IDF: v5.1-dev-4304-gcb51a3b-dirty
Compile time: Mar 30 2023 19:14:17
.. _image-format-bootloader-description:
Bootloader Description
@@ -57,14 +62,14 @@ Bootloader Description
The ``DRAM0`` segment of the bootloader binary starts with the :cpp:type:`esp_bootloader_desc_t` structure which carries specific fields describing the bootloader. This structure is located at a fixed offset = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`).
* ``magic_byte`` - the magic byte for the esp_bootloader_desc structure.
* ``reserved`` - reserved for the future IDF use.
* ``version`` - bootloader version, see :ref:`CONFIG_BOOTLOADER_PROJECT_VER`
* ``idf_ver`` - ESP-IDF version. ``*``
* ``date`` and ``time`` - compile date and time.
* ``reserved2`` - reserved for the future IDF use.
* ``magic_byte``: the magic byte for the esp_bootloader_desc structure
* ``reserved``: reserved for the future IDF use
* ``version``: bootloader version, see :ref:`CONFIG_BOOTLOADER_PROJECT_VER`
* ``idf_ver``: ESP-IDF version. [#f1]_
* ``date`` and ``time``: compile date and time
* ``reserved2``: reserved for the future IDF use
``*`` - The maximum length is 32 characters, including null-termination character.
.. [#f1] The maximum length is 32 characters, including null-termination character.
To get the :cpp:type:`esp_bootloader_desc_t` structure from the running bootloader, use :cpp:func:`esp_bootloader_get_description`.
docs/en/api-reference/system/internal-unstable.rst
+2
View File
@@ -1,6 +1,8 @@
Internal and Unstable APIs
==========================
:link_to_translation:`zh_CN:[中文]`
This section is listing some APIs that are internal or likely to be changed or removed in the next releases of ESP-IDF.
docs/en/api-reference/system/log.rst
+123 -4
View File
@@ -1,4 +1,126 @@
.. include:: ../../../../components/log/README.rst
Logging library
===============
:link_to_translation:`zh_CN:[中文]`
Overview
--------
The logging library provides three ways for setting log verbosity:
- **At compile time**: in menuconfig, set the verbosity level using the option :ref:`CONFIG_LOG_DEFAULT_LEVEL`.
- Optionally, also in menuconfig, set the maximum verbosity level using the option :ref:`CONFIG_LOG_MAXIMUM_LEVEL`. By default, this is the same as the default level, but it can be set higher in order to compile more optional logs into the firmware.
- **At runtime**: all logs for verbosity levels lower than :ref:`CONFIG_LOG_DEFAULT_LEVEL` are enabled by default. The function :cpp:func:`esp_log_level_set` can be used to set a logging level on a per-module basis. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
- **At runtime**: if :ref:`CONFIG_LOG_MASTER_LEVEL` is enabled then a ``Master logging level`` can be set using :cpp:func:`esp_log_set_level_master`. This option adds an additional logging level check for all compiled logs. Note that this will increase application size. This feature is useful if you want to compile a lot of logs that are selectable at runtime, but also want to avoid the performance hit from looking up the tags and their log level when you don't want log output.
There are the following verbosity levels:
- Error (lowest)
- Warning
- Info
- Debug
- Verbose (highest)
.. note::
The function :cpp:func:`esp_log_level_set` cannot set logging levels higher than specified by :ref:`CONFIG_LOG_MAXIMUM_LEVEL`. To increase log level for a specific file above this maximum at compile time, use the macro `LOG_LOCAL_LEVEL` (see the details below).
How to Use Logging Library
--------------------------
In each C file that uses logging functionality, define the TAG variable as shown below:
.. code-block:: c
static const char* TAG = "MyModule";
Then use one of logging macros to produce output, e.g:
.. code-block:: c
ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
Several macros are available for different verbosity levels:
* ``ESP_LOGE`` - Error (lowest)
* ``ESP_LOGW`` - Warning
* ``ESP_LOGI`` - Info
* ``ESP_LOGD`` - Debug
* ``ESP_LOGV`` - Verbose (highest)
Additionally, there are ``ESP_EARLY_LOGx`` versions for each of these macros, e.g. :c:macro:`ESP_EARLY_LOGE`. These versions have to be used explicitly in the early startup code only, before heap allocator and syscalls have been initialized. Normal ``ESP_LOGx`` macros can also be used while compiling the bootloader, but they will fall back to the same implementation as ``ESP_EARLY_LOGx`` macros.
There are also ``ESP_DRAM_LOGx`` versions for each of these macros, e.g. :c:macro:`ESP_DRAM_LOGE`. These versions are used in some places where logging may occur with interrupts disabled or with flash cache inaccessible. Use of this macros should be as sparse as possible, as logging in these types of code should be avoided for performance reasons.
.. note::
Inside critical sections interrupts are disabled so it's only possible to use ``ESP_DRAM_LOGx`` (preferred) or ``ESP_EARLY_LOGx``. Even though it's possible to log in these situations, it's better if your program can be structured not to require it.
To override default verbosity level at file or component scope, define the ``LOG_LOCAL_LEVEL`` macro.
At file scope, define it before including ``esp_log.h``, e.g.:
.. code-block:: c
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
#include "esp_log.h"
At component scope, define it in the component CMakeLists:
.. code-block:: cmake
target_compile_definitions(${COMPONENT_LIB} PUBLIC "-DLOG_LOCAL_LEVEL=ESP_LOG_VERBOSE")
To configure logging output per module at runtime, add calls to the function :cpp:func:`esp_log_level_set` as follows:
.. code-block:: c
esp_log_level_set("*", ESP_LOG_ERROR); // set all components to ERROR level
esp_log_level_set("wifi", ESP_LOG_WARN); // enable WARN logs from WiFi stack
esp_log_level_set("dhcpc", ESP_LOG_INFO); // enable INFO logs from DHCP client
.. note::
The "DRAM" and "EARLY" log macro variants documented above do not support per module setting of log verbosity. These macros will always log at the "default" verbosity level, which can only be changed at runtime by calling ``esp_log_level("*", level)``.
Even when logs are disabled by using a tag name, they will still require a processing time of around 10.9 microseconds per entry.
Master Logging Level
^^^^^^^^^^^^^^^^^^^^
To enable the Master logging level feature, the :ref:`CONFIG_LOG_MASTER_LEVEL` option must be enabled. It adds an additional level check for ``ESP_LOGx`` macros before calling :cpp:func:`esp_log_write`. This allows to set a higher :ref:`CONFIG_LOG_MAXIMUM_LEVEL`, but not inflict a performance hit during normal operation (only when directed). An application may set the master logging level (:cpp:func:`esp_log_set_level_master`) globally to enforce a maximum log level. ``ESP_LOGx`` macros above this level will be skipped immediately, rather than calling :cpp:func:`esp_log_write` and doing a tag lookup. It is recommended to only use this in an top-level application and not in shared components as this would override the global log level for any user using the component. By default, at startup, the Master logging level is :ref:`CONFIG_LOG_DEFAULT_LEVEL`.
Note that this feature increases application size because the additional check is added into all ``ESP_LOGx`` macros.
The snippet below shows how it works. Setting the Master logging level to ``ESP_LOG_NONE`` disables all logging globally. :cpp:func:`esp_log_level_set` does not currently affect logging. But after the Master logging level is released, the logs will be printed as set by :cpp:func:`esp_log_level_set`.
.. code-block:: c
// Master logging level is CONFIG_LOG_DEFAULT_LEVEL at start up and = ESP_LOG_INFO
ESP_LOGI("lib_name", "Message for print"); // prints a INFO message
esp_log_level_set("lib_name", ESP_LOG_WARN); // enables WARN logs from lib_name
esp_log_set_level_master(ESP_LOG_NONE); // disables all logs globally. esp_log_level_set has no effect at the moment
ESP_LOGW("lib_name", "Message for print"); // no print, Master logging level blocks it
esp_log_level_set("lib_name", ESP_LOG_INFO); // enable INFO logs from lib_name
ESP_LOGI("lib_name", "Message for print"); // no print, Master logging level blocks it
esp_log_set_level_master(ESP_LOG_INFO); // enables all INFO logs globally
ESP_LOGI("lib_name", "Message for print"); // prints a INFO message
Logging to Host via JTAG
^^^^^^^^^^^^^^^^^^^^^^^^
By default, the logging library uses the vprintf-like function to write formatted output to the dedicated UART. By calling a simple API, all log output may be routed to JTAG instead, making logging several times faster. For details, please refer to Section :ref:`app_trace-logging-to-host`.
Thread Safety
^^^^^^^^^^^^^
The log string is first written into a memory buffer and then sent to the UART for printing. Log calls are thread-safe, i.e., logs of different threads do not conflict with each other.
Application Example
-------------------
@@ -13,6 +135,3 @@ API Reference
-------------
.. include-build-file:: inc/esp_log.inc
docs/en/api-reference/system/random.rst
+23 -21
View File
@@ -1,43 +1,45 @@
Random Number Generation
========================
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi", esp32h2="Bluetooth or 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee"}
{IDF_TARGET_RF_IS: default="are", esp32s2="is"}
{IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE: default="", esp32="I2S, "}
{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using the APIs :cpp:func:`esp_random` and :cpp:func:`esp_fill_random`.
{IDF_TARGET_NAME} contains a hardware random number generator (RNG). You can use the APIs :cpp:func:`esp_random` and :cpp:func:`esp_fill_random` to obtained random values from it.
The hardware RNG produces true random numbers under any of the following conditions:
The hardware RNG produces true random numbers so long as one or more of the following conditions are met:
- RF subsystem is enabled (i.e., {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} enabled).
- RF subsystem is enabled. i.e., {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} enabled.
- An internal entropy source has been enabled by calling :cpp:func:`bootloader_random_enable` and not yet disabled by calling :cpp:func:`bootloader_random_disable`.
- While the ESP-IDF :ref:`second-stage-bootloader` is running. This is because the default ESP-IDF bootloader implementation calls :cpp:func:`bootloader_random_enable` when the bootloader starts, and :cpp:func:`bootloader_random_disable` before executing the app.
- While the ESP-IDF :ref:`second-stage-bootloader` is running. This is because the default ESP-IDF bootloader implementation calls :cpp:func:`bootloader_random_enable` when the bootloader starts, and :cpp:func:`bootloader_random_disable` before executing the application.
When any of these conditions are true, samples of physical noise are continuously mixed into the internal hardware RNG state to provide entropy. Consult the **{IDF_TARGET_NAME} Technical Reference Manual** > **Random Number Generator (RNG)** [`PDF <{IDF_TARGET_TRM_EN_URL}#rng>`__] chapter for more details.
When any of these conditions are true, samples of physical noise are continuously mixed into the internal hardware RNG state to provide entropy. Consult the **{IDF_TARGET_NAME} Technical Reference Manual** > **Random Number Generator (RNG)** [`PDF <{IDF_TARGET_TRM_EN_URL}#rng>`__] chapter for more details.
If none of the above conditions are true, the output of the RNG should be considered pseudo-random only.
If none of the above conditions are true, the output of the RNG should be considered as pseudo-random only.
Startup
-------
During startup, ESP-IDF bootloader temporarily enables a non-RF entropy source (internal reference voltage noise) that provides entropy for any first boot key generation. However, after the app starts executing then normally only pseudo-random numbers are available until {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} initialized.
During startup, ESP-IDF bootloader temporarily enables a non-RF entropy source (internal reference voltage noise) that provides entropy for any first boot key generation. However, after the application starts executing, then normally only pseudo-random numbers are available until {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} initialized.
To re-enable the entropy source temporarily during app startup, or for an application that does not use {IDF_TARGET_RF_NAME}, call the function :cpp:func:`bootloader_random_enable` to re-enable the internal entropy source. The function :cpp:func:`bootloader_random_disable` must be called to disable the entropy source again before using ADC, {IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE}{IDF_TARGET_RF_NAME}.
To re-enable the entropy source temporarily during application startup, or for an application that does not use {IDF_TARGET_RF_NAME}, call the function :cpp:func:`bootloader_random_enable` to re-enable the internal entropy source. The function :cpp:func:`bootloader_random_disable` must be called to disable the entropy source again before using ADC, {IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE} {IDF_TARGET_RF_NAME}.
.. note::
The entropy source enabled during the boot process by the ESP-IDF Second Stage Bootloader seeds the internal RNG state with some entropy. However, the internal hardware RNG state is not large enough to provide a continuous stream of true random numbers. This is why a continuous entropy source must be enabled whenever true random numbers are required.
The entropy source enabled during the boot process by the ESP-IDF Second Stage Bootloader seeds the internal RNG state with some entropy. However, the internal hardware RNG state is not large enough to provide a continuous stream of true random numbers. This is why a continuous entropy source must be enabled whenever true random numbers are required.
.. note::
If an application requires a source of true random numbers but it is not possible to permanently enable a hardware entropy source, consider using a strong software DRBG implementation such as the mbedTLS CTR-DRBG or HMAC-DRBG, with an initial seed of entropy from hardware RNG true random numbers.
If an application requires a source of true random numbers but cannot permanently enable a hardware entropy source, consider using a strong software DRBG implementation such as the mbedTLS CTR-DRBG or HMAC-DRBG, with an initial seed of entropy from hardware RNG true random numbers.
.. only:: not esp32
Secondary Entropy
-----------------
{IDF_TARGET_NAME} RNG contains a secondary entropy source, based on sampling an asynchronous 8 MHz internal oscillator (see the Technical Reference Manual for details). This entropy source is always enabled in ESP-IDF and continuously mixed into the RNG state by hardware. In testing, this secondary entropy source was sufficient to pass the `Dieharder`_ random number test suite without the main entropy source enabled (test input was created by concatenating short samples from a continuously resetting {IDF_TARGET_NAME}). However, it is currently only guaranteed that true random numbers are produced when the main entropy source is also enabled as described above.
{IDF_TARGET_NAME} RNG contains a secondary entropy source, based on sampling an asynchronous 8 MHz internal oscillator (see the Technical Reference Manual for details). This entropy source is always enabled in ESP-IDF and is continuously mixed into the RNG state by hardware. In testing, this secondary entropy source was sufficient to pass the `Dieharder`_ random number test suite without the main entropy source enabled (test input was created by concatenating short samples from continuously resetting {IDF_TARGET_NAME}). However, it is currently only guaranteed that true random numbers are produced when the main entropy source is also enabled as described above.
API Reference
-------------
@@ -52,34 +54,34 @@ A compatible version of the Linux ``getrandom()`` function is also provided for
.. code-block:: c
#include <sys/random.h>
#include <sys/random.h>
ssize_t getrandom(void *buf, size_t buflen, unsigned int flags);
ssize_t getrandom(void *buf, size_t buflen, unsigned int flags);
This function is implemented by calling :cpp:func:`esp_fill_random` internally.
The ``flags`` argument is ignored, this function is always non-blocking but the strength of any random numbers is dependent on the same conditions described above.
The ``flags`` argument is ignored. This function is always non-blocking but the strength of any random numbers is dependent on the same conditions described above.
Return value is -1 (with ``errno`` set to ``EFAULT``) if the ``buf`` argument is NULL, and equal to ``buflen`` otherwise.
``getentropy()``
----------------
A compatible version of the Linux ``getentropy()`` function is also provided for ease of porting:
A compatible version of the Linux ``getentropy()`` function is also provided for easy porting:
.. code-block:: c
#include <unistd.h>
#include <unistd.h>
int getentropy(void *buffer, size_t length);
int getentropy(void *buffer, size_t length);
This function is implemented by calling :cpp:func:`getrandom` internally.
Strength of any random numbers is dependent on the same conditions described above.
The strength of any random numbers is dependent on the same conditions described above.
Return value is 0 on success and -1 otherwise with ``errno`` set to:
- ``EFAULT`` if the ``buffer`` argument is NULL.
- ``EIO`` if the ``length`` is more then 256.
- ``EFAULT`` if the ``buffer`` argument is NULL.
- ``EIO`` if the ``length`` is more then 256.
.. _Dieharder: https://webhome.phy.duke.edu/~rgb/General/dieharder.php