GNUPro® Toolkit
GNUPro Toolkit Reference for eCos
Fujitsu SPARClite
eCos 1.2.1
April 1999

Table of Contents

Copyright Ó 1999 CYGNUS SOLUTIONS, Inc. All rights reserved.
No part of this document may be reproduced in any form or by any means without the prior express written consent of CYGNUS SOLUTIONS, Inc.
No part of this document may be changed and/or modified without the prior express written consent of CYGNUS SOLUTIONS, Inc.
GNUPro®, the GNUPro® logo, and the Cygnus Solutions logo are registered trademarks of
CYGNUS SOLUTIONS, Inc. All other brand and product names are trademarks of their respective owners.

Corporate Headquarters

CYGNUS SOLUTIONS
1325 Chesapeake Terrace
Sunnyvale, CA 94089 USA
TEL: +1 408 542 9600 Support:
Within USA/Canada: +1 800 CYGNUS1
Outside USA/Canada: +1 408 542 9601 FAX: +1 408 542 9699
EMAIL: info@cygnus.com
WEBSITE: http://www.cygnus.com/

Cygnus Japan

NIHON CYGNUS SOLUTIONS
Madre Matsuda Building
4-13 Kioi-cho Chiyoda-ku
Tokyo 102-0094 JAPAN
TEL: +81-3-3234-3896
FAX: +81-3-3239-3300
EMAIL: info@cygnus.co.jp
WEBSITE: http://www.cygnus.co.jp/

Cygnus Europe

CYGNUS SOLUTIONS
35-36 Cambridge Place
Cambridge CB2 1NS
United Kingdom
TEL: +44 1223 728728
FAX: +44 1223 728777

Part #: 300-400-1010059-1.2.1
Table of Contents

Introduction Tool naming conventions
Toolkit features Processor version(s)
Targets Supported
Hosts Supported
Object file format GNUPro on Windows NT Windows environment settings
Case Sensitivity GNUPro on Redhat Linux
GNUPro on Solaris 2.5.1 Reference Compiler SPARClite-specific command-line options
Preprocessor symbols
SPARClite-specific attributes New compiler and linker features Initialization prioritization
Selective linking ABI Summary Data type sizes and alignments
Calling conventions
Register usage
The Stack Frame Assembler SPARClite-specific command-line options
Syntax
Register names Linker SPARClite-specific command-line options Debugger SPARClite-specific command-line options
Debugging programs with multiple threads Simulator Features
Simulator-specific command line options
Using the simulator
Simulator exceptions within GDB Appendix A: CygMon (Cygnus ROM Monitor) Installing and building CygMon Installing CygMon Source
Building CygMon CygMon command list baud
break
disassemble
dump
go
help
load
memory
port
register
step
terminal
transfer
unbreak
usage
version CygMon command editing
Debugging CygMon
Bootstrap Protocol Solaris 2.6
Windows NT4.0 Appendix B: Bibliography

Introduction

The GNUPro Toolkit for eCos is a complete solution for C and C++ development for the Fujitsu SPARClite. The tools include the compiler, assembler, linker, simulator and interactive debugger. ROM Monitor, linker and debugger support are also included for the SPARClite MB8683x evaluation board. In addition to this manual, please read Getting started with eCos. Tool naming conventions

Cross-development tools in the Cygnus GNUPro Toolkit normally have names that reflect the target processor and the object file format output by the tools (for example ELF). This makes it possible to install more than one set of tools in the same binary directory, including both native and cross-development tools.

The complete tool name is a three-part hyphenated string. The first part indicates the processor family (sparclite). The second part indicates the file format output by the tool (elf). The third part is the generic tool name (gcc). For example, the GCC compiler for the Fujitsu SPARClite is sparclite-elf-gcc.

The Fujitsu SPARClite package includes the following supported tools:

Tool Description | Tool Name
GCC compiler | sparclite-elf-gcc
C++ compiler | sparclite-elf-c++
GAS assembler | sparclite-elf-as
GLD linker | sparclite-elf-ld
Standalone simulator | sparclite-elf-run
Binary Utilities | sparclite-elf-ar sparclite-elf-nm sparclite-elf-objcopy sparclite-elf-objdump sparclite-elf-ranlib sparclite-elf-size sparclite-elf-strings sparclite-elf-strip
GDB debugger | sparclite-elf-gdb

The binaries for a Windows NT hosted toolchain are installed with an .exe suffix. However, the .exe suffix does not need to be specified when running the executable.
Toolkit features

The following describes Fujitsu SPARClite-specific features of the GNUPro Toolkit. Processor version(s) Fujitsu SPARClite Targets Supported GNUPro Instruction Set Simulator with architectural extensions to support eCos execution

Fujitsu SPARClite MB8683X evaluation board

Hosts Supported

CPU | Operating System | Vendor
x86 | Windows NT 4.0 | Microsoft
x86 | Redhat Linux 5.x | Redhat
SPARC | Solaris 2.5.1 | Sun

Object file format The Fujitsu SPARClite tools support the ELF object file format. Refer to Chapter 4, System V Application Binary Interface (Prentice Hall, 1990.). Use ld (refer to Using LD in GNUPro Utilities) or objcopy (refer to The GNU Binary Utilities in GNUPro Utilities) to produce S-records.
GNUPro on Windows NT

Windows environment settings The Windows NT hosted toolchain requires the following environmental settings to function properly. Assuming the release is installed in:

