lincan/README

   1
   2                 Linux CAN Driver (LinCAN) version 0.3.4
   3                 Pavel Pisa <pisa@cmp.felk.cvut.cz>
   4                         OCERA team member <http://www.ocera.org>
   5                         Real-time Systems Laboratory <http://rtlab.felk.cvut.cz/>
   6                         Department of Control Engineering, FEE CTU
   7
   8
   9 INTRODUCTION
  10 ============
  11 The LinCAN is an implementation of the Linux CAN-bus device driver supporting
  12 more CAN controller chips and many CAN interface boards. Its development
  13 has long history already. The OCERA version of the driver has new better
  14 designed internal structure, adds new features (as support for open by multiple
  15 applications, select system call) and other enhancements.
  16
  17 The driver consist of four main layers:
  18   - chip level manipulation routines
  19   - board specific support
  20   - message queues
  21   - user-space API and ABI character device interface
  22
  23
  24 DRIVER HISTORY
  25 ==============
  26
  27 The driver originates in The Linux Lab Project
  28   http://www.llp.fu-berlin.de/
  29 then it has been first rewritten by Arnaud Westenberg
  30   http://home.wanadoo.nl/arnaud/
  31 now it is developed and maintained as part of OCERA framework
  32   http://www.ocera.org/
  33
  34 I am unable to contact previous maintainer Arnaud Westenberg
  35 (arnaud@wanadoo.nl). If you know something about him, I like
  36 to hear it.
  37
  38 Versions:
  39
  40 can-0.7.1       latest driver version version published
  41                 by Arnaud Westenberg
  42
  43 can-0.7.1-tm5   the enhanced version with better support of
  44                 SJA1000 PeliCAN mode and CAN Ethernet proxy
  45                 contributed by Tomasz Motylewski <T.Motylewski@bfad.de>
  46
  47 can-0.7.1-pi1   the import and usage of previous version for
  48 (Dec 2002)      OCERA group purposes
  49
  50 can-0.7.1-pi3.4 enhanced version with select support and rewritten
  51 (Mar 2003)      make system for Linux kernels (2.2.x,2.4.x,2.5.x),
  52                 interrupts service cleanup and partial redesign
  53                 and DEVFS support
  54
  55 lincan-0.2-pre  heavily rewritten infrastructure of the driver based
  56 (Aug 2003)      on atomic slot management of queues
  57
  58 lincan-0.2      version tested on many bords and 2.2, 2.4, 2.6 Linux
  59 (Mar 2004)      and RT-Linux enabled 2.4 Linux kernel
  60
  61 lincan-0.2.8    possible SMP and HT deadlock fixed, driver can take
  62 (Jul 2004)      advantage of CMPXCHG instruction if present on CPU,
  63                 added support for CPC-PCI and PCAN-PCI cards,
  64                 messages timestamping implemented
  65                 partially implemented support for Bosch C_CAN module,
  66                 requires more work and real hardware
  67
  68 lincan-0.3      Changed SJA1000 chip IRQ handling. Enhanced VME
  69 (Nov 2004)      and EMS CPC-PCI support and many other changes.
  70
  71 lincan-0.3.1    Small improvements, RTR read moved into separate IOCTL,
  72 (Jul 2005)      initial support for some boards contributed by users
  73
  74 lincan-0.3.2    Improvements in SJA1000 error handling and reporting,
  75 (Feb 2006)      i82527 support fixes, simple UDEV support,
  76                 updates for kernels up to 2.6.15 and fully preemptive
  77                 kernel compatibility. Support for MX1_DIS1 extension
  78                 board for PiMX1 ARM based BCC.
  79
  80 lincan-0.3.3    Some more fixes of SJA1000 buss-of recovery,
  81 (May 2006)      i82527 IRQ stuck problem fixed (reported by Terence Soh),
  82                 tested up to 2.6.17 (rc4). Minimal chip info in /proc/can.
  83                 Support for NSI CAN PCI contributed by Eric Pennamen.
  84
  85 lincan-0.3.4    Some more fixes of SJA1000 buss-of recovery,
  86 (March 2009)    Many enhancements and fixes. Tested up to 2.6.28 Linux kernel.
  87
  88 The actual version of driver have been latest tested it with
  89   - PC104 Advantech PCM3680 dual channel board on 2.4 RT-Linux enabled kernel
  90   - PiKRON ISA card on 2.4.and 2.6 Linux kernels
  91   - PiKRON CAN extension board for PiMCX1 ARM BCC on 2.6 Linux kernels
  92   - BfaD DIMM PC card on 2.4 RT-Linux enabled kernel
  93   - KVASER pcican-q on 2.6 Linux kernel
  94   - MICROSPACE msmcan on 2.4 Linux and RT-Linux enabled kernel
  95   - Unicontrols PCAN ("unican"),PCAN-PCI ("unican-pci"), VCAN  ("unican-vme")
  96   - EMS CPC-PCI cards ("ems_cpcpci")
  97   - virtual board tested on all systems as wel
  98 It takes more time to test driver with more cards.
  99 Infrastructure and support for more than 20 boards with more
 100 variants is prepared in the sources.
 101
 102
 103 SOURCES AND URLs
 104 ================
 105
 106 The LinCAN driver component page at OCERA web site
 107 (not updated to the new version yet)
 108
 109   http://www.ocera.org/download/components/WP7/lincan-0.3.1.html
 110
 111 List of related communication components
 112
 113   http://www.ocera.org/download/components/WP7/index.html
 114
 115 The obtaining LinCAN and other CAN related components
 116 from OCERA CVS repository at SourceForge
 117
 118   EXTCVS=":pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera"
 119   cvs -d$EXTCVS login
 120   cvs -z3 -d$EXTCVS co ocera/components/comm/can
 121
 122 Web access into CVS
 123
 124   http://ocera.cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ocera/ocera/components/comm/can/lincan/
 125
 126 Experimental directory at maintainer's (Pavel Pisa's) pages
 127
 128   http://cmp.felk.cvut.cz/~pisa/can/
 129   http://cmp.felk.cvut.cz/~pisa/can/lincan-YYMMDD.tar.gz
 130
 131 Please send comments, bug-fixes and enhancements directly to
 132 Pavel Pisa <pisa@cmp.felk.cvut.cz> or to OCERA discussion
 133 forum <https://sourceforge.net/forum/forum.php?forum_id=170893>
 134 and lists <ocera-development@lists.sourceforge.net>
 135
 136 Driver documentation can be found at
 137
 138   http://cmp.felk.cvut.cz/~pisa/can/doc/lincandoc-0.3.pdf
 139
 140 The anouncements of new version are published at FreshMeat page
 141
 142   http://freshmeat.net/projects/lincan/
 143
 144
 145 COMPILATION of LinCAN releases
 146 ==============================
 147
 148 Just type 'make' at the command line and driver module should compile
 149 without errors for current running kernel.
 150
 151 More information can be found in driver documentation at
 152   http://cmp.felk.cvut.cz/~pisa/can/
 153   http://cmp.felk.cvut.cz/~pisa/can/lincandoc-X.Y.pdf
 154
 155 Some releases use experimental OMK make system, which requires
 156 recent GNU make program version 3.81beta1 and above.
 157 Makefiles can be switched to old ones by script
 158
 159   sh ./switch-omk2std
 160   make
 161
 162 If you have problem to obtain recent GNU make program,
 163
 164  ftp://alpha.gnu.org/gnu/make/make-3.81beta4.tar.bz2
 165
 166 you can use our local copy
 167
 168   http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz
 169
 170
 171 COMPILATION from CVS sources without full OCERA tree
 172 ====================================================
 173
 174 ---------------------------------------------------------------------------
 175 Obtaining CVS sources of the CAN components only
 176 ---------------------------------------------------------------------------
 177   cvs -d:pserver:anonymous@ocera.cvs.sourceforge.net:/cvsroot/ocera login
 178   cvs -z3 -d:pserver:anonymous@ocera.cvs.sourceforge.net:/cvsroot/ocera co
 179          ocera/components/comm/can
 180
 181 ---------------------------------------------------------------------------
 182 Commands to build OCERA CVS CAN components outside OCERA tree
 183 ---------------------------------------------------------------------------
 184   cd ocera/components/comm/can
 185   ./switch2standalone
 186   make
 187
 188 The selection of required features and options can be specified before make
 189 command invocation. Lines containing required changes to config.omk-default
 190 file should be stored in config.omk file. The config.omk is not altered by
 191 OMK system and options defined there override values defined in
 192 config.omk-default file. GNU make program version 3.81beta1 or newer is
 193 required by OMK make-system. If this is problem, LinCAN driver can be
 194 compiled with use of old style Makefiles as well.
 195
 196 ---------------------------------------------------------------------------
 197 Old style Makefiles compilation of the LinCAN driver only
 198 ---------------------------------------------------------------------------
 199   cd ocera/components/comm/can/lincan
 200   ./switch-omk2std
 201   make
 202
 203
 204 INSTALLATION
 205 ============
 206 Type 'make install' for standard make system compilation.
 207 The driver should be copied into actual kernel version
 208 modules directory "/lib/modules/x.y.z/kernel/drivers/char".
 209
 210 OMK system requires manual copy of files from "_compiled" tree
 211 to its final destinations.
 212
 213 Create file "lincan.rules" with contents listed below in or linked
 214 into "/etc/udev/rules.d" directory to enable automatic device nodes
 215 creation for UDEV based system
 216
 217   # LinCAN driver
 218   SUBSYSTEM=="can",GROUP="users",MODE="0660"
 219
 220 The driver automatic loding can be requested by addition of "lincan"
 221 line into "/etc/modules" od Debian based systems.
 222
 223 The target hardware/board specific options should be added into
 224 "/etc/modprobe.conf" file or file with similar functionality for your
 225 distribution. The options are discusses in the next paragraph.
 226
 227 LOADING
 228 =======
 229
 230 To load the driver type:
 231 # insmod can.o hw='your hardware' irq='irq number' io='io address' <options>
 232 Examples: # insmod can.o hw=pip5 irq=4 io=0x8000
 233           # insmod can.o hw=virtual io=0
 234
 235 The hw argument can be one of:
 236 - pip5, for the PIP5 computer by MPL
 237 - pip6, for the PIP6 computer by MPL
 238 - pip7, for the PIP7 computer by MPL
 239 - pip8, for the PIP8 computer by MPL
 240 - pccan-q, for the PCcan-Q ISA card by KVASER
 241 - pccan-f, for the PCcan-F ISA card by KVASER
 242 - pccan-s, for the PCcan-S ISA card by KVASER
 243 - pccan-d, for the PCcan-D ISA card by KVASER
 244 - pcican-q, for the PCIcan-Q PCI card by KVASER (4x SJA1000)
 245 - pcican-d, for the PCIcan-Q PCI card by KVASER (2x SJA1000)
 246 - pcican-s, for the PCIcan-Q PCI card by KVASER (1x SJA1000)
 247 - smartcan for i82527 based card with indexed access
 248 - nsican, for the CAN104 PC/104 card by NSI
 249 - nsicanpci, for NSI CAN PCI card (2xi82527)
 250 - cc104, for the CAN104 PC/104 card by Contemporary Controls
 251 - aim104, for the AIM104CAN PC/104 card by Arcom Control Systems
 252 - pc-i03, for the PC-I03 ISA card by IXXAT
 253 - pcm3680, for the PCM-3680 PC/104 card by Advantech
 254 - m437, for the M436 PC/104 card by SECO
 255 - bfadcan for sja1000 CAN embedded card made by BFAD GmbH
 256 - gensja1000io for many sja1000 I/O mapped cards (PCAN-PC/104 for example).
 257 - gensja1000mm for ISA memory mapped sja1000 CAN cards
 258   (for pikronisa card used by PiKRON Ltd. the clockfreq=24000 has to be specified)
 259 - pimx1 for MX1_DIS1 extension board for PiMX1 ARM based BCC
 260 - msmcan for MICROSPACE IO space indexed i82527
 261 - unican for Unicontrols PCAN card
 262 - unican-pci for Unicontrols PCAN-PCI card
 263 - unican-vme for Unicontrols VCAN card
 264 - ipci165 for IXXAT iPC-I 165 (PCI), requires CONFIG_OC_LINCAN_CARD_ipci165=y
 265 - ems_cpcpci for EMS CPC-PCI card
 266 - pcan_dongle for PEAK's printer port dongle addapter
 267 - oscar for SJA1000 based card connected to ARM LH7A400 SoC
 268 - eb8245 for Kontron EB8245 onboard CAN with SJA1000 controller
 269 - adlink7841 for ADLINK PCI-7841 dual SJA1000 based card
 270 - tscan1 for Technologic Systems' TS-CAN1 single SJA1000 based board
 271 - ts7kv for Technologic Systems' TS-7KV Multi-function board with SJA1000
 272    both these cards require CONFIG_OC_LINCAN_CARD_tscan1=y
 273 - pcan_pci for PEAK System PCAN-PCI single, double or quad SJA1000 based board
 274 - esdpci200 for the CAN/PCI-200 card by ESD Electronics
 275 - esdpci266 for the ESD PCI/PMC 266 card by ESD Electronics
 276 - template, for yet unsupported hardware (you need to edit src/template.c)
 277 - virtual, CAN channel for testing of software and driver without CAN hardware
 278
 279 options can be one of:
 280 - major=<nr>, major specifies the major number of the driver.
 281 - minor=<nr>, you can specify which minor numbers the driver should use for your
 282   hardware.
 283 - extended=[1|0], configures the driver to use extended message format.
 284 - pelican=[1|0], configures the driver to set the CAN chips into pelican mode.
 285 - baudrate=<nr>, sets the baudrate of the device(s)
 286 - clockfreq=<nr>, the frequency of the CAN quartz
 287 - stdmask=<nr>, sets the standard mask of the device
 288 - extmask=<nr>, sets the extended mask of the device
 289 - mo15mask=<nr>, sets the mask for message object 15 (i82527 only)
 290 - processlocal=<nr>, controls distribution of send messages to Rx FIFOs
 291                 0, no local outgoing messages delivery to Rx FIFOs
 292                 1, default off, but can be controlled by individual filter settings
 293                 2, all FIFOs receive local messages
 294
 295 There's still a lot of work to do, have a look at the TODO file for more
 296 information.
 297
 298 Some boards support is compiled in only, when it is enabled through
 299 config.omk file. It has to be stored in same directory as Makefile.rules
 300 and config.omk-default is located.