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


13 Binary monitor

The binary remote monitor commands are sent over a dedicated connection, specified with the command line options -binarymonitor & -binarymonitoraddress. See section 6.15 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.

13.1 Command Structure

byte 0: 0x02 (STX)
byte 1: API version ID (currently 0x01)
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 13.4 Commands.
byte 11+: The command body.
See section 13.4 Commands.

13.2 Response Structure

byte 0: 0x02 (STX)
byte 1: API version ID (currently 0x01)
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
0x80
command length is not correct for this command
0x81
an invalid parameter occurred

See section 13.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 13.4 Commands.

13.3 Example Exchange

  1. Client connects to ip4://127.0.0.1:6502
  2. Client sends a command to set a temporary checkpoint:

    02 | 01 | 08 00 00 00 | ad de 34 12 | 12 | e2 fc | e3 fc | 01 | 01 | 04 | 01

    0x02
    Begin command
    0x01
    API version 1
    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 13.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 | 01 | 26 00 00 00 | 31 | 00 | ff ff ff ff | 09 00 [ 03 { 03 | cf e5 } 03 { 00 | 00 00 } ... ]

    0x02
    Begin response
    0x01
    API Version 1
    0x00000026
    Response length is 38
    0x31
    See section 13.5.1 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 13.4.16 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 13.4.16 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 | 01 | 02 00 00 00 | 62 | 00 | ff ff ff ff | cf e5

    0x02
    Begin response
    0x01
    API Version 1
    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 13.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 13.4.17 Exit (0xaa).
  7. Server acknowledges the command:

    ... | aa | ...
    (Some response header fields are omitted (...) for brevity.)

    0xaa
    See section 13.4.17 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 13.5.5 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.

13.4 Commands

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

13.4.1 Memory get (0x01)

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

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:
byte 6-7: bank ID
Describes which bank you want. This is dependent on your machine. See section 13.4.15 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.
byte 2+: The memory at the address.

13.4.2 Memory set (0x02)

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

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:
byte 6-7: bank ID
Describes which bank you want. This is dependent on your machine. See section 13.4.15 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.

13.4.3 Checkpoint get (0x11)

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

Command body:

byte 0-3: checkpoint number

See section 13.5.2 Checkpoint Response (0x11).

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

See section 13.5.2 Checkpoint Response (0x11).

13.4.5 Checkpoint delete (0x13)

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

Command body:

byte 0-3: checkpoint number

Response type:

0x13: MON_RESPONSE_CHECKPOINT_DELETE

Response body:

Currently empty.

13.4.6 Checkpoint list (0x14)

Command body:

Currently empty.

Response type:

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

0x14: MON_RESPONSE_CHECKPOINT_LIST

Response body:

byte 0-3: The total number of checkpoints

13.4.7 Checkpoint toggle (0x15)

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.

byte 0-3: The total number of checkpoints

13.4.8 Condition set (0x22)

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

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.

13.4.9 Registers get (0x31)

Get details about the registers

Command body:

Currently empty.

See section 13.5.1 Register Response (0x31).

13.4.10 Registers set (0x32)

Set the register values

Command 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

See section 13.5.1 Register Response (0x31).

13.4.11 Advance Instructions (0x71)

Step over a certain number of instructions.

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.

13.4.12 Keyboard feed (0x72)

Add text to the keyboard buffer.

Command body:

byte 0: Length of text
byte 1+: The text
Special characters such as return are escaped with backslashes.

Response type:

0x72: MON_RESPONSE_KEYBOARD_FEED

Response body:

Currently empty.

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

Command body:

Currently empty.

Response type:

0x73: MON_RESPONSE_EXECUTE_UNTIL_RETURN

Response body:

Currently empty.

13.4.14 Ping (0x81)

Get an empty response

Command body:

Always empty

Response type:

0x81: MON_RESPONSE_PING

Response body:

Always empty

13.4.15 Banks Available (0x82)

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

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

13.4.16 Registers Available (0x83)

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

Command body:

Currently empty.

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

13.4.17 Exit (0xaa)

Exit the monitor until the next breakpoint.

Command body:

Currently empty.

Response type:

0xaa: MON_RESPONSE_EXIT

Response body:

Currently empty.

13.4.18 Quit (0xbb)

Quits VICE.

Command body:

Currently empty.

Response type:

0xbb: MON_RESPONSE_QUIT

Response body:

Currently empty.

13.4.19 Reset (0xcc)

Reset the system or a drive

Command body:

byte 0: What to reset

Response type:

0xcc: MON_RESPONSE_RESET

Response body:

Currently empty.

13.4.20 Autostart / autoload (0xdd)

Load a program then return to the monitor

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.

13.5 Responses

13.5.1 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

13.5.2 Checkpoint Response (0x11)

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

13.5.3 JAM Response (0x61)

When the CPU jams

Response type:

0x61: MON_RESPONSE_JAM

Response body:

byte 0-1: The current program counter position

13.5.4 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

13.5.5 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


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