GNUProÔ Toolkit
 
 
GNUPro Toolkit Reference for eCos
Toshiba TX39
 
 
 
 
 
eCos 1.1
October 1998
 
 
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 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 East

CYGNUS SOLUTIONS
955 Massachusetts Avenue
Cambridge, MA 02139-3180

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 U.K.

CYGNUS SOLUTIONS
35-36 Cambridge Place
Cambridge CB2 1NS
United Kingdom

Part #: 300-400-1010047-1.0
 
 
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  TX39-specific command-line options
Preprocessor symbols
TX39-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  MIPS-specific command-line options 
Syntax 
Register names 
Assembler directives 
MIPS Synthetic Instructions Supported for the TX39
Linker  TX39-specific command-line options Debugger  TX39-specific command-line options 
Debugging programs with multiple threads
Simulator  Features 
Simulator-specific command line options 
Using the simulator 
Simulator exceptions within GDB 
CygMon, the simulator, and thread-aware debugging
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
Appendix B: Bibliography 

 
Introduction


The GNUPro Toolkit from Cygnus is a complete solution for C and C++ development for the Toshiba TX39. The tools include the compiler, interactive debugger and utilities libraries. Debugger and linker support is also included for the Toshiba JMR-TX3904A-50 Evaluation board. In addition to this manual, please read "Getting started 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 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
  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 TX39-specific features of the GNUPro Toolkit. Processor version(s) Toshiba TX39. Targets Supported GNUPro Instruction Set Simulator

Toshiba JMR-TX3904A-50 Evaluation board

Both 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 TX39  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\mips-tx39-elf\ecos-98r1p3

SET PROOT=C:\cygnus\gnupro\i386-cygwin32\mips-tx39-elf\ecos-98r1p3
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 Unsupported Tools for eCos are also installed. Assuming these are installed in their default location in

C:\cygnus\gnupro\i386-cygwin32\i386-cygwin32\unsupported-98r1p2

then add the environmental setting:

SET PATH=C:\cygnus\gnupro\i386-cygwin32\i386-cygwin32\unsupported-98r1p2\H-i386-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: The following strings are not case sensitive under Windows NT: 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-981021/src
 
By following the instructions in the Installation Guide, you should eventually have the tools installed in
  /usr/cygnus/ecosSWtools-981021/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-981021
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-981021

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 TX39-specific features of the GNUPro Compiler. TX39-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. MIPS-specific options can also be found in the MIPS Development section of GNUPro Tools for Embedded Systems. In addition, the following TX39-specific command-line option is of particular interest:

-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:

__mips__
__R3000__

Each of these is always defined. __mips_eabi Is always defined because the GNUPro TX39 toolchain conforms to the MIPS Embedded ABI __MIPSEB__ Is always defined, because the tx39 is big-endian only. __mips_soft_float Is always defined, because the tx39 has no FPU, and so passing  ‘-msoft-float’ to the compiler is unnecessary.
TX39-specific attributes There are no TX39-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 MIPS Embedded Application Binary Interface (EABI). As the TX39 does not have a floating-point unit, the parts of the EABI pertaining to floating point registers do not apply. 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
   

Subroutine calls


The following describes the calling conventions for subroutine calls. The first table outlines the registers used for passing parameters. The second table outlines other register usage.  
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
   

The Stack Frame


This section describes TX39 stack frame: Stack frames for functions that take a fixed number of arguments look like this:

* 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.

 

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 (or register pair for modes in which floating-point registers hold only 32 bits). ‘GR’ contains the number of the next available general-purpose register. ‘STARG’ is the address of the next available stack parameter word.
INITIALIZE: Set ‘GR=r4’, ‘FR=f12’, 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 > 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:

If ‘GR > r11’, 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 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’.