C:\cygnus\gnupro\i386-cygwin32\sparclite-elf\ecos-98r1p6
SET PROOT=C:\cygnus\gnupro\i386-cygwin32\sparclite-elf\ecos-98r1p6
SET PATH=%PROOT%\H-i386-cygwin32\bin;%PATH%
SET INFOPATH=%PROOT%\info
REM Set TMPDIR to point to a ramdisk if you have one
SET TMPDIR=C:\TEMP
For the Sourceware release of eCos, ensure that the Cygwin B20.1 tools are also installed. Assuming these are installed in their default location in
C:\cygnus\cygwin-b20 then add the environmental setting:
SET PATH=C:\cygnus\cygwin-b20\H-i586-cygwin32\bin;%PATH%
If you are using the eCos Developers Kit CD release (not included in the sourceware release), a working environment can be established by using the following shortcut from the Windows Start menu:
Programs->Cygnus eCos->eCos Development Environment. This will bring up a window running bash, and your Windows environment will be automatically set up. Case Sensitivity The following strings are case sensitive under Windows NT:

- command line options
- assembler labels
- linker script commands
- section names

The following strings are not case sensitive under Windows NT:

- gdb commands
- assembler instructions and register names

Case sensitivity for Windows NT is dependent on system configuration. By default, file names under Windows NT are not case sensitive. GNUPro on Redhat Linux

The GNUPro Tools for Redhat Linux are supplied in a ZIP format file. Detailed instructions for installation can be found on the eCos sourceware site:

http://sourceware.cygnus.com/ecos/
Assuming the sources for the tools were installed in
/usr/cygnus/ecosSWtools-990319/src
By following the instructions in the Installation Guide, you should eventually have the tools installed in
/usr/cygnus/ecosSWtools-990319/H-i386-pc-linux-gnu/bin
In which case, we recommend you have the following settings in your appropriate shell startup script.

For Bourne shell compatible shells:
PROOT=/usr/cygnus/ecosSWtools-990319
PATH=$PROOT/H-i386-pc-linux-gnu/bin:$PATH
INFOPATH=$PROOT/info:${INFOPATH-/usr/local/info:/usr/info}
MANPATH=$PROOT/man:${MANPATH-/usr/local/man:/usr/man}
export PATH INFOPATH MANPATH
For C-shell compatible shells:
setenv PROOT /usr/cygnus/ecosSWtools-990319

if ( "$?MANPATH" == "0" ) then
setenv MANPATH "/usr/local/man:/usr/man"
endif

if ( "$?INFOPATH" == "0" ) then
setenv INFOPATH "/usr/local/info:/usr/info"
endif

setenv MANPATH $PROOT/man:$MANPATH
setenv INFOPATH $PROOT/info:$INFOPATH
set path = ( $PROOT/H-i386-pc-linux-gnu/bin $path )

GNUPro on Solaris 2.5.1

The GNUPro Tools for Solaris 2.5.1 are supplied in a compressed tar archive. Install the tools by extracting the files from this archive in a suitable location such as /usr/cygnus/:
$ mkdir /usr/cygnus
$ cd /usr/cygnus
$ zcat < tool-bin.taz | tar xvf - This should leave the tools installed in
/usr/cygnus/ecos-98r1p6/H-sparc-sun-solaris2.5/bin
In which case, we recommend you have the following settings in your appropriate shell startup script.

For Bourne shell compatible shells:
PROOT=/usr/cygnus/ecos-98r1p6
PATH=$PROOT/H-sparc-sun-solaris2.5/bin:$PATH
INFOPATH=$PROOT/info:${INFOPATH-/usr/local/info:/usr/info}
MANPATH=$PROOT/man:${MANPATH-/usr/local/man:/usr/man}
export PATH INFOPATH MANPATH
For C-shell compatible shells:
setenv PROOT /usr/cygnus/ecos-98r1p6

if ( "$?MANPATH" == "0" ) then
setenv MANPATH "/usr/local/man:/usr/man"
endif

if ( "$?INFOPATH" == "0" ) then
setenv INFOPATH "/usr/local/info:/usr/info"
endif

setenv MANPATH $PROOT/man:$MANPATH
setenv INFOPATH $PROOT/info:$INFOPATH
set path = ( $PROOT/H-sparc-sun-solaris2.5/bin $path )

Reference

Compiler

This section describes SPARClite-specific features of the GNUPro Compiler. SPARClite-specific command-line options For a list of available generic compiler options, refer to GNU CC Command Options in Using GNU CC in GNUPro Compiler Tools. There are no SPARClite-specific command-line options. Preprocessor symbols The compiler supports the following preprocessor symbols:

__sparc__
__sparclite__ Each of these is always defined.

SPARClite-specific attributes There are no SPARClite-specific attributes. See Declaring Attributes of Functions and Specifying Attributes of Variables in Extensions to the C Language Family in Using GNU CC in GNUPro Compiler Tools for more information.

New compiler and linker features

The GNUPro compiler and linker have been improved by Cygnus to provide even more benefits for customers developing for embedded targets. These features are guaranteed order of initialization at startup, and selective linking. Initialization prioritization In C++, you can define static and global objects with constructors, or initialize static and global variables from a function. This means that the constructors or functions are run before the rest of your program starts. However, when you have these objects spread over multiple files, the C++ standard does not specify the order in which they are initialized, and for all practical purposes the order is random. For an embedded system, this can be a problem, as you may want to ensure that a static scheduler object is initialized before static threads can attach to it, or that devices are initialized before they are used. GNUPro solves this problem by allowing you to define a priority when the static or global is declared. The following example shows the syntax:

