From 0282cedd0bcbaad45fdb9f2f00461020eb0b593f Mon Sep 17 00:00:00 2001 From: Fu Hanxi Date: Fri, 24 Dec 2021 17:12:21 +0800 Subject: [PATCH] docs: drop support for v3.x grammar --- .../api-guides/linker-script-generation.rst | 53 ++++++++++--------- docs/en/migration-guides/build-system.rst | 8 +++ .../api-guides/linker-script-generation.rst | 50 ++++++++--------- 3 files changed, 62 insertions(+), 49 deletions(-) diff --git a/docs/en/api-guides/linker-script-generation.rst b/docs/en/api-guides/linker-script-generation.rst index ba1e99a433..c56d1744b4 100644 --- a/docs/en/api-guides/linker-script-generation.rst +++ b/docs/en/api-guides/linker-script-generation.rst @@ -24,16 +24,16 @@ This section presents a guide for quickly placing code/data to RAM and RTC memor For this guide, suppose we have the following:: - - components/ - - my_component/ - - CMakeLists.txt - - component.mk - - Kconfig - - src/ - - my_src1.c - - my_src2.c - - my_src3.c - - my_linker_fragment_file.lf + component + └── my_component + └── CMakeLists.txt + ├── component.mk + ├── Kconfig + ├── src/ + │ ├── my_src1.c + │ ├── my_src2.c + │ └── my_src3.c + └── my_linker_fragment_file.lf - a component named ``my_component`` that is archived as library ``libmy_component.a`` during build - three source files archived under the library, ``my_src1.c``, ``my_src2.c`` and ``my_src3.c`` which are compiled as ``my_src1.o``, ``my_src2.o`` and ``my_src3.o``, respectively @@ -71,7 +71,7 @@ Placing object files """""""""""""""""""" Suppose the entirety of ``my_src1.o`` is performance-critical, so it is desirable to place it in RAM. On the other hand, the entirety of ``my_src2.o`` contains symbols needed coming out of deep sleep, so it needs to be put under RTC memory. -In the the linker fragment file, we can write: +In the linker fragment file, we can write: .. code-block:: none @@ -125,6 +125,9 @@ Similarly, this places the entire component in RTC memory: entries: * (rtc) + +.. _ldgen-conditional-placements: + Configuration-dependent placements """""""""""""""""""""""""""""""""" @@ -224,6 +227,9 @@ The three fragment types share a common grammar: - type: Corresponds to the fragment type, can either be ``sections``, ``scheme`` or ``mapping``. - name: The name of the fragment, should be unique for the specified fragment type. - key, value: Contents of the fragment; each fragment type may support different keys and different grammars for the key values. + + - For :ref:`sections` and :ref:`scheme`, the only supported key is ``entries`` + - For :ref:`mappings`, both ``archive`` and ``entries`` are supported. .. note:: @@ -286,24 +292,10 @@ Condition checking behaves as you would expect an ``if...elseif/elif...else`` bl key_2: value_b - **Comments** Comment in linker fragment files begin with ``#``. Like in other languages, comment are used to provide helpful descriptions and documentation and are ignored during processing. -Compatibility with ESP-IDF v3.x Linker Script Fragment Files -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -ESP-IDF v4.0 brings some changes to the linker script fragment file grammar: - -- indentation is enforced and improperly indented fragment files generate a parse exception; this was not enforced in the old version but previous documentation and examples demonstrates properly indented grammar -- move to ``if...elif...else`` structure for conditionals, with the ability to nest checks and place entire fragments themselves inside conditionals -- mapping fragments now requires a name like other fragment types - -Linker script generator should be able to parse ESP-IDF v3.x linker fragment files that are indented properly (as demonstrated by the ESP-IDF v3.x version of this document). Backward compatibility with the previous mapping fragment grammar (optional name and the old grammar for conditionals) has also been retained but with a deprecation warning. Users should switch to the newer grammar discussed in this document as support for the old grammar is planned to be removed in the future. - -Note that linker fragment files using the new ESP-IDF v4.0 grammar is not supported on ESP-IDF v3.x, however. - Types """"" @@ -608,3 +600,14 @@ Then the corresponding excerpt from the generated linker script will be as follo Rule generated from the default scheme entry ``iram -> iram0_text``. Since the default scheme specifies an ``iram -> iram0_text`` entry, it too is placed wherever ``iram0_text`` is referenced by a marker. Since it is a rule generated from the default scheme, it comes first among all other rules collected under the same target name. The linker script template currently used is :component_file:`esp_system/ld/{IDF_TARGET_PATH_NAME}/sections.ld.in`; the generated output script ``sections.ld`` is put under its build directory. + +.. _ldgen-migrate-lf-grammar : + +Migrate to ESP-IDF v5.0 Linker Script Fragment Files Grammar +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The old grammar supported in ESP-IDF v3.x would be dropped in ESP-IDF v5.0. Here are a few notes on how to migrate properly: + +1. Now indentation is enforced and improperly indented fragment files would generate a runtime parse exception. This was not enforced in the old version but previous documentation and examples demonstrate properly indented grammar. +2. Migrate the old condition entry to the ``if...elif...else`` structure for conditionals. You can refer to the :ref:`earlier chapter` for detailed grammar. +3. mapping fragments now requires a name like other fragment types. diff --git a/docs/en/migration-guides/build-system.rst b/docs/en/migration-guides/build-system.rst index abb2f1bcb4..0a3e790361 100644 --- a/docs/en/migration-guides/build-system.rst +++ b/docs/en/migration-guides/build-system.rst @@ -1,4 +1,12 @@ Migrate Build System to ESP-IDF 5.0 =================================== +Migrating from make to cmake +---------------------------- + Please follow the :ref:`build system ` guide for migrating make-based projects no longer supported in ESP-IDF v5.0. + +Update fragment file grammar +---------------------------- + +Please follow the :ref:`migrate linker script fragment files grammar` chapter for migrating v3.x grammar to the new one. diff --git a/docs/zh_CN/api-guides/linker-script-generation.rst b/docs/zh_CN/api-guides/linker-script-generation.rst index 6ee1d3f2d0..31258be653 100644 --- a/docs/zh_CN/api-guides/linker-script-generation.rst +++ b/docs/zh_CN/api-guides/linker-script-generation.rst @@ -24,16 +24,16 @@ 假设用户有:: - - components/ - - my_component/ - - CMakeLists.txt - - component.mk - - Kconfig - - src/ - - my_src1.c - - my_src2.c - - my_src3.c - - my_linker_fragment_file.lf + component + └── my_component + └── CMakeLists.txt + ├── component.mk + ├── Kconfig + ├── src/ + │ ├── my_src1.c + │ ├── my_src2.c + │ └── my_src3.c + └── my_linker_fragment_file.lf - 名为 ``my_component`` 的组件，在构建过程中存储为 ``libmy_component.a`` 库文件 - 库文件包含的三个源文件：``my_src1.c``、``my_src2.c`` 和 ``my_src3.c``，编译后分别为 ``my_src1.o``、``my_src2.o`` 和 ``my_src3.o`` @@ -125,6 +125,8 @@ entries: * (rtc) +.. _ldgen-conditional-placements : + 根据具体配置存放 """""""""""""""""""" @@ -225,6 +227,9 @@ - 名称：片段名称，指定片段类型的片段名称应唯一。 - 键值：片段内容。每个片段类型可支持不同的键值和不同的键值语法。 + - 在 ``段`` 和 ``协议`` 中，仅支持 ``entries`` 键。 + - 在 ``映射`` 中，键支持 ``archive`` 和 ``entries``。 + .. note:: 多个片段的类型和名称相同时会引发异常。 @@ -286,24 +291,10 @@ key_2: value_b - **注释** 链接器片段文件中的注释以 ``#`` 开头。和在其他语言中一样，注释提供了有用的描述和资料，在处理过程中会被忽略。 -与 ESP-IDF v3.x 链接器脚本片段文件兼容 -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -ESP-IDF v4.0 变更了链接器脚本片段文件使用的一些语法： - -- 必须缩进，缩进不当的文件会产生解析异常；旧版本不强制缩进，但之前的文档和示例均遵循了正确的缩进语法 -- 条件改用 ``if...elif...else`` 结构，可以嵌套检查，将完整片段置于条件内 -- 映射片段和其他片段类型一样，需有名称 - -链接器脚本生成器可解析 ESP-IDF v3.x 版本中缩进正确的链接器片段文件（如 ESP-IDF v3.x 版本中的本文件所示），依然可以向后兼容此前的映射片段语法（可选名称和条件的旧语法），但是会有弃用警告。用户应换成本文档介绍的新语法，因为旧语法将在未来停用。 - -请注意，ESP-IDF v3.x 不支持使用 ESP-IDF v4.0 新语法的链接器片段文件。 - 类型 """"""" @@ -608,3 +599,14 @@ ESP-IDF v4.0 变更了链接器脚本片段文件使用的一些语法： 这是根据默认协议条目 ``iram -> iram0_text`` 生成的规则。默认协议指定了 ``iram -> iram0_text`` 条目，因此生成的规则同样也放在被 ``iram0_text`` 标记的地方。由于该规则是根据默认协议生成的，因此在同一目标下收集的所有规则下排在第一位。 目前使用的链接器脚本模板是 :component_file:`esp_system/ld/{IDF_TARGET_PATH_NAME}/sections.ld.in`，生成的脚本存放在构建目录下。 + +.. _ldgen-migrate-lf-grammar : + +将链接器脚本片段文件语法迁移至 ESP-IDF v5.0 适应版本 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-IDF v5.0 中将不再支持 ESP-IDF v3.x 中链接器脚本片段文件的旧式语法。在迁移的过程中需注意以下几点： + +- 必须缩进，缩进不当的文件会产生解析异常；旧版本不强制缩进，但之前的文档和示例均遵循了正确的缩进语法 +- 条件改用 ``if...elif...else`` 结构，可以参照 :ref:`之前的章节` +- 映射片段和其他片段类型一样，需有名称