1.. _code_data_relocation:
2
3Code And Data Relocation
4########################
5
6Overview
7********
8This feature will allow relocating .text, .rodata, .data, and .bss sections from
9required files and place them in the required memory region. The memory region
10and file are given to the :ref:`gen_relocate_app.py` script in the form
11of a string. This script is always invoked from inside cmake.
12
13This script provides a robust way to re-order the memory contents without
14actually having to modify the code.  In simple terms this script will do the job
15of ``__attribute__((section("name")))`` for a bunch of files together.
16
17A regular expression filter can be used to select only the required sections to be relocated.
18
19Details
20*******
21The memory region and file are given to the :ref:`gen_relocate_app.py` script
22through a file where each line specifies a list of files to be placed in the
23given region.
24
25An example of such a file is:
26
27  .. code-block:: none
28
29     SRAM2:/home/xyz/zephyr/samples/hello_world/src/main.c,
30     SRAM1:/home/xyz/zephyr/samples/hello_world/src/main2.c,
31
32This script is invoked with the following parameters:
33``python3 gen_relocate_app.py -i input_file -o generated_linker -c generated_code``
34
35Kconfig :kconfig:option:`CONFIG_CODE_DATA_RELOCATION` option,  when enabled in
36``prj.conf``, will invoke the script and do the required relocation.
37
38This script also trigger the generation of ``linker_relocate.ld`` and
39``code_relocation.c`` files.  The ``linker_relocate.ld`` file creates
40appropriate sections and links the required functions or variables from all the
41selected files.
42
43.. note::
44
45   The text section is split into 2 parts in the main linker script. The first
46   section will have some info regarding vector tables and other debug related
47   info.  The second section will have the complete text section.  This is
48   needed to force the required functions and data variables to the correct
49   locations.  This is due to the behavior of the linker. The linker will only
50   link once and hence this text section had to be split to make room for the
51   generated linker script.
52
53The ``code_relocation.c`` file has code that is needed for
54initializing data sections, and a copy of the text sections (if XIP).
55Also this contains code needed for bss zeroing and
56for  data copy operations from ROM to required memory type.
57
58**The procedure to invoke this feature is:**
59
60* Enable :kconfig:option:`CONFIG_CODE_DATA_RELOCATION` in the ``prj.conf`` file
61
62* Inside the ``CMakeLists.txt`` file in the project, mention
63  all the files that need relocation.
64
65  ``zephyr_code_relocate(FILES src/*.c LOCATION SRAM2)``
66
67  Where the first argument is the file/files and the second
68  argument is the memory where it must be placed.
69
70  .. note::
71
72     function zephyr_code_relocate() can be called  as many times as required.
73
74Additional Configurations
75=========================
76This section shows additional configuration options that can be set in
77``CMakeLists.txt``.
78
79* If the memory is ``SRAM1``, ``SRAM2``, ``CCD``, or ``AON``, then place the
80  full object in the sections. For example:
81
82  .. code-block:: none
83
84     zephyr_code_relocate(FILES src/file1.c LOCATION SRAM2)
85     zephyr_code_relocate(FILES src/file2.c LOCATION SRAM)
86
87* If the memory type is appended with ``_DATA``, ``_TEXT``, ``_RODATA``,
88  ``_BSS`` or ``_NOINIT``, only the selected memory is placed in the required
89  memory region. For example:
90
91  .. code-block:: none
92
93     zephyr_code_relocate(FILES src/file1.c LOCATION SRAM2_DATA)
94     zephyr_code_relocate(FILES src/file2.c LOCATION SRAM2_TEXT)
95
96* Multiple regions can also be appended together such as:
97  ``SRAM2_DATA_BSS_NOINIT``. This will place all data: value-initialized,
98  zero-initialized and uninitialized inside ``SRAM2``.
99
100* Multiple files can be passed to the ``FILES`` argument, or CMake generator
101  expressions can be used to relocate a comma-separated list of files.
102
103  .. code-block:: none
104
105     file(GLOB sources "file*.c")
106     zephyr_code_relocate(FILES ${sources} LOCATION SRAM)
107     zephyr_code_relocate(FILES $<TARGET_PROPERTY:my_tgt,SOURCES> LOCATION SRAM)
108
109Section Filtering
110=================
111
112By default, all sections of the specified files will be relocated. If
113``FILTER`` is used, a regular expression is provided to select only
114the sections to be relocated.
115
116The regular expression applies to sections names which can be used to
117select the file's symbols when this one has been built with
118``-ffunction-sections`` and ``-fdata-sections`` which is the case by
119default.
120
121  .. code-block:: none
122
123     zephyr_code_relocate(FILES src/file1.c FILTER ".*\\.func1|.*\\.func2" LOCATION SRAM2_TEXT)
124
125The example above will only relocate ``func1()`` and ``func2()`` of file ``src/file1.c``
126
127NOKEEP flag
128===========
129
130By default, all relocated functions and variables will be marked with ``KEEP()``
131when generating ``linker_relocate.ld``.  Therefore, if any input file happens to
132contain unused symbols, then they will not be discarded by the linker, even when
133it is invoked with ``--gc-sections``. If you'd like to override this behavior,
134you can pass ``NOKEEP`` to your ``zephyr_code_relocate()`` call.
135
136  .. code-block:: none
137
138     zephyr_code_relocate(FILES src/file1.c LOCATION SRAM2_TEXT NOKEEP)
139
140The example above will help ensure that any unused code found in the .text
141sections of ``file1.c`` will not stick to SRAM2.
142
143NOCOPY flag
144===========
145
146When a ``NOCOPY`` option is passed to the ``zephyr_code_relocate()`` function,
147the relocation code is not generated in ``code_relocation.c``. This flag can be
148used when we want to move the content of a specific file (or set of files) to a
149XIP area.
150
151This example will place the .text section of the ``xip_external_flash.c`` file
152to the ``EXTFLASH`` memory region where it will be executed from (XIP). The
153.data will be relocated as usual into SRAM.
154
155  .. code-block:: none
156
157     zephyr_code_relocate(FILES src/xip_external_flash.c LOCATION EXTFLASH_TEXT NOCOPY)
158     zephyr_code_relocate(FILES src/xip_external_flash.c LOCATION SRAM_DATA)
159
160Relocating libraries
161====================
162
163Libraries can be relocated using the LIBRARY argument to
164``zephyr_code_relocation()`` with the library name. For example, the following
165snippet will relocate serial drivers to SRAM2:
166
167  .. code-block:: none
168
169    zephyr_code_relocate(LIBRARY drivers__serial LOCATION SRAM2)
170
171Tips
172====
173
174Take care if relocating kernel/arch files, some contain early initialization
175code that executes before code relocation takes place.
176
177Additional MPU/MMU configuration may be required to ensure that the
178destination memory region is configured to allow code execution.
179
180Samples/ Tests
181==============
182
183A test showcasing this feature is provided at
184``$ZEPHYR_BASE/tests/application_development/code_relocation``
185
186This test shows how the code relocation feature is used.
187
188This test will place .text, .data, .bss from 3 files to various parts in the SRAM
189using a custom linker file derived from ``include/zephyr/arch/arm/cortex_m/scripts/linker.ld``
190
191A sample showcasing the NOCOPY flag is provided here: :zephyr:code-sample:`code_relocation_nocopy`.
192