VMB Serial Device Specification

Serial Device Specification

Memory Layout

Byte | Mode | Name | Description
00 | R | EIn | read error indicator: 0x80
01-02 | R | - | zero
03 | R | CIn | read byte count
04-06 | R | - | zero
07 | R | DIn | read byte
08 | R | EOut | write error indicator: 0x80
09-0A | R | - | zero
0B | R | COut | write byte count
0C-0E | R | - | zero
0F | RW | DOut | write byte

Serial Operation

The program will contact the motherboard at [host:]port and register itself with the given address and interrupt. It will then connect to a serial port on the host computer and forward send and receive data between the host serial device and the virtual serial device.

The Serial Device can be used to connect a real serial device to the virtual bus or, using a (real or virtual) null-modem, it can be used to connect the host computer to the virtual bus, thus providing a serial connection between the host computer and the virtual computer. The tty (Unix) or the COM port (Windows) is configurable (see below). Under Unix, virtual null modems are called pseudo ttys and can be found in /dev/pty as pairs of master and slave devices that are connected pairwise. Under Windows, the program com0com (see com0com.sourceforge.net) can be used to create a virtual null-modem.

Input

At offset 0, the serial device will provide a read only octabyte in the following format:

EE00 00CC 0000 00DD

The EE byte signals errors. It will be 0x80 if an error occurred (making the octabyte negative) and 0x00 otherwise.

The CC byte contains a count of the characters read from the input since the last read operation. This should be 0 if no new character was received and 1 if one character was received. Any other value will indicate that characters were lost since the last read operation.

The DD byte contains the last character received. It is valid only if CC is not zero.

The full octabyte will be reset to zero after reading the DD byte.

Reading a CC byte equal to zero means there is no DD byte available. If the read interrupt is enabled, reading a zero CC value, will cause generation of a read interrupt as soon as CC becomes non zero. If the application does not read CC, there will be no read interrupts.

Especially when debugging such a serial device, it is often not possible to read data from the DD Byte fast enough. Then the CC count will increase past 1 and data is lost. Therefore the Input by default is bufferd. The device stores the next byte from the input stream in the DD byte only after the previous byte was read from DD. In buffered mode, the CC Counter will always be 0 or at most 1. Setting the unbuffered flag to true (on the commandline or under WIN32 in the Settings Dialog), the serial device will no longer buffer incomming data internaly.

Output

At offset 8, the serial device will provide a read/write octabyte in the following format:

EE00 00CC 0000 00DD

The EE byte signals errors. It will be 0x80 if an error occurred (making the octabyte negative) and 0x00 otherwise.

The CC byte contains a count of the characters written to DD since the last output from the serial device was completed. This should be 0 if DD is ready to receive a character or 1 if the (virtual) hardware is busy with writing the DD byte. Any other value will indicate that characters were lost since the last write operation.

The DD byte contains the last character written to DD. It is valid only if CC is non zero.

The full octabyte will be reset to zero after sending of the DD byte completes successfully.

Reading a CC byte equal to zero means you can write one byte to DD to send output. If the write interrupt is enabled, reading a non zero CC value, will cause generation of a write interrupt as soon as CC is returning to zero. If the application does not read CC, there will be no write interrupts.

To make the use of the device simple, by default it operates in buffered mode. In this mode a byte written to DD is send immediately to the output buffer. So reading the CC Byte will always return zero.

Serial Configuration

The serial device has the following configurable parameters:

host | localhost | the host where the bus is located
port | 9002 | the port where the bus is located
address | default | address where the resource is located
rinterrupt | default | read interrupt send by device
winterrupt | default | write interrupt send by device
rdisable | false | disable read interrupts
wdisable | false | disable write interrupts
buffered | false | buffer input data until it is read from EIn
serial |  | connect to the given serial device
x | 0 | the x position of the window
y | 0 | the y position of the window
minimized | false | start with a minimized window
debug | false | to generate debug output
debugmask | 0xFFF0 | set mask to hide debug output
verbose | false | make debugging verbose, sets debug mask to zero
define | not set | to define a name for conditionals
config | not set | filename for a configuration file
help | false | to print information
These an be set on the command line or in configuration file.