==================================
DOOM NETWORK TROUBLESHOOTING GUIDE
==================================

 AUTHOR: Murray Chapman
VERSION: 1.4
   DATE: 20th April, 1995


INTRODUCTION
------------

The purpose of this file is to help you diagnose problems when running DOOM
on a dedicated network.  Dedicated means that there is no network software
running, it is not connected to any other computers, and will be carrying
no traffic other than DOOM.

In other words, this file will help you if you have computers, ethernet cards,
and cable but don't know how to set it up.

I have no experience with Novell/LANtastic/TCP, etc, and hence can't help you.


DISCLAIMER
----------

I accept no responsibility for anything that might happen to you or your
computer.  I also make no guarantees about the correctness of this, or its
ability to produce anything that works at all.  You're on your own.


BACKGROUND
----------

DOOM requires an IPX network to run.  IPX is a very simple and very
popular protocol, so you shouldn't have compatibility problems with 99% of
network cards.

Definitions:

Node: A computer with a network card installed in it.

BNC: A type of cable and connector: cable is coaxial, often MIL-C-17D grade.
     The ends of the cable have connectors with collars which slide over
     the socket and are held on by pins on the socket when you rotate the
     collar.  Cost: a 20 metre cable, complete with all adapters, plugs,
     and terminators for a four-node system cost me about $US80.

