Merge branch 'next' of git://git.kernel.org/pub/scm/linux/kernel/git/davej/cpufreq
[linux-2.6] / Documentation / networking / can.txt
1 ============================================================================
2
3 can.txt
4
5 Readme file for the Controller Area Network Protocol Family (aka Socket CAN)
6
7 This 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
38     6.4 The virtual CAN driver (vcan)
39     6.5 currently supported CAN hardware
40     6.6 todo
41
42   7 Credits
43
44 ============================================================================
45
46 1. Overview / What is Socket CAN
47 --------------------------------
48
49 The socketcan package is an implementation of CAN protocols
50 (Controller Area Network) for Linux.  CAN is a networking technology
51 which has widespread use in automation, embedded devices, and
52 automotive fields.  While there have been other CAN implementations
53 for Linux based on character devices, Socket CAN uses the Berkeley
54 socket API, the Linux network stack and implements the CAN device
55 drivers as network interfaces.  The CAN socket API has been designed
56 as similar as possible to the TCP/IP protocols to allow programmers,
57 familiar with network programming, to easily learn how to use CAN
58 sockets.
59
60 2. Motivation / Why using the socket API
61 ----------------------------------------
62
63 There have been CAN implementations for Linux before Socket CAN so the
64 question arises, why we have started another project.  Most existing
65 implementations come as a device driver for some CAN hardware, they
66 are based on character devices and provide comparatively little
67 functionality.  Usually, there is only a hardware-specific device
68 driver which provides a character device interface to send and
69 receive raw CAN frames, directly to/from the controller hardware.
70 Queueing of frames and higher-level transport protocols like ISO-TP
71 have to be implemented in user space applications.  Also, most
72 character-device implementations support only one single process to
73 open the device at a time, similar to a serial interface.  Exchanging
74 the CAN controller requires employment of another device driver and
75 often the need for adaption of large parts of the application to the
76 new driver's API.
77
78 Socket CAN was designed to overcome all of these limitations.  A new
79 protocol family has been implemented which provides a socket interface
80 to user space applications and which builds upon the Linux network
81 layer, so to use all of the provided queueing functionality.  A device
82 driver for CAN controller hardware registers itself with the Linux
83 network layer as a network device, so that CAN frames from the
84 controller can be passed up to the network layer and on to the CAN
85 protocol family module and also vice-versa.  Also, the protocol family
86 module provides an API for transport protocol modules to register, so
87 that any number of transport protocols can be loaded or unloaded
88 dynamically.  In fact, the can core module alone does not provide any
89 protocol and cannot be used without loading at least one additional
90 protocol module.  Multiple sockets can be opened at the same time,
91 on different or the same protocol module and they can listen/send
92 frames on different or the same CAN IDs.  Several sockets listening on
93 the same interface for frames with the same CAN ID are all passed the
94 same received matching CAN frames.  An application wishing to
95 communicate using a specific transport protocol, e.g. ISO-TP, just
96 selects that protocol when opening the socket, and then can read and
97 write application data byte streams, without having to deal with
98 CAN-IDs, frames, etc.
99
100 Similar functionality visible from user-space could be provided by a
101 character device, too, but this would lead to a technically inelegant
102 solution 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
140 3. 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
190   arbitration on the CAN bus the transmission of a low prio CAN-ID
191   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
238 4. 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 {
285                     /* 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 */
289             } 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
472 5. 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
485     disabled by using stattimer=0 on the module commandline.
486
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
539 6. 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
588   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
624
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
642   6.6 todo
643
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
650 7. 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)