First Commit of my working state

[simh.git] / 0readme_ethernet.txt

This file contains information about the SIMH Ethernet package.\r
\r
-------------------------------------------------------------------------------\r
\r
The XQ emulator is a host-independant software emulation of Digital's\r
DELQA (M7516) and DEQNA (M7504) Q-bus ethernet cards for the SIMH emulator.\r
\r
The XU emulator is a host-independant software emulation of Digital's DEUNA\r
(M7792/M7793) and DELUA (M7521) Unibus ethernet cards for the SIMH emulator.\r
\r
The XQ and XU simulators use the Sim_Ether module to execute host-specific\r
packet reads and writes, since all operating systems talk to real ethernet\r
cards/controllers differently. See the comments at the top of sim_ether.c\r
for the list of currently supported host platforms.\r
\r
The Sim_Ether module sets the selected ethernet card into\r
promiscuous mode to gather all packets, then filters out the packets that it\r
doesn't want. In Windows, packets having the same source MAC address as the\r
controller are ignored for WinPCAP compatibility (see Windows notes below).\r
\r
If your ethernet card is plugged into a switch, the promiscuous mode setting\r
should not cause much of a problem, since the switch will still filter out\r
most of the undesirable traffic. You will only see "excessive" traffic if you\r
are on a direct or hub(repeater) segment.\r
\r
Using the libpcap/WinPcap interface, the simulated computer cannot "talk" to\r
the host computer via the selected interface, since the packets are not\r
reflected back to the host. The workaround for this is to use a second NIC in\r
the host and connect them both into the same network; then the host and the\r
simulator can communicate over the physical LAN.\r
\r
Universal TUN/TAP support provides another solution for the above dual-NIC\r
problem for systems that support Universal TUN/TAP. Since the TUN/TAP interface\r
is at a different network level, the host can create a TAP device for the\r
simulator and then bridge or route packets between the TAP device and the real\r
network interface. Note that the TAP device and any bridging or routing must be\r
established before running the simulator; SIMH does not create, bridge, or\r
route TAP devices for you.\r
\r
-------------------------------------------------------------------------------\r
\r
Windows notes:\r
 1. The Windows-specific code uses the WinPCAP 3.0 package from\r
    http://www.winpcap.org. This package for windows simulates the libpcap\r
    package that is freely available for un*x systems.\r
\r
 2. You must *install* the WinPCAP runtime package.\r
\r
 3. The first time the WinPCAP driver is used, it will be dynamically loaded,\r
    and the user must be an Administrator on the machine to do so. If you need\r
    to run as an unprivileged user, you must set the service to autostart. See\r
    the WinPCAP documentation for details on the static loading workaround.\r
