Simulator Commands
NOTES ON COMMAND SYNTAX
- In general, case (upper, lower, mixed) does not matter.
- The syntax of each command is listed below in the format:
Command: NAME (X* parameter [optionalParameter])
X* literally means X, followed by any sequence of characters. This is generally used
to show the minimum required to specify a certain command option. For example, "B*"
means "BREAKPOINT", but you are allowed to put just "B" or "BRE" or "BREAK", etc.
(actually anything that simply starts with B).
B* = BREAKPOINT
G* = GUARD
M* = MEMORY or MODIFIED (depending on where used)
R* = REGISTER
- The symbol "|" means "or" (technically, it means "xor") and is used to divide groups of
parameter options. For example "(parameter1) | (parameter2)" means you can specify either
(parameter1) or (parameter2), but not both.
- A parameter surrounded by "[" and "]" means that the parameter is optional. If not specified,
a default value is usually used instead.
Command: ADD ( (B* address) | (G* expression) )
Alias: +
----------------------------------------------------------------------
Result:
* ADD DONE
Exception Messages:
Invalid address specified for breakpoint.
Unable to initialize breakpoint list.
Unable to add breakpoint.
Breakpoint already exists at that address.
Invalid guard expression.
Unable to add guard expression.
Incorrect use of ADD command.
Description:
Allows you to add breakpoints at a given address, or add a guard expression. For example, to
add a breakpoint at address 0x00400040, then issue "ADD BREAKPOINT 0x00400040". The address
can also be specified as a decimal value, such as 100. GUARD expressions are currently not
supported. That is, you can specify anything you want as the expression. However, the
simulator does not currently evaluate the expression.
Command: CHECKPOINT
Alias:
----------------------------------------------------------------------
Result:
* CHECKPOINT DONE
Exception Messages:
Description:
Forces the creation of a checkpoint for this cycle.
Command: EXIT
Alias: X, QUIT
----------------------------------------------------------------------
Result:
* EXIT DONE
Exception Messages:
Error deallocating simulator.
Description:
This command should be issued to terminate the simulator. It instructs the command processor
to null the simulator. The simulator can be re-initialized by issuing a RESET command.
Command: GET ( M* [ range | single | M* ] ) | ( R* (GPR|CP0|CP1) [ range | single ] )
Alias: G, DUMP
----------------------------------------------------------------------
Result:
* GET MEMORY startAddress(8) v1(2) ... vN(2)
* GET REGISTER GPR index(2) value(8)
* GET REGISTER CP0 index(2) value(8)
* GET REGISTER CP1 index(2) value(8)
* GET ERR ERR_CRITICAL errorMsg
* GET DONE
Exception Messages:
Invalid memory range or value specified.
Invalid register range or value specified.
Invalid use of GET command.
Description:
Used to get a specific value or range of values of memory or register.
If the MEMORY parameter is used: you can specified what memory to get in three different ways:
1) a range from start to stop, such as "0x10000000-0x1000003D" or "100-200"
2) a specific single address (such as "0x00400040")
3) use the MODIFIED keyword to get only the modified memory values
The GET command will return the starting address (the starting address of the range specified)
in 8-digit hex, followed by the byte values in memory starting at that address (each value is
specified in 2-digit hex). Be aware that issuing a command such as "GET MEMORY 0x00000000-0xFFFFFFFF"
to get the entire contents of memory is not a good idea (you will most likely get an out of memory
error response). In general, you should only request small regions of memory. If no range or address
value is specified, then the GET MEMORY command will default to the MODIFIED version. When requesting
only MODIFIED memory addresses, the GET MEMORY command may return multiple lines in the command result
buffer. Each line in the response begins with an 8-digit hex address, followed by the modified memory
values starting at that address. If a non-modified memory address is found, a new line in the response
is started. This next line in the command response marks the beginning of the next region of modified
memory. For example, the response might be two lines as follows:
* GET MEMORY 00400000 AA BB CC DD ... ZZ
* GET MEMORY 10000000 00 00 10 11 12 ... 13
This indicates that there are two regions of modified memory, one starting at
0x00400000 and another at 0x10000000.
If the REGISTER parameter is used: there are three different sets of registers values (GPR = General
Purpose Registers, CP0 = Coprocessor0, CP1 = Coprocessor1). Therefore you must specify which set of
registers is desired, followed by the specified register or range of registers (e.g. if you specify
GPR, you could select "0-31" or "$t0-$t7"). The GET command will return the index of the desired
register(s) (in 2-digit hex format), followed by the 8-digit hex value of that register. If multiple
registers are specified, then the GET command returns multiple responses (that is, only one register
per response). If no range or value is specified, then the GET command will return the value of all
of the registers in the specified register set.
Command: HELP
Alias: H, ?
----------------------------------------------------------------------
Result:
* HELP command
* HELP DONE
Exception Messages:
Description:
Retrieves a list of valid commands and their parameters. This is primarily an internal reference or
for testing purposes.
Command: LIST ( B* | G* )
Alias: I
----------------------------------------------------------------------
Result:
* LIST BREAKPOINT NONE
* LIST BREAKPOINT index address(8)
* LIST GUARD NONE
* LIST GUARD index guardExpression
* LIST DONE
Exception Messages:
Incorrect use of LIST command.
Description:
Used to list either breakpoints or guards. The index is the corresponding index in decimal
(e.g. 0, 1, 2, ...). For breakpoints, the corresponding address is returns as an 8-digit hex value.
Currently, guards are not supported. But if a guard is added, this command will return the guard string
that was added. The index number can be used in the REMOVE command.
Command: LOAD (S filename) | (T x1 x2 x3 x4 [Ly]) | (D x1 ... xN)
Alias: L
----------------------------------------------------------------------
Result:
* LOAD OK
* LOAD ERR ERR_INVALID_LIT
* LOAD ERR ERR_CRITICAL
* LOAD DONE
Exception Messages:
Description:
Used to load a MIPSASM code file. This command can be used manually. However, this command was actually
designed to be used as follows: the MIPS assembler compiles MIPS assembly code, and the output of the
assembler matches the parameters for this command. Therefore, the assembler output can be sent directly
to the simulator using the LOAD command. Each line in the assembler output requires another LOAD command
to be issued. For an explanation to the parameters of this command, refer to the format of the assembler
output.
Command: REMOVE ( B* | G* ) index
Alias: -
----------------------------------------------------------------------
Result:
* REMOVE DONE
Exception Messages:
Invalid breakpoint index.
Invalid guard index.
Incorrect use of REMOVE command.
Description:
Used to remove a previous added breakpoint or guard, referenced by index. Use the LIST command to list
what breakpoint or guards are defined.
Command: RESET
Alias:
----------------------------------------------------------------------
Result:
* RESET OK
* RESET ERR ERR_UNKNOWN_ERROR errorMsg
* RESET DONE
Exception Messages:
Description:
Used to initialize or reset the simulator. This clears all memory and register values. It returns the
simulator to the initial state. Before using the simulator, a RESET command should be issued first.
Command: RUN
Alias:
----------------------------------------------------------------------
Result:
* RUN ERR ERR_INVALID_RESPONSE
* RUN ERR ERR_NOT_STEP_RESPONSE
* RUN BREAKPOINT index
* RUN GUARD index
* RUN EXCEPTION index
* RUN ERR ERR_STEP_ERROR stepResponse
* RUN DONE
Exception Messages:
Description:
The RUN command starts to run any instruction at the current Program Counter. The simulator continues
to run, until one of several conditions occurs: (1) breakpoint encountered, (2) guard encountered,
(3) exception encountered, (4) some general error. If none of these conditions is ever encountered, the
program will run indefinitely (most likely an exception will eventually occur). The RUN command works
by repeatedly issuing "STEP 1" commands. If the step encountered an error, then ERROR_STEP_ERROR is
returned followed by the entire stepResponse. If an exception occurs, the client should check the
exception index to determine what exception has occurred (and respond appropriately). All indexes are
specified in decimal integer form (e.g. 0, 1, 2, ...)
Command: SET ( M* (range|single) value ) | ( R* (GPR|CP0|CP1) (range | x) value )
Alias:
----------------------------------------------------------------------
Result:
* SET DONE
Exception Messages:
Invalid range or value specified.
Invalid memory value specified.
Memory value must be 8-bit number.
Invalid register set specified in SET command.
Invalid range or value or incorrect use of SET command.
Invalid use of SET command.
Description:
Used to set a range of specific memory address or register to the specified value. The parameters are
similar to those of the GET command, except that a value is specified to indicate the desired value.
For memory, the value must be an 8-bit value (0x00-0xFF). For registers, the value can be up to an 8-digit
hex value (32-bit word, 0x00000000-0xFFFFFFFF).
Command: STATUS
Alias:
----------------------------------------------------------------------
Result:
* STATUS JAVA_MEM_TOTAL x
* STATUS JAVA_MEM_FREE x
* STATUS NUM_CHECKPOINTS x
* STATUS NUM_STATE_CHANGES x
* STATUS NEXT_CHECKPOINT_SIZE_EST x
* STATUS STATE_HISTORY_SIZE_EST x
* STATUS DONE
Exception Messages:
Description:
The status command is used to report various internal values of the simulator. It also encourages the
JVM (Java Virtual Machine) to perform garbage collection. This is mostly for in-house debugging.
Command: STEP [n]
Alias: S
----------------------------------------------------------------------
Result:
* STEP BREAKPOINT index
* STEP GUARD index
* STEP EXCEPTION index
* STEP ERR ERR_CYCLE_ERROR
* STEP DONE
Exception Messages:
Unable to translate value of n specified.
Value of n must be larger than 0.
Description:
The STEP command instructs the simulator to perform n cycles. The default value for n is 1. The simulator
is responsible for detecting breakpoint and guard events. If a breakpoint or guard is encountered, the
STEP command will return the index of the matching breakpoint or guard expression. Exceptions can happen
for various reasons, and the client should examine the index of the exception result to determine how to
proceed. Refer to the exception documentation to see the meaning of different exception index values.
An ERR_CYCLE_ERROR can mean some internal error, such as null pointer or index out of bounds, or an out of
memory condition.
Command: UNDO [n]
Alias: U
----------------------------------------------------------------------
Result:
* UNDO OK
* UNDO OUTPUT
* UNDO EXCEPTION index
* UNDO ERR ERR_NO_STATE_CHANGE
* UNDO ERR ERR_CRITICAL_ERROR index
* UNDO DONE
Exception Messages:
Unable to translate value of n specified.
Value of n must be larger than 0.
Description:
This command uses the undo buffer to undo the state changes from a previous STEP command. The default
value for n is 1. If n is larger than the number of cycles currently executed, then eventually a
ERR_NO_STATE_CHANGE response will be sent. An ERR_CRITICAL_ERROR response usually means an internal error,
or out of memory. The index value only has internal meaning and need not be reported.
Command: HISTORY (C* | V* | W*)
Alias:
----------------------------------------------------------------------
Result:
* HISTORY OK
* HISTORY ERR ERR_NO_CLEAR
* HISTORY ERR ERR_HISTORY_LOG
* HISTORY ERR ERR_HISTORY_WRITE
* HISTORY DONE
Exception Messages:
You must specify CLEAR, VIEW, or WRITE.
Description:
The VIEW parameter is primarily only for debugging purposes. The CLEAR parameter, however, can be used
to conserve memory (by clearing the undo buffer). The WRITE command outputs the history log to a file
named _HISTORY in the same directory that the simulator is running in.
Command: INPUT "string"
Alias: IN
----------------------------------------------------------------------
Result:
* INPUT ERR ERR_NO_INPUT_EXPECTED
* INPUT ERR ERR_BAD_INPUT_FORMAT
* INPUT DONE
Exception Messages:
Invalid format of input or unexpected error.
Description:
This is used to send input into the simulator. Note that input can only be performed when the simulator
has requested it (via a syscall). If the simulator has not requested any input, then the ERR_NO_INPUT_EXPECTED
error is returned in the result buffer. The format of the input will be translated appropriately, depending on
the syscall that was issued. If the input is expecting an integer and the string consists of letters, then
an ERR_BAD_INPUT_FORMAT response is returned.
The format of the input string is as follows: the string must be enclosed within double quotes. The string
may consists of standard C-style tokens: \n = new line, \\ = slash, \" = double quote, \r = carriage return,
\t = tab.
Command: OUTPUT
Alias: OUT
----------------------------------------------------------------------
Result:
* OUTPUT OK
* OUTPUT ERR ERR_NOTHING_TO_OUTPUT
* OUTPUT ERR ERR_CRITICAL
* OUTPUT DONE
Exception Messages:
Description:
A program may output by performing a SYSCALL with the proper variable set. When such output is sent, the
client must received this output before the program can proceed. The OUTPUT command is used to get output
from the simulator. If an OUTPUT OK response is received, then the output has been successful sent and the
simulator may continue executing the program. In order for the client to actually get the output content,
it should use the sbGetOutput() method of the CommandOutput instance (which returns a string buffer containing
the simulator output). To get the CommandOutput instance, you can use the getLastCommandResult() method of
the CommandProcessor just after issuing the OUTPUT command. If the OUTPUT command is issued when there is
no pending output available, then an ERR_NOTHING_TO_OUTPUT response is sent.