5.5. Linker Scripts
Prev | Chapter 5. CS3™: The CodeSourcery Common Startup Code Sequence | Next

## 5.5. Linker Scripts

CS3 provides linker scripts for each supported board. Each board may be used in a number of different configurations, and these are reflected in the linker script names. 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 hosting or semihosting is provided.

### Caution

Linker scripts are required to create executable programs for MIPS ELF targets. When invoking the Sourcery G++ linker from the command line, you must explicitly supply a linker script using the `-T` option; otherwise a link error results.

### 5.5.1. 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.

### 5.5.2. Hosting and Semihosting

CS3 is designed to support boards without an operating system. To allow functions like `open` and `write` to work without operating system support, 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.

Semihosting requires support from the remote GDB debugging stub or agent, as well as the debugger itself. The Sourcery G++ Debug Sprite implements semihosting for all supported devices. Semihosting is also supported by the GDB Simulator included with Sourcery G++ Lite. You can additionally use semihosting when connecting to the target using MDI. However, semihosting may not be supported by debugging stubs provided by third parties. If you are using a debug device that communicates with GDB using the GDB remote protocol, check the documentation for your device to see whether semihosting is supported.

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.

Some targets supported by CS3 can run a boot monitor that provides console I/O services and other basic system calls. CS3 can also provide hosting via these facilities; where a boot monitor is supported, this is noted in the board tables below. Unlike semihosting, hosting via the boot monitor can be used when running programs outside of the debugger.

### 5.5.3. Choosing a Linker Script

When using Sourcery G++ from the command line, you must add `-T `script`` to your linking command, where `script` is the appropriate linker script. For example, to target M5208EVB boards, you could link with `-T m5208evb-ram`.

Prev | Up | Next
5.4. Interrupt Vectors and Handlers | Home | 5.6. Supported Boards for MIPS ELF