Go to the first, previous, next, last section, table of contents.

# 12 Monitor

The VICE emulator has a complete built-in monitor, which can be used to examine, disassemble and assemble machine language programs, as well as debug them through breakpoints. It can be activated by using "Activate monitor" from the menu. The monitor will either run in a seperate window, or in a terminal emulation program (such as `rxvt` or `xterm`) when "native monitor" has been enabled in the settings.

## 12.1 Terminology

``address_space'`
  This refers to the range of memory locations and a set of registers. This can be the addresses available to the computer's processor, the disk drive's processor or a specific memory configuration of one of the mentioned processors.
``bankname'`
  The CPU can only see 64KiB of memory at any one time, due to its 16 bit address bus. The C64 and other computers have more than this amount, and this is handled by banking: a memory address can have different contents, depending on the active memory bank. A bankname names a specific bank in the current address_space.
``register'`
  One of the following: program counter (PC), stack pointer (SP), accumulator (A), X register (X), or Y register (Y).
``address'`
  A specific memory location in the range $0000 to $FFFF.
``address_range'`
  Two addresses. If the second address is less than the first, the range is assumed to wraparound from $FFFF to $0000. Both addresses must be in the same address space.
``address_opt_range'`
  An address or an address range.
``radix_type'`
  Radix for the output, H for hex, D for decimal, O for octal, or B for binary.
``label'`
  `label` is the name of a label. It must start with a dot (".") in order for the monitor to recognize it as a label. Register names preceeded by a dot (for example `.PC`) are special labels that evaluate to value of the respective register at the time it is used, and thus can not be used as a regular label.
``prompt'`
  The prompt has the format (address space:current address).
``checkpoint'`
  The monitor has the ability to setup triggers that perform an action when a specified situation occurs. There are three types of checkpoints; breakpoints, tracepoints and watchpoints.
``breakpoint'`
  A breakpoint is triggered based on the program counter. When it is triggered, the monitor is entered.
``tracepoint'`
  Like breakpoints, a tracepoint is triggered based on the program counter. Instead of entering the monitor, the program counter is printed and execution continues.
``watchpoint'`
  Watchpoints are triggered by a read and/or write to an address. When a watchpoint is triggered, the monitor is entered.
``memmap'`
  The memmap keeps track of RAM/ROM/IO read/write/execute accesses. The feature must be enabled with "--enable-cpuhistory" configure option, as it might decrease performance notably on slower hardware. The option also enables CPU history.
``<...>'`
  A data type.
``*'`
  Zero or more occurrences.
``[...]'`
  An optional argument.

## 12.2 General commands

`help [<command>]`
  If no argument is given, prints out a list of all available commands. If an argument is given, prints out specific help for that command.
`print <expression>`
`p <expression>`
  Evaluate the specified expression and output the result.
`~ <number>`
  Display the specified number in decimal, hex, octal and binary.

## 12.3 Monitor state commands

`device [c:|8:|9:|10:|11:]`
`dev [c:|8:|9:|10:|11:]`
  Set the default address space to either the computer (`c:`) or the disk (`8:|9:|10:|11:`). Switches to computer when not given a device.
`sidefx [on|off|toggle]`
`sfx [on|off|toggle]`
  Control how monitor generated reads affect memory locations that have read side-effects, like CIA interrupt registers for example. If the argument is 'on' then reads may cause side-effects. If the argument is 'off' then reads don't cause side-effects. If the argument is 'toggle' then the current mode is switched. No argument displays the current state.
`log [on|off|toggle]`
  Control whether the monitor output is logged into a logfile. If the argument is 'on' then all output will be written into the logfile. If the argument is 'off' then no log is produced. If the argument is 'toggle' then the current mode is switched. No argument displays the current state.
`logname "<filename>"`
  Sets the filename of the logfile.
`exit`
`x`
  Leave the monitor and return to execution.
`quit`
`q`
  Exit the emulator immediately.
`radix [H|D|O|B]`
`rad [H|D|O|B]`
  Set the default radix to hex, decimal, octal, or binary. With no argument, the current radix is printed.

## 12.4 Machine state commands

`backtrace`
`bt`
  Print JSR call chain (most recent call first). Stack offset relative to SP+1 is printed in parentheses. This is a best guess only.
