]>
Commit | Line | Data |
---|---|---|
f7ab97f7 OH |
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 | |
e5d23048 OH |
38 | 6.4 The virtual CAN driver (vcan) |
39 | 6.5 currently supported CAN hardware | |
40 | 6.6 todo | |
f7ab97f7 OH |
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 | |
d9195881 | 190 | arbitration on the CAN bus the transmission of a low prio CAN-ID |
f7ab97f7 OH |
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 { | |
56690c21 OH |
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 */ | |
f7ab97f7 OH |
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 | |
d9195881 | 485 | disabled by using stattimer=0 on the module commandline. |
f7ab97f7 OH |
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 | ||
e5d23048 OH |
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 | |
f7ab97f7 OH |
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 | ||
e5d23048 | 642 | 6.6 todo |
f7ab97f7 OH |
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) |