Linux CAN Driver (LinCAN) version 0.3.5
part of OrtCAN project
Pavel Pisa
Department of Control Engineering (DCE) FEE CTU
DCE Real-Time Systems group CAN resources
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/OrtCAN 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/
The driver code undergone major redesign in a frame of the OCERA IST project
http://www.ocera.org/
Actual driver version is maintained togther with other CAN/CANopen
components as part of the OrtCAN project
http://ortcan.sourceforge.net/
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
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
lincan-0.3.2 Improvements in SJA1000 error handling and reporting,
(Feb 2006) i82527 support fixes, simple UDEV support,
updates for kernels up to 2.6.15 and fully preemptive
kernel compatibility. Support for MX1_DIS1 extension
board for PiMX1 ARM based BCC.
lincan-0.3.3 Some more fixes of SJA1000 buss-of recovery,
(May 2006) i82527 IRQ stuck problem fixed (reported by Terence Soh),
tested up to 2.6.17 (rc4). Minimal chip info in /proc/can.
Support for NSI CAN PCI contributed by Eric Pennamen.
lincan-0.3.4 Some more fixes of SJA1000 buss-of recovery,
(March 2009) Many enhancements and fixes. Tested up to 2.6.28 Linux kernel.
lincan-0.3.5 Make system updates to build under latest Linux kernels,
(October 2011) LinCAN core builds and tested with 2.6.35 and 3.0 Linux kernels.
The actual version of driver have been latest tested it with
- KVASER pcican-q on 2.6 and 3.0 Linux kernel
- 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 actual driver version, development sources and mailing list
can be found on OrtCAN project pages
http://ortcan.sourceforge.net/
Please send comments, bug-fixes and enhancements directly to
Pavel Pisa or to OrtCAN discussion
forums
and or mailinglist found on OrtCAN project page.
The original LinCAN driver component page at OCERA web site
(not updated to the new version yet)
http://www.ocera.org/download/components/WP7/lincan-0.3.1.html
List of related communication components
http://www.ocera.org/download/components/WP7/index.html
Driver documentation can be found at
http://cmp.felk.cvut.cz/~pisa/can/doc/lincandoc-0.3.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 detailed information can be found in driver documentation at
http://ortcan.sourceforge.net/lincan/
Local maintainer site holds some usesfull information as well
http://cmp.felk.cvut.cz/~pisa/can/
http://cmp.felk.cvut.cz/~pisa/can/lincandoc-X.Y.pdf
The LinCAN releases use 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
COMPILATION from OrtCAN project GIT repository tree
===================================================
There are more options to build LinCAN driver.
The first one is to use stand-alone driver module build.
The other option is to build LinCAN driver as part of the
whole OrtCAN tree.
The latest version of stand-alone LinCAN sources can be
obtained from GIT repository and build by next commands
git clone git://git.code.sf.net/p/ortcan/lincan
cd lincan
./build-lincan.sh
The other option is to build LinCAN driver as part of the whole
OrtCAN tree
git clone git://git.code.sf.net/p/ortcan/ortcan-top
cd ortcan/
git submodule update --init
make default-config
make
COMPILATION options
===================
The options are defined in "config.omk" file for OMK based builds.
File is looked for at directory where are build top directory,
files "Makefile.rules" and "config.omk-default"
located. To select card which is not enabled by default
add line of next format to the "config.omk" file
CONFIG_OC_LINCAN_CARD_tscan1=y
The cross-compilation and build against non-default kernel
can be selected in "config.omk" file as well
LINUX_DIR=/usr/src/linux-2.6-mpc5200-build
CC=powerpc-linux-gnu-gcc
CXX=powerpc-linux-gnu-g++
AR=powerpc-linux-gnu-ar
LD=powerpc-linux-gnu-ld
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/extra".
OMK system requires manual copy of files from "_compiled" tree
to its final destinations. Just compiled driver can be
tested directly from LinCAN build directory (i.e. example
for PC/104 PCM3680 board)
insmod _compiled/modules/lincan.ko hw=pcm3680 io=0x200 irq=7,11
Driver can be copied into system final location after testing
mkdir /lib/modules/$(uname -r)/extra
cp _compiled/modules/lincan.ko /lib/modules/$(uname -r)/extra
chown root:root /lib/modules/$(uname -r)/extra/lincan.ko
depmod -a
Right to access the driver for non-root users can be granted by
generation of "10-lincan.rules" in the UDEV configuration directory
"/etc/udev/rules.d"
# LinCAN driver
SUBSYSTEM=="can",GROUP="users",MODE="0660"
The driver automatic loading of the driver can be requested by addition
of "lincan" line into "/etc/modules" for Debian based systems. The module
parameters can be specified in the same file after "lincan" driver name
or in separate file in "/etc/modprobe.d" directory (i.e.)
echo >/etc/modprobe.d/lincan.conf \
options lincan processlocal=2 hw=pcm3680 io=0x200 irq=7,11
This files location can vary between distributions.
The LinCAN driver options are discusses in more details in
the next paragraph.
LOADING
=======
To load the driver type:
# insmod can.o hw='your hardware' irq='irq number' io='io address'
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
- nsicanpci, for NSI CAN PCI card (2xi82527)
- 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
- gensja1000io for many sja1000 I/O mapped cards (PCAN-PC/104 for example).
- gensja1000mm for ISA memory mapped sja1000 CAN cards
(for pikronisa card used by PiKRON Ltd. the clockfreq=24000 has to be specified)
- pcisja1000mm for SJA1000 directly mapped into PCI mem region 0
- pimx1 for MX1_DIS1 extension board for PiMX1 ARM based BCC
- 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
- tscan1 for Technologic Systems' TS-CAN1 single SJA1000 based board
- ts7kv for Technologic Systems' TS-7KV Multi-function board with SJA1000
both these cards require CONFIG_OC_LINCAN_CARD_tscan1=y
- pcan_pci for PEAK System PCAN-PCI single, double or quad SJA1000 based board
- esdpci200 for the CAN/PCI-200 card by ESD Electronics
- esdpci266 for the ESD PCI/PMC 266 card by ESD Electronics
- 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=, major specifies the major number of the driver.
- minor=, 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=, sets the baudrate of the device(s)
- clockfreq=, the frequency of the CAN quartz
- stdmask=, sets the standard mask of the device
- extmask=, sets the extended mask of the device
- mo15mask=, sets the mask for message object 15 (i82527 only)
- processlocal=, 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.