dio-fishcamp dio driver for linux 2.2.xx and 2.4.xx

LICENSE: distributed under GPL

AUTHOR: Matt Clark matt.clark@nottingham.ac.uk 
DATE: October 2001


VERSION: 0.5 beta

STATUS: tested under kernel 2.2.16 / 2.2.17 / 2.4.2 all x86

PROVIDES: Binary device driver /dev/dio and Text device for
scripts /dev/dio_port0, /dev/dio_port1, /dev/dio/port2,
/dev/dio_allports

INSTALLATION:
In any clean directory

>make
#requires root permission
>make clean #or ./install_dio

deINSTALLATION:
#requires root permission
>./remove_dio

Note: The major device number is dynamically allocated and
catered for in the installation script.

No automatic module configuration is provided, the device
driver will not be there on reboot- automating this depending
on your preference and system, see man module.conf.

Device driver file nodes: The installation scripts create
file nodes /dev/dio, /dev/dio_port0 etc

>ls /dev/dio*

The main device is /dev/dio and can be treated as a standard
device (below).

The additional devices are "text support"- simple text in and
out primarily aimed at simplifing scripts- we like this in
our group as it makes rapid construction of quick experiments
easy. You can "cat" the devices to get a text readout of the
ports and pipe in text values to set the ports. Note that
word wide direction setting applies to these text devices.

USAGE:
TEXT: 
Reading:
to read the values on the ports just use cat, eg.
>cat /dev/dio_port0
ffffffff
#reverts to ffffffff if pins are unconnected

to read all three ports 
>cat /dev/dio_allports

Writing:
to write to the ports pipe the values in, eg
>echo "f0f0f0f0" > /dev/dio_port0
or
>echo "f0f0f0f0 12345678 5" > /dev/dio_allports

Technical notes on text devices:
*All transfers are in hex.

*Error checking is confined to keeping the driver and kernel
 going and errors are logged to /var/log/messages and dmesg 
 with log priority KERN_ERR.

*Whitespace and non-hex characters are ignored, '\n' is the
 same as '\0'.

*The read text function returns EOF after one read (so that
 cat just gets one line of data), subsequent reads (while
 still open) get data, eof data,eof etc etc.

*Writes absorb as much data as they should ie one word for
 one port and three word for three ports, the transfer is
 truncated to 100 bytes which is plenty for this BUT it
 reports as having transferred the whole buffer for any
 particular read.

BINARY: The device /dev/dio provides a standard binary char
device.  This is used via the open / close / read / write /
ioctl standard c library functions.  The read / write flags
are ignored by the driver, however the library function might
care so open for reading and writing. A user program MUST
include dio.h to get the correct ioctl and symbolic defines.

Port selection and port directions:
the direction within the words are set with

 ioctl(...,DIO_DIR,unsigned int direction) where direction 
 has the bits 0-11 set to 0 for byte read and 1 for byte 
 write. 0-means all read 0x00f write port0 read ports 1 and 2  
 etc.

Which ports are read and written are set with

 ioctl(...,DIO_READ_SEQ,unsigned int sequence) and
 ioctl(...,DIO_WRITE_SEQ,unsigned int sequence) where the
 sequence is made up by ORint DIO_PORT0, DIO_PORT1 and
 DIO_PORT2 or DIO_ALLPORTS

DIO_PORT0->DIO_PORT2 = 0x00f, 0x0f0 and 0xf00 so these may
also be used to set which bytes are writes when using DIO_DIR

The latch can be set using ioctl(...,DIO_LATCH,NULL); and
ioctl(...,DIO_UNLATCH,NULL); (I can't say I have tested this
matt Oct 2001).

Reads and writes will do buffered transfers, that is if you
provide a buffer full of data they will try to use it all the
read / write sequence goes port0->port1->port2 missing out
those ports that are NOT defined in DIO_READ_SEQ and
DIO_WRITE_SEQ.

The maximum transfer size is determined at driver compile
time and defined by DIO_MAX_BUFF (currently
4*PAGE_SIZE/sizeof(u32)  or 4096 words).  If the transfer
buffer is bigger than this it will return DIO_MAX_BUFF words
(subject to quantisation). Depending on how you opened the
driver (open or fopen) you may or may not see this- some
library calls will keep reading and writing in chunks of
DIO_MAX_BUFF until its all gone.

If the driver is expecting to write three words it will
ignore any data that doesn't fit nicely into a multiple of
three words (same for 1 and 2 words).  This is quantisation
of the data transfers.

DELAYS: I have left delays as a compile time option- edit the
Makefile to enable them by adding -DDIO_DELAY to the defines.
Under most platforms there is no hiresolution timer- short
waits are done by busy waiting (spinning) and lock the
processor they are on- longer waits by calling sleep on.

In the case of this driver I thought arbitrary busy waits
were dangerous (allowing a user to lock the system solid) and
longer waits lacking the precision required.

If you want waits and don't mind about these issues then
enable the DIO_DELAY at compile time and remember not to hit
the big red button if you are just stuck in a lengthy set of
busy waits (this can freeze the system for up to
10,000us*4096 words=40seconds). Longer waits are done by
sleeping on and are only at the precision of a timer tick
which is 1/HZ where HZ is typically 100 (x86) but varies from
platform to platform.

TEST PROGRAM: included test_dio.c comile with gcc test_dio.c
-o test_dio.c This assumes that port 0 is wired to port 1 but
doesn't care so long as writing to port 0 is ok by you-


BUGS: none known (yet) -could well be a few it hasn't been
tested comprehensively yet.

bug reports / suggestions / requests to
matt.clark@nottingham.ac.uk


Enjoy, matt



 

	  













