Commit | Line | Data |
---|---|---|
196ba1fc PH |
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 |