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.
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.
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"
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)
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.
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.
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:
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.
parameters: none returns: Ok
This command is used to cold boot the current emulation.
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.
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.
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.
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.
parameters: none returns: Ok
Halts exection of the 8085 CPU. If the CPU is already halted, this command has no effect.
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.
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.
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
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.
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.
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: validRegionsThe 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
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.
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.
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.
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).
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.
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
parameters: none returns: Ok
Performs an emulation system reset. Does not clear emulation memory.
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.
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 writeIf 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.
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".
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.
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.
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.
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.
parameters: none returns: Ok
Terminates the VirtualT session and forces a clean shutdown (RAM and Preferences will be saved).
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.
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.