
		Linux CAN Driver (LinCAN) version 0.3.1
		Pavel Pisa <pisa@cmp.felk.cvut.cz>
			OCERA team member
			<http://www.ocera.org>


INTRODUCTION
============
The LinCAN is an implementation of the Linux CAN-bus device driver supporting
more CAN controller chips and many CAN interface boards. Its development
has long history already. The OCERA version of the driver has new better
designed internal structure, adds new features (as support for open by multiple
applications, select system call) and other enhancements.
  
The driver consist of four main layers:
  - chip level manipulation routines
  - board specific support
  - message queues
  - user-space API and ABI character device interface


DRIVER HISTORY
==============

The driver originates in The Linux Lab Project
  http://www.llp.fu-berlin.de/
then it has been first rewritten by Arnaud Westenberg
  http://home.wanadoo.nl/arnaud/
now it is developed and maintained as part of OCERA framework
  http://www.ocera.org/

I am unable to contact previous maintainer Arnaud Westenberg
(arnaud@wanadoo.nl). If you know something about him, I like
to hear it.

Versions:

can-0.7.1	latest driver version version published
		by Arnaud Westenberg

can-0.7.1-tm5	the enhanced version with better support of
		SJA1000 PeliCAN mode and CAN Ethernet proxy
		contributed by Tomasz Motylewski <T.Motylewski@bfad.de>

can-0.7.1-pi1	the import and usage of previous version for
(Dec 2002)	OCERA group purposes
		
can-0.7.1-pi3.4 enhanced version with select support and rewritten
(Mar 2003)	make system for Linux kernels (2.2.x,2.4.x,2.5.x),
		interrupts service cleanup and partial redesign
		and DEVFS support

lincan-0.2-pre	heavily rewritten infrastructure of the driver based
(Aug 2003)	on atomic slot management of queues

lincan-0.2	version tested on many bords and 2.2, 2.4, 2.6 Linux
(Mar 2004)	and RT-Linux enabled 2.4 Linux kernel

lincan-0.2.8	possible SMP and HT deadlock fixed, driver can take
(Jul 2004)	advantage of CMPXCHG instruction if present on CPU,
		added support for CPC-PCI and PCAN-PCI cards,
		messages timestamping implemented
		partially implemented support for Bosch C_CAN module,
		requires more work and real hardware

lincan-0.3	Changed SJA1000 chip IRQ handling. Enhanced VME
(Nov 2004)	and EMS CPC-PCI support and many other changes.

lincan-0.3.1	Small improvements, RTR read moved into separate IOCTL,
(Jul 2005)	initial support for some boards contributed by users
		
The actual version of driver have been latest tested it with
  - PC104 Advantech PCM3680 dual channel board on 2.4 RT-Linux enabled kernel
  - PiKRON ISA card on 2.4.and 2.6 Linux kernels
  - BfaD DIMM PC card on 2.4 RT-Linux enabled kernel
  - KVASER pcican-q on 2.6 Linux kernel
  - MICROSPACE msmcan on 2.4 Linux and RT-Linux enabled kernel
  - Unicontrols PCAN ("unican"),PCAN-PCI ("unican-pci"), VCAN  ("unican-vme")
  - EMS CPC-PCI cards ("ems_cpcpci")
  - virtual board tested on all systems as wel
It takes more time to test driver with more cards.
Infrastructure and support for more than 20 boards with more
variants is prepared in the sources.


SOURCES AND URLs
================

The LinCAN driver component page at OCERA web site
(not updated to the new version yet)

  http://www.ocera.org/download/components/WP7/lincan-0.2.html
  
List of related communication components
  
  http://www.ocera.org/download/components/WP7/index.html

The CVS repository of OCERA project at SourceForge

  EXTCVS=":pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera"
  cvs -d$EXTCVS login
  cvs -z3 -d$EXTCVS co ocera
  
Web access into CVS

  http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ocera/ocera/components/comm/can/lincan/

Experimental directory at maintainer's (Pavel Pisa's) pages 

  http://cmp.felk.cvut.cz/~pisa/can/
  http://cmp.felk.cvut.cz/~pisa/can/lincan-YYMMDD.tar.gz
  
Please send comments, bug-fixes and enhancements directly to
Pavel Pisa <pisa@cmp.felk.cvut.cz> or to OCERA discussion
forum <https://sourceforge.net/forum/forum.php?forum_id=170893> 
and lists <ocera-development@lists.sourceforge.net>

Driver documentation can be found at

  http://cmp.felk.cvut.cz/~pisa/can/doc/lincandoc-0.2.pdf

The anouncements of new version are published at FreshMeat page

  http://freshmeat.net/projects/lincan/


COMPILATION of LinCAN releases
==============================

Just type 'make' at the command line and driver module should compile
without errors for current running kernel. 

More information can be found in driver documentation at
  http://cmp.felk.cvut.cz/~pisa/can/
  http://cmp.felk.cvut.cz/~pisa/can/lincandoc-X.Y.pdf
  
Some releases use experimental OMK make system, which requires
recent GNU make program version 3.81beta1 and above.
Makefiles can be switched to old ones by script

  sh ./switch-omk2std
  make

If you have problem to obtain recent GNU make program,

 http://paulandlesley.org/make/make-3.81beta1.tar.bz2

you can use our local copy

  http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz


COMPILATION from CVS sources without full OCERA tree
====================================================
  
---------------------------------------------------------------------------
Obtaining CVS sources of the CAN components only
---------------------------------------------------------------------------
  cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ocera login
  cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ocera co
         ocera/components/comm/can

---------------------------------------------------------------------------
Commands to build OCERA CVS CAN components outside OCERA tree
---------------------------------------------------------------------------
  cd ocera/components/comm/can
  ./switch2standalone
  make

The selection of required features and options can be specified before make 
command invocation. Lines containing required changes to config.omk-default 
file should be stored in config.omk file. The config.omk is not altered by 
OMK system and options defined there override values defined in 
config.omk-default file. GNU make program version 3.81beta1 or newer is 
required by OMK make-system. If this is problem, LinCAN driver can be 
compiled with use of old style Makefiles as well.

---------------------------------------------------------------------------
Old style Makefiles compilation of the LinCAN driver only
---------------------------------------------------------------------------
  cd ocera/components/comm/can/lincan
  ./switch-omk2std
  make


INSTALLATION
============
Type 'make install' for standard make system compilation.
The driver should be copied into actual kernel version
modules directory "/lib/modules/x.y.z/kernel/drivers/char".

OMK system requires manual copy of files from "_compiled" tree
to its final destinations.

LOADING
=======

To load the driver type:
# insmod can.o hw='your hardware' irq='irq number' io='io address' <options>
Examples: # insmod can.o hw=pip5 irq=4 io=0x8000
          # insmod can.o hw=virtual io=0

The hw argument can be one of:
- pip5, for the PIP5 computer by MPL
- pip6, for the PIP6 computer by MPL
- pip7, for the PIP7 computer by MPL
- pip8, for the PIP8 computer by MPL
- pccan-q, for the PCcan-Q ISA card by KVASER
- pccan-f, for the PCcan-F ISA card by KVASER
- pccan-s, for the PCcan-S ISA card by KVASER
- pccan-d, for the PCcan-D ISA card by KVASER
- pcican-q, for the PCIcan-Q PCI card by KVASER (4x SJA1000)
- pcican-d, for the PCIcan-Q PCI card by KVASER (2x SJA1000)
- pcican-s, for the PCIcan-Q PCI card by KVASER (1x SJA1000)
- smartcan for i82527 based card with indexed access
- nsican, for the CAN104 PC/104 card by NSI
- cc104, for the CAN104 PC/104 card by Contemporary Controls
- aim104, for the AIM104CAN PC/104 card by Arcom Control Systems
- pc-i03, for the PC-I03 ISA card by IXXAT
- pcm3680, for the PCM-3680 PC/104 card by Advantech
- m437, for the M436 PC/104 card by SECO
- bfadcan for sja1000 CAN embedded card made by BFAD GmbH
- pikronisa for ISA memory mapped sja1000 CAN card made by PiKRON Ltd.
- msmcan for MICROSPACE IO space indexed i82527
- unican for Unicontrols PCAN card
- unican-pci for Unicontrols PCAN-PCI card
- unican-vme for Unicontrols VCAN card
- ipci165 for IXXAT iPC-I 165 (PCI), requires CONFIG_OC_LINCAN_CARD_ipci165=y
- ems_cpcpci for EMS CPC-PCI card
- pcan_dongle for PEAK's printer port dongle addapter
- oscar for SJA1000 based card connected to ARM LH7A400 SoC
- eb8245 for Kontron EB8245 onboard CAN with SJA1000 controller
- adlink7841 for ADLINK PCI-7841 dual SJA1000 based card
- template, for yet unsupported hardware (you need to edit src/template.c)
- virtual, CAN channel for testing of software and driver without CAN hardware

options can be one of:
- major=<nr>, major specifies the major number of the driver.
- minor=<nr>, you can specify which minor numbers the driver should use for your
  hardware.
- extended=[1|0], configures the driver to use extended message format.
- pelican=[1|0], configures the driver to set the CAN chips into pelican mode.
- baudrate=<nr>, sets the baudrate of the device(s)
- clock_freq=<nr>, the frequency of the CAN quartz
- stdmask=<nr>, sets the standard mask of the device
- extmask=<nr>, sets the extended mask of the device
- mo15mask=<nr>, sets the mask for message object 15 (i82527 only)
- processlocal=<nr>, controls distribution of send messages to Rx FIFOs
		0, no local outgoing messages delivery to Rx FIFOs
		1, default off, but can be controlled by individual filter settings
		2, all FIFOs receive local messages

There's still a lot of work to do, have a look at the TODO file for more
information.

Some boards support is compiled in only, when it is enabled through
config.omk file. It has to be stored in same directory as Makefile.rules
and config.omk-default is located.
