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

# 12 Binary monitor

The binary remote monitor commands are sent over a dedicated connection, specified with the command line options `-binarymonitor` & `-binarymonitoraddress`. See section 5.17 Monitor settings. The remote monitor detects a binary command because it starts with ASCII STX (0x02). Note that there is no termination character. The command length acts as synchronisation point.

All multibyte values are in little endian order unless otherwise specified.

## 12.1 Command Structure

byte 0: 0x02 (STX)
byte 1: API version ID (currently 0x02)
  The API version identifies incompatible changes, such as modifying the header structure, or rearranging or changing the meaning of existing response fields. The API version does not need to be incremented for additional fields. If all the variable length fields are prefixed with their lengths then you should be able to add new ones to any response. The server can assume default values for older clients, and for newer clients with longer commands it should be able to ignore the extra fields safely.
byte 2-5: length
  Note that the command length does *not* count the STX, the command length, the command byte, or the request ID. Basically nothing in the header, just the body.
byte 6-9: request id
  In little endian order. All multibyte values are in little endian order, unless otherwise specified. There is no requirement for this to be unique, but it makes it easier to match up the responses if you do.
byte 10: The numeric command type
  See section 12.4 Commands.
byte 11+: The command body.
  See section 12.4 Commands.

## 12.2 Response Structure

byte 0: 0x02 (STX)
byte 1: API version ID (currently 0x02)
  The API version identifies incompatible changes, such as modifying the header structure, or rearranging or changing the meaning of existing response fields. The API version does not need to be incremented for additional fields. If all the variable length fields are prefixed with their lengths then you should be able to add new ones to any response. The client can assume default values for older versions of VICE, and for newer versions of VICE with longer responses it should be able to ignore the extra fields safely.
byte 2-5: response body length. Does not include any header fields
byte 6: response type
  This is usually the same as the command ID
byte 7: error code
  `0x00`
    OK, everything worked
  `0x01`
    The object you are trying to get or set doesn't exist.
  `0x02`
    The memspace is invalid
  `0x80`
    Command length is not correct for this command
  `0x81`
    An invalid parameter value was present
  `0x82`
    The API version is not understood by the server
  `0x83`
    The command type is not understood by the server
  `0x8f`
    The command had parameter values that passed basic checks, but a general failure occurred
    See section 12.4 Commands for other error codes
byte 8-11: request ID
  This is the request ID given to initiate this response. If the value is 0xffffffff, Then the response was initiated by an event, such as hitting a checkpoint.
byte 12+: response body.
  See section 12.4 Commands.

## 12.3 Example Exchange

1. Client connects to ip4://127.0.0.1:6502
2. Client sends a command to set a temporary checkpoint:
   `02 | 02 | 08 00 00 00 | ad de 34 12 | 12 | e2 fc | e3 fc | 01 | 01 | 04 | 01`
   `0x02`
     Begin command
   `0x02`
     API version 2
   `0x00000008`
     The command excluding the header is 8 bytes long.
   `0x1234dead`
     The request ID is 0x1234dead. The response will contain this ID.
   `0x12`
     See section 12.4.4 Checkpoint set (0x12).
   `0xfce2`
     The address range of the checkpoint starts at 0xfce2.
   `0xfce3`
     The address range of the checkpoint ends at 0xfce3.
   `0x01`
     The checkpoint will cause the emulator to stop.
   `0x01`
     The checkpoint is enabled.
   `0x04`
     The checkpoint will trigger on exec from 0xfce2 - 0xfce3.
   `0x01`
     The checkpoint is temporary.
