README: Eric H. Herrin II
	University of Kentucky Mathematical Sciences Laboratories
 	915 Patterson Office Tower
	University of Kentucky
	Lexington, KY 40506
	eric@ms.uky.edu, ..!cbosgd!ukma!eric 

Version 2.1

Thanks to 
1.  Mike "Ford" Ditto
    kenobi!ford@crash.CTS.COM, ...!crash!kenobi!ford
    for his bug fix in the ptyrelease routine.
2.  Michael Bloom 
    mb@ttidca.tti.com
    for his bug fix to the master read routine in the original driver.
    I incorporated this fix and it seems to work fine.

This directory contains the PD pty driver for System V, modified for
use with the AT&T UnixPC or Convergent Technologies Safari 4 computers,
running Version 3.51 of the UNIX System V OS (it may also work on
earlier versions, but I have no way of verifying this).  Anyone using
this driver should have no problems, but I will provide little support.
Questions should be sent to the above address, either with ground mail
or real (e-)mail.


This README is intended to mark the changes made to the PD pty driver to
satisfy the author's request.  It was not easy or feasible to clearly mark
every change in the code, thus it was decided that an explanation of the
procedure would probably be enough.  A brief introduction to UnixPC 
device drivers is followed by the list of changes made.  A couple of
hacks will also be explained.

NOTE: The #ifdef DEBUG statements use eprintf() instead of printf().
      This puts any messages into the error icon's queue of system 
      errors (the icon is the !! icon at the top of the console).


UnixPC device drivers:

	The UnixPC has a different kind of device driver from other 
System V machines.  They can be loaded while the machine is running or
at boot time, but are always linked into the OS while the kernel is
active.  However nice this may be, there ARE some problems.  

	1.  Loadable device drivers CANNOT communicate with one another.
	    That is, one driver cannot use a data structure defined in 
	    another driver (IE. they are not in the same identifier
	    name space).  
	2.  Conf.c doesn't exist, it is redone by the /etc/lddrv -av 
	    program and relinked into the kernel.  Thus, one can't
	    declare common structures this way.
	

Changes to the PD pty driver:

	The following changes (hacks?) were made to the PD pty driver for
the purpose of making it usable on the UnixPC.

	   Problem 1 & 2 influenced me to try to make a single driver
	   (there were two, ptm and pts).  How could one do this?
	   My solution (and I would be very interested if you can
	   think of a better one) was to create the slave devices
	   /dev/tty[p-z][0-f] with minor numbers 0-(PTYCNT/2-1) and
	   master devices /dev/pty[p-z][0-f] with minor numbers 
	   (PTYCNT/2)-(PTYCNT-1).  Major numbers of both types of devices
	   are the same. I can then simply define a macro to determine 
	   whether the dev_t passed to the driver was a slave or master 
	   pty.  Once determined, I can perform the appropriate duties.  
	   Also, it was more readable to merge the ptm and pts modules 
	   into a single set of pty[open, close, ioctl, read, write]
	   routines.  I added a release routine so that the kernel will
	   know the device has properly released if one deallocates
	   the driver. 
	   Another modification was the addition of ptystate[], which
	   holds the MRWAIT, MWWAIT, MOPEN flags.  This was necessary
	   because the original author insisted upon using 3 UNUSED
	   bits in the t_state field of the tty.  The UnixPC does not
	   have any free bits here.
	   A check for TTIOW was added due to the fix by Michael
	   Bloom in the master section of the ptyread() routine.  Note 
	   his original fixes were for the original pty driver and
	   most of the changes were already incorporated into this driver.

Making alterations to the number of ptys, etc.
	   The number of ptys is defined in the file number-ptys.h.  This 
	   number should not exceed the maximum minor device number divided by
	   two.  Ie. a maximum minor device number of 128 would allow
	   a maximum of 64 ptys.  It is currently defined at only 32, but
	   I believe this is quite liberal, especially for a machine as
	   small as a 3b1.  One could load the driver multiple times by
	   calling it a different name in the /etc/master file.  One could
	   have the first 64 ptys with major number 10, the next 64 with
	   major number 11, etc.  I think 64 should do fine for any reasonable
	   UNIX PC user (good grief, how would one use 64 ptys on a max
   	   5 user machine?  Better yet, how would one get 5 users on the
  	   thing?  Yuch!).  At any rate, we don't use that many ptys on
	   a large system with lots of users.... so I really don't see this
	   as a problem.
	   

Pty driver generation and installation procedure.
	   Put the number of ptys you want in the file number-ptys.h.
	   Type "make"
	   Type "/bin/sh MKflop"
	   Insert a floppy diskette.
	   Use the UA to install the diskette.
	   (you can skip the floppy part and simply run the Install script 
	   in the same directory the pty.o object is located.  But you
	   won't be able to uninstall it from the UA.  There is a
	   Remove script to do this which you will have to run manually.)

Acknowledgement:  I realize the usage of a single major device number is
a supreme hack, and I welcome any improvements/solutions.  I do not assume
any responsibility for the changes I have made, nor do I imply any 
liability on the part of the original author.  I include a complete set
of {Install, Remove, etc, etc} scripts so that binary floppies may be
made to be installed by the UnixPC user agent.  I do not assume any
responsibility for these either.  I don't assume any responsibility for
anything even remotely related to this stuff.


	    Eric H. Herrin II
	    University of Kentucky Mathematical Sciences Laboratories
	    eric@ms.uky.edu, !cbosgd!ukma!eric

=======================Orignal pty README===============================
This is a pseudo tty driver for system V machines. It works very
similar to ptys on BSD, for instance emacs works fine. To install this
driver you will need to modify your `master' and `dfile' file which
contains your driver specifications. As these vary from machine to machine,
you will have to look up in your manual how to do that. Here is an example
for a sperry s5050 alias ncr tower 32 :

Add the following two lines to the driver description section in master:
pts	0	237	244	pts	0	0	28	32	0	tty
ptm	0	37	344	ptm	0	0	29	0	0

This says there are max 32 pts devices at major number 28 having associated
tty structures and 0 ptm devices having major number 29 with no associated
data. The number of ptm devices is not configurable, as this depends on the
number of pts's.

The following two lines go in the dfile:
pts	0	0	0
ptm	0	0	0

Probably you will also want to increase the NCLIST parameter.

If your configuration procedure is different, you must change the shell
script mkpty, which is used to create the device nodes in /dev.

The ptm devices (/dev/pty[p-z][0-9a-f]) are the controlling ones, everything
written there will show up at the associated pts device
(/dev/tty[p-z][0-9a-f]), as well as erverything which is written on the pts
device will show up on the ptm device. The pts side will accept the usual
termio ioctl calls. The master side is a bit different, as ioctl calls which
normally wait for output to drain flush output. The reason for this funny
behaviour is that otherwise the master side will hang. Also the master side
may be opened only once, further open calls will result in an EBUSY error.
