8. Linker Script

8.1. 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.

8.2. 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.

8.3. Different Stacks

There is more than one stack in the system.

8.3.1. 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.

8.3.2. 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.

8.4. FreeRTOS Heap vs. TI Runtime Heap

Two different heaps exist in the application.

8.4.1. 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.

8.4.2. 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

8.5. 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.

8.6. 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 │
└────────────────────────────────────────┴────────────┘

8.7. 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.

8.7.1. 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 │
└───────────────────────────────────────────────┴────────────┘

8.7.2. 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 │
└───────────────────────────────────────────────┴────────────┘

8.7.3. 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 │
└───────────────────────────────────────────────┴────────────┘