CS3 is CodeSourcery's low-level board support library. This chapter documents the boards supported by Sourcery CodeBench Lite and the compiler and linker options you need to use with them. It also explains how you can use and modify CS3-provided definitions for memory maps, system startup code and interrupt vectors in your own code.
Table of Contents
Many developers turn to the GNU toolchain for its cross-platform consistency: having a single system support so many different processors and boards helps to limit risk and keep learning curves gentle. Historically, however, the GNU toolchain has lacked a consistent set of conventions for processor- and board-level initialization, language run-time setup, and interrupt and trap handler definition.
The CodeSourcery Common Startup Code Sequence (CS3) addresses this problem. For each supported system, CS3 provides a set of linker scripts describing the system's memory map, and a board support library providing generic reset, startup, and interrupt handlers. These scripts and libraries all follow a standard set of conventions across a range of processors and boards.
This chapter is organized in two parts. The first part explains CS3 concepts:
The second part provides details about the CS3 implementation for ARM EABI:
When you build programs for ARM EABI targets, you must use a linker script. The linker script serves several purposes:
When invoking the Sourcery CodeBench linker from the command line,
you must explicitly supply a linker script using the
-T option; otherwise a link error results.
CS3 may provide multiple linker scripts for different configurations using the same board. For example, on some boards CS3 may support running the program from either RAM or ROM (flash). Some CS3 link configurations are also designed to co-exist with, or be run from, a boot monitor on the target board. Simulator targets typically require different startup code configurations than hardware targets. In CS3 terminology, each of these different configurations is referred to as a profile.
The remainder of this section discusses profile and hosting selection considerations in more detail. You can find the full list of supported boards and linker scripts included in this release of Sourcery CodeBench Lite in Section 5.5, “Supported Boards for ARM EABI”.
Many boards have both RAM and ROM (flash) memory devices. CS3 provides distinct linker scripts to place the application either entirely in RAM, or to place code and read-only data in ROM.
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 profile 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 CodeBench runtime library
and/or startup code.
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. 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 debugger console 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. For production code, or programs where memory usage
is tightly constrained, use the unhosted CS3 linker scripts
instead.
These 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, or that your program contains unused
code.
As an alternative to semihosting via the debugger, 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.
When using Sourcery CodeBench from the command line or from a
Makefile, you must add -T
to your linking
command, where scriptscript is the
appropriate linker script. For example, to target
Altera Cyclone III Cortex-M1 boards, you could link with -T
cycloneiii-cm1-ram-hosted.ld.