A Sample Linker Script

from:http://www.hertaville.com/a-sample-linker-script.html

A sample script file that will work with C based projects is provided below:

/******************************************************************************
    * This linker file was developed by Hussam Al-Hertani. Please use freely as
    * long as you leave this header in place. The author is not responsible for any
    * damage or liability that this file might cause.
******************************************************************************/

   /* Entry Point */
   ENTRY(Reset_Handler)

   /* Specify the memory areas */
   MEMORY
   {
     FLASH (rx)      : ORIGIN = 0x08000000, LENGTH = 0x10000 /*64K*/
     RAM (xrw)       : ORIGIN = 0x20000000, LENGTH = 0x02000 /*8K*/
   }

   /* define stack size and heap size here */
   stack_size = ;
   heap_size = ;

   /* define beginning and ending of stack */
   _stack_start = ORIGIN(RAM)+LENGTH(RAM);
   _stack_end = _stack_start - stack_size;

   /* Define output sections */
   SECTIONS
   {
     /* The startup code goes first into FLASH */
     .isr_vector :
     {
       . = ALIGN();
       KEEP(*(.isr_vector)) /* Startup code */
       . = ALIGN();
     } >FLASH

     /* The program code and other data goes into FLASH */
     .text :
     {
       . = ALIGN();
       *(.text)           /* .text sections (code) */
       *(.text*)          /* .text* sections (code) */
       *(.rodata)         /* .rodata sections (constants, strings, etc.) */
       *(.rodata*)        /* .rodata* sections (constants, strings, etc.) */
       *(.glue_7)         /* glue arm to thumb code */
       *(.glue_7t)        /* glue thumb to arm code */
       . = ALIGN();
       _etext = .;        /* define a global symbols at end of code */
     } >FLASH

      .ARM.extab   : { *(.ARM.extab* .gnu.linkonce.armextab.*) } >FLASH
       .ARM : {
       __exidx_start = .;
         *(.ARM.exidx*)
         __exidx_end = .;
       } >FLASH

     /* used by the startup to initialize data */
     _sidata = .;

     /* Initialized data sections goes into RAM, load LMA copy after code */
     .data : AT ( _sidata )
     {
       . = ALIGN();
       _sdata = .;        /* create a global symbol at data start */
       *(.data)           /* .data sections */
       *(.data*)          /* .data* sections */

       . = ALIGN();
       _edata = .;        /* define a global symbol at data end */
     } >RAM

     /* Uninitialized data section */
     . = ALIGN();
     .bss :
     {
       /*  Used by the startup in order to initialize the .bss secion */
       _sbss = .;         /* define a global symbol at bss start */
       __bss_start__ = _sbss;
       *(.bss)
       *(.bss*)
       *(COMMON)

       . = ALIGN();
       _ebss = .;         /* define a global symbol at bss end */
       __bss_end__ = _ebss;
     } >RAM

       . = ALIGN();
       .heap :
       {
           _heap_start = .;
           . = . + heap_size;
                   _heap_end = .;
       } > RAM

       /* Remove information from the standard libraries */
       /DISCARD/ :
       {
           libc.a ( * )
           libm.a ( * )
           libgcc.a ( * )
       }

       .ARM.attributes  : { *(.ARM.attributes) }
   }

The Linker script is somewhat self documenting. I will briefly go through the various sections. The first line of the linker script is:

ENTRY(Reset_Handler)

This defines the entry point into the chip. On exit from a reset condition, the first thing that the MCU executes is a reset handler function that initializes the chip and puts it in a known state. To view this handler (interrupt subroutine (ISR)) function take a look at the startup file.

The linker script then defines the sections of the memory map that in to which it will map the various sections of the object files. It does this in "Memory" section.

/* Specify the memory areas */
MEMORY
{
  FLASH (rx)      : ORIGIN = 0x08000000, LENGTH = 0x10000 /*64K*/
  RAM (xrw)       : ORIGIN = 0x20000000, LENGTH = 0x02000 /*8K*/
}

The memory map of the STM32F051C8 chip is shown in Page 35 of the datasheet . It shows that the Flash memory section starts at address 0x08000000 and is 64KB long or 65536 bytes long which in hex is 0x10000. The RAM memory section starts a address 0x20000000 and is 8KB long or 8192 bytes long, which in hex is 0x02000 . All of this information is provided to the linker via the memory section of the linker script. Also note the the FLASH memory s defined as (rx) which means that it has read and execute only, whereas the RAM memory is defined as (xrw) which means that it is read, write and execute.

The next major section of the linker script is called "SECTIONS". It defines where each if the various sections of the object files goes into the memory map defined in the MEMORY section.

The first section defined under SECTIONS is the .isr_vector section. This section contains the interrupt vector table and the startup / initialization code i.e. the body of the Reset handler routine specified as the entry point. This is put first in flash memory starting at 0x08000000 as specified by the ">FLASH" found at the end of the section.

/* Define output sections */
SECTIONS
{
  /* The startup code goes first into FLASH */
  .isr_vector :
  {
    . = ALIGN();
    KEEP(*(.isr_vector)) /* Startup code */
    . = ALIGN();
  } >FLASH

The ALIGN(4) instructions tells the linker that this section ought to be word aligned. Since this is a 32-bit machine it typically needs to be word aligned (32-bit -> 4 bytes hence the '4' specified with the align command. )

/* The program code and other data goes into FLASH */
  .text :
  {
    . = ALIGN();
    *(.text)           /* .text sections (code) */
    *(.text*)          /* .text* sections (code) */
    *(.rodata)         /* .rodata sections (constants, strings, etc.) */
    *(.rodata*)        /* .rodata* sections (constants, strings, etc.) */
    *(.glue_7)         /* glue arm to thumb code */
    *(.glue_7t)        /* glue thumb to arm code */
    . = ALIGN();
    _etext = .;        /* define a global symbols at end of code */
  } >FLASH

The next section of the linker script is the .text section. This section includes all the .text sections from the object files. These .text sections contain all the binary instructions that our c and assembly programs were compiled/assembled into and are typically put in program memory, which in this case is flash. Notice that this section also contains .rodata sections which signifies that right after the linker has put the binary instructions into the program memory, it should but the constant data in their as well. At this point in time I'm not quite sure of the .glue_7 sections but I think they have to do with backwards compatibility between arm and thumb instructions. They are probably not needed. ofcourse this entire section .text section is put in Flash via the ">FLASH" linker instruction.

.ARM.extab   : { *(.ARM.extab* .gnu.linkonce.armextab.*) } >FLASH
    .ARM : {
    __exidx_start = .;
      *(.ARM.exidx*)
      __exidx_end = .;
    } >FLASH

The following .ARM.extab section has to do with table/loop unwinding. I have found little information on it. I have included it here even though I know that I probably do not need it.

/* Initialized data sections goes into RAM, load LMA copy after code */
  .data : AT ( _sidata )
  {
    . = ALIGN();
    _sdata = .;        /* create a global symbol at data start */
    *(.data)           /* .data sections */
    *(.data*)          /* .data* sections */

    . = ALIGN();
    _edata = .;        /* define a global symbol at data end */
  } >RAM

The .data section contains all initialized global and static variables. the "AT" basically means that this code will be put in both (via LMA initializer) Flash and RAM. To explain this further the static and global variables of the .data section need to be stored in two different locations:

• VMA (virtual memory address): the run-time address where the compiled code expects the variables to be. This will be in RAM as signified by ">RAM".
• LMA (load memory address): the addresses to which the initialization data are stored by the linker. This will be in Flash as signified by the "AT".

The startup code will copy from .data section's LMA to .data section's VMA.

/* Uninitialized data section */
  . = ALIGN();
  .bss :
  {
    /*  Used by the startup in order to initialize the .bss secion */
    _sbss = .;         /* define a global symbol at bss start */
    __bss_start__ = _sbss;
    *(.bss)
    *(.bss*)
    *(COMMON)

    . = ALIGN();
    _ebss = .;         /* define a global symbol at bss end */
    __bss_end__ = _ebss;
  } >RAM

The next section of the linker script is the .bss section. The .bss section consists of uninitialized static and global variables. This section is saved in RAM.

. = ALIGN();
.heap :
{
    _heap_start = .;
    . = . + heap_size;
            _heap_end = .;
} > RAM

The next  section define the heap section of RAM. The heap starts right after the bss section and continues on until the heap size specified by the heap_size variable at the beginning of the script. With the exception of the stack, all other sections grow upwards. The stack grows downwards. This basically means that the stack starts at the last location in the RAM which is 0x20002000 and grows downwards from their via the "stack_size" variable. Both the "stack_size" and the "heap_size" variables control the sizes of the stack and heap respectively. They must be sized such that both sections never overlap i.e. the sum of the two variables and the sizes of the data(VMA) and bss sections, must never be larger than the 8192.

Because the linker needs to specify memory sections in an upwards / growing fashion, we used the _stack_begin label, which basically is assigned to the address 0x20002000 and the stack size to determine the value of the _stack_end variable in the top of the script. This is used to decide where the stack section starts from the perspective of the linker.

Figure 1 represents the linker file rules graphically and demonstrates how the various sections are mapped into the Flash and RAM memories. The labels such as _etext, _sdata, _edata e.t.c define the begin and/or end addresses for each section.

Figure 1. Graphical representation of the rules defined in the linker file

The final sections ensure that no redundant code from the standard libraries is included into memory. I do not know the purpose of the ".ARM.attributes 0" line either. The linker files would very likely function just fine without, but I will keep them for the time being.

 /* Remove information from the standard libraries */
    /DISCARD/ :
    {
        libc.a ( * )
        libm.a ( * )
        libgcc.a ( * )
    }

    .ARM.attributes  : { *(.ARM.attributes) }
}

This concludes our explanation of (most of) the linker file sections and its structure.