kopia lustrzana https://github.com/espressif/esp-idf
Merge branch 'docs/add_cn_trans_gcc_provisioning' into 'master'
Docs: Add CN translation for gcc.rst and provisioning.rst Closes DOC-3071 See merge request espressif/esp-idf!19445pull/9565/head
Mo Fei Fei
commit
46ab579df9
|
|
@ -1,64 +1,32 @@
|
|||
GCC
|
||||
***
|
||||
|
||||
Previous GCC version was 8.4.0
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
||||
Official GNU porting guides for your code
|
||||
=========================================
|
||||
GCC Version
|
||||
===========
|
||||
|
||||
The previous GCC version was GCC 8.4.0. This has now been upgraded to GCC 11.2.0 on all targets. Users that need to port their code from GCC 8.4.0 to 11.2.0 should refer to the series of official GCC porting guides listed below:
|
||||
|
||||
* `Porting to GCC 9 <https://gcc.gnu.org/gcc-9/porting_to.html>`_
|
||||
* `Porting to GCC 10 <https://gcc.gnu.org/gcc-10/porting_to.html>`_
|
||||
* `Porting to GCC 11 <https://gcc.gnu.org/gcc-11/porting_to.html>`_
|
||||
|
||||
|
||||
* https://gcc.gnu.org/gcc-9/porting_to.html
|
||||
Warnings
|
||||
========
|
||||
|
||||
* https://gcc.gnu.org/gcc-10/porting_to.html
|
||||
The upgrade to GCC 11.2.0 has resulted in the addition of new warnings, or enhancements to existing warnings. The full details of all GCC warnings can be found in `GCC Warning Options <https://gcc.gnu.org/onlinedocs/gcc-11.2.0/gcc/Warning-Options.html>`_. Users are advised to double-check their code, then fix the warnings if possible. Unfortunately, depending on the warning and the complexity of the user's code, some warnings will be false positives that require non-trivial fixes. In such cases, users can choose to suppress the warning in multiple ways. This section outlines some common warnings that users are likely to encounter, and ways to suppress them.
|
||||
|
||||
* https://gcc.gnu.org/gcc-11/porting_to.html
|
||||
.. warning::
|
||||
Users are advised to check that a warning is indeed a false positive before attempting to suppress them it.
|
||||
|
||||
|
||||
Espressif Toolchain changes
|
||||
===========================
|
||||
``-Wstringop-overflow``, ``-Wstringop-overread``, ``-Wstringop-truncation``, and ``-Warray-bounds``
|
||||
--------------------------------------------------------------------------------------------------------
|
||||
|
||||
|
||||
``int32_t`` and ``uint32_t`` for Xtensa compiler
|
||||
------------------------------------------------
|
||||
|
||||
The types ``int32_t`` and ``uint32_t`` have been changed from ``int`` and ``unsigned int`` to ``long`` and ``unsigned long``. Upstream GCC uses ``long`` integers for int32_t/uint32_t on Xtensa, RISC-V and other architectures.
|
||||
|
||||
+---------+--------------------------+-----------------+
|
||||
| | 2021r2 and older, GCC 8 | 2022r1, GCC 11 |
|
||||
+=========+==========================+=================+
|
||||
| xtensa | (unsigned) int | (unsigned) long |
|
||||
+---------+--------------------------+-----------------+
|
||||
| riscv32 | (unsigned) long | (unsigned) long |
|
||||
+---------+--------------------------+-----------------+
|
||||
|
||||
|
||||
The most cases in code are related to the formatting. Using ``%i``, ``%x``, etc., should be replaced to ``PRIi32``, ``PRIxx``, and others from ``<inttypes.h>``.
|
||||
|
||||
In other cases it should be noted that enums have ``int`` type.
|
||||
|
||||
In common, ``int32_t`` and ``int`` are different types, as well as ``uint32_t`` and ``unsigned int``.
|
||||
|
||||
|
||||
Removing of ``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS`` build option
|
||||
------------------------------------------------------------------
|
||||
|
||||
``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS`` option was introduced to help transition from rigid GCC 5 toolchain to new ones with helping build ancient code. Enough time has passed to fix the warnings.
|
||||
|
||||
For now in GCC 11, the suggestion is to review your own code to comply compiler warnings.
|
||||
|
||||
|
||||
Common cases in code
|
||||
====================
|
||||
|
||||
|
||||
``-Wstringop-overflow``, ``-Wstringop-overread``, ``-Wstringop-truncation``, and ``-Warray-bounds`` warnings
|
||||
------------------------------------------------------------------------------------------------------------
|
||||
|
||||
Warning details: https://gcc.gnu.org/onlinedocs/gcc-11.2.0/gcc/Warning-Options.html
|
||||
|
||||
Double check your code then fix please. Unfortunately, not all seemingly simple ways to satisfy the compiler will work.
|
||||
You can supress such warnings if the compiler worried for nothing.
|
||||
Users that use memory/string copy/compare functions will run into one of the ``-Wstringop`` warnings if the compiler cannot properly determine the size of the memory/string. The examples below demonstrate code that triggers these warnings and how to suppress them.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
|
|
@ -80,15 +48,10 @@ You can supress such warnings if the compiler worried for nothing.
|
|||
#pragma GCC diagnostic pop
|
||||
|
||||
|
||||
``-Waddress-of-packed-member``
|
||||
--------------------------------
|
||||
|
||||
``-Waddress-of-packed-member`` warning
|
||||
--------------------------------------
|
||||
|
||||
Warning details: https://gcc.gnu.org/onlinedocs/gcc-11.2.0/gcc/Warning-Options.html
|
||||
|
||||
Double check your code then fix please.
|
||||
|
||||
Unaligned pointer value for data doesn't have penalty for xtensa and riscv32 Espressif chips so we can ignore it in most cases.
|
||||
GCC will issue this warning when accessing an unaligned member of a packed ``struct`` due to the incurred penalty of unaligned memory access. However, all ESP chips (on both Xtensa and RISC-V architectures) allow for unaligned memory access and incur no extra penalty. Thus, this warning can be ignored in most cases.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
|
@ -98,7 +61,7 @@ Unaligned pointer value for data doesn't have penalty for xtensa and riscv32 Esp
|
|||
| ^~~~~~~~~~~~~
|
||||
|
||||
|
||||
on CMake level for tons of cases:
|
||||
If the warning occurs in multiple places across multiple source files, users can suppress the warning at the CMake level as demonstrated below.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
|
|
@ -109,7 +72,7 @@ on CMake level for tons of cases:
|
|||
"host/bluedroid/btc/profile/std/gatt/btc_gatts.c"
|
||||
PROPERTIES COMPILE_FLAGS -Wno-address-of-packed-member)
|
||||
|
||||
or on code level:
|
||||
However, if there are only one or two instances, users can suppress the warning directly in the source code itself as demonstrated below.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
|
|
@ -121,8 +84,46 @@ or on code level:
|
|||
#pragma GCC diagnostic pop
|
||||
|
||||
|
||||
|
||||
``llabs()`` for 64-bit integers
|
||||
``llabs()`` for 64-bit Integers
|
||||
-------------------------------
|
||||
|
||||
The function ``abs()`` from stdlib.h takes ``int`` argument. Please use ``llabs()`` for types that intended to be 64-bit. In particular it's important for ``time_t``.
|
||||
The function ``abs()`` from stdlib.h takes ``int`` argument. Please use ``llabs()`` for types that are intended to be 64-bit. It is particularly important for ``time_t``.
|
||||
|
||||
|
||||
Espressif Toolchain Changes
|
||||
===========================
|
||||
|
||||
``int32_t`` and ``uint32_t`` for Xtensa Compiler
|
||||
------------------------------------------------
|
||||
|
||||
The types ``int32_t`` and ``uint32_t`` have been changed from the previous ``int`` and ``unsigned int`` to ``long`` and ``unsigned long`` respectively for the Xtensa compiler. This change now matches upstream GCC which ``long`` integers for ``int32_t`` and ``uint32_t`` on Xtensa, RISC-V, and other architectures.
|
||||
|
||||
|
||||
.. list-table::
|
||||
:widths: 20 45 35
|
||||
:header-rows: 1
|
||||
|
||||
* -
|
||||
- 2021r2 and older, GCC 8
|
||||
- 2022r1, GCC 11
|
||||
* - Xtensa
|
||||
- (unsigned) int
|
||||
- (unsigned) long
|
||||
* - riscv32
|
||||
- (unsigned) long
|
||||
- (unsigned) long
|
||||
|
||||
|
||||
The change mostly affects code that formats strings using types provided by ``<inttypes.h>``. Users will need to replace placeholders such as ``%i`` and ``%x`` with ``PRIi32`` and ``PRIxx`` respectively.
|
||||
|
||||
In other cases, it should be noted that enums have the ``int`` type.
|
||||
|
||||
In common, ``int32_t`` and ``int``, as well as ``uint32_t`` and ``unsigned int``, are different types.
|
||||
|
||||
|
||||
Removing ``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS`` Build Option
|
||||
------------------------------------------------------------------
|
||||
|
||||
``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS`` option was introduced to allow building of legacy code dating from the rigid GCC 5 toolchain. However, enough time has passed to allow for the warnings to be fixed, thus this option has been removed.
|
||||
|
||||
For now in GCC 11, users are advised to review their code and fix the compiler warnings where possible.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,25 @@
|
|||
Provisioning
|
||||
============
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Protocomm
|
||||
---------
|
||||
|
||||
The :cpp:func:`protocomm_set_security` API now takes a parameter ``sec_params`` as input instead of ``pop`` (deprecated).
|
||||
This parameter should contain the structure (containing the security parameters) as required by the protocol version used.
|
||||
The ``pop`` field in the :cpp:func:`protocomm_set_security` API is now deprecated. Please use the ``sec_params`` field instead of ``pop``. This parameter should contain the structure (including the security parameters) as required by the protocol version used.
|
||||
|
||||
For example when using security version 2, the ``sec_params`` parameter should contain the pointer to the structure of type :cpp:type:`protocomm_security2_params_t`.
|
||||
For example, when using security version 2, the ``sec_params`` parameter should contain the pointer to the structure of type :cpp:type:`protocomm_security2_params_t`.
|
||||
|
||||
Wi-Fi Provisioning
|
||||
------------------
|
||||
|
||||
The :cpp:func:`wifi_prov_mgr_start_provisioning` API now takes a parameter ``wifi_prov_sec_params`` as input instead of ``pop``.
|
||||
This parameter should contain the structure (containing the security parameters) as required by the protocol version used.
|
||||
The ``pop`` field in the :cpp:func:`wifi_prov_mgr_start_provisioning` API is now deprecated. Please use the ``wifi_prov_sec_params`` field instead of ``pop``. This parameter should contain the structure (containing the security parameters) as required by the protocol version used.
|
||||
|
||||
For example when using security version 2, the ``wifi_prov_sec_params`` parameter should contain the pointer to the structure of type :cpp:type:`wifi_prov_security2_params_t`.
|
||||
For example, when using security version 2, the ``wifi_prov_sec_params`` parameter should contain the pointer to the structure of type :cpp:type:`wifi_prov_security2_params_t`.
|
||||
|
||||
ESP Local Control
|
||||
-----------------
|
||||
The `pop` field in :cpp:type:`esp_local_ctrl_proto_sec_cfg_t` is now deprecated, use ``sec_params`` field instead of ``pop``.
|
||||
This field should contain the structure (containing the security parameters) as required by the protocol version used.
|
||||
|
||||
For example when using security version 2, the ``sec_params`` field should contain pointer to the structure of type :cpp:type:`esp_local_ctrl_security2_params_t`.
|
||||
The ``pop`` field in the :cpp:type:`esp_local_ctrl_proto_sec_cfg_t` API is now deprecated. Please use the ``sec_params`` field instead of ``pop``. This field should contain the structure (containing the security parameters) as required by the protocol version used.
|
||||
|
||||
For example, when using security version 2, the ``sec_params`` field should contain pointer to the structure of type :cpp:type:`esp_local_ctrl_security2_params_t`.
|
||||
|
|
|
|||
|
|
@ -1 +1,129 @@
|
|||
.. include:: ../../../en/migration-guides/release-5.x/gcc.rst
|
||||
GCC
|
||||
***
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
|
||||
GCC 版本
|
||||
========
|
||||
|
||||
ESP-IDF 之前使用的 GCC 版本为 8.4.0，现已针对所有芯片目标升级至 GCC 11.2.0。若需要将您的代码从 GCC 8.4.0 迁移到 GCC 11.2.0，请参考以下官方 GCC 迁移指南。
|
||||
|
||||
* `迁移至 GCC 9 <https://gcc.gnu.org/gcc-9/porting_to.html>`_
|
||||
* `迁移至 GCC 10 <https://gcc.gnu.org/gcc-10/porting_to.html>`_
|
||||
* `迁移至 GCC 11 <https://gcc.gnu.org/gcc-11/porting_to.html>`_
|
||||
|
||||
|
||||
警告
|
||||
====
|
||||
|
||||
升级至 GCC 11.2.0 后会触发新警告，或是导致原有警告内容发生变化。所有 GCC 警告的详细内容，请参考 `GCC 警告选项 <https://gcc.gnu.org/onlinedocs/gcc-11.2.0/gcc/Warning-Options.html>`_。建议用户仔细检查代码，并设法解决这些警告。但由于某些警告的特殊性及用户代码的复杂性，有些警告可能为误报，需要进行关键修复。在这种情况下，用户可以采取多种方式来抑制这些警告。本节介绍了用户可能遇到的常见警告及如何抑制这些警告。
|
||||
|
||||
.. 注意::
|
||||
建议用户在抑制警告之前仔细确认该警告是否确实为误报。
|
||||
|
||||
|
||||
``-Wstringop-overflow``、``-Wstringop-overread``、``-Wstringop-truncation`` 和 ``-Warray-bounds``
|
||||
--------------------------------------------------------------------------------------------------
|
||||
|
||||
如果编译器不能准确判断内存或字符串的大小，使用 memory/string copy/compare 函数的用户会遇到某种 ``-Wstringop`` 警告。下文展示了触发这些警告的代码，并介绍了如何抑制这些警告。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#pragma GCC diagnostic push
|
||||
#pragma GCC diagnostic ignored "-Wstringop-overflow"
|
||||
#pragma GCC diagnostic ignored "-Warray-bounds"
|
||||
memset(RTC_SLOW_MEM, 0, CONFIG_ULP_COPROC_RESERVE_MEM); // <<-- 此行触发了警告
|
||||
#pragma GCC diagnostic pop
|
||||
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#pragma GCC diagnostic push
|
||||
#if __GNUC__ >= 11
|
||||
#pragma GCC diagnostic ignored "-Wstringop-overread" // <<-- 此键从 GCC 11 开始引入
|
||||
#endif
|
||||
#pragma GCC diagnostic ignored "-Warray-bounds"（-Warray-bounds）。
|
||||
memcpy(backup_write_data, (void *)EFUSE_PGM_DATA0_REG, sizeof(backup_write_data)); // <<-- 此行触发了警告
|
||||
#pragma GCC diagnostic pop
|
||||
|
||||
|
||||
``-Waddress-of-packed-member``
|
||||
---------------------------------
|
||||
|
||||
当访问打包 ``struct`` 中的某个未对齐成员时，由于非对齐内存访问会对性能产生影响，GCC 会触发 ``-Waddress-of-packed-member`` 警告。然而，所有基于 Xtensa 或 RISC-V 架构的 ESP 芯片都允许非对齐内存访问，并且不会产生额外的性能影响。因此，在大多数情况下，可以忽略此问题。
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
components/bt/host/bluedroid/btc/profile/std/gatt/btc_gatt_util.c: In function 'btc_to_bta_gatt_id':
|
||||
components/bt/host/bluedroid/btc/profile/std/gatt/btc_gatt_util.c:105:21: warning: taking address of packed member of 'struct <anonymous>' may result in an unaligned pointer value [-Waddress-of-packed-member]
|
||||
105 | btc_to_bta_uuid(&p_dest->uuid, &p_src->uuid);
|
||||
| ^~~~~~~~~~~~~
|
||||
|
||||
|
||||
如果该警告在多个源文件中多次出现，可以在 CMake 级别抑制该警告，如下所示。
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_source_files_properties(
|
||||
"host/bluedroid/bta/gatt/bta_gattc_act.c"
|
||||
"host/bluedroid/bta/gatt/bta_gattc_cache.c"
|
||||
"host/bluedroid/btc/profile/std/gatt/btc_gatt_util.c"
|
||||
"host/bluedroid/btc/profile/std/gatt/btc_gatts.c"
|
||||
PROPERTIES COMPILE_FLAGS -Wno-address-of-packed-member)
|
||||
|
||||
但如果只有一或两处警告，可以直接在源代码中进行抑制，如下所示。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#pragma GCC diagnostic push
|
||||
#if __GNUC__ >= 9
|
||||
#pragma GCC diagnostic ignored "-Waddress-of-packed-member" <<-- 此键从 GCC 11 开始引入
|
||||
#endif
|
||||
uint32_t* reg_ptr = (uint32_t*)src;
|
||||
#pragma GCC diagnostic pop
|
||||
|
||||
|
||||
``llabs()`` 用于 64 位整数
|
||||
-------------------------------
|
||||
|
||||
stdlib.h 中的函数 ``abs()`` 需要使用 ``int`` 参数。请在计划为 64 位的类型中使用 ``llabs()``，尤其是 ``time_t``。
|
||||
|
||||
|
||||
乐鑫工具链更新
|
||||
=================
|
||||
|
||||
Xtensa 编译器中的 ``int32_t`` 和 ``uint32_t``
|
||||
---------------------------------------------------
|
||||
|
||||
在 Xtensa 编译器中，``int32_t`` 和 ``uint32_t`` 类型已分别从 ``int`` 和 ``unsigned int`` 更新为 ``long`` 和 ``unsigned long``。此更新现与上游 GCC 相匹配，上游 GCC 在 Xtensa、RISC-V 和其他架构上使用 ``long`` 整数来表示 ``int32_t`` 和 ``uint32_t``。
|
||||
|
||||
|
||||
.. list-table::
|
||||
:widths: 20 45 35
|
||||
:header-rows: 1
|
||||
|
||||
* -
|
||||
- 2021r2 及以上版本，GCC 8
|
||||
- 2022r1，GCC 11
|
||||
* - Xtensa
|
||||
- (unsigned) int
|
||||
- (unsigned) long
|
||||
* - riscv32
|
||||
- (unsigned) long
|
||||
- (unsigned) long
|
||||
|
||||
|
||||
上述变化主要影响到使用 ``<inttypes.h>`` 提供的类型来格式化字符串的代码。请使用 ``PRIi32``、``PRIxx`` 等占位符来分别替换 ``%i``、``%x`` 等。
|
||||
|
||||
在其他情况下，请注意枚举支持 ``int`` 类型。
|
||||
|
||||
通常，``int32_t`` 和 ``int`` 为不同的类型。同样，``uint32_t`` 和 ``unsigned int`` 也为不同的类型。
|
||||
|
||||
|
||||
移除构建选项 ``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS``
|
||||
----------------------------------------------------------
|
||||
|
||||
原有的 ``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS`` 选项用于构建使用现已僵化的 GCC 5 工具链编写的陈旧代码。但由于已经过去较长时间，现在可以对警告进行修复，因此该选项已被移除。
|
||||
|
||||
目前，在 GCC 11 中，建议用户仔细检查代码，尽量解决编译器警告。
|
||||
|
|
|
|||
|
|
@ -1 +1,25 @@
|
|||
.. include:: ../../../en/migration-guides/release-5.x/provisioning.rst
|
||||
配置
|
||||
======
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
Protocomm
|
||||
---------
|
||||
|
||||
:cpp:func:`protocomm_set_security` API 中的 ``pop`` 字段现已弃用。请使用 ``sec_params`` 字段来代替 ``pop``。此参数应包含所使用的协议版本所要求的结构（包括安全参数）。
|
||||
|
||||
例如，当使用安全版本 2 时，``sec_params`` 参数应包含指向 :cpp:type:`protocomm_security2_params_t` 类型结构的指针。
|
||||
|
||||
Wi-Fi 配置
|
||||
-------------
|
||||
|
||||
:cpp:func:`wifi_prov_mgr_start_provisioning` API 中的 ``pop`` 字段现已弃用。请使用 ``wifi_prov_sec_params`` 字段来代替 ``pop``。此参数应包含所使用的协议版本所要求的结构（包括安全参数）。
|
||||
|
||||
例如，当使用安全版本 2 时，``wifi_prov_sec_params`` 参数应包含指向 :cpp:type:`wifi_prov_security2_params_t` 类型结构的指针。
|
||||
|
||||
ESP 本地控制
|
||||
-----------------
|
||||
|
||||
:cpp:type:`esp_local_ctrl_proto_sec_cfg_t` API 中的 ``pop`` 字段现已弃用。请使用 ``sec_params`` 字段来代替 ``pop``。此参数应包含所使用的协议版本所要求的结构（包括安全参数）。
|
||||
|
||||
例如，当使用安全版本 2 时，``sec_params`` 字段应包含指向 :cpp:type:`esp_local_ctrl_security2_params_t` 类型结构的指针。
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue