lincan/README

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