# Chapter 6 - Socket Interface

This chapter describes the socket interface supported by VirtualT. The Socekt Interface provides the capability of remote control of most of VirtualT's emulation functionality. The interface also adds low-level debug control of the emulation.

Home

## Invoking

To enable the socket interface, VirtualT must be invoked with a command-line option to specify the socket port as follows:

    virtualt -p port_number

    NOTE:  On Windows platforms, the Windows firewall sometimes blocks unkown ports and may
    need to be configured.  Sometimes simply envoking VirtualT with the '-p' option a second time
    will "open" the port.

This will cause VirtualT to launch a socket listener thread for remote control appliations. To connect to the socket interface using the vt_client application, from a command prompt perform the following:

    'cd' to the VirtualT directory
    type './vt_client port_number'

The vt_client application will connect to the socket interface of VirtualT and present a command-line interface for control. The socket interface can be used by any client to remotely control VirtualT, such as a Perl script, C++ test bench, or any other socket capable program. The vt_client application is just a simple command line example application.

## Protocol

The socket interface protocol is an ASCII based command / response type protocol. Commands must be sent as independant socket messages. Each command can have one or more arguments formatted appropriately per command. Commands are not terminated with a NEWLINE character. For each command, VirtualT will respond with one or more messages depending on the command. All responses will end with the ASCII text "Ok". Responses that report information will have one or more lines of data each followed with a NEWLINE (\n) character.

Here is an example transaction of the socket interface protocol:

       Client   sends "halt"
       VirtualT sends "Ok"
       Client   sends "pc"
       VirtualT sends "27105\n"
       VirtualT sends "Ok"
       Client   sends "radix 16"
       VirtualT sends "Ok"
       Client   sends "wr pc=0x69e2"
       VirtualT sends "Ok"
       Client   sends "run"
       VirtualT sends "Ok"

## Async Events

Occasionally VirtualT needs to send a message to the client to indicate an event has occurred. Reporting of asynchronous events follows a standard format so they can be parsed by the client application and properly separated from the expected response messages. The format for async event reporting is as follows:

       event, event_name, event_data \n

The async events reported by VirtualT 1.0 are:

       event, break, PC=address     Indicates a breakpoint was encountered
       event, lcdwrite, (r,c),data  Reports data written to the LCD at (r,c)

## Debugger

The socket interface works with the integrated debugger to provide remote debug control over the VirtualT emulation. Using this interface, the 8085 CPU can be halted, single stepped and resumed, breakpoints can be set and / or cleared, and all register and memory can be read and written.

The debugger allows breakpoints to be set for any memory address in the CPU's 64K address range. An unlimited number of breakpoints can be defined. Each breakpoint can be defined to cause a break in CPU execution depending on the active ROM and/or RAM bank of the emulation. Bank selection that should be monitored by the debugger is established during the set_break command.

Breakpoints can also be configured to monitor read and/or write access to specific addresses. To monitor an address for read or write operations, send a set_break command specifying the address with "read" and/or "write" parameters.

To perform debug operations, the integrated debugger must interogate the Program Counter (PC) before excution of every instruction to determine if an active breakpoint has been encountered. When a breakpoint is encountered, the debugger will halt the CPU execution and send an Async Event to the socket interface.

## LCD Monitor

The socket interface provides a feature to monitor data sent to the LCD. This feature was added to help accomodate automated regression testing of VirtualT features and applications developed using VirtualT as the development platform.

During LCD monitoring, the integrated debugger is used for monitoring program execution to trap function calls made to the "Character Level 6 Plotting" routine. When a call to this routine is detected, VirtualT extracts the plotted character and the curent row and column position. This data is then used to build strings of data representing the data written to the LCD.

The LCD monitoring feature can be turned on or off using the lcd_mon command. Sometimes during LCD monitoring, it is desireable to ignore portions of the LCD to eliminate excessive socket messages for data that is written repetitively, such as time and date updates on the MENU. To accomodate this, the user can define up to 10 "ignore regions" using the lcd_ignore command. During LCD monitoring, the socket interface will discard any write operations when the curent row and column are bounded by one of the ignore regions.

