Merge: Correction for 2.6.23-git kernel - unregister_chrdev() does not return value.
[lincan.git] / lincan / README
1
2                 Linux CAN Driver (LinCAN) version 0.3.3
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                 
86 The actual version of driver have been latest tested it with
87   - PC104 Advantech PCM3680 dual channel board on 2.4 RT-Linux enabled kernel
88   - PiKRON ISA card on 2.4.and 2.6 Linux kernels
89   - PiKRON CAN extension board for PiMCX1 ARM BCC on 2.6 Linux kernels
90   - BfaD DIMM PC card on 2.4 RT-Linux enabled kernel
91   - KVASER pcican-q on 2.6 Linux kernel
92   - MICROSPACE msmcan on 2.4 Linux and RT-Linux enabled kernel
93   - Unicontrols PCAN ("unican"),PCAN-PCI ("unican-pci"), VCAN  ("unican-vme")
94   - EMS CPC-PCI cards ("ems_cpcpci")
95   - virtual board tested on all systems as wel
96 It takes more time to test driver with more cards.
97 Infrastructure and support for more than 20 boards with more
98 variants is prepared in the sources.
99
100
101 SOURCES AND URLs
102 ================
103
104 The LinCAN driver component page at OCERA web site
105 (not updated to the new version yet)
106
107   http://www.ocera.org/download/components/WP7/lincan-0.3.1.html
108   
109 List of related communication components
110   
111   http://www.ocera.org/download/components/WP7/index.html
112
113 The obtaining LinCAN and other CAN related components
114 from OCERA CVS repository at SourceForge
115
116   EXTCVS=":pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera"
117   cvs -d$EXTCVS login
118   cvs -z3 -d$EXTCVS co ocera/components/comm/can
119   
120 Web access into CVS
121
122   http://ocera.cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ocera/ocera/components/comm/can/lincan/
123
124 Experimental directory at maintainer's (Pavel Pisa's) pages 
125
126   http://cmp.felk.cvut.cz/~pisa/can/
127   http://cmp.felk.cvut.cz/~pisa/can/lincan-YYMMDD.tar.gz
128   
129 Please send comments, bug-fixes and enhancements directly to
130 Pavel Pisa <pisa@cmp.felk.cvut.cz> or to OCERA discussion
131 forum <https://sourceforge.net/forum/forum.php?forum_id=170893> 
132 and lists <ocera-development@lists.sourceforge.net>
133
134 Driver documentation can be found at
135
136   http://cmp.felk.cvut.cz/~pisa/can/doc/lincandoc-0.3.pdf
137
138 The anouncements of new version are published at FreshMeat page
139
140   http://freshmeat.net/projects/lincan/
141
142
143 COMPILATION of LinCAN releases
144 ==============================
145
146 Just type 'make' at the command line and driver module should compile
147 without errors for current running kernel. 
148
149 More information can be found in driver documentation at
150   http://cmp.felk.cvut.cz/~pisa/can/
151   http://cmp.felk.cvut.cz/~pisa/can/lincandoc-X.Y.pdf
152   
153 Some releases use experimental OMK make system, which requires
154 recent GNU make program version 3.81beta1 and above.
155 Makefiles can be switched to old ones by script
156
157   sh ./switch-omk2std
158   make
159
160 If you have problem to obtain recent GNU make program,
161
162  ftp://alpha.gnu.org/gnu/make/make-3.81beta4.tar.bz2
163
164 you can use our local copy
165
166   http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz
167
168
169 COMPILATION from CVS sources without full OCERA tree
170 ====================================================
171   
172 ---------------------------------------------------------------------------
173 Obtaining CVS sources of the CAN components only
174 ---------------------------------------------------------------------------
175   cvs -d:pserver:anonymous@ocera.cvs.sourceforge.net:/cvsroot/ocera login
176   cvs -z3 -d:pserver:anonymous@ocera.cvs.sourceforge.net:/cvsroot/ocera co
177          ocera/components/comm/can
178
179 ---------------------------------------------------------------------------
180 Commands to build OCERA CVS CAN components outside OCERA tree
181 ---------------------------------------------------------------------------
182   cd ocera/components/comm/can
183   ./switch2standalone
184   make
185
186 The selection of required features and options can be specified before make 
187 command invocation. Lines containing required changes to config.omk-default 
188 file should be stored in config.omk file. The config.omk is not altered by 
189 OMK system and options defined there override values defined in 
190 config.omk-default file. GNU make program version 3.81beta1 or newer is 
191 required by OMK make-system. If this is problem, LinCAN driver can be 
192 compiled with use of old style Makefiles as well.
193
194 ---------------------------------------------------------------------------
195 Old style Makefiles compilation of the LinCAN driver only
196 ---------------------------------------------------------------------------
197   cd ocera/components/comm/can/lincan
198   ./switch-omk2std
199   make
200
201
202 INSTALLATION
203 ============
204 Type 'make install' for standard make system compilation.
205 The driver should be copied into actual kernel version
206 modules directory "/lib/modules/x.y.z/kernel/drivers/char".
207
208 OMK system requires manual copy of files from "_compiled" tree
209 to its final destinations.
210
211 Create file "lincan.rules" with contents listed below in or linked
212 into "/etc/udev/rules.d" directory to enable automatic device nodes
213 creation for UDEV based system
214
215   # LinCAN driver
216   SUBSYSTEM=="can",GROUP="users",MODE="0660"
217
218 The driver automatic loding can be requested by addition of "lincan"
219 line into "/etc/modules" od Debian based systems.
220
221 The target hardware/board specific options should be added into
222 "/etc/modprobe.conf" file or file with similar functionality for your
223 distribution. The options are discusses in the next paragraph.
224
225 LOADING
226 =======
227
228 To load the driver type:
229 # insmod can.o hw='your hardware' irq='irq number' io='io address' <options>
230 Examples: # insmod can.o hw=pip5 irq=4 io=0x8000
231           # insmod can.o hw=virtual io=0
232
233 The hw argument can be one of:
234 - pip5, for the PIP5 computer by MPL
235 - pip6, for the PIP6 computer by MPL
236 - pip7, for the PIP7 computer by MPL
237 - pip8, for the PIP8 computer by MPL
238 - pccan-q, for the PCcan-Q ISA card by KVASER
239 - pccan-f, for the PCcan-F ISA card by KVASER
240 - pccan-s, for the PCcan-S ISA card by KVASER
241 - pccan-d, for the PCcan-D ISA card by KVASER
242 - pcican-q, for the PCIcan-Q PCI card by KVASER (4x SJA1000)
243 - pcican-d, for the PCIcan-Q PCI card by KVASER (2x SJA1000)
244 - pcican-s, for the PCIcan-Q PCI card by KVASER (1x SJA1000)
245 - smartcan for i82527 based card with indexed access
246 - nsican, for the CAN104 PC/104 card by NSI
247 - nsicanpci, for NSI CAN PCI card (2xi82527)
248 - cc104, for the CAN104 PC/104 card by Contemporary Controls
249 - aim104, for the AIM104CAN PC/104 card by Arcom Control Systems
250 - pc-i03, for the PC-I03 ISA card by IXXAT
251 - pcm3680, for the PCM-3680 PC/104 card by Advantech
252 - m437, for the M436 PC/104 card by SECO
253 - bfadcan for sja1000 CAN embedded card made by BFAD GmbH
254 - gensja1000io for many sja1000 I/O mapped cards (PCAN-PC/104 for example).
255 - pikronisa for ISA memory mapped sja1000 CAN card made by PiKRON Ltd.
256 - pimx1 for MX1_DIS1 extension board for PiMX1 ARM based BCC
257 - msmcan for MICROSPACE IO space indexed i82527
258 - unican for Unicontrols PCAN card
259 - unican-pci for Unicontrols PCAN-PCI card
260 - unican-vme for Unicontrols VCAN card
261 - ipci165 for IXXAT iPC-I 165 (PCI), requires CONFIG_OC_LINCAN_CARD_ipci165=y
262 - ems_cpcpci for EMS CPC-PCI card
263 - pcan_dongle for PEAK's printer port dongle addapter
264 - oscar for SJA1000 based card connected to ARM LH7A400 SoC
265 - eb8245 for Kontron EB8245 onboard CAN with SJA1000 controller
266 - adlink7841 for ADLINK PCI-7841 dual SJA1000 based card
267 - tscan1 for Technologic Systems' TS-CAN1 single SJA1000 based board
268 - ts7kv for Technologic Systems' TS-7KV Multi-function board with SJA1000
269    both these cards require CONFIG_OC_LINCAN_CARD_tscan1=y
270 - pcan_pci for PEAK System PCAN-PCI single, double or quad SJA1000 based board
271 - esdpci200 for the CAN/PCI-200 card by ESD Electronics board
272 - template, for yet unsupported hardware (you need to edit src/template.c)
273 - virtual, CAN channel for testing of software and driver without CAN hardware
274
275 options can be one of:
276 - major=<nr>, major specifies the major number of the driver.
277 - minor=<nr>, you can specify which minor numbers the driver should use for your
278   hardware.
279 - extended=[1|0], configures the driver to use extended message format.
280 - pelican=[1|0], configures the driver to set the CAN chips into pelican mode.
281 - baudrate=<nr>, sets the baudrate of the device(s)
282 - clockfreq=<nr>, the frequency of the CAN quartz
283 - stdmask=<nr>, sets the standard mask of the device
284 - extmask=<nr>, sets the extended mask of the device
285 - mo15mask=<nr>, sets the mask for message object 15 (i82527 only)
286 - processlocal=<nr>, controls distribution of send messages to Rx FIFOs
287                 0, no local outgoing messages delivery to Rx FIFOs
288                 1, default off, but can be controlled by individual filter settings
289                 2, all FIFOs receive local messages
290
291 There's still a lot of work to do, have a look at the TODO file for more
292 information.
293
294 Some boards support is compiled in only, when it is enabled through
295 config.omk file. It has to be stored in same directory as Makefile.rules
296 and config.omk-default is located.