mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/add_cn_trans_for_bootloader_image_format_and_random.rst' into 'master'
docs: Provide Chinese translation for bootloader_image_format, log, random, and internal-unstable.rst Closes DOC-6419 See merge request espressif/esp-idf!26224
This commit is contained in:
Zhang Xiao Yan
commit
bba48f1e1e
@ -1,120 +1 @@
|
||||
Logging library
|
||||
===============
|
||||
|
||||
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 in 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 this 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 sparing 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.
|
||||
Please see :doc:`docs/en/api-reference/system/log.rst` for more details.
|
||||
@ -1,6 +1,7 @@
|
||||
*************
|
||||
API Reference
|
||||
*************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
********
|
||||
API 参考
|
||||
********
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user