This file contains information about the XQ/SIM_ETHER package.

-------------------------------------------------------------------------------

BETA 5 Changes: (23-Oct-02)
 1. Added all_multicast and promiscuous mode support
 2. Finished DEQNA emulation
 3. Verified LAT functionality
 4. Added NXM (Non-eXistant Memory) protection (suggested by Robert Supnik)
 5. Added NetBSD support to Sim_Ether (courtesy of Jason Thorpe)
 6. Fixed write buffer overflow bug (discovered by Jason Thorpe)
 7. Fixed unattached device behavior (discovered by Patrick Caulfield)
 8. Extensive rewrite of this README
 9. Debugged sanity timer

-------------------------------------------------------------------------------

BETA 4 Changes: (16-Oct-02)
 1. Added stub support for all_multicast and promiscuous modes
 2. Integrated with SIMH v2.10-0b1
 3. Added VAX network bootstrap support
 4. Added SET/SHOW XQ TYPE and SANITY commands
 5. Added stub support for DEQNA mode

-------------------------------------------------------------------------------

BETA 3 Changes: (10-Oct-02)
 1. Fixed off-by-one bug in setup address processing
 2. Added rejection of multicast addresses to SET XQ MAC
 3. Added linux support to Sim_Ether (courtesy of Patrick Caulfield)

-------------------------------------------------------------------------------

BETA 2 Changes: (08-Oct-02)
 1. Integrated with SIMH v2.10-0p4
 2. Added floating vectors; this also fixes pdp11 emulation problem
 3. Cleaned up codebase; 100% of packet driver code moved to Sim_Ether
 4. Verified TCP/IP functionality
 5. Added Copyrights

-------------------------------------------------------------------------------

BETA 1 Changes: (03-Oct-02)
 1. Moved most of packet driver functionality from XQ to Sim_Ether
 2. Verified DECNET functionality
 3. Added SET/SHOW MAC command
 4. Added SHOW ETH command

-------------------------------------------------------------------------------

The XQ emulator is a host-independant software emulation of Digital's
DELQA (M7516) and DEQNA (M7504) Q-bus ethernet cards for the SIMH emulator.

See the last section of this document for XQ usage instructions.

The XQ emulator uses the Sim_Ether module to execute host-specific ethernet
packet reads and writes, since all operating systems talk to real ethernet
cards/controllers differently. The host-dependant Sim_Ether module currently
supports Windows, Linux, and NetBSD.

Currently, the Sim_Ether module sets the selected ethernet card into
promiscuous mode to gather all packets, then filters out the packets that it
doesn't want. This method is somewhat inefficient and will be looked at in
future versions. Packets having the same source MAC address as the
controller are ignored for WinPCAP compatibility (see Windows notes below).

If your ethernet card is plugged into a switch, the promiscuous mode setting
should not cause much of a problem, since the switch will still filter out
most of the undesirable traffic. You will only see "excessive" traffic if you
are on a hub(repeater) or a direct lan (thickwire/thinwire) segment.

-------------------------------------------------------------------------------

Windows notes:
 1. The Windows-specific code uses the WinPCAP 3.0 package from
    http://winpcap.polito.it. This package for windows simulates the libpcap
    package that is freely available for unix systems.
 2. You must *install* WinPCAP.
 3. Note that WinPCAP DOES NOT support dual CPU environments.
 4. WinPCAP loops packet writes back into the read queue. This causes problems
    since the XQ controller is not expecting to read it's own packet. A fix
    to the packet read filter was added to reject packets from the current MAC,
    but this defeats DECNET's duplicate node number detection scheme. A more
    correct fix for WinPCAP will be explored as time allows.
 5. The first time the WinPCAP driver is used, it will be dynamically loaded,
    and the user must be an Administrator on the machine to do so. See the
    WinPCAP documentation for a static load workaround if needed.

Building on Windows:
 1. Install WinPCAP 3.0.
 2. Get the required .h files (bittypes.h, devioctl.h, ip6_misc.h, packet32.h,
    pcap.h, pcap-stdinc.h) from the WinPCAP 3.0 developer's kit
 3. Get the required .lib files (packet.lib, wpcap.lib) from the WinPCAP 3.0
    developer's kit. If you're using Borland C++, use COFF2OMF to convert
    the .lib files into a format that can be used by the compiler.
 4. Put Sim_Ether and pdp11_xq into the build makefiles
 5. Build it!

-------------------------------------------------------------------------------

Linux and NetBSD notes:

 1. You must run SIMH(scp) as root so that the ethernet card can be set into
    promiscuous mode by the driver.


-------------------------------------------------------------------------------

THE XQ/SIM_ETHER Beta has been successfully tested on a Windows 2000 host,
emulating an OpenVMS 7.2 VAX system with DECNET Phase IV, MultiNet 4.4a, and
LAT 5.3.

Regression test criteria:
 1. VAX shows device correctly                                      (passed)
 2. VMS boots successfully with new device emulation                (passed)
 3. VMS initializes device correctly                                (passed)
 4. DECNET loads successfully                                       (passed)
 5. DECNET line stays up                                            (passed)
 6. SET HOST x.y:: works from SIMH to real DECNET machine           (passed)
 7. SET HOST x.y:: works from real DECNET machine to SIMH           (passed)
 8. DECNET copy works from SIMH to real DECNET machine              (passed)
 9. DECNET copy works from real DECNET machine to SIMH              (passed)
