You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
190 lines
6.8 KiB
190 lines
6.8 KiB
.. _code_data_relocation: |
|
|
|
Code And Data Relocation |
|
######################## |
|
|
|
Overview |
|
******** |
|
This feature will allow relocating .text, .rodata, .data, and .bss sections from |
|
required files and place them in the required memory region. The memory region |
|
and file are given to the :ref:`gen_relocate_app.py` script in the form |
|
of a string. This script is always invoked from inside cmake. |
|
|
|
This script provides a robust way to re-order the memory contents without |
|
actually having to modify the code. In simple terms this script will do the job |
|
of ``__attribute__((section("name")))`` for a bunch of files together. |
|
|
|
A regular expression filter can be used to select only the required sections to be relocated. |
|
|
|
Details |
|
******* |
|
The memory region and file are given to the :ref:`gen_relocate_app.py` script |
|
through a file where each line specifies a list of files to be placed in the |
|
given region. |
|
|
|
An example of such a file is: |
|
|
|
.. code-block:: none |
|
|
|
SRAM2:/home/xyz/zephyr/samples/hello_world/src/main.c, |
|
SRAM1:/home/xyz/zephyr/samples/hello_world/src/main2.c, |
|
|
|
This script is invoked with the following parameters: |
|
``python3 gen_relocate_app.py -i input_file -o generated_linker -c generated_code`` |
|
|
|
Kconfig :kconfig:option:`CONFIG_CODE_DATA_RELOCATION` option, when enabled in |
|
``prj.conf``, will invoke the script and do the required relocation. |
|
|
|
This script also trigger the generation of ``linker_relocate.ld`` and |
|
``code_relocation.c`` files. The ``linker_relocate.ld`` file creates |
|
appropriate sections and links the required functions or variables from all the |
|
selected files. |
|
|
|
.. note:: |
|
|
|
The text section is split into 2 parts in the main linker script. The first |
|
section will have some info regarding vector tables and other debug related |
|
info. The second section will have the complete text section. This is |
|
needed to force the required functions and data variables to the correct |
|
locations. This is due to the behavior of the linker. The linker will only |
|
link once and hence this text section had to be split to make room for the |
|
generated linker script. |
|
|
|
The ``code_relocation.c`` file has code that is needed for |
|
initializing data sections, and a copy of the text sections (if XIP). |
|
Also this contains code needed for bss zeroing and |
|
for data copy operations from ROM to required memory type. |
|
|
|
**The procedure to invoke this feature is:** |
|
|
|
* Enable :kconfig:option:`CONFIG_CODE_DATA_RELOCATION` in the ``prj.conf`` file |
|
|
|
* Inside the ``CMakeLists.txt`` file in the project, mention |
|
all the files that need relocation. |
|
|
|
``zephyr_code_relocate(FILES src/*.c LOCATION SRAM2)`` |
|
|
|
Where the first argument is the file/files and the second |
|
argument is the memory where it must be placed. |
|
|
|
.. note:: |
|
|
|
function zephyr_code_relocate() can be called as many times as required. |
|
|
|
Additional Configurations |
|
========================= |
|
This section shows additional configuration options that can be set in |
|
``CMakeLists.txt`` |
|
|
|
* if the memory is SRAM1, SRAM2, CCD, or AON, then place the full object in the |
|
sections for example: |
|
|
|
.. code-block:: none |
|
|
|
zephyr_code_relocate(FILES src/file1.c LOCATION SRAM2) |
|
zephyr_code_relocate(FILES src/file2.c LOCATION SRAM) |
|
|
|
* if the memory type is appended with _DATA, _TEXT, _RODATA or _BSS, only the |
|
selected memory is placed in the required memory region. |
|
for example: |
|
|
|
.. code-block:: none |
|
|
|
zephyr_code_relocate(FILES src/file1.c LOCATION SRAM2_DATA) |
|
zephyr_code_relocate(FILES src/file2.c LOCATION SRAM2_TEXT) |
|
|
|
* Multiple regions can also be appended together such as: SRAM2_DATA_BSS. |
|
This will place data and bss inside SRAM2. |
|
|
|
* Multiple files can be passed to the FILES argument, or CMake generator |
|
expressions can be used to relocate a comma-separated list of files |
|
|
|
.. code-block:: none |
|
|
|
file(GLOB sources "file*.c") |
|
zephyr_code_relocate(FILES ${sources} LOCATION SRAM) |
|
zephyr_code_relocate(FILES $<TARGET_PROPERTY:my_tgt,SOURCES> LOCATION SRAM) |
|
|
|
Section Filtering |
|
================= |
|
|
|
By default, all sections of the specified files will be relocated. If |
|
``FILTER`` is used, a regular expression is provided to select only |
|
the sections to be relocated. |
|
|
|
The regular expression applies to sections names which can be used to |
|
select the file's symbols when this one has been built with |
|
``-ffunction-sections`` and ``-fdata-sections`` which is the case by |
|
default. |
|
|
|
.. code-block:: none |
|
|
|
zephyr_code_relocate(FILES src/file1.c FILTER ".*\\.func1|.*\\.func2" LOCATION SRAM2_TEXT) |
|
|
|
The example above will only relocate ``func1()`` and ``func2()`` of file ``src/file1.c`` |
|
|
|
NOKEEP flag |
|
=========== |
|
|
|
By default, all relocated functions and variables will be marked with ``KEEP()`` |
|
when generating ``linker_relocate.ld``. Therefore, if any input file happens to |
|
contain unused symbols, then they will not be discarded by the linker, even when |
|
it is invoked with ``--gc-sections``. If you'd like to override this behavior, |
|
you can pass ``NOKEEP`` to your ``zephyr_code_relocate()`` call. |
|
|
|
.. code-block:: none |
|
|
|
zephyr_code_relocate(FILES src/file1.c LOCATION SRAM2_TEXT NOKEEP) |
|
|
|
The example above will help ensure that any unused code found in the .text |
|
sections of ``file1.c`` will not stick to SRAM2. |
|
|
|
NOCOPY flag |
|
=========== |
|
|
|
When a ``NOCOPY`` option is passed to the ``zephyr_code_relocate()`` function, |
|
the relocation code is not generated in ``code_relocation.c``. This flag can be |
|
used when we want to move the content of a specific file (or set of files) to a |
|
XIP area. |
|
|
|
This example will place the .text section of the ``xip_external_flash.c`` file |
|
to the ``EXTFLASH`` memory region where it will be executed from (XIP). The |
|
.data will be relocated as usual into SRAM. |
|
|
|
.. code-block:: none |
|
|
|
zephyr_code_relocate(FILES src/xip_external_flash.c LOCATION EXTFLASH_TEXT NOCOPY) |
|
zephyr_code_relocate(FILES src/xip_external_flash.c LOCATION SRAM_DATA) |
|
|
|
Relocating libraries |
|
==================== |
|
|
|
Libraries can be relocated using the LIBRARY argument to |
|
``zephyr_code_relocation()`` with the library name. For example, the following |
|
snippet will relocate serial drivers to SRAM2: |
|
|
|
.. code-block:: none |
|
|
|
zephyr_code_relocate(LIBRARY drivers__serial LOCATION SRAM2) |
|
|
|
Tips |
|
==== |
|
|
|
Take care if relocating kernel/arch files, some contain early initialization |
|
code that executes before code relocation takes place. |
|
|
|
Additional MPU/MMU configuration may be required to ensure that the |
|
destination memory region is configured to allow code execution. |
|
|
|
Samples/ Tests |
|
============== |
|
|
|
A test showcasing this feature is provided at |
|
``$ZEPHYR_BASE/tests/application_development/code_relocation`` |
|
|
|
This test shows how the code relocation feature is used. |
|
|
|
This test will place .text, .data, .bss from 3 files to various parts in the SRAM |
|
using a custom linker file derived from ``include/zephyr/arch/arm/cortex_m/scripts/linker.ld`` |
|
|
|
A sample showcasing the NOCOPY flag is provided here: :zephyr:code-sample:`code_relocation_nocopy`.
|
|
|