Mux serial port driver for NS/Intel

NeGeN/NiNe/R&A distribution [1.0]
(version: Mux 1.7)
May 1995

For more info contact: <negen-connect@negen.twi.tudelft.nl>

This is the binary distribution of Mux, Mark Salyzyn's serial port driver for NS/Intel, as brought to you by NeGeN/NiNe (the Dutch NEXTSTEP user group) and R&A.  It is meant as a replacement of the (notoriously slow/inefficient/buggy) SerialPorts driver that comes with the standard NEXTSTEP distribution.  If you need a reliable, high speed serial connection, for instance with Taylor UUCP or a SLIP or PPP link, you should seriously consider upgrading to Mux. 

Mux is distributed as an easy-to-install NEXTSTEP Installer package aptly named Mux-version.I.b.pkg, which not only contains the compiled Mux.config driver, but also tries hard to configure and add itself to the system configuration when it is unpacked.

This README file contains some (hopefully helpful) hints to assist you in creating a configuration that is right for your system.

IMPORTANT: you must install this package as "root".  This is because some system configuration files must be edited in the configuration process.  If you don't know how to become "root", you'll have to ask your system administrator to install this package.  (If you are your own system administrator and you still don't know how to become "root", you have a serious problem:-)

INSTALLATION

The installation creates the driver Mux.config in the directory /NextLibrary/Drivers, and asks you to choose from a list of standard configurations, listed below, to configure the driver.  Also it installs Mux as an active driver in the System configuration (and removes the SerialPorts driver when applicable), so normally you don't need to do anything in Configure.app in order to install Mux once you installed this package  (of course it's always a good idea to run Configure to check that everything went as planned...)

You can choose, amongst others, one of the following configurations:
 
 · COM1,COM2
 	Drop-in replacement of the SerialPorts Driver.

 · COM1,COM2,COM3,COM4
 	Replace and augment the base capabilities of the SerialPorts Driver for up to 4 `dumb' ports.

 · COM1,COM2,DigiBoard4
	Mix regular and multiplexed serial ports, all controlled by the Mux Serial Port driver.

 · SerialPort,COM2
 	Use the COM1 SerialPorts driver for a SerialMouse instance, and use the Mux driver to handle the high speed communications on COM2.

 · SerialPorts,DigiBoard8
 	Another example of mixing the SerialPorts and Mux drivers. Note the setting of the various Path variables in the Mux Instance.

A backup is made of every file that has been changed during the installation.

If you have already installed the Mux package, and you want to change the configuration without re-installing the entire package, you can run the shell script <package-name>.post_install in the package wrapper by hand in a terminal window.

From the original Mux README

[...]

This serial driver is used to add additional ports starting at ttyc and
onwards. I have managed to get reliable 57600 Baud operation with this driver
under NeXTSTEP/FIP with the 16550s of either a single additional port, or
on the multiplexed 4 or 8 port DigiBoard cards.

I have had reports of speeds into the 3600c/s region for this driver! I get
only 870ch/s from the SerialPorts driver, and my machine crashes if I try
using it at 19200 Baud ... I can calmly say: 500M of news flow over a three
day period, at 57600 Baud (to a 14400 Baud modem), has not crashed the machine!

You are free to use this source in any way you wish, but credit must be given
to California Regents Berkeley, Carnegie Mellon University, Olivetti (for their
original work) and Mark Salyzyn.

This driver is designed to work as a DigiBoard and AST Style multiple serial
I/O cards, single port *any* address *any* interrupt, or multiple port (no mux
register) shared interrupt (use a 470 ohm resistor in parallel with a diode to
provide the wired-or [active high] connections for the IRQ lines).

Refer to the README in the Configurations directory for more details on
setup hints for odd configurations. The Default.table that is shipped is
adequate for use with the standard two port serial system, and extensible to
a four port system simply using the configuration inspector.

Bugs:

The AST standard, a far more modern one, is not yet tested, and without
one of these cards, I am at a loss to provide testing for it. It *may* work if
you don't specify a multiplex register or specify a Mux register with a port
range of 1.

The Default Inspector does not work adequately on multiplexed boards except to
set the interrupt, it has no concept of multiple port addresses (except in NS3.3
using the Expert button). If you use it to set up the port, it will work
adequately for a single port card added into the system though. Under NS3.2, It
is recommended to use an editor to manipulate the
/NextLibrary/Devices/Mux.config/Instance0.table (but keep in mind that you do
this at your own risk, drop me a note if you want some confidence pills ...)
yourself after the Config Application is finished and saved to add in the
additional ports on a Interrupt Multiplexed card, or to adjust other
characteristics of the driver. An address range of 1 or 2 bytes is assumed to
be the multiplex register, and must be stated last in the set of serial port
ranges (with a range of addresses of 1[AST] or 2[DigiBoard]).
[Editor's note: When you install Mux from the Installer package, it lets you choose one of the predefined configurations, and installs it in the Mux.config wrapper itself.  So normally there should be no need to dive in with an editor.]

The SerialMouse driver doesn't like this driver at all because of hard coded
checking done within the Configure and Loading of the driver application to
ensure that the SerialPorts driver is loaded. Since a 1200 Baud serial mouse
hardly is a problem for the original SerialPorts driver, a `cook book'
arrangement is documented to set the system up in the Configurations
subdirectories. When mixing the SerialPorts and Mux drivers, one must be very
careful about the NXString variables associated with device paths.
[As stated above, the Mux Installer package should take care of this.]

With the addition of the RTS side of the RTS/CTS handshaking, the driver
no longer overloads the Kernel beyond TTYHOG on streaming protocols. You can
control the size of the Receive and Transmit buffer by editing the
Instance?.table files, or using the Expert button in the configuration
application under NeSTSTEP 3.3, but once again, I remind you that you do this
at your own risk (This driver in itself may void any warantees and service
contracts).

[...]

Please send ALL bug reports (and any code fragments you wish added) to
mark@ve6mgs.ampr.ab.ca (Mark Salyzyn). I am interested in any work you feel
will improve this project.

Legal ease:

If you feel compelled to donate an amount that would appear to compensate me
for my efforts in writing and maintaining this driver, I would appreciate
receiving said funds. Contact me for my current fixed address.

Ciao -- Mark Salyzyn

Mux README.rtf 1.0, 1995/05/05 20:50:47.  Copyright ã1994,1995 R&A..