3. The transmission of any command causes the emulator to stop, similar to the regular monitor. This causes the server to respond with a list of register values.
   `02 | 02 | 26 00 00 00 | 31 | 00 | ff ff ff ff | 09 00 [ 03 { 03 | cf e5 } 03 { 00 | 00 00 } ... ]`
   `0x02`
     Begin response
   `0x02`
     API Version 2
   `0x00000026`
     Response length is 38
   `0x31`
     See section 12.5.3 Register Response (0x31).
   `0x00`
     No error occurred
   `0xffffffff`
     This response was not directly triggered by a command from the client.
   `0x0009`
     The register array is 9 items long
   `PC:`
     `0x03`
       The register array item is 3 bytes long
     `0x03`
       The register is the PC (ID 3) Note: you should find the names to these IDs using the MON_CMD_REGISTERS_AVAILABLE command. See section 12.4.20 Registers available (0x83). Do not rely on them being consistent.
     `0xe5cf`
       The register value is 0xe5cf
   `A:`
     `0x03`
       The register array item is 3 bytes long
     `0x00`
       The register is A (ID 0) Note: you should find the names to these IDs using the MON_CMD_REGISTERS_AVAILABLE command. See section 12.4.20 Registers available (0x83). Do not rely on them being consistent.
     `0x0000`
       The register value is 0x0000
4. After the register information, the server sends a stopped event to indicate that the emulator is stopped.
   `02 | 02 | 02 00 00 00 | 62 | 00 | ff ff ff ff | cf e5`
   `0x02`
     Begin response
   `0x02`
     API Version 2
   `0x00000002`
     Response is two bytes long.
   `0x62`
     Response type is 0x62, MON_RESPONSE_STOPPED.
   `0xffffffff`
     This response was not directly triggered by a command from the client.
   `0xe5cf`
     The current program counter
5. The server processes the checkpoint set command, and sends a response to the client.
   `... | 11 | ... | 02 00 00 00 | 00 | e2 fc | e3 fc | 01 | 01 | 04 | 01 | 00 00 00 00 | 00 00 00 00 | 00`
   (Some response header fields are omitted (...) for brevity.)
   `0x11`
     See section 12.5.2 Checkpoint Response (0x11).
   `0x00000002`
     Checkpoint number is 2
   `0x00`
     Checkpoint was not hit (as it was just created)
   `0xfce2`
     Checkpoint start address
   `0xfce3`
     Checkpoint end address
   `0x01`
     The checkpoint will cause the emulator to stop.
   `0x01`
     The checkpoint is enabled.
   `0x04`
     The checkpoint will trigger on exec from 0xfce2 - 0xfce3.
   `0x01`
     The checkpoint is temporary.
   `0x00000000`
     The checkpoint has been hit zero times.
   `0x00000000`
     The checkpoint has been ignored zero times.
6. Client sends a command to continue:
   `... | aa`
   (Some command header fields are omitted (...) for brevity.)
   `0xaa`
     See section 12.4.26 Exit (0xaa).
7. Server acknowledges the command:
   `... | aa | ...`
   (Some response header fields are omitted (...) for brevity.)
   `0xaa`
     See section 12.4.26 Exit (0xaa).
8. Server resumes execution and sends a resume event:
   `... | 63 | ... | cf e5`
   (Some response header fields are omitted (...) for brevity.)
   `0x63`
     See section 12.5.6 Resumed Response (0x63).
   `0xe5cf`
     Program counter is currently at 0xe5cf
9. Some time later, the server hits the breakpoint. This causes it to emit a checkpoint response. This is identical to the previous checkpoint response, except that it is marked as "hit" and the hit and ignore counts are updated.
10. The server emits the register information and the stopped event when reentering the monitor, as seen previously.

## 12.4 Commands

These are the possible command types and responses, without the header portions mentioned above.

### 12.4.1 Memory get (0x01)

Reads a chunk of memory from a start address to an end address (inclusive).

Minimum VICE version: 3.5

Command body:

byte 0: side effects?
  Should the read cause side effects?
byte 1-2: start address
byte 3-4: end address
byte 5: memspace
  Describes which part of the computer you want to read:
  - 0x00: main memory
  - 0x01: drive 8
  - 0x02: drive 9
  - 0x03: drive 10
  - 0x04: drive 11
byte 6-7: bank ID
  Describes which bank you want. This is dependent on your machine. See section 12.4.19 Banks available (0x82). If the memspace selected doesn't support banks, this value is ignored.