## Commands

VirtualT accepts commands on the socket interface to control emulation options, access low-level hardware resources, and interface with the VirtualT debugger. For commands that accept an address argument, addresses can be represented in decimal format or in hex format by pre-pending with the standard C "0x" syntax, such as 0xA31. Addresses can also be specified by one of the 16 bit registers (pc, sp, bc, de, hl). The commands that VirtualT supports are:

### Emulation Control Commands:

cold_boot, load, model, optrom, radix, reset, speed, status, terminate

### Hardware Control Commands:

flags, in, key, out, read_mem, read_reg, string, write_mem, write_reg a b c d e h l bc de hl pc sp

### Debug Commands:

clear_break, debug_isr, dis, halt, lcd_ignore, lcd_mon, list_break, run, set_break, step, step_over, x

### clear_break (cb)

    parameters:  "all", address, "pc", "sp", "bc", "de", "hl"

    returns:     Ok
                 Parameter Error

This command clears the breakpoint specified by the argument. If the argument is "all", then all breakpoints are cleared.

### cold_boot

    parameters:  none

    returns:     Ok

This command is used to cold boot the current emulation.

### debug_isr (isr)

    parameters:  ["on" "off"]

    returns:     Parameter error
                 Current ISR debug state
                 Ok

Sets the current state for debugging ISRs, or returns the current state if no parameter is supplied. Turning off debugging of ISR allows single stepping of assembly programs without the interruption of periodic interrupts from the system's RST 7.5 background ISR. When an interrupt is encountered during single stepping, the debugger will allow the ISR to run to completion before halting the processor, and the effect will appear to be a true single step operation.

### dis

    parameters:  [address [lineCount]]

    returns:     Parameter error
                 Disassembled lines of code
                 Ok

Dissasembles object code using VirtualT's disassembler function. Includes comments for the known addresses and variables. The starting address can be supplied or ommited to continue disassembly from the last disassembled address. If the address is supplied, then a line count can also be provided to specify the number of lines to disassemble.

### x

For disassembling at the current PC location, the shortcut comand "x" (for eXecution) is provided and is equivalent to "dis pc". The "x" command can have an optional line_count parameter to specifiy the number of lines to disassemble.

### flags

    parameters:  ["all", "s", "z", "c", "ac", "ts", "ov", "p"]
                 ["flag=1", "flag=0"]

    returns:     Parameter error
                 Current Flag status
                 Status of specified flags
                 Ok

Returns and/or sets specified flags. If no parameters are specified, then the command will return a space delimeited list of flags that are currently set. If one or more flag parameters are supplied, each parameter will be parsed and acted upon individually, and the response data will be ordered to match the parameter order. Multiple flags can be read or set in the same command. If the emulation is not halted, the value of each flag in a command my represent results from different CPU instructions.

### halt

    parameters:  none

    returns:     Ok

Halts exection of the 8085 CPU. If the CPU is already halted, this command has no effect.

### help

    parameters:  none

    returns:     Help information
                 Ok

Sends a formatted list of commands supported by the VirtualT socket interface. Each help command is sent as a separate socket message and the list is terminated with the "Ok" response.

### in

    parameters:  portNumber

    returns:     Parameter error
                 Port read value
                 Ok

Reads the value of the specified port and returns the value using the current selected radix.

### key

    parameters:  Keystroke list

    returns:     Parameter error
                 Ok

Simulates keystroke events on the keyboard. The keystroke list can be any length and can consist of quoted string and/or special key symbols as described below. The key stroke input will be timed and monitored based on emulation speed to validate proper scanning by the keyboard ISR. To specify the quote character as input in a quoted string, precede the quote with the '\' character. To specify the '\' character type '\\'.

    "  =  \"
    \  =  \\

Special key symbols are case insensitive. The special key symbols are:

enter, shift, code, graph, grph, esc, ctrl, tab, f1-f8, paste, label, print, pause, left, right, up, down, space, insert, ins, delete, del, bksp, back, backspace, home, end, pgup, pageup, pgdn, pagedown