Network Card: The card that slots into your computer.  It could be either
     8- or 16-bit.  It should have a round BNC socket on the back, and should
     be able to run IPX networks.  99% do.  Cost:  I picked up four second hand
     cards for about $US70 (that's less than $US18 each!)

Transceiver: A device which should be built into the network card.  It is
     the hardware that converts between the TTL logic levels used in your
     computer and the signal levels used on the cable.  If there is a round
     BNC socket on the back of your card, then you have an "internal
     tranceiver".

Packet Driver (PD): a small program, specific to your brand/model of network
     card.  It handles the raw interface to the hardware on your network
     card.  This packet driver provides a hardware-independant interface for
     software.

IPX driver: a small program which sits on top of a packet driver, which
    implements the IPX protocol.

Ethernet: A networking standard.  See:

    http://wwwhost.ots.utexas.edu/ethernet/ethernet-home.html

    for an extremely detailed breakdown.  You shouldn't need to know any of
    this for the purposes of setting up a DOOM network, though.



A GENERAL NOTE ABOUT DEBUGGING
------------------------------

Occam's razor: reduce a problem down to the smallest system that still exhibits
the erroneous behaviour.

If you are experiencing problems networking, it makes sense to minimise all
the sources of possible errors.  For example, don't try debugging a 4-player
game if you can't get a two player game going.  Strip your machine down
to bare minimum that you need to run DOOM: no TSRs, no HIMEM, remove the
sound card and drivers, EVERYTHING!  This can't be stressed enough.  Don't
assume that YOUR soundcard couldn't possibly be causing a problem!

If the problem disappears, then you know it was one of those components.  You
can then add them back one at a time to find the problem.

A fundamental problem is that there isn't much middle ground for testing a DOOM
network: you must have everything right to get it to work.  If even just one
thing is wrong, it won't work, and it won't give you a clue about where
to look.


A DOOM NETWORK
--------------

Here is a two-node DOOM network, from a hardware/software point of view:

              +---------------+                       +---------------+
              | DOOM -nodes 2 |                       | DOOM -nodes 2 |
              +---------------+                       +---------------+
              | DOOM launcher |                       | DOOM launcher |
   SOFTWARE   | ([IPX]SETUP)  |                       | ([IPX]SETUP)  |
              +---------------+                       +---------------+
              |  IPX driver   |                       |  IPX driver   |
              +---------------+                       +---------------+
              | Packet driver |                       | Packet driver |
<-------------+---------------+-----------------------+---------------+------->
              | Network Card  |                       | Network Card  |
   HARDWARE   +---------------+-----------------------+---------------+
              |         C O N N E C T O R S   &   C A B L E S         |
              +-------------------------------------------------------+

3 and 4 player systems are just an extension of this, shown below.

You need to construct this system from the bottom up, as each level of the
system requires the lower level be present in order to work.  (DOOM itself is
automatically run by IPXSETUP, which in turn can be launched from SETUP.)

Debug from the bottom up: make sure that each layer is working before you
attempt to install the next.

Note that you do *not* need LSL.COM.


HARDWARE SETUP
--------------

H0. Remove all unnecessary hardware.  This includes sound cards.  Don't forget
    to tell DOOM via SETUP that you no longer have a sound card.  This is
    important.

H1. Install the network cards in the computers.  Make sure all the jumpers on
    the network cards are set to either the defaults, or (if you are certain
    the default setting will cause a conflict) a known safe setting.  Make sure
    that you plug a 16-bit card into a 16-bit slot.  8-bit cards should work in
    16-bit slots.

H2. Connect your computers up as follows:


 Two Node setup:

        =TTT----------------TTT=
          T                  T
        NODE 1             NODE 2


 Three Node setup:

        =TTT----------------TTT----------------TTT=
          T                  T                  T
        NODE 1             NODE 2             NODE 3


 Four Node setup:

        =TTT----------------TTT----------------TTT----------------TTT=
          T                  T                  T                  T
        NODE 1             NODE 2             NODE 3             NODE 4

 Where:
  TTT is a BNC T-piece
   T

   - is 50 ohm ethernet cable (MIL-C-17D) cable with BNC plugs

   = are 50 ohm terminator plugs

  Please note that the terminator plugs are essential for correct functioning
  of the network.  Very important!  If for some strange reason you can't find
  terminator plugs, all you have to do is connect the two wires in the cable
  via a 50 ohm resistor.  The plugs are cheap, and make a nice clean job of
  it, so you shouldn't really have to do this.

  Total cable length should not exceed about 180 metres(!)  Any longer than
  that and you might suffer dropout or pick up too much RF interference.  The
  cleaner that you make the plug/wire connections, the more throughput you
  will get from your network.  Do a good job, so you won't have to worry about
  not wiggling the cable.


H3. Learn about your system.  Run MSD.EXE (Microsoft System Diagnostics),
    Norton Utilities, PC Tools, or any other program which will give you
    details about IRQ levels, shared memory, etc.  Also check all aspects of
    your CMOS.  Make sure that you note all addresses that are in use.


H4. If your network cards came with software diagnostics, run them.

   The diagnostics should be able to detect the presence of the cards in the
   system, and check their circuitry.  They will ask you for things such as
   IRQ level and DMA channels.  Make sure that the values you supply match
   any settings you made with jumpers during step H1.  Also make sure that
   they don't conflict with any other setting in your system.

   Remember that DOOM can only use sound cards on IRQ 5 or 7.  Consider keeping
   one of these is still free if you intend to run a sound card as well.  If
   you have problems, however, don't be afraid to try IRQ 5 or 7.

   The diagnostics might mention a "loopback plug".  This is merely:

                                =TTT=
                                  T
                                NODE

   but the networks illustrated in step H2 above provide the same functionality.

   You might be able to set up an "echo server".  Set up one node to be an
   echo server, then try running "echo client" on the others.  If none of them
   work, then it's probable that at least the node that has been set up to be
   the echo server is at fault.  If at least one client passes the test, then
   the server appears to be working.  The diagnostics should give you
   statistics about the success or otherwise of the test.

   If you have a node that works and one that doesn't, swap the network cards.
   If the problem follows the network card, then either the jumper settings
   are incorrectly set, or the card is at fault.  If the problem doesn't follow
   the card, then the problem is with that particular computer.

   For a each node that you suspect isn't working, redo steps H1 to H4.


H5. Once you have done all of this, you can assume the following:

    The cards are functioning correctly.  The cabling has been done correctly.
    The network is functioning correctly AT THE MOMENT.  There is no guarantee
    that it will work properly under DOOM.


PROBLEMS?

  If it doesn't work, then try all combinations of jumper settings, all
  card/PC combinations, and test your cables, plugs, and terminators with a
  multimeter.

  If you can't get it to work no matter what you try, then try setting up
  a null-modem game.  These are much easier to set up and run.  DOOM only
  requires three connections: pins 2, 3, and 7.  Make sure 2 and 3 swap over
  between computers.  If you can't get this to work, then I doubt that you
  would be able to get network DOOM to work.


SOFTWARE
--------

S0. Strip your AUTOEXEC.BAT and CONFIG.SYS down to the bare minimum needed
    to run DOOM.  This includes removing all sound-card drivers, all TSRs,
    HIMEM, SMARTDRIVE, mouse drivers, etc.

S1. Find a packet driver (PD) specific for your computer.  There are a whole
    suite of them available in:

        oak.oakland.edu:/SimTel/msdos/pktdrvr/pktd11.zip

    and associated SimTel mirror sites.

    Older versions of the file (OLDIPX.ZIP) are available at ftp.uwp.edu.
    If you get really stuck, try contacting the
    manufacturer (ftp.3com.com, for example).

S2. Install your packet driver.

    Run your packet driver without arguments for a brief description of how
    to do this.

    Typically, you have to give the packet driver parameters which tell it
    what hardware settings you have made.  For example, a 3com 503 card
    running on IRQ 5, interrupt 0x60, communicating via port 0x300 would be set
    up like this:


        C:\IPX>3c503 0x60 0x5 0x300
                (a)   (b)  (c) (d)

      (a) 3c503.com: a packet driver for the card, found in pktdrv11.zip
      (b) IO interrupt: 0x60 is standard, others are 0x62, 0x64, etc
      (c) IRQ level
      (d) IO port

    Your packet driver should report on whether the attempt was successful
    or not.  If you have run the wrong PD, it should report that it couldn't
    find the card.

    Note that some of these values will have to match the values set by the
    jumpers on the network card.  Make sure they match and don't conflict
    with any other settings in your system.  The 3c503 lets you set IO address
    and shared memory address via jumpers, but the IRQ level is software
    selectable.  pktdrv11.zip contains readme files which should help.

    If you can't get it to install, try changing the jumper settings on the
    card, and restart at step H1.


*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

  NOTE!

  AN INCORRECTLY INSTALLED PACKET DRIVER IS THE SOURCE OF MOST ERRORS.

  What does an incorrectly installed packet driver do?

     (a) reboots/crashes/locks your computer.
     (b) Erratic/unpredictable behaviour within two minutes
     (c) nothing immediate

  (a) is easy to detect, (b) can be detected by making sure that you can
      still get a directory, change dirs, run programs, etc.  I had a problem
      whereby the system would freeze after about 15 seconds.

  (c) is interesting.  It might have appeared to work, but if you get problems
      later you might have to come back here.  This is the most common place
      for errors.

  Don't assume that any two computers are the same.  There are *so* many
  things that can be different between computers/hardware.  Once you find
  a network card that works in a computer, KEEP IT THERE and make a little
  batch file that loads the packet driver and IPX layer upon boot.

  Once you install a PD, you might not be able to remove it or change the
  settings without rebooting your computer.  Be prepared to do this many
  times!

*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*



S3. Install the IPX driver:

        C:\IPX>IPXPD

    IPXPD.COM (or the newer PDIPX.COM) is in pdipx103.zip, which is either
    in the same directory that you found pktd11.zip in, or is often included
    itself in the pktd11.zip archie.  Some people have reported lockups at the
    "Looking for a node..." point with PDIPX.  Try IPXPD first, although it
    is sometimes not included in the pktd11.zip archive.

    IPXPD will look for your packet driver.  An optional parameter (in our
    example 0x60) tells it specifically where to look for the driver.  If you
    don't supply the parameter, it will search from 0x60 onwards.

    It shouldn't report an error.  If it reports an error or hangs, that means
    that it had a problem detecting your packet driver, so you should go back
    to step S2.

    Running MSD (or Norton Utilities) at this point should report that it
    detected a network.  Don't worry if some of the details look like rubbish,
    as long as it says "IPX DETECTED".


S4. Attempt to launch DOOM:

        C:\DOOM>IPXSETUP

    This is for a two node system.  Note that all nodes must be running the
    same version of DOOM, have the same DOOM.WAD, and IPXSETUP must be run on
    all nodes with the same parameters.  (There are exceptions to this: you can
    run different sound PWADs on different nodes.  Occam's razor implies that
    you shouldn't be doing this, however.)

    If everything is ok, it should say something like:

          Looking for a node....
          Found a node!.
          Communicating via .....

      ...and then launch DOOM.

    If it reports "IPX not detected", then step S3 didn't work,

    NOTE!
      In early versions of IPXSETUP, if you abort the connection attempt, or
      IPXSETUP reports "Illegal game packet encountered during setup", then
      IPXSETUP will exit, leaving the socket open.   If you try to run IPXSETUP
      again, it will say:

          Open socket: 0xff

      and you will have to reboot to close it.  Don't forget to reload your
      PD and IPXPD.  If DOOM terminates normally, IPXSETUP closes the socket
      correctly, and you can relaunch DOOM via IPXSETUP or SETUP.

      Later versions of IPXSETUP close the socket gracefully if you hit ESC,
      but if you CTRL-BREAK out, it will leave the socket open and you will
      have to reboot.


    If a node hangs on: "Looking for a node..........." (ad-infinitum)
    Then either the PD on at least one node didn't install correctly (go to
    step S2), or you have a problem with a cable.

    If a node hangs (ie does not print out dots approximately one per second),
    that means that the packet driver on the hung computer didn't install
    correctly.  Goto step S2.


    If you have problems even getting this far, then try using IPXFER
    (sendnet and recnet) from Jackson Software (shareware, available at most
    DOOM FTP sites.)  This software allows you to transfer files over an IPX
    network.  If you can't get this to work, then you have no chance of
    getting DOOM to work.  I have found that IPXFER version 0.99b works,
    but IPXFER 2.1 does not.


NOTE!

  An incorrectly installed packet driver often crashes when it *receives*
  a packet, rather than when it transmits one.  Your packet driver might look
  like it's installed ok, and you might be sitting there "Looking for a
  node......" for a while.  When another node replies to this (incorrectly
  installed) packet driver, it causes it to crash.  Be careful and mindful of
  what traffic there is or could be on the network at all times!

  This can be put to your advantage, though.  If you have a node that is
  *guaranteed* to be working fine and one that locks up when you install
  IPXPD, you can debug it thus:

  Set the good node "Looking for a node.....", and then install the packet
  driver on the suspect node.  If the suspect node then crashes/hangs at the
  same time that that good node prints another ".", then the packet driver
  you just installed wasn't installed correctly.  Reboot the faulty node and
  try different settings on the packet driver and/or card until the node
  no longer crashes in this manner.




