|
Virtual null-modem cable driver (COM2COM) v. 0.3 (19/11/2026, Martin Iturbide) |
Readme/What's new |
# COM2COM
Virtual null-modem cable for OS/2 / ArcaOS: a 16-bit character device driver that creates two serial ports, `COM3` and `COM4`, wired to each other. What a program writes to one port can be read from the other, so two serial programs (or a serial program and a test tool) can talk without hardware.
| | |
|---|---|
| **Status** | Partially working. Loads, and data goes both ways between COM3 and COM4 (smoke test passes). Not every serial IOCTL is implemented (see Known issues). |
| **Tested on** | ArcaOS 5.1.1 in VirtualBox (Dev VM), driver built with Open Watcom 2.0, 2026-11-18. Not tested on real hardware, not tested with real serial applications. |
| **License** | BSD 3-clause for the whole project (see [LICENSE](LICENSE)). The 2003 original code has no stated author; see the note in LICENSE and [doc/LICENSES.md](doc/LICENSES.md). |
| **Authors** | Original author not stated in the source (code dated 2003). Build update, clean-room replacements and tests for Open Watcom 2 / ArcaOS: 2026, Martin Iturbide (with Claude). |
| **Original source** | https://github.com/OS2World/DRV-SERIAL-COM2COM, state tagged `upstream-original` (two commits: "Initial commit", "2003-01-07"). |
| **Build tools** | Open Watcom 2.0 (`wcc`, `wpp`, `wasm`, `wlink`, `wmake`) and the OS/2 DDK headers (`base\h`, path set in `Makefile.wat`). Run `compile_wat.cmd` from the project root; `compile_wat.cmd clean` cleans. |
## Install
1. Copy `bin\com2com.sys` to a boot directory, for example `C:\OS2\BOOT\COM2COM.SYS`.
2. Add to `CONFIG.SYS` (back it up first):
```
DEVICE=C:\OS2\BOOT\COM2COM.SYS
```
The position does not matter much; any place with the other `DEVICE=` lines works.
3. Reboot. `COM3` and `COM4` now exist; make sure no real COM3/COM4 is in the machine or in use by another driver.
## Parameters
None. The driver prints nothing at boot (quiet by default, as in the driver guidelines). The `/V /Q /W /AA` options of the common driver scheme are not implemented because the driver has no boot messages.
## Using it
* Open `COM3` in one program and `COM4` in another (or the same one). Data written to COM3 is read from COM4, and the other way round. Each direction has an 8192-byte buffer.
* Baud rate and line settings (DCB) are stored and returned (set/get baud rate, extended baud rate, set/get DCB), but nothing is paced by them: transfers are as fast as the programs run.
* The device `COM2COM$` is a log device (built with `DEBUG_RAS`): reading it returns the driver's trace of requests. `sample\logout.cc` shows how to read it.
## Sample / test
* `sample\` : `testout.cc` (writes numbered lines to a file/port), `testin.cc` (reads a port and prints each byte), `logout.cc` (prints the `COM2COM$` log). Source only, not built by `compile_wat.cmd`.
* `test\longmath_test.c` : tests the 32-bit multiply/divide helpers (`test\build_longmath.cmd`, then `bin\lmtest.exe` prints PASS/FAIL).
* `test\smoke.c` : sends a string COM3 -> COM4 and COM4 -> COM3, reads the DCB through DosDevIOCtl, checks that a read blocked on COM4 is woken by a write to COM3, and prints `PASS`/`FAIL`. `test\build_smoke.cmd` builds `bin\smoke.exe`; `test\run_smoke.cmd` runs it and writes `bin\smoke.out`. Run it right after a boot with the driver loaded (it expects empty buffers).
## Link recipe (wlink)
```
format os2 dll initglobal
option nodefaultlibs
option quiet,map=bin\com2com.map
option description '@#OS2World:0.3#@Virtual null-modem COM port pair COM3-COM4 (COM2COM)'
file segments.obj, devtable.obj, init.obj, dispatch.obj, devhelp.obj, stdio.obj, stdlib.obj, string.obj,
resident.obj, CircularBuffer.obj, ComDevice.obj, longmath.obj
```
`segments.obj` must be first: it defines the segment order (header, data, end markers, code). C is compiled with `wcc -bt=os2 -bm -ms -6 -omi -s -zdp -zff -zgf -zu -zl -zp=1`, C++ with `wpp` and the same options, plus `-dDEBUG_BREAKPOINT -dDEBUG_RAS` as in the original build.
## Known issues
* Not implemented (return an error to the caller): modem control lines and status (`GETMODEMINPUT/OUTPUT`, `SETMODEMCTRL`), break, line control, queue counts, comm status/error/event, enhanced mode parms. Programs that need those may fail to open or configure the port.
* The port names are fixed: `COM3` and `COM4`.
* `logPrintf` keeps a 1 KB buffer on the stack of the driver and the log is always on (`DEBUG_RAS`); a release build might want it off.
* Only tested in a VM with the smoke test, not with real serial applications or on real hardware.
* The original 2003 author is unknown; the code is published under BSD 3-clause by the maintainer (see LICENSE and [doc/LICENSES.md](doc/LICENSES.md)).
## Links
* Original repository: https://github.com/OS2World/DRV-SERIAL-COM2COM
## Changelog
* 0.3 (2026-11-19): the five IBM DDK source kit files and the four Open Watcom run-time files and the DevHelp wrapper header replaced by clean-room BSD 3-clause code ([doc/CLEANROOM.md](doc/CLEANROOM.md)), LICENSE is now BSD 3-clause for those files. No functional change.
* 0.2 (2026-11-18): build with Open Watcom 2 (`Makefile.wat`, `compile_wat.cmd`), project layout standardized, BLDLEVEL signature, smoke test. No functional change to the driver. Details in [doc/CHANGES.md](doc/CHANGES.md).
* original (2003): source as published. |
Aggiungi un commento