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