Response type:

0x01: MON_RESPONSE_MEM_GET

Response body:

byte 0-1: The length of the memory segment. Will be zero for start 0x0000, end 0xffff.
byte 2+: The memory at the address.

### 12.4.2 Memory set (0x02)

Writes a chunk of memory from a start address to an end address (inclusive).

Minimum VICE version: 3.5

Command body:

byte 0: side effects?
  Should the write cause side effects?
byte 1-2: start address
byte 3-4: end address
byte 5: memspace
  Describes which part of the computer you want to write:
  - 0x00: main memory
  - 0x01: drive 8
  - 0x02: drive 9
  - 0x03: drive 10
  - 0x04: drive 11
byte 6-7: bank ID
  Describes which bank you want. This is dependent on your machine. See section 12.4.19 Banks available (0x82). If the memspace selected doesn't support banks, this byte is ignored.
byte 8+: Memory contents to write

Response type:

0x02: MON_RESPONSE_MEM_SET

Response body:

Currently empty.

### 12.4.3 Checkpoint get (0x11)

Gets any type of checkpoint. (break, watch, trace)

Minimum VICE version: 3.5

Command body:

byte 0-3: checkpoint number

See section 12.5.2 Checkpoint Response (0x11).

### 12.4.4 Checkpoint set (0x12)

Sets any type of checkpoint. This combines the functionality of several textual commands (break, watch, trace) into one, as they are all the same with only minor variations. To set conditions, see section 12.4.8 Condition set (0x22) after executing this one.

Command body:

byte 0-1: start address
byte 2-3: end address
byte 4: stop when hit
  >=0x01: true, 0x00: false
byte 5: enabled
  >=0x01: true, 0x00: false
byte 6: CPU operation
  >=0x01: load, 0x02: store, 0x04: exec
byte 7: temporary
  Deletes the checkpoint after it has been hit once. This is similar to "until" command, but it will not resume the emulator.
byte 8 (optional): memspace
  Describes which part of the computer to checkpoint:
  - 0x00: main memory
  - 0x01: drive 8
  - 0x02: drive 9
  - 0x03: drive 10
  - 0x04: drive 11

See section 12.5.2 Checkpoint Response (0x11).

### 12.4.5 Checkpoint delete (0x13)

Deletes any type of checkpoint. (break, watch, trace)

Minimum VICE version: 3.5

Command body:

byte 0-3: checkpoint number

Response type:

0x13: MON_RESPONSE_CHECKPOINT_DELETE

Response body:

Currently empty.

### 12.4.6 Checkpoint list (0x14)

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

Emits a series of MON_RESPONSE_CHECKPOINT_INFO responses (see section 12.5.2 Checkpoint Response (0x11)) followed by

0x14: MON_RESPONSE_CHECKPOINT_LIST

Response body:

byte 0-3: The total number of checkpoints

### 12.4.7 Checkpoint toggle (0x15)

Minimum VICE version: 3.5

Command body:

byte 0-3: Checkpoint number
byte 4: Enabled?
  0x00: disabled, 0x01: enabled

Response type:

0x15: MON_RESPONSE_CHECKPOINT_TOGGLE

Response body:

Currently empty.

### 12.4.8 Condition set (0x22)

Sets a condition on an existing checkpoint. It is not currently possible to retrieve conditions after setting them.

Minimum VICE version: 3.5

Command body:

byte 0-3: checkpoint number
byte 4: condition expression length
byte 5+: condition expression string
  This is the same format used on the command line. Not null terminated.

Response type:

0x22: MON_RESPONSE_CONDITION_SET

Response body:

Currently empty.

### 12.4.9 Registers get (0x31)

Get details about the registers

Minimum VICE version: 3.5

Command body:

byte 0: memspace
  Describes which part of the computer you want to read:
  - 0x00: main memory
  - 0x01: drive 8
  - 0x02: drive 9
  - 0x03: drive 10
  - 0x04: drive 11