Keystroke sequences can be specified using the "+" operator as shown below. Keys in a keystroke sequence will be pressed in a left-to-right order and depressed in a right-to-left order.

Examples

    key ctrl+c
    key graph+a
    key right enter "test.do" enter "This is data for \"TEXT\"" f8

### lcd_ignore (li)

    parameters:  ["none", (row,col)-(row,col)]

    returns:     Parameter error
                 List of active ignore regions
                 Ok

Specifies an ignore region on the LCD during LCD monitoring or returns a list of active ignore regions if no parameter is provided. If the parameter is "none", then all ignore regions are deleted. If a parameter is specified, it must follow the format "(row, col)-(row, col)". All row and col values are "1" based. Up to 10 ignore regions can be defined. During LCD monitoring, any data written to an ignore region will not be reported on the socket interface. This is useful when monitoring repetitive operations, such as time updates on the MENU, etc.

### lcd_mon (lm)

    parameters:  ["on", "off"]

    returns:     Parameter error
                 Current state of LCD monitoring
                 Ok

Turns LCD monitoring on, off or reports the current activation state if no parameter is provided. During LCD monitoring, any data written to the LCD that is not part of an lcd_ignore region will be reported on the socket interface using an async event. Data written to the LCD will be reported as strings as long as it is written to consecutive columns and the time between characters is less than .75 seconds.

Turning LCD monitoring on and off does not affect the ignore regions.

### list_break (lb)

    parameters:  none

    returns:     List of active breakpoints
                 Ok

Returns a list of the breakpoints the debugger is actively monitoring, one breakpoint per message. Each breakpoint is reported using the current radix in the following format:

    address: validRegions

The validRegions field of the reported breakpoints reports the bank or banks in which the breakpoint will be active. This field will contain one or more of the following:

    main mplan opt ram ram2 ram3 read write

### load

    parameters:  filename

    returns:     Load Error
                 Ok

Loads the specified file from the Host OS into the emulated model's "filesystem". The file is loaded relative to the VirtualT working directory. If the file cannot be loaded successfully, a "Load Error" message will be sent to the socket interface. As with any "Load from Host" operation, this will force a system reset after the load is complete.

### optrom

    parameters:  ["unload", filename]

    returns:     none
                 Current option ROM filename
                 Invalid hex file
                 File not found
                 Ok

If the comand is sent with no parameters, VirtualT returns the name of the currently loaded option ROM or "none" if no option ROM is loaded. If the parameter "unload" is sent, VirtualT will unload the option ROM. If a filename is provided, that file will be loaded into the Option ROM memory space, or an error will be returned if it cannot be loaded.

Unlike the menu item "Load / Unload option ROM", this command does not reset the CPU after loading or unloading a ROM.

### out

    parameters:  address, value

    returns:     Parameter error
                 Ok

Performs a CPU 'out' instruction to the specified port, writing the specified data. The out instruction is preformed asynchronously from the emulation.

### radix

    parameters:  "10", "16"

    returns:     Parameter error
                 Ok

Specifies the radix that should be used when reporting addresses and data to the socket interface. The radix parameter does not affect input data. Input data will be parsed a standard C regardless of the radix setting. The default radix is 10 (decimal).

### read_mem (rm)

    parameters:  address [count]

    returns:     Data in current radix
                 Parameter error
                 Ok

Reads data from the CPU's 64K memory space and sends it to the socket interface formatted using the current radix. If a count value is not specified, VirtualT returns a single byte of data. Otherwise it will return 'count' bytes separated by spaces. The data will be read from the CPU's memory space at the time the command is received. If an OptROM or ReMem memory is mapped into the CPU address being requested, then that memory will be read.

### read_reg (rr)

    parameters:  "all", "a", "b", "c", "d", "e", "h", "l", "m"
                 "bc", "de", "hl", "pc", "sp"

    returns:     Data in current radix
                 xx
                 Ok

