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
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
The complete tool name is a four-part hyphenated string. The first part indicates the processor family (mips). The second part indicates the processor (tx39). The third part indicates the file format output by the tool (elf). The fourth part is the generic tool name (gcc). For example, the GCC compiler for the Toshiba TX39 is mips-tx39-elf-gcc.
The TX39 package includes the following supported tools:
Tool Description | Tool Name |
GCC compiler | mips-tx39-elf-gcc |
C++ compiler | mips-tx39-elf-c++ |
GAS assembler | mips-tx39-elf-as |
GLD linker | mips-tx39-elf-ld |
Standalone simulator | mips-tx39-elf-run |
Binary Utilities | mips-tx39-elf-ar
mips-tx39-elf-nm mips-tx39-elf-objcopy mips-tx39-elf-objdump mips-tx39-elf-ranlib mips-tx39-elf-size mips-tx39-elf-strings mips-tx39-elf-strip |
GDB debugger | mips-tx39-elf-gdb |
Toshiba JMR-TX3904A-50 evaluation board
Both targets run in big-endian mode.
CPU | Operating System | Vendor |
x86 | Windows NT 4.0 | Microsoft |
x86 | Redhat Linux 5.x | Redhat |
C:\cygnus\gnupro\i386-cygwin32\mips-tx39-elf\ecos-98r1p6
For Bourne shell compatible shells:
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 )
-msoft-float
__mips__
__R3000__
New compiler and linker
features
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.
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:
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 |
Parameter registers: | |
general-purpose | r4-r11 |
floating point | f12-f19 |
Register usage: | |
fixed 0 value | r0 |
volatile | r1-r15, r24, r25 |
non-volatile | r16-r23, r30 |
kernel reserved | r26, r27 |
gp (SDA base) | r28 |
stack pointer | r29 |
frame pointer | r30 (if needed) |
return address | r31 |
* If
no alloca
region the frame pointer (FP) points to the same place as SP.
Stack frames for functions that take a variable number of arguments look like this:
* If no alloca region the frame pointer (FP) points to the same place as SP.
DOUBLE OR FLOAT:
If FR > f19, go to STACK. Otherwise, load the parameter
value into
floating-point register FR and advance FR to the
next floating-point register (or register pair in 32-bit mode). Then go
to SCAN.
SIMPLE ARG:
A SIMPLE ARG is one of the following:
LONG LONG in 32-bit mode:
If GR > r10, go to STACK. Otherwise, if GR is odd, 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- or zero-extended to this width. float arguments are considered to have size and alignment equal to the size of a floating-point register. In 64-bit mode, floats are stored in the low-order 32 bits of the 64-bit space allocated to them. double and long long are considered to have 64-bit size and alignment. 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.
Copies of large structs are made under the following rules:
ANSI mode | K&R Mode | |
Normal param | Callee copies if needed | Caller copies |
Varargs (...) param | Caller copies | Caller copies |
The varargs macros set up a two-part register save area, one part for the general-purpose registers and one part for floating-point registers, and maintain separate pointers for these two areas and for the stack parameter area. The register save area lies between the caller and callee stack frame areas.
In the case of software floating-point only the general-purpose registers need to be saved. Because the save area lies between the two stack frames, the saved register parameters are contiguous with parameters passed on the stack. This allows the varargs macros to be much simpler. Only one pointer is needed, which advances from the register save area into the caller's stack frame.
Type | Register |
int | r2 |
short | r2 |
long | r2 |
long long | r2-r3 (32-bit mode) |
float | f0 |
double | f0-f1 (32-bit mode) |
struct/union | see below |
The symbols $0 through $31 refer to the general-purpose registers.
The following symbols can be used as aliases for individual registers:
Symbol | Register |
$at | $1 |
$kt0 | $26 |
$kt1 | $27 |
$gp | $28 |
$sp | $29 |
$fp | $30 |
.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 | .zero |
MIPS Synthetic Instructions
Supported for the TX39
R1 R2 R3 - integer registers
I1 I2 I3 - immediate integers
I? - integer value dependent on values of macro arguments
Instruction | Expansion |
abs R1 R2 | bgez
R2,abs-L1
ove R1,R2 neg R1,R2 abs-L1: |
add R1 R2 I1 | addi R1,R2,I1 |
addu R1 R2 I1 | addiu R1,R2,I1 |
and R1 R2 I1 | andi R1,R2,I1 |
beq R1 I1 I2 | li
$at,I1
beq R1,$at,+I2 |
beql R1 I1 I2 | li
$at,I1
beql R1,$at,+I2 |
bge R1 R2 I1 | slt
$at,R1,R2
beqz $at,+I1 |
bge R1 I1 I2 | slti
$at,R1,I1
beqz $at,+I2 |
bgel R1 R2 I1 | slt
$at,R1,R2
beqzl $at,+I1 |
bgel R1 I1 I2 | slti
$at,R1,I1
beqzl $at,+I2 |
Instruction | Expansion |
bgeu R1 R2 I1 | sltu
$at,R1,R2
beqz $at,+I1 |
bgeu R1 I1 I2 | sltiu
$at,R1,I1
beqz $at,+I2 |
bgeul R1 R2 I1 | sltu
$at,R1,R2
beqzl $at,+I1 |
bgeul R1 I1 I2 | sltiu
$at,R1,I1
beqzl $at,+I2 |
bgt R1 R2 I1 | slt
$at,R2,R1
bnez $at,+I1 |
bgt R1 I1 I2 | slti
$at,R1,I1+1
beqz $at,+I2 |
bgtl R1 R2 I1 | slt
$at,R2,R1
bnezl $at,+I1 |
bgtl R1 I1 I2 | slti
$at,R1,I1+1
beqzl $at,+I2 |
bgtu R1 R2 I1 | sltu
$at,R2,R1
bnez $at,+I1 |
bgtu R1 I1 I2 | sltiu
$at,R1,I1+1
beqz $at,+I2 |
bgtul R1 R2 I1 | sltu
$at,R2,R1
bnezl $at,+I1 |
bgtul R1 I1 I2 | sltiu
$at,R1,I1+1
beqzl $at,+I2 |
ble R1 R2 I1 | slt
$at,R2,R1
beqz $at,+I1 |
Instruction | Expansion |
ble R1 I1 I2 | slti
$at,R1,I1+1
bnez $at,+I2 |
blel R1 R2 I1 | slt
$at,R2,R1
beqzl $at,+I1 |
blel R1 I1 I2 | slti
$at,R1,I1+1
bnezl $at,+I2 |
bleu R1 R2 I1 | sltu
$at,R2,R1
beqz $at,+I1 |
bleu R1 I1 I2 | sltiu
$at,R1,I1+1
bnez $at,+I2 |
bleul R1 R2 I1 | sltu
$at,R2,R1
beqzl $at,+I1 |
bleul R1 I1 I2 | sltiu
$at,R1,I1+1
bnezl $at,+I2 |
blt R1 R2 I1 | slt
$at,R1,R2
bnez $at,+I1 |
blt R1 I1 I2 | slti
$at,R1,I1
bnez $at,+I2 |
bltl R1 R2 I1 | slt
$at,R1,R2
bnezl $at,+I1 |
bltl R1 I1 I2 | slti
$at,R1,I1
bnezl $at,+I2 |
bltu R1 R2 I1 | sltu
$at,R1,R2
bnez $at,+I1 |
bltu R1 I1 I2 | sltiu
$at,R1,I1
bnez $at,+I2 |
Instruction | Expansion |
bltul R1 R2 I1 | sltu $at,R1,R2
bnezl $at,+I1 |
bltul R1 I1 I2 | sltiu $at,R1,I1
bnezl $at,+I2 |
bne R1 I1 I2 | li $at,I1
bne R1,$at,+I2 |
bnel R1 I1 I2 | li $at,I1
bnel R1,$at,+I2 |
div R1 R2 R3 | div
$zero,R2,R3
bnez R3,div-L6 nop break 0x7 div-L6: li $at,-1 bne R3,$at,div-L7 lui $at,0x8000 bne R2,$at,div-L7 nop break 0x6 div-L7: mflo R1 |
div R1 R2 I1 | li
$at,I1
div $zero,R2,$at mflo R1 |
divu R1 R2 R3 | divu
$zero,R2,R3
bnez R3,divu-L8 nop break 0x7 divu-L8: mflo R1 |
divu R1 R2 I1 | li
$at,I1
divu $zero,R2,$at mflo R1 |
dmul R1 R2 R3 | dmultu
R2,R3
mflo R1 |
dmul R1 R2 I1 | li
$at,I1
dmult R2,$at mflo |
Instruction | Expansion |
dsub R1 R2 I1 | daddi R1,R2,-I1 |
dsubu R1 R2 I1 | daddiu R1,R2,-I1 |
jal R1 R2 | jalr R1,R2 |
jal R1 | jalr R1 |
la R1 I1(R2) | li R1,I1
daddu R1,R1,R2 |
lb R1 I1(R2) | lb R1,I1(R2) |
lbu R1 I1(R2) | lbu R1,I1(R2) |
ld R1 I1(R2) | ld R1,I1(R2) |
ldc2 R1 I1(R2) | ldc2 R1,I1(R2) |
ldc3 R1 I1(R2) | ld R1,I1(R2) |
ldl R1 I1(R2) | ldl R1,I1(R2) |
ldr R1 I1(R2) | ldr R1,I1(R2) |
lh R1 I1(R2) | lh R1,I1(R2) |
lhu R1 I1(R2) | lhu R1,I1(R2) |
li.d R1 I1 | li
R1,I?
dsll32 R1,R1,0xf |
li.s R1 I1 | lui R1,I? |
lwc0 R1,I1(R2) | ll R1,I1(R2) |
mul R1 R2 R3 | multu
R2,R3
mflo R1 |
Instruction | Expansion |
mul R1 R2 I1 | li
$at,I1
mult R2,$at mflo R1 |
nor R1 R2 I1 | ori
R1,R2,I1
nor R1,R1,$zero |
or R1 R2 I1 | ori R1,R2,I1 |
rem R1 R2 R3 | div
$zero,R2,R3
bnez R3,rem-L12 nop break 0x7 rem-L12: li $at,-1 bne R3,$at,rem-L13 lui $at,0x8000 bne R2,$at,rem-L13 nop break 0x6 rem-L13: mfhi R1 |
rem R1 R2 I1 | li
$at,I1
div $zero,R2,$at mfhi R1 |
remu R1 R2 R3 | divu
$zero,R2,R3
bnez R3,remu-L14 nop break 0x7 remu-L14 mfhi R1 |
remu R1 R2 I1 | li
$at,I1
divu $zero,R2,$at mfhi R1 |
rol R1 R2 R3 | negu
$at,R3
srlv $at,R2,$at sllv R1,R2,R3 or R1,R1,$at |
Instruction | Expansion |
rol R1 R2 I1 | sll
$at,R2,I1
srl R1,R2,32-I1 or R1,R1,$at |
ror R1 R2 R3 | negu
$at,R3
sllv $at,R2,$at srlv R1,R2,R3 or R1,R1,$at |
ror R1 R2 I1 | srl
$at,R2,I1
sll R1,R2,32-I1 or R1,R1,$at |
sdc3 R1 I1(R2) | sd R1,I1(R2) |
seq R1 R2 R3 | xor
R1,R2,R3
sltiu R1,R1,1 |
seq R1 R2 I1 | xori
R1,R2,I1
sltiu R1,R1,1 |
sge R1 R2 R3 | slt
R1,R2,R3
xori R1,R1,0x1 |
sge R1 R2 I1 | slti
R1,R2,I1
xori R1,R1,0x1 |
sgeu R1 R2 R3 | sltu
R1,R2,R3
xori R1,R1,0x1 |
sgeu R1 R2 I1 | sltiu
R1,R2,I1
xori R1,R1,0x1 |
sgt R1 R2 R3 | slt R1,R3,R2 |
Instruction | Expansion |
sgt R1 R2 I1 | li
$at,I1
slt R1,$at,R2 |
sgtu R1 R2 R3 | sltu R1,R3,R2 |
sgtu R1 R2 I1 | li
$at,I1
sltu R1,$at,R2 |
sle R1 R2 R3 | slt
R1,R3,R2
xori R1,R1,0x1 |
sle R1 R2 I1 | li
$at,I1
slt R1,$at,R2 xori R1,R1,0x1 |
sleu R1 R2 R3 | sltu
R1,R3,R2
xori R1,R1,0x1 |
sleu R1 R2 I1 | li
$at,I1
sltu R1,$at,R2 xori R1,R1,0x1 |
slt R1 R2 I1 | slti R1,R2,I1 |
sltu R1 R2 I1 | sltiu R1,R2,I1 |
sne R1 R2 R3 | xor
R1,R2,R3
sltu R1,$zero,R1 |
sne R1 R2 I1 | xori
R1,R2,I1
sltu R1,$zero,R1 |
sub R1 R2 I1 | addi R1,R2,-I1 |
subu R1 R2 I1 | addiu R1,R2,-I1 |
swc0 R1 I1(R2) | sc R1,I1(R2) |
Instruction | Expansion |
scache R1 I1(R2) | swl R1,I1(R2) |
invalidate R1 I1(R2) | swr R1,I1(R2) |
teq R1 I1 | teqi R1,I1 |
tge R1 I1 | tgei R1,I1 |
tgeu R1 I1 | tgeiu R1,I1 |
tlt R1 I1 | tlti R1,I1 |
tltu R1 I1 | tltiu R1,I1 |
tne R1 I1 | tnei R1,I1 |
ulh R1 I1(R2) | lb
R1,I1(R2)
lbu $at,I1+1(R2) sll R1,R1,0x8 or R1,R1,$at |
ulhu R1 I1(R2) | lbu
R1,I1(R2)
lbu $at,I1+1(R2) sll R1,R1,0x8 or R1,R1,$at |
ulw R1 I1(R2) | lwl
R1,I1(R2)
lwr R1,I1+3(R2) |
ush R1 I1(R2) | sb R1,I1+1(R2)
srl $at,R1,0x8 sb $at,I1(R2) |
usw R1 I1(R2) | swl R1,I1(R2)
swr R1,I1+3(R2) |
xor R1 R2 I1 | xori R1,R2,I1 |
There are two ways for GDB to talk to a TX39 target.
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.
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.
Debugging programs with
multiple threads
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
info threads
When your program has multiple threads, you can choose
whether to set breakpoints on all threads, or on a particular thread.
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.
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
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]
The TX39 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.
The user program is provided with a single 32mb block of memory at address 0xa0000000 (shadowed at address 0x80000000).
--board=BOARD
The tx39 simulator also supports --board=jmr3904pal,
a superset of the JMR TX3904 board simulation. This adds certain virtual
devices used by eCos programs that were configured with the --platform=sim
option.
C:\> mips-tx39-elf-run
--profile --frequency 128 hello
Hello, world!
3 + 4 = 7
C:\> mips-tx39-elf-run
-help
Usage: run [options]
program [program args]
Options:
C:\> mips-tx39-elf-run
--trace hello
Hello, world!
3 + 4 = 7
The simulator rounds the sample size up the next power of two.
C:\> mips-tx39-elf-run
--profile --samples 20000 hello
Hello, world!
3 + 4 = 7
C:\> mips-tx39-elf-run
--trace hello
Hello, world!
3 + 4 = 7
Here are the first 10 lines of the file produced by the above run:
2 a0040004 ; width
4 ; load instruction
2 a0040008 ; width
4 ; load instruction
2 a004000c ; width
4 ; load instruction
2 a0040010 ; width
4 ; load instruction
2 a0040014 ; width
4 ; load instruction
2 a0040018 ; width
4 ; load instruction
2 a004001c ; width
4 ; load instruction
2 a0040020 ; width
4 ; load instruction
2 a0040024 ; width
4 ; load instruction
2 a0040028 ; width
4 ; load instruction
C:\> mips-tx39-elf-run
--trace --tracefile=trace.out hello
Placing trace information
into file "trace.out"
Hello, world!
3 + 4 = 7
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 CygMon | RAM startup |
Download to simulator without CygMon | ROM startup |
Download to simulator with CygMon | RAM startup |
Download to simulator ignoring devices | SIM configuration |
If you are building eCos for the simulator configuration, you must remember to start the simulator with the --board=jmr3904pal option rather than the normal --board=jmr3904 ROM startup option.
If you fail to use the correct option your application is likely to
fail with errors like: SIGSEGV:
bus error.
In some cases, you may want to use a simulator specific configuration to try to work around problems with the device drivers or with the simulator itself.
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 example, suppose you are debugging a ROM monitor in the simulator invoked from GDB (well 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:
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
While this approach offers the desired functionality, it is has a few disadvantages. The simulator is not only slow to execute code compared with real hardware, but simulation of the ROM monitor also slows the downloading of code to approximately the speed of a serial port. In addition, since the simulator must run continuously to execute CygMon, it can interfere with the performance of GDB. If there is insufficient memory for both programs to be in memory together, there may also be delays due to memory paging.
This technique uses TCP/IP for communication between the simulator and GDB, so you must ensure that the TCP/IP protocol stack is installed on your machine.
To run CygMon in the simulator, type the following command at the command line:
mips-tx39-elf-run --board=jmr3904 --sockser-addr=localhost:XXXX cygmon.rom
Where XXXX, is an unused TCP port number on your computer. A value of 1234 usually works, but any number between 1024 and 65535, which does not result in an error will do. The executable, cygmon.rom can be found in the directory, loaders/tx39-jmr3904 within the eCos installation.
This has started the simulator running CygMon. To make use of it you must run a separate GDB session and connect to it.
If you run GDB in command-line mode, you can attach it
to the simulated CygMon with the following command:
If you are running the GDBTk then, in the Target Settings dialog, select Remote/TCP in the Target edit field. Type localhost into the Host edit field, and put the value chosen for the port number in the Port entry.
You should use executables configured to run on the target board with RAM startup, and not executables configured for the simulator.
If the performance of the two programs on a single machine
is too slow, it is possible to use two machines: one to run the simulator
and one to run GDB. These machines must be connected together on a TCP/IP
network. Run the simulator on one machine, but supply the name of the machine
in place of localhost
in the --sockser-addr
option. When running GDB on the other machine, replace localhost
with the name of the machine running the simulator.
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
For users of the Sourceware release of eCos, instructions can be found at
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.
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:
cygmon.rom
Is the ELF executable of the ROM-resident version of
CygMon. It is used in the standalone simulator for thread-aware debugging.
cygmon.sre
Is the ROM-resident version of CygMon in S-Record format.
File names | Descriptions | |
|
||
libstub/generic-stub.c | Generic remote debug stub | |
libstub/relocate.c | Segment relocation while booting ROMS | |
libstub/stub-vpatchtrap.c | Detailed vector table management | |
|
||
libstub/mips/mip.mk | Makefile common to all mips variants | |
libstub/mips/crt0_stub.S | From _start to main( ) for all mips variants | |
libstub/mips/mips-stub.c | Specific to mips, common to mips variants | |
libstub/mips/mips-vir-tab.S | Vector table indexed by interrupt cause | |
|
||
libstub/mips/tx39jmr.mk | Linker map, downloadable cygmon/libstub | |
libstub/mips/tx39jmr/jmr3904.ld | Linker script, ROM cygmon or libstub | |
libstub/mips/tx39jmr/jmr3904rom.ld | Debug stub exception handler | |
libstub/mips/tx39jmr/stubrom.c | Reconfigure initialization for ROM | |
libstub/mips/tx39jmr/tx39jmr-board.c | JMR board specific, NOT IO | |
libstub/mips/tx39jmr/tx39jmr-board.h | Key macro definitions | |
libstub/mips/tx39jmr/tx39jmr-power.S | JMR board minimal initialization | |
libstub/mips/tx39jmr/tx39jmr-serial.c | JMR board serial driver for debugging | |
libstub/mips/tx39jmr/tx39jmr-stubmain.c | Main to tie it together |
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.
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.
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.
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.
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.
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.
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.
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 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.
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 v1 1f
Places the value 1f in the register v1.
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.
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.
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.
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.
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.
The version command displays the version of the monitor.
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 |
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.
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)