BNU DOOM Serial driver version 1.2.6
DOOM Network interface is copyright 1994 by Id Software Inc.
BNU SIO Driver is copyright 1994 by David L Nugent
& Unique Computing P/L


BNU for DOOM is a drop-in replacement for Id Software's
SERSETUP.EXE provided with DOOM 1.2. This version, however,
provides a full and complete interrupt driven serial driver
implementation and therefore does not suffer many of the
shortcomings in Id's original driver which was much too
simplistic to provide the services necessary for running on
today's typical modem configurations or at faster speeds
than 9600 baud.

This work is a derivative and blending of Id's published
source for SERSETUP and my own BNU FOSSIL driver plus some
useful enhancements to the original dialer. This driver
provides full support for the 8250 family of UARTs, including
the 8250, 16450, 16550 (original, used in older PS/2's),
16550A(FN), 16551-4 (CMOS and packaged versions of the 16550)
Intel 82510 and the TYPE3. It provides hardware flow control,
the ability to run at *any* baud rate supported by the UART,
configurable inbound/outbound buffer sizes.

Before you ask, BNU is an acronym for Basic Networking
Utility, referring to its use in the FidoNet community as
the base level of communications. FOSSIL in this context
means "Fido Opus SEAdog Standard Interface Layer", which is
a phrase used to describe the set of common interrupt
functions developed as a common layer for many FidoNet
applications. SIO (which you'll see in SERSETUP's banner)
means "serial input/output".

This driver does not use FOSSIL services, so you need not
install one nor need to even know what one is.


INSTALLATION

This driver is almost a drop-in replacement for Id's
original. First, rename Id's version to "SERSETUP.OLD" and
copy in SERSETUP.EXE from this archive into your DOOM
directory.

If you have used your modem to call other DOOM players and
have an init string that works, then all the rules have
just changed - you will almost certainly have to change your
initialisation string from the one you used with Id's
SERSETUP.

Specifically, you'll need to:

- Enable V42bis (if available)
- Enable error correction (optional)
- ENABLE HARDWARE FLOW CONTROL
(ALSO REFERRED TO AS RTS/CTS HANDLING)

The latter is the most important if you intend to use an error
corrected link, the others optional. Error correction and
compression are transparent to the data stream. BNU automatically
provides CTS/RTS signal handling to take care of the "spurts" of
data it receives as a result of the protocol used between the
modems. If you only have MNP5 compression, try it since it may
work fine - disable it if play becomes too jerky. Compression is
likely to slow down the game and make it less responsive, but
implementations vary so trying it won't hurt.

- You need 9600 baud or greater!

Don't consider attempting to run DOOM at any lesser speed -
it just doesn't work. You'll get a connect, but movement is
so slow that it is entirely unplayable. At 4800 baud it's
like molasses at 50 fathoms! At 2400, it's like attempting
to play DOOM inside a Jupiter Mining Corps' stasis booth -
i.e. pretty much a waste of time. Try it on a direct connect
if you like, it is amusing, but don't donate money to your
PTT provider trying it out if you only have 2400 baud modems
or less. At 7200 you might get a slow moving game going, but
9600 is really where it becomes playable. In fact, if you
have a 16450 and/or a slower 386, you may find that 9600
provides the most playable game (it is, after all, the speed
for which the networking interface was developed by Id).

- If you use error correction and/or compression, use a baud
rate greater than the actual connect speed.

For V32 modems, use 19200 (more probably won't be an
advantage and makes your system work harder - sometimes
causing jerky play). V32b modems should use 38400 or 19200.
This driver *may* work with the HST protocols (but probably
not brilliantly) and will certainly do just fine with ZYXEL
16.8K and 19.2K. VFC and V34 modems will probably need the
port set at 38400 or 57600 (incidentally, if anyone has parallel
port specs for use with these modems, or knows where these can
be obtained, please let me know at the Email address noted
at the end of this document).

MODEM.CFG has some additional (optional) lines which you can use:

Line 1: Modem init string (+)
Line 2: Modem hang up string (+)
Line 3: Default baud rate (if not specified, 9600 is used)
Line 4: Receive buffer size (defaults to 2048 bytes)
Line 5: Transmit buffer size (defaults to receive buffer size)

+ Also present in Id's SERSETUP

Anything after the fifth line is ignored. Note that to make your
existing MODEM.CFG compatible with this driver, it is advisable
to either complete the above values or add empty lines for the
additional fields as numbers starting on the additional lines may
cause spurious options to be set.

As far as possible, this rework of SERSETUP is compatible with
DOOM's SETUP.EXE. In fact, with the addition of configurable port
settings via the environment (see below 'nonstandard settings')
this version should be more compatible than the original, allowing
SETUP to be used with non-standard port configurations.


SERIAL CONNECTIONS

SERSETUP's dialer has been reworked into something that may work
a little more intelligently than the original. Specifically, it
supports these types of connections:

- Direct connection (no modem)

Run SERSETUP with none of the following present on the command
line: -modem, -voice, -dial, -answer
In the absence of these options, direct connect is the default.

- Dialup and answer via modem (answer mode, dial mode)

One end uses "-dial " (where is replaced by the
telephone number to dial), and the other and uses "-answer".
The dialing end's modem will call out to the other, and the
answering end attempts to pick up the phone line and establish
carrier when it sees "RING".

- Connection via an existing modem <-> modem connection

This is similar to the direct connect. However, if you use the
-modem switch, you may optionally hang up the telephone line
on completion of the game.

- Switching voice -> data prior and data -> voice after play

This avoids making unnecessary calls by allowing easy switching
between voice and data.

As with dialup, this requires an originating (dialing) end
and an answering end, the difference between them being that
some parts of establishing the connection aren't present.
The originating system is told to 'pick up' the line immediately
and the answering end told to issue connection tones without
waiting for RING.

At the originating end, use "-voice D" on the command line to
force originate mode. Your modem may offer other parameters
which do the same thing, perhaps a little better. In that case,
use "-voice " where '' is the recommended
string to place the modem into originate mode.

At the answering end, use "-answer -noinit", which skips the
modem initialisation and sends the command "ATA" (answer call)
to the modem immediately without waiting for RING.

All responses now have time-outs, and redial is automatic should the
number called result in "BUSY" or "NO CARRIER". SERSETUP also
understands response strings such as "VOICE" and "NO DIAL TONE",
failing the call should they be detected and exiting cleanly.

Note that hanging up after a call is now optional. The default (by
hitting ENTER at the prompt presented at the time) is to hang up.


NONSTANDARD SETTINGS

DOOM 1.2's SETUP.EXE did not allow any but the standard port (1-4)
selections. This means that those use run their modem on other
serial ports, or ports configured slightly differently than standard
had to either change these to the standard settings or use SERSETUP
from the command line. The original SERSETUP did attempt to provide
a way to use non-standard configurations; however, the code to support
this was buggy - almost definitely never tested.

SERSETUP allows for this by allowing you to 'redefine' serial ports
using an environment variable.

SET COM1=3F8,4 Redefines COM1 to the default settings (there is
no reason to do this except as an example).

SET COM3=2E8,5 Redefines COM3 to port 0x2E8 on IRQ 5.

COM1 through COM4 are supported. After setting the environment
variable, simply use -com? (where ? is the port number) on the
command line and SERSETUP will obtain it's settings from your DOS
environment. This means also that selecting the corresponding port
from DOOM 1.2's SETUP will work.



COMMAND LINE REFERENCE

This is the complete list of command line switches that SERSETUP
supports. These options may be given on the command line or specified
in the "SERSETUP" environment variable. The latter way of setting
options is very useful if you want to specify options other than those
supported by Id's SETUP.EXE, or simply to set permanant options from
your AUTOEXEC.BAT or other batch files where SERSETUP is always used
connect in a particular configuration. Where the command line is in
comflict with the environment variable, the command line takes
precedence.

-com1, -com2, -com3, -com4

Selects the communications port in a standard
configuration applicable to your machine. (+)

-port 0x????

Overrides the port address. This must be in the
format "0x????" where ???? is the port address in
hexadecimal. For example, the standard COM1 and
COM2 port addresses are 0x3F8 and 0x2F8
respectively. (+, but had a bug)

-irq n

Sets the IRQ number - this is the CPU interrupt
request line. Refer to your serial cards
documentation if you have an unusual port
configuration. Very often cards provide jumpers
which you can use to select the IRQ generated by
ports on the card. (+)

-vector 0xn

Sets the interrupt vector used to gate information between
DOOM and the serial driver to n, where n is a hexadecimal
number. Unless this is given, SERSETUP automatically searches
for an unused vector in the range 0x60 - 0x66.

-answer

Sets up SERSETUP in 'answer' mode. This
initialises the modem and waits for a call. (+)

-dial n

Causes SERSETUP to init the connected modem and
dial out to the other player. 'n' is the phone
number to dial (+).

Note that the -dial switch requires a number to call. If,
for whatever reason, you wish to dial an 'empty' number
(it issue ATDT to the modem), then use -dial "" (empty
quotes as a placeholder.

-modem

Assumes that a modem is in use. This automatically enables
hardware flow control (if you still need it disabled, disable
it using -noflow) and if carrier is detected on termination of
DOOM it also asks if you wish to hang up.

-voice n

Causes SERSETUP to skip initialisation and issue
ATn (where 'n' is supplied) to the modem immediately
and wait for carrier.

-noinit

Skips modem initialisation altogether. When used with
"-answer", SERSETUP will also skip waiting for a RING
before issuing ATA to answer the line. This is useful
when switching from voice to data to start playing
DOOM.

-baud n, -speed n

These are both the same thing. Sets the DTE
communications rate (the baud rate used between
your computer and the modem or your computer and
another computer to which it is connected). This
is NOT NECESSARILY THE SAME SPEED AS THE
CONNECTION SPEED BETWEEN YOUR MODEM AND YOUR
FELLOW DOOMER's MODEM!

-rx n

Sets the receive buffer size.

-tx n

Sets the transmit buffer size. The default I/O
buffer size is around 2K (2048 bytes) in both
directions. This is adequate at 9600. You may need
to increase this at higher connection speeds and
allow for smoother play, particularly if error
correction or compression are in use.

-rt n

Sets 16550/16550A/82510/TYPE3 receive trigger to
'n'. Valid values for the 16550x and TYPE3 are 1,
2, 4, 8 and 15. The 82510 supports 1 through 4. A
zero value sets the receive trigger to 1 unless
-rf 0 is used, in which case the FIFOs are
disabled (but why would anyone want to do that??!?
:-))

NOTE: the switch is RT (for Receive Trigger), not RF.

-tf n

Sets the transmitter FIFO usage
16550/16550A/82510/TYPE3. This should almost
always be 15 or 16, irrespective of the -rt
setting. If you have a Western Digital or Silicon
Logic 16550A then use "-tf 15". Setting both this
parameter and -rt to 0 will disable the UART's
built-in FIFO. This value can be set to any value
from 0 through 16 on 16550A or TYPE 3, 0 to 8 on a
16550, 0 to 4 on an Intel 82510.

NOTE: the switch is TF (for Transmit FIFO).

-noflow

Disables hardware flow control, which is by default ON
if you use any of the modem switches (-modem, -dial or
-answer) and OFF otherwise. If you have problems with
your modem due to a nonstandard or faulty cable, or your
modem does not support CTS/RTS (in which case, since it
must support 9600 or above baud rates to play DOOM it is
probably disabled - so enable it!), then -noflow can be
used to force hardware flow control NOT to be used.

-flow

Enables flow control. Since this version of SERSERTUP
disables hardware flow control by default on non-modem
connections, this switch is provided to enable it. Some
NULL MODEM cables do have the CTS and RTS lines crossed,
which makes it both possible and desirable to use hardware
flow control between the two machines.

More information about NULL MODEM cables which are
compatible with this driver and which allow use of hardware
flow control may be found in a separate section below.

-chat

Enables the chat function; this causes a system-to-system
chat function to be invoked both prior establishing the
protocol between the DOOM network engines and after the
game exits. This allows two gamers to remain on-line
and discuss subsequent games and the previous game without
having to hang up or switching the line to voice. This
facility is provided as a way of saving calls.

If you have an ANSI driver installed, the chat function
will detect this and add some colour to the exchange;
text typed in from the console will be in yellow, and
cyan from the remote.

The chat shell is terminated pressing ESC at either end.

-nohangup

When connected via modem, SERSETUP will prompt you and
ask you if you wish to hang up if carrier is still high
when DOOM exits. -nohangup bypasses this and causes the
line to be held open without hanging up, as a
convenience to allow multiple games.

The following options are really for 'hackers' only. They were
implemented for experimentation and their use may have
unpredictable or unexpected results.

-debug

Useful for debugging only. For hackers, this echoes
some additional information to the screen and dumps
all packets received and sent into a file "sersetup.deb"
in the current directory. This will probably slow
down gameplay considerably so it is not recommended.
Debug information dumped into the file is in one
of the following formats:

T[] Transmitted packet
R[] Received packet
$ Transmit buffer dumped (full)
# Receive buffer dumped (overflow)

is the packet data length modulus 256
is the actual packet data, no conversion
is a newline.

-extra

Sets the 'extratics' field in the communications header
to 1. This causes DOOM to "send a backup tick in every
packet". On some systems, using this reduces jerkiness
in modem play.

All parameters specified on SERSETUP's command line are passed
on to DOOM unmodified.

Note that where a value has been both specified in SERSETUP and
on the command line and the two are in conflict, the command line
will take preference. -port and -irq switches specified on the
command line override any -com? switch or any COM? environment
setting (the default being COM1 if no -com? switch is given).


RUNNING DOOM

The BNU version of SERSETUP is command line compatible with
the original SERSETUP command line, this one can also be run
from DOOM's setup program. This is probably both easiest and
best unless you need to fine tune things a little by
overriding FIFO settings. Since the default speed and buffer
sizes can be more permanently configured in MODEM.CFG, you
can simply insert these in there and use SETUP.



PLAYING SPEED

Baud rates used on remote (modem) connections is adequately
covered above. Game speed will be affected mostly by the
ability of the modems being used to transfer and pump data
at sufficient speed. Some of the following, however, may
apply to modem connections, but remember that on modem
connects, the limitation is the modem devices and the effective
transfer rate between them, not the 'baud rate' is a direct
machine-to-machine null modem connection.

WITH DIRECT CONNECTS - FASTER ISN'T NECESSARILY BETTER.
19200 is fairly good, 38400 equally as good as DOOM across
IPX using 8 bit ethernet, but above that you may have to
contend with performance problems due to overhead in
servicing interrupts. Since DOOM runs under DPMI, it has
to context switch (switch into V86 or real mode from native
386 protected mode) every time the serial port triggers an
interrupt, and faster speeds usually means that
interrupts come more frequently and closer together (I
hope to address at least some of this with a DPMI mode
serial interrupt handler in a future release of SERSETUP
which will provide enhanced performance when running DOOM
under a DPMI host).

If your baud rate is set to 38400 or greater and you are
using 16550AFN uarts (these speed would probably not be
usable without them!), the BNU SIO driver automatically
adjusts usage of the UART FIFO's to accommodate to 8x8
instead of the default at lower speeds of 16x14. If you know
what this means and you wish to try using more of the UART
FIFOs at the risk of some overhead which may slow play down,
use -tf 16 -rt 14 on the command line to override the FIFO
size. You'd probably have to be using a 486DX260 or
thereabouts to see an improvement though - more than likely
the effect will be the opposite.

The best results in the author's opinion for direct
connections are running at 38400 or 57600 baud using the
default 8x8 FIFO. This is very smooth, at least on a DOS
386DX40 connected to a 486DX33 OS/2 system and provides
even better playability than using the IPX driver.

It is not recommended that you use speeds in excess of 19200
with 16450 UARTs. You may find that play is best at 9600
since the number of errors due to missing characters will be
significantly reduced. 19200 should provide a reasonably
playable game on most 386's able to run DOOM smoothly.

I/O buffer sizes also have an effect on playing smoothness
at high speeds (ie. above 9600). The size of the serial I/O
buffers will effect how often communicated data is "thrown
away" and replaced with fresh data either before being sent
or after being received (if the receiving system is getting
behind the data stream). Smaller buffers will cause data to
be thrown away more frequently - this may actually improve
play, whereas large buffers may slow things down a lot,
depending on how well the computers are keeping up with the
data stream. In general, the slower the machine, the smaller
the receive buffers you should use. Conversely, the slower
the OTHER machine is, the smaller transmit buffer you should
use. The actual size is relative to the baud rate (direct
connections) or modem speeds (remote connections) being used.
If in doubt, experiment.

WARNING: Making transmit or receive buffers less than 512
bytes is not recommended. The default (2048) is about right
for most uses.



CABLING

Connecting two systems together directly to play DOOM requires
at least a 3 wire connection, the connection of which are:

Pins
DB9 DB25
--- ----
3 2 TX <-> RX
2 3 RX <-> TX
5 7 GND <-> GND

Wiring for DB25 <-> DB25 2-3, 3-2, 7-7
DB9 <-> DB9 2-3, 3-2, 5-5
DB25 <-> DB9 2-2, 3-3, 7-5
DB9 <-> DB25 2-2, 3-3, 5-7


This is about as basic a "NULL MODEM" connection that you can
get. Unfortunately, any additional lines wired for handshaking
and signalling is less than standard. Best results for hardware
flow control from PC to PC are:

Pins
DB9 DB25
--- ----
3 2 TX -> RX
2 3 RX <- TX
5 7 GND <-> GND
7 4 RTS -> CTS
8 5 CTS <- RTS

Wiring for DB25 <-> DB25 2-3, 3-2, 7-7, 4-5, 5-4
DB9 <-> DB9 2-3, 3-2, 5-5, 7-8, 8-7
DB25 <-> DB9 2-2, 3-3, 7-5, 4-8, 5-7
DB9 <-> DB25 2-2, 3-3, 5-7, 7-5, 8-4

Some additional wires may optionally be connected, but are
not used by SERSETUP.

For external modems, you should use the cable recommended for
use with the modem. These will usually be "straight through"
cables.



COMMAND LINE EXAMPLES

Obviously, the easiest way to use SERSETUP is to run it
indirectly from DOOM's SETUP program. However, for direct
connections and for voice <-> data switching, you may find it
more convenient to run it directly.

Scenario 1: Direct connect, simple (3 wire) null modem cable,
assuming 19200 baud, and standard COM2 on both machines.

#1: sersetup -baud 19200 -com2
#2: sersetup -baud 19200 -com2

Scenario 2: Direct connect, full null modem cable with
hardware handshaking support, 38400 baud:

#1: sersetup -baud 38400 -com2 -flow
#2: sersetup -baud 38400 -com2 -flow

Scenario 3: Connect via phone line using V32+ modems (including
hardware flow control and error correction), assuming that
MODEM.CFG has been set accordingly with init strings etc.

#1: sersetup -com1 -dial 1234567890
Alternative 1:
#2: sersetup -com2 -answer
Alternative 2:
#2: set SERSETUP=-com2
#2: sersetup -answer

Scenario 4: Similar to scenario 2, except that system 2 uses an
internal modem configured as COM3 (2E8) on IRQ 5.

#1: sersetup -com1 -dial 1234567890
Alternative 1:
#2: sersetup -com3 -irq 5 -answer
Alternative 2:
#2: sersetup -port 0x2e8 -irq 5 -answer
Alternative 3:
#2: set COM3=2E8,5
#2: sersetup -com3 -answer
Alternative 4:
#2: set SERSETUP=-port 0x2e8 -irq 5
#2 sersetup -answer

Scenario 5: Two DOOMers are conversing voice, both then switch
the line from voice to data, connecting their modem:

#1: sersetup -com1 -voice D
#2: sersetup -com3 -irq 5 -answer -noinit


PROBLEMS?

If you experience any problems whatsoever in using this
driver, feedback to the author is certainly appreciated!
While I can't hope to solve all your problems, provided that
it can be diagnosed (which depends on the information you
supply) many of them can be easily be fixed either by
changing setup or by using alternative configuration
parameters.

If you do have a problem report, please complete the form in
SERSETUP.FRM and send this back with your report. This
information contains the minimal set of data I usually need
to resolve problems without having to ask you lots more
questions about basics. Using the form will save us both
time.

If you have any comments or suggestions, words or praise or
feature requests, you can direct them to any of the Email
addresses below - we'll be appreciative of the feedback and
happy to look at anything which you may suggest. We are
particularly interested in hearing about configurations where
this driver did not work!


DOES THIS COST ANYTHING?

That's entirely up to you. This is not shareware, but
DONATEware - if you find it useful then you are more than
welcome to send a nominal sum of US$10 or equivalent to the
address below. Furthermore, if you haven't already done so,
REGISTER DOOM WITH ID! They deserve it for this awesome
creation; registering will encourage the development of this
type of game in the future, both from Id and others.

We also welcome any commercial enquiries regarding use and
licensing of the BNU SIO driver.

Postal address (aka: where to send the moola :-)):

PO Box 352
Doveton,
Victoria, 3177
Australia


CONTACTING THE AUTHOR

InterNet: [email protected] (fastest)
[email protected]
[email protected]
FidoNet: david nugent 3:632/348 (3:50/0, 3:3/20)
Data/BBS: +61-3-792-3507 (PEP)
+61-3-794-7949 (V32b)
Voice: +61-3-793-2728

The BNU SIO driver is an all-Australian product!

REVISION HISTORY
Reverse chronological order

Version Date Comments
------- ----------- ----------------------------------------------
1.2.6 28-Mar-1994

Fixes - Dropping DTR on exit was unconditional due
to complete UART state restoration when
SERSETUP exists: if DTR was not originally
set it would be dropped even if the user had
requested no hangup. The previously
undocumented (but implemented) "-nohangup"
switch should also now work as expected.
- Command line bug: DOOM wasn't seeing the
first switch given to SERSETUP.
Changes - Minor modifications made to the ISR to further
prevent generation of spurious THRE interrupts
on 16450/8250s.
- The -isr switch is no longer functional (nor
necessary - the code affected is now adaptive
and used whenever the driver detects that
interrupts have been 'missed').
- Cosmetic: the command line passed to DOOM is
now shown whether or not -debug is specified.

1.2.5 19-Mar-1994 Initial release
------- ----------- ----------------------------------------------