static object_t myobj __attribute__((init_priority (30000) ));

The syntax is slightly different if the object takes any arguments to its constructor:

static object_t myobj __attribute__((init_priority (30000) )) = \ object_t(arg1, arg2);

The numeric priority can be from 1 to 65535, with 1 being the highest priority, and 65535 being the lowest. The default priority for objects without this attribute is 65535. Constructors with a higher priority are guaranteed execution before constructors with lower priority.

In all cases, you must provide the argument -finit-priority to the compiler on its command-line for it to recognize this attribute when you are compiling your C++ source files.

If you are using eCos, be warned that eCos uses initialization priorities internally. Ensure you choose an appropriate priority level so that other eCos subsystems will have initialized before you refer to them in your own constructor.

Selective linking When writing C and C++ code, it is sometimes natural to include more than one function in a source file. For example in C++, it is common to have all methods for a particular class contained in the same C++ source file. However, there is a drawback that, conventionally, if you use just one of these functions, then all the functions defined in that file also get included in the final executable image. For an embedded system, this can substantially and unnecessarily increase the size of the final image stored in ROM, or loaded into RAM when debugging.

The GNUPro C and C++ compilers can now optionally remove these unnecessary functions from the final image. They also ensure that any shared global data is removed that is only referenced by functions that are removed. This can be done by including the options -ffunction-sections and -fdata-sections on the command-line, when you invoke the C or C++ compiler. The -ffunction-sections option removes unnecessary functions, and the -fdata-sections option removes unnecessary data.

In addition, when classes define virtual methods in C++, it is possible to remove any unused methods from the final image by passing the option
-fvtable-gc to the C++ compiler on its command-line.

In all cases, you must also supply a command-line option when linking. If invoking the linker ld directly, use --gc-sections on its command-line; alternatively, if you are using the preferred method of linking your executable, using the form gcc -o <program name> <file1>.o <file2>.o, then also pass the option -Wl,--gc-sections on the compiler command-line, for example: gcc -o prog f1.o f2.o -Wl,--gc-sections

ABI Summary

This section describes the ABI, which the SPARClite tools adhere to, by default. Data type sizes and alignments

The following table shows the size and alignment for all data types:

Type | Size (bytes) | Alignment (bytes)
char | 1 byte | 1 byte
short | 2 bytes | 2 bytes
int | 4 bytes | 4 bytes
long | 4 bytes | 4 bytes
long long | 8 bytes | 8 bytes
float | 4 bytes | 4 bytes
double | 8 bytes | 8 bytes
pointer | 4 bytes | 4 bytes

Calling conventions

The calling convention follows the sparc register windows model. The first six words of integer arguments are passed in registers o0 through o5, which is referenced in the callee as i0 through i5. Additional integer arguments are passed on the runtime stack at offset %sp+60. Values that are at least 32 bits are aligned to an even word boundary. Integer return values are placed in i0 through i5. Structures and unions are returned by setting up an area to receive the values, and setting %sp+64 to the address of the area.

Register usage

Register | Usage
%g0 | Holds constant 0
%g1-%g4 | Free global registers for application usage.
%g5 | Available for application use.
%g6-%g7 | Reserved for the kernel.
%o0-%o5 | Input/output registers (for function calls made from this function)
%o6 | Stack pointer
%o7 | Return address
%l0-%l7 | Local registers
%i0-%i5 | Input/output registers (for this function call).
%i6-%i7 | Functions do not have to preserve value for the caller
%i6 | Frame pointer

From the callers point of view, the following registers are volatile when doing a call (i.e., the content of these registers cannot be assumed to be preserved across the call): %o0-%o5, %y, and %g1-%g4.

The Stack Frame

This section describes SPARClite stack frame:

- The stack grows downwards from high addresses to low addresses.
- A leaf function need not allocate a stack frame if it doesn't need one.
- A frame pointer need not be allocated.
- The stack pointer shall always be aligned to 8 byte boundaries.

Stack frames for functions that take a fixed number of arguments look like this:

Assembler

This section describes SPARClite-specific features of the GNUPro Assembler. SPARClite-specific command-line options For a list of available generic assembler options, refer to Command-Line Options in Using AS in GNUPro Utilities. There are no SPARClite-specific command-line options. Syntax The assembler syntax is based on the BSD 4.2 assembler.

For information about SPARC assembler, see SPARC Architecture, Assembly Language Programming (Richard D. Paul, Prentice Hall). For information about the SPARC instruction set, see The SPARC Architecture Manual: Version 8 (SPARC International, Inc, Prentice Hall).

Register names

Description | Register
Global integer registers (8) | %g0 through %g7
Output integer registers (8) | %o0 through %o7
Local integer registers (8) | %l0 through %l7
Input integer registers (8) | %i0 through %i7
Integer condition code register | %icc
Processor status register (contains %icc) | %psr
Multiply/divide accumulator register 17 | %y
Auxiliary status register | %asr17
Trap base register | %tbr
Window invalid mask | %wim

Linker

eCos generates linker scripts appropriate for the exact eCos configuration you have chosen. Instructions on how to use this linker script are provided in the manual Getting Started with eCos. SPARClite-specific command-line options For a list of available generic linker options, refer to ld command line options in Using LD in GNUPro Utilities. There are no SPARClite-specific command-line linker options.

Debugger

