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