	This directory contains a number of network, disk and other
drivers.  Attached at the end of this document is the original README.

	Believe it or not, you won't have to really understand how a driver
works in order to install it.  Just follow the bouncing ball ...  Note that
some of the old `glue' used to patch drivers in this directory can be found
in the "GLUE" subdirectory.

STEP #1:
--------
	Install the source code in the proper directory.  A pdp MASSBUS
driver would go in pdpmba, a pdp UNIBUS driver would go in pdpuba.  In
reality (the present system) all drivers are in pdpuba regardless of
being MASSBUS or UNIBUS.  We'll use the versatec driver as an example.  
Since it's a UNIBUS driver, we'll move vp.c into pdpuba.  If you're installing 
a driver from the OTHERS directory, or you've got a local work of art that 
you wish to use, there are a few things you should check so that it will 
work correctly with 2.11BSD:

	Note, in the following examples, "XX" is the two or three letter
	designation that device drivers under UNIX get assigned, e.g. "vp"
	for the Versatec driver, "vv" for the Pronet driver, etc.

	a) The XXattach routines should return 1 on success, 0 on failure.

	b) If your XXread and XXwrite routines use physio(), make sure that
	   you're passing the correct number and types of arguments.

	   Between the initial release of 2.11BSD and the present the 
	   WORD/BYTE argument (added between 2.9 and 2.10) was removed.
	   If it is important to enforce alignment this can be done in
	   either the strategy routine or in XXread/XXwrite before calling
	   physio().

	c) The XXread and XXwrite routines should return 0, if successful,
	   and the correct errno value (for later assignment to u.u_error)
	   if they fail.  All the XXread and XXwrite routines which only
	   called physio() have been removed (the common routines rawread()
	   and rawwrite() replacing XXread() and XXwrite() in the cdevsw[]
	   table).

	   Note:  If XXread() and/or XXwrite() only calls physio() then
	   the XXread and XXwrite entry points can be removed and the common
	   routines 'rawread', 'rawwrite' used in the cdevsw[] table.  See
	   the entries for any of the disc or tape drivers for examples of
	   this.

	d) The XXioctl routine has changed a *lot* between 2.9 and 2.11:

		+ XXioctl() now takes four arguments, (dev, cmd, data,
		  flags) a device (dev_t), the ioctl command (u_int), a
		  buffer address (caddr_t), and some flags (int).  Of real
		  interest is the command, which is the low order 16 bits
		  of the ioctl command.  Ioctl's in user land are 32 bits.
		  The low order word contains the ioctl command itself, the
		  high order describes any necessary argument transfers
		  between the kernel and user process.  See sys/ioctl.h for
		  macros IO, IOR, IOW and IORW that implement this.
		  Sys/mtio.h is a good file to look at for how to add the
		  correct definitions to your include file.  THIS IS THE
		  TRICKY PART!!  Look at how other device drivers handle this.

		+ XXioctl() no longer copies anything in or out of user
		  land.  The new upper word of the ioctl "cmd" allows the
		  ioctl system call to perform all necessary transfers
		  between the kernel and the user process.  See the kernel
		  ioctl() routine for more info.

		+ XXioctl has to return 0 on success, or the correct errno
		  value for later assignment to u.u_error.

	e) Make sure that you handle buffer allocation correctly.  If you
	   wish to be portable, there should be allocations of mapping
	   registers using mapalloc() for UNIBUS mapped machines, ifdef'd
	   on "UNIBUS_MAP".  You should ifdef *real* 22-bit QBUS addressing
	   with the define "Q22" (see the comments in conf/GENERIC and
	   pdp/machdep2.c.)  Buffer cache buffers have to be mapped in to
	   be accessed in 2.9BSD and 2.11BSD.  I don't really understand
	   how it worked before then, but some of the drivers in the OTHERS
	   directory predate that, so be paranoid.

	f) The device addresses and partition table sizes should be
	   included in the device driver itself, not in ioconf.c (which
	   is used for an entirely different purpose now.)  See the drivers 
	   in pdpuba for examples.

	g) You should have an XXopen() routine that validates the unit
	   number for the read, write, and ioctl system calls.  See the
	   the drivers in pdpuba for examples.  Normally they will look
	   something like:
		XXopen(dev)
			dev_t	dev;
		{
			if (minor(dev) > XXRL || !XXADDR)
				return (ENXIO);
			return (0);
		}

	   If you've already got the driver lying around, the XXstrategy
	   routine probably already does this.  The read/write/ioctl
	   routines *MAY* do it, i.e. you can rip it out of them once
	   you've got the open routine working.  Note, make sure that
	   you don't assign an absolute address to XXADDR when you declare
	   it (a lot of old drivers do) as it negates the test of
	   XXADDR in XXopen().  Also, a lot of old drivers use the minor
	   numbers in strange and wonderful ways; don't assume that the
	   above test, "minor(dev) > XXRL", is correct for your device.
	   Anyway, this is a Very Important Thing.  If you don't do this
	   fix right, interesting things will happen when someone accesses
	   a device for which you have a node in /dev, but which doesn't
	   really exist.

STEP #2:
--------
	Write some code that will attempt to "probe" the routine.  See any
of the other device drivers for examples.  Install this code in the
"sys/autoconfig" directory, only call it "XXauto.c", where XX is
the prefix for the driver.  In our example, we'll install it as
"sys/autoconfig/vpauto.c".  This is the code that is used by the auto 
configuration program to get to the device.  By convention, this routine 
must be named "XXprobe()".  It's also useful to check and see if any of 
the probe routines already written would be identical to your probe routine.
For example, the "xpauto.c" file contains the probe routine for several 
flavors of disk drive.  If you're porting a 4BSD driver, it probably 
already has a probe routine in it which may be close to what you want.  
Also, in any case, rip the XXprobe stuff out of the main file ... it is never 
used by the kernel and it just wastes text space.
	Previously the XXauto.c files were kept in the same directory as
the device drivers themselves.  This lead to the misleading assumption that 
'/etc/autoconfig' would automatically be rebuilt if the probe routine in
the XXauto.c files in sys/pdpuba were modified.  To clarify matters the 
XXauto.c files were moved into the sys/autoconfig directory.

STEP #3:
--------
	Go to the auto configuration directory, "sys/autoconfig" and update
the "DOBJS" and "SRCS" defines to reflect the existence of the new device
driver.  Our example would add "vpauto.c" to the "SRCS" define, and
"vpauto.o" to the "DOBJS" define.  Update the source file
"sys/autoconfig/uprobe.c" to reflect the existence of the new device
driver.  Basically, you have to define the "vpprobe" routine and then add a
new line to the "uprobe" table.  For our example, we'd add:

	int	vpprobe();

at the beginning of the file and:

	"vp",	vpprobe,	/* vp -- Versatec */

in the "uprobe" table.

STEP #4:
--------
	Update the "/etc/dtab" table to reflect the new drive.  You may be
able to simply uncomment an existing line, otherwise, figure out the
correct values for each field and write a new one.  Our example needs an
entry of the format:

	# vp	? 177500 174	4	vpintr		# Versatec

Where "vp" is the letter designation, "?" means that we aren't assigning a
specific unit number (the normal case), 177500 is the address of the
device, 174 is the interrupt vector, 4 is the interrupt priority level
(Br), and "vpintr" is the handler(s) as designated in the file "scb.s".

STEP #5:
--------
	In scb.s you'll need to add an interrupt interface:

	a) Add an include of "XX.h" to the top so that the presence or
	   absence of the driver can be determined.

	b) If the driver is for a disk you'll need to add an interrupt
	   vector definition so that device interrupts can be caught.  In
	   general this won't have to be done for most devices because
	   /etc/autoconfig will assign, initialize and probe the device
	   after the system has booted.  Disks have to have their interrupt
	   vectors already set up at boot time for obvious reasons.  For
	   convenience several of the networking drivers are also hardwired
	   in, but that probably wasn't necessary.  The Versatec, for instance,
	   does not need an interrupt vector set up at boot time, so its
	   vector will be set up by /etc/autoconfig.

	   If an interrupt vector is needed, it can be added by determining
	   the device's interrupt vector address, IADDR, and then adding
	   lines of the form:

		#if NXX > 0
			DEVTRAP(IADDR, XXintr, brX)
		#endif

	   numerically in order with the other sets of lines like the above
	   already present in scb.s.  "IADDR", as mentioned above, would be
	   the devices interrupt vector address, "XXintr" is the name of
	   the interrupt handling routine in the C source of your driver,
	   and "brX" is the priority level that the device interrupts at.
	   Note that "XXintr" is the handler name that would be added to
	   /etc/dtab.  Also note that some devices have more than one
	   interrupt vector that must be set up.

	   If (and it doesn't!) the versatec needed an interrupt vector
	   assigned at boot time, it would look like the following:

		#if NVP > 0
			DEVTRAP(174, vpintr, br4)
		#endif

	c) Finally, add an interrupt interface thunk in the last half of
	   scb.s to correspond with the new device's interrupt vector(s).
	   These small thunks catch the device's interrupts and hand
	   control off to the the real handler routine after first saving
	   the machine's current context by (essentially) passing the
	   address of the real handler to the routine "call" in pdp/mch_trap.s.

	   The following would be added for the Versatec driver:

		#if NVP > 0
			HANDLER(vpintr)
		#endif

STEP #6:
--------
	Update the conf.c file (it used to be called c.c, in previous
incarnations).  This file needs to have an include line for the .h file
that will determine if this driver gets included in the kernel, a set of
defines so that the kernel can compile correctly whether you not you choose
to include the driver, and entries in the block and/or character device
switch tables.  For our example we would add:

#include "vp.h"
#if NVP > 0
int	vpopen(), vpclose(), vpwrite(), vpioctl();
#define	vpstrategy	nulldev
#else
#define	vpopen		nodev
#define	vpclose		nodev
#define	vpwrite		nodev
#define	vpioctl		nodev
#define	vpstrategy	nodev
#endif	NVP

to the character device definition section of conf.c, and

/* vp = 20 */
	vpopen,		vpclose,	nodev,		vpwrite,
	vpioctl,	nulldev,	0,		SELECT(nodev),
	vpstrategy,

to the character device switch table (cdevsw[]).

The strategy member of the cdevsw[] structure is new since 2.11BSD was 
released.  Since VP does not have a strategy routine a dummy definition 
is created.  Other devices (such as disc and tape drivers) do have
strategy routines and their entries look like:

#include "tms.h"
#if NTMS > 0
int	tmscpopen(), tmscpclose(), tmscpstrategy(), tmscpioctl();
#else
#define	tmscpopen	nodev
#define	tmscpclose	nodev
#define	tmscpioctl	nodev
#define	tmscpstrategy	nodev
#endif

/* tmscp = 23 (tu81/tk50) */
	tmscpopen,	tmscpclose,	rawread,	rawwrite,
	tmscpioctl,	nulldev,	0,		seltrue,
	tmscpstrategy,
};

	Note, in our example, we've been assuming that NVP is the define that
governs whether or not the device is included, as well as how many of them
we have.  For example, "#define NVP 5" in the file "vp.h" means that we
have 5 of the devices, and "#define NVP 0" means that we don't even include
the driver.  More on "vp.h" a little later.

	Since the versatec is a character device only, it only gets
included in the character device switch table, "cdevsw[]". (for a disk
driver, for instance, you would have entries in both the character and
block device switch tables) The entries in the table correspond to the
routines that get called when you open a versatec, close a versatec, etc.
etc.  See the include file "sys/conf.h" for more information on what the
fields in the block and character switches mean.  The easiest method to
make a new entry is to find a device that looks like yours and do what it
does.

	Note, the "major" number that you'll use later when you add the node
to the "/dev" directory is the offset into this table, or, in the above
example, 20.

STEP #7:
--------
	Next, update the following files: "conf/GENERIC", "conf/config",
"conf/Make.pdpuba" (or "conf/Make.pdpmba" or "conf/Make.net"), and
"conf/Makefile".  Basically, add lines of the form:

NVP		0		# Versatec
VP_TWOSCOMPL	NO		# interface needs two's complement bytecount

in "conf/GENERIC".  These are the lines that get changed when you want to
configure a new system.  Some drivers may only need a single line to
describe the number of devices to be configured in, others, like the
Versatec need auxiliary configuration information.  Change "conf/config"
to do the intelligent thing with those lines, i.e. something like

echo "#define NVP	$NVP"		> ../$MACHINE/vp.h
if [ $VP_TWOSCOMPL = YES ] ; then
	echo "#define VP_TWOSCOMPL"	>> ../$MACHINE/vp.h
fi

which will place the appropriate defines for the Versatec into vp.h.
Obviously, the source code for your driver should modify its behavior based
on the defines found in its include file.

	Note that if you do have additional configuration options for your
driver they *should* be put into conf/GENERIC with appropriate comments.
Don't hide them in pdpuba/vpreg.h for instance - that's the way things used
to be done in 2.9BSD and earlier, making it extremely difficult to
configure a system.  With all of the relevant options in one place
(conf/GENERIC) it is very simple for the person configuring a new system
to just `check off' the items they want.

	Finally, add the resulting object file names for your device
