COM Port Exchanger

These two components allow the exchange of data between a physical COM port (i.e. RS-232 serial port) and a virtual UART in the simulated VMLAB environment. The components should work with a variety of serial devices: builtin RS-232 ports on the motherboard, USB to RS-232 dongles, and even virtual COM ports such as those created by the com0com loopback driver. The components are licensed under the GNU LGPL v2.1. They are based on the original source posted by AMTools in the VMLAB user forum, and which AMTools has agreed to release under an open source license.

Requirements: These components will only run using VMLAB.EXE version 3.15 or higher.

Regarding Parity: VMLAB's builtin TTY/TTY2 components as well as the UART in the AVR simulator actually implement parity incorrectly. To quote an AVR datasheet: "The parity bit is calculated by doing an exclusive-or of all the data bits. If odd parity is used, the result of the exclusive or is inverted." To keep the argument list of comxch/comxchx interchangable with the TTY/TTY2 components, the 4th argument is simply renamed to "EvenParity" in the usage statement below, indicating the correct interpretation of parity type.

Supported Features

  • Breakpoint the simulation on parity or framing errors received on the RX pin of the virtual UART.
  • Parity or framing errors received by the COM port are passed through onto the TX pin of the virtual UART.
  • Serial break conditions (i.e. a long logic 0) are passed through in both directions between the COM port and the virtual UART.
  • A warning is printed to the Messages window if a receiver overrun is detected on the COM port.

Downloads

  • comxch-1.0.zip - Contains the precompiled "comxch.dll" and "comxchx.dll" components. Check the included "README.txt" for additional instructions.
  • comxch-1.0-src.zip - Contains the common source code for both components, a BCC55 makefile, and compiling instructions.
  • comxch-1.0-test.zip - Contains two example projects: the "test-null.prj" creates a virtual null modem between two com0com ports, and the "test-tty.prj" provides a simple terminal emulator to any COM port on the system.

Usage

; To use either component, use one of the following component definition:
;
; X<Port> _comxch(<Baud> [<Data> <Parity> <EvenParity> <Stop>]) <TX> <RX>
;
; X<Port> _comxchx(<Baud> [<Data> <Parity> <EvenParity> <Stop>]) <TX> <RX>
; + <CTS> <DSR> <RI> <DCD> <RTS> <DTR> <OUT1> <OUT2>
;
; The instance name <Port> identifies which serial port to use. It would normally
; be of the form COM<N> such as "COM1" or "COM3", although it can also be a
; non-standard name like "CNCA0" if using the com0com null-modem emulator. Any
; data that arrives on the COM port will be transmitted via the <TX> pin of the
; comxch component, and any data received at the <RX> pin will be sent out through
; the same COM port. The arguments to the comxch or comxchx component are in the
; same order and format as VMLAB's builtin TTY component, and they specify the
; data format used by both the physical COM port and the <TX> and <RX> pair of
; pins:
;
; <Baud>       : Required argument; any positive integer is allowed although a
;                physical COM port will only support standard rates.
; <Data>       : Number of data bits; must be 7 or 8; default is 7
; <Parity>     : 0 for no parity, 1 to use parity; default is 0
; <EvenParity> : 1 for even parity, 0 for odd; default is 0; ignored if
;                <Parity> argument is 0
; <Stop>       : Number of stop bits; must be 1 or 2; default is 1
;
; The comxchx component provides additional pins to get and set all of the
; auxiliary modem control lines of the RS-232 port. A logic 1 on any of the
; auxiliary pins corresponds to an asserted signal on the COM port. (i.e. a
; SPACING condition or a positive voltage on a physical port).
;
; The <CTS>, <DSR>, <RI>, and <DCD> output pins respectively mirror the state of
; the Clear To Send, Data Set Ready, Ring Indicator, and Data Carrier Detect input
; signals on the COM port. The <RTS> and <DTR> input pins respectively control the
; state of the Request To Send and Data Terminal Ready output signals on the COM
; port. The <OUT1> and <OUT2> input pins are for use only with the com0com virtual
; loopback driver; they allow for controlling of the Ring Indicator and Data Carrier
; Detect signals at the opposite COM port in the loopback. See the "ReadMe.txt" for
; the com0com driver for instructions on how to configure the OUT1 and OUT2 signals.
;
; The comxch component uses automatic RTS hardware flow control for the COM port
; input, but no flow control for the COM port output. The comxchx component uses no
; flow control in either direction.

Example

XCOM1 _comxch(9600 8 0 0 1) tx rx
XCNCB0 _comxchx(9600 8 0 0 1) tx rx cts dsr ri dcd rts dtr out1 out2

Version History

  • v1.0 - 2009-01-27 - Detect COM port receiver overrun; added comxchx component
  • v0.3 - 2009-01-22 - Pass break/parity/framing errors from COM port to TX
  • v0.2 - 2009-01-18 - Better error reporting; detect break and framing errors on RX
  • v0.1 - 2008-12-25 - First working version released
  • v0.0 - 2006-02-09 - Original source posted by AMTools in VMLAB user forum