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