0readme_ethernet.txt

   1 This file contains information about the SIMH Ethernet package.
   2
   3 -------------------------------------------------------------------------------
   4
   5 The XQ emulator is a host-independant software emulation of Digital's
   6 DELQA (M7516) and DEQNA (M7504) Q-bus ethernet cards for the SIMH emulator.
   7
   8 The XU emulator is a host-independant software emulation of Digital's DEUNA
   9 (M7792/M7793) and DELUA (M7521) Unibus ethernet cards for the SIMH emulator.
  10
  11 The XQ and XU simulators use the Sim_Ether module to execute host-specific
  12 packet reads and writes, since all operating systems talk to real ethernet
  13 cards/controllers differently. See the comments at the top of sim_ether.c
  14 for the list of currently supported host platforms.
  15
  16 The Sim_Ether module sets the selected ethernet card into
  17 promiscuous mode to gather all packets, then filters out the packets that it
  18 doesn't want. In Windows, packets having the same source MAC address as the
  19 controller are ignored for WinPCAP compatibility (see Windows notes below).
  20
  21 If your ethernet card is plugged into a switch, the promiscuous mode setting
  22 should not cause much of a problem, since the switch will still filter out
  23 most of the undesirable traffic. You will only see "excessive" traffic if you
  24 are on a direct or hub(repeater) segment.
  25
  26 Using the libpcap/WinPcap interface, the simulated computer cannot "talk" to
  27 the host computer via the selected interface, since the packets are not
  28 reflected back to the host. The workaround for this is to use a second NIC in
  29 the host and connect them both into the same network; then the host and the
  30 simulator can communicate over the physical LAN.
  31
  32 Universal TUN/TAP support provides another solution for the above dual-NIC
  33 problem for systems that support Universal TUN/TAP. Since the TUN/TAP interface
  34 is at a different network level, the host can create a TAP device for the
  35 simulator and then bridge or route packets between the TAP device and the real
  36 network interface. Note that the TAP device and any bridging or routing must be
  37 established before running the simulator; SIMH does not create, bridge, or
  38 route TAP devices for you.
  39
  40 -------------------------------------------------------------------------------
  41
  42 Windows notes:
  43  1. The Windows-specific code uses the WinPCAP 3.0 package from
  44     http://www.winpcap.org. This package for windows simulates the libpcap
  45     package that is freely available for un*x systems.
  46
  47  2. You must *install* the WinPCAP runtime package.
  48
  49  3. The first time the WinPCAP driver is used, it will be dynamically loaded,
  50     and the user must be an Administrator on the machine to do so. If you need
  51     to run as an unprivileged user, you must set the service to autostart. See
  52     the WinPCAP documentation for details on the static loading workaround.
  53
  54  4. If you want to use TAP devices, they must be created before running SIMH.
  55     (TAP component from the OpenVPN project; http://openvpn.sourceforge.net)
  56
  57  5. Compaq PATHWORKS 32 v7.2 also enabled bridging for the ethernet adapters
  58     when the DECNET and LAT drivers were installed; TAP was not needed.
  59
  60
  61 Building on Windows:
  62  1. Install WinPCAP 3.0 runtime and the WinPCAP Developer's kit.
  63
  64  2. Put the required .h files (bittypes,devioctl,ip6_misc,packet32,pcap,
  65     pcap-stdinc).h from the WinPCAP 3.0 developer's kit in the compiler's path
  66
  67  3. Put the required .lib files (packet,wpcap).lib from the WinPCAP 3.0
  68     developer's kit in the linker's path
  69
  70  4. If you're using Borland C++, use COFF2OMF to convert the .lib files into
  71     a format that can be used by the compiler.
  72
  73  5. Define USE_NETWORK.
  74
  75  6. Build it!
  76
  77 -------------------------------------------------------------------------------
  78
  79 Linux, {Free|Net|Open}BSD, OS/X, and Un*x notes:
  80
  81 ----- WARNING ----- WARNING ----- WARNING ----- WARNING ----- WARNING -----
  82
  83 Sim_Ether has been reworked to be more universal; because of this, you will
  84 need to get a version of libpcap that is 0.9 or greater. This can be
  85 downloaded from www.tcpdump.org - see the comments at the top of Sim_ether.c
  86 for details.
  87
  88 At the time of this release, the "Current Version" available at:
  89 http://www.tcpdump.org/daily/libpcap-current.tar.gz is the
  90 latest checked-in source code that is actually higher than the released
  91 0.8.3 version number. Specifically, for all platforms, it contains code that
  92 opens the ethernet device in Read/Write mode instead of the Read-Only mode
  93 that previous libpcap versions for platforms which use one of pcap-bpf.c,
  94 pcap-pf.c, or pcap-snit.c.  This capabiligy now exists to support a newly
  95 provided generic packet sending capability.
  96
  97 ----- WARNING ----- WARNING ----- WARNING ----- WARNING ----- WARNING -----
  98
  99  1. For all platforms, you must run SIMH(scp) with sufficient privilege to
 100     allow the ethernet card can be set into promiscuous mode and to write
 101     packets through the driver. For most Unix/Unix-like platforms this will
 102     mean running as root.  For systems which use bpf devices (NetBSD,
 103     OpenBSD, FreeBSD and OS/X) it is possible to set permissions on the bpf
 104     devices to allow read and write access to users other than root (For
 105     example: chmod 666 /dev/bpf*).  Doing this, has its own security issues.
 106     Additional alternative methods for avoiding the 'run as root' requirement
 107     will be welcomed.
 108
 109  2. If you want to use TAP devices, they must be created before running SIMH.
 110
 111 Building on Linux, {Free|Net|Open}BSD, OS/X, Un*x:
 112
 113  1. Get/make/install the libpcap package for your operating system. Sources:
 114       All    : http://www.tcpdump.org/
 115       Older versions of libpcap can be found, for various systems, at:
 116       Linux  : search for your variant on http://rpmfind.net
 117       OS/X   : Apple Developer's site?
 118
 119             NOTE: These repositories will not likely contain a version
 120                   of libpcap greater than 0.8.1 for several years since
 121                   other packages in these repositories don't depend on a
 122                   later version than they currently have.
 123
 124  2. Use 'make USE_NETWORK=1'
 125
 126  3. Build it!
 127
 128 -------------------------------------------------------------------------------
 129
 130 OpenVMS Alpha notes:
 131   1. Ethernet support will only work on Alpha VMS 7.3-1 or later, which is
 132      when required VCI promiscuous mode support was added. Hobbyists can
 133      get the required version of VMS from the OpenVMS Alpha Hobbyist Kit 3.0.
 134
 135      Running a simulator built with ethernet support on a version of VMS prior
 136      to 7.3-1 will behave as if there is no ethernet support built in due to
 137      the inability of the software to set the PCAPVCM into promiscuous mode.
 138
 139      An example display of fully functional ethernet support:
 140        sim> SHOW XQ ETH
 141        ETH devices:
 142          0  we0 (VMS Device: _EWA0:)
 143          1  we1 (VMS Device: _EWB0:)
 144
 145      An example display when the simulator was built without ethernet support
 146      or is not running the required version of VMS:
 147        sim> SHOW XQ ETH
 148        ETH devices:
 149          no network devices are available
 150
 151   2. You must place the PCAPVCM.EXE execlet in SYS$LOADABLE_IMAGES before
 152      running a simulator with ethernet support.  Note: This is done by the
 153      build commands in descrip.mms.
 154
 155   3. You must have CMKRNL privilege to SHOW or ATTACH an ethernet device;
 156      alternatively, you can INSTALL the simulator with CMKRNL privilege.
 157
 158   4. If you use a second adapter to communicate to the host, SOME protocol
 159      that creates an I/O structure (SCS, DECNET, TCP) must be running on the
 160      adapter prior trying to connect with SIMH, or the host may crash.
 161      The execlet is not written to create an I/O structure for the device.
 162
 163 Building on OpenVMS Alpha:
 164   The current descrip.mms file will build simulators capable of using
 165   ethernet support with them automatically.  These currently are: VAX,
 166   PDP11, and PDP10.  The descrip.mms driven builds will also build the
 167   pcap library and build and install the VCI execlet.
 168
 169   1. Fetch the VMS-PCAP zip file from:
 170             http://simh.trailing-edge.com/sources/vms-pcap.zip
 171   2. Unzip it into the base of the simh distribution directory.
 172   3. Build the simulator(s) with MMS or MMK:
 173          $ MMx {VAX,PDP11,PDP10, etc...}
 174
 175 -------------------------------------------------------------------------------
 176
 177 VAX simulator support:
 178
 179 An OpenVMS VAX v7.2 system with DECNET Phase IV, MultiNet 4.4a, and LAT 5.3 has
 180 been successfully run. Other testers have reported success booting NetBSD and
 181 OpenVMS VAX 5.5-2 also.
 182
 183
 184 PDP11 simulator support:
 185
 186 An RT-11 v5.3 system with a freeware TCP/IP stack has been successfully run.
 187 Other testers have reported that RSX with DECNET and the NetBSD operating
 188 systems also work. RSTS/E v10.1 has preliminary support - RSTS/E boots and
 189 enables the XH (XQ) device - DECNET and LAT software have not been tested.
 190
 191 The XU module has been tested by a third party for basic packet functionality
 192 under a modified RSX11M environment. I am unable to test it in-house until
 193 someone can arrange to send me a disk image containing a stock RSTS/E or
 194 RSX11M+ system image that also contains DECNET, LAT, and/or TCP/IP software.
 195
 196 -------------------------------------------------------------------------------
 197
 198 How to debug problems with the ethernet subsystems:
 199
 200 PLEASE read the host-specific notes in sim_ether.c!
 201
 202 While running SCP, the following commands can be used to enable debug messages:
 203
 204   scp> SET DEBUG STDERR
 205   scp> SET XQ DEBUG={ETH|TRC|REG|WRN|CSR|VAR|SAN|SET|PCK}
 206   scp> SET XU DEBUG={ETH|TRC|REG|WRN}
 207
 208 Documentation of the functionality of these debug modifiers can be found in
 209 pdp11_xq.h and pdp11_xu.h. Inline debugging has replaced the previous #ifdef
 210 style of debugging, which required recompilation before debugging.
 211
 212 -------------------------------------------------------------------------------
 213
 214 Things planned for future releases:
 215  1. PDP-11 bootstrap/bootrom
 216  2. Full MOP implementation
 217  3. DESQA support (if someone can get me the user manuals)
 218  4. DETQA support [DELQA-Turbo] (I have the manual)
 219
 220 -------------------------------------------------------------------------------
 221
 222 Things which I need help with:
 223  1. Information about Remote MOP processing
 224  2. VAX/PDP-11 hardware diagnotics image files and docs, to test XQ thoroughly.
 225  3. Feedback on operation with other VAX/PDP-11 OS's.
 226
 227 -------------------------------------------------------------------------------
 228
 229 Please send all patches, questions, feedback, clarifications, and help to:
 230   david DOT hittner AT ngc DOT com
 231
 232 Thanks, and Enjoy!!
 233 Dave
 234
 235
 236 ===============================================================================
 237                                Change Log
 238 ===============================================================================
 239
 240 19-Mar-04 Release:
 241  1. Genericized Sim_Ether code, reduced #ifdefs                (David Hittner)
 242  2. Further refinement of sim_ether, qualified more platforms (Mark Pizzolato)
 243  3. Added XU module                                            (David Hittner)
 244  4. Corrected XQ interrupt signalling for PDP11s               (David Hittner)
 245  5. Added inline debugging support                             (David Hittner)
 246
 247 -------------------------------------------------------------------------------
 248
 249 26-Nov-03 Release:
 250  1. Added VMS support to Sim_Ether; created pcap-vms port      (Anders Ahgren)
 251  2. Added DECNET duplicate detection for Windows              (Mark Pizzolato)
 252  3. Added BPF filtering to increase efficiency                (Mark Pizzolato)
 253  4. Corrected XQ Runt processing                              (Mark Pizzolato)
 254  5. Corrected XQ Sofware Reset                               (Mark Pizzolato)
 255  6. Corrected XQ Multicast/Promiscuous mode setting/resetting (Mark Pizzolato)
 256  7. Added Universal TUN/TAP support                           (Mark Pizzolato)
 257  8. Added FreeBSD support                                  (Edward Brocklesby)
 258  9. Corrected interrupts on XQB device                         (David Hittner)
 259
 260 -------------------------------------------------------------------------------
 261
 262 05-Jun-03 Release:
 263  1. Added SET/SHOW XQ STATS                                    (David Hittner)
 264  2. Added SHOW XQ FILTERS                                      (David Hittner)
 265  3. Added ability to split rcv packets into multiple buffers   (David Hittner)
 266  4. Added explicit runt & giant packet processing              (David Hittner)
 267
 268 -------------------------------------------------------------------------------
 269
 270 30-May-03 Release:
 271  1. Corrected bug in xq_setmac introduced in v3.0            (multiple people)
 272  2. Made XQ rcv buffer allocation dynamic to reduce scp size   (David Hittner)
 273  3. Optimized some structs, removed legacy variables          (Mark Pizzolato)
 274  4. Changed #ifdef WIN32 to _WIN32 for consistancy            (Mark Pizzolato)
 275
 276 -------------------------------------------------------------------------------
 277
 278 06-May-03 Release:
 279  1. Added second XQ controller                                 (David Hittner)
 280  2. Added SIMH v3.0 compatibility                              (David Hittner)
 281  3. Removed SET ADDRESS functionality                          (David Hittner)
 282
 283 -------------------------------------------------------------------------------
 284
 285 10-Apr-03 Release:
 286  1. Added preliminary support for RSTS/E                       (David Hittner)
 287  2. Added PDP-11 bootrom load via CSR flags                    (David Hittner)
 288  3. Support for SPARC linux                                   (Mark Pizzolato)
 289
 290 -------------------------------------------------------------------------------
 291
 292 11-Mar-03 Release:
 293  1. Added support for RT-11 TCP/IP
 294  2. Corrected interrupts (thanks to Tom Evans and Bob Supnik)
 295  3. Moved change log to the bottom of the readme file, cleaned up document
 296
 297 -------------------------------------------------------------------------------
 298
 299 16-Jan-03 Release:
 300  1. Added VMScluster support (thanks to Mark Pizzolato)
 301  2. Verified VAX remote boot functionality (>>>B XQA0)
 302  3. Added major performance enhancements (thanks to Mark Pizzolato again)
 303  4. Changed _DEBUG tracers to XQ_DEBUG and ETH_DEBUG
 304  5. Added local packet processing
 305  6. Added system id broadcast
 306
 307 -------------------------------------------------------------------------------
 308
 309 08-Nov-02 Release:
 310  1. Added USE_NETWORK conditional to Sim_Ether
 311  2. Fixed behaviour of SHOW XQ ETH if no devices exist
 312  3. Added OpenBSD support to Sim_Ether (courtesy of Federico Schwindt)
 313  4. Added ethX detection simplification (from Megan Gentry)
 314
 315 ===============================================================================