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