Documentation for Null Modem Simulator -------------------------------------- 06-Mar-1999 ========================================================== nullser.device V1.0 05-Mar-1999 Copyright © 1999 Frederick H. G. Wright II ========================================================== License ======= This software is freeware, and may be used or distributed free of charge for any noncommercial purpose. Disclaimer ========== This program and its documentation are provided "as is". No warranties are made with respect to the accuracy, reliability, performance or operation of this software and information. You are using this program at your own risk. The author is not liable for any damages that may have been caused by using this software. Introduction ============ This driver simulates pairs of serial ports interconnected by null-modem cables. It can be used for testing comm programs and network software, but the primary motivation was to allow linking network software on an emulated computer (e.g. Mac emulated by FUSION) to Amiga network software. NOTE: This is a true null-modem simulation, not a simulation of two modems connected to each other as in nullmodem.device. The ability to network in this fashion provides a number of benefits, albeit not at blinding speeds: 1) Emulated and Amiga-native network software can share the same dialup link. 2) Ethernet cards that don't work correctly under the emulation can be used via the Amiga's network software. 3) Third-party serial cards that don't work correctly under the emulation can be used via the Amiga's network sofware. 4) The native serial port can use Miami's built-in driver, which tends to work better than serial.device or any of its replacements. 5) Incompatibilities between the emulation's Ethernet support and Open Transport on an emulated Mac don't preclude using Open Transport on the Amiga's Ethernet. Changes in 1.0 ============== Hosts file information added to documentation. No changes to code from 0.9beta other than version information. Changes in 0.9beta ================== Documentation additions for clarification. Commands (other than NSCMD_DEVICEQUERY) issued to unit -1 now return IOERR_NOCMD instead of IOERR_OPENFAIL. Made driver fully NSD-compliant. Note that 0.8beta is "NSD-safe", but doesn't implement the NSD query command. Some units are now interrupt-legal (for BeginIO/AbortIO). This is not known to be required by any applications, but is available if needed. For consistency, closing a unit completely now terminates WRITEs on its peer with the same NoDSR error that would have occurred if they had been issued in this state. System requirements =================== Any Amiga. The driver should be compatible with all CPUs and OS versions. However, CPUs with caches require V36 (2.0) or later. Software Installation ===================== Installing the driver is simply a matter of copying the file nullser.device to an appropriate DEVS: directory. Configuration ============= The driver itself needs no configuration, although the software using it will. Its unit numbers are taken in even/odd pairs (e.g. 0/1, 24/25, etc.) to form simulated links. Compatibility with serial.device ================================ Only a subset of the serial.device features are supported, though it should be adequate for the intended uses. Some of these features (or lack thereof) may be visible when configuring programs to use the driver. Most of the behavior follows from the fact that it passes 8-bit characters without examination or modification, and transfers directly between sending and receiving buffers without any internal intermediate buffering. The characteristics are as follows: Unit Numbers ------------ Unit numbers from 0-65535 are supported, thus allowing up to 32768 links as memory permits. Unit -1 is the typical special case which opens the driver but not any unit (no I/O other than NSD query is allowed in this case). Also, unit numbers which are >=128 mod 256 are now interrupt-legal for BeginIO() and AbortIO(). BeginIO() for SDCMD_QUERY is always interrupt-legal. SHARED Mode ----------- Implemented normally. Note that ownership is per unit - there is no need to use SHARED mode to allow different programs to use different units, including the two units forming a link. EOFMODE ------- Not supported. Any attempt to use it will result in an error. Note that due to the way the driver works, using EOFMODE would actually be slower. Flow Control ------------ The actual flow control is implicit, but the status bits mimic the behavior of CTS/RTS flow control. The supplied enable for CTS/RTS (7WIRE) is ignored. XON/XOFF flow control is not supported, and attempting to select it will result in an error. Character Format ---------------- Characters are always 8 bits with no parity generated or checked. The parameters for character length, parity and number of stop bits are all ignored. The effect is sort of like implied 8N1 (though 8N0 might be more accurate). Baud Rate --------- Since there is no serial communication, baud rate is meaningless and the parameter is ignored. With software whose behavior is influenced by communication speed, it may be desirable to select the highest speed available; otherwise it doesn't matter at all. Buffer Size ----------- Since there is no internal buffer, this parameter is ignored. BREAK Type and Duration ----------------------- BREAK is not currently implemented, hence these parameters are ignored. A future version may implement BREAK for use in testing comm programs. It's never used in network connections. RS-232 Status Indicators ------------------------ These are implemented to the extent meaningful, as follows: DTR Always asserted RI Never asserted DSR Asserted when the peer unit is open CD Asserted when the peer unit is open RTS Asserted when at least one READ is outstanding on this unit CTS Asserted when at least one READ is outstanding on the peer unit Performance =========== Performance should be quite good when READs and WRITEs of significant size are used, since there is a single stage of copying with no actual "processing" of the characters. However, single-character READs and WRITEs incur significant command processing overhead. A future version may add some speedup code for the single-character case. Note that when using this driver for a network link, there is substantial overhead in other processing. Two mating PPP or SLIP drivers incur quite a bit of processing time, and even if the driver added zero overhead it would probably not be possible to reach Ethernet speeds on the fastest current Amigas. Testing ======= So far, the following combinations have been tested: VLT<->VLT, both typing and ZModem MicroPhone/FUSION<->VLT, both typing and ZModem FreePPP/FUSION<->MiamiDx FreePPP/ShapeShifter<->MiamiDx Using the Driver as a Network Link ================================== The driver can be used to link two TCP/IP stacks together, simply by using the even and odd units of a pair as the two ends of a "null modem" link. Configure the nullser units just as you would real serial units. Note that this method of network access requires TCP/IP software on both "machines". The Amiga's TCP code is not available to the other end of the link; all it's TCP/IP stack is doing is acting as a packet forwarder with optional address modifications. For an emulated Mac, this means you still need MacTCP or Open Transport installed and configured, along with a PPP or SLIP driver such as FreePPP. It would be much simpler to configure and more efficient to make bsdsocket.library accessible to the Mac, but that's a much more complex (and mainly Mac-side) programming problem. Thus this kludgy method will have to suffice for now. The configuration is really no different from a real nullmodem configuration. Note that the two "machines" need separate IP addresses, though they may apparently share a single externally visible address if an address translation mechanism such as IP-NAT or SOCKS is used. The setup depends primarily on the characteristics of the network software being used. PPP can be a little tricky since there are some asymmetries bewteen the "client" and "server" that can cause problems when one attempts to connect two "clients". SLIP is too dumb to be afflicted with this problem, so in some cases using SLIP rather than PPP may help. But since SLIP is more easily misconfigured, it's usually worth trying PPP first. Although no actual "dialing" is taking place, in some cases dialscript features may be useful in coordinating the link startup. For example, one side might issue a "modem" command which is recognized as a "result string" by the script on the other side. If the software supports it, waiting for CD can also be used to initiate protocol startup without any scripts at all. With neither of these options, one typically needs to start the link from both sides at approximately the same time to avoid timeouts. For best performance, it's best to enable options that avoid adding unnecessary overhead, while avoiding options that use extra computing to remove existing overhead. Thus ACCM=0 is best, but VJC should be disabled. Whether ACFC and PFC are better on or off is questionable, but it's probably only a minor difference. The "Null FCS" option would be desirable, but it's not often implemented. In general larger MTUs will perform better, but for traffic gatewaying to/from another interface there's no benefit in using a larger MTU in the nullser link than in the "ultimate" link. Thus in most cases 1500 would be a good choice, since it matches the maximum Ethernet MTU and Path MTU Discovery should adjust to a lower MTU over a serial link if needed. If Path MTU Discovery is broken somewhere, however, it may be necessary to reduce the MTU setting. The following is a sample setup (except for the clearly installation- dependent parameters) for linking the Mac with FreePPP to MiamiDx and using IP-NAT to share the Amiga's "visible" IP address. If you have multiple IP addresses actually available, then it's better to configure "real" separete addresses for the Amiga and Mac, and not use IP-NAT at all. The choices of IP address are somewhat aribitrary, but should be within one of the "reserved for private networks" blocks and not in conflict with other LAN addresses (if applicable). My Settings in MiamiDx beta 0.9d -------------------------------- Hardware: Name: NUL0 Type: serial device driver Driver: nullser.device Unit: 1 Speed: 460800 Use CD: off Flow control: RTS/CTS EOF mode: off MTU: 1500 Serial mode: 8N1 Modem settings...: Null modem Dialer: Name: NULL Dial script: TIMEOUT 30000000 WAITPPP (other items blank or default) Interface: Name: ppp1 Alias: Mac Type: PPP dial-out Hardware: NUL0 Priority: 10 Dialer: NULL IP type: static IP address: 172.24.0.1 Gateway type: static Gateway: 172.24.0.2 Pri: 0 Multicasts: disabled Multicast pri: 10 Control panel: on GUI default: off Logging...: (PPP logging as desired) Auto-connect/disconnect...: defaults TCP/IP settings...: everything off PPP settings...: VJC: off ACCM: 0 Get DNS from IPCP: off TermReq before hangup: on Quick Reconnect: disabled Manually configured routes...: none Events...: default TCP/IP: ... Gateway: on ... LAN-Connect: Interfaces: Name Type (any outside interface) Internet ppp1 LAN SocksD: off IP-NAT: internal FTP: on IRC-DCC: off (unless using Mac IRC) IP-NAT redirection...: (none) Note: if the firewall is enabled and Open Transport is being used on the Mac, then the following firewall entry must be included (in addition to any others) to permit sucecssful DNS lookups: Access Proto S-IP D-Port D-IP ------ ----- ---- ------ ---- Accept UDP 32768 This is because OT's DNS uses a source port of 32768, which is not permitted through the firewall by default. My settings in FUSION 3.1 ------------------------- Ports: Port A Device Driver Unit serial nullser.device 0 My settings in FreePPP 2.6.2 ---------------------------- Connect to: NullModem From: Home Using: NullModem Accounts/NullModem: Account: Account name: NullModem Connect: Directly (others blank) Dialup: (all blank) Options: Domain name: (as required) Primary DNS: (as required) Secondary DNS: (as required) Configure OT TCP/IP for this server: on IP address: 172.24.0.2 Modems/NullModem: Modem config name: NullModem Connected to: Modem Port Port speed: 230400 Dial Type: Tone Speaker enabled: on Long re-dial delay: off Hangup on disconnect: off Fast modem initialization: on Performa internal modem: off Modem init string settings: Use: (blank) Note on selection of private IP addresses ----------------------------------------- In principle, the only requirement for the selection of "private" IP addresses is that they come from one of the blocks reserved for the purpose to insure that they don't conflict with registered IP addresses. In practice, there are a couple of considerations that make it advantageous to choose addresses less likely to conflict with other *private* addresses: 1) In some cases, private addresses are used for intermediate internal routers in "outside" network links. While this does not present a problem for routing, it could produce misleading symbolic names from traceroute. 2) If the system might, under some circumstances, be directly connected to a private network, avoiding address collisions would be important. For these reasons, I've chosen the Class B private address block in the above examples (since most sites seem to prefer the Class C or Class A blocks), and also (a change since the original document) picked addresses in the "middle" of the block (172.24.0.x rather than 172.16.0.x). These addresses are only suggestions. Differences When Using Separate "Real" IP Addresses --------------------------------------------------- In this case, the Amiga's real assigned IP address should be used for the link, and the Mac's real IP address should be used as the "gateway" address on the MiamiDx side of the link, and as the static IP in FreePPP. Other machines on a LAN should be configured to see the Amiga's IP as a gateway for the Mac's IP, unless the Amiga is already the default gateway. And of course IP-NAT should be disabled. Host Names ---------- Since DNS servers won't know about the local IP addresses, it's necessary to configure names for these manually if you want to refer to the machines by name. In MiamiDx, this is done by adding entries to Database/hosts, as in: IP Address Name Aliases ---------- ---- ------- 172.24.0.1 Amiga 172.24.0.2 Mac On The Mac side, this is accomplished through the use of a Hosts file. A sample Hosts file equivalent to the above is included, in MacBinary format. With Open Transport, this file can be placed anywhere and loaded into the configuration via the "Select Hosts File..." button in the TCP/IP control panel. MacTCP is supposed to look for the file Hosts in the System Folder, although at the time of this writing it doesn't seem to work. It may need a particular file type and/or creator to work properly. If you have a real LAN, then other name/address combinations can be added to the Hosts file. Note that OT does not allow single component names in A records, so it's necessary to use a fake domain in the A records and then use CNAME aliases for the real names. This, which can be seen in the sample file, is unnecessary but permissible with MacTCP. Also note that Mac Hosts files are *not* in the same format as used by Unix and derivatives. Ping Testing ------------ A handy little Mac ping client that's useful for testing is MPing, which can be found in the following directory (at the time of this writing): ftp://ftp.apple.com/developer/Tool_Chest/Networking_-_Communications/MacTCP/ It works with both MacTCP and Open Transport. It's not quite as friendly as something aimed at ordinary users, but it works. The particular things to watch out for are: 1) Entering a CR after the target name or IP confuses it. 2) The display area doesn't scroll automatically, so repeated attempts at pinging the same machine, especially in verbose mode, might look confusing since the new results are invisible. Known Bugs and Deficiencies =========================== The only known deficiency is the noted inefficiency with single-character operations. I have seen a couple of anomalies while using it, but one was nonreproducible and the other was reproducible even without using any networking at all. Known Problems with Other Software ================================== ***WARNING*** When using FreePPP under FUSION, if a connection attempt hangs with the progress bar at about the 50% point, do NOT click on Stop - it freezes the entire machine. This is probably a FUSION serial bug, since it doesn't happen with ShapeShifter. To unhang it, go online from the other side or connect to the mating port with a comm program. I changed some handling in the driver to avoid getting to this point in the common case where the link hasn't been brought up on the other side yet, but it's still possible to get to it in more obscure circumstances. FUSION has a less serious bug in the case where the link hasn't been brought up on the other side, which causes FreePPP to hang with the connection progress bar at about the 10% point. In this case the Stop button is merely ineffective. This same symptom occurs on serial.device when the external modem is powered off, so it doesn't seem to be a bug in nullser.device. It can be unhung by bringing up the mating unit (or powering up the modem in the real serial case). Note that the Stop button is not actually ignored, it just can't be processed at this time. Bringing up the link with MiamiDx after clicking Stop in FreePPP causes the link to go up and then down again within a couple of seconds, due to the pending Stop. There is a relevant unresolved issue in the current MiamiDx beta at this time: Auto online after passive offline doesn't work reliably. This would be handy for a self-recycling link. Combining this with the "online at startup" option would make a semi-permanent listener. Et Cetera ========= Configuring multicomputer networks is a bit complicated, especially when linking two systems that each expect to be the "client". If something doesn't work at all, most likely it's a configuration problem. Report any bugs to me: Fred Wright fw@well.com