What Embedded Development Means

When developing with a cross-configuration, you work with the tools on the host by using a toolchain . For example, working with a SPARCstation, you generate and debug code for a Power PC-based board by calling a specific tool with a specific embedded target's toolchain (this is described in more detail in Tools, Toolchains and Usage). The toolchain method has routines for providing a specific type of compiled output, others for preprocessing, and others for controlling assembling, linking, optimizing, debugging, and other target-specific functions.

When compiling, the following routines are for optimization:

• -inbyte
  Returns a single byte from the console.
• -outbyte
  For low-level debugging, takes an argument for print() and prints a byte out to the console (typically used for ASCII text).

When compiling, the following routines are for dynamic memory allocation:

• sbrk()
  Returns a pointer to the last memory address your application uses before malloc() , calloc() , and realloc() functions allocate more memory (all at their lowest levels).
• caddr_t
  Defines use of the char * definition.
• RAMSIZE
  Moves a pointer to heap memory during compile time and checks for the upper limit.

newlib calls the following support routines, although not for embedded targets:

• isatty()
  Checks for a terminal device.
• kill()
  Exits.
• getpd()
  Returns any value greater than one; value does not affect anything in newlib .

Most applications use calls to the standard C library. To link libc.a when you are developing with a target that has no operating system, you must first define several I/O functions, such as the open() and close() functions; for more information, see "System Calls" in GNUPro C Library in GNUPro Libraries .

When debugging, set up the tools as follows:

1. Set up the C run-time environment; see The C Run-time Environment (crt0).
2. Create stubs , or minimal versions of operating system subroutines for the C subroutine library; see Using RedBoot for Remote Debugging , and also "System Calls" in GNUPro C Library in GNUPro Libraries .
3. Connect to the debugger; see "Specifying a Debugging Target" in Debugging with GDB in GNUPro Debugger Tools, and see also Debug with Insight.

WARNING!

This type of embedded development may be inappropriate for real-time operating systems as embedded operating systems may provide their own configuration of tools.

Tools, Toolchains and Usage

When you use GNUPro tools, you typically use a standard convention for toolchain names. A toolchain name is a combination of a host name and a target name as a prefix to the tool name. The tables that follow provide the specific host and target names that you require. If you are not already familiar with the names of specific tools, review Compiler and Development Tools.

Toolchain names for Microsoft Windows NT 4.0 embedded targets

Toolchain names for Red Hat Linux 6.0, 6.1, 6.2 and 7.0 embedded targets

Toolchain names for Sun SPARC Solaris 2.6 embedded targets

IMPORTANT!

Before developing, use the configure command with the --exec= toolchain or --exec-prefix= toolchain option to specify in the Makefile the sources for the development environment.

The C Run-time Environment (crt0)

To link and run C or C++ programs and to ensure that the system hardware initializes for C conventions before calling main , define a small module, crt0 (usually written in assembler as crt0.s ) to serve as your startup code. The startup code defines a special start symbol, the default address for your application, as well as the first symbol in the executable image. If you will use any routines from the standard C library, implement the functions upon which the library depends. To write your own crt0.s module, you need the following information about your target.

• The memory map, showing the size of available memory and memory location
• The way the stack grows
• The output format in use.

There are some examples available in the sources of GNUPro Toolkit for crt0.s code (along with examples of system calls with subroutines); look in the installdir /src/newlib/libc/sys path ( installdir refers to your installation directory; for example, look in .../sys/h8300hms for Hitachi H8/300 boards). More examples are in the installdir /src/newlib/stub directory.

At a minimum, your crt0.s module must provide the following processes to link and run your programs:

• Define the symbol, start ( _start in assembler code). Execution begins with it.
• Set up sp , the stack pointer.

Choose where to store your stack within the constraints of your target's memory map, the simplest choice being a fixed-size area somewhere in the uninitialized data section (often bss ). Whether you choose a low address or a high address in this area depends on the direction your stack grows.

• Initialize all memory in the uninitialized-data bss section to zero.

Use a linker script (see The Linker Script and "Linker Scripts" in Using ld in GNUPro Development Tools ) to define symbols such as bss_start and bss_end to record the boundaries of this section; then you can use a for loop to initialize all memory between them in the crt0.s module.