Structure passing


  As noted above, code, which passes structures and unions by value is implemented specially. (In this section, "struct" will refer to structs and unions inclusively.) Structs small enough to fit in a register are passed by value in a single register or in a stack frame slot the size of a register. Larger structs are handled by passing the address of the structure. In this case, a copy of the structure will be made if necessary in order to preserve the pass-by-value semantics.

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
  In the case of normal (non-varargs) large-struct parameters in ANSI mode, the callee is responsible for producing the same effect as if a copy of the structure were passed, preserving the pass-by-value semantics. This may be accomplished by having the callee make a copy, but in some cases the callee may be able to determine that a copy is not necessary in order to produce the same results. In such cases, the callee may choose to avoid making a copy of the parameter. Varargs handling

No special changes are needed for handling varargs parameters other than the caller knowing that a copy is needed on struct parameters larger than a register (see above).

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.

Function Return Values

Data types and register usage for return values:  
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
  Structures and unions, which will fit into two general-purpose registers are returned in ‘r2’, or in ‘r2’ and ‘r3’ if necessary. They are aligned within the register according to the endianness of the processor; e.g., on a big-endian processor the first byte of the struct is returned in the most significant byte of ‘r2’, while on a little-endian processor the first byte is returned in the least significant byte of ‘r2’. 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 TX39-specific features of the GNUPro Assembler. MIPS-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 information about the MIPS instruction set, see MIPS RISC Architecture, (Kane and Heindrich, Prentice-Hall). For an overview of MIPS assembly conventions, see "Appendix D: Assembly Language Programming" in the same volume. Register names There are 32 64-bit general (integer) registers, named ‘$0’ through ‘$31’.

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
 

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
 

MIPS Synthetic Instructions Supported for the TX39


The TX39 GAS assembler supports the typical MIPS synthetic instructions (macros). What follows is a list of synthetic instructions supported by the assembler, as well as an example expansion of each instruction.

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
daddu R1 R2 I1 daddiu R1,R2,I1
ddiv R1 R2 R3 ddiv $zero,R2,R3  
bnez R3,ddiv-L3  
nop  
break 0x7  
ddiv-L3:  
daddiu $at,$zero,-1  
bne R3,$at,ddiv-L4  
daddiu $at,$zero,1  
dsll32 $at,$at,0x1f  
bne R2,$at,ddiv-L4  
nop  
break 0x6  
ddiv-L4:  
mflo R1
ddiv R1 R2 I1 li $at,I1  
ddiv $zero,R2,$at  
mflo R1
ddivu R1 R2 R3 ddivu $zero,R2,R3 
bnez R3,ddivu-L5 
nop 
break 0x7 
ddivu-L5: 
mflo R1
ddivu R1 R2 I1 li $at,I1 
ddivu $zero,R2,$at 
mflo R1
 

 

Instruction Expansion
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
dla R1 I1(R2) li R1,I1  
daddu R1,R1,R2
dli R1 I1 li R1,I1
dmul R1 R2 R3 dmultu R2,R3  
mflo R1
dmul R1 R2 I1 li $at,I1  
dmult R2,$at  
mflo 
 

 

Instruction Expansion
drem R1 R2 R3 ddiv $zero,R2,R3  
bnez R3,2e4  
nop  
break 0x7  
drem-L9:  
daddiu $at,$zero,-1  
bne R3,$at,drem-L10  
daddiu $at,$zero,1  
dsll32 $at,$at,0x1f  
bne R2,$at,drem-L10  
nop  
break 0x6  
drem-L10:  
mfhi R1
drem R1 R2 I1 li $at,I1  
ddiv $zero,R2,$at  
mfhi R1
dremu R1 R2 R3 ddivu $zero,R2,R3  
bnez R3,dremu-L11  
nop  
break 0x7  
dremu-L11:  
mfhi R1
dremu R1 R2 I1 li $at,I1  
ddivu $zero,R2,$at  
mfhi R1
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)
 

 

Instruction Expansion
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
uld R1 I1(R2) ldl R1,I1(R2)  
ldr R1,I1+7(R2)
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)
 

 

Instruction Expansion
usd R1 I1(R2) sdl R1,I1(R2)  
sdr R1,I1+7(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
 

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

 

Debugger

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

    1. Simulator:

    2. To build eCos for the simulator you may either configure it to build for the target hardware with ROM startup, or 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.
       

    3. Remote target board:

    4. 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, or GDB loader stub 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.

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).
TX39-specific command-line options For the available generic debugger options, refer to Debugging with GDB in GNUPro Debugging Tools. There are no TX39 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

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.
  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_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_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..

 

