MegaDoom Add-On 3/MEGADOOM3.iso/editor/bnudm126/sersetup.txt

Text File | 1994-10-26 | 28KB | 690 lines

  │
 ││ 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 <number>" (where <number> 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 <command>" where '<command>' 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<len>[<data>]<NL>   Transmitted packet
          R<len>[<data>]<NL>   Received packet
          $<NL>                Transmit buffer dumped (full)
          #<NL>                Receive buffer dumped (overflow)

          <len> is the packet data length modulus 256
          <data> is the actual packet data, no conversion
          <NL> 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: [e-mail] (fastest)
            [e-mail]
            [e-mail]
   FidoNet: david nugent 3:632/348 (3:50/0, 3:3/20)
  Data/BBS: [phone] (PEP)
            [phone] (V32b)
     Voice: [phone]

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
------- ----------- ----------------------------------------------