This section describes SPARClite-specific features of the GNUPro Debugger.
For debugging examples, see chapter Run an eCos test case in Getting Started with eCos

There are two ways for GDB to talk to a SPARClite target.

1. Simulator:
To build eCos for the simulator you must configure it to build for the minimal simulator with RAM startup. Linking your program against the eCos libtarget.a library, and with the target.ld linker script will produce the correct final executable that should be loaded into the simulator.

Note:
Loading binaries into the simulator that were built for the standard evaluation board with RAM startup will not work.

To activate the simulator in GDB, follow the instructions in the Simulator section later in this document.

2. Remote target board:
To load your program onto the standard evaluation board, build eCos for the hardware with RAM startup. Provided the board is fitted with CygMon ROMs, you may connect to the target board in GDB using the command target remote <devicename> where <devicename> will be a serial device such as com2 (Windows NT) or /dev/ttyS1 (Linux). Then load the code onto the target board by typing load. After being downloaded, the program can be executed.

It is also possible to download files via ethernet/TCP, which is faster. Consult the Getting Started with eCos documentation for details of how to do this.

Note:
When using the remote target, GDB does not accept the run command. However, since downloading the program has the side effect of setting the PC to the start address, you can start your program by typing continue (the letter c works as a shortcut for the continue command).

SPARClite-specific command-line options For the available generic debugger options, refer to Debugging with GDB in GNUPro Debugging Tools. There are no SPARClite specific debugger command-line options.

Debugging programs with multiple threads

Programs with multiple threads can be debugged using either the graphic user interface to GDB, GDBTk or the GDB command line interface. The following describes how to debug multiple threads using the GDB command line.

In some operating systems, such as eCos, a single program may have more than one thread of execution. The precise semantics of threads differ from one operating system to another, but in general the threads of a single program are akin to multiple processes, except that they share one address space (that is, they can all examine and modify the same variables). On the other hand, each thread has its own registers and execution stack, and perhaps private memory.

GDB provides the following functions for debugging multi-thread programs

- thread threadno, a command to switch among threads
- info threads, a command to inquire about existing threads
- thread apply [threadno][all] args , a command to apply a command to a list of threads
- thread-specific breakpoints

The GDB thread-debugging facility allows you to observe all threads while your program runs, but whenever GDB takes control, one thread in particular is always the focus of debugging. This thread is called the current thread. Debugging commands show program information from the perspective of the current thread.

For debugging purposes, GDB associates its own thread number, always a single integer, with each thread in your program.
info threads Display a summary of all threads currently in your program. GDB displays for each thread (in the following order):

1. The thread number assigned by GDB
2. The target systems thread I.D.
3. The current stack frame summary for that thread

An asterisk * to the left of the GDB thread number indicates the current thread. Use the following example for clarity.

(gdb) info threads
* 2 thread 2 breakme ()
at /eCos/packages/kernel/v1_2_1/tests/thread_gdb.c:91
Name: controller, State: running, Priority: 0, More: <none>
1 thread 1 Cyg_HardwareThread::thread_entry (thread=0x1111aaa2)
at /eCos/packages/kernel/v1_2_1/src/common/thread.cxx:68
Name: Idle Thread, State: running, Priority: 31, More: <none>

thread <threadno> Make thread number <threadno>the current thread. The command argument, <threadno>, is the internal GDB thread number, as shown in the first field of the info threads display. GDB responds by displaying the system identifier of the thread you selected, and its current stack frame summary, as in the following output. (gdb) thread 2
[Switching to thread 2]
#0 change_state (id=0, newstate=0 '\000')
at /eCos/kernel/current/tests/bin_sem2.cxx:93
93 if (PHILO_LOOPS == state_changes++)
Current language: auto; currently c++
thread apply [<threadno>][<all>] <args> The thread apply command allows you to apply a command to one or more threads. Specify the numbers of the threads that you want affected with the command argument <threadno>, where <threadno> is the internal GDB thread number, as shown in the first field of the info threads display. To apply a command to all threads, use thread apply all args. Whenever GDB stops your program, due to a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened.

When your program has multiple threads, you can choose whether to set breakpoints on all threads, or on a particular thread.
break <linespec> thread <threadno>
If <linespec> specifies source lines, then there are several ways of writing them. Use the qualifier thread <threadno> with a breakpoint command to specify that you only want GDB to stop the program when a particular thread reaches this breakpoint. <threadno> is one of the numeric thread identifiers assigned by GDB, shown in the first column of the info threads display.

If you do not specify thread <threadno> when you set a breakpoint, the breakpoint applies to all threads of your program.

You can use the thread qualifier on conditional breakpoints as well; in this case, place thread <threadno> before the breakpoint condition, as the following example shows.
(gdb) break frik.c:13 thread 28 if bartab > lim
Whenever your program stops under GDB for any reason, all threads of execution stop; not just the current thread. This allows you to examine the overall state of the program, including switching between threads, without worrying that things may change.

Conversely, whenever you restart the program, all threads start executing. This is true even when single stepping with commands like step or next. In particular, GDB cannot single-step all threads in lockstep. Since thread scheduling is up to your debugging targets operating system (not controlled by GDB), other threads may execute more than one statement while the current thread completes a single step. In general other threads stop in the middle of a statement, rather than at a clean statement boundary, when the program stops.

You might even find your program stopped in another thread after continuing or even single stepping. This happens whenever some other thread runs into a breakpoint, a signal, or an exception before the first thread completes whatever you requested.

