mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-07 20:00:53 +00:00
Merge branch 'docs/update_cn_translation' into 'master'
docs: Sync CN and EN docs Closes DOC-9614 See merge request espressif/esp-idf!35256
This commit is contained in:
Shen Meng Jing
@@ -474,7 +474,7 @@ The number of IP addresses returned by network database APIs such as ``getaddrin
|
||||
|
||||
In the implementation of ``getaddrinfo()``, the canonical name is not available. Therefore, the ``ai_canonname`` field of the first returned ``addrinfo`` structure will always refer to the ``nodename`` argument or a string with the same contents.
|
||||
|
||||
The ``getaddrinfo()`` system call in lwIP within ESP-IDF has a limitation when using ``AF_UNSPEC``, as it defaults to returning only an IPv4 address in dual stack mode. This can cause issues in IPv6-only networks. To handle this, a workaround involves making two sequential calls to ``getaddrinfo()``: the first with AF_INET to query for IPv4 addresses, and the second with AF_INET6 to retrieve IPv6 addresses. To address this, the custom ``esp_getaddrinfo()`` function has been added to the lwIP port layer to handle both IPv4 and IPv6 addresses when AF_UNSPEC is used. The :ref:`CONFIG_LWIP_USE_ESP_GETADDRINFO` option, available when both IPv4 and IPv6 are enabled, controls whether ``esp_getaddrinfo()`` or the default lwIP implementation is used. It is disabled by default.
|
||||
The ``getaddrinfo()`` system call in lwIP within ESP-IDF has a limitation when using ``AF_UNSPEC``, as it defaults to returning only an IPv4 address in dual stack mode. This can cause issues in IPv6-only networks. To handle this, a workaround involves making two sequential calls to ``getaddrinfo()``: the first with ``AF_INET`` to query for IPv4 addresses, and the second with ``AF_INET6`` to retrieve IPv6 addresses. To provide a more robust solution, the custom ``esp_getaddrinfo()`` function has been added to the lwIP port layer to handle both IPv4 and IPv6 addresses when ``AF_UNSPEC`` is used. The :ref:`CONFIG_LWIP_USE_ESP_GETADDRINFO` option, available when both IPv4 and IPv6 are enabled, controls whether ``esp_getaddrinfo()`` or ``getaddrinfo()`` is used. It is disabled by default.
|
||||
|
||||
Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This failure occurs due to the limitations of buffer sizes in the lower-layer network interface drivers. If all driver transmit buffers are full, the UDP transmission will fail. For applications that transmit a high volume of UDP datagrams and aim to avoid any dropped datagrams by the sender, it is advisable to implement error code checking and employ a retransmission mechanism with a short delay.
|
||||
|
||||
|
||||
@@ -115,8 +115,7 @@ In the OpenThread protocol stack, defining macros to enable features and configu
|
||||
|
||||
.. note::
|
||||
|
||||
The priority of the above configuration methods, from highest to lowest, is as follows:
|
||||
Configuration Menu → User-defined Header File → openthread-core-esp32x-xxx-config.h → OpenThread Stack Default Configuration
|
||||
The priority of the above configuration methods, from highest to lowest, is as follows: Configuration Menu → User-defined Header File → openthread-core-esp32x-xxx-config.h → OpenThread Stack Default Configuration
|
||||
|
||||
The OpenThread Border Router
|
||||
----------------------------
|
||||
|
||||
@@ -54,7 +54,7 @@ Here is the summary printed for the "Factory app, two OTA definitions" configura
|
||||
Creating Custom Tables
|
||||
----------------------
|
||||
|
||||
If you choose "Custom partition table CSV" in menuconfig then you can also enter the name of a CSV file (in the project directory) to use for your partition table. The CSV file can describe any number of definitions for the table you need.
|
||||
If you choose "Custom partition table CSV" in ``menuconfig``, then you can also enter the name of a CSV file (in the project directory) to use for your partition table. The CSV file can describe any number of definitions for the table you need.
|
||||
|
||||
The CSV format is the same format as printed in the summaries shown above. However, not all fields are required in the CSV. For example, here is the "input" CSV for the OTA partition table:
|
||||
|
||||
@@ -135,18 +135,18 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
|
||||
|
||||
* When type is ``bootloader``, the SubType field can be specified as:
|
||||
|
||||
- ``primary`` (0x00). This is the 2nd stage bootloader, located at the {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} address in flash memory. The tool automatically determines the appropriate size and offset for this subtype, so any size or offset specified for this subtype will be ignored. You can either leave these fields blank or use ``N/A`` as a placeholder.
|
||||
- ``ota`` (0x01). This is a temporary bootloader partition used by the bootloader OTA update functionality to download a new image. The tool ignores the size for this subtype, allowing you to leave it blank or use ``N/A``. You can only specify an offset, or leave it blank to have the tool calculate it based on the offsets of previously used partitions.
|
||||
- ``recovery`` (0x02). This is the recovery bootloader partition used for safely performing OTA updates to the bootloader. The ``gen_esp32part.py`` tool automatically determines the address and size for this partition, so you can leave these fields blank or use ``N/A`` as a placeholder. The address must match an eFuse field, which is defined through a Kconfig option. If the normal bootloader loading path fails, the ROM bootloader will attempt to load the recovery partition at the address specified by the eFuse field.
|
||||
- ``primary`` (0x00). This is the 2nd stage bootloader, located at the {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} address in flash memory. The tool automatically determines the appropriate size and offset for this subtype, so any size or offset specified for this subtype will be ignored. You can either leave these fields blank or use ``N/A`` as a placeholder.
|
||||
- ``ota`` (0x01). This is a temporary bootloader partition used by the bootloader OTA update functionality to download a new image. The tool ignores the size for this subtype, allowing you to leave it blank or use ``N/A``. You can only specify an offset, or leave it blank to have the tool calculate it based on the offsets of previously used partitions.
|
||||
- ``recovery`` (0x02). This is the recovery bootloader partition used for safely performing OTA updates to the bootloader. The ``gen_esp32part.py`` tool automatically determines the address and size for this partition, so you can leave these fields blank or use ``N/A`` as a placeholder. The address must match an eFuse field, which is defined through a Kconfig option. If the normal bootloader loading path fails, the first stage (ROM) bootloader will attempt to load the recovery partition at the address specified by the eFuse field.
|
||||
|
||||
The size of the bootloader type is calculated by the ``gen_esp32part.py`` tool based on the specified ``--offset`` (the partition table offset) and ``--primary-partition-offset`` arguments. Specifically, the bootloader size is defined as (:ref:`CONFIG_PARTITION_TABLE_OFFSET` - {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}). This calculated size applies to all subtypes of the bootloader.
|
||||
The size of the bootloader type is calculated by the ``gen_esp32part.py`` tool based on the specified ``--offset`` (the partition table offset) and ``--primary-partition-offset`` arguments. Specifically, the bootloader size is defined as (:ref:`CONFIG_PARTITION_TABLE_OFFSET` - {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}). This calculated size applies to all subtypes of the bootloader.
|
||||
|
||||
* When type is ``partition_table``, the SubType field can be specified as:
|
||||
|
||||
- ``primary`` (0x00). This is the primary partition table, located at the :ref:`CONFIG_PARTITION_TABLE_OFFSET` address in flash memory. The tool automatically determines the appropriate size and offset for this subtype, so any size or offset specified for this subtype will be ignored. You can either leave these fields blank or use ``N/A`` as a placeholder.
|
||||
- ``ota`` (0x01). It is a temporary partition table partition used by the partition table OTA update functionality for downloading a new image. The tool ignores the size for this subtype, allowing you to leave it blank or use ``N/A``. You can specify an offset, or leave it blank, in which case the tool will calculate it based on the offsets of previously allocated partitions.
|
||||
- ``primary`` (0x00). This is the primary partition table, located at the :ref:`CONFIG_PARTITION_TABLE_OFFSET` address in flash memory. The tool automatically determines the appropriate size and offset for this subtype, so any size or offset specified for this subtype will be ignored. You can either leave these fields blank or use ``N/A`` as a placeholder.
|
||||
- ``ota`` (0x01). It is a temporary partition table partition used by the partition table OTA update functionality for downloading a new image. The tool ignores the size for this subtype, allowing you to leave it blank or use ``N/A``. You can specify an offset, or leave it blank, in which case the tool will calculate it based on the offsets of previously allocated partitions.
|
||||
|
||||
The size for the ``partition_table`` type is fixed at ``0x1000`` and applies uniformly across all subtypes of ``partition_table``.
|
||||
The size for the ``partition_table`` type is fixed at ``0x1000`` and applies uniformly across all subtypes of ``partition_table``.
|
||||
|
||||
* When type is ``data``, the subtype field can be specified as ``ota`` (0x00), ``phy`` (0x01), ``nvs`` (0x02), nvs_keys (0x04), or a range of other component-specific subtypes (see :cpp:type:`subtype enum <esp_partition_subtype_t>`).
|
||||
|
||||
@@ -220,15 +220,15 @@ Two flags are currently supported, ``encrypted`` and ``readonly``:
|
||||
|
||||
.. note::
|
||||
|
||||
The following type partitions will always be encrypted, regardless of whether this flag is set or not:
|
||||
The following type partitions will always be encrypted, regardless of whether this flag is set or not:
|
||||
|
||||
.. list::
|
||||
.. list::
|
||||
|
||||
- ``app``,
|
||||
- ``bootloader``,
|
||||
- ``partition_table``,
|
||||
- type ``data`` and subtype ``ota``,
|
||||
- type ``data`` and subtype ``nvs_keys``.
|
||||
- ``app``,
|
||||
- ``bootloader``,
|
||||
- ``partition_table``,
|
||||
- type ``data`` and subtype ``ota``,
|
||||
- type ``data`` and subtype ``nvs_keys``.
|
||||
|
||||
- If ``readonly`` flag is set, the partition will be read-only. This flag is only supported for ``data`` type partitions except ``ota`` and ``coredump`` subtypes. This flag can help to protect against accidental writes to a partition that contains critical device-specific configuration data, e.g., factory data partition.
|
||||
|
||||
|
||||
@@ -67,7 +67,7 @@ The map file itself is broken into parts and each part has a heading. The parts
|
||||
|
||||
.. note::
|
||||
|
||||
Linker map files are generated by the GNU binutils linker ``ld``, not ESP-IDF. You can find additional information online about the linker map file format. This quick summary is written from the perspective of ESP-IDF build system in particular.
|
||||
Linker map files are generated by the GNU binutils linker ``ld``, not ESP-IDF. You can find additional information online about the linker map file format. This quick summary is written from the perspective of ESP-IDF build system in particular.
|
||||
|
||||
.. _reducing-overall-size:
|
||||
|
||||
@@ -94,7 +94,7 @@ The following configuration options reduces the final binary size of almost any
|
||||
|
||||
.. note::
|
||||
|
||||
In addition to the many configuration items shown here, there are a number of configuration options where changing the option from the default increases binary size. These are not noted here. Where the increase is significant is usually noted in the configuration item help text.
|
||||
In addition to the many configuration items shown here, there are a number of configuration options where changing the option from the default increases binary size. These are not noted here. Where the increase is significant is usually noted in the configuration item help text.
|
||||
|
||||
.. _size-targeted-optimizations:
|
||||
|
||||
@@ -147,9 +147,9 @@ lwIP IPv4
|
||||
|
||||
- If IPv4 connectivity is not required, setting :ref:`CONFIG_LWIP_IPV4` to ``false`` will reduce the size of the lwIP, supporting IPv6-only TCP/IP stack.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
Before disabling IPv4 support, please note that IPv6 only network environments are not ubiquitous and must be supported in the local network, e.g., by your internet service provider or using constrained local network settings.
|
||||
Before disabling IPv4 support, please note that IPv6 only network environments are not ubiquitous and must be supported in the local network, e.g., by your internet service provider or using constrained local network settings.
|
||||
|
||||
.. _picolibc-instead-of-newlib:
|
||||
|
||||
@@ -224,21 +224,22 @@ The help text for each option has some more information for reference.
|
||||
|
||||
.. important::
|
||||
|
||||
It is **strongly not recommended to disable all these mbedTLS options**. Only disable options of which you understand the functionality and are certain that it is not needed in the application. In particular:
|
||||
It is **strongly not recommended to disable all these mbedTLS options**. Only disable options of which you understand the functionality and are certain that it is not needed in the application. In particular:
|
||||
|
||||
- Ensure that any TLS server(s) the device connects to can still be used. If the server is controlled by a third party or a cloud service, it is recommended to ensure that the firmware supports at least two of the supported cipher suites in case one is disabled in a future update.
|
||||
- Ensure that any TLS client(s) that connect to the device can still connect with supported/recommended cipher suites. Note that future versions of client operating systems may remove support for some features, so it is recommended to enable multiple supported cipher suites, or algorithms for redundancy.
|
||||
- Ensure that any TLS server(s) the device connects to can still be used. If the server is controlled by a third party or a cloud service, it is recommended to ensure that the firmware supports at least two of the supported cipher suites in case one is disabled in a future update.
|
||||
- Ensure that any TLS client(s) that connect to the device can still connect with supported/recommended cipher suites. Note that future versions of client operating systems may remove support for some features, so it is recommended to enable multiple supported cipher suites, or algorithms for redundancy.
|
||||
|
||||
If depending on third party clients or servers, always pay attention to announcements about future changes to supported TLS features. If not, the {IDF_TARGET_NAME} device may become inaccessible if support changes.
|
||||
If depending on third party clients or servers, always pay attention to announcements about future changes to supported TLS features. If not, the {IDF_TARGET_NAME} device may become inaccessible if support changes.
|
||||
|
||||
.. only:: CONFIG_ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB
|
||||
|
||||
Enabling the config option :ref:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from mbedTLS library inside the chip ROM.
|
||||
Disabling the config option :ref:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from the ESP-IDF mbedtls component library. This will increase the binary size (flash footprint).
|
||||
Enabling the config option :ref:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from mbedTLS library inside the chip ROM.
|
||||
|
||||
Disabling the config option :ref:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from the ESP-IDF mbedtls component library. This will increase the binary size (flash footprint).
|
||||
|
||||
.. note::
|
||||
|
||||
Not every combination of mbedTLS compile-time config is tested in ESP-IDF. If you find a combination that fails to compile or function as expected, please report the details on `GitHub <https://github.com/espressif/esp-idf>`_.
|
||||
Not every combination of mbedTLS compile-time config is tested in ESP-IDF. If you find a combination that fails to compile or function as expected, please report the details on `GitHub <https://github.com/espressif/esp-idf>`_.
|
||||
|
||||
VFS
|
||||
@@@
|
||||
@@ -264,6 +265,7 @@ VFS
|
||||
@@@@
|
||||
|
||||
.. list::
|
||||
|
||||
* Enabling :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH` can reduce the IRAM usage and binary size by placing the entirety of the heap functionalities in flash memory.
|
||||
:CONFIG_ESP_ROM_HAS_HEAP_TLSF: * Enabling :ref:`CONFIG_HEAP_TLSF_USE_ROM_IMPL` can reduce the IRAM usage and binary size by linking in the TLSF library of ROM implementation.
|
||||
|
||||
@@ -278,10 +280,10 @@ VFS
|
||||
1. Disable the secondary console by setting :ref:`CONFIG_ESP_CONSOLE_SECONDARY` to ``CONFIG_ESP_CONSOLE_SECONDARY_NONE``.
|
||||
2. Set :ref:`CONFIG_ESP_CONSOLE_UART` to use one of the following:
|
||||
|
||||
* ``UART`` reduces the binary size by around 2.5 KB.
|
||||
* ``USB-Serial-JTAG`` reduces the binary size by around 10 KB and DRAM usage by around 1.5 KB.
|
||||
* ``UART`` reduces the binary size by around 2.5 KB.
|
||||
* ``USB-Serial-JTAG`` reduces the binary size by around 10 KB and DRAM usage by around 1.5 KB.
|
||||
|
||||
Please note that these size reductions assume the UART/USB-Serial-JTAG driver code is not pulled into the app, if you already use these drivers for other purposes then the savings will be smaller.
|
||||
Please note that these size reductions assume the UART/USB-Serial-JTAG driver code is not pulled into the app. If these drivers are already used for other purposes, then the savings will be smaller.
|
||||
|
||||
|
||||
Bootloader Size
|
||||
|
||||
Reference in New Issue
Block a user