10. MultiNet TCP/IP loads successfully                              (passed)
11. Multinet TCP/IP initializes device successfully                 (passed)
12. SET HOST/TELNET x.y.z.w works from SIMH to real VAX IP machine  (passed)
13. SET HOST/TELNET x.y.z.w works from real VAX IP machine to SIMH  (passed)
14. FTP GET from a real VAX IP machine                              (passed)
15. LAT loads sucessfully                                           (passed)
16. SET HOST/LAT <nodename> works from SIMH to real VAX LAT machine (passed)
17. SET HOST/LAT <nodename> works from real VAX LAT machine to SIMH (passed)

I have NOT tested the following, but have reports that the following work:
 1. Operation with the PDP-11 emulator (RSX)
 2. Remote booting of NetBSD (via >>> B XQA0)

I have tested the following, and they do NOT work correctly:
 1. VMS NI Clustering (LAVC)
 2. Remote VAX booting (>>>B XQA0) into a VMScluster

-------------------------------------------------------------------------------

Things planned for future releases:
 1. Loopback packet processing
 2. Full MOP implementation
 3. Identity broadcast, which should occur every 8-10 minutes
 4. Full support for network boot (>> B XQA0)
 5. VMS NI Cluster (LAVC) support
 6. More efficient Sim_Ether module implementation for windows
 7. PDP-11 bootstrap
 8. DESQA support (if someone can get me the user manuals)
 9. DETQA support [DELQA-Turbo] (I have the manual)

-------------------------------------------------------------------------------

Things which I need help with:
 1. Porting Sim_Ether packet driver to other platforms, especially VMS.
 2. Information about Remote MOP processing
 3. PDP-11 bootstrap code.
 4. VAX hardware diagnotics image file and docs, to test XQ thoroughly.
 5. Feedback on the ethernet timing clock interval.
 6. Feedback on operation with other VAX OS's.
 7. Feedback on operation of PDP-11 OS's.

-------------------------------------------------------------------------------

Please send all patches, questions, feedback, clarifications, and help to:
  dhittner AT northropgrumman DOT com

NOTE: I _have_ corrected my email address!! Sorry about the confusion!

Thanks, and Enjoy!!
Dave

===============================================================================

DEQNA/DELQA Ethernet controller (XQ) Usage


XQ has the following options:

	SET  XQ MAC=<mac-address>	ex. 08-00-2B-AA-BB-CC
        SHOW XQ MAC

where <mac-address> is a valid ethernet MAC, delimited by dashes or periods.
The controller defaults to 08-00-2B-AA-BB-CC, which should be sufficient if
you are only running one SIMH controller on your LAN. Two cards with the same
MAC address will see each other's packets, resulting in a serious mess.


	ATTACH XQ0 {ethX|<device_name>}		ex. eth0 or /dev/era0
        SHOW XQ ETH

where X in 'ethX' is the number of the ethernet controller to attach, or the
real device name. The X number is system dependant. If you only have one
ethernet controller, the number will probably be 0. To find out what your
system thinks the ethernet numbers are, use the SHOW XQ ETH command. The
device list can be quite cryptic, depending on the host system, but is
probably better than guessing. If you do not attach the device, the
controller will behave as though the ethernet cable were unplugged.


	SET  XQ TYPE={DEQNA|[DELQA]}
        SHOW XQ TYPE

This command is used to set the emulation of the card. DELQA mode
is better and faster, but may not be usable by older or non-DEC OS's.
Also, be aware that DEQNA mode is not supported by many modern OS's. The
DEQNA-LOCK mode of the DELQA card is emulated by setting the the controller
to DEQNA - there is no need for a separate mode. DEQNA-LOCK mode behaves
exactly like a DEQNA, except for the operation of the VAR and MOP processing.


	SET  XQ SANITY={ON|[OFF]}
	SHOW XQ SANITY

This sets the INITIALIZATION sanity timer (DEQNA jumper W3/DELQA switch S4).
The INITIALIZATION sanity timer has a default timeout of 4 minutes, and
cannot be turned off, just reset. The normal sanity timer can be set by
operating system software regardless of the state of this switch. Note
that only the DEQNA (or the DELQA in DEQNA-LOCK mode(=DEQNA)) supports
INITIAL SANITY - it is ignored by a DELQA in Normal mode, which uses
switch S4 for a different purpose.


XQ has the following registers:
	CSR	Control Status Register
	VAR	Vector Address Register
	RBDL	Receive Buffer Descriptor List
	XBDL	Trans(X)mit Buffer Descriptor List
	SA0	Station Address word 0
	SA1	Station Address word 1
	SA2	Station Address word 2
	SA3	Station Address word 3
	SA4	Station Address word 4
	SA5	Station Address word 5


One final note: because of it's asynchronous nature, the XQ controller is
not limited to the ~1.5Mbit/sec of the real DEQNA/DELQA controllers,
nor the 10Mbit/sec of a standard ethernet. Attach it to a fast ethernet
(100Mbit/sec) card, and "Feel the Power!" :-)

