$Revision: 0.21 $	$Date: 2002/01/13 16:54:40 $


These are Linux kernel device drivers for ECAN1000HR and ECAN527HR
CAN bus controllers, developed by Real Time Devices, Inc.



1. Drivers Features
-------------------

* The drivers interface and behaviour designed to be the same as MS
  Windows ones as close as possible in spite of its design flaws.

* Can be builded and used for any of 2.0.x or 2.2.x or 2.4.x kernel
  release from single source files tree.

* Handles multiple boards from one loaded driver module; it is the norm.
  Up to 10 boards can be used simultaneously, real amount is limited by
  available IRQ lines only.

* IRQ lines detected automatically, no need to specify them in driver
  options.

* I/O address of ECAN527 detected automatically, no need to specify
  them in driver options.

* Device entries are created and removed automatically so it is no need
  to care about an official device major numbers registration or to
  check possible collisions with other drivers manually.



2. Build and Install
--------------------

To build and install this package read the general guide in INSTALL file
at source top directory ( ../.. from this ).

For impatients:

	make config && make all
	su
	make install

	/sbin/insmod rtd-ecan1000 io=0xNNN,0xNNN ...

	/sbin/insmod rtd-ecan527


Differences are followed:


2.1. Driver parameters
----------------------

Complete insmod parameters list for rtd-ecan1000 and rtd-ecan527 drivers:

io		10 base I/O addresses,
			default is: -1 (don't probe) for ECAN1000
				     0 (auto  probe) for ECAN527
irq		10 IRQ line numbers,
			default is 0 (auto probe)
devmode		device permission bits,
			default is 0666 (rw-rw-rw-)
devuid		device user id
			default is 0 (root)
devgid		device group id
			default is 0 (root)

verbose		device detection fail verbosity flag (boolean)
			default is 0

See insmod(1) manual page for parameter syntax details.


The ten device file entries /dev/rtd-ecanMAGIC-N is created on module
loading and removed on module unloading automatically, where MAGIC is
board type magic number, 1000 for ECAN1000HR and 527 for ECAN527HR and
N is board instance number, 0..9.
Their owner, group, permission bits defined by corresponding devmode,
devuid, devgid module parameters.



3. Driver utilities
-------------------

The 'rtd-ecan-cmd' is interactive program allows to execute almost all
of driver functions. Its main purpose was debugging the driver, so it
has slightly long and cryptic command and argument names.

The 'rtd-ecan-print-accounts' prints accounts of driver operations of
specified board. It can be used with the 'watch' command to see changes
dynamically in slightly lengthened xterm window.

The 'rtd-ecan-clear-accounts' clears accounts of specified board.

The 'rtd-ecan-read' reads incoming messages from board and send data to
stdout. The 'rtd-ecan-write' reads stdin and sends it to board. Both of
them are use high level Ecan*() functions.

ECAN527 board due to the brain-damaged intel chip design has unbuffered
receivers so packet losses are possible with high packet rate and
the software FIFO can not solve this problem at all.
In order to test the ECAN527 driver and board by file transferring
run the rtd-ecan-write without -q option and rtd-ecan-read with -q
option to delay between outgoing packets and check message lost field
in rtd-ecan-print-accounts output.



4. Programming notes
--------------------

4.1. Interface levels
---------------------

The drivers interface and behaviour designed to be the same as MS
Windows ones as close as possible in spite of its design flaws. In
order to meet this requirements there are three levels of interface:

High level is exact copy of Ecan* functions interface of MS Windows
driver wrapper, declared in <EcanFunc.h> header file.

Mid level is definitions of argument structures used in high-level
Ecan* functions and in low-level MS Windows DeviceIoControl() for the
driver, defined in <EcanIoctl.h> header file.

Low level is Linux driver interface functions rtd_ecan_*() defined in
<rtd-ecan-ioctl.h> header file.

Note that in this implementation release the high level Ecan* functions
use low-level driver interface directly and there are no
DeviceIoControl() simulation.

Complete description of low-level driver interface contains in
linux/API.txt file, it is installed to $prefix/doc/rtd-ecan/ directory.



4.2. Linking with rtd-ecan library
----------------------------------

Some of Ecan* functions, declared in <EcanFunc.h> header, is too big to
be inline; thus they are moved to rtd-ecan static library. To link with
it add '-lrtd-ecan' to linker options.



4.3. Driver access
------------------

A programm gets access to CAN bus controller boards by opening (see
open(2) system call) device file '/dev/rtd-ecanMAGIC-N', where MAGIC is
board type magic number, 1000 for ECAN1000HR and 527 for ECAN527HR and
N is board instance number, 0..9.

High level Ecan_CreateHandle() function does it automatically for you
if you like.



4.4. Synchronous I/O multiplexing
---------------------------------

The driver supports select(2) and poll(2) system calls. MS Windows has
analogous but slightly limited feature called WaitForMultipleObjects().

The driver has two types of events only: read/POLLIN and write/POLLOUT.

IN  event/state means that there are messages in driver's receive
queue. OUT event/state means that there are free message slots in
driver's transmit queue. Since errors and other special state
conditions reported by status fields in message structure of receive
queue items, there is no exception/POLLPRI event support for a
select/poll.

See also select(2) and poll(2) man pages and
"info libc 'Low-Level I/O' 'Waiting for I/O'" for details.



4.5. Process blocking (sleep)
-----------------------------

Since the MS Windows driver's interface and behaviour has no process
blocking feature (process sleep and wake up) this Linux driver
implementation does not blocks and ignores O_NONBLOCK flag. Thus there
is nothing to do with interrupted system calls.

