Linker Scripts

CS3 provides linker scripts for each board that is supported. Each board may be used in a number of different configurations, and these are reflected in the linker script name. The linker scripts are named board-profile-hosted.ld, where board is the name of the board, profile describes the memory arrangement used and -hosted indicates whether semihosting is provided.

Caution

If you do not explicitly specify a linker script, Sourcery G++ produces a link error, preventing you from creating an executable program.

Program and Data Placement

Many boards have both RAM and ROM (flash) memory devices. CS3 provides distinct linker scripts to place the application either entirely in RAM, or in ROM where data is initialized during the C initialization phase.

Some boards have very small amounts of RAM memory. If you use large library functions (such as printf and malloc), you may overflow the available memory. You may need to use the ROM-based linker scripts for such programs, so that the program itself is stored in ROM. You may be able to reduce the total amount of memory used by your program by replacing portions of the Sourcery G++ runtime library and/or startup code.

Semihosting

CS3 is designed to support boards where there may be no operating system. To allow functions like open and write to work, a semihosting feature is supported, in conjunction with the debugger.

With semihosting enabled, these system calls are translated into equivalent function calls on your host system. You can only use these function calls while connected to the debugger; if you try to use them when disconnected from the debugger, you will get a hardware exception.

A good use of semihosting is to display debugging messages. For example, this program prints a message on the standard error stream on the host:

#include <unistd.h>

int main () {
  write (STDERR_FILENO, "Hello, world!\n", 14);
  return 0;
}

The hosted CS3 linker scripts provide the semihosting support, and as such programs linked with them may only be run with the debugger. The unhosted CS3 linker scripts provide stub versions of the system calls, which return an appropriate error value in errno. If such a stub system call is required in the executable, the linker also produces a warning. Such a warning may indicate that you have left debugging code active, and that your executable is larger than it might need to be.

Choosing a Linker Script from the Command Line

From the command line, you must add -T script to your linking command, where script is the appropriate linker script. For example, if you are using a Cyclone III Cortex-M1 board, you could link with -T cycloneiii-cm1-ram-hosted.ld.