FURTHER PROBLEMS
----------------

Consider what happens when you try to launch a game of network DOOM.  Each
node sends out small tentative messages over the network.  Once they have
agreed on who is which player, DOOM is launched.  Then what happens?
DOOM starts to run.  The video card gets thrashed.  The sound card gets
thrashed.  The keyboard/mouse gets thrashed.  In summary, your bus is carrying
a LOT of information.  DOOM pushes your system to the limit, and this could
be where problems surface.  It's like idling your car, then flooring the
accellerator: your fuel system might be able to supply enough fuel to idle,
but it might stall when you demand more from it.  Don't forget that your sound
card isn't active during the connect phase of IPXSETUP.

Once you see the "DOS4GW Protected Runtime System" message come up, you know
that DOOM considers that your network is capable of supporting the current
setup.  It *can* communicate correctly, given the right circumstances.  Write
down the IRQ, jumper, DMA, and port numbers for each node for future reference.

With all the problems below, try different combinations of nodes, different
number of nodes, different peripherals, different powers of computers.  Best
to try are two reasonably similar computers, with similar performance and
memory characteristics.  Try to work out exactly when the problem occurs.

If you have one node that crashes, the problem is almost certainly with that
node.  Take it offline, replace it with a different node, and see if the
problem repeats itself.

