III. The ESIX 4.0.4 Device Driver

Most of the information in this section was originally written by Nat Cowen. I have modified it slightly to represent changes made to the system since he worked here and have re-formatted it so that it looks better (I hope).

The DSP system now uses one device driver: nir_dsp = nir_port + nir_spec. More info about creating and installing device drivers can be found in the ESIX 3.2 Driver Packet (Device Driver Release Notes). We only have a photocopy since we aren't sure where the original documentation is located. Therefore, don't lose it. Currently there are two copies.

The Driver Software Package (DSP - yes, I know this causes some confusion, but blame ESIX, not me) consists of five components: UNIX installation files, driver files, interface files, diagnostic files and documentation files. The documentation files are specified by the .doc or .ldoc endings on the filename. The .ldoc means that the file should be printed in landscape mode.

Now let us examine the different components of the Driver Software Package. First up are the UNIX installation files. These files are needed to install the device driver into the ESIX kernel. They are: Driver.o, Files, Install, Master, Name, Node, Remove, Size, System.

I have never seen NC use the Install and Remove scripts, so I usually just follow the directions in the Device Drivers Release Notes (page B-80). Following the directions for idinstall, running "idinstall -a -k nir_dsp" will install the UNIX installation files listed above into the proper /etc/conf/ directories (you may have to run idinstall by hand with different options to get this to work). The -k is needed to prevent idinstall from removing the original copies of these files. After installing the required driver files, you can build the driver by executing /etc/conf/bin/idbuild. After the first installation, if you ever want to add a new version of a driver, all you have to do is place the new Driver.o file in /etc/conf/pack.d/nir_dsp directory and recompile the kernel with the idbuild command.

The following tables describe the remaining files in /applic/dsp/csource/driver. Executing "make" in this directory will create all aspects of the device driver.

General
makefile Compile & link files.
nir_dsp.h Our #defines & data types.

Driver
dsp_driver.c Externally callable routines.
dsp_driver_port.h General port I/O.
dsp_driver_spec.h Spectrum board specific routines.
dsp_driver_tran.h Kernel <-> user transfer functions.

Interface
dsp_if.c Handles interface overhead.
dsp_if_port.h General port I/O.
dsp_if_spec.h Spectrum specific routines.
dsp_if.o Links with user programs.

Diagnostics
dsp_diag Menu driven driver diagnostics.
dsp_diag.o Links with interface object code.
dsp_diag.c Handles diagnostic overhead.
dsp_diag_port.c General port I/O.
dsp_diag_spec.c Spectrum specific routines.

Spectrum
dsp56.h Header file associated with DSP56001.
sm56dev.c Interface library for DSP56001 boards.

Documentation
dsp_driver_files.doc List of driver files.
dsp_driver.doc Detailed documentation for driver.

The following table was originally written by N.C. and I have formatted it for HTML. It describes the different functions that are used in the device driver.

Functions By Layer in the NIR DSP Device Driver (4.0) & Device Driver Interface
Programming Layers Function Types Std Overhead: Init Driver & Interface, Enable Disable Communication
Device Driver Interface C Functions Only --- nir_if_init nir_if_open nir_if_close
Unix C System Calls Calls at boot --- open close
Device Driver Driver Entry Points nirinit --- niropen nirclose
Internal Functions is_board_present --- --- ---
Unix C Port I/O Calls inb, inw --- --- ---
Programming Layers Function Types Error/Debug & Board Info: Invalid Command, Driver Params, Status of Board(s)
Device Driver Interface C Functions Only --- nir_if_show_params nir_if_status all_boards_info
Unix C System Calls ioctl ioctl ioctl ---
Device Driver Driver Entry Points nirioctl nirioctl nirioctl ---
Internal Fncts/Consts nir_invalid_command nir_show_params nir_status ---
Unix C Port I/O Calls --- --- inb, inw ---
Programming Layers Function Types Single Port I/O: One Port Read Once(Data Trans & Spectrum DSP Boards)
Device Driver Interface C functions/forth words inp outp inpw outpw
Unix C System Calls ioctl ioctl ioctl\ ioctl
Device Driver Driver Entry Points nirioctl nirioctl nirioctl nirioctl
Internal Fncts/Consts nir_inb nir_outb nir_inw nir_outw
Unix C Port I/O Calls inb outb inw outw
Programming Layers Function Types Repeated Port I/O: Multiple Ports Read Mult Times (Spectrum DSP Brds Only)
Device Driver Interface C functions/forth words rdblock16i[a] readarray16i[b] readbuffer16i[c] rdblock16q[d]
Unix C System Calls ioctl ioctl ioctl ioctl
Device Driver Driver Entry Points nirioctl nirioctl nirioctl nirioctl
Internal Fnctns/Consts nir_rdblock16i nir_readarray16i nir_readbuffer16i nir_rdblock16q
Unix C Port I/O Calls inb, outb inb, outb inb, outb inb, outb
[a] Current generation of device driver uses rdblock16buf.
[b] Can be thought of as ``readimage''.
[c] Can be thought of as ``copyimage''.
[d] Same as rdblock16i, except that instead of interleaving the data by columns, is is interleaved by quadrants.
[b], [c], and [d] have not yet been written.

More information can be found in the device driver directory on the ESIX machines, as well as in the following N.C. directories:

~nat/programming/device_drivers/doc
~nat/programming/device_drivers/esix_4.0_drivers/nir_4.0_dsp