{"id":4484,"date":"2019-01-02T14:31:11","date_gmt":"2019-01-02T22:31:11","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=4484"},"modified":"2019-01-02T14:33:37","modified_gmt":"2019-01-02T22:33:37","slug":"understanding-gnu-linker-scripts","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/arm\/linkerscripts\/","title":{"rendered":"Customizing Memory Layout of Embedded Programs with GNU Linker Scripts"},"content":{"rendered":"

This tutorial shows how to use linker scripts to control the memory layout of your embedded programs. We will create a basic “Blinking LED” program, add a new global variable to it and will use the linker script to place this variable in several specific memory locations. Before you begin, install VisualGDB 5.3 or later.<\/p>\n

    \n
  1. Start Visual Studio and open the VisualGDB Embedded Project Wizard:\"\"<\/a><\/li>\n
  2. Proceed with creating a new MSBuild-based project: \"\"<\/a><\/li>\n
  3. On the Device Selection page pick the toolchain and the device. In this tutorial we will use the STM32F4Discovery board and hence will select the STM32F407VG device:\"\"<\/a><\/li>\n
  4. Select a sample project to clone. In this tutorial we will pick the simplest “LEDBlink” project:
    \n    \"\"<\/a><\/li>\n
  5. Connect your debugger to the USB port and let VisualGDB detect it, or simply choose it from the list:\"\"<\/a><\/li>\n
  6. Press “Finish” to generate the project. Then open VisualGDB Project Properties, go to MSBuild Settings page and click “Linker Script -> Copy to project directory”:\"\"<\/a><\/li>\n
  7. Locate the linker script in Solution Explorer and open it:\"\"<\/a><\/li>\n
  8. Each linker script consists of the 2 main parts:\n
      \n
    1. Definition of the memory regions, such as SRAM and FLASH.<\/li>\n
    2. Rules that define where each part of the program (e.g. functions, variables or special artifacts such as the interrupt vector table) gets placed.<\/li>\n<\/ol>\n

      Parts of the program with similar properties (e.g. all regular functions) are often grouped into sections – consecutive regions of memory sharing the same attributes. In this example, the first section going into the FLASH memory is .isr_vector<\/strong>.
      \nYou can see to see the result of the linker script (i.e. the addresses assigned to each section and symbol in your program) by generating the map files as shown below:<\/p>\n

      \"\"<\/a><\/li>\n

    3. Build the project and open the map file shown in the build output. Then search for .isr_vector<\/strong> in it:\"\"<\/a>See how the .isr_vector<\/strong> section containing the g_pfnVectors<\/strong> variable got placed at the 0x08000000<\/strong> address (beginning of the FLASH memory as defined in the linker script).<\/li>\n
    4. Search for the g_pfnVectors<\/strong> variable in the source files. See how it is explicitly placed into the “.isr_vector” section using the “section” attribute:\"\"<\/a>Regular functions and variables that do not have a “section” attribute will be placed into the “.text.<function name><\/strong>” and “.data.<variable name><\/strong>” sections. Having one section per function or variable allows linker to automatically discard the unused functions (the linker can drop the sections not referenced by any other section).<\/li>\n
    5. Now we will add a new global variable and use the “section” attribute together with some linker script constructs to place it at a fixed location in the memory.\u00a0 Add the following code to your main source file:\n
      int __attribute__((section(\".newsection\"))) VariableAt0x2000 = 1234;<\/pre>\n
      \"\"<\/a><\/li>\n
    6. Now add the following lines inside the .isr_vector<\/strong> section definition:\n
      . = 0x2000;\r\nKEEP(*(.newsection))<\/pre>\n
      \"\"<\/a>The “. = 0x2000” statement sets the “current address” pointer to 0x2000 (counting from the beginning of the section) and the *(.newsection)<\/strong> places the contents of the “.newscetion” sections from all source files at the current location. The KEEP() construct forces the linker to keep the sections in the final executable file even if they are not referenced by any other code (as we have not referenced the VariableAt0x2000<\/strong> variable from any code, it would have normally been discarded).<\/li>\n
    7. Build the project again and check the map file. See how the VariableAt0x2000<\/strong> got placed inside the .isr_vector<\/strong> section exactly at the 0x08002000<\/strong> address:\"\"<\/a><\/li>\n
    8. If you want to align the variable at a certain boundary (e.g. 0x1000) instead of hardcoding the address, you can use the ALIGN() keyword as shown below:\n
      .isr_vector :\r\n{\r\n\t. = ALIGN(4);\r\n\tKEEP(*(.isr_vector))\r\n\t. = ALIGN(4);\r\n\r\n\tFILL(0xff)\r\n\t. = ALIGN(0x1000);\r\n\tKEEP(*(.newsection))\r\n} > FLASH<\/pre>\n
      This will result in the following output:<\/p>\n
       *(.isr_vector)\r\n .isr_vector    0x08000000      0x188 VisualGDB\/Debug\/startup_stm32f407xx.o\r\n                0x08000000                g_pfnVectors\r\n                0x08000188                . = ALIGN (0x4)\r\n FILL mask 0xff\r\n                0x08001000                . = ALIGN (0x1000)\r\n *fill*         0x08000188      0xe78 ff\r\n *(.newsection)\r\n .newsection    0x08001000        0x4 VisualGDB\/Debug\/LEDBlink.o\r\n                0x08001000                VariableAt0x2000<\/pre>\n<\/li>\n
    9. Now we will try placing our global variable inside another memory. The STM32F407VG device includes 64 kilobytes of CCMRAM (see the linker script), so we will place our variable there:\u00a0\"\"<\/a>If your device has a single RAM region, you can split it into 2 parts by editing the MEMORY part of the linker script to try out the techniques from the rest of the tutorial.<\/li>\n
    10. Remove the “.newsection” reference from .isr_vector<\/strong> and place it into a separate section at the end of the SECTIONS part of the linker script:\"\"<\/a><\/li>\n
    11. Build the project and check the map file. See how the VariableAt0x2000<\/strong> got placed to 0x10000000<\/strong> (beginning of CCMRAM):\"\"<\/a><\/li>\n
    12. Despite being placed at the correct address, this memory layout will have several side effects that we will explain below. First of all, locate the .bin<\/strong> file generated for your project. Depending on the exact memory address of .newsection<\/strong>, it can be several megabytes to gigabytes long:\"\"<\/a><\/li>\n
    13. Then try modifying the variable from your program and run it. First time you start a debug session, the variable value will be correct:\"\"<\/a><\/li>\n
    14. However, if you try resetting the program, you will see that the variable value will not be changed from the previous run (in this example it was incremented from 1234 to 1235 in the previosu run and got further incremented to 1236 just now):\"\"
      \n<\/a>Furthermore, if you try power-cycling your device and attach to the program without programming it, the variable in CCMRAM will not be initialized at all (depending on your device type, it will have either a value of 0, or a random value).<\/li>\n
    15. Both the .bin<\/strong> file size and the incorrect initialization happen due to the same reason. Simply placing a variable at the address of 0x10000000<\/strong>\u00a0would make the tools act as if it was a part of the FLASH memory:\n