If your DOOM session hangs, then see which nodes will bring up the menu
(eventually) when you hit ESC. If a node can bring up the menu, then it
is probably working properly.  Look at nodes that can't bring up the menu.


SYMPTOM: DOOM hangs on "Listening for network start info"
 Cause: most likely a problem with another, slower computer.  This node is
        ready to go, and is awaiting another node.
   Fix: check other node(s).


SYMPTOM: DOOM hangs on a blank screen
 Cause: Protocol problem
   Fix: Wait.  If it doesn't continue, then whichever node was last to start
        is probably the culprit


SYMPTOM: DOOM runs extremely slowly.
 Cause: Too many monsters
   Fix: add "-nomonsters" to the IPXSETUP command on all nodes
   Fix: Make all nodes play on low detail mode.

 Cause: Too complex a level
   Fix: play a more simple level, such as "-episode 1 -map 8"
   Fix: Make all nodes play on low detail mode.

 Cause: Someone is in Map Mode
   Fix: Don't go into map mode!
   Fix: A later version of DOOM?

 Cause: A really slow computer
   Fix: Make sure that you don't play with a 386SX-16! :-)

 Cause: Cable too long
   Fix: Try a shorter cable.

 Cause: Protocol errors.  Doom automatically detects when there is a problem
        a transmission. It "drops" erroneous packets, and waits for others.
        This causes DOOM to slow down.
   Fix: Try to isolate the problem down to a particular node.  Reinstall
        everything on that node.