`bank [<bankname>]`
  Without a bankname, display all available banks for the current address_space. With a bankname given, switch to the specified bank. If a bank is not completely filled (ROM banks for example) normally the `ram` bank is used where the bank has holes. The `cpu` bank uses the bank currently used by the CPU.
`cpuhistory [<count>] [c:] [8:] [9:] [10:] [11:]`
`chis [<count>] [c:] [8:] [9:] [10:] [11:]`
  Show <count> last executed commands on up to five devices. If no devices are specified, then the default device is shown. VICE emulation runs each CPU for a variable number of cycles before switching between them. They will be synchronized when communication between them occurs. (disabled by default; configure with --enable-cpuhistory to enable)
`dump "<filename>"`
  Write a snapshot of the machine into the file specified. This snapshot is compatible with a snapshot written out by the UI. Note: No ROM images are included into the dump.
`goto <address>`
`g <address>`
  Change the PC to address and continue execution.
`io [<address>]`
  Display i/o registers. Invoking without an address shows a dump of the entire io range, if an address is given then details for the chip at the respective (base-)address are displayed (if available).
`next [<count>]`
`n [<count>]`
  Advance to the next instruction(s). COUNT allows stepping more than a single instruction at a time. Subroutines are treated as a single instruction ("step over").
`registers [<reg_name> = <number> [, <reg_name> = <number>]*]`
`r [<reg_name> = <number> [, <reg_name> = <number>]*]`
  Assign respective registers (use FL for status flags). With no parameters, display register values.
`reset [<type>]`
  Reset the machine or drive. `type`: 0 = reset, 1 = power cycle, 8-11 = drive.
`return`
`ret`
  Continues execution and returns to the monitor just after the next RTS or RTI is executed ("step out").
`step [<count>]`
`z [<count>]`
  Single step through instructions. An optional count allows stepping more than a single instruction at a time ("step into").
`stopwatch [reset]`
  Print the CPU cycle counter of the current device. 'reset' sets the counter to 0.
`undump "<filename>"`
  Read a snapshot of the machine from the file specified.
`warp [on|off|toggle]`
  Turn warp mode on or off. If the argument is 'toggle' then the current mode is toggled. When no argument is given the current mode is displayed.
`cartfreeze`
  Use cartridge freeze.
`cpu <type>`
  Specify the type of CPU currently used (6502/z80).
`export`
`exp`
  Print out list of attached expansion port devices.
`keybuf "<string>"`
  Put the specified string into the keyboard buffer. Note that you can specify specific keycodes by using C-style escaped hexcodes ("\x0a").

## 12.5 Memory commands

`compare <address_range> <address>`
`c <address_range> <address>`
  Compare memory from the source specified by the address range to the destination specified by the address. The regions may overlap. Any values that miscompare are displayed using the default displaytype.
`fill <address_range> <data_list>`
`f <address_range> <data_list>`
  Fill memory in the specified address range with the data in <data_list>. If the size of the address range is greater than the size of the data_list, the data_list is repeated.