SET SCHEDULER-LOCKING
For targets that support it, GDB has a new command that helps to debug
multi-threaded programs. The set scheduler-locking [on off step] command allows the GDB user to exert some control over how threads are scheduled while debugging.

Normally GDB does not attempt to interfere with thread scheduling. This means that in the default mode (scheduler-locking off), the current thread may be scheduled out, and a different thread may begin running, at any time (as determined by the native scheduler). For instance, you may give a GDB command such as step or finish, and when the command completes, you may be looking at a different thread.

If you set the scheduler-locking mode to step, then GDB will try to interfere with the native scheduler just enough to prevent another thread from popping up while you debug. Other threads may get to run sometimes, but whenever a command such as step or finish completes, you should be looking at the same thread that was running before the command. Of course, if another thread gets to run and hits a breakpoint, GDB will still switch you to that thread (so if you dont want that to happen, then disable your breakpoints).

For even greater (and more intrusive) control over the thread scheduler, GDB provides the mode scheduler-locking on. In this mode, the native scheduler is completely locked, and no thread may run except the current one. Obviously this will radically change the behavior of your program, and may lead to deadlock or other unpleasant consequences, so use it with caution.

Syntax:

set scheduler-locking [off on step] Set mode for locking scheduler during target execution. off No locking (threads may preempt at any time). on Full locking (no thread except the current thread may run). step The scheduler is locked during every single-step operation. In this mode, no other thread may run during a step command. However, other threads may run while stepping over a function call (next).

Simulator

The GNUPro instruction-set simulator that has been included with this release is unsupported software, and was included as a possible convenience to developers.

The GNUPro simulator allows execution of a program compiled for the SPARClite target CPU on any supported host computer. It includes a simulator module for the target CPU instruction set, memory, and may also include simulated peripheral devices such as serial I/O and timers. Altogether, these features allow developers to test their SPARClite programs, without need for an actual board with that CPU.

The SPARClite simulator is not designed to match timing characteristics of its target board. For example, the CPU module uses a single clock cycle for all instructions, its memory is infinitely fast, and its simulated serial I/O is infinitely fast. Furthermore, a number of obscure or inapplicable functions were omitted from the simulated peripherals. The simulator is just complex and accurate enough to run eCos programs.

Features The simulator includes support for SPARClites special registers window.

The user program is provided with a single 512kb block of memory at address 0x02000000.

Simulator-specific command line options -nfp Disallows use of floating point instructions. -sparclite Enables SPARClite specific simulation. -dumbio Enables dumb IO, allowing simple diagnostics text output.
All three options should be used when running eCos programs. Using the simulator

An eCos program is normally built with a particular download method in mind, that is, the means by which the program is to be ultimately loaded into the target hardware. Use the configuration options in eCoss Hardware Abstraction Layer (HAL) package to support the different download methods. The following table summarizes the ways in which an eCos image can be prepared for different types of download.

HAL configuration, for various download methods

Download method | HAL configuration
Download to board with CygMon | RAM startup
Download to simulator ignoring devices | SIM configuration
Burn hardware ROM | ROM Startup

CAUTION: An application configured for RAM startup cannot be run directly on the simulator: it will fail during startup.
The simulator-specific configuration does not include device drivers or watchdog devices that the simulator would otherwise have to emulate.

Simulator clocks and timers sometimes appear to be running very slowly, even when there are apparently no active threads. Delays that should only be in seconds can run to minutes. These delays occur because the eCos kernel idle thread is running intensively, and the simulator emulates it faithfully. With the SIM configuration, however, the eCos kernel realizes it is in a simulated environment, and can therefore adjust the clock settings to be more realistic.

Simulator exceptions within GDB

If you invoke the simulator within GDB, using the target sim command, you may encounter some ambiguities when processing signals and exceptions. When an exception is raised in the simulator, GDB does not known whether the simulated program is intended to handle the exception, or if GDB is intended to handle it.

To solve this, you can tell GDB not to process breakpoints itself, but to let the simulated target process them. To do this, use the following command:
handle SIGxxxx pass nostop noprint
where SIGxxxx is one of the signals listed by GDB when you use the
info handle command to the GDB console prompt.

For example the command handle SIGTRAP pass nostop noprint tells GDB to not stop the simulated target at a breakpoint, or even to print that it has been stopped. Instead, the command tells GDB to pass the information back to the program. You can modify the command to use with other signals and exceptions.

Appendix A: CygMon (Cygnus ROM Monitor)

CygMon is a ROM monitor designed to be portable across a large number of embedded systems. It is also completely compatible with existing GDB protocols, thus allowing the use of a standard ROM monitor with existing GNU tools across a wide range of embedded platforms.

CygMon has basic program handling and debugging commands, programs can be loaded into memory and run, and the contents of memory can be viewed. There are several more advanced options that can be included at compile time, such as a disassembler (this of course increases the code size significantly).

Since CygMon contains a GDB remote stub, full debugging can be done from a host running GDB to a target running CygMon. Switching between CygMon monitor mode and GDB stub mode is designed to be transparent to the user, since CygMon can detect when GDB is communicating with the target and switch into stub mode. When GDB stops communicating with the target normally, it sends a termination packet which lets the stub know when to switch to the CygMon monitor mode.

The command parser was written specifically for CygMon, to provide necessary functionality in limited space. All commands consist of words followed by arguments separated by spaces. Abbreviations of command names may be used. Any unique subset of a command name is recognized as being that command, so du is recognized to be the dump command. The user is prompted to resolve any ambiguities. Generally, a command with some or all of its arguments empty will either assume a default-set of arguments or return the status of the operation controlled by the command.

