From de8478b7f33f55850cf1bb53d8c58bba87f962ac Mon Sep 17 00:00:00 2001 From: Daniel DeGrasse Date: Tue, 4 Oct 2022 18:47:59 -0500 Subject: [PATCH] doc: code-relocation: Update usage of zephyr_code_relocate Update usage of zephyr_code_relocate to new API, and add examples of relocating a library target, as well as using multiple files in list or CMake generator expressions. Signed-off-by: Daniel DeGrasse --- doc/kernel/code-relocation.rst | 36 +++++++++++++++++++++++------- doc/releases/release-notes-3.3.rst | 5 +++++ 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/doc/kernel/code-relocation.rst b/doc/kernel/code-relocation.rst index 90ce99d0ba2..2e75b542787 100644 --- a/doc/kernel/code-relocation.rst +++ b/doc/kernel/code-relocation.rst @@ -54,14 +54,13 @@ for data copy operations from ROM to required memory type. * Inside the ``CMakeLists.txt`` file in the project, mention all the files that need relocation. - ``zephyr_code_relocate(src/*.c SRAM2)`` + ``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:: - The file argument supports limited regular expressions. function zephyr_code_relocate() can be called as many times as required. This step has to be performed before calling find_package(Zephyr ...) in the application's CMakeLists.txt. @@ -77,8 +76,8 @@ This section shows additional configuration options that can be set in .. code-block:: none - zephyr_code_relocate(src/file1.c SRAM2) - zephyr_code_relocate(src/file2.c.c SRAM) + 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. @@ -86,12 +85,21 @@ This section shows additional configuration options that can be set in .. code-block:: none - zephyr_code_relocate(src/file1.c SRAM2_DATA) - zephyr_code_relocate(src/file2.c.c SRAM2_TEXT) + 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 $ LOCATION SRAM) + NOCOPY flag =========== @@ -106,8 +114,20 @@ to the ``EXTFLASH`` memory region where it will be executed from (XIP). The .. code-block:: none - zephyr_code_relocate(src/xip_external_flash.c EXTFLASH_TEXT NOCOPY) - zephyr_code_relocate(src/xip_external_flash.c SRAM_DATA) + 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 kernel code to ITCM and serial drivers to SRAM2: + + .. code-block:: none + + zephyr_code_relocate(LIBRARY kernel LOCATION ITCM_TEXT) + zephyr_code_relocate(LIBRARY drivers__serial LOCATION SRAM2) Sample ====== diff --git a/doc/releases/release-notes-3.3.rst b/doc/releases/release-notes-3.3.rst index 7a8ab8f25c5..0a5a5caf7e8 100644 --- a/doc/releases/release-notes-3.3.rst +++ b/doc/releases/release-notes-3.3.rst @@ -311,6 +311,11 @@ Boards & SoC Support Build system and infrastructure ******************************* +* Code relocation + + * ``zephyr_code_relocate`` API has changed to accept a list of files to + relocate and a location to place the files. + Drivers and Sensors *******************