\r
 4. If you want to use TAP devices, they must be created before running SIMH.\r
    (TAP component from the OpenVPN project; http://openvpn.sourceforge.net)\r
\r
 5. Compaq PATHWORKS 32 v7.2 also enabled bridging for the ethernet adapters\r
    when the DECNET and LAT drivers were installed; TAP was not needed.\r
\r
\r
Building on Windows:\r
 1. Install WinPCAP 3.0 runtime and the WinPCAP Developer's kit.\r
\r
 2. Put the required .h files (bittypes,devioctl,ip6_misc,packet32,pcap,\r
    pcap-stdinc).h from the WinPCAP 3.0 developer's kit in the compiler's path\r
\r
 3. Put the required .lib files (packet,wpcap).lib from the WinPCAP 3.0\r
    developer's kit in the linker's path\r
\r
 4. If you're using Borland C++, use COFF2OMF to convert the .lib files into\r
    a format that can be used by the compiler.\r
\r
 5. Define USE_NETWORK.\r
\r
 6. Build it!\r
\r
-------------------------------------------------------------------------------\r
\r
Linux, {Free|Net|Open}BSD, OS/X, and Un*x notes:\r
\r
----- WARNING ----- WARNING ----- WARNING ----- WARNING ----- WARNING -----\r
\r
Sim_Ether has been reworked to be more universal; because of this, you will\r
need to get a version of libpcap that is 0.9 or greater. This can be\r
downloaded from www.tcpdump.org - see the comments at the top of Sim_ether.c\r
for details.\r
\r
At the time of this release, the "Current Version" available at:\r
http://www.tcpdump.org/daily/libpcap-current.tar.gz is the \r
latest checked-in source code that is actually higher than the released\r
0.8.3 version number. Specifically, for all platforms, it contains code that \r
opens the ethernet device in Read/Write mode instead of the Read-Only mode \r
that previous libpcap versions for platforms which use one of pcap-bpf.c, \r
pcap-pf.c, or pcap-snit.c.  This capabiligy now exists to support a newly \r
provided generic packet sending capability.\r
\r
----- WARNING ----- WARNING ----- WARNING ----- WARNING ----- WARNING -----\r
\r
 1. For all platforms, you must run SIMH(scp) with sufficient privilege to\r
    allow the ethernet card can be set into promiscuous mode and to write\r
    packets through the driver. For most Unix/Unix-like platforms this will \r
    mean running as root.  For systems which use bpf devices (NetBSD, \r
    OpenBSD, FreeBSD and OS/X) it is possible to set permissions on the bpf \r
    devices to allow read and write access to users other than root (For\r
    example: chmod 666 /dev/bpf*).  Doing this, has its own security issues.\r
    Additional alternative methods for avoiding the 'run as root' requirement \r
    will be welcomed.\r
\r
 2. If you want to use TAP devices, they must be created before running SIMH.\r
\r
Building on Linux, {Free|Net|Open}BSD, OS/X, Un*x:\r
\r
 1. Get/make/install the libpcap package for your operating system. Sources:\r
      All    : http://www.tcpdump.org/\r
      Older versions of libpcap can be found, for various systems, at:\r
      Linux  : search for your variant on http://rpmfind.net\r
      OS/X   : Apple Developer's site?\r
\r
	    NOTE: These repositories will not likely contain a version\r
	          of libpcap greater than 0.8.1 for several years since \r
	          other packages in these repositories don't depend on a \r
	          later version than they currently have.\r
\r
 2. Use 'make USE_NETWORK=1'\r
\r
 3. Build it!\r
\r
-------------------------------------------------------------------------------\r
\r
OpenVMS Alpha notes:\r
  1. Ethernet support will only work on Alpha VMS 7.3-1 or later, which is\r
     when required VCI promiscuous mode support was added. Hobbyists can\r
     get the required version of VMS from the OpenVMS Alpha Hobbyist Kit 3.0.\r
\r
     Running a simulator built with ethernet support on a version of VMS prior\r
     to 7.3-1 will behave as if there is no ethernet support built in due to\r
     the inability of the software to set the PCAPVCM into promiscuous mode.\r
\r
     An example display of fully functional ethernet support:\r
       sim> SHOW XQ ETH\r
       ETH devices:\r
         0  we0 (VMS Device: _EWA0:)\r
         1  we1 (VMS Device: _EWB0:)\r
\r
     An example display when the simulator was built without ethernet support\r
     or is not running the required version of VMS:\r
       sim> SHOW XQ ETH\r
       ETH devices:\r
         no network devices are available\r
\r
  2. You must place the PCAPVCM.EXE execlet in SYS$LOADABLE_IMAGES before\r
     running a simulator with ethernet support.  Note: This is done by the\r
     build commands in descrip.mms.\r
\r
  3. You must have CMKRNL privilege to SHOW or ATTACH an ethernet device;\r
     alternatively, you can INSTALL the simulator with CMKRNL privilege.\r
\r
  4. If you use a second adapter to communicate to the host, SOME protocol\r
     that creates an I/O structure (SCS, DECNET, TCP) must be running on the\r
     adapter prior trying to connect with SIMH, or the host may crash.\r
     The execlet is not written to create an I/O structure for the device.\r
\r
Building on OpenVMS Alpha:\r
  The current descrip.mms file will build simulators capable of using\r
  ethernet support with them automatically.  These currently are: VAX, \r
  PDP11, and PDP10.  The descrip.mms driven builds will also build the\r
  pcap library and build and install the VCI execlet.\r
  \r
  1. Fetch the VMS-PCAP zip file from:  \r
	    http://simh.trailing-edge.com/sources/vms-pcap.zip\r
  2. Unzip it into the base of the simh distribution directory.\r
  3. Build the simulator(s) with MMS or MMK:\r
         $ MMx {VAX,PDP11,PDP10, etc...}\r
\r
-------------------------------------------------------------------------------\r
\r
VAX simulator support:\r
\r
An OpenVMS VAX v7.2 system with DECNET Phase IV, MultiNet 4.4a, and LAT 5.3 has\r
been successfully run. Other testers have reported success booting NetBSD and\r
OpenVMS VAX 5.5-2 also.\r
\r
\r
PDP11 simulator support:\r
\r
An RT-11 v5.3 system with a freeware TCP/IP stack has been successfully run.\r
Other testers have reported that RSX with DECNET and the NetBSD operating\r
systems also work. RSTS/E v10.1 has preliminary support - RSTS/E boots and\r
enables the XH (XQ) device - DECNET and LAT software have not been tested.\r
\r
The XU module has been tested by a third party for basic packet functionality \r
under a modified RSX11M environment. I am unable to test it in-house until\r
someone can arrange to send me a disk image containing a stock RSTS/E or\r
RSX11M+ system image that also contains DECNET, LAT, and/or TCP/IP software.\r
\r
-------------------------------------------------------------------------------\r
\r
How to debug problems with the ethernet subsystems:\r
\r
PLEASE read the host-specific notes in sim_ether.c!\r
\r
While running SCP, the following commands can be used to enable debug messages:\r
\r
  scp> SET DEBUG STDERR\r
  scp> SET XQ DEBUG={ETH|TRC|REG|WRN|CSR|VAR|SAN|SET|PCK}\r
  scp> SET XU DEBUG={ETH|TRC|REG|WRN}\r
\r
Documentation of the functionality of these debug modifiers can be found in\r
pdp11_xq.h and pdp11_xu.h. Inline debugging has replaced the previous #ifdef\r
style of debugging, which required recompilation before debugging.\r
\r
-------------------------------------------------------------------------------\r
\r
Things planned for future releases:\r
 1. PDP-11 bootstrap/bootrom\r
 2. Full MOP implementation\r
 3. DESQA support (if someone can get me the user manuals)\r
 4. DETQA support [DELQA-Turbo] (I have the manual)\r
\r
-------------------------------------------------------------------------------\r
\r
Things which I need help with:\r
 1. Information about Remote MOP processing\r
 2. VAX/PDP-11 hardware diagnotics image files and docs, to test XQ thoroughly.\r
 3. Feedback on operation with other VAX/PDP-11 OS's.\r
\r
-------------------------------------------------------------------------------\r
\r
Please send all patches, questions, feedback, clarifications, and help to:\r
  david DOT hittner AT ngc DOT com\r
\r
Thanks, and Enjoy!!\r
Dave\r
\r
\r
===============================================================================\r
                               Change Log\r
===============================================================================\r
\r
19-Mar-04 Release:\r
 1. Genericized Sim_Ether code, reduced #ifdefs                (David Hittner)\r
 2. Further refinement of sim_ether, qualified more platforms (Mark Pizzolato)\r
 3. Added XU module                                            (David Hittner)\r
 4. Corrected XQ interrupt signalling for PDP11s               (David Hittner)\r
 5. Added inline debugging support                             (David Hittner)\r
\r
-------------------------------------------------------------------------------\r
\r
26-Nov-03 Release:\r
 1. Added VMS support to Sim_Ether; created pcap-vms port      (Anders Ahgren)\r
 2. Added DECNET duplicate detection for Windows              (Mark Pizzolato)\r
 3. Added BPF filtering to increase efficiency                (Mark Pizzolato)\r
 4. Corrected XQ Runt processing                              (Mark Pizzolato)\r
 5. Corrected XQ Sofware Reset                               (Mark Pizzolato)\r
 6. Corrected XQ Multicast/Promiscuous mode setting/resetting (Mark Pizzolato)\r
 7. Added Universal TUN/TAP support                           (Mark Pizzolato)\r
 8. Added FreeBSD support                                  (Edward Brocklesby)\r
 9. Corrected interrupts on XQB device                         (David Hittner)\r
\r
-------------------------------------------------------------------------------\r
\r
05-Jun-03 Release:\r
 1. Added SET/SHOW XQ STATS                                    (David Hittner)\r
 2. Added SHOW XQ FILTERS                                      (David Hittner)\r
 3. Added ability to split rcv packets into multiple buffers   (David Hittner)\r
 4. Added explicit runt & giant packet processing              (David Hittner)\r
\r
-------------------------------------------------------------------------------\r
\r
30-May-03 Release:\r
 1. Corrected bug in xq_setmac introduced in v3.0            (multiple people)\r
 2. Made XQ rcv buffer allocation dynamic to reduce scp size   (David Hittner)\r
 3. Optimized some structs, removed legacy variables          (Mark Pizzolato)\r
 4. Changed #ifdef WIN32 to _WIN32 for consistancy            (Mark Pizzolato)\r
\r
-------------------------------------------------------------------------------\r
\r
06-May-03 Release:\r
 1. Added second XQ controller                                 (David Hittner)\r
 2. Added SIMH v3.0 compatibility                              (David Hittner)\r
 3. Removed SET ADDRESS functionality                          (David Hittner)\r
\r
-------------------------------------------------------------------------------\r
\r
10-Apr-03 Release:\r
 1. Added preliminary support for RSTS/E                       (David Hittner)\r
 2. Added PDP-11 bootrom load via CSR flags                    (David Hittner)\r
 3. Support for SPARC linux                                   (Mark Pizzolato)\r
\r
-------------------------------------------------------------------------------\r
\r
11-Mar-03 Release:\r
 1. Added support for RT-11 TCP/IP\r
 2. Corrected interrupts (thanks to Tom Evans and Bob Supnik)\r
 3. Moved change log to the bottom of the readme file, cleaned up document\r
\r
-------------------------------------------------------------------------------\r
\r
16-Jan-03 Release:\r
 1. Added VMScluster support (thanks to Mark Pizzolato)\r
 2. Verified VAX remote boot functionality (>>>B XQA0)\r
 3. Added major performance enhancements (thanks to Mark Pizzolato again)\r
 4. Changed _DEBUG tracers to XQ_DEBUG and ETH_DEBUG \r
 5. Added local packet processing\r
 6. Added system id broadcast\r
\r
-------------------------------------------------------------------------------\r
\r
08-Nov-02 Release:\r
 1. Added USE_NETWORK conditional to Sim_Ether\r
 2. Fixed behaviour of SHOW XQ ETH if no devices exist\r
 3. Added OpenBSD support to Sim_Ether (courtesy of Federico Schwindt)\r
 4. Added ethX detection simplification (from Megan Gentry)\r
\r
===============================================================================\r