mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: drop support for v3.x grammar
This commit is contained in:
Fu Hanxi
parent
172854a850
commit
0282cedd0b
@ -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
|
||||
""""""""""""""""""""""""""""""""""
|
||||
|
||||
@ -225,6 +228,9 @@ The three fragment types share a common grammar:
|
||||
- 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<ldgen-sections-fragment>` and :ref:`scheme<ldgen-scheme-fragment>`, the only supported key is ``entries``
|
||||
- For :ref:`mappings<ldgen-mapping-fragment>`, both ``archive`` and ``entries`` are supported.
|
||||
|
||||
.. note::
|
||||
|
||||
In cases where multiple fragments of the same type and name are encountered, an exception is thrown.
|
||||
@ -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<ldgen-conditional-placements>` for detailed grammar.
|
||||
3. mapping fragments now requires a name like other fragment types.
|
||||
|
||||
@ -1,4 +1,12 @@
|
||||
Migrate Build System to ESP-IDF 5.0
|
||||
===================================
|
||||
|
||||
Migrating from make to cmake
|
||||
----------------------------
|
||||
|
||||
Please follow the :ref:`build system <migrating_from_make>` 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<ldgen-migrate-lf-grammar>` chapter for migrating v3.x grammar to the new one.
|
||||
|
||||
@ -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:`之前的章节<ldgen-conditional-placements>`
|
||||
- 映射片段和其他片段类型一样，需有名称
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user