# CygMon: The 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.

Not all eCos targets support CygMon as the ROM monitor. Some targets use simple GDB remote stub ROMs that only provide for communication with GDB. Please examine the Getting Started with eCos manual to determine whether CygMon is applicable to your target platform.

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.

## Rebuilding CygMon

The eCos Developer's Kit comes supplied with prebuilt CygMon ROM images that can be used on the target board. If for some reason you need to rebuild CygMon, you can follow the instructions for your specific target board found in the Getting Started with eCos manual.

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

### copy

Usage: `copy` startaddr destaddr amount

> Used to copy 'amount' bytes of memory from 'startaddr' to 'destaddr'.

Example: `copy 10000 20000 300`

> Copies 0x300 bytes of memory from 0x10000 to 0x20000.

### crc

Usage: crc startaddr endaddr

> The crc command is used to calculate a standard CRC32 checksum of the specified memory region. The checksum is displayed as a hexadecimal value.

Example: `crc 1000 2000`

> Calculates the CRC32 value of the memory contents between 0x1000 and 0x2000 inclusive.

### disassemble

Note: This option is not supported for use with eCos.

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`'.

### fill

Usage: fill[.size] startaddress endaddress[value]

> Used to fill a region of memory from 'startaddress' to 'endaddress' with the value in 'value'. If no value is specified, it uses zero. 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 size of the writes that are used, in bits.

Example: `fill.32 20000 21000 32`

> Would fill memory from 0x20000 to 0x21000 with the 32-bit value 0x32.

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

### history

Usage: `history`

> The history command will display the commands most recently entered at the CygMon command prompt. By default the 10 most recently entered commands are stored.

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

### swapmem

Usage:swapmem [little|big]

> The swapmem command is used to determine whether or not memory values are displayed and written in little or big-endian byte order. By default, values are read and written to match the byte order of the target CPU.

> This command does not alter the CPU state in any way; it only changes the way memory values are displayed and written within the monitor.

Example: `swapmem`

> Displays the byte order that is currently in effect.

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

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