driver to "conf/Makefile" and "conf/Make.pdpuba" (or "conf/Make.pdpmba"
or "conf/Make.net").  The former just needs to know the name so it can
load it; the latter must be able to compile the file.  Be careful where
you have "conf/Makefile" load your object as certain things have to be
loaded in special places; in general, just put your object name in an
overlay or the base segment.

STEP #8:
--------
	You should also edit "dev/MAKEDEV.local" to make nodes with the
correct major/minor numbers in the /dev directory.  The major number for
character devices is the offset of the device's entry in cdevsw[], and
the major number for block devices is the similar offset in bdevsw[].

	One final note, we've had fair success with porting 4BSD drivers.
You just have to rip out all of the stuff that understands about multiple
UNIBUS's and you're halfway there.  Two things you have to check; it may
play pretty loose and casual with buffers since it doesn't cost anything to
have them.  It's EXPENSIVE on the PDP-11, because you have to do a mapin()
every time you want one, plus, you can only have one at a time!!  Look for
calls to geteblk(), it's a dead giveaway.  Also, MBUF allocation is
different in the two systems, if the driver goes for one of them, take a
long look at it.

	As far as the various device drivers in this directory, note that
comments like "will probably converted soon" and "should work without
modification" are probably now specious.  While comments like "is untested",
"might work with ...", etc. should be taken to mean "it didn't work on
2.9BSD and you'd probably be better off rewriting it from scratch or buying
an IBM PC" ...

	Several of the drivers in the OTHERS directory should eventually
