blob: 2035bc4932f224685992ca57b29e64de5da4934e [file] [log] [blame]
Oliver Hartkoppf7ab97f2007-11-16 16:09:28 -08001============================================================================
2
3can.txt
4
5Readme file for the Controller Area Network Protocol Family (aka Socket CAN)
6
7This file contains
8
9 1 Overview / What is Socket CAN
10
11 2 Motivation / Why using the socket API
12
13 3 Socket CAN concept
14 3.1 receive lists
15 3.2 local loopback of sent frames
16 3.3 network security issues (capabilities)
17 3.4 network problem notifications
18
19 4 How to use Socket CAN
20 4.1 RAW protocol sockets with can_filters (SOCK_RAW)
21 4.1.1 RAW socket option CAN_RAW_FILTER
22 4.1.2 RAW socket option CAN_RAW_ERR_FILTER
23 4.1.3 RAW socket option CAN_RAW_LOOPBACK
24 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
25 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
26 4.3 connected transport protocols (SOCK_SEQPACKET)
27 4.4 unconnected transport protocols (SOCK_DGRAM)
28
29 5 Socket CAN core module
30 5.1 can.ko module params
31 5.2 procfs content
32 5.3 writing own CAN protocol modules
33
34 6 CAN network drivers
35 6.1 general settings
36 6.2 local loopback of sent frames
37 6.3 CAN controller hardware filters
Oliver Hartkoppe5d23042008-09-23 14:53:14 -070038 6.4 The virtual CAN driver (vcan)
39 6.5 currently supported CAN hardware
40 6.6 todo
Oliver Hartkoppf7ab97f2007-11-16 16:09:28 -080041
42 7 Credits
43
44============================================================================
45
461. Overview / What is Socket CAN
47--------------------------------
48
49The socketcan package is an implementation of CAN protocols
50(Controller Area Network) for Linux. CAN is a networking technology
51which has widespread use in automation, embedded devices, and
52automotive fields. While there have been other CAN implementations
53for Linux based on character devices, Socket CAN uses the Berkeley
54socket API, the Linux network stack and implements the CAN device
55drivers as network interfaces. The CAN socket API has been designed
56as similar as possible to the TCP/IP protocols to allow programmers,
57familiar with network programming, to easily learn how to use CAN
58sockets.
59
602. Motivation / Why using the socket API
61----------------------------------------
62
63There have been CAN implementations for Linux before Socket CAN so the
64question arises, why we have started another project. Most existing
65implementations come as a device driver for some CAN hardware, they
66are based on character devices and provide comparatively little
67functionality. Usually, there is only a hardware-specific device
68driver which provides a character device interface to send and
69receive raw CAN frames, directly to/from the controller hardware.
70Queueing of frames and higher-level transport protocols like ISO-TP
71have to be implemented in user space applications. Also, most
72character-device implementations support only one single process to
73open the device at a time, similar to a serial interface. Exchanging
74the CAN controller requires employment of another device driver and
75often the need for adaption of large parts of the application to the
76new driver's API.
77
78Socket CAN was designed to overcome all of these limitations. A new
79protocol family has been implemented which provides a socket interface
80to user space applications and which builds upon the Linux network
81layer, so to use all of the provided queueing functionality. A device
82driver for CAN controller hardware registers itself with the Linux
83network layer as a network device, so that CAN frames from the
84controller can be passed up to the network layer and on to the CAN
85protocol family module and also vice-versa. Also, the protocol family
86module provides an API for transport protocol modules to register, so
87that any number of transport protocols can be loaded or unloaded
88dynamically. In fact, the can core module alone does not provide any
89protocol and cannot be used without loading at least one additional
90protocol module. Multiple sockets can be opened at the same time,
91on different or the same protocol module and they can listen/send
92frames on different or the same CAN IDs. Several sockets listening on
93the same interface for frames with the same CAN ID are all passed the
94same received matching CAN frames. An application wishing to
95communicate using a specific transport protocol, e.g. ISO-TP, just
96selects that protocol when opening the socket, and then can read and
97write application data byte streams, without having to deal with
98CAN-IDs, frames, etc.
99
100Similar functionality visible from user-space could be provided by a
101character device, too, but this would lead to a technically inelegant
102solution for a couple of reasons:
103
104* Intricate usage. Instead of passing a protocol argument to
105 socket(2) and using bind(2) to select a CAN interface and CAN ID, an
106 application would have to do all these operations using ioctl(2)s.
107
108* Code duplication. A character device cannot make use of the Linux
109 network queueing code, so all that code would have to be duplicated
110 for CAN networking.
111
112* Abstraction. In most existing character-device implementations, the
113 hardware-specific device driver for a CAN controller directly
114 provides the character device for the application to work with.
115 This is at least very unusual in Unix systems for both, char and
116 block devices. For example you don't have a character device for a
117 certain UART of a serial interface, a certain sound chip in your
118 computer, a SCSI or IDE controller providing access to your hard
119 disk or tape streamer device. Instead, you have abstraction layers
120 which provide a unified character or block device interface to the
121 application on the one hand, and a interface for hardware-specific
122 device drivers on the other hand. These abstractions are provided
123 by subsystems like the tty layer, the audio subsystem or the SCSI
124 and IDE subsystems for the devices mentioned above.
125
126 The easiest way to implement a CAN device driver is as a character
127 device without such a (complete) abstraction layer, as is done by most
128 existing drivers. The right way, however, would be to add such a
129 layer with all the functionality like registering for certain CAN
130 IDs, supporting several open file descriptors and (de)multiplexing
131 CAN frames between them, (sophisticated) queueing of CAN frames, and
132 providing an API for device drivers to register with. However, then
133 it would be no more difficult, or may be even easier, to use the
134 networking framework provided by the Linux kernel, and this is what
135 Socket CAN does.
136
137 The use of the networking framework of the Linux kernel is just the
138 natural and most appropriate way to implement CAN for Linux.
139
1403. Socket CAN concept
141---------------------
142
143 As described in chapter 2 it is the main goal of Socket CAN to
144 provide a socket interface to user space applications which builds
145 upon the Linux network layer. In contrast to the commonly known
146 TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
147 medium that has no MAC-layer addressing like ethernet. The CAN-identifier
148 (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
149 have to be chosen uniquely on the bus. When designing a CAN-ECU
150 network the CAN-IDs are mapped to be sent by a specific ECU.
151 For this reason a CAN-ID can be treated best as a kind of source address.
152
153 3.1 receive lists
154
155 The network transparent access of multiple applications leads to the
156 problem that different applications may be interested in the same
157 CAN-IDs from the same CAN network interface. The Socket CAN core
158 module - which implements the protocol family CAN - provides several
159 high efficient receive lists for this reason. If e.g. a user space
160 application opens a CAN RAW socket, the raw protocol module itself
161 requests the (range of) CAN-IDs from the Socket CAN core that are
162 requested by the user. The subscription and unsubscription of
163 CAN-IDs can be done for specific CAN interfaces or for all(!) known
164 CAN interfaces with the can_rx_(un)register() functions provided to
165 CAN protocol modules by the SocketCAN core (see chapter 5).
166 To optimize the CPU usage at runtime the receive lists are split up
167 into several specific lists per device that match the requested
168 filter complexity for a given use-case.
169
170 3.2 local loopback of sent frames
171
172 As known from other networking concepts the data exchanging
173 applications may run on the same or different nodes without any
174 change (except for the according addressing information):
175
176 ___ ___ ___ _______ ___
177 | _ | | _ | | _ | | _ _ | | _ |
178 ||A|| ||B|| ||C|| ||A| |B|| ||C||
179 |___| |___| |___| |_______| |___|
180 | | | | |
181 -----------------(1)- CAN bus -(2)---------------
182
183 To ensure that application A receives the same information in the
184 example (2) as it would receive in example (1) there is need for
185 some kind of local loopback of the sent CAN frames on the appropriate
186 node.
187
188 The Linux network devices (by default) just can handle the
189 transmission and reception of media dependent frames. Due to the
Matt LaPlanted9195882008-07-25 19:45:33 -0700190 arbitration on the CAN bus the transmission of a low prio CAN-ID
Oliver Hartkoppf7ab97f2007-11-16 16:09:28 -0800191 may be delayed by the reception of a high prio CAN frame. To
192 reflect the correct* traffic on the node the loopback of the sent
193 data has to be performed right after a successful transmission. If
194 the CAN network interface is not capable of performing the loopback for
195 some reason the SocketCAN core can do this task as a fallback solution.
196 See chapter 6.2 for details (recommended).
197
198 The loopback functionality is enabled by default to reflect standard
199 networking behaviour for CAN applications. Due to some requests from
200 the RT-SocketCAN group the loopback optionally may be disabled for each
201 separate socket. See sockopts from the CAN RAW sockets in chapter 4.1.
202
203 * = you really like to have this when you're running analyser tools
204 like 'candump' or 'cansniffer' on the (same) node.
205
206 3.3 network security issues (capabilities)
207
208 The Controller Area Network is a local field bus transmitting only
209 broadcast messages without any routing and security concepts.
210 In the majority of cases the user application has to deal with
211 raw CAN frames. Therefore it might be reasonable NOT to restrict
212 the CAN access only to the user root, as known from other networks.
213 Since the currently implemented CAN_RAW and CAN_BCM sockets can only
214 send and receive frames to/from CAN interfaces it does not affect
215 security of others networks to allow all users to access the CAN.
216 To enable non-root users to access CAN_RAW and CAN_BCM protocol
217 sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be
218 selected at kernel compile time.
219
220 3.4 network problem notifications
221
222 The use of the CAN bus may lead to several problems on the physical
223 and media access control layer. Detecting and logging of these lower
224 layer problems is a vital requirement for CAN users to identify
225 hardware issues on the physical transceiver layer as well as
226 arbitration problems and error frames caused by the different
227 ECUs. The occurrence of detected errors are important for diagnosis
228 and have to be logged together with the exact timestamp. For this
229 reason the CAN interface driver can generate so called Error Frames
230 that can optionally be passed to the user application in the same
231 way as other CAN frames. Whenever an error on the physical layer
232 or the MAC layer is detected (e.g. by the CAN controller) the driver
233 creates an appropriate error frame. Error frames can be requested by
234 the user application using the common CAN filter mechanisms. Inside
235 this filter definition the (interested) type of errors may be
236 selected. The reception of error frames is disabled by default.
237
2384. How to use Socket CAN
239------------------------
240
241 Like TCP/IP, you first need to open a socket for communicating over a
242 CAN network. Since Socket CAN implements a new protocol family, you
243 need to pass PF_CAN as the first argument to the socket(2) system
244 call. Currently, there are two CAN protocols to choose from, the raw
245 socket protocol and the broadcast manager (BCM). So to open a socket,
246 you would write
247
248 s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
249
250 and
251
252 s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
253
254 respectively. After the successful creation of the socket, you would
255 normally use the bind(2) system call to bind the socket to a CAN
256 interface (which is different from TCP/IP due to different addressing
257 - see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM)
258 the socket, you can read(2) and write(2) from/to the socket or use
259 send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
260 on the socket as usual. There are also CAN specific socket options
261 described below.
262
263 The basic CAN frame structure and the sockaddr structure are defined
264 in include/linux/can.h:
265
266 struct can_frame {
267 canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */
268 __u8 can_dlc; /* data length code: 0 .. 8 */
269 __u8 data[8] __attribute__((aligned(8)));
270 };
271
272 The alignment of the (linear) payload data[] to a 64bit boundary
273 allows the user to define own structs and unions to easily access the
274 CAN payload. There is no given byteorder on the CAN bus by
275 default. A read(2) system call on a CAN_RAW socket transfers a
276 struct can_frame to the user space.
277
278 The sockaddr_can structure has an interface index like the
279 PF_PACKET socket, that also binds to a specific interface:
280
281 struct sockaddr_can {
282 sa_family_t can_family;
283 int can_ifindex;
284 union {
Oliver Hartkopp56690c22008-04-15 00:46:38 -0700285 /* transport protocol class address info (e.g. ISOTP) */
286 struct { canid_t rx_id, tx_id; } tp;
287
288 /* reserved for future CAN protocols address information */
Oliver Hartkoppf7ab97f2007-11-16 16:09:28 -0800289 } can_addr;
290 };
291
292 To determine the interface index an appropriate ioctl() has to
293 be used (example for CAN_RAW sockets without error checking):
294
295 int s;
296 struct sockaddr_can addr;
297 struct ifreq ifr;
298
299 s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
300
301 strcpy(ifr.ifr_name, "can0" );
302 ioctl(s, SIOCGIFINDEX, &ifr);
303
304 addr.can_family = AF_CAN;
305 addr.can_ifindex = ifr.ifr_ifindex;
306
307 bind(s, (struct sockaddr *)&addr, sizeof(addr));
308
309 (..)
310
311 To bind a socket to all(!) CAN interfaces the interface index must
312 be 0 (zero). In this case the socket receives CAN frames from every
313 enabled CAN interface. To determine the originating CAN interface
314 the system call recvfrom(2) may be used instead of read(2). To send
315 on a socket that is bound to 'any' interface sendto(2) is needed to
316 specify the outgoing interface.
317
318 Reading CAN frames from a bound CAN_RAW socket (see above) consists
319 of reading a struct can_frame:
320
321 struct can_frame frame;
322
323 nbytes = read(s, &frame, sizeof(struct can_frame));
324
325 if (nbytes < 0) {
326 perror("can raw socket read");
327 return 1;
328 }
329
330 /* paraniod check ... */
331 if (nbytes < sizeof(struct can_frame)) {
332 fprintf(stderr, "read: incomplete CAN frame\n");
333 return 1;
334 }
335
336 /* do something with the received CAN frame */
337
338 Writing CAN frames can be done similarly, with the write(2) system call:
339
340 nbytes = write(s, &frame, sizeof(struct can_frame));
341
342 When the CAN interface is bound to 'any' existing CAN interface
343 (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the
344 information about the originating CAN interface is needed:
345
346 struct sockaddr_can addr;
347 struct ifreq ifr;
348 socklen_t len = sizeof(addr);
349 struct can_frame frame;
350
351 nbytes = recvfrom(s, &frame, sizeof(struct can_frame),
352 0, (struct sockaddr*)&addr, &len);
353
354 /* get interface name of the received CAN frame */
355 ifr.ifr_ifindex = addr.can_ifindex;
356 ioctl(s, SIOCGIFNAME, &ifr);
357 printf("Received a CAN frame from interface %s", ifr.ifr_name);
358
359 To write CAN frames on sockets bound to 'any' CAN interface the
360 outgoing interface has to be defined certainly.
361
362 strcpy(ifr.ifr_name, "can0");
363 ioctl(s, SIOCGIFINDEX, &ifr);
364 addr.can_ifindex = ifr.ifr_ifindex;
365 addr.can_family = AF_CAN;
366
367 nbytes = sendto(s, &frame, sizeof(struct can_frame),
368 0, (struct sockaddr*)&addr, sizeof(addr));
369
370 4.1 RAW protocol sockets with can_filters (SOCK_RAW)
371
372 Using CAN_RAW sockets is extensively comparable to the commonly
373 known access to CAN character devices. To meet the new possibilities
374 provided by the multi user SocketCAN approach, some reasonable
375 defaults are set at RAW socket binding time:
376
377 - The filters are set to exactly one filter receiving everything
378 - The socket only receives valid data frames (=> no error frames)
379 - The loopback of sent CAN frames is enabled (see chapter 3.2)
380 - The socket does not receive its own sent frames (in loopback mode)
381
382 These default settings may be changed before or after binding the socket.
383 To use the referenced definitions of the socket options for CAN_RAW
384 sockets, include <linux/can/raw.h>.
385
386 4.1.1 RAW socket option CAN_RAW_FILTER
387
388 The reception of CAN frames using CAN_RAW sockets can be controlled
389 by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
390
391 The CAN filter structure is defined in include/linux/can.h:
392
393 struct can_filter {
394 canid_t can_id;
395 canid_t can_mask;
396 };
397
398 A filter matches, when
399
400 <received_can_id> & mask == can_id & mask
401
402 which is analogous to known CAN controllers hardware filter semantics.
403 The filter can be inverted in this semantic, when the CAN_INV_FILTER
404 bit is set in can_id element of the can_filter structure. In
405 contrast to CAN controller hardware filters the user may set 0 .. n
406 receive filters for each open socket separately:
407
408 struct can_filter rfilter[2];
409
410 rfilter[0].can_id = 0x123;
411 rfilter[0].can_mask = CAN_SFF_MASK;
412 rfilter[1].can_id = 0x200;
413 rfilter[1].can_mask = 0x700;
414
415 setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter));
416
417 To disable the reception of CAN frames on the selected CAN_RAW socket:
418
419 setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
420
421 To set the filters to zero filters is quite obsolete as not read
422 data causes the raw socket to discard the received CAN frames. But
423 having this 'send only' use-case we may remove the receive list in the
424 Kernel to save a little (really a very little!) CPU usage.
425
426 4.1.2 RAW socket option CAN_RAW_ERR_FILTER
427
428 As described in chapter 3.4 the CAN interface driver can generate so
429 called Error Frames that can optionally be passed to the user
430 application in the same way as other CAN frames. The possible
431 errors are divided into different error classes that may be filtered
432 using the appropriate error mask. To register for every possible
433 error condition CAN_ERR_MASK can be used as value for the error mask.
434 The values for the error mask are defined in linux/can/error.h .
435
436 can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF );
437
438 setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER,
439 &err_mask, sizeof(err_mask));
440
441 4.1.3 RAW socket option CAN_RAW_LOOPBACK
442
443 To meet multi user needs the local loopback is enabled by default
444 (see chapter 3.2 for details). But in some embedded use-cases
445 (e.g. when only one application uses the CAN bus) this loopback
446 functionality can be disabled (separately for each socket):
447
448 int loopback = 0; /* 0 = disabled, 1 = enabled (default) */
449
450 setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback));
451
452 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
453
454 When the local loopback is enabled, all the sent CAN frames are
455 looped back to the open CAN sockets that registered for the CAN
456 frames' CAN-ID on this given interface to meet the multi user
457 needs. The reception of the CAN frames on the same socket that was
458 sending the CAN frame is assumed to be unwanted and therefore
459 disabled by default. This default behaviour may be changed on
460 demand:
461
462 int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */
463
464 setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS,
465 &recv_own_msgs, sizeof(recv_own_msgs));
466
467 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
468 4.3 connected transport protocols (SOCK_SEQPACKET)
469 4.4 unconnected transport protocols (SOCK_DGRAM)
470
471
4725. Socket CAN core module
473-------------------------
474
475 The Socket CAN core module implements the protocol family
476 PF_CAN. CAN protocol modules are loaded by the core module at
477 runtime. The core module provides an interface for CAN protocol
478 modules to subscribe needed CAN IDs (see chapter 3.1).
479
480 5.1 can.ko module params
481
482 - stats_timer: To calculate the Socket CAN core statistics
483 (e.g. current/maximum frames per second) this 1 second timer is
484 invoked at can.ko module start time by default. This timer can be
Matt LaPlanted9195882008-07-25 19:45:33 -0700485 disabled by using stattimer=0 on the module commandline.
Oliver Hartkoppf7ab97f2007-11-16 16:09:28 -0800486
487 - debug: (removed since SocketCAN SVN r546)
488
489 5.2 procfs content
490
491 As described in chapter 3.1 the Socket CAN core uses several filter
492 lists to deliver received CAN frames to CAN protocol modules. These
493 receive lists, their filters and the count of filter matches can be
494 checked in the appropriate receive list. All entries contain the
495 device and a protocol module identifier:
496
497 foo@bar:~$ cat /proc/net/can/rcvlist_all
498
499 receive list 'rx_all':
500 (vcan3: no entry)
501 (vcan2: no entry)
502 (vcan1: no entry)
503 device can_id can_mask function userdata matches ident
504 vcan0 000 00000000 f88e6370 f6c6f400 0 raw
505 (any: no entry)
506
507 In this example an application requests any CAN traffic from vcan0.
508
509 rcvlist_all - list for unfiltered entries (no filter operations)
510 rcvlist_eff - list for single extended frame (EFF) entries
511 rcvlist_err - list for error frames masks
512 rcvlist_fil - list for mask/value filters
513 rcvlist_inv - list for mask/value filters (inverse semantic)
514 rcvlist_sff - list for single standard frame (SFF) entries
515
516 Additional procfs files in /proc/net/can
517
518 stats - Socket CAN core statistics (rx/tx frames, match ratios, ...)
519 reset_stats - manual statistic reset
520 version - prints the Socket CAN core version and the ABI version
521
522 5.3 writing own CAN protocol modules
523
524 To implement a new protocol in the protocol family PF_CAN a new
525 protocol has to be defined in include/linux/can.h .
526 The prototypes and definitions to use the Socket CAN core can be
527 accessed by including include/linux/can/core.h .
528 In addition to functions that register the CAN protocol and the
529 CAN device notifier chain there are functions to subscribe CAN
530 frames received by CAN interfaces and to send CAN frames:
531
532 can_rx_register - subscribe CAN frames from a specific interface
533 can_rx_unregister - unsubscribe CAN frames from a specific interface
534 can_send - transmit a CAN frame (optional with local loopback)
535
536 For details see the kerneldoc documentation in net/can/af_can.c or
537 the source code of net/can/raw.c or net/can/bcm.c .
538
5396. CAN network drivers
540----------------------
541
542 Writing a CAN network device driver is much easier than writing a
543 CAN character device driver. Similar to other known network device
544 drivers you mainly have to deal with:
545
546 - TX: Put the CAN frame from the socket buffer to the CAN controller.
547 - RX: Put the CAN frame from the CAN controller to the socket buffer.
548
549 See e.g. at Documentation/networking/netdevices.txt . The differences
550 for writing CAN network device driver are described below:
551
552 6.1 general settings
553
554 dev->type = ARPHRD_CAN; /* the netdevice hardware type */
555 dev->flags = IFF_NOARP; /* CAN has no arp */
556
557 dev->mtu = sizeof(struct can_frame);
558
559 The struct can_frame is the payload of each socket buffer in the
560 protocol family PF_CAN.
561
562 6.2 local loopback of sent frames
563
564 As described in chapter 3.2 the CAN network device driver should
565 support a local loopback functionality similar to the local echo
566 e.g. of tty devices. In this case the driver flag IFF_ECHO has to be
567 set to prevent the PF_CAN core from locally echoing sent frames
568 (aka loopback) as fallback solution:
569
570 dev->flags = (IFF_NOARP | IFF_ECHO);
571
572 6.3 CAN controller hardware filters
573
574 To reduce the interrupt load on deep embedded systems some CAN
575 controllers support the filtering of CAN IDs or ranges of CAN IDs.
576 These hardware filter capabilities vary from controller to
577 controller and have to be identified as not feasible in a multi-user
578 networking approach. The use of the very controller specific
579 hardware filters could make sense in a very dedicated use-case, as a
580 filter on driver level would affect all users in the multi-user
581 system. The high efficient filter sets inside the PF_CAN core allow
582 to set different multiple filters for each socket separately.
583 Therefore the use of hardware filters goes to the category 'handmade
584 tuning on deep embedded systems'. The author is running a MPC603e
585 @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
586 load without any problems ...
587
Oliver Hartkoppe5d23042008-09-23 14:53:14 -0700588 6.4 The virtual CAN driver (vcan)
589
590 Similar to the network loopback devices, vcan offers a virtual local
591 CAN interface. A full qualified address on CAN consists of
592
593 - a unique CAN Identifier (CAN ID)
594 - the CAN bus this CAN ID is transmitted on (e.g. can0)
595
596 so in common use cases more than one virtual CAN interface is needed.
597
598 The virtual CAN interfaces allow the transmission and reception of CAN
599 frames without real CAN controller hardware. Virtual CAN network
600 devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ...
601 When compiled as a module the virtual CAN driver module is called vcan.ko
602
603 Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel
604 netlink interface to create vcan network devices. The creation and
605 removal of vcan network devices can be managed with the ip(8) tool:
606
607 - Create a virtual CAN network interface:
608 ip link add type vcan
609
610 - Create a virtual CAN network interface with a specific name 'vcan42':
611 ip link add dev vcan42 type vcan
612
613 - Remove a (virtual CAN) network interface 'vcan42':
614 ip link del vcan42
615
616 The tool 'vcan' from the SocketCAN SVN repository on BerliOS is obsolete.
617
618 Virtual CAN network device creation in older Kernels:
619 In Linux Kernel versions < 2.6.24 the vcan driver creates 4 vcan
620 netdevices at module load time by default. This value can be changed
621 with the module parameter 'numdev'. E.g. 'modprobe vcan numdev=8'
622
623 6.5 currently supported CAN hardware
Oliver Hartkoppf7ab97f2007-11-16 16:09:28 -0800624
625 On the project website http://developer.berlios.de/projects/socketcan
626 there are different drivers available:
627
628 vcan: Virtual CAN interface driver (if no real hardware is available)
629 sja1000: Philips SJA1000 CAN controller (recommended)
630 i82527: Intel i82527 CAN controller
631 mscan: Motorola/Freescale CAN controller (e.g. inside SOC MPC5200)
632 ccan: CCAN controller core (e.g. inside SOC h7202)
633 slcan: For a bunch of CAN adaptors that are attached via a
634 serial line ASCII protocol (for serial / USB adaptors)
635
636 Additionally the different CAN adaptors (ISA/PCI/PCMCIA/USB/Parport)
637 from PEAK Systemtechnik support the CAN netdevice driver model
638 since Linux driver v6.0: http://www.peak-system.com/linux/index.htm
639
640 Please check the Mailing Lists on the berlios OSS project website.
641
Oliver Hartkoppe5d23042008-09-23 14:53:14 -0700642 6.6 todo
Oliver Hartkoppf7ab97f2007-11-16 16:09:28 -0800643
644 The configuration interface for CAN network drivers is still an open
645 issue that has not been finalized in the socketcan project. Also the
646 idea of having a library module (candev.ko) that holds functions
647 that are needed by all CAN netdevices is not ready to ship.
648 Your contribution is welcome.
649
6507. Credits
651----------
652
653 Oliver Hartkopp (PF_CAN core, filters, drivers, bcm)
654 Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
655 Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
656 Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews)
657 Robert Schwebel (design reviews, PTXdist integration)
658 Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
659 Benedikt Spranger (reviews)
660 Thomas Gleixner (LKML reviews, coding style, posting hints)
661 Andrey Volkov (kernel subtree structure, ioctls, mscan driver)
662 Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
663 Klaus Hitschler (PEAK driver integration)
664 Uwe Koppe (CAN netdevices with PF_PACKET approach)
665 Michael Schulze (driver layer loopback requirement, RT CAN drivers review)