`hunt <address_range> <data_list>`
`h <address_range> <data_list>`
  Hunt memory in the specified address range for the data in <data_list>. If the data is found, the starting address of the match is displayed. The entire range is searched for all possible matches. The data list may have `xx' as a wildcard.
`i <address_opt_range>`
  Display memory contents as PETSCII text.
`ii <address_opt_range>`
  Display memory contents as screen code text
`mem [<radix_type>] [<address_opt_range>]`
`m [<radix_type>] [<address_opt_range>]`
  Display the contents of memory. If no datatype is given, the default is used. If only one address is specified, the length of data displayed is based on the datatype. If no addresses are given, the 'dot' address is used.
`memmapshow [<mask>] [<address_opt_range>]`
`mmsh [<mask>] [<address_opt_range>]`
  Show the memmap. The mask can be specified to show only those locations with accesses of certain type(s). The mask is a number with the bits "ioRWXrwx", where RWX are for ROM and rwx for RAM. Optionally, an address range can be specified. (disabled by default; configure with --enable-cpuhistory to enable)
`memmapzap`
`mmzap`
  Clear the memmap. (disabled by default; configure with --enable-cpuhistory to enable)
`memmapsave "<filename>" <format>`
`mmsave "<filename>" <format>`
  Save the memmap as a picture. `format`: 0 = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF. (disabled by default; configure with --enable-cpuhistory to enable)
`memchar [<radix_type>] [<address_opt_range>]`
`mc [<radix_type>] [<address_opt_range>]`
  Display the contents of memory as character data. If only one address is specified, only one character is displayed. If no addresses are given, the "dot" address is used.
`memsprite [<radix_type>] [<address_opt_range>]`
`ms [<radix_type>] [<address_opt_range>]`
  Display the contents of memory as sprite data. If only one address is specified, only one sprite is displayed. If no addresses are given, the "dot" address is used.
`move <address_range> <address>`
`t <address_range> <address>`
  Move memory from the source specified by the address range to the destination specified by the address. The regions may overlap.
`screen`
`sc`
  Displays the contents of the screen.
`> [<address>] <data_list>`
  Write the specified data at `address`.

## 12.6 Assembly commands

`a <address> [ <instruction> [: <instruction>]* ]`
  Assemble instructions to the specified address. If only one instruction is specified, enter assembly mode (enter an empty line to exit assembly mode).
`disass [<address> [<address>]]`
`d [<address> [<address>]]`
  Disassemble instructions. If two addresses are specified, they are used as a start and end address. If only one is specified, it is treated as the start address and a default number of instructions are disassembled. If no addresses are specified, a default number of instructions are disassembled from the dot address.

## 12.7 Checkpoint commands

`break [load|store|exec] [address [address] [if <cond_expr>]]`
  This command allows setting a breakpoint or listing the current breakpoints. If no address is given, the currently valid checkpoints are printed. If an address is given, a breakpoint is set for that address and the breakpoint number is printed. The "load|store|exec" parameter can be either "load", "store" or "exec" (or any combination of these) to determine on which operation the monitor breaks. If not specified, the monitor breaks on "exec". A conditional expression can also be specified for the breakpoint. For more information on conditions, see the CONDITION command.
`enable <checknum>`
`disable <checknum>`
  Each checkpoint can be enabled or disabled. This command allows changing between these states.
`command <checknum> "<command>"`
  When checkpoint `checknum` is hit, the specified command is executed by the monitor. Note that the `x` command is not yet supported as a command argument.
`condition <checknum> if <cond_expr>`
`cond <checknum> if <cond_expr>`
  Each time the specified checkpoint is examined, the condition is evaluated. If it evalutes to true, the checkpoint is activated. Otherwise, it is ignored. If registers are specified in the expression, the values used are those at the time the checkpoint is examined, not when the condition is set. The condition can use registers (A, X, Y, PC, SP, FL and other cpu specific registers (see manual)) and compare them (==, !=, <, >, <=, >=) against other registers or constants. RL can be used to refer to the current rasterline, and CY refers to the current cycle in the line. Full expressions are also supported (+, -, *, /, &, |, &&, ||). This lets you for example check specific bits in the FL register using the bitwise boolean operators (& and |). Please note that currently expressions are evaluated strictly left to right, so use parentheses in complex expressions to indicate the desired evaluation order. Registers can be the registers of other devices; this is denoted by a memspace prefix (i.e., c:, 8:, 9:, 10:, 11:) Examples: A == $0, X == Y, 8:X == X You can also compare against the value of a memory location in a specific bank, i.e you can break only if the vic register $d020 is $f0. use the form @[bankname]:[$<address>] | [.label]. Note this is for the C: memspace only. Examples : if @io:$d020 == $f0, if @io:.vicBorder == $f0 As an extension as the previous case, you can also dereference an expression, using the form @[bankname]:(expression) . The parentheses around the expression distinguish it from the previous form. Example: break load 0 $ffff if @cpu:(pc - $1) == $37
`delete <checknum>`
`del <checknum>`
  Delete the specified checkpoint.
`ignore <checknum> [<count>]`
  Ignore a checkpoint after a given number of crossings. If no count is given, the default value is 1.
`trace [load|store|exec] [address [address] [if <cond_expr>]]`
`tr [load|store|exec] [address [address] [if <cond_expr>]]`
  This command is similar to the `break` command except that it operates on tracepoints. A tracepoint differs from a breakpoint by not stopping execution but simply printing the PC, giving the user an execution trace. The second optional address can be used to specify the end of an range of addresses to be traced. If no addresses are given, a list of all the checkpoints is printed. The "load|store|exec" parameter can be either "load", "store" or "exec" (or any combination of these) to determine which operation the monitor traces. If not specified, the monitor traces all operations. A conditional expression can also be specified for the tracepoint. For more information on conditions, see the CONDITION command.
`until [<address>]`
`un [<address>]`
  If no address is given, the currently valid breakpoints are printed. If an address is given, a temporary breakpoint is set for that address and the breakpoint number is printed. Control is returned to the emulator by this command. The breakpoint is deleted once it is hit.
`watch [load|store|exec] [address [address] [if <cond_expr>]]`
`w [load|store|exec] [address [address] [if <cond_expr>]]`
  This command is similar to the `break` command except that it operates on watchpoints. A watchpoint differs from a breakpoint by stopping on a read and/or write to an address or range of addresses. If no addresses are given, a list of all the checkpoints is printed. The "load|store|exec" parameter can be either "load", "store" or "exec" (or any combination of these) to determine on which operation the monitor breaks. If not specified, the monitor breaks on "load" and "store" operations. A conditional expression can also be specified for the watchpoint. For more information on conditions, see the CONDITION command.
`dummy [on|off|toggle]`
  Control whether the checkpoints will trigger on dummy accesses. If the argument is 'on' then dummy accesses will cause checkpoints to trigger. If the argument is 'off' then dummy accesses will not trigger any checkpoints. If the argument is 'toggle' then the current mode is switched. No argument displays the current state.

## 12.8 File commands

`cd <directory>`
  Change the working directory.
`dir [<directory>]`
`ls [<directory>]`
  Display the directory contents.
`pwd`
  Show current working directory.
`mkdir <directory>`
  Create directory.
`rmdir <directory>`
  Remove directory.
`attach <filename> <device>`
  Attach file to device. (device 32 = cart)
`block_read <track> <sector> [<address>]`
`br <track> <sector> [<address>]`
  Read the block at the specified track and sector. If an address is specified, the data is loaded into memory. If no address is given, the data is displayed using the default datatype.
`block_write <track> <sector> <address>`
`bw <track> <sector> <address>`
  Write a block of data at `address` to the specified track and sector of disk in drive 8.
`detach <device>`
  Detach file from device. (device 32 = cart)
`@<disk command>`
  Perform a disk command on the currently attached disk image on virtual drive 8. Since the emulated drive is halted when the monitor is open, DOS commands can not be sent to the actual drive emulation and must be handled by the virtual drive implementation. As a consequence, all limitations of the virtual drives apply. Use the regular monitor commands to eg execute code in the drive.
`list [<directory>]`
  List disk contents.
`load "<filename>" <device> [<address>]`
`l "<filename>" <device> [<address>]`
  Load the specified file into memory. If no address is given, the file is loaded to the address specified by the first two bytes read from the file. If address is given, the file is loaded to the specified address and the first two bytes read from the file are skipped. If device is 0, the file is read from the file system.
`loadbasic "<filename>" <device> [<address>]`
`ldb "<filename>" <device> [<address>]`
  Load the specified file into memory and set BASIC pointers as if the file was loaded by the Kernal. If no address is given, the file is loaded to the address specified by the first two bytes read from the file. If address is given, the file is loaded to the specified address and the first two bytes read from the file are skipped. If device is 0, the file is read from the file system.
`bload "<filename>" <device> <address>`
`bl "<filename>" <device> <address>`
  Load the specified file into memory at the specified address. If device is 0, the file is read from the file system.
`save "<filename>" <device> <address1> <address2>`
`s "<filename>" <device> <address1> <address2>`
  Save the memory from address1 to address2 to the specified file. Write two-byte load address. If device is 0, the file is written to the file system.
`bsave "<filename>" <device> <address1> <address2>`
`bs "<filename>" <device> <address1> <address2>`
  Save the memory from address1 to address2 to the specified file. If device is 0, the file is written to the file system.
`verify "<filename>" <device> [<address>]`
`v "<filename>" <device> [<address>]`
  Compare the specified file with memory. If no address is given, the address is specified by the first two bytes read from the file. If address is given, the specified address is used and the first two bytes read from the file are skipped. If device is 0, the file is read from the file system.
`bverify "<filename>" <device> <address>`
`bv "<filename>" <device> <address>`
  Compare the specified file with memory at the specified address. If device is 0, the file is read from the file system.
`tapectrl <command>`
  Control the datasette. `command`: 0 = stop, 1 = start, 2 = forward, 3 = rewind, 4 = record, 5 = reset, 6 = reset counter.
`tapeoffs <offset>`
  Set the attached .tap to the given `offset`. When no offset is given, show the current offset.
`screenshot "<filename>" [<format>]`
`scrsh "<filename>" [<format>]`
  Take a screenshot. `format`: default = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF.

## 12.9 Command file commands

`playback "<filename>"`
`pb "<filename>"`
  Monitor commands from the specified file are read and executed. This command stops at the end of file or when a STOP command is read.
`record "<filename>"`
`rec "<filename>"`
  After this command, all commands entered are written to the specified file until the STOP command is entered.
`stop`
  Stop recording commands. See `record`.
`; <text>`
  Add a comment to a file to be read by the monitor. For example:

      ; Set border and background to black
      > d020 00 00

## 12.10 Label commands

`add_label <address> <label>`
`al <address> <label>`
  Map a given address to a label. This label can be used when entering assembly code and is shown during disassembly. Additionally, it can be used whenever an address must be specified. <label> is the name of the label; it must start with a dot (".") in order for the monitor to recognize it as a label.
`delete_label [<address_space>] <label>`
`dl [<address_space>] <label>`
  Remove the specified label from the label tables. If no address space is checked, all tables are checked.
`load_labels [<address_space>] "<filename>"`
`ll [<address_space>] "<filename>"`
  Load a file containing a mapping of labels to addresses. If no address space is specified, the default readspace is used. The file must contain commands the monitor understands, e.g. add_label. The compiler cc65 can create such label files. Vice can also load label files created by the Acme assembler. Their syntax is e.g. "labelname = $1234 ; Maybe a comment". A dot will be added automatically to label names assigned in this way to fit to the Vice label syntax. Normally the semicolon seperates commands but after an assignment of this kind it may be used to start a comment to end of line, so unchanged Acme label files can be fed into Vice.
`save_labels [<address_space>] "<filename>"`
`sl [<address_space>] "<filename>"`
  Save labels to a file. If no address space is specified, all of the labels are saved.
`show_labels [<address_space>]`
`shl [<address_space>]`
  Display current label mappings. If no address space is specified, show all labels from default address space.
`clear_labels [<address_space>]`
`cl [<address_space>]`
  Clear current label mappings. If no address space is specified, clear all labels from default address space.

## 12.11 Profiling commands

Profiling commands are executed through the `profile` command (alt. abbreviated `prof`) followed by subcommand and arguments per below.

`profile on`
  Start profiling and flush old profiling data.
`profile off`
  Stop profiling.
`profile flat [<num=20>]`
  Show flat summary of `num` top functions sorted by self time.
`profile graph [<ctx>] [depth <d>]`
  Show callgraph up to `d` levels deep. If `ctx` is given, zoom on that subtree.
`profile func <function>`
  Show aggregate statistics for a function including callers and callees.
`profile disass <function>`
  Show per-instruction profiling for a given function.
`profile context <ctx>`
  Show detailed context information including per-instruction profiling for a function a call graph context.
`profile clear <function>`
  Clears all profiling stats for a function.

## 12.12 Resources commands

`resourceget "<resource>"`
`resget "<resource>"`
  Displays the value of the `resource`.
`resourceset "<resource>" "<value>"`
`resset "<resource>" "<value>"`
  Sets the value of the `resource`.
`load_resources "<file>"`
`resload "<file>"`
  Load resources from `file`.
`save_resources "<file>"`
`ressave "<file>"`
  Save resources to `file`.

Go to the first, previous, next, last section, table of contents.