be removed because working versions exist in the pdpuba directory.  These
are the ts-11 (OTHERS/ts - pdpuba/ts.c), rp04/rp06 (OTHERS/rp04.06 - 
pdpuba/xp.c), TMSCP (OTHERS/tk - pdpuba/tmscp.c), RX01&RX02 (OTHERS/rx01, 
OTHERS/rx02 - pdpuba/rx.c), MSCP (OTHERS/ra - pdpuba/ra.c), TU-16 (OTHERS/ht -
pdpuba/ht.c), rm02/rm03/rm05 (OTHERS/rm02.03.05 - pdpuba/xp.c), Fuji-160
(OTHERS/fuji_160 - pdpuba/xp.c), dm11 (OTHERS/dm11 - pdpuba/dh.c).


Keith Bostic & Casey Leedom (revised by Steven Schultz)

ORIGINAL README:
----------------
	The device drivers in this directory are here because they are
untested, or have not been completely converted to use new ioctl or
buffering protocols, or because they are of limited interest or use.  Some
of them have comments at the beginning describing their state.  If you test
and/or finish any of these drivers, please let the 2BSD project know about it.

	The dc and dj drivers don't have the current ioctl mechanism.  They
are untested.

	The dmc and du drivers don't know how to handle system buffers,
since there are no in-address-space buffers any longer.  They could
probably be made to work with dedicated buffers or mapped-in buffers.  The
bk driver (berknet line discipline) also has this problem, but will
probably be converted and tested soon.  It has never worked on PDP11's to
my knowledge.

	The rx2, rx3 and ml drivers have been modified only slightly from
working versions received from the authors.  They will probably work
without modification.

	The multiplexor driver has not been made to work with anything like
the current system.  It is unmodified (as far as I know); if you try it,
check the order and types of arguments to the external entry points.

	The cr (card reader) driver is probably flaky, at least with this
system.
