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

> mn10300-elf/cygmon/eval

The images are:

> cygmon.img

> > Is the ROM-resident version of CygMon in binary format.

> cygmon.rom

> > Is the ELF executable of the ROM-resident version of CygMon. It is used in the standalone simulator for thread-aware debugging.

> 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
cygmon/bsp/monitor.c | Generial CygMon monitor support
cygmon/bsp/monitor_cmd.c | Cygmon command interpreter
cygmon/bsp/ledit.c | CygMon line editor
Processor Specific Parts
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
Board Specific Parts
libstub/mn10300/eval.mk | Makefile specific to MN10300 EVB
libstub/mn10300/mn10300-lib.c | Support for MN10300 EVB
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

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.

#### 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 r1 1f
Places the value '1f' in the register 'r1'.

### reset

#### Usage

reset
The reset command resets the board.

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