• Call main . Nothing else will.

A more complete crt0.s module might also do the following:

• Define an _exit subroutine (the C name in your assembler code). Use the label _ _exit (with two leading underbars); its precise behavior depends on the details of your system and on your choice of your system's behavior. Possibilities include trapping back to the boot monitor (if there is one), to the loader (if there is no monitor), or to the start symbol.
• If your target has no monitor for output from the debugger, set up the hardware exception handler in the crt0.s module. See "The GDB Remote Serial Protocol" in Debugging with GDB in GNUPro Debugger Tools for details for using the generic remote-target facilities for this purpose.
• Perform other hardware-dependent initialization (for example, initializing an mmu or an auxiliary floating-point chip).
• Define low-level input and output subroutines (for example, the crt0.s module is a convenient place to define the minimal assembly-level routines; see "System Calls" in GNUPro C Library in GNUPro Libraries ).

crt0 , the Main Startup File

The crt0 (C RunTime 0) file contains the initial startup code for embedded development; its object is linked in first and bootstraps the rest of your application. A crt0 file is available for most platforms, although you may want your own crt0 file for each target. The crt0 file is usually written in assembler and named crt0.s .

The crt0 file defines a special symbol such as _start , which is both the default base address for the application and the first symbol in the executable binary image.

If you plan to use any routines from the standard C library, you will also need to implement the functions on which newlib depends.

The crt0 file initializes everything that your program requires for the host and target. This initialization section varies for some systems:

• If you are developing an application that gets downloaded to a ROM monitor, there is usually no need for special initialization because the ROM monitor handles it for you.
• If you plan to burn your code in a ROM, the crt0 file typically does all of the hardware initialization required to run an application. This can include initializing serial ports and running a memory check; however, results vary depending on your hardware.

The following shows a basic initialization of a crt0.s file; your file may differ, although there will be a similar initialization process.

1. Set up concatenation macros:

#define CONCAT1(a, b) CONCAT2(a, b)
#define CONCAT2(a, b) a ## b

2. Set up label macros:

#ifndef _ _USER_LABEL_PREFIX_ _
#define _ _USER_LABEL_PREFIX_ _
#endif

#define SYM(x) CONCAT1 (_ _USER_LABEL_PREFIX_ _, x)

These macros make the code portable between COFF and a.out ; COFF has _ _ (two underlines) before its global symbol names, while a.out has none.

3. Set up register names (with the appropriate prefix):

#ifndef _ _ REGISTER_PREFIX _ _
#define _ _ REGISTER_PREFIX _ _
#endif
/* Use the right prefix for registers. */
#define REG(x) CONCAT1 _ _ REGISTER_PREFIX _ _ , x)
#define d0 REG (d0)
#define d1 REG (d1)
#define d2 REG (d2)
#define d3 REG (d3)
#define d4 REG (d4)
#define d5 REG (d5)
#define d6 REG (d6)
#define d7 REG (d7)
#define a0 REG (a0)
#define a1 REG (a1)
#define a2 REG (a2)
#define a3 REG (a3)
#define a4 REG (a4)
#define a5 REG (a5)
#define a6 REG (a6)
#define fp REG (fp)
#define sp REG (sp)

Register names are for portability between assemblers. Some register names have % or $ prepended to them.

4. Set up space for the stack by assigning part of memory. (Although you can also set this allocation in the linker script, it typically is done at this point.)

.set stack_size, 0x2000 .
comm SYM (stack), stack_size

5. Define empty space for an environment:

.data
.align 2
SYM (environ):
.long 0

This call is unlike most for a ROM monitor. Generally it is best to set up a valid address and then pass the address to main() . In this way if an application checks for an empty environment, it finds one.

6. Set up a few global symbols:

.align 2
.text
.global SYM (stack) .global SYM (main)
.global SYM (exit)
.global _ _ bss_start

The last line really should not be SYM (_ _bss_start) , since declaring _ _bss_start this way ensures the appropriate setting of its value in the linker script.

7. Set up the start global symbol for the linker to use as the default address for the .text section. This helps your program run.

SYM (start):
link a6, #-8
moveal #SYM (stack) + stack_size, sp