Installing and building CygMon

This section explains to owners of the eCos Development Kit how to install the CygMon source, and build the CygMon ROM monitor program under the Windows NT operating system. Installing CygMon Source By selecting the appropriate component, the eCos installer will install the CygMon source code, and we recommend you do so. When installed the sources would then be found in:

C:\Program Files\Cygnus Solutions\eCos\ecos-98r1p6\cygmon-src

If you choose to install the sources to a different location, the cygmon-src directory will be located at ecos-98r1p6\cygmon-src relative to the specified location. Please note that due to the configuration and build tools being used, the sources must be installed in a directory hierarchy that uses only alphanumeric, dash or underscore characters in the directory names.

Building CygMon From the Start Menu, select:

Programs->Cygnus eCos->eCos Development Environment

This will bring up a window running bash.

Mount the sources such that the full path to the CygMon sources uses only alphanumeric, dash or underscore characters:
mount C:/Program\ Files/Cygnus\ Solutions/eCos /ecos
In addition, you must mount the bin directory for the unsupported tools as /bin:
mount C:/cygnus/gnupro/i386-cygwin32/i386-cygwin32/\
unsupported-98r1p2/H-i386-cygwin32/bin /bin
You should now be able to configure and build CygMon as follows:
mkdir /ecos/ecos-98r1p6/objdir
cd /ecos/ecos-98r1p6/objdir
../cygmon-src/configure --host=i386-cygwin32 --target=sparclite-elf
make -w
When complete, you will have CygMon images built in:
sparclite-elf/cygmon/mb8683x
The images are:

cygmon.img Is the ROM-resident version of CygMon in binary format
cygmon.rom Is the ELF executable of the ROM-resident version of CygMon. It is used in the standalone simulator for thread-aware debugging.
If you want to read the source code, here are the names of the files in the cygmon and bsp directories, specific to this version of CygMon. In general, the bsp directory holds all board support and gdb debugging support. The cygmon directory holds the CygMon command line interpreter.