See section 12.5.3 Register Response (0x31).

### 12.4.10 Registers set (0x32)

Set the register values

Minimum VICE version: 3.5

Command body:

byte 0: memspace
  Describes which part of the computer you want to write:
  - 0x00: main memory
  - 0x01: drive 8
  - 0x02: drive 9
  - 0x03: drive 10
  - 0x04: drive 11
byte 1-2: The count of the array items
byte 3+: An array with items of structure:
  byte 0: Size of the item, excluding this byte
  byte 1: ID of the register
  byte 2-3: register value

See section 12.5.3 Register Response (0x31).

### 12.4.11 Dump (0x41)

Saves the machine state to a file.

Minimum VICE version: 3.5

Command body:

byte 0: Save ROMs to snapshot file?
  >=0x01: true, 0x00: false
byte 1: Save disks to snapshot file?
  >=0x01: true, 0x00: false
byte 2: Length of filename
byte 3+: Filename
  The filename to save the snapshot to.

Response type:

0x41: MON_RESPONSE_DUMP

Response body:

Currently empty.

### 12.4.12 Undump (0x42)

Loads the machine state from a file.

Minimum VICE version: 3.5

Command body:

byte 0: Length of filename
byte 1+: Filename
  The filename to load the snapshot from.

Response type:

0x42: MON_RESPONSE_UNDUMP

Response body:

byte 0-1: The current program counter position

### 12.4.13 Resource Get (0x51)

Get a resource value from the emulator. See section 5.1 Format of resource files.

Minimum VICE version: 3.5

Command body:

byte 0: Length of resource name
byte 1+: Resource name

Response type:

0x51: MON_RESPONSE_RESOURCE_GET

Response body:

byte 0: Type of the resource
  0x00: String, 0x01: Integer
byte 1: Length of the value
byte 2+: The value

### 12.4.14 Resource Set (0x52)

Set a resource value in the emulator. See section 5.1 Format of resource files.

Minimum VICE version: 3.5

Command body:

1 byte: Type of the resource value
  0x00: String, 0x01: Integer
  Strings will be interpreted if the destination is an Integer.
1 byte: Resource name length = (&name)
(*name) bytes: The resource name
1 byte: Resource value length = (&value)
(*value) bytes: The resource value

Response type:

0x52: MON_RESPONSE_RESOURCE_SET

Response body:

Currently empty.

### 12.4.15 Advance Instructions (0x71)

Step over a certain number of instructions.

Minimum VICE version: 3.5

Command body:

byte 0: Step over subroutines?
  Should subroutines count as a single instruction?
byte 1-2: How many instructions to step over.

Response type:

0x71: MON_RESPONSE_ADVANCE_INSTRUCTIONS

Response body:

Currently empty.

### 12.4.16 Keyboard feed (0x72)

Add text to the keyboard buffer.

Minimum VICE version: 3.5

Minimum API version: 2

Command body:

byte 0: Length of text
byte 1+: The text, in PETSCII

Response type:

0x72: MON_RESPONSE_KEYBOARD_FEED

Response body:

Currently empty.

### 12.4.17 Execute until return (0x73)

Continues execution and returns to the monitor just after the next RTS or RTI is executed.

This command is the same as "return" in the text monitor.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0x73: MON_RESPONSE_EXECUTE_UNTIL_RETURN

Response body:

Currently empty.

### 12.4.18 Ping (0x81)

Get an empty response

Minimum VICE version: 3.5

Command body:

Always empty

Response type:

0x81: MON_RESPONSE_PING

Response body:

Always empty

### 12.4.19 Banks available (0x82)

Gives a listing of all the bank IDs for the running machine with their names.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0x82: MON_RESPONSE_BANKS_AVAILABLE

Response body:

byte 0-1: The count of the array items
byte 2+: An array with items of structure:
  byte 0: Size of the item, excluding this byte
  byte 1-2: bank ID
  byte 3: Name length
  byte 4+: Name

### 12.4.20 Registers available (0x83)