SYMPTOM: DOOM slows down slightly for a moment, then resumes normal speed.
  Cause: One node is struggling; either it is doing a lot of work, or is
         having problems with its card.
    Fix: More memory, faster computer, faster hard drive.


SYMPTOM: DOOM hangs suddenly, can't get the menu up on at least one node.
  Cause: That node has crashed.  The problem is probably with that node.
    Fix: Re-install system on that node, from step H0.


SYMPTOM: DOOM hangs suddenly, but you can get the menu up on all nodes.
  Cause: Someone kicked a cable out!
    Fix: Check the cabling!


SYMPTOM: DOOM slows down, then crashes on one particular node.
  Cause: A problem with the crashed node.
    Fix: Remove/replace that node, see if the problem re-occurs.


SYMPTOM: DOOM consistently crashes at a particular point
  Cause: A network card is clashing with another hardware device in a single
         node.
    Fix: Change the jumpers on the card or the software settings.  Go to step
         H3.


DEBUGGING EXAMPLES
------------------

(A)
Two 386DX-33s. One with a SB-16, the other with a SB-16-ASP.  Both sound cards
were set to IRQ 5, and both were trying to run network cards on IRQ 5 as well.
3com 503 ethernet cards.  DOOM 1.2.

Changed soundcard IRQ jumpers to 7, notified DOOM of this via SETUP, and it
worked fine.

(B)
A 386DX-33/8Mb/SB-16/Sound Canvas and a 486DX-33/16Mb/Sound Galaxy were
networked, and worked fine.  Both had 3com 503 network cards.  DOOM 1.2.

Added a 486DLC-40/8Mb with a 3com 503 network card.  DOOM started ok, but
crashed whenever we tried to move too far.

Took the 386 off line, to see if it was a problem with the DLC or with 3 nodes
in general.  The problem remained, therefore it was with the DLC.

Checked the CMOS on the DLC.  Becuase it had a hybrid chip, it had some extra
setting.  There was a setting for "Hard Disk type 47 area", which was 0x300,
the same as the port for the network card.  I changed a jumper on the network
card so that the card used 0x310.  When installing the PD, I made sure I
specified 0x310.

The problem remained.

I remembered that in order to get DOOM to run on the DLC in the first place,
we had to switch off some shadow RAM.  Thinking there might be a memory
conflict, I changed the "shared memory" jumper on the network card from "DC00"
to "DISABLE", left the port at 0x310, and ran it.  It worked.


(C)
A 386DX-33/8Mb/SB8 3com 503 network card.  Would connect ok, but send the
network start info, but would then hang on a black screen.  The problem was the
old 8-bit Sound Blaster, which would only use DMA channel 1.  The network card
was software selectable to DMA channel 3.  Unfortunately, this didn't work,
so we removed the sound card, and this solved the problems.  DOOM 1.2.

(D)
A 486SX-33/8Mb/PAS-16 3com 503.  Would say "listening for network start info",
then print a string of garbage, then quit back to DOS. Solution: Eliminated
things from CONFIG.SYS.  EMM was probably at fault here.  DOOM 1.2.

(E)
486DX-33/16Mb/SB-16 3com 503.  Would hang on "listening for network start info"
Tried everything, eventually discovered that when we swapped the network card
for a slightly different revision board, it worked fine.  The board at fault
worked perfectly in a different computer.  DOOM 1.2.


(F)
486DX2-66/8Mb/3c503.  Card worked when running software that came with
the card; verified, echo server test ok.  Packet driver / IPX layer would
install, and MSD would verify the existence of an IPX network.  DOOM
would hang after printing "Looking for a node."  Only one dot was printed,
no more.  The problem was fixed by setting the base address to 0x350
and the shared memory to C8000.  DOOM2 1.666.


Murray

-- Murray Chapman                               Zheenl Punczna            --
-- muzzle@cs.uq.oz.au                           zhmmyr@pf.hd.bm.nh        --
-- University of Queensland                     Havirefvgl bs Dhrrafynaq  --
-- Brisbane, Australia                          Oevfonar, Nhfgenyvn       --