ddeevviiccee ddrriivveerrss -- Overview

A  _d_e_v_i_c_e _d_r_i_v_e_r  is  a program  that  controls the  action of  one of  the
physical  devices attached  to your computer  system.  The  following table
lists  the device  drivers included  with the  COHERENT system.   The first
field gives  the device's major  device number; the second  gives its name;
and the  third describes  it.  If  a major number  does not appear  in this
table, that number is available for a driver yet to be written.

 0:  nnuullll      The ``bit bucket''
 0:  mmeemm       Interface to memory and null device
 0:  kkmmeemm      Device to manage kernel memory
 0:  kkmmeemmhhii
 0:  cclloocckk     System clock
 0:  ccmmooss      System CMOS
 0:  ppss        Processes currently being executed
 0:  iiddllee      System idle time
 1:  cctt        Controlling terminal device (/ddeevv/ttttyy)
 2:  ccoonnssoollee   Video module for console (/ddeevv/ccoonnssoollee)
 2:  kkbb        Non-configurable keyboard driver, /ddeevv/ccoonnssoollee
 2:  nnkkbb       Configurable keyboard driver, /ddeevv/ccoonnssoollee
 2:  vvttkkbb      Non-configurable keyboard driver, virtual consoles
 2:  vvttnnkkbb     Configurable keyboard driver, virtual consoles
 2:  mmmm        The video driver
 3:  llpp        Parallel line printer
 4:  ffdd        Floppy-disk drive
 4:  ffddcc       765 diskette and floppy-tape controller
 4:  fftt        Floppy-tape drive
 5:  aassyy       Serial driver
 8:  rrmm        Dual RAM disk
 9:  ppttyy       Pseudoterminals
11:  aatt        AT hard disk
13:  hhaaii       Host adapter-independent SCSI driver
13:  aahhaa       Older driver for Adaptec SCSI hard disks
13:  ssss        Older driver for Seagate SCSI hard disks

Please note that the devices with major number 0 are not portable, and non-
DDI/DKI.  Also  note that  in future releases  of COHERENT, the  hhaaii driver
will be  divided into  several optional  SCSI host-bus adapters  (HBAs) and
target devices.

It is  not unusual  for one  major number to  admit several  driver service
modules.  Instances of this include the following major numbers:

00  This number is for a number of system-dependent drivers.

22  This  number supports  the console,  both its  keyboard modules  and its
   video modules.

44  This describes varieties  of floppy-disk and floppy-tape controllers and
   drives.

1133 This describes  a number of  SCSI host modules, HBA  modules, and target
   modules.

_M_a_j_o_r _a_n_d _M_i_n_o_r _N_u_m_b_e_r_s
COHERENT uses a system of _m_a_j_o_r  and _m_i_n_o_r device numbers to manage devices
and drivers.   In theory,  COHERENT assigns a  unique major number  to each
type of  device, and a unique  minor number to each  instance of that type.
In practice, however, a major number describes a device driver (rather than
a device _p_e_r _s_e).   The  individual devices  serviced  by  that driver  are
identified by a minor number.  Sometimes, certain parts of the minor number
specify configuration.   For example, bits 0 through 6  of the minor number
for COHERENT RAM disks indicate the size of the allocated device.

_O_p_t_i_o_n_a_l _K_e_r_n_e_l _C_o_m_p_o_n_e_n_t_s
The kernel also contains the following optional components:

eemm8877      Emulate hardware floating-point routines
mmssgg       Perform System V-style message operations
sseemm       Perform System V-style semaphore operations
sshhmm       Perform System V-style shared-memory operations
ssttrreeaammss   Perform STREAMS operations

These  components  resemble  device  drivers,  in  that that  they  perform
discreet work and can be linked  into or excluded from the kernel, as shown
below.  However, they do not perform I/O with a device, and so are not true
drivers.  For details on these modules, see their entries in the Lexicon.

_C_o_n_f_i_g_u_r_i_n_g _D_r_i_v_e_r_s _a_n_d _t_h_e _K_e_r_n_e_l
Beginning  with  release 4.2,  COHERENT  lets you  tune  kernel and  driver
variables,  enable or  disable  drivers, and  easily build  a new  bootable
kernel that incorporates your changes.

The command iiddeennaabbllee lets you enable or disable a driver within the kernel.
The  command iiddttuunnee  lets  you set  a user-modifiable  variable within  the
kernel.   Finally,  the   command  iiddmmkkccoohh  generates  a  new  kernel  that
incorporates  all changes  you  have made  with the  other three  commands.
Changes are entered  with iiddeennaabbllee and iiddttuunnee do not  take effect until you
invoke iiddmmkkccoohh to generate a new  kernel, and boot the new kernel.  Scripts
/eettcc/ccoonnff/*/mmkkddeevv  simpify  the  choices  of  iiddeennaabbllee  and  iiddttuunnee  during
installation  and  reconfiguration: they  invoke  iiddttuunnee  and iiddeennaabbllee  For
details, see these commands' entries in the Lexicon.

_A_d_d_i_n_g _a _N_e_w _D_e_v_i_c_e _D_r_i_v_e_r
The  commands described  above make  it easy  for you to  add a  new device
driver to your COHERENT kernel.

The following walks you through the  processing of adding a new driver.  We
will add the driver ffoooo, which enables the popular ``widget'' device.

11. To begin, log in as the superuser rroooott.

22. The next step is to create  a directory to hold the driver's sources and
   object.   Every  driver  must have  its  own  directory under  directory
   /eettcc/ccoonnff;  and  the sources  must  be  held in  directory  ssrrcc in  that
   driver's directory.  In  this case, create directory /eettcc/ccoonnff/ffoooo; then
   create directory /eett/ccoonnff/ffoooo/ssrrcc.

33. Copy the sources for the driver into its source directory; in this case,
   copy them into /eettcc/ccoonnff/ffoooo/ssrrcc.

44. Create   a   MMaakkeeffiillee  in   your   driver's   source  directory,   e.g.,
   /eettcc/ccoonnff/ffoooo/ssrrcc/mmaakkeeffiillee. The  easiest way to see  what is required is
   to review several of the driver MMaakkeeffiillees shipped in the COHERENT driver
   kit.  You can perform a test  compilation of your driver by running mmaakkee
   with the  driver's ssrrcc directory as the  current directory.  This should
   create one  object file that has  the suffix .oo.  Copy  this file in the
   driver's home directory, and name  it DDrriivveerr.oo. In this case, the object
   for the  driver should be  in file /eettcc/ccoonnff/ffoooo/DDrriivveerr.oo.  In some rare
   cases, a driver compile into more than one object.  You should store all
   of these  objects into one archive; name the  archive DDrriivveerr.aa and store
   it in the driver's home directory.  The COHERENT commands that build the
   new kernel know how to handle archives correctly.  The main idea is that
   files SSppaaccee.cc (if one exists) and  DDrriivveerr.oo or DDrriivveerr.aa be placed in the
   driver directory, i.e., the parent of the ssrrcc directory.

55. Add an  entry to  file /eettcc/ccoonnff/ssddeevviiccee  for this driver.   ssddeevviiccee, as
   described above,  names the drivers  to be included in  the kernel.  The
   entries for practically every entry are identical; you need to note only
   that  the second  column  marks whether  to  include the  driver in  the
   kernel.   In this  case, the  entry for  the driver  ffoooo should  read as
   follows:

       foo Y   0   0   0   0   0x0 0x0 0x00x0

   For  details  on what  each  column  means, read  the  comments in  file
   /eettcc/ccoonnff/ssddeevviiccee.

66. Add an entry to file /eettcc/ccoonnff/mmddeevviiccee for the new driver.  This file is
   a  little more  complex than  ssddeevviiccee;  in particular,  it distinguishes
   between  STREAMS-style drivers and  ``old-style'' COHERENT  drivers.  In
   most cases, you  can simply copy an entry for  an existing driver of the
   same type,  and modify  it slightly.   In this case,  the entry  for ffoooo
   should read as follows:

       # full  func    misc    code    blockchar minor minor dma cpu
       # name  flags   flags   prefix  majormajor min max chan id
       foo -   CGo foo 15  15  0   255 -1-1

   In almost every  case, the full name and the  code prefix are identical.
   The code prefix also names the directory that holds the driver's object.
   Function  flags are  always  always a  hyphen,  and miscellaneous  flags
   almost always  CGo.  The  block-major and character-major  numbers again
   are almost  always identical.  The  major number is  usually assigned by
   the creator  of the  device driver.  In  future releases of  the kernel,
   these will be assigned  dynamically by the kernel itself; poorly written
   drivers that  depend upon the driver having  a magic major-device number
   will no  longer work.   Finally, the  last four columns  for non-STREAMS
   drivers are  almost always  0, 255, -1,  and -1, respectively.   See the
   comments in file /eettcc/ccoonnff/mmddeevviiccee.

77. If the  driver has tunable  variables, these should  be set in  the file
   SSppaaccee.cc, which  should be stored in the driver's  home directory.  As it
   happens, ffoooo does not need a  SSppaaccee.cc file.  For examples of such files,
   look in the various sub-directories of /eettcc/ccoonnff.

88. Type the command iiddmmkkccoohh to build  a new kernel.  If necessary, move the
   new kernel  into the root directory;  you cannot boot it  until it is in
   the root directory.

99. Save the  old kernel and link  the newly build kernel  to /aauuttoobboooott. You
   want save  the old kernel, just  in case the new  one doesn't work.  For
   directions on how to boot a kernel other than /aauuttoobboooott, see the Lexicon
   entry for bboooottiinngg.

1100.
   Back up your files!  With a new driver in your kernel, it's best to play
   it safe.

1111.
   Reboot your system to invoke the new kernel.  If all goes well, you will
   now be enjoying the services of the new device driver.

For scripts  on how to add  or remove individual drivers  from your kernel,
see the article of the driver in question.

_S_e_e _A_l_s_o
AAddmmiinniisstteerriinngg CCOOHHEERREENNTT, aassyy, aatt, bboooott, ccoonnssoollee, cctt, eemm8877, ffllooppppyy ddiisskk, hhaarrdd
ddiisskk,  iiddllee,  kkeerrnneell,  llpp, mmbboooott,  mmddeevviiccee,  mmeemm,  mmssgg,  mmttuunnee, nnuullll,  ppssyy,
ssddeevviiccee, sseemm, ssggttttyy, sshhmm, SSTTRREEAAMMSS, ssttuunnee, ttaappee, tteerrmmiioo

_N_o_t_e_s
Note that in future releases of COHERENT, major numbers will not be static,
as  they are  in the  above table.   Rather, they will  be assigned  by the
ccoonnffiigg script when you install COHERENT onto your system.  This scheme will
allow more  flexible arrangements of drivers, and  will also allow COHERENT
to support  more than 32 drivers  at once.  If you write  code to work with
device drivers, you should _n_o_t  make any assumptions about a given driver's
major or minor number.

See  the Release  Notes for  your release  of COHERENT for  a full  list of
supported devices and device drivers.

Source code for all COHERENT device  drivers is published in version 4.2 of
the  COHERENT Device-Driver  Kit, with  the exception  of drivers  that use
proprietary information from  manufacturers.  Experienced writers of device
drivers  will find  the driver  kit a  good tool  for writing  or importing
drivers for devices that COHERENT does not yet support.