• crt0 zeroes the .bss section.
  Clear the .bss section for uninitialized data using the following example. Initialize all of the addresses in the .bss section to zero so programs will get predictable results when there is no check for the default values of new variables.

moveal # _ _ bss_start, a0
moveal #SYM (end), a1
1:
movel #0, (a0)
leal 4(a0), a0
cmpal a0, a1
bne 1b

Applications can get unpredictable effects with the .bss section left uncleared, causing particular problems with some implementations of malloc() calls.

• crt0 calls main() .
  If your ROM monitor supports it, set up argc and argv for command line arguments and an environment pointer before the call to main() . F or GNU C++ compiling, the code generator inserts a branch to _ _main at the top of your main() routine, while the GNU C++ compiler uses _ _main to initialize its internal tables and then returns control to your main() routine. For crt0 to call your main() routine, use the following example. Set up the environment pointer and jump to main() and call the main routine from the application with main (argc, argv, environ) , using argv as a pointer to NULL .

pea 0
pea SYM (environ)
pea sp@(4)
pea 0
jsr SYM (main)
movel d0, sp@-4

• crt0 calls (exit)
  After main() runs, the crt0 file then returns control of the hardware from the application. On some hardware there is nothing to return to, especially if your program is in ROM. If that is the case, you need to do a hardware reset or branch back to the original start address. Using a ROM monitor you can usually call a user trap to provide the ROM control. Pick a safe vector with no sides effects. Some ROMs have a built-in trap handler for just this case. Exit from the application with _exit ; normally, this causes a user trap to return to the ROM monitor for another run. Proceed by using the following example:

SYM (exit):
trap #0

Both rom68k and bug can handle an exception of 0 with no side effects; although the bug monitor has a user-caused trap that returns control to the ROM monitor, the bug monitor is more portable.

The Linker Script

In the /usr/redhat/host/target/lib/ldscripts/ path, find the example linker scripts (host signifies your host configuration and target signifies the embedded configuration that you target). In that directory there will be files with the .x , .xbn , .xn , .xr , .xs , and .xu extensions serving as examples of linker scripts.

The linker script does the following:

• Sets up the memory map for the application.

When your application loads into memory, it allocates some RAM, some disk space for I/O, and some registers. The linker script makes a memory map of this memory allocation. This is important to embedded systems because you gain the ability to manage the behavior of the chip, even though they have no OS.

• Sets up the constructor and destructor tables for GNU C++ compiling.

Actual section names vary depending on your object file format. For a.out and COFF formats, .text , .data , and .bss are the three main sections.

• Sets the default values for variables in use by sbrk() and the crt0 file, which are typically called by _bss_start and _end .

There are two ways to ensure the memory map is correct.

• Have the linker create the memory map by using the -Map option.
• After linking, use the nm utility to check start , bss_end , _etext and other critical addresses.

The following example shows how to set up a linker script for a Motorola 68000 target.

1. Load the file so that it executes first with the STARTUP(crt0.o) command.

By default, the Motorola 68000 configuration using the COFF object file format does not link in crt0.o because it assumes that you have a crt0 file. A config file controls this behavior in each architecture in a STARTFILE_SPEC macro. If you have STARTFILE_SPEC set to NULL , the GNU compiler formats its command line and does not add crt0.o . You can specify any filename with STARTUP , although the default is always crt0.o . If you use only ld to link, you control whether or not to link in crt0.o on the command line.
If you have multiple crt0 files, you can omit STARTUP and link in crt0.o in a makefile or by using different linker scripts (this option is useful when initializing floating point values or when adding device support).

2. Use GROUP to load a file:

GROUP(-lgcc-liop-lc)

In this case, the file is a relocated library containing the definitions for the low-level functions that the libc.a file requires.

3. Use SEARCH_DIR to specify the path in which to look for files:

SEARCH_DIR(.)



4. Use _DYNAMIC to specify whether or not there are shared dynamic libraries. In the following example, the value of zero provides no shared libraries:

_ _ DYNAMIC = 0;



5. Set _stack , the variable for specifying RAM for the ROM monitor.



6. Specify a name for a section to which you can refer later in the script.

In the following example, it is only a pointer to the beginning of free RAM space with an upper limit at 2MB. If the output file exceeds the upper limit, MEMORY produces an error message.

MEMORY{
ram : ORIGIN = 0x10000, LENGTH = 2M
}

In this example, you set up the memory map of the board's stack for high memory for both the rom68k and mon68k monitors.

7. For the GNU C++ compiler, set up constructor and destructor tables. Set up the .text section, using the following example:

SECTIONS
{
.text :
{
CREATE_OBJECT_SYMBOLS
*(.text)
etext = .;
_ _ CTOR_LIST _ _ = .;
LONG(( _ _ CTOR_END _ _ - _ _ CTOR_LIST _ _ ) / 4 - 2)
*(.ctors)
LONG(0)
_ _ CTOR_END _ _ = .;
_ _ DTOR_LIST _ _ = .;

LONG(( _ _ DTOR_END _ _ - _ _ DTOR_LIST _ _ ) / 4 - 2)
*(.dtors)
LONG(0)
_ _ DTOR_END _ _ = .;
*(.lit)
*(.shdata) }
> ram
.shbss SIZEOF(.text) + ADDR(.text) : {
*(.shbss)
}

In a COFF file, all of the actual instructions for setting up the constructor and destructor tables for the GNU C++ compiler are in .text . The section description redirects itself to the RAM variable that you previously set (see Set _stack, the variable for specifying RAM for the ROM monitor.) with the _stack variable.

8. Set up the .data section.

.talias : { } > ram
.data : {
*(.data)
CONSTRUCTORS
_edata = .;
} > ram

A COFF file is where all of the initialized data goes. CONSTRUCTORS is a special command that the GNU linker, ld , uses.

9. Set up default values for _bss_start and _end variables by setting up the .bss section.

The default values for _bss_start and _end are for use by the crt0 file when it zeros the .bss section.

.bss SIZEOF(.data) + ADDR(.data) :
{
_ _ bss_start = ALIGN(0x8);
*(.bss)
*(COMMON)
end = ALIGN(0x8);
_end = ALIGN(0x8);
_ _ end = ALIGN(0x8);
}
.mstack : { } > ram
.rstack : { } > ram
.stab . (NOLOAD) :
{
[ .stab ]
}
.stabstr . (NOLOAD) :
{
[ .stabstr ]
}
}

For more information on linking, see Using ld in GNUPro Development Tools .

Using Cygwin

This section discusses the architecture underlying the Cygwin tools for porting UNIX applications to Windows 32-bit environments. For more information, see:

http://sources.redhat.com/cygwin/

GNUPro Toolkit provides the following packages for Cygwin:

• GNUPro development tools: binutils , bison , byacc , dejagnu , diff , expect , flex , as , gcc , gdb , itcl , ld , libstdc++ , make , patch , tcl , tix , tk .
• GNUPro unsupported tools: ash , bash , bzip2 , diff , fileutils , findutils , gawk , grep , gzip , m4 , sed , shellutils , tar , textutils , time .

Cygwin emulates a standard UNIX directory structure. To emulate the /etc directory (so that the ls -l UNIX directory contents listing command works), use the following example's declarations as a guide:

mkdir /etc/
cd /etc
mkpasswd > /etc/passwd
mkgroup > /etc/group

Cygwin comes with both bash.exe and sh.exe shells. sh.exe is based on ash . In case of trouble with ash , make sh.exe point to the bash.exe shell.

When executing a binary linked against the library, the Cygwin dynamically linked library (DLL) loads into the application's text segment. To emulate a UNIX kernel for allowing access to all processes that can run with it, use the Cygwin DLL. The Cygwin DLL will create shared memory areas so that other processes using separate instances of the DLL can access the kernel. The DLL keeps track of open file descriptors and, among other purposes, assists fork and exec calls. In addition to the shared memory regions, every process also has a per-process structure that contains information such as process ID, user ID, signal masks, and other similar process-specific information.

The DLL uses the Win32 API. Because processes run under the standard Win32 subsystem, they can access both the UNIX compatibility calls provided by Cygwin as well as any of the Win32 API calls. This gives the programmer complete flexibility in designing the structure of their program in terms of the API in use; for example, a project might require a Win32-specific GUI using Win32 API calls on top of a UNIX back-end that uses Cygwin.

