GNUPro® Toolkit
GNUPro Toolkit Reference for eCos
PowerPC
eCos 1.2.1
April 1999
Table of Contents

Copyright Ó 1998 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-1010046-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

Reference Compiler PowerPC-specific command-line options
Preprocessor symbols
PowerPC-specific attributes New compiler and linker features Initialization prioritization
Selective linking EABI Summary Data type sizes and alignments
Subroutine calls
The Stack Frame
Parameter Assignment to Registers
Structure passing
Varargs handling
Function Return Values Assembler PowerPC-specific command-line options
Syntax
Register names
Assembler directives Linker PowerPC-specific command-line options Debugger PowerPC-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: Bibliography

Introduction

The GNUPro Toolkit for eCos is a complete solution for C and C++ development for the PowerPC. The tools include the compiler, assembler, linker, simulator and interactive debugger. Simulator, linker and debugger support is also included for the Cogent CMA287-23 (MPC823), CMA287-50 (MPC850), and CMA286-60 (MPC860) evaluation boards. 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 (‘powerpc’). The second part is (‘eabi’). The third part is the generic tool name (‘gcc’). For example, the GCC compiler for the Motorola PowerPC is ‘powerpc-eabi-gcc’.

The Motorola MPC860 package includes the following supported tools:

Tool Description | Tool Name
GCC compiler | powerpc-eabi-gcc
C++ compiler | powerpc-eabi-c++
GAS assembler | powerpc-eabi-as
GLD linker | powerpc-eabi-ld
Standalone simulator | powerpc-eabi-run
Binary Utilities | powerpc-eabi-ar powerpc-eabi-nm powerpc-eabi-objcopy powerpc-eabi-objdump powerpc-eabi-ranlib powerpc-eabi-size powerpc-eabi-strings powerpc-eabi-strip
GDB debugger | powerpc-eabi-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 PowerPC-specific features of the GNUPro Toolkit. Processor version(s) Motorola MPC823, MPC850, and MPC860 Targets Supported GNUPro Instruction Set Simulator with architectural extensions to support eCos execution

Cogent CMA287-23 (MPC823), CMA287-50 (MPC850), and CMA286-60 (MPC860) evaluation boards

All targets run in big-endian mode.

Hosts Supported

CPU | Operating System | Vendor
x86 | Windows NT 4.0 | Microsoft
x86 | Redhat Linux 5.x | Redhat

Object file format The PowerPC 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. Assume the release is installed in:

C:\cygnus\gnupro\i386-cygwin32\powerpc-eabi\ecos-98r1p6
SET PROOT=C:\cygnus\gnupro\i386-cygwin32\powerpc-eabi\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 Developer’s 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 )

Reference

Compiler

This section describes PowerPC-specific features of the GNUPro Compiler. PowerPC-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. In addition, the following PowerPC-specific command-line options are supported:

These ‘-m’ options are defined for the PowerPC. -mbig
-mbig-endian This option is on by default. On System V.4 and embedded PowerPC systems compile code for the processor in big endian mode.
-mcpu=860 Specifically set the architecture type, register usage, choice of mnemonics, and instruction scheduling parameters for machine type. Supported value is ‘860’.
-mmpc860c0[=NUM]

This option is only applicable to MPC860 chips when producing ELF executables with the GNU linker. It does not cause any changes to the .o files but causes the linker to perform a check for "problematic" conditional branches and implement a work around.
The problem is that some chips may treat the target instruction as a no-op, given the following conditions:
1. The processor is an MPC860, version C0 or earlier.
2. A forward conditional branch is executed.
3. The branch is predicted as not taken.
4. The branch is taken.
5. The branch is located in the last 5 words of a page.
6. The branch target is located on a subsequent page.

The optional argument is the number of words that are checked at the end of each text page. It may be any value from 1 to 10 and defaults to 5.

