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 is only supported for
the AM31 (MN10300) part. For the AM33 you should use the GDB stub ROM provided
with eCos. Therefore, the remainder of this appendix only applies to the
AM31 part.
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.
CygMon includes an API, which
allows user programs, running under it, to use system calls for various
functions. The available system calls allow access to the serial ports
and on-board timer functions, if they are available.
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 selecting the appropriate
component, the eCos installer will install the CygMon source code, and
we recommend you do so. When installed the sources would then be found
in:
C:\Program
Files\Cygnus Solutions\eCos\ecos-99r1-990828\cygmon-src
If you choose to install the
sources to a different location, the '
cygmon-src'
directory will be located at
'
ecos-99r1-990828\cygmon-src'
relative to the specified location. Please note that due to the configuration
and build tools being used, the sources must be installed in a directory
hierarchy that uses only alphanumeric, dash or underscore characters in
the directory names.
Building CygMon
From the Start Menu, select:
Programs->Cygnus
eCos->eCos Development Environment
This will bring up a window
running "bash".
Mount the sources such that
the full path to the CygMon sources uses only alphanumeric, dash or underscore
characters:
mount
C:/Program\ Files/Cygnus\ Solutions/eCos /ecos
In addition, you must mount
the bin directory for the unsupported tools as '
bin':
mount
C:/cygnus/gnupro/i686-cygwin32/i686-cygwin32/\
unsupported-99r1/H-i686-cygwin32/bin
/bin
You should now be able to
configure and build CygMon as follows:
mkdir
/ecos/ecos-99r1-990828/objdir
cd /ecos/ecos-99r1-990828/objdir
../cygmon-src/configure
--host=i686-cygwin32 --target=mn10300-elf
make -w
When complete, you will have
CygMon images built in:
Is the ROM-resident version of CygMon in binary format.
Is the ELF executable of the ROM-resident version of CygMon.
It is used in the standalone simulator for thread-aware debugging.
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.
|
|
|
|
Generic remote debug stub
|
|
Segment relocation while
booting ROMS
|
|
Generial CygMon monitor
support
|
|
Cygmon command interpreter
|
|
|
|
libstub/mn10300/mn10300.mk
|
Makefile common to all
mn10300 variants
|
libstub/mn10300/mn10300-stub.c
|
Specific to mn10300, gdb
stub support
|
cygmon/mn10300/mn10300.mon.c
|
Specific to mn10300, CygMon
support
|
|
|
Makefile specific to MN10300
EVB
|
libstub/mn10300/mn10300-lib.c
|
|
cygmon/mn10300/mn10300.mon.ld
|
CygMon linker script for
EVB
|
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
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
Sets the speed
of the active port to 9600 baud.
break
Usage
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
Sets a breakpoint
at address '
4ff5'.
disassemble
Usage
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.
Example
Displays disassembled
code starting at location '
45667000'.
dump
Usage
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
Displays 16 bytes starting
with '
44f0'
and ending with '
44ff'.
go
Usage
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
Sets the '
pc'
to '
40020000'
, and starts program execution.
help
Usage
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
Shows the help
screen for the command '
foo'.
load
Usage
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
Places the 8-bit value 57
at the location '
45f6b2'.
port
Usage
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
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
Places the value
'
1f' in the
register '
r1'.
reset
Usage
The reset command
resets the board.
step
Usage
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
Executes one instruction
at the current '
pc'.
terminal
Usage
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
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
The unbreak command
removes breakpoints from memory. It takes one argument, the location to
remove the breakpoint from.
Example
Removes a previously
set breakpoint at memory location '
4ff5'.
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
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.
|
|
|
Execute the currently
displayed command
|
|
Move to Beginning of line
|
|
|
|
|
|
|
|
|
|
Yank Character (undelete)
|
|
|
|
|
|
|
|
|
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.