III. The ESIX 4.0.4 Device Driver

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.

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: