Linker Scripts

The application executable building process can be divided into compiling and linking. Linking is performed by a linker that accepts linker command language files called linker scripts. The primary purpose of a linker script is to describe the memory layout of the target machine, and specify where each section of the program should be placed in memory.

Note: Only standalone applications need linker script. Linux OS helps managing the memory allocation, and thus it does not need a linker script.

The Vitis software platform provides a linker script generator to simplify the task of creating a linker script for GCC. The linker script generator GUI examines the target hardware platform and determines the available memory sections. The only action required by you is to assign the different code and data sections in the ELF file to different memory regions.

Note:
  • For multi-processor systems, each processor runs a different ELF file, and each ELF file requires its own linker script. Ensure that the two ELF files do not overlap in memory.
  • The default linker always points to the DDR address available in memory. If you are creating an application under a given hardware/domain project, the memory will overlap for the applications.

Generating a Linker Script for an Application

To generate a linker script for an application, do the following:

  1. Select the application project in the Project Navigator view.
  2. Right-click Generate Linker Script. Alternatively, you can click Xilinx > Generate Linker Script. The left side of the page is read-only, except for the Output Script name and project build settings in the Modify project build settings as follows field. This region shows all the available memory areas for the design. You have two choices of how to allocate memory: using the Basic view or the Advanced view. Both perform the same tasks; however, the Basic view is less granular and treats all types of data as “data” and all types of instructions as “code”. This is often sufficient to accomplish most tasks. Use the Advanced view for precise allocation of software blocks into various types of memory.
  3. Click OK.

    If there are errors, they must be corrected before you can build your application with the new linker script.

    Note: If the linker script already exists, a message view appears, asking if you want to overwrite the file. Click OK to overwrite the file or Cancel to cancel the overwrite.

    The Vitis software platform automatically adds the linker script to the linker settings for a managed make project based on the options selected in Modify project build settings as follows.

Basic Page

Configure the following sections of the Linker Script Generator page Basic view. Placing these key sections into the appropriate memory region can improve performance. Use the drop-down menu next to the code, data, and heap or stack sections to select the region and type of memory that you want these blocks to reside in.

Code Sections
This is used to store the executable code (instructions). Typically DDR memory is used for this task. Sometimes interrupt handlers or frequently used functions are built into separate sections and can be mapped to lower latency memory such as BRAM or OCM.
Data Sections
Place initialized and uninitialized data in this region. Often DDR memory is used; however, if the data size requirements are small, OCM or BRAM can be used to improve performance.
Heap and Stack
Heap is accessed through dynamic memory allocation calls such as malloc(). These sections are typically left in DDR unless they are known to be small, in which case they can be placed in OCM or BRAM. If the stack is lightly used, no significant performance loss will occur if left in DDR.
Heap Size
Specify the heap size. Even if a programmer does not use dynamic memory allocation explicitly, there are some functions that use the heap such as printf(). It is a good idea to allocate a few KB for such functions, as a precaution.
Stack Size
Specify the stack size. Remember that the stack size grows down in memory and could overrun the heap without warning. Make certain that you allocate enough memory, especially if you use recursive functions or deep hierarchies.


Advanced Page

If you require more control over the definition of memory sections and assignments to them, use the LinkerScript Generator page Advanced view.

Code Section Assignments
Typically there is only one code section, .text, unless you specifically created other code sections. All the code sections appear in this region.
Data Sections Assignments
The compilers automatically generate a number of different types of data sections including read-only data (.rodata), initialized data (.data), and uninitialized data (.bss).
Heap and Stack Section Assignments
Use this area to map the heap and stack onto memory and define their sizes.
Heap Size
Specify the heap size. Even if a programmer does not use dynamic memory allocation explicitly, there are some functions that use the heap such as printf(). It is a good idea to allocate a few KB for such functions, as a precaution.
Stack Size
Specify the stack size. Remember that the stack size grows down in memory and could overrun the heap without warning. Make certain that you allocate enough memory, especially if you use recursive functions or deep hierarchies.


Manually Adding the Linker Script

If you want to manually add the linker script for a managed make flow, do the following:

  1. Right-click your managed make project and select C/C++ Build Settings.
  2. Click the linker corresponding to your target processor, for example ARM v8 gcc linker.
  3. Select Linker Script to add the linker script.
  4. For standard make projects, add the linker script manually to your Makefile linker options.

Modifying a Linker Script

When you generate a linker script, there are multiple ways in which you can update it.
  1. Open the linker script using a text editor, and directly edit the linker script. Right-click on the linker script and select Open With > Text Editor.
  2. Regenerate the linker script with different settings using the linker script generator.
  3. Use the linker script editor to make modifications. To do this, double-click on the linker script. The custom linker script editor displays relevant sections of the linker script.

The linker script editor provides the following functionality.

Table 1. Linker Script Editor Functionality

Name

Function

Available Memory Regions This section lists the memory regions specified in the linker script. You can add a new region by clicking on the Add button to the right. You can modify the name, base address and size of each defined memory region.
Stack and Heap Sizes This section displays the sizes of the stack and heap sections. Simply edit the value in the text box to update the sizes for these sections.
Section to Memory Region Mapping This section provides a way to change the assigned memory region for any section defined in the linker script. To change the assigned memory region, simply click on the memory region to bring a drop down menu from which an alternative memory region can be selected.