lincan/README

   1
   2                 Linux CAN Driver (LinCAN) version 0.3.1
   3                 Pavel Pisa <pisa@cmp.felk.cvut.cz>
   4                         OCERA team member
   5                         <http://www.ocera.org>
   6
   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 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 now it is developed and maintained as part of OCERA framework
  31   http://www.ocera.org/
  32
  33 I am unable to contact previous maintainer Arnaud Westenberg
  34 (arnaud@wanadoo.nl). If you know something about him, I like
  35 to hear it.
  36
  37 Versions:
  38
  39 can-0.7.1       latest driver version version published
  40                 by Arnaud Westenberg
  41
  42 can-0.7.1-tm5   the enhanced version with better support of
  43                 SJA1000 PeliCAN mode and CAN Ethernet proxy
  44                 contributed by Tomasz Motylewski <T.Motylewski@bfad.de>
  45
  46 can-0.7.1-pi1   the import and usage of previous version for
  47 (Dec 2002)      OCERA group purposes
  48
  49 can-0.7.1-pi3.4 enhanced version with select support and rewritten
  50 (Mar 2003)      make system for Linux kernels (2.2.x,2.4.x,2.5.x),
  51                 interrupts service cleanup and partial redesign
  52                 and DEVFS support
  53
  54 lincan-0.2-pre  heavily rewritten infrastructure of the driver based
  55 (Aug 2003)      on atomic slot management of queues
  56
  57 lincan-0.2      version tested on many bords and 2.2, 2.4, 2.6 Linux
  58 (Mar 2004)      and RT-Linux enabled 2.4 Linux kernel
  59
  60 lincan-0.2.8    possible SMP and HT deadlock fixed, driver can take
  61 (Jul 2004)      advantage of CMPXCHG instruction if present on CPU,
  62                 added support for CPC-PCI and PCAN-PCI cards,
  63                 messages timestamping implemented
  64                 partially implemented support for Bosch C_CAN module,
  65                 requires more work and real hardware
  66
  67 lincan-0.3      Changed SJA1000 chip IRQ handling. Enhanced VME
  68 (Nov 2004)      and EMS CPC-PCI support and many other changes.
  69
  70 lincan-0.3.1    Small improvements, RTR read moved into separate IOCTL,
  71 (Jul 2005)      initial support for some boards contributed by users
  72
  73 The actual version of driver have been latest tested it with
  74   - PC104 Advantech PCM3680 dual channel board on 2.4 RT-Linux enabled kernel
  75   - PiKRON ISA card on 2.4.and 2.6 Linux kernels
  76   - BfaD DIMM PC card on 2.4 RT-Linux enabled kernel
  77   - KVASER pcican-q on 2.6 Linux kernel
  78   - MICROSPACE msmcan on 2.4 Linux and RT-Linux enabled kernel
  79   - Unicontrols PCAN ("unican"),PCAN-PCI ("unican-pci"), VCAN  ("unican-vme")
  80   - EMS CPC-PCI cards ("ems_cpcpci")
  81   - virtual board tested on all systems as wel
  82 It takes more time to test driver with more cards.
  83 Infrastructure and support for more than 20 boards with more
  84 variants is prepared in the sources.
  85
  86
  87 SOURCES AND URLs
  88 ================
  89
  90 The LinCAN driver component page at OCERA web site
  91 (not updated to the new version yet)
  92
  93   http://www.ocera.org/download/components/WP7/lincan-0.2.html
  94
  95 List of related communication components
  96
  97   http://www.ocera.org/download/components/WP7/index.html
  98
  99 The CVS repository of OCERA project at SourceForge
 100
 101   EXTCVS=":pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera"
 102   cvs -d$EXTCVS login
 103   cvs -z3 -d$EXTCVS co ocera
 104
 105 Web access into CVS
 106
 107   http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ocera/ocera/components/comm/can/lincan/
 108
 109 Experimental directory at maintainer's (Pavel Pisa's) pages
 110
 111   http://cmp.felk.cvut.cz/~pisa/can/
 112   http://cmp.felk.cvut.cz/~pisa/can/lincan-YYMMDD.tar.gz
 113
 114 Please send comments, bug-fixes and enhancements directly to
 115 Pavel Pisa <pisa@cmp.felk.cvut.cz> or to OCERA discussion
 116 forum <https://sourceforge.net/forum/forum.php?forum_id=170893>
 117 and lists <ocera-development@lists.sourceforge.net>
 118
 119 Driver documentation can be found at
 120
 121   http://cmp.felk.cvut.cz/~pisa/can/doc/lincandoc-0.2.pdf
 122
 123 The anouncements of new version are published at FreshMeat page
 124
 125   http://freshmeat.net/projects/lincan/
 126
 127
 128 COMPILATION of LinCAN releases
 129 ==============================
 130
 131 Just type 'make' at the command line and driver module should compile
 132 without errors for current running kernel.
 133
 134 More information can be found in driver documentation at
 135   http://cmp.felk.cvut.cz/~pisa/can/
 136   http://cmp.felk.cvut.cz/~pisa/can/lincandoc-X.Y.pdf
 137
 138 Some releases use experimental OMK make system, which requires
 139 recent GNU make program version 3.81beta1 and above.
 140 Makefiles can be switched to old ones by script
 141
 142   sh ./switch-omk2std
 143   make
 144
 145 If you have problem to obtain recent GNU make program,
 146
 147  http://paulandlesley.org/make/make-3.81beta1.tar.bz2
 148
 149 you can use our local copy
 150
 151   http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz
 152
 153
 154 COMPILATION from CVS sources without full OCERA tree
 155 ====================================================
 156
 157 ---------------------------------------------------------------------------
 158 Obtaining CVS sources of the CAN components only
 159 ---------------------------------------------------------------------------
 160   cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ocera login
 161   cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ocera co
 162          ocera/components/comm/can
 163
 164 ---------------------------------------------------------------------------
 165 Commands to build OCERA CVS CAN components outside OCERA tree
 166 ---------------------------------------------------------------------------
 167   cd ocera/components/comm/can
 168   ./switch2standalone
 169   make
 170
 171 The selection of required features and options can be specified before make
 172 command invocation. Lines containing required changes to config.omk-default
 173 file should be stored in config.omk file. The config.omk is not altered by
 174 OMK system and options defined there override values defined in
 175 config.omk-default file. GNU make program version 3.81beta1 or newer is
 176 required by OMK make-system. If this is problem, LinCAN driver can be
 177 compiled with use of old style Makefiles as well.
 178
 179 ---------------------------------------------------------------------------
 180 Old style Makefiles compilation of the LinCAN driver only
 181 ---------------------------------------------------------------------------
 182   cd ocera/components/comm/can/lincan
 183   ./switch-omk2std
 184   make
 185
 186
 187 INSTALLATION
 188 ============
 189 Type 'make install' for standard make system compilation.
 190 The driver should be copied into actual kernel version
 191 modules directory "/lib/modules/x.y.z/kernel/drivers/char".
 192
 193 OMK system requires manual copy of files from "_compiled" tree
 194 to its final destinations.
 195
 196 LOADING
 197 =======
 198
 199 To load the driver type:
 200 # insmod can.o hw='your hardware' irq='irq number' io='io address' <options>
 201 Examples: # insmod can.o hw=pip5 irq=4 io=0x8000
 202           # insmod can.o hw=virtual io=0
 203
 204 The hw argument can be one of:
 205 - pip5, for the PIP5 computer by MPL
 206 - pip6, for the PIP6 computer by MPL
 207 - pip7, for the PIP7 computer by MPL
 208 - pip8, for the PIP8 computer by MPL
 209 - pccan-q, for the PCcan-Q ISA card by KVASER
 210 - pccan-f, for the PCcan-F ISA card by KVASER
 211 - pccan-s, for the PCcan-S ISA card by KVASER
 212 - pccan-d, for the PCcan-D ISA card by KVASER
 213 - pcican-q, for the PCIcan-Q PCI card by KVASER (4x SJA1000)
 214 - pcican-d, for the PCIcan-Q PCI card by KVASER (2x SJA1000)
 215 - pcican-s, for the PCIcan-Q PCI card by KVASER (1x SJA1000)
 216 - smartcan for i82527 based card with indexed access
 217 - nsican, for the CAN104 PC/104 card by NSI
 218 - cc104, for the CAN104 PC/104 card by Contemporary Controls
 219 - aim104, for the AIM104CAN PC/104 card by Arcom Control Systems
 220 - pc-i03, for the PC-I03 ISA card by IXXAT
 221 - pcm3680, for the PCM-3680 PC/104 card by Advantech
 222 - m437, for the M436 PC/104 card by SECO
 223 - bfadcan for sja1000 CAN embedded card made by BFAD GmbH
 224 - pikronisa for ISA memory mapped sja1000 CAN card made by PiKRON Ltd.
 225 - msmcan for MICROSPACE IO space indexed i82527
 226 - unican for Unicontrols PCAN card
 227 - unican-pci for Unicontrols PCAN-PCI card
 228 - unican-vme for Unicontrols VCAN card
 229 - ipci165 for IXXAT iPC-I 165 (PCI), requires CONFIG_OC_LINCAN_CARD_ipci165=y
 230 - ems_cpcpci for EMS CPC-PCI card
 231 - pcan_dongle for PEAK's printer port dongle addapter
 232 - oscar for SJA1000 based card connected to ARM LH7A400 SoC
 233 - eb8245 for Kontron EB8245 onboard CAN with SJA1000 controller
 234 - adlink7841 for ADLINK PCI-7841 dual SJA1000 based card
 235 - template, for yet unsupported hardware (you need to edit src/template.c)
 236 - virtual, CAN channel for testing of software and driver without CAN hardware
 237
 238 options can be one of:
 239 - major=<nr>, major specifies the major number of the driver.
 240 - minor=<nr>, you can specify which minor numbers the driver should use for your
 241   hardware.
 242 - extended=[1|0], configures the driver to use extended message format.
 243 - pelican=[1|0], configures the driver to set the CAN chips into pelican mode.
 244 - baudrate=<nr>, sets the baudrate of the device(s)
 245 - clock_freq=<nr>, the frequency of the CAN quartz
 246 - stdmask=<nr>, sets the standard mask of the device
 247 - extmask=<nr>, sets the extended mask of the device
 248 - mo15mask=<nr>, sets the mask for message object 15 (i82527 only)
 249 - processlocal=<nr>, controls distribution of send messages to Rx FIFOs
 250                 0, no local outgoing messages delivery to Rx FIFOs
 251                 1, default off, but can be controlled by individual filter settings
 252                 2, all FIFOs receive local messages
 253
 254 There's still a lot of work to do, have a look at the TODO file for more
 255 information.
 256
 257 Some boards support is compiled in only, when it is enabled through
 258 config.omk file. It has to be stored in same directory as Makefile.rules
 259 and config.omk-default is located.