From 1d1bba21647ca3c844d5e9d5a2f4240dee96b42c Mon Sep 17 00:00:00 2001 From: Zhang Shuxian Date: Wed, 25 Jun 2025 19:00:43 +0800 Subject: [PATCH] docs: Update cn translation for build-system.rst --- .../release-6.x/6.0/build-system.rst | 16 +++--- .../release-6.x/6.0/build-system.rst | 52 ++++++++++++++++++- 2 files changed, 59 insertions(+), 9 deletions(-) diff --git a/docs/en/migration-guides/release-6.x/6.0/build-system.rst b/docs/en/migration-guides/release-6.x/6.0/build-system.rst index 0ace3c6d95..098d4537cb 100644 --- a/docs/en/migration-guides/release-6.x/6.0/build-system.rst +++ b/docs/en/migration-guides/release-6.x/6.0/build-system.rst @@ -28,16 +28,16 @@ If you encounter an orphan section error during linking, you can resolve it usin Change in Global Constructor Order ---------------------------------- -Initially, global constructors were executed using the internal `do_global_ctors()` function. This approach was used to support Xtensa targets, which emit `.ctors.*` sections ordered in **descending** order. +Initially, global constructors were executed using the internal ``do_global_ctors()``` function. This approach was used to support Xtensa targets, which emit ``.ctors.*`` sections ordered in **descending** order. -On RISC-V targets, the toolchain emits `.init_array.*` sections, which follow a standard **ascending** order. While priority constructors in `.init_array.*` were correctly processed, the non-priority `.init_array` section was previously handled in **descending** order and matched the Xtensa `.ctors` behavior. +On RISC-V targets, the toolchain emits ``.init_array.*`` sections, which follow a standard **ascending** order. While priority constructors in ``.init_array.*`` were correctly processed, the non-priority ``.init_array`` section was previously handled in **descending** order and matched the Xtensa ``.ctors`` behavior. -Starting from ESP-IDF v6.0, the startup code uses `__libc_init_array()`, consistent with standard toolchain behavior. This function processes both priority and non-priority constructors in **ascending** order. +Starting from ESP-IDF v6.0, the startup code uses ``__libc_init_array()``, consistent with standard toolchain behavior. This function processes both priority and non-priority constructors in **ascending** order. To support this behavior, the following breaking changes were introduced: - - On Xtensa targets `.ctors.*` entries are now converted to ascending order to ensure compatibility with `__libc_init_array()`. - - The processing order of non-priority `.init_array` and legacy `.ctors` sections was changed from **descending** to **ascending**. +- On Xtensa targets ``.ctors.*`` entries are now converted to ascending order to ensure compatibility with ``__libc_init_array()``. +- The processing order of non-priority ``.init_array`` and legacy ``.ctors`` sections was changed from **descending** to **ascending**. These changes align ESP-IDF with toolchain expectations and improve consistency across supported architectures. @@ -48,7 +48,7 @@ Update Constructor Registration Logic In some cases, data structures were built assuming that constructors run in reverse order. To preserve the original behavior, update the registration logic to insert new items at the tail instead of the head. -Example (from `components/unity/unity_runner.c`): +Example (from ``components/unity/unity_runner.c``): .. code-block:: diff @@ -66,11 +66,11 @@ Example (from `components/unity/unity_runner.c`): Use Constructor Priorities ~~~~~~~~~~~~~~~~~~~~~~~~~~ -To explicitly control constructor order, use the `constructor()` function attribute with a numeric priority: +To explicitly control constructor order, use the ``constructor()`` function attribute with a numeric priority: .. code-block:: c __attribute__((constructor(PRIO))) void foo(void); -Replace `PRIO` with an integer value. Lower values are executed earlier. This is the preferred method when specific ordering is required. +Replace ``PRIO`` with an integer value. Lower values are executed earlier. This is the preferred method when specific ordering is required. diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst index bbfec461eb..a203c7b59a 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/build-system.rst @@ -23,4 +23,54 @@ .. warning:: - 方案3 **不推荐使用**，因为孤立段可能意味着内存映射配置存在问题，或应用程序中存在非预期行为。 + 方案 3 **不推荐使用**，因为孤立段可能意味着内存映射配置存在问题，或应用程序中存在非预期行为。 + +全局构造函数顺序变更 +--------------------- + +最初，ESP-IDF 使用内部函数 ``do_global_ctors()`` 执行全局构造函数，以兼容 Xtensa 架构，其编译器会生成按 **降序** 排列的 ``.ctors.*`` 段。 + +在 RISC-V 架构中，工具链会生成 ``.init_array.*`` 段，并采用标准的 **升序** 排列。虽然优先级构造函数（位于 ``.init_array.*``）能正确执行，但此前未指定优先级的 ``.init_array`` 段却是按 **降序** 方式处理，从而与 Xtensa 的 ``.ctors`` 行为保持一致。 + +从 ESP-IDF v6.0 起，启动代码改用标准工具链函数 ``__libc_init_array()``。该函数会按 **升序** 执行带优先级和不带优先级的构造函数。 + +因此，我们引入了以下重大变更： + +- 对于 Xtensa 架构，``.ctors.*`` 项现在会被转换为升序，以确保与 ``__libc_init_array()`` 的行为兼容。 +- 非优先级的 ``.init_array`` 和旧版 ``.ctors`` 段的执行顺序从 ``降序`` 改为 ``升序``。 + +这些变更使 ESP-IDF 的行为与工具链的预期保持一致，并提升了跨架构的兼容性。 + +若应用程序依赖原有构造函数的执行顺序（降序），并因此受到影响，可参考以下解决方案。 + +更新构造函数注册逻辑 +~~~~~~~~~~~~~~~~~~~~ + +有些数据结构是基于“构建函数按相反顺序运行”的假设来构建的。现在为了不改变原有行为，可将注册新项的逻辑从“插入头部”改为“插入尾部”。 + +示例（来自 ``components/unity/unity_runner.c``）： + +.. code-block:: diff + + - // 插入到链表头部 + - desc->next = s_unity_tests_first; + - s_unity_tests_first = desc; + + // 插入到链表尾部 + + _unity_tests_last->next = desc; + + s_unity_tests_last = desc; + +.. note:: + + 此方案仅适用于特定场景。 + +使用构造函数优先级 +~~~~~~~~~~~~~~~~~~~~~~~ + +若需显式控制构造函数执行顺序，可使用带数值优先级的 ``constructor()`` 函数属性： + +.. code-block:: c + + __attribute__((constructor(PRIO))) + void foo(void); + +将 ``PRIO`` 替换为整数值。值越小，执行越早。当对执行顺序有特定要求时，这种方式是首选。