-msoft-float This option is on by default. It causes the compiler to generate output containing library calls for floating point operations. Preprocessor symbols The compiler supports the following preprocessor symbols: __powerpc__ Is always defined. __embedded__ Is always defined. PowerPC-specific attributes There are no PowerPC-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

EABI Summary

This section describes the V.4 EABI. The PowerPC tools adhere to the V.4 EABI. The Motorola MPC 860 does not have hardware floating-point support. 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
unsigned | 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

- Alignment within aggregates (structs and unions) is as above, with padding added if needed
- Aggregates have alignment equal to that of their most aligned member
- Aggregates have sizes which are a multiple of their alignment

Subroutine calls

The following describes the calling conventions for subroutine calls. The first table outlines the registers used for passing and returning parameters. The second table outlines other register usage.

Parameter registers:
general-purpose | r3-r10
return general-purpose | r3-r4
floating point | f1-f8
return floating point | f1

Register usage:
function linkage | r0, r11, r12, r31
stack pointer | r1
kernel reserved | r2
small data pointer | r13
volatile | r0, r3-r13, f0-f13, lr, ctr, xer, fpscr, cr0, cr1, cr5-cr7
non-volatile | r14-r31, f14-f31
return address | lr

- General-purpose and floating-point parameter registers are allocated independently.
- Structures that are less than or equal to 32 bits are passed as values.
- Structures that are greater than 32 bits are passed as pointers.
- Bit 6 of ‘cr1’ is set if a variable-argument function is passed floating-point arguments in registers.

The Stack Frame

This section describes the PowerPC stack frame:

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

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

When alloca is executed, the back chain to the caller’s stack frame and the link register save area must be updated.

The parameter save area does not contain space to store the 8 integer arguments. If it is desired that they be stored, the callee must allocate space to save it in the local variable area of the stack. Structures and unions are copied into temporary slots and an address of the temporary slot is passed as the argument.

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

Parameter Assignment to Registers

Consider the parameters in a function call as ordered from left (first parameter) to right. In this algorithm, ‘FR’ contains the number of the next available
floating-point register, ‘GR’ contains the number of the next available general-purpose register, and ‘STARG’ is the address of the next available stack parameter word. INITIALIZE: Set ‘GR=r3’, ‘FR=f1’, and ‘STARG’ to point to parameter word 1. SCAN: If there are no more parameters, terminate. Otherwise, select one of the following depending on the type of the next parameter:

DOUBLE OR FLOAT:

If ‘FR > f8’, go to ‘STACK’. Otherwise, load the parameter value into
floating-point register ‘FR’ and advance ‘FR’ to the next floating-point register. Then go to ‘SCAN’.

SIMPLE ARG:

A SIMPLE ARG is one of the following:

- One of the simple integer types which will fit into a general-purpose register
- A pointer to an object of any type
- A struct or union small enough to fit in a register
- A larger struct or union, which shall be treated as a pointer to a copy of that object

If ‘GR > r10’, go to ‘STACK’. Otherwise, load the parameter value into general-purpose register ‘GR’ and advance ‘GR’ to the next general-purpose register. Values shorter than the register size are sign-extended or zero-extended depending on whether they are signed or unsigned. Then go to ‘SCAN’.

LONG LONG:

If ‘GR > r8’, go to ‘STACK’. Otherwise, if ‘GR’ is even, advance ‘GR’ to the next register. Load the 64-bit ‘long long’ value into register pair ‘GR’ and ‘GR+1’. Advance ‘GR’ to ‘GR+2’ and go to ‘SCAN’.

STACK:

Parameters not otherwise handled above are passed in the parameter words of the caller's stack frame. SIMPLE ARGs, as defined above, are considered to have size and alignment equal to the size of a general-purpose register, with simple argument types shorter than this sign-extended or zero-extended to this width. ‘float’ arguments are considered to have size and alignment equal to the 32 bits. ‘double’ and ‘long long’ are considered to have size and alignment equal to 64 bits. Round ‘STARG’ up to a multiple of the alignment requirement of the parameter and copy the argument byte-for-byte into ‘STARG’, ‘STARG+1’, ... ‘STARG+size-1’. Set ‘STARG’ to ‘STARG+size’ and go to ‘SCAN’.

Structure passing

As noted above, code, which passes structures and unions by value is implemented specially; in this section, “struct” will refer to structures and unions inclusively. Structs small enough to fit in a register are passed by value in a single general-purpose register or in a 32-bit stack slot. Larger structures are handled by the caller making a copy of the structure, in order to preserve the pass-by-value semantics, and passing a pointer to the copy. The copy is made in the local variable area of the caller’s stack. Varargs handling

Varargs are handled differently in the V.4 EABI than they are for most other ABIs. Variable argument functions must store the registers used for passing arguments that aren’t used for fixed arguments into a 96-word area in the local variable section of the stack. If bit 6 of the CR is not 1, it doesn’t have to save the floating-point registers. The V.4 EABI never passes floating-point arguments in general-purpose registers. The registers used to hold arguments are saved in a separate save area, and ‘va_list’ is an array of 1 element of a structure that contains pointers to the stack and register save area, and two char values indicating how many general-purpose and floating-point registers have been processed.

The ‘va_list’ type is defined as follows:
typedef struct { char gpr; /* index to next saved gp register */
char fpr; /* index to next saved fp register */
char *ovf_arg_area; /* pointer to next overflow arg */
char *reg_save_area; /* pointer to register save area */ } va_list[1];

Function Return Values

Data types and register usage for return values:

Type | Register
int | r3
short | r3
long | r3
long long | r3+r4
float | f1
double | f1
struct/union | see below

Structures and unions that will fit into two general-purpose registers are returned in ‘r3’, or in ‘r3’ and ‘r4’ if necessary. The caller handles larger structures and unions by passing, as a "hidden" first argument, a pointer to space allocated to receive the return value.

Assembler

This section describes PowerPC-specific features of the GNUPro Assembler. PowerPC-specific command-line options
For a list of available generic assembler options, refer to "Command-Line Options" in Using AS in GNUPro Utilities. Syntax
For more information about the PowerPC instruction set and PowerPC assembly conventions, see The PowerPC (tm) Architecture:A SPECIFICATION FOR A NEW FAMILIY OF RISC PROCESSORS (Morgan Kaufmann Publishers, Inc.)
or
PowerPC (tm) Microprocessor Family:The Programming Environments (Published by both IBM (MPRPPCFPE-01) and Motorola (MPCFPE/AD)) Register names
There are 32 32-bit general (integer) registers, named ‘r0’ through ‘r31’. There are 32 64-bit floating-point registers, named ‘f0’ through ‘f31’.

The compiler will generate assembly code, which uses the numbers `0' through `31' to represent general-purpose registers.

The following symbols can be used as aliases for individual registers:

Symbol | Register
sp | r1
toc | r2

Furthermore, the GNU tools recognize the PowerPC’s special registers:

Symbol | Register
lr | the link register
ctr | the count register
cr0 ... cr7 | the condition registers

Other PowerPC special registers (‘xer’, ‘fpscr’, etc.) are supported by the GNU tools, but do not have names since they are used implicitly by specific instructions (‘qv: mcrxr’): these registers may also be referenced in assembly language by number.

Assembler directives

This is a complete list of the PowerPC assembler directives.

.abicalls | .dcb.b | .fail | .irepc | .psize
.abort | .dcb.d | .file | .irp | .purgem
.aent | .dcb.l | .fill | .irpc | .quad
.align | .dcb.s | .float | .lcomm | .rdata
.appfile | .dcb.w | .fmask | .lflags | .rep
.appline | .dcb.x | .format | .linkonce | .rept
.ascii | .debug | .frame | .list | .rva
.asciiz | .double | .global | .livereg | .sbttl
.asciz | .ds | .globl | .llen | .sdata
.balign | .ds.b | .gpword | .loc | .set
.balignl | .ds.d | .half | .long | .short
.balignw | .ds.l | .hword | .lsym | .single
.bgnb | .ds.p | .if | .macro | .skip
.bss | .ds.s | .ifc | .mask | .space
.byte | .ds.w | .ifdef | .mexit | .spc
.comm | .ds.x | .ifeq | .mri | .stabd
.common | .dword | .ifeqs | .name | .stabn
.common.s | .eject | .ifge | .noformat | .stabs
.cpadd | .else | .ifgt | .nolist | .string
.cpload | .elsec | .ifle | .nopage | .struct
.cprestore | .end | .iflt | .octa | .text
.data | .endb | .ifnc | .offset | .title
.dc | .endc | .ifndef | .option | .ttl
.dc.b | .endif | .ifne | .org | .verstamp
.dc.d | .ent | .ifnes | .p2align | .word
.dc.l | .equ | .ifnotdef | .p2alignl | .xcom
.dc.s | .equiv | .include | .p2alignw | .xdef
.dc.w | .err | .insn | .page | .xref
.dc.x | .exitm | .int | .plen | .xstabs
.dcb | .extern | .irep | .print | .zero

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. PowerPC-specific command-line options For a list of available generic linker options, refer to "Command Language" in Using LD in GNUPro Utilities. There is only one PowerPC-specific command-line linker option.

--mpc860c0[=NUM]

This option is only applicable to MPC860 chips when producing ELF executables with the GNU linker. It causes the linker to perform a check for “problematic” conditional branches and implement a work around.

The problem is that some chips may treat the target instruction as a no-op, given the following conditions:

1. The processor is an MPC860, version C0 or earlier.
2. A forward conditional branch is executed.
3. The branch is predicted as not taken.
4. The branch is taken.
5. The branch is located in the last 5 words of a page.
6. The branch target is located on a subsequent page.

The optional argument is the number of words that are checked at the end of each text page. It may be any value from 1 to 10 and defaults to 5.
The problem is avoided by changing problematic branches to be predicted as taken.

Debugger

This section describes PowerPC-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 PowerPC target.

1. Simulator:
eCos may be 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 real hardware 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 the GDB loader stub ROM, 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.

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). PowerPC-specific command-line options
For the available generic debugger options, refer to Debugging with GDB in GNUPro Debugging Tools. There are no PowerPC 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 system’s 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 target’s 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 don’t 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 simulator allows execution of a program compiled for the PowerPC 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 PowerPC programs, without need for an actual board with that CPU.

The PowerPC simulator is capable of matching the instruction timing characteristics of different PowerPC CPUs, and can provide detailed instruction dispatch and cache profiling information. This can be handy for performance analysis, but is not necessary for simply testing eCos programs.

The simulator can also model devices, which will eventually allow eCos programs compiled for hardware targets to be run on the simulator. This is already possible to do on the simulators for the two other eCos target CPUs, but no devices have been defined for the PowerPC simulator in this release.

Features
The PowerPC simulator includes support for 32, 32-bit general-purpose registers and 32, 32-bit floating-point registers, as well as most special purpose registers.

The current release of eCos only supports the Motorola MPC860, which does not contain floating-point registers, so these registers are not currently used.

The user program is provided with a single block of memory at address ‘0x00000000’. The default size of this block is 1MB, but another size can be specified at simulator startup.

Simulator-specific command line options
Running eCos programs only requires one particular option:
-o '/iobus/pal@0xf0001000/reg 0xf0001000 32'

This simulator option defines an IO port in the simulator memory space which is used by eCos for console output. Pretty much like a serial port if you will, except that the simulator feeds any characters written on this IO port to stdout.
C:\> powerpc-eabi-run -o '/iobus/pal@0xf0001000/reg 0xf0001000 32' hello
Hello, eCos world!

-o mpc860c0[=NUM]

This option is only applicable to ELF executables for certain MPC860 chips. It causes the simulator to perform a check for "problematic" conditional branches and stop with an error message if one is executed.

The error message will include the address of the problematic branch.

The problem is that some chips may treat the target instruction as a no-op, given the following conditions:

1. The processor is an MPC860, version C0 or earlier.
2. A forward conditional branch is executed.
3. The branch is predicted as not taken.
4. The branch is taken.
5. The branch is located in the last 5 words of a page.
6. The branch target is located on a subsequent page.

The optional argument is the number of words that are checked at the end of each text page. It may be any value from 1 to 10 and defaults to 5.

-f <file> Merge ‘<file>’ into the device tree. Use this as an alternative way to specify the ‘-o’ option. For example in eCos, using the supplied file ‘BASE_DIR/hal/powerpc/sim/v1_2_1/runtime/tree’ as an argument.
The following general options, are supported by the simulator:

--help Here is a list of the PowerPC-specific options, as printed by ‘--help’:

C:\> powerpc-eabi-run -–help
Usage: psim [ <psim-option> ... ] <image> [ <image-arg> ... ] Where <image> Name of the PowerPC program to run.
<image-arg> Argument to be passed to <image>
<psim-option> See below The following are valid <psim-option>s: -c <count> Limit the simulation to <count> iterations
-i or -i2 Print instruction counting statistics
-I Print execution unit statistics
-e <os-emul> specify an OS or platform to model
-E <endian> Specify the endianness of the target
-f <file> Merge <file> into the device tree
-h -? -H give more detailed usage
-m <model> Specify the processor to model (604)
-n <nr-smp> Specify the number of processors in SMP simulations
-o <dev-spec> Add device <dev-spec> to the device tree
-r <ram-size> Set RAM size in bytes (OEA environments)
-t [!]<trace> Enable (disable) <trace> option

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 eCos’s 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
Burn hardware ROM | ROM startup
Download to ROM emulator | ROM startup
Download to board with GDB stub | RAM startup
Download to simulator ignoring devices | SIM configuration

The debugging environment for most developers will be either a hardware board with GDB stubs, or the simulator, in which case the developer will be able to select a single HAL configuration (RAM startup for the board, SIM configuration for the simulator).

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.

For further information on the PowerPC PSIM simulator, please refer to
http://sourceware.cygnus.com/psim/

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.

For example, suppose you are debugging a ROM monitor in the simulator invoked from GDB (we’ll call this GDB1), and you have downloaded an application to it from a second GDB session (which we will call GDB2). The second GDB session, GDB2, would simply consider the simulated target as a remote target and nothing more. Now suppose that in GDB2 you set a breakpoint in the program. The breakpoint will be physically set in GDB1. So when the breakpoint is reached, instead of the breakpoint being handled by the ROM monitor as if it was a real target, the breakpoint will be interpreted by GDB1 as if you had asked GDB1 to set a breakpoint in the ROM monitor code. This may not be your desired intention. To solve this, you can tell GDB1 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.

Note: if you use the aforementioned command, you will no longer be able to set breakpoints in the ROM monitor code (as in the example). You may be able to work around this problem by using conditional breakpoints. Please consult the GDB manual on how to use conditional-breakpoints.

The ambiguities discussed in this section are not a problem when you are using the standalone simulator. In such a case, the standalone simulator is the only target program that can handle the exception.

Appendix A: Bibliography

The PowerPC (tm) Architecture:A SPECIFICATION FOR A NEW FAMILIY OF RISC PROCESSORS
(Published by Morgan Kaufmann Publishers, Inc. San Francisco, California ISBN 1-55860-316-6 PB)

PowerPC (tm) Microprocessor Family:The Programming Environments
(Published by both IBM (MPRPPCFPE-01) and Motorola (MPCFPE/AD))

PowerPC MPC823 User's Manual
Motorola (MPC823UM/D)

MPC850 Integrated Communications Microprocessor User's Manual
Motorola (MPC850UM/D)

MPC860 PowerQUICC User's Manual
Motorola (MPC860UM/AD)

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

eCos User's Guide 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)