File Names | Description
cygmon/bsp/monitor.c | Generic CygMon monitor support
cygmon/bsp/monitor_cmd.c | Cygmon commands
cygmon/bsp/ledit.c | Line editing support
cygmon/generic_fmt32.c | Address to/from string conversion
cygmon/generic_bp32.c | Breakpoint support
cygmon/generic_mem.c | Memory read/write support
cygmon/sparc/sparc-bspmon.c | Sparc-specific monitor support
bsp/common/*.c | Common BSP support
bsp/common/gdb.c | Generic gdb stub
bsp/common/gdb-threads.c | Generic thread debug support
bsp/net/*.c | Generic network support
bsp/sparc/*.c | Sparc-specific support
bsp/sparc/gdb-cpu.c | Sparc-specific gdb support
bsp/sparc/singlestep.c | Sparc-specific singlestep support
bsp/sparc/mem.c | Safe sparc memory read/write
bsp/sparc/start.S | Sparc reset handler
bsp/sparc/vectors.S | Sparc trap vector table
bsp/sparc/exceptions.S | Default sparc exception handler
bsp/sparc/stublow.S | Low-level gdb stub entry.
bsp/sparc/mb8683x/init_86x.S | Low-level board startup.
bsp/sparc/mb8683x/mb.c | High-level board-specific support
bsp/sparc/mb8683x/mb86964.c | Ethernet driver

CygMon command list

This is a list of all the commands that can be typed at the CygMon command prompt. Arguments in [brackets] are optional, arguments without brackets are required. Note that all commands can be invoked by typing enough of the command name to uniquely specify the command. Some commands have aliases, which are single-letter abbreviations for commands which do not have unique first letters. Aliases for all commands are shown in the help screens. baud Usage: baud speed

The baud command sets the speed of the active serial port. It takes one argument, which specifies the speed to which the port will be set.

Example: baud 9600

Sets the speed of the active port to 9600 baud.

break Usage: break [location]

The break command displays and sets breakpoints in memory. It takes zero or one argument. With zero arguments, it displays a list of all currently set breakpoints. With one argument it sets a new breakpoint at the specified location.

Example: break 4ff5

Sets a breakpoint at address 4ff5.

disassemble Usage: disassemble [location]

The disassemble command disassembles the contents of memory. Because of the way breakpoints are handled, all instructions are shown and breakpoints are not visible in the disassembled code. The disassemble command takes zero or one argument. When called with zero arguments, it starts disassembling from the current (user program) pc. When called with a location, it starts disassembling from the specified location. When called after a previous call and with no arguments, it disassembles the next area of memory after the one previously disassembled. The disassemble command may be disabled depending upon copyright issues.

Example: disassemble 45667000

Displays disassembled code starting at location 45667000.

dump Usage: dump location

The dump command shows a region of 16 bytes around the specified location, aligned to 16 bytes. Thus, dump 65 would show all bytes from 60 through 6f.

Example: dump 44f5

Displays 16 bytes starting with 44f0 and ending with 44ff.

go Usage: go [location]

The go command starts user program execution. It can take zero or one argument. If no argument is provided, go starts execution at the current pc. If an argument is specified, go sets the pc to that location, and then starts execution at that location.

Example: go 40020000

Sets the pc to 40020000, and starts program execution.

help Usage: help [command]

The help command without arguments shows a list of all available commands with a short description of each one. With a command name as an argument it shows usage for the command and a paragraph describing the command. Usage is shown as command name followed by names of extensions or arguments.

Arguments in [brackets] are optional, plain text arguments are required. Note that all commands can be invoked by typing enough of the command name to uniquely specify the command. Some commands have aliases, which are one letter abbreviations for commands which do not have unique first letters. Aliases for all commands are shown in the help screen, which displays commands in the format:

command name: (alias, if any) description of command

Example: help foo

Shows the help screen for the command foo.

load Usage: load

The load command switches the monitor into a state where it takes all input as s-records and stores them in memory. The monitor exits this mode when a termination record is hit, or certain errors (such as an invalid s-record) cause the load to fail.

memory Usage: memory[.size] location [value]

The memory command is used to view and modify single locations in memory. It can take a size extension, which follows the command name or partial command name without a space, and is a period, followed by the number of bits to be viewed or modified. Options are 8, 16, 32, and 64. Without a size extension, the memory command defaults to displaying or changing 8 bits at a time.

The memory command can take one or two arguments, independent of whether a size extension is specified. With one argument, it displays the contents of the specified location. With two arguments, it replaces the contents of the specified location with the specified value.

Example: memory.8 45f6b2 57

Places the 8-bit value 57 at the location 45f6b2.

The SPARC architecture supports multiple address spaces. An alternate address space for the location can be specified by enclosing the address space identifier in brackets and prepending it to the location.

Example: memory.8 [4]45f6b2 57

Places the 8-bit value 57 at the location 45f6b2 in address space 4.

port Usage: port [port number]

The port command allows control over the serial port being used by the monitor. It takes zero or one argument. Called with zero arguments it displays the port currently in use by the monitor. Called with one argument it switches the port in use by the monitor to the one specified. It then prints out a message on the new port to confirm the switch.

Example: port 1

Switches the port in use by the monitor to port 1.

register Usage: register [register name] [value]

The register command allows the viewing and manipulation of register contents. It can take zero, one, or two arguments. When called with zero arguments, the register command displays the values of all registers. When called with only the register name argument, it displays the contents of the specified register. When called with both a register name and a value, it places that value into the specified register.

Example: register g1 1f

Places the value 1f in the register g1.

step Usage: step [location]

The step command causes one instruction of the user program to execute, then returns control to the monitor. It can take zero or one argument. If no argument is provided, step executes one instruction at the current pc. If a location is specified, step executes one instruction at the specified location.

Example: step

Executes one instruction at the current pc.

terminal Usage: terminal type

The terminal command sets the type of the current terminal to that specified in the type argument. The only available terminal types are vt100 and dumb. This function is used by the line-editor to determine how to update the terminal display.

Example: terminal dumb

Sets the type of the current terminal to a dumb terminal.

transfer Usage: transfer

The transfer or $ function transfers control to the gdb stub. This function does not actually need to be called by the user, as connecting to the board with gdb will call it automatically. The transfer command takes no arguments. The $ command does not wait for a return, but executes immediately. A telnet setup in line mode will require a return when executed by the user, as the host computer does not pass any characters to the monitor until a return is pressed. Disconnecting from the board in gdb automatically returns control to the monitor.

unbreak Usage: unbreak location

The unbreak command removes breakpoints from memory. It takes one argument, the location to remove the breakpoint from.

Example: unbreak 4ff5

Removes a previously set breakpoint at memory location 4ff5.

usage Usage: usage

Shows the amount of memory being used by the monitor, broken down by category. Despite its name, it has nothing to do with the usage of any other command.

version Usage: version

The version command displays the version of the monitor.

CygMon command editing

CygMon has a line-editing interface. If you type the wrong thing, you can correct it. Position the cursor back, delete the wrong characters and entry the right ones. The user can recover previous commands and edit them or simply re-execute them.

These are common EMACS and X text editing escape sequences. Here are the keys for editing.

Keystroke | Command
CR \n | Execute the currently displayed command
ctl-a | Move to Beginning of line
ctl-e | End of line
ctl-f | Forward char
ctl-b | Backward char
ctl-k | Delete to end of line
ctl-y | Yank Character (undelete)
ctl-d | Delete current character
ctl-p | Edit previous command
ctl-u | Erase Line
ctl-n | Edit next command

Debugging CygMon

The CygMon directories build two binaries. One is a ROM image. The other is a downloadable program, which can be run under the supervision of the previous monitor. The downloaded CygMon will be using the serial connection. GDB can be used to talk to the downloaded CygMon. Once the downloaded CygMon has initialized to the point of installing the exception handler, the original ROM monitor will no longer support debugging. At that point CygMon can be used to download and run additional programs. It is important to watch your memory layouts carefully.

When developing and debugging CygMon, it is convenient to run CygMon itself as a downloadable application. There are some modifications that the developer may want to make temporarily, to debug CygMon. Reconfigure CygMon so it does not patch the exception handler. Have your test program call breakpoint explicitly. This combination disables CygMon in some serious ways, but many essential features remain functional and debuggable. Breakpoints can be administered, memory accesses can be tested, or registers fetched. You can debug the serial driver. But, you cannot resume execution, single step or test if a breakpoint has been hit. You can force CygMon through its context-save and context-restore. This is the plan; get all the basics working and verified, and then restore the exception patching capability.

Bootstrap Protocol

The Bootstrap Protocol (BOOTP) is an UDP/IP-based protocol that enables a booting host to discover and apply configuration information relevant to the boot process dynamically without user supervision. A BOOTP server is setup to pass a variety of information to a client host as it boots. The information provided via BOOTP may include details of a boot server from which the host can fetch and load a bootstrap executable. However, this is not the way CygMon uses BOOTP. Instead, CygMon only uses BOOTP as an IP address allocation mechanism Solaris 2.6

In order to configure a BOOTP service on Solaris 2.6 the following steps should be followed.

1. Ensure that the relevant packages are installed (SUNWdhcsr, SUNWdhcsu).
2. Run the dhcpconfig command to set up the DHCP/BOOTP databases. This command provides a menu driven utility to configure DHCP and BOOTP services under Solaris 2.6. The minimal steps necessary to configure the BOOTP service are as follows:

Choose option 1 from the main menu (Configure DHCP Service). Thereafter, the dialogue below should be followed (with the appropriate local network address substituted for 192.168.2.0, and other local policies taken into account). *************************
Would you like to stop the DHCP service? (recommended) ([Y]/N):y
### DHCP Service Configuration ###
### Configure DHCP Database Type and Location ###

Enter datastore (files or nisplus) [files]:files
Enter absolute path to datastore directory [/var/dhcp]:/var/dhcp
### DHCP server daemon option setup ###
Would you like to specify nondefault daemon options (Y/[N]):n
### Initialize dhcptab table ###

Enter default DHCP lease policy (in days) [3]: 3
Do you want to allow clients to renegotiate their leases? ([Y]/N):n

### Select Networks For BOOTP/DHCP Support ###

Enable DHCP/BOOTP support of networks you select? ([Y]/N):y

### Configure Local Networks ###

Configure BOOTP/DHCP on local LAN network: 192.168.2.0 ([Y]/N):y
Do you want hostnames generated and inserted in the files hosts table? Y/[N]):n
Enter starting IP address [192.168.2.0]: 192.168.2.0
Enter the number of clients you want to add (x < 63): 1
Disable (ping) verification of 192.168.2.02.168.2.0 address(es)? (Y/[N]):n
Configured 0 entries for network: 192.168.2.0.

### Configure Remote Networks ###

Would you like to configure BOOTP/DHCP service on remote networks? ([Y]/N):n
Would you like to restart the DHCP service? (recommended) ([Y]/N):y
****************************

Once the databases have been setup, a BOOTP reservation can be created via the pntadm command.

For example the command below would reserve the IP address 192.168.2.44 for the board, with hardware address 0:0:e:31:0:1 (the leading 01 of the argument to the -i switch specifies the hardware type - 10Mbps ethernet).
pntadm -A 192.168.2.44 -i 0100000E310001 -f BOOTP+MANUAL 192.168.2.44

Consult the Sun documentation on in.dhcpd, dhcpconfig, pntadm, and dhtadm for further information.

Windows NT4.0

Several third-party suppliers of BOOTP servers are mentioned in this section. Cygnus does not guarantee the functionality of any of these BOOTP servers, and all requests for support should be addressed to the appropriate supplier.

According to the Microsoft Knowledge Base article "How to Configure Microsoft DHCP Server for BOOTP Clients", the DHCP Server that comes standard with NT Server 4.0 should provide BOOTP service if Service Pack 2 or later has been applied. See:
http://support.microsoft.com/support/kb/articles/q174/7/65.asp Tellurian supplies a BOOTP server for Windows NT4.0, which can run on either the "Server of Workstation" version of the operating system. The Tellurian bootp server is Shareware and will only run for 7 hours unless you purchase it.
http://www.tellurian.com.au/bootpdNT
This BOOTP server installs as a service, and by default expects a bootptab with details of client in C:\tftpboot. The following bootptab would achieve the same address allocation, as was the case in the Solaris example above.
.default:
:sm=255.255.255.0:

sleb1:
:ha=00000E310001:
:tc=.default:
:ip=192.168.2.44:

Weird Solutions also supply a BOOTP server for NT4.0, which also runs on both NT Server and NT Workstation. It provides a GUI to administer the service and its clients. The Weird solutions BOOTP server needs to be purchased too, but provides a limited demo that can support just one BOOTP client but without a timeout restriction.
http://www.weird-solutions.com/products/bootp/bootpnt/nt_bootp.html

Appendix B: Bibliography

SPARClite 83x Series Embedded Processor Users Guide MB8683x
Fujitsu Microelectronics Inc.

Getting Started with eCos version 1.2.1
(Sunnyvale: Cygnus Solutions, 1999)

eCos User Guides version 1.2.1
(Sunnyvale: Cygnus Solutions, 1999)

eCos Reference Manual version 1.2.1
(Sunnyvale: Cygnus Solutions, 1999)

Getting Started with GNUPro Toolkit
(Sunnyvale: Cygnus Solutions, 1999)

GNUPro Compiler Tools
(Sunnyvale: Cygnus Solutions, 1999)

GNUPro Debugging Tools
(Sunnyvale: Cygnus Solutions, 1999)

GNUPro Libraries
(Sunnyvale: Cygnus Solutions, 1999)

GNUPro Utilities
(Sunnyvale: Cygnus Solutions, 1999)

GNUPro Advanced Topics
(Sunnyvale: Cygnus Solutions, 1999)

GNUPro Tools for Embedded Systems
(Sunnyvale: Cygnus Solutions, 1999)

System V Application Binary Interface
(Prentice Hall, 1990)