Source Code 1992 March

home *** CD-ROM | disk | FTP | other *** search

/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 1 / 1067 / README < prev next >

Wrap

Text File | 1990-12-28 | 22.4 KB | 544 lines

README file for the FAS Final Async Solution driver --------------------------------------------------- What is this package: This is an alternate async driver for 386 based unix systems that adds several features that are not supported by vendors drivers. 1. It supports the NS16550 UART chips in full FIFO mode. 2. It supports modem sharing for input and output. Microport almost supported this feature but none of the other vendors did. 3. It supports hardware flow control. This driver should work with most of the UNIX SYS V/386 3.X ports currently available. You can have both this and the original vendor driver in the same kernel. Each driver controls its own separate set of serial ports. The only restriction here is that any int vector must not be used by more than one of the drivers. The kernel config program will complain otherwise. Note: This driver supports neither VP/ix nor DosMerge virtual serial devices. If you need COM ports for your DOS programs you have to connect the needed devices to ports that are controlled by the original vendor async driver. You won't have the special features of the FAS driver on these ports, though. If you don't need to access serial ports from DOS the vendor driver can be removed from the kernel. ------------------------------------------------------------------------ A little about what it does: This driver supports shared line usage by having two logical devices sharing one physical line. To those familiar with Microport this is very similar. For the other readers a brief description follows. For each line there are two names. For example for the first line the names are ttyF00 (minor device 0) and ttyFM00 (minor device 192). The ttyF00 is used for cu, kermit, and other programs that want to dial out. It ignores the modem signals and just goes to it. The ttyFM00 line is strictly for getty. When getty calls open on ttyFM00 the driver hangs the open until the modem asserts the carrier detect signal and then lets the open complete. If cu opens ttyF00 while getty is waiting for the open to complete the device is given to cu and the getty open must wait for cu to finish and then will again wait for the carrier. If cu tries to open the ttyF00 line while getty has ttyFM00 open cu will get an error. If getty tries to open ttyFM00 while cu has ttyF00 open the getty open will just hang and wait for cu to close the line and then wait for the carrier. To put it simply you should put up a getty on ttyFM00 with a -t 60 and use ttyF00 for cu and uucico. The modem devices ttyFMxx is the minor device of ttyFxx plus 192. There are several other possible minor devices for each port. See the description in `fas.c'. ------------------------------------------------------------------------ A little about what it supports: The driver supports and has been tested on many async cards and mux boards. It supports most combinations of shared interrupts. The current driver supports NS16450, NS16550 and um82450. It is also reported to work on the 8250B. I suspect that it will not work on some of the earlier 8250 and 8250A parts, due to various bugs and speed problems in these early parts. Since these parts have no place in an 386 or other high performance systems I did nothing to try to support them. Take a look at the various samples of space-xxxx for details of how to set up for various devices. A WORD ABOUT CHARACTER LOSSES ----------------------------- If you experienced character losses with your vendor async driver at high baud rates you shouldn't blame the vendor for that. The real reason for this problem lies in the ancient port devices used in most 386 systems: The 8250 and the NS16450. They have only one receiver character buffer. This implies that the operating system must read a character from this buffer before the next one arrives from the port's shift register. For the old IBM PC with DOS this was sufficient. But for UNIX and with baud rates up to 38400 this is simply a joke. UNIX is not a real-time operating system. That means that it's kernel isn't optimized for fast interrupt responses. With the proper hardware this is no problem. But because the vendors have to adapt UNIX to the standard hardware found in 386 systems they also have to cope with the NS16450 ports which are in there simply to be compatible with IBM PCs, XTs and ATs. It is impossible to make it work at high baud rates without a major redesign of the AT&T supplied UNIX kernel. But then it wouldn't be UNIX SYSV any more. Luckily, there is a pin-to-pin replacement available from National Semiconductors: The NS16550A. This device has separate 16 character FIFOs for the receiver and the transmitter. With these FIFOs the interrupt latency of the kernel can be quiet high without losing any characters. Additionally, because with most interrupts many characters are processed at once the system is loaded much less. As you see, the necessary hardware is available. Therefor, if you have to blame the UNIX vendor then blame him for not telling you that you should buy some NS16550A and/or for not supplying you with a serial driver that supports these port devices. But as you have the FAS driver now and if you use the NS16550A devices you shouldn't have this kind of trouble any more. This is the philosophy behind the driver's name `Final Async Solution'. Enjoy! ------------------------------------------------------------------------ Whats in this package: README This file. INSTALLATION A description about how to install the driver on your system. PATCHLEVEL Just a reference file for future updates. fas.h The header file for the driver. fas.c The driver itself. space-xxxxx These are samples of what `space.c' must look like. You can either copy one of these to `space.c' or use it as a template to create your own `space.c'. space-c1-2 For com1 and com2. space-c1-3 For com1, com2 and com3. space-mux4 For the MU-440 four line mux board. config-xxxxx This is for uPort SYS V/386 only. Kernel configuaration file. You should pick the one that matches your configuration and copy it to `config'. config-c1-2 For com1 and com2. config-c1-3 For com1, com2 and com3. config-mux4 For the MU-440 four line mux board. s_fas-xxxxx This is for ISC 386/ix only. Kernel configuration file. You should pick the one that matches your configuration and copy it to `s_fas'. s_fas-c1-2 For com1 and com2. s_fas-c1-3 For com1, com2 and com3. s_fas-mux4 For the MU-440 four line mux board. n_fas-xxxxx This is for ISC 386/ix only. Tty device nodes file. You should pick the one that matches your configuration and copy it to `n_fas'. n_fas-c1-2 For com1 and com2. n_fas-c1-3 For com1, com2 and com3. n_fas-mux4 For the MU-440 four line mux board. i_fas-xxxxx This is for ISC 386/ix only. Inittab getty lines file. You should pick the one that matches your configuration and copy it to `i_fas'. i_fas-c1-2 For com1 and com2. i_fas-c1-3 For com1, com2 and com3. i_fas-mux4 For the MU-440 four line mux board. makefile.uPort A makefile for uPort SYS V/386 systems. This is generic and should work for all configurations of lines and interrupts. makefile.ISC A makefile for ISC 386/ix systems. This is generic and should work for all configurations of lines and interrupts. ------------------------------------------------------------------------ What you will need to use this package: You will need a one of the above mentioned systems with the link kit and the software development package. ------------------------------------------------------------------------ Release History: release 1.1a Sat Nov 11, 1989 This is an unofficial release as I'm not the original author of this async driver. Uwe Doering gemini@geminix.mbx.sub.org Billstedter Pfad 17 B 1000 Berlin 20 West Germany New Features: Added a third minor tty device number for every physical port. See description preceding the asyopen function in asy.c. Changed the behavior of ttyxx, too. Added output hardware handshake support for DSR. Now you can do handshake with CTS, DSR or both. Input hardware handshake is on if you use at least one of the output handshake signals. More flexible support of additional interrupt registers on mux boards. This is fully configurable now. Added support for the CREAD flag. If not set, receiver interrupts are still serviced, but the received characters are simply thrown away. This is not as elegant as disabeling the interrupts themselves, but with the already existing driver it was the easiest way, and the most new-bugs-preventing, too. Added a lot of comments to the source so that the curious user can understand why and how things are done. Bug Fixes: The hang-up-on-last-close flag (HUPCL) was ignored. DTR was asserted regardless of this flag. Made the detection of CTS and DCD more bullet-proof. Especially because between a close and the next open of a line, where interrupts are ignored, the software copys of CTS and DCD must be set up propperly in the asyopen function or the tty line would be blocked under certain circum- stances. For similar reasons, there is also a setup in the asyparam function. Rewrote the input character processing function to work according to the TERMIO(7) man page. Changed the behavior of BREAK generation to let the transmitter drain before TX is set to low. Changed line hangup procedure so that the closing process returns immediately and doesn't sleep during the hangup delay/time. Instead, if an other process tries to open the line while hangup is still in progress, this process will sleep until hangup is competed. With DOS Merge, on MicroPort V/386 3.0e the linker was missing the function `init8250'. Reengineered this from a disassembler listing of MicroPort's original driver and modified it to work with the NS16550 16-bit FIFO. This funktion was added simply to be able to link the kernel. DOS Merge's virtual COM ports are still unusable with this release, though. To include this function, add a `-DMERGE' to the CFLAGS line in your makefile. Made a lot of other corrections and enhancements in both speed and functionallity. As a result of all my effords I think this driver is slightly faster, more versatile and much more stable than the original release. ------------------------------------------------------------ release 1.1b Sat Nov 25, 1989 New Features: Changed the minor device number scheme again. There are now two main groups: The unblocked open and the blocked open. Every group has four sub-modes and an additional hardware handshake flag. All this is coded in the higher four bits of the minor device number. Because of this, the maximum of 32 ports was reduced to 16 ports so that the port number fits into the remaining lower four bits of the minor device number. 32 dumb ports in a single machine would have been overkill anyway. For more details refer to the comment above the `asyopen' function in the file `asy.c'. ------------------------------------------------------------ release 2.00 Mon Nov 27, 1989 As this release differs so much from the original version I got, I now declare this as independant from the original author Jim Murray. This allows me to introduce new release levels without wondering whether they will collide with Jim's releases. Of course many credits to Jim for writing this software in the first place. Without his driver as a base I never would have been able to do such kernel driver development. Bug Fixes: If there were glitches on the hardware handshake lines and the DCD line a getty on this port would sometimes hang and become an immortal process. I think this was because the output buffer wasn't flushed properly on carrier loss. I hope I fixed this now. We'll see. ------------------------------------------------------------ release 2.01 Tue Nov 28, 1989 Did some cleanup in the source code. I splitted the driver into two parts: The driver itself and the file `space.c'. `space.c' contains all data structures necessary to configure the driver and is compiled at kernel link time. Therefore if you change your serial card configuration you simply change `space.c' directly in the link kit directory and relink the kernel. No driver recompilation or installation is necessary for this. But note that whenever you use `make install' your setup in the link kit directory is overwritten by the original `space.c' file. Therefore you should copy your new `space.c' back to the source directory when you are finished with the configuration. Renamed the package to `FAS Final Async Solution'. The following files have been renamed: asy.c -> fas.c asy.h -> fas.h asy_conf-xxxxx -> space-xxxxx ISC 386/ix is supported now. There are separate makefiles for uPort and ISC to cope with the differences in link kit installation. Bug Fixes: `getty' still hung sometimes on a line with hardware handshake. Tried to fix it this time. ------------------------------------------------------------ release 2.02 Thu Nov 30, 1989 Abandoned the distinction between space-xxxxx files with and without hardware flow control because this is selected by the minor device number now. Bug Fixes: Set the high and low water marks for hardware input flow control to higher values than software flow control. This gives precedence to software flow control if both methods are used. These marks are self-adjusting and don't need to be changed if some flavor of UNIX has a different buffer size than the standard 256 characters. Before this change concurrent use of both flow controls could cause trouble with some high-speed modems. This is fixed now. A flush read or write buffer request now also clears the receiver or transmitter FIFO, respectively. An ioctl call with a TCSETA* command clears the FIFOs, too. ------------------------------------------------------------ release 2.03 Fri Dec 01, 1989 Wrote an installation guide. The driver should be quite easy to install now. Added tty node configuration files for ISC. Hardware input flow control is bound now to the level of the receiver ring buffer instead of the UNIX input buffer. This has the advantage that buffer size and trigger levels are defined in the driver and therefore can be varied as needed. New Features: Added a boot time status message that shows the init state of each port. This tells you immediately what ports are found and initted by the driver. Useful to determine hardware configuration problems. Refer to file fas.c (function `asyinit') for a description. Thanks to Kritt Gierlewsen for this proposal. ------------------------------------------------------------ release 2.04 Thu Dec 07, 1989 Did some cleanup in the source. Removed the FIFO clear from the ioctl function. We don't want to do things there that aren't in the book. An ioctl call that switches off the CLOCAL flag will create a SIGHUP signal if the carrier is actually missing at this time. Every device is tested now quite thoroughly during initialization. If the test fails the corresponding device keeps unconfigured. ------------------------------------------------------------ release 2.05 Sat Jan 13, 1990 This is the first public release of the FAS driver. Special thanks to the sysops of my test sites, Axel Fischer and Kritt Gierlewsen. FAS is now an independant driver with its own driver name (`fas'), major device number, link kit directory and other things necessary for a driver. The original asy driver may or may not be linked with the kernel. You only need it if you want to access some serial devices via the virtual COM ports of the DOS emulator (DosMerge or VP/ix) because the FAS driver doesn't have this (really vendor dependant) feature. The default prefix for tty device node names is `ttyF' now. This prevents mix-ups with the device names of the original asy driver. Dropped the SYSV/AT support. I couldn't test the driver for several release generations on uPort SYSV/AT, and because there are not very much systems left with that flavor of UNIX it doesn't make sense to try to maintain compatibility with it. If someone really wants to use this driver on a 286 he has to port it himself. Improved the transmitter FIFO fill procedure. Now it will try harder to fill the FIFO as much as possible to cut down on transmitter interrupts. Software input flow control (XON/XOFF) is controlled by the driver now. It is bound to the level of the receiver ring buffer (as is hardware flow control). As usual, it can be switched on and off by the IXOFF flag in the termio structure. Changed and speeded up the ring buffer -> unix buffer processing. For ISC, the getty lines for the inittab file are installed by the makefile now. The conditional compilation of the function `init8250' (for DosMerge) is now controlled by a define in `fas.h'. The compiler switch `-DMERGE' is not used any more. Improved the documentation. The signals used for modem control and hardware flow control are fully configurable in the space.c file now. Look at fas.h for possible macros and combinations. There are some new modes for hardware flow control, for instance HO_CTS_ON_DSR. This means that CTS is only looked at if DSR is on. If DSR is off output is possible regardless of CTS. The underlying assumption here is that we can expect proper handshake handling only from devices that are in the ready state (indicated by DSR). As a spin-off the problem with the hanging getty on lines with turned-off terminals (mentioned in earlier releases) should be gone if you use this new mode. If the XCLUDE-Flag is availabe (SYSV 3.2 because of Xenix compatibility) exclusive open of a device is possible. The default size of the input ring buffer is now 5000 bytes. This makes streaming input more likely even on loaded systems. Bug Fixes: The task state busy flag wasn't reset in some rare cases. This could cause processes to become immortal while waiting for the busy flag. Under some special conditions an ioctl call with a TCSETA? command could corrupt the last character in the transmitter shift register. This is fixed now. More fixing of the busy flag handling was necessary. Co-ordinating several delayed tasks controlling this flag is kind of tricky. After a TCSETA* ioctl command we disable the transmitter for 2 sec (measured from the last transmitted character) if the character format and/or speed has changed. This gives the receiving side some time to do the same changes. This is kind of experimental. There may be applications that suffer from this delay. You may change the #define ADAPT_TIME in fas.h to a smaller value. ------------------------------------------------------------ release 2.06 Fri Mar 16, 1990 This should have been patch #3 for release 2.05, but there are so many changes now that I decided to make it a new release. Therefor some of the changes are described in the 2.05 release notes above but were never released to the public. New Features: There is a transmitter ring buffer now to make the output less system load dependent. This really speeds things up because the transmitter FIFO gets filled with more characters at once. The buffer size depends on the actual baud rate to prevent long output buffer drains at low speeds. There are also bigger input buffers to make FAS more competitive against "intelligent" cards. Lots of speed improvements and many small changes. Bug Fixes: Fixed input/output buffer flush on carrier loss while close is waiting for the output to drain. --------------------------------------------------------------------- Originally written by Jim Murray encore!cloud9!jjmhome!jjm 2 Mohawk Circle harvard!m2c!jjmhome!jjm Westboro Mass 01581 jjm%jjmhome@m2c.m2c.org USA voice (508) 366-2813 Current author: Uwe Doering gemini@geminix.mbx.sub.org Billstedter Pfad 17 B 1000 Berlin 20 West Germany