Gives a listing of all the registers for the running machine with their names.

Minimum VICE version: 3.5

Command body:

byte 0: memspace
  Describes which part of the computer you want to read:
  - 0x00: main memory
  - 0x01: drive 8
  - 0x02: drive 9
  - 0x03: drive 10
  - 0x04: drive 11

Response type:

0x82: MON_RESPONSE_REGISTERS_AVAILABLE

Response body:

byte 0-1: The count of the array items
byte 2+: An array with items of structure:
  byte 0: Size of the item, excluding this byte
  byte 1: ID of the register
  byte 2: Size of the register in bits
  byte 3: Length of name
  byte 4+: Name

### 12.4.21 Display Get (0x84)

Gets the current screen in a requested bit format.

Minimum VICE version: 3.5

Minimum API version: 2

Command body:

byte 0: USE VIC-II?
  Must be included, but ignored for all but the C128. If true, (>=0x01) the screen returned will be from the VIC-II. If false (0x00), it will be from the VDC.
byte 1: Format
  0x00: Indexed, 8 bit

Response type:

0x84: MON_RESPONSE_DISPLAY_GET

Response body:

4 bytes: Length of the fields before the display buffer
2 bytes: Debug width of display buffer (uncropped)
  The largest width the screen gets.
2 bytes: Debug height of display buffer (uncropped)
  The largest height the screen gets.
2 bytes: X offset
  X offset to the inner part of the screen.
2 bytes: Y offset
  Y offset to the inner part of the screen.
2 bytes: Width of the inner part of the screen.
2 bytes: Height of the inner part of the screen.
1 byte: Bits per pixel of display buffer, 8
4 bytes: Length of display buffer = (&buffer)
(*buffer) bytes: Display buffer data

### 12.4.22 VICE info (0x85)

Get general information about VICE. Currently returns the versions.

Minimum VICE version: 3.6

Command body:

Always empty

Response type:

0x85: MON_RESPONSE_VICE_INFO

Response body:

1 byte: Length of main version = (&main)
(*main) bytes: Main version
  In linear format. For example 0x03, 0x05, 0x00, 0x00 for 3.5.0.0
1 byte: Length of SVN revision = (&rev)
(*rev) bytes: SVN revision
  In little endian format. Returns zero if it's not an SVN build.

### 12.4.23 Palette get (0x91)

Get the colors in the current palette

Minimum VICE version: 3.6

Command body:

byte 0: USE VIC-II?
  Must be included, but ignored for all but the C128. If true, (>=0x01) the screen returned will be from the VIC-II. If false (0x00), it will be from the VDC.

Response type:

0x91: MON_RESPONSE_PALETTE_GET

Response body:

byte 0-1: The number of palette items.
byte 2+: An array with items of structure:
  byte 0: Size of the item, excluding this byte
  byte 1: Red
  byte 2: Green
  byte 3: Blue

### 12.4.24 Joyport set (0xa2)

Set the simulated joyport value.

Minimum VICE version: 3.6

Command body:

byte 0-1: The port to set the value on
byte 2-3: The value to set

Response type:

0xa2: MON_RESPONSE_JOYPORT_SET

Response body:

Currently empty.

### 12.4.25 Userport set (0xb2)

Set the simulated userport value.

Minimum VICE version: 3.6

Command body:

byte 0-1: The value to set

Response type:

0xb2: MON_RESPONSE_USERPORT_SET

Response body:

Currently empty.

### 12.4.26 Exit (0xaa)

Exit the monitor until the next breakpoint.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0xaa: MON_RESPONSE_EXIT

Response body:

Currently empty.

### 12.4.27 Quit (0xbb)

Quits VICE.

Minimum VICE version: 3.5

Command body:

Currently empty.

Response type:

0xbb: MON_RESPONSE_QUIT

Response body:

Currently empty.

### 12.4.28 Reset (0xcc)

Reset the system or a drive

Minimum VICE version: 3.5

Command body:

byte 0: What to reset
  - 0x00: Reset system
  - 0x01: Power cycle system
  - 0x08 - 0x0b: Reset drives 8 - 11

Response type:

0xcc: MON_RESPONSE_RESET

Response body:

Currently empty.

### 12.4.29 Autostart / autoload (0xdd)

Load a program then return to the monitor

Minimum VICE version: 3.5

Command body:

byte 0: Run after loading?
  >=0x01: true, 0x00: false
byte 1-2: File index
  The index of the file to execute, if a disk image. 0x00 is the default value.
byte 3: Length of filename
byte 4+: Filename
  The filename to autoload.

Response type:

0xdd: MON_RESPONSE_AUTOSTART

Response body:

Currently empty.

## 12.5 Responses

These responses are generated by many different commands, or by certain events. Events are generated with a request ID of 0xffffffff, so that they can be easily distinguished from regular requests.

### 12.5.1 Invalid Response (0x00)

This response type is returned for errors.

Response type:

0x00: MON_RESPONSE_INVALID

Response body:

Usually empty

### 12.5.2 Checkpoint Response (0x11)

This response is generated by hitting a checkpoint, or by many of the checkpoint commands.

See section 12.4.3 Checkpoint get (0x11).

See section 12.4.4 Checkpoint set (0x12).

See section 12.4.6 Checkpoint list (0x14).

Response type:

0x11: MON_RESPONSE_CHECKPOINT_INFO

Response body:

byte 0-3: Checkpoint number
byte 4: Currently hit?
  >=0x01: true, 0x00: false
byte 5-6: start address
byte 7-8: end address
byte 9: stop when hit
  >=0x01: true, 0x00: false
byte 10: enabled
  >=0x01: true, 0x00: false
byte 11: CPU operation
  0x01: load, 0x02: store, 0x04: exec
byte 12: temporary
  Deletes the checkpoint after it has been hit once. This is similar to "until" command, but it will not resume the emulator.
byte 13-16: hit count
byte 17-20: ignore count
byte 21: Has condition?
  >=0x01: true, 0x00: false
byte 22: memspace
  - 0x00: main memory
  - 0x01: drive 8
  - 0x02: drive 9
  - 0x03: drive 10
  - 0x04: drive 11

### 12.5.3 Register Response (0x31)

Response type:

0x31: MON_RESPONSE_REGISTER_INFO

Response body:

byte 0-1: The count of the array items
byte 2+: An array with items of structure:
  byte 0: Size of the item, excluding this byte
  byte 1: ID of the register
  byte 2-3: register value

### 12.5.4 JAM Response (0x61)

When the CPU jams

Response type:

0x61: MON_RESPONSE_JAM

Response body:

byte 0-1: The current program counter position

### 12.5.5 Stopped Response (0x62)

When the machine stops for the monitor, either due to hitting a checkpoint or stepping.

Response type:

0x62: MON_RESPONSE_STOPPED

Response body:

byte 0-1: The current program counter position

### 12.5.6 Resumed Response (0x63)

When the machine resumes execution for any reason.

Response type:

0x63: MON_RESPONSE_RESUMED

Response body:

byte 0-1: The current program counter position

## 12.6 Example Projects

Here's a short list of some projects using the binary monitor interface:

C64 Studio | IDE for assembly and BASIC projects, geared toward game development.
https://github.com/GeorgRottensteiner/C64Studio
VICE Binary Monitor Bridge for .NET | A cross platform .NET 5 library that implements a bridge for communication with the VICE binary monitor.
https://github.com/MihaMarkic/vice-bridge-net
IceBro Lite | IceBro Lite is a source-level debugger with a graphical user interface (GUI).
https://github.com/Sakrac/IceBroLite
VS65 Debugger | Visual Studio Code extension to debug CC65 projects.
https://github.com/empathicqubit/vscode-cc65-debugger
VS64 | The VS64 extension makes it easy to build, debug, inspect and run C64 assembly code from Visual Studio Code.
https://github.com/rolandshacks/vs64

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