Simulator

The GNUPro simulator allows execution of a program compiled for the TX39 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 TX39 programs, without need for an actual board with that CPU.

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.

Features
  The TX39 simulator includes support for 32, 32 bit general-purpose registers.

The user program is provided with a single 32mb block of memory at address ‘0xa0000000’ (shadowed at address ‘0x80000000’).

Simulator-specific command line options
  The following general options, are supported by the simulator:

--board=BOARD

Specifies that the simulator be tailored model a specified hardware board. For the tx39, the ‘--board=jmr3904’ option will add support for the peripherals of the JMR-TX3904A-50 Evaluation Board, including the tx3904 CPU’s on-board interrupt controller, timers, serial I/O modules. The board’s actual RAM & ROM memory layouts are matched by the simulator.

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.
 

--frequency <frequency> By default, the simulator samples the running program every 256 instructions. This option allows you to change this profiling frequency to some other number. Smaller numbers increasing the accuracy of the profile, but make the simulator run slightly slower. Also, because the counters used in the profile are only 16 bits, a high sampling frequency may cause the counters to overflow.

C:\> mips-tx39-elf-run --profile --frequency 128 hello
Hello, world!
3 + 4 = 7
 

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

C:\> mips-tx39-elf-run -–help
Usage: run [options] program [program args]
Options:

-l FILE, --log FILE Log file
-n MODEL, --name MODEL Select arch model
-p[on|off], --profile [on|off]
Enable profiling
-t[on|off], --trace [on|off]
Enable tracing
-z FILE, --tracefile FILE Write trace to file
-y FREQ, --frequency FREQ Profile frequency
-y SIZE, --samples SIZE Profile sample size
 
--profile [on|off] This option creates a file called ‘gmon.out’ that contains profiling information. This file can be used as input to ‘gprof’, the GNU profiler.

C:\> mips-tx39-elf-run --trace hello
Hello, world!
3 + 4 = 7
 

--samples <size> By default, the simulator uses a profiling sample size of 131072 (128K). This option allows you to change the sample size. Increasing the sample size will make the profile more accurate, but will also increase the size of the profile output file (‘gmon.out’).

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
 

--sockser-addr=HOSTNAME:PORT Specifies that the simulation of the primary serial I/O peripherals should send data to and from a TCP/IP socket rather than to and from the simulator console. The TCP/IP socket’s listening address is specified by the argument. HOSTNAME should refer to an IP address of the host, and PORT should be an unused port number between 1024 and 65535. You may use any terminal program that connects to TCP/IP sockets, such as telnet, kermit, or socket, to interact directly with the simulated program. You can also use gdb’s ‘target remote HOSTNAME:PORT’ command to connect, if the simulator is running a program equipped with a gdb stub.

--trace=[on|off]

This creates a file called ‘trace.din’ that contains tracing information. Use the ‘--tracefile’ switch (discussed below) to change the name of the output file.

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
 

--tracefile <file> This changes the name of the file to which trace information will be written.

C:\> mips-tx39-elf-run --trace --tracefile=trace.out hello
Placing trace information into file "trace.out"
Hello, world!
3 + 4 = 7

 
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. With some special considerations, the simulator is able to run programs built for any of these methods. 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 CygMon RAM startup
Download to simulator without CygMon ROM startup
Download to simulator with CygMon RAM startup
Download to simulator ignoring devices SIM configuration
  CAUTION: An application configured for RAM startup cannot be run directly on the simulator: it will fail during startup. You can only download it to the simulator if you are already running CygMon in the simulator, as described below.
The simulator-specific configuration does not include device drivers or watchdog devices that the simulator would otherwise have to emulate.

In most circumstances, you should not download to simulator ignoring devices. If you use this download method, the binaries built with the configuration will not run on the target board; they can only run on the simulator. On the other hand, binaries built for the target boards can also be run on the simulator.

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.