The CYGWIN environment variable helps to override the Win32 default behavior and force POSIX1 standards compliance.

UNIX applications that have to switch the user context have the setuid and seteuid calls, which are not part of the Microsoft Windows API. Nevertheless these calls are supported under Windows Microsoft Windows NT and Microsoft Windows 2000 with Cygwin.

Using RedBoot for Remote Debugging

If you are trying to debug a program running the GNU debugger, GDB, you can use remote debugging with RedBoot. For details about debugging with RedBoot, a wide set of tools for downloading and executing programs on embedded target systems, see: http://sources.redhat.com/ecos/docs-latest/redboot/redboot.html RedBoot helps with manipulating a target system's environment, for both product development (debug support) and for end product deployment (flash and network booting).

Debug with Insight

The following documentation serves as a general reference for debugging with GNUPro Toolkit's graphical user interface, Insight; for more information, see Insight's Help menu for discussion of general functionality and use of menus, buttons or other features; see also "Insight, GDB's Alternative Interface" and the "Examples of Debugging with Insight" documentation in GNUPro Debugger Tools (see http://www.redhat.com/docs/manuals/gnupro/ ).

IMPORTANT!

Insight works as the default means for debugging; to disable the GUI, use the gdb -nw command for non-windowing command line work.

1. From a shell window, enter the following input:

gdb

Insight launches, displaying the Source Window (Source Window, the main window interface for Insight).

Source Window , the main window interface for Insight

 

The menu selections in the Source Window are File , Run , View , Control , Preferences , and Help . To work with the other windows for debugging purposes specific to your project, use the View menu or the buttons in the toolbar.

2. To open a specific file as a project for debugging, select File → Open in the Source Window . The file's contents will then pass to the GDB interpreter.
3. To start debugging, click the Run button (Run button) from the Source Window.

Run button

 

When the debugger runs, the button turns into the Stop button (Stop button).

Stop button

 

The Stop button interrupts the debugging process for a project, provided that the underlying hardware and protocols support such interruptions. Generally, machines that are connected to boards cannot interrupt programs on those boards. In such cases, a dialog box appears as a prompt asking if you want to abandon the session and if the debugger should detach from the target.

For an embedded project, click Run ; then click Continue (Continue button); this ensures configuration between the target and the host is clear so that the debugging tools will work effectively.

Continue button

 

WARNING!

When debugging a target, do not click on the Run button during an active debugging process, since using the Run button will effectively restart the session with all work unrecoverable.

For more information on Insight, see its Help menu. For examples of debugging session procedures for using Insight, see the following documentation (the content assumes familiarity with debugging procedures).

• Selecting and Examining a Source File (below)
• Setting Breakpoints and Viewing Local Variables
• Setting Breakpoints on Multiple Threads

To specify how source code appears and to change debugging settings, from the Preferences menu, select Source .

IMPORTANT!

To add identification codes to the debugger's table of processors, see the GDB Internals documentation, distributed with the source code.

Selecting and Examining a Source File

To select a source file, or to specify what to display when examining a source file when debugging, use the following processes.

1. Select a source file from the file drop-down list with the Source Window ( hello.c in Source file selection ).

Source file selection

 
2. Select a function from the function drop-down list to the right of the file drop-down list, or type its name in the text field above the list to locate the function (in Search for functions , see the executable line 11, where the main function displays).

Search for functions

 
3. Use the Enter key to repeat a previous search. Use the Shift and Enter keys simultaneously to search backwards.
4. Type @ with a number in the search text box in the top right of the Source Window . Press Enter . Searching for a specific line in source code shows a jump to line 8 in the hello.c source file.

Searching for a specific line in source code

 

Setting Breakpoints and Viewing Local Variables

A breakpoint can be set at any executable line in a source file.

Executable lines are marked by a minus sign in the left margin of the Source Window . When the cursor is over a minus sign for an executable line, the cursor changes to a circle. When the cursor is in this state, a breakpoint can be set. The Breakpoints window is for managing the breakpoints: disabling them, enabling them, or erasing them; an enabled breakpoint is one for which the debugging session will stop, a disabled breakpoint is one which the debugging session ignores.

The following exercise steps you through setting four breakpoints in a function, as well as running the program and viewing changed values in local variables.

1. To set a breakpoint, have an active the hello.c source file open in the Source Window , and, with the cursor over a minus sign on a line, click the left mouse button. When you click on the minus sign, a red square appears for the line, signifying a set breakpoint (see the highlighted line 15 in Results of setting breakpoint for line 17 for a set breakpoint).

Clicking the line again will remove the breakpoint.

Results of setting breakpoint for line 17

 
2. Open the Breakpoints window ( Breakpoints window ) using the Breakpoints button from the Source Window. See a line with a check box in the window appears showing that you set a breakpoint for a corresponding line in the Source Window frame. With the cursor over a breakpoint, a breakpoint information balloon displays in the Source Window (the information details the breakpoint, its address, its associated source file and line, its state, whether enabled, temporary, or erased, and the association to all threads for which the breakpoint will cause a stop; see also Setting Breakpoints on Multiple Threads for details about threads).

Breakpoints window

 
3. The debugger ignores disabled breakpoints, lines indicated having a black square over them in the Source Window frame (see line 17 in Results of setting breakpoint for line 17). Click on a breakpoint to disable the breakpoint. Results of disabling a breakpoint at line 17 shows the results in the Breakpoints window of disabling a breakpoint. Re-enable a breakpoint at a line by clicking on the check box in the Breakpoints window. Once a breakpoint is enabled for a line, it will again have a red square in the Source Window frame.

Results of disabling a breakpoint at line 17

 
4. Repeat the process to set breakpoints at specific lines.
5. Click Run in the Source Window to start the executable. The debugger runs until it finds a breakpoint. When the target stops at a breakpoint, the debugger highlights a line (see highlighted line 17 in Executable after changing local variable's values, where the debugging stopped). For more information about breakpoints, see the standard documentation for Insight: "Insight, GDB's Alternative Interface" and the "Examples of Debugging with Insight" documentation in GNUPro Debugger Tools ; see http://www.redhat.com/docs/manuals/gnupro/ ).
6. Open the Local Variables window by clicking its button in the tool bar for the Source Window ; the Local Variables window displays the values of the variables (see Local Variables window for the b variable in hello.c).

Local Variables window

 
7. Click the Continue button in the Source Window tool bar to move to the next breakpoint. The variables that changed value turn color in the Local Variables window (see results in Local Variables window after setting breakpoints for the b variable in hello.c ).

Local Variables window after setting breakpoints

 
8. Click the Continue button two more times to step through the next two breakpoints (until execution stops at line 17) and see the values of the local variables change (compare results from hello.c in Results of setting breakpoint for line 17 and results in Executable after changing local variable's values ).

Executable after changing local variable's values

 

Setting Breakpoints on Multiple Threads

Select threads and set breakpoints on one or more threads when debugging a multi-threaded application with Insight.

WARNING!

Working with multiple threads does not function similarly on all embedded targets. When debugging C++ code, for instance, breakpoints and exceptions may not work on multiple threads.

A process can have multiple threads running concurrently, each performing a different task, such as waiting for events or something time-consuming that a program does not need to complete before resuming. The thread debugging facility allows you to observe all threads while your program runs. However, whenever the debugging process is active, one thread in particular is always the focus of debugging. This thread is called the current thread. The precise semantics of threads and the use of threads differs depending on operating systems. In general, the threads of a single program are like multiple processes, except that they share one address space (that is, they can all examine and modify the same variables). Additionally, each thread has its own registers and execution stack and, perhaps, private memory.

1. In the Source Window , right click on an executable line without a breakpoint to open the breakpoint pop-up menu (Breakpoint pop-up menu in the Source Window).

Breakpoint pop-up menu in the Source Window

 
2. Select Set Breakpoint on Thread(s) to display a window allowing you to choose the threads with which you set breakpoints. The Processes window (see Processes window with threads), available from the Source Window 's View → Threads List menu, displays all the available threads in the system and allows you to switch the current thread. See Debugging with GDB in GNUPro Debugger Tools (see http://www.redhat.com/docs/manuals/gnupro/ ) for more general information about threads.

Processes window with threads