.. include:: ../../macros.txt .. include:: ../../units.txt .. _LINKER_SCRIPT: Linker Script ============= Overview -------- The application build combines four different layers that each describe a part of the runtime memory behavior: - The application linker scripts ``src/app/main/app.cmd`` and ``src/app/main/app_hex.cmd`` define the memory map and section placement. - The HALCoGen configuration in ``conf/hcg/app.hcg`` and ``conf/hcg/app.dil`` generates startup code such as ``_coreInitStackPointer_()``. - The |freertos| configuration in ``src/os/freertos/freertos/include/FreeRTOSConfig.h`` defines the RTOS heap and task behavior. - The port.c file in ``src/os/freertos/freertos/portable/ccs/arm_cortex-r5/port.c`` defines the MPU configuration and access rights for the different memory regions. Relevant Files -------------- For the application build, the following files are the relevant sources for review and maintenance: - ``src/app/main/app.cmd`` - ``src/app/main/app_hex.cmd`` - ``src/os/freertos/freertos/include/FreeRTOSConfig.h`` - ``src/os/freertos/freertos/portable/ccs/arm_cortex-r5/port.c`` - ``conf/hcg/app.dil`` Notes: - ``src/app/main/app.cmd`` is the primary linker-script source. - ``src/app/main/app_hex.cmd`` is a derived memory map representation. - Parts of ``port.c`` are generated by HALCoGen; manual changes must preserve alignment with linker and HALCoGen settings. Different Stacks ---------------- There is more than one stack in the system. TI runtime stack ++++++++++++++++ The linker flag ``--stack_size=0x2000`` in ``src/app/main/app.cmd`` configures the TI runtime stack size. The linker script region ``STACKS`` refers to this stack. The HALCoGen setting ``DRIVER.SYSTEM.VAR.RAM_STACK_LENGTH.VALUE`` in ``conf/hcg/app.dil`` must stay aligned with this because HALCoGen generates the stack pointer initialization code. FreeRTOS task stacks ++++++++++++++++++++ Each |freertos| task has its own task stack. Those stack sizes are configured per task in the application code, for example in the task configuration files. These task stacks are not the same as the TI runtime stack from ``--stack_size``. FreeRTOS Heap vs. TI Runtime Heap --------------------------------- Two different heaps exist in the application. FreeRTOS heap +++++++++++++ ``configTOTAL_HEAP_SIZE`` in ``FreeRTOSConfig.h`` configures the |freertos| heap. In the current configuration it is ``40 * 1024`` bytes, i.e. ``0xA000``. This heap contributes to the amount of privileged RAM that must fit into the ``KERNEL_DATA`` region, but it does not define the full size of ``KERNEL_DATA`` by itself. ``KERNEL_DATA`` also contains other privileged data. TI runtime heap +++++++++++++++ The linker flag ``--heap_size=0x2000`` in ``src/app/main/app.cmd`` configures the TI C runtime heap that backs functions such as ``malloc()`` and ``free()``. This heap is placed into the ``.sysmem`` section. In ``src/app/main/app.cmd``, ``.sysmem`` is placed into the general ``RAM`` region, not into ``KERNEL_DATA``. Therefore: - ``configTOTAL_HEAP_SIZE`` controls the |freertos| heap - ``--heap_size`` controls the TI runtime heap - they are independent and should not be confused Shared RAM for DMA ------------------ ``SHARED_RAM`` is the dedicated non-cacheable RAM window used for DMA-related data. The same region must stay consistent across: - ``src/app/main/app.cmd`` - ``src/app/main/app_hex.cmd`` - ``src/os/freertos/freertos/portable/ccs/arm_cortex-r5/port.c`` The linker places variables into this region via the ``.sharedRAM`` section. The MPU configuration in ``port.c`` marks the same address range as non-cacheable shared memory. Memory Map ---------- The relevant parts of the memory map of the TMS 570LC4375 for configuring the linker script are:: ┌────────────────────────────────────────┬────────────┐ │ ... │ │ │ │ │ ├────────────────────────────────────────┼────────────┤ │ Flash │ 0xF047FFFF │ │ (Flash ECC, OTP and EEPROM accesses) │ 0xF0000000 │ ├────────────────────────────────────────┼────────────┤ │ ... │ │ │ │ │ ├────────────────────────────────────────┼────────────┤ │ RAM (512KB) │ 0x0807FFFF │ │ │ 0x08000000 │ ├────────────────────────────────────────┼────────────┤ │ ... │ │ │ │ │ ├────────────────────────────────────────┼────────────┤ │ Flash (4MB) │ 0x003FFFFF │ │ │ 0x00000000 │ └────────────────────────────────────────┴────────────┘ The Flash bank is divided into two equally sized banks with a length of ``0x200000``, i.e., the total flash size is ``2 * 0x200000``. Detail information for the Flash ECC:: ┌────────────────────────────────────────┬────────────┐ │ Flash Data Space ECC │ 0xF05FFFFF │ │ │ 0xF047FFFF │ └────────────────────────────────────────┴────────────┘ Linker Script ------------- The application linker script is found at ``src/app/main/app.cmd``. A derived hex-linker script is found at ``src/app/main/app_hex.cmd``. The linker script for the bootloader is found at ``src/bootloader/main/bootloader.cmd``. The ``MEMORY`` and ``SECTIONS`` directives can be used to configure the allocation process. The ``ECC`` directive can be used to configure the Error-correcting code of the memory. The ``MEMORY`` directive tells the linker the location and the size of memory blocks. The task of the ``SECTIONS`` directive is to tell the linker how to map input sections into output sections, and how to place the output sections in memory, i.e., specific sections can be placed in particular memory regions. Memory Layout Configuration For App +++++++++++++++++++++++++++++++++++ Flash:: ┌───────────────────────────────────────────────┬────────────┐ │ VECTORS_TABLE │ 0x0001FFE0 │ │ (0x20) │ 0x0001FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ VER_VERSION_INFORMATION │ 0x00020000 │ │ (0xC0) │ 0x000200BF │ ├───────────────────────────────────────────────┼────────────┤ │ KERNEL_FUNCTIONS │ 0x000200C0 │ │ (0x8000) │ 0x000280BF │ ├───────────────────────────────────────────────┼────────────┤ │ APP_FLASH │ 0x000280C0 │ │ (0x3D7F40) │ 0x003FFFFF │ └───────────────────────────────────────────────┴────────────┘ RAM:: ┌───────────────────────────────────────────────┬────────────┐ │ STACKS │ 0x08000000 │ │ (0x2000) │ 0x08001FFF │ ├───────────────────────────────────────────────┼────────────┤ │ KERNEL_DATA │ 0x08010000 │ │ (0x10000) │ 0x0801FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ RAM │ 0x08020000 │ │ (0x5E000) │ 0x0807DFFF │ ├───────────────────────────────────────────────┼────────────┤ │ SHARED_RAM │ 0x0807E000 │ │ (0x2000) │ 0x0807FFFF │ └───────────────────────────────────────────────┴────────────┘ Flash ECC:: ┌───────────────────────────────────────────────┬────────────┐ │ ECC_VECTORS_TABLE │ 0xF0403FFC │ │ (0x4) │ 0xF0403FFF │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_VERSION_INFORMATION │ 0xF0404000 │ │ (0x18) │ 0xF0404017 │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_KERNEL_FUNCTIONS │ 0xF0404018 │ │ (0x1000) │ 0xF0405017 │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_APP_FLASH │ 0xF0405018 │ │ (0x7AFE8) │ 0xF047FFFF │ └───────────────────────────────────────────────┴────────────┘ Memory Layout Configuration For Bootloader ++++++++++++++++++++++++++++++++++++++++++ Flash:: ┌───────────────────────────────────────────────┬────────────┐ │ VECTORS_TABLE_INIT │ 0x00000000 │ │ (0x20) │ 0x0000001F │ ├───────────────────────────────────────────────┼────────────┤ │ BOOTLOADER │ 0x00000020 │ │ (0x17FE0) │ 0x00017FFF │ ├───────────────────────────────────────────────┼────────────┤ │ PROGRAM_INFO_AREA │ 0x00018000 │ │ (0x7FE0) │ 0x0001FFDF │ ├───────────────────────────────────────────────┼────────────┤ │ VECTORS_TABLE │ 0x0001FFE0 │ │ (0x20) │ 0x0001FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ PROGRAM_PLACE_HOLDER │ 0x00020000 │ │ (0x3E0000) │ 0x003FFFFF │ └───────────────────────────────────────────────┴────────────┘ RAM:: ┌───────────────────────────────────────────────┬────────────┐ │ STACK │ 0x08000000 │ │ (0x10000) │ 0x0800FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ RAM │ 0x08010000 │ │ (0x20000) │ 0x0802FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ RAM_FLASH │ 0x08030000 │ │ (0x40000) │ 0x0806FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ RAM_FLASH_API │ 0x08070000 │ │ (0x10000) │ 0x0807FFFF │ └───────────────────────────────────────────────┴────────────┘ Flash ECC:: ┌───────────────────────────────────────────────┬────────────┐ │ ECC_VECTORS_TABLE_INIT │ 0xF0400000 │ │ (0x4) │ 0xF0400003 │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_BOOTLOADER │ 0xF0400004 │ │ (0x2FFC) │ 0xF0402FFF │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_PROGRAM_INFO_AREA │ 0xF0403000 │ │ (0xFFC) │ 0xF0403FFB │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_VECTORS_TABLE │ 0xF0403FFC │ │ (0x4) │ 0xF0403FFF │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_PROGRAM_PLACE_HOLDER │ 0xF0404000 │ │ (0x7C000) │ 0xF047FFFF │ └───────────────────────────────────────────────┴────────────┘ Total Memory Layout After Uploading the App Using the Bootloader ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Flash:: ┌───────────────────────────────────────────────┬────────────┐ │ VECTORS_TABLE_INIT │ 0x00000000 │ │ (0x20) │ 0x0000001F │ ├───────────────────────────────────────────────┼────────────┤ │ BOOTLOADER │ 0x00000020 │ │ (0x17FE0) │ 0x00017FFF │ ├───────────────────────────────────────────────┼────────────┤ │ PROGRAM_INFO_AREA │ 0x00018000 │ │ (0x7FE0) │ 0x0001FFDF │ ├───────────────────────────────────────────────┼────────────┤ │ VECTORS_TABLE │ 0x0001FFE0 │ │ (0x20) │ 0x0001FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ VER_VERSION_INFORMATION │ 0x00020000 │ │ (0xC0) │ 0x000200BF │ ├───────────────────────────────────────────────┼────────────┤ │ KERNEL_FUNCTIONS │ 0x000200C0 │ │ (0x8000) │ 0x000280BF │ ├───────────────────────────────────────────────┼────────────┤ │ APP_FLASH │ 0x000280C0 │ │ (0x3D7F40) │ 0x003FFFFF │ └───────────────────────────────────────────────┴────────────┘ RAM:: ┌───────────────────────────────────────────────┬────────────┐ │ STACKS │ 0x08000000 │ │ (0x2000) │ 0x08001FFF │ ├───────────────────────────────────────────────┼────────────┤ │ KERNEL_DATA │ 0x08010000 │ │ (0x10000) │ 0x0801FFFF │ ├───────────────────────────────────────────────┼────────────┤ │ RAM │ 0x08020000 │ │ (0x5E000) │ 0x0807DFFF │ ├───────────────────────────────────────────────┼────────────┤ │ SHARED_RAM │ 0x0807E000 │ │ (0x2000) │ 0x0807FFFF │ └───────────────────────────────────────────────┴────────────┘ Flash ECC:: ┌───────────────────────────────────────────────┬────────────┐ │ ECC_VECTORS_TABLE_INIT │ 0xF0400000 │ │ (0x4) │ 0xF0400003 │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_BOOTLOADER │ 0xF0400004 │ │ (0x2FFC) │ 0xF0402FFF │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_PROGRAM_INFO_AREA │ 0xF0403000 │ │ (0xFFC) │ 0xF0403FFB │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_VECTORS_TABLE │ 0xF0403FFC │ │ (0x4) │ 0xF0403FFF │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_VERSION_INFORMATION │ 0xF0404000 │ │ (0x18) │ 0xF0404017 │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_KERNEL_FUNCTIONS │ 0xF0404018 │ │ (0x1000) │ 0xF0405017 │ ├───────────────────────────────────────────────┼────────────┤ │ ECC_APP_FLASH │ 0xF0405018 │ │ (0x7AFE8) │ 0xF047FFFF │ └───────────────────────────────────────────────┴────────────┘ Common Linker Script related Abbreviations ------------------------------------------ .. csv-table:: Common Linker Script related Abbreviations :name: common-linker-script-related-abbreviations :header-rows: 1 :delim: ; :file: ./linker-script-definitions.csv