Reads one or more CPU register(s) as specified and sends the results to the socket interface formatted using the current radix. The parameters are case insensitive and must be separated with spaces. If more than one input parameter is supplied, then the CPU values will be reported in the same order as the parameters, separated by spaces. If the parameter "all" is given, all CPU registers will be read and reported in the following format:

    A=## B=## C=## ...

As a shortcut, registers can also be read by sending a command with only the name of the register and no arguments. The register value will be returned, formatted using the current radix value.

This is a debug command and is intended to be used during a CPU halt condition. If multiple registers are requested while the CPU is running, no provisions are made to ensure the registers are sampled during the same CPU cycle.

Examples

    read_reg bc
    rr HL m a sp PC

### reset

    parameters:  none

    returns:     Ok

Performs an emulation system reset. Does not clear emulation memory.

### run

    parameters:  none

    returns:     Ok

Resumes the CPU exectuion after a halt command or a breakpoint. If the CPU is already running, this operation has no affect.

### set_break (sb)

    parameters:  address [validRegions]

    returns:     Parameter Error
                 Ok

Defines a new breakpoint for the integrated debugger. Breakpoints can be defined for any address and can be valid for selected banks as determined by the optional validRegions paramter. Additionally, breakpoints can be configured to halt CPU excution upon detection of a read and/or write to a specified address. Valid values for this parameter are:

    main opt mplan ram ram2 ram3 read write

If no parameter is supplied for validRegions, then VirtualT will default the selection to all banks that make sense for the specified address on the emulated model. There is currently no provisions for saving breakpoint information between successive VirtualT sessions.

### speed

    parameters:  "2.4", "friendly", "max"

    returns:     Parameter Error
                 Ok

Sets the emulation speed to the specified value. Note that only one option is given for the CPU Friendly speed but the Speed menu item provides two seletions. The friendly option in this command will set the speed to match the menu item "CPU Friendly".

### status

    parameters:  none

    returns:     Current model and CPU status
                 Ok

Returns the current model and CPU running status in the following format:

    Model=m100, CPU running
    Model=pc8201, CPU halted
    etc.

### step (s)

    parameters:  [count]

    returns:     Parameter Error
                 Ok

Causes the CPU to execute one or more instruction beginning at the current Program Counter (PC) location. If no parameter is provided, a single instruction is executed, otherwise 'count' instrutions will be executed.

### step_over (so)

    parameters:  [count]

    returns:     Parameter Error
                 Ok

Causes the CPU to step over any RST, CALL, CZ, CNZ, etc. instruction and return control at the next instruction. The subroutine which is the target of the RST, CALL, etc. will be executed entirely. This is accomplished by setting a temporary breakpoint at the instruction just after the RST, CALL, etc. and allowing the processor to run. If a breakpoint is encountered within the subroutine, running the processor 'run' will cause the program to continue to the intended location of the single step.

### string

    parameters:  address

    returns:     String data
                 Ok

Reads data from the CPU's 64K memory space beginning at the address specified and formats it as a NULL terminated string. Data that is not ASCII text will be formatted using the current radix value and enclosed with '<>' characters. The resulting string is written to the socket interface.

### terminate

    parameters:  none

    returns:     Ok

Terminates the VirtualT session and forces a clean shutdown (RAM and Preferences will be saved).

### write_mem (wm)

    parameters:  address data [data data ...]

    returns:     Ok

Writes data to the CPU's 64K memory space starting with the specified address. For Base Memory emulation, writes to the System ROM are allowed using this command. For ReMem memory emulation, write operations will be dictated by the READ_ONLY bit for the address block being written.

No provisions are made by this command to halt the CPU while writing multiple memory locations.

### write_reg (wr)

    parameters:  a=xx b=xx c=xx d=xx e=xx h=xx l=xx m=xx
                 bc=xx de=xx hl=xx sp=xx pc=xx

    returns:     Ok

Writes data to one or more CPU registers as specified by the parameters. Register write parameters must be separated by spaces and must follow the syntax shown. Input values will be parsed using standard C notation.

No provisions are made by this command to halt the CPU while writing multiple memory locations.