When using a system configured for simulator startup, ignoring devices, invoke the simulator with the ‘--board=jmr3904pal’ option instead of the ‘--board=jmr3904’ option.
 
 

Simulator exceptions within GDB

CygMon, the simulator, and thread-aware debugging

The simulator does not support thread-aware debugging. However, CygMon does support it. To obtain this functionality in the simulator, run CygMon under the simulator, and interact with it as if it were actually running on the real hardware.

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:
 

(gdb) target remote localhost:XXXX
 
Where ‘XXXX’ is the port number given in the call to the simulator. GDB should connect to the simulator and talk to the version of CygMon running in it in exactly the same way as if it were talking to CygMon running on the real hardware.

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.
 
 

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.

For users of the Sourceware release of eCos, instructions can be found at

http://sourceware.cygnus.com/ecos/

Installing CygMon Source
  By default, the GNUPro toolchain installer will install the CygMon source code, and we recommend you do so. When installed the sources would then be found in:

C:\cygnus\gnupro\i386-cygwin32\mips-tx39-elf\ecos-98r1p3\cygmon-src

  If you choose to install the sources to a different location, the ‘cygmon-src’ directory will be located at ‘ecos-98r1p3\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.

In our examples everything is assumed to be installed on drive ‘C:’. If the CygMon source was not installed initially, it may be installed later by running the GNUPro compiler tools installer from the CD (‘D:’ must be replaced with the proper drive letter for your CD-ROM drive):
 

D:\tools\comp\tx39\setup.exe
 
When asked where to install the tools, select a location, which uses only alphanumeric, dash or underscore characters in the directory names. For example:
  C:\ecos-cygmon
 
Next, select only the "CygMon Source Code" component. You will need to deselect the "Tools", "Documenatation" and "Source Code" components if the checkboxes are checked.

When the installation is complete, the sources should be installed in:
 

C:\ecos-cygmon\ecos-98r1p3\cygmon-src
 
Building CygMon
  From the Start Menu, select:

Programs->Cygnus eCos->eCos Development Environment

This will bring up a window running "bash".

If the location of your sources is not already mounted, do so:
 

mount C: /c
 
In addition, you must mount the installation 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 //c/ecos-cygmon/ecos-98r1p3/objdir
cd //c/ecos-cygmon/ecos-98r1p3/objdir
../cygmon-src/configure --host=i386-cygwin32 --target=mips-tx39-elf
make -w

When complete, you will have CygMon images built in:
 

mips-tx39-elf/cygmon/tx39jmr
 
The images are:
  cygmon.exe
Is the ELF executable of the RAM-resident version of CygMon

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.

 

If you want to read the source code, here are the names of the files in the cygmon and libstub directories, specific to this version of CygMon.
 
File names Descriptions
Generic Parts
libstub/generic-stub.c Generic remote debug stub
libstub/relocate.c Segment relocation while booting ROMS
libstub/stub-vpatchtrap.c Detailed vector table management
Processor Specific Parts
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
Board Specific Parts
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
 

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’.

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.

 

 

Appendix B: Bibliography

JMR-TX3904 User's Manual
TX3904 RISC Processor Reference Board
(Rev. 0.02, October 31, 1997, Toshiba America Electronics Components, Inc.)

Getting Started with eCos
(Sunnyvale: Cygnus Solutions, 1998)

eCos User Guides
(Sunnyvale: Cygnus Solutions, 1998)

eCos Reference Manual
(Sunnyvale: Cygnus Solutions, 1998)

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

GNUPro Compiler Tools
(Sunnyvale: Cygnus Solutions, 1998)

GNUPro Debugging Tools
(Sunnyvale: Cygnus Solutions, 1998)

GNUPro Libraries
(Sunnyvale: Cygnus Solutions, 1998)

GNUPro Utilities
(Sunnyvale: Cygnus Solutions, 1998)

GNUPro Advanced Topics
(Sunnyvale: Cygnus Solutions, 1998)

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

System V Application Binary Interface (Prentice Hall, 1990)