Commit | Line | Data |
---|---|---|
7d597739 RS |
1 | =================================== |
2 | SocketCAN - Controller Area Network | |
3 | =================================== | |
4 | ||
5 | Overview / What is SocketCAN | |
6 | ============================ | |
7 | ||
8 | The socketcan package is an implementation of CAN protocols | |
9 | (Controller Area Network) for Linux. CAN is a networking technology | |
10 | which has widespread use in automation, embedded devices, and | |
11 | automotive fields. While there have been other CAN implementations | |
12 | for Linux based on character devices, SocketCAN uses the Berkeley | |
13 | socket API, the Linux network stack and implements the CAN device | |
14 | drivers as network interfaces. The CAN socket API has been designed | |
15 | as similar as possible to the TCP/IP protocols to allow programmers, | |
16 | familiar with network programming, to easily learn how to use CAN | |
17 | sockets. | |
18 | ||
19 | ||
20 | .. _socketcan-motivation: | |
21 | ||
22 | Motivation / Why Using the Socket API | |
23 | ===================================== | |
24 | ||
25 | There have been CAN implementations for Linux before SocketCAN so the | |
26 | question arises, why we have started another project. Most existing | |
27 | implementations come as a device driver for some CAN hardware, they | |
28 | are based on character devices and provide comparatively little | |
29 | functionality. Usually, there is only a hardware-specific device | |
30 | driver which provides a character device interface to send and | |
31 | receive raw CAN frames, directly to/from the controller hardware. | |
32 | Queueing of frames and higher-level transport protocols like ISO-TP | |
33 | have to be implemented in user space applications. Also, most | |
34 | character-device implementations support only one single process to | |
35 | open the device at a time, similar to a serial interface. Exchanging | |
36 | the CAN controller requires employment of another device driver and | |
37 | often the need for adaption of large parts of the application to the | |
38 | new driver's API. | |
39 | ||
40 | SocketCAN was designed to overcome all of these limitations. A new | |
41 | protocol family has been implemented which provides a socket interface | |
42 | to user space applications and which builds upon the Linux network | |
43 | layer, enabling use all of the provided queueing functionality. A device | |
44 | driver for CAN controller hardware registers itself with the Linux | |
45 | network layer as a network device, so that CAN frames from the | |
46 | controller can be passed up to the network layer and on to the CAN | |
47 | protocol family module and also vice-versa. Also, the protocol family | |
48 | module provides an API for transport protocol modules to register, so | |
49 | that any number of transport protocols can be loaded or unloaded | |
50 | dynamically. In fact, the can core module alone does not provide any | |
51 | protocol and cannot be used without loading at least one additional | |
52 | protocol module. Multiple sockets can be opened at the same time, | |
53 | on different or the same protocol module and they can listen/send | |
54 | frames on different or the same CAN IDs. Several sockets listening on | |
55 | the same interface for frames with the same CAN ID are all passed the | |
56 | same received matching CAN frames. An application wishing to | |
57 | communicate using a specific transport protocol, e.g. ISO-TP, just | |
58 | selects that protocol when opening the socket, and then can read and | |
59 | write application data byte streams, without having to deal with | |
60 | CAN-IDs, frames, etc. | |
61 | ||
62 | Similar functionality visible from user-space could be provided by a | |
63 | character device, too, but this would lead to a technically inelegant | |
64 | solution for a couple of reasons: | |
65 | ||
66 | * **Intricate usage:** Instead of passing a protocol argument to | |
67 | socket(2) and using bind(2) to select a CAN interface and CAN ID, an | |
68 | application would have to do all these operations using ioctl(2)s. | |
69 | ||
70 | * **Code duplication:** A character device cannot make use of the Linux | |
71 | network queueing code, so all that code would have to be duplicated | |
72 | for CAN networking. | |
73 | ||
74 | * **Abstraction:** In most existing character-device implementations, the | |
75 | hardware-specific device driver for a CAN controller directly | |
76 | provides the character device for the application to work with. | |
77 | This is at least very unusual in Unix systems for both, char and | |
78 | block devices. For example you don't have a character device for a | |
79 | certain UART of a serial interface, a certain sound chip in your | |
80 | computer, a SCSI or IDE controller providing access to your hard | |
81 | disk or tape streamer device. Instead, you have abstraction layers | |
82 | which provide a unified character or block device interface to the | |
83 | application on the one hand, and a interface for hardware-specific | |
84 | device drivers on the other hand. These abstractions are provided | |
85 | by subsystems like the tty layer, the audio subsystem or the SCSI | |
86 | and IDE subsystems for the devices mentioned above. | |
87 | ||
88 | The easiest way to implement a CAN device driver is as a character | |
89 | device without such a (complete) abstraction layer, as is done by most | |
90 | existing drivers. The right way, however, would be to add such a | |
91 | layer with all the functionality like registering for certain CAN | |
92 | IDs, supporting several open file descriptors and (de)multiplexing | |
93 | CAN frames between them, (sophisticated) queueing of CAN frames, and | |
94 | providing an API for device drivers to register with. However, then | |
95 | it would be no more difficult, or may be even easier, to use the | |
96 | networking framework provided by the Linux kernel, and this is what | |
97 | SocketCAN does. | |
98 | ||
99 | The use of the networking framework of the Linux kernel is just the | |
100 | natural and most appropriate way to implement CAN for Linux. | |
101 | ||
102 | ||
103 | .. _socketcan-concept: | |
104 | ||
105 | SocketCAN Concept | |
106 | ================= | |
107 | ||
108 | As described in :ref:`socketcan-motivation` the main goal of SocketCAN is to | |
109 | provide a socket interface to user space applications which builds | |
110 | upon the Linux network layer. In contrast to the commonly known | |
111 | TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) | |
112 | medium that has no MAC-layer addressing like ethernet. The CAN-identifier | |
113 | (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs | |
114 | have to be chosen uniquely on the bus. When designing a CAN-ECU | |
115 | network the CAN-IDs are mapped to be sent by a specific ECU. | |
116 | For this reason a CAN-ID can be treated best as a kind of source address. | |
117 | ||
118 | ||
119 | .. _socketcan-receive-lists: | |
120 | ||
121 | Receive Lists | |
122 | ------------- | |
123 | ||
124 | The network transparent access of multiple applications leads to the | |
125 | problem that different applications may be interested in the same | |
126 | CAN-IDs from the same CAN network interface. The SocketCAN core | |
127 | module - which implements the protocol family CAN - provides several | |
128 | high efficient receive lists for this reason. If e.g. a user space | |
129 | application opens a CAN RAW socket, the raw protocol module itself | |
130 | requests the (range of) CAN-IDs from the SocketCAN core that are | |
131 | requested by the user. The subscription and unsubscription of | |
132 | CAN-IDs can be done for specific CAN interfaces or for all(!) known | |
133 | CAN interfaces with the can_rx_(un)register() functions provided to | |
134 | CAN protocol modules by the SocketCAN core (see :ref:`socketcan-core-module`). | |
135 | To optimize the CPU usage at runtime the receive lists are split up | |
136 | into several specific lists per device that match the requested | |
137 | filter complexity for a given use-case. | |
138 | ||
139 | ||
140 | .. _socketcan-local-loopback1: | |
141 | ||
142 | Local Loopback of Sent Frames | |
143 | ----------------------------- | |
144 | ||
145 | As known from other networking concepts the data exchanging | |
146 | applications may run on the same or different nodes without any | |
147 | change (except for the according addressing information): | |
148 | ||
149 | .. code:: | |
150 | ||
151 | ___ ___ ___ _______ ___ | |
152 | | _ | | _ | | _ | | _ _ | | _ | | |
153 | ||A|| ||B|| ||C|| ||A| |B|| ||C|| | |
154 | |___| |___| |___| |_______| |___| | |
155 | | | | | | | |
156 | -----------------(1)- CAN bus -(2)--------------- | |
157 | ||
158 | To ensure that application A receives the same information in the | |
159 | example (2) as it would receive in example (1) there is need for | |
160 | some kind of local loopback of the sent CAN frames on the appropriate | |
161 | node. | |
162 | ||
163 | The Linux network devices (by default) just can handle the | |
164 | transmission and reception of media dependent frames. Due to the | |
165 | arbitration on the CAN bus the transmission of a low prio CAN-ID | |
166 | may be delayed by the reception of a high prio CAN frame. To | |
b7017450 | 167 | reflect the correct [#f1]_ traffic on the node the loopback of the sent |
7d597739 RS |
168 | data has to be performed right after a successful transmission. If |
169 | the CAN network interface is not capable of performing the loopback for | |
170 | some reason the SocketCAN core can do this task as a fallback solution. | |
a9cf02c6 | 171 | See :ref:`socketcan-local-loopback2` for details (recommended). |
7d597739 RS |
172 | |
173 | The loopback functionality is enabled by default to reflect standard | |
174 | networking behaviour for CAN applications. Due to some requests from | |
175 | the RT-SocketCAN group the loopback optionally may be disabled for each | |
176 | separate socket. See sockopts from the CAN RAW sockets in :ref:`socketcan-raw-sockets`. | |
177 | ||
b7017450 | 178 | .. [#f1] you really like to have this when you're running analyser |
7d597739 RS |
179 | tools like 'candump' or 'cansniffer' on the (same) node. |
180 | ||
181 | ||
182 | .. _socketcan-network-problem-notifications: | |
183 | ||
184 | Network Problem Notifications | |
185 | ----------------------------- | |
186 | ||
187 | The use of the CAN bus may lead to several problems on the physical | |
188 | and media access control layer. Detecting and logging of these lower | |
189 | layer problems is a vital requirement for CAN users to identify | |
190 | hardware issues on the physical transceiver layer as well as | |
191 | arbitration problems and error frames caused by the different | |
192 | ECUs. The occurrence of detected errors are important for diagnosis | |
193 | and have to be logged together with the exact timestamp. For this | |
194 | reason the CAN interface driver can generate so called Error Message | |
195 | Frames that can optionally be passed to the user application in the | |
196 | same way as other CAN frames. Whenever an error on the physical layer | |
197 | or the MAC layer is detected (e.g. by the CAN controller) the driver | |
198 | creates an appropriate error message frame. Error messages frames can | |
199 | be requested by the user application using the common CAN filter | |
200 | mechanisms. Inside this filter definition the (interested) type of | |
201 | errors may be selected. The reception of error messages is disabled | |
202 | by default. The format of the CAN error message frame is briefly | |
203 | described in the Linux header file "include/uapi/linux/can/error.h". | |
204 | ||
205 | ||
206 | How to use SocketCAN | |
207 | ==================== | |
208 | ||
209 | Like TCP/IP, you first need to open a socket for communicating over a | |
210 | CAN network. Since SocketCAN implements a new protocol family, you | |
211 | need to pass PF_CAN as the first argument to the socket(2) system | |
212 | call. Currently, there are two CAN protocols to choose from, the raw | |
213 | socket protocol and the broadcast manager (BCM). So to open a socket, | |
214 | you would write:: | |
215 | ||
216 | s = socket(PF_CAN, SOCK_RAW, CAN_RAW); | |
217 | ||
218 | and:: | |
219 | ||
220 | s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); | |
221 | ||
222 | respectively. After the successful creation of the socket, you would | |
223 | normally use the bind(2) system call to bind the socket to a CAN | |
224 | interface (which is different from TCP/IP due to different addressing | |
225 | - see :ref:`socketcan-concept`). After binding (CAN_RAW) or connecting (CAN_BCM) | |
226 | the socket, you can read(2) and write(2) from/to the socket or use | |
227 | send(2), sendto(2), sendmsg(2) and the recv* counterpart operations | |
228 | on the socket as usual. There are also CAN specific socket options | |
229 | described below. | |
230 | ||
75191707 OH |
231 | The Classical CAN frame structure (aka CAN 2.0B), the CAN FD frame structure |
232 | and the sockaddr structure are defined in include/linux/can.h: | |
7d597739 RS |
233 | |
234 | .. code-block:: C | |
235 | ||
236 | struct can_frame { | |
237 | canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ | |
75191707 OH |
238 | union { |
239 | /* CAN frame payload length in byte (0 .. CAN_MAX_DLEN) | |
240 | * was previously named can_dlc so we need to carry that | |
241 | * name for legacy support | |
242 | */ | |
243 | __u8 len; | |
244 | __u8 can_dlc; /* deprecated */ | |
245 | }; | |
7d597739 RS |
246 | __u8 __pad; /* padding */ |
247 | __u8 __res0; /* reserved / padding */ | |
75191707 | 248 | __u8 len8_dlc; /* optional DLC for 8 byte payload length (9 .. 15) */ |
7d597739 RS |
249 | __u8 data[8] __attribute__((aligned(8))); |
250 | }; | |
251 | ||
75191707 OH |
252 | Remark: The len element contains the payload length in bytes and should be |
253 | used instead of can_dlc. The deprecated can_dlc was misleadingly named as | |
254 | it always contained the plain payload length in bytes and not the so called | |
255 | 'data length code' (DLC). | |
256 | ||
257 | To pass the raw DLC from/to a Classical CAN network device the len8_dlc | |
258 | element can contain values 9 .. 15 when the len element is 8 (the real | |
259 | payload length for all DLC values greater or equal to 8). | |
260 | ||
7d597739 RS |
261 | The alignment of the (linear) payload data[] to a 64bit boundary |
262 | allows the user to define their own structs and unions to easily access | |
263 | the CAN payload. There is no given byteorder on the CAN bus by | |
264 | default. A read(2) system call on a CAN_RAW socket transfers a | |
265 | struct can_frame to the user space. | |
266 | ||
267 | The sockaddr_can structure has an interface index like the | |
268 | PF_PACKET socket, that also binds to a specific interface: | |
269 | ||
270 | .. code-block:: C | |
271 | ||
272 | struct sockaddr_can { | |
273 | sa_family_t can_family; | |
274 | int can_ifindex; | |
275 | union { | |
276 | /* transport protocol class address info (e.g. ISOTP) */ | |
277 | struct { canid_t rx_id, tx_id; } tp; | |
278 | ||
75191707 OH |
279 | /* J1939 address information */ |
280 | struct { | |
281 | /* 8 byte name when using dynamic addressing */ | |
282 | __u64 name; | |
283 | ||
284 | /* pgn: | |
285 | * 8 bit: PS in PDU2 case, else 0 | |
286 | * 8 bit: PF | |
287 | * 1 bit: DP | |
288 | * 1 bit: reserved | |
289 | */ | |
290 | __u32 pgn; | |
291 | ||
292 | /* 1 byte address */ | |
293 | __u8 addr; | |
294 | } j1939; | |
295 | ||
7d597739 RS |
296 | /* reserved for future CAN protocols address information */ |
297 | } can_addr; | |
298 | }; | |
299 | ||
300 | To determine the interface index an appropriate ioctl() has to | |
301 | be used (example for CAN_RAW sockets without error checking): | |
302 | ||
303 | .. code-block:: C | |
304 | ||
305 | int s; | |
306 | struct sockaddr_can addr; | |
307 | struct ifreq ifr; | |
308 | ||
309 | s = socket(PF_CAN, SOCK_RAW, CAN_RAW); | |
310 | ||
311 | strcpy(ifr.ifr_name, "can0" ); | |
312 | ioctl(s, SIOCGIFINDEX, &ifr); | |
313 | ||
314 | addr.can_family = AF_CAN; | |
315 | addr.can_ifindex = ifr.ifr_ifindex; | |
316 | ||
317 | bind(s, (struct sockaddr *)&addr, sizeof(addr)); | |
318 | ||
319 | (..) | |
320 | ||
321 | To bind a socket to all(!) CAN interfaces the interface index must | |
322 | be 0 (zero). In this case the socket receives CAN frames from every | |
323 | enabled CAN interface. To determine the originating CAN interface | |
324 | the system call recvfrom(2) may be used instead of read(2). To send | |
325 | on a socket that is bound to 'any' interface sendto(2) is needed to | |
326 | specify the outgoing interface. | |
327 | ||
328 | Reading CAN frames from a bound CAN_RAW socket (see above) consists | |
329 | of reading a struct can_frame: | |
330 | ||
331 | .. code-block:: C | |
332 | ||
333 | struct can_frame frame; | |
334 | ||
335 | nbytes = read(s, &frame, sizeof(struct can_frame)); | |
336 | ||
337 | if (nbytes < 0) { | |
338 | perror("can raw socket read"); | |
339 | return 1; | |
340 | } | |
341 | ||
342 | /* paranoid check ... */ | |
343 | if (nbytes < sizeof(struct can_frame)) { | |
344 | fprintf(stderr, "read: incomplete CAN frame\n"); | |
345 | return 1; | |
346 | } | |
347 | ||
348 | /* do something with the received CAN frame */ | |
349 | ||
350 | Writing CAN frames can be done similarly, with the write(2) system call:: | |
351 | ||
352 | nbytes = write(s, &frame, sizeof(struct can_frame)); | |
353 | ||
354 | When the CAN interface is bound to 'any' existing CAN interface | |
355 | (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the | |
356 | information about the originating CAN interface is needed: | |
357 | ||
358 | .. code-block:: C | |
359 | ||
360 | struct sockaddr_can addr; | |
361 | struct ifreq ifr; | |
362 | socklen_t len = sizeof(addr); | |
363 | struct can_frame frame; | |
364 | ||
365 | nbytes = recvfrom(s, &frame, sizeof(struct can_frame), | |
366 | 0, (struct sockaddr*)&addr, &len); | |
367 | ||
368 | /* get interface name of the received CAN frame */ | |
369 | ifr.ifr_ifindex = addr.can_ifindex; | |
370 | ioctl(s, SIOCGIFNAME, &ifr); | |
371 | printf("Received a CAN frame from interface %s", ifr.ifr_name); | |
372 | ||
373 | To write CAN frames on sockets bound to 'any' CAN interface the | |
374 | outgoing interface has to be defined certainly: | |
375 | ||
376 | .. code-block:: C | |
377 | ||
378 | strcpy(ifr.ifr_name, "can0"); | |
379 | ioctl(s, SIOCGIFINDEX, &ifr); | |
380 | addr.can_ifindex = ifr.ifr_ifindex; | |
381 | addr.can_family = AF_CAN; | |
382 | ||
383 | nbytes = sendto(s, &frame, sizeof(struct can_frame), | |
384 | 0, (struct sockaddr*)&addr, sizeof(addr)); | |
385 | ||
386 | An accurate timestamp can be obtained with an ioctl(2) call after reading | |
387 | a message from the socket: | |
388 | ||
389 | .. code-block:: C | |
390 | ||
391 | struct timeval tv; | |
392 | ioctl(s, SIOCGSTAMP, &tv); | |
393 | ||
394 | The timestamp has a resolution of one microsecond and is set automatically | |
395 | at the reception of a CAN frame. | |
396 | ||
397 | Remark about CAN FD (flexible data rate) support: | |
398 | ||
399 | Generally the handling of CAN FD is very similar to the formerly described | |
400 | examples. The new CAN FD capable CAN controllers support two different | |
401 | bitrates for the arbitration phase and the payload phase of the CAN FD frame | |
402 | and up to 64 bytes of payload. This extended payload length breaks all the | |
403 | kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight | |
404 | bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g. | |
405 | the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that | |
406 | switches the socket into a mode that allows the handling of CAN FD frames | |
75191707 | 407 | and Classical CAN frames simultaneously (see :ref:`socketcan-rawfd`). |
7d597739 RS |
408 | |
409 | The struct canfd_frame is defined in include/linux/can.h: | |
410 | ||
411 | .. code-block:: C | |
412 | ||
413 | struct canfd_frame { | |
414 | canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ | |
415 | __u8 len; /* frame payload length in byte (0 .. 64) */ | |
416 | __u8 flags; /* additional flags for CAN FD */ | |
417 | __u8 __res0; /* reserved / padding */ | |
418 | __u8 __res1; /* reserved / padding */ | |
419 | __u8 data[64] __attribute__((aligned(8))); | |
420 | }; | |
421 | ||
422 | The struct canfd_frame and the existing struct can_frame have the can_id, | |
423 | the payload length and the payload data at the same offset inside their | |
424 | structures. This allows to handle the different structures very similar. | |
425 | When the content of a struct can_frame is copied into a struct canfd_frame | |
426 | all structure elements can be used as-is - only the data[] becomes extended. | |
427 | ||
428 | When introducing the struct canfd_frame it turned out that the data length | |
429 | code (DLC) of the struct can_frame was used as a length information as the | |
430 | length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve | |
431 | the easy handling of the length information the canfd_frame.len element | |
432 | contains a plain length value from 0 .. 64. So both canfd_frame.len and | |
75191707 | 433 | can_frame.len are equal and contain a length information and no DLC. |
7d597739 RS |
434 | For details about the distinction of CAN and CAN FD capable devices and |
435 | the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`. | |
436 | ||
437 | The length of the two CAN(FD) frame structures define the maximum transfer | |
438 | unit (MTU) of the CAN(FD) network interface and skbuff data length. Two | |
439 | definitions are specified for CAN specific MTUs in include/linux/can.h: | |
440 | ||
441 | .. code-block:: C | |
442 | ||
75191707 | 443 | #define CAN_MTU (sizeof(struct can_frame)) == 16 => Classical CAN frame |
7d597739 RS |
444 | #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame |
445 | ||
446 | ||
447 | .. _socketcan-raw-sockets: | |
448 | ||
449 | RAW Protocol Sockets with can_filters (SOCK_RAW) | |
450 | ------------------------------------------------ | |
451 | ||
452 | Using CAN_RAW sockets is extensively comparable to the commonly | |
453 | known access to CAN character devices. To meet the new possibilities | |
454 | provided by the multi user SocketCAN approach, some reasonable | |
455 | defaults are set at RAW socket binding time: | |
456 | ||
457 | - The filters are set to exactly one filter receiving everything | |
458 | - The socket only receives valid data frames (=> no error message frames) | |
459 | - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`) | |
460 | - The socket does not receive its own sent frames (in loopback mode) | |
461 | ||
462 | These default settings may be changed before or after binding the socket. | |
463 | To use the referenced definitions of the socket options for CAN_RAW | |
464 | sockets, include <linux/can/raw.h>. | |
465 | ||
466 | ||
467 | .. _socketcan-rawfilter: | |
468 | ||
469 | RAW socket option CAN_RAW_FILTER | |
470 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
471 | ||
472 | The reception of CAN frames using CAN_RAW sockets can be controlled | |
473 | by defining 0 .. n filters with the CAN_RAW_FILTER socket option. | |
474 | ||
475 | The CAN filter structure is defined in include/linux/can.h: | |
476 | ||
477 | .. code-block:: C | |
478 | ||
479 | struct can_filter { | |
480 | canid_t can_id; | |
481 | canid_t can_mask; | |
482 | }; | |
483 | ||
484 | A filter matches, when: | |
485 | ||
486 | .. code-block:: C | |
487 | ||
488 | <received_can_id> & mask == can_id & mask | |
489 | ||
490 | which is analogous to known CAN controllers hardware filter semantics. | |
491 | The filter can be inverted in this semantic, when the CAN_INV_FILTER | |
492 | bit is set in can_id element of the can_filter structure. In | |
493 | contrast to CAN controller hardware filters the user may set 0 .. n | |
494 | receive filters for each open socket separately: | |
495 | ||
496 | .. code-block:: C | |
497 | ||
498 | struct can_filter rfilter[2]; | |
499 | ||
500 | rfilter[0].can_id = 0x123; | |
501 | rfilter[0].can_mask = CAN_SFF_MASK; | |
502 | rfilter[1].can_id = 0x200; | |
503 | rfilter[1].can_mask = 0x700; | |
504 | ||
505 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); | |
506 | ||
507 | To disable the reception of CAN frames on the selected CAN_RAW socket: | |
508 | ||
509 | .. code-block:: C | |
510 | ||
511 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); | |
512 | ||
513 | To set the filters to zero filters is quite obsolete as to not read | |
514 | data causes the raw socket to discard the received CAN frames. But | |
515 | having this 'send only' use-case we may remove the receive list in the | |
516 | Kernel to save a little (really a very little!) CPU usage. | |
517 | ||
518 | CAN Filter Usage Optimisation | |
519 | ............................. | |
520 | ||
521 | The CAN filters are processed in per-device filter lists at CAN frame | |
522 | reception time. To reduce the number of checks that need to be performed | |
523 | while walking through the filter lists the CAN core provides an optimized | |
524 | filter handling when the filter subscription focusses on a single CAN ID. | |
525 | ||
526 | For the possible 2048 SFF CAN identifiers the identifier is used as an index | |
527 | to access the corresponding subscription list without any further checks. | |
528 | For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as | |
529 | hash function to retrieve the EFF table index. | |
530 | ||
531 | To benefit from the optimized filters for single CAN identifiers the | |
532 | CAN_SFF_MASK or CAN_EFF_MASK have to be set into can_filter.mask together | |
533 | with set CAN_EFF_FLAG and CAN_RTR_FLAG bits. A set CAN_EFF_FLAG bit in the | |
534 | can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is | |
535 | subscribed. E.g. in the example from above: | |
536 | ||
537 | .. code-block:: C | |
538 | ||
539 | rfilter[0].can_id = 0x123; | |
540 | rfilter[0].can_mask = CAN_SFF_MASK; | |
541 | ||
542 | both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass. | |
543 | ||
544 | To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the | |
545 | filter has to be defined in this way to benefit from the optimized filters: | |
546 | ||
547 | .. code-block:: C | |
548 | ||
549 | struct can_filter rfilter[2]; | |
550 | ||
551 | rfilter[0].can_id = 0x123; | |
552 | rfilter[0].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_SFF_MASK); | |
553 | rfilter[1].can_id = 0x12345678 | CAN_EFF_FLAG; | |
554 | rfilter[1].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_EFF_MASK); | |
555 | ||
556 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); | |
557 | ||
558 | ||
559 | RAW Socket Option CAN_RAW_ERR_FILTER | |
560 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
561 | ||
562 | As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generate so | |
563 | called Error Message Frames that can optionally be passed to the user | |
564 | application in the same way as other CAN frames. The possible | |
565 | errors are divided into different error classes that may be filtered | |
566 | using the appropriate error mask. To register for every possible | |
567 | error condition CAN_ERR_MASK can be used as value for the error mask. | |
568 | The values for the error mask are defined in linux/can/error.h: | |
569 | ||
570 | .. code-block:: C | |
571 | ||
572 | can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF ); | |
573 | ||
574 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, | |
575 | &err_mask, sizeof(err_mask)); | |
576 | ||
577 | ||
578 | RAW Socket Option CAN_RAW_LOOPBACK | |
579 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
580 | ||
581 | To meet multi user needs the local loopback is enabled by default | |
582 | (see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases | |
583 | (e.g. when only one application uses the CAN bus) this loopback | |
584 | functionality can be disabled (separately for each socket): | |
585 | ||
586 | .. code-block:: C | |
587 | ||
588 | int loopback = 0; /* 0 = disabled, 1 = enabled (default) */ | |
589 | ||
590 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback)); | |
591 | ||
592 | ||
593 | RAW socket option CAN_RAW_RECV_OWN_MSGS | |
594 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
595 | ||
596 | When the local loopback is enabled, all the sent CAN frames are | |
597 | looped back to the open CAN sockets that registered for the CAN | |
598 | frames' CAN-ID on this given interface to meet the multi user | |
599 | needs. The reception of the CAN frames on the same socket that was | |
600 | sending the CAN frame is assumed to be unwanted and therefore | |
601 | disabled by default. This default behaviour may be changed on | |
602 | demand: | |
603 | ||
604 | .. code-block:: C | |
605 | ||
606 | int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */ | |
607 | ||
608 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, | |
609 | &recv_own_msgs, sizeof(recv_own_msgs)); | |
610 | ||
924e464f EF |
611 | Note that reception of a socket's own CAN frames are subject to the same |
612 | filtering as other CAN frames (see :ref:`socketcan-rawfilter`). | |
7d597739 RS |
613 | |
614 | .. _socketcan-rawfd: | |
615 | ||
616 | RAW Socket Option CAN_RAW_FD_FRAMES | |
617 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
618 | ||
619 | CAN FD support in CAN_RAW sockets can be enabled with a new socket option | |
620 | CAN_RAW_FD_FRAMES which is off by default. When the new socket option is | |
621 | not supported by the CAN_RAW socket (e.g. on older kernels), switching the | |
622 | CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT. | |
623 | ||
624 | Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames | |
625 | and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames | |
626 | when reading from the socket: | |
627 | ||
628 | .. code-block:: C | |
629 | ||
630 | CAN_RAW_FD_FRAMES enabled: CAN_MTU and CANFD_MTU are allowed | |
631 | CAN_RAW_FD_FRAMES disabled: only CAN_MTU is allowed (default) | |
632 | ||
633 | Example: | |
634 | ||
635 | .. code-block:: C | |
636 | ||
637 | [ remember: CANFD_MTU == sizeof(struct canfd_frame) ] | |
638 | ||
639 | struct canfd_frame cfd; | |
640 | ||
641 | nbytes = read(s, &cfd, CANFD_MTU); | |
642 | ||
643 | if (nbytes == CANFD_MTU) { | |
644 | printf("got CAN FD frame with length %d\n", cfd.len); | |
645 | /* cfd.flags contains valid data */ | |
646 | } else if (nbytes == CAN_MTU) { | |
75191707 | 647 | printf("got Classical CAN frame with length %d\n", cfd.len); |
7d597739 RS |
648 | /* cfd.flags is undefined */ |
649 | } else { | |
650 | fprintf(stderr, "read: invalid CAN(FD) frame\n"); | |
651 | return 1; | |
652 | } | |
653 | ||
654 | /* the content can be handled independently from the received MTU size */ | |
655 | ||
656 | printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len); | |
657 | for (i = 0; i < cfd.len; i++) | |
658 | printf("%02X ", cfd.data[i]); | |
659 | ||
660 | When reading with size CANFD_MTU only returns CAN_MTU bytes that have | |
75191707 | 661 | been received from the socket a Classical CAN frame has been read into the |
7d597739 RS |
662 | provided CAN FD structure. Note that the canfd_frame.flags data field is |
663 | not specified in the struct can_frame and therefore it is only valid in | |
664 | CANFD_MTU sized CAN FD frames. | |
665 | ||
666 | Implementation hint for new CAN applications: | |
667 | ||
668 | To build a CAN FD aware application use struct canfd_frame as basic CAN | |
669 | data structure for CAN_RAW based applications. When the application is | |
670 | executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES | |
75191707 | 671 | socket option returns an error: No problem. You'll get Classical CAN frames |
7d597739 RS |
672 | or CAN FD frames and can process them the same way. |
673 | ||
674 | When sending to CAN devices make sure that the device is capable to handle | |
675 | CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU. | |
676 | The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. | |
677 | ||
678 | ||
679 | RAW socket option CAN_RAW_JOIN_FILTERS | |
680 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
681 | ||
682 | The CAN_RAW socket can set multiple CAN identifier specific filters that | |
683 | lead to multiple filters in the af_can.c filter processing. These filters | |
684 | are indenpendent from each other which leads to logical OR'ed filters when | |
685 | applied (see :ref:`socketcan-rawfilter`). | |
686 | ||
687 | This socket option joines the given CAN filters in the way that only CAN | |
688 | frames are passed to user space that matched *all* given CAN filters. The | |
689 | semantic for the applied filters is therefore changed to a logical AND. | |
690 | ||
691 | This is useful especially when the filterset is a combination of filters | |
692 | where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or | |
693 | CAN ID ranges from the incoming traffic. | |
694 | ||
695 | ||
696 | RAW Socket Returned Message Flags | |
697 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
698 | ||
699 | When using recvmsg() call, the msg->msg_flags may contain following flags: | |
700 | ||
701 | MSG_DONTROUTE: | |
702 | set when the received frame was created on the local host. | |
703 | ||
704 | MSG_CONFIRM: | |
705 | set when the frame was sent via the socket it is received on. | |
706 | This flag can be interpreted as a 'transmission confirmation' when the | |
707 | CAN driver supports the echo of frames on driver level, see | |
708 | :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`. | |
709 | In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set. | |
710 | ||
711 | ||
712 | Broadcast Manager Protocol Sockets (SOCK_DGRAM) | |
713 | ----------------------------------------------- | |
714 | ||
715 | The Broadcast Manager protocol provides a command based configuration | |
716 | interface to filter and send (e.g. cyclic) CAN messages in kernel space. | |
717 | ||
718 | Receive filters can be used to down sample frequent messages; detect events | |
719 | such as message contents changes, packet length changes, and do time-out | |
720 | monitoring of received messages. | |
721 | ||
722 | Periodic transmission tasks of CAN frames or a sequence of CAN frames can be | |
723 | created and modified at runtime; both the message content and the two | |
724 | possible transmit intervals can be altered. | |
725 | ||
726 | A BCM socket is not intended for sending individual CAN frames using the | |
727 | struct can_frame as known from the CAN_RAW socket. Instead a special BCM | |
728 | configuration message is defined. The basic BCM configuration message used | |
729 | to communicate with the broadcast manager and the available operations are | |
730 | defined in the linux/can/bcm.h include. The BCM message consists of a | |
731 | message header with a command ('opcode') followed by zero or more CAN frames. | |
732 | The broadcast manager sends responses to user space in the same form: | |
733 | ||
734 | .. code-block:: C | |
735 | ||
736 | struct bcm_msg_head { | |
737 | __u32 opcode; /* command */ | |
738 | __u32 flags; /* special flags */ | |
739 | __u32 count; /* run 'count' times with ival1 */ | |
740 | struct timeval ival1, ival2; /* count and subsequent interval */ | |
741 | canid_t can_id; /* unique can_id for task */ | |
742 | __u32 nframes; /* number of can_frames following */ | |
743 | struct can_frame frames[0]; | |
744 | }; | |
745 | ||
746 | The aligned payload 'frames' uses the same basic CAN frame structure defined | |
747 | at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All | |
748 | messages to the broadcast manager from user space have this structure. | |
749 | ||
750 | Note a CAN_BCM socket must be connected instead of bound after socket | |
751 | creation (example without error checking): | |
752 | ||
753 | .. code-block:: C | |
754 | ||
755 | int s; | |
756 | struct sockaddr_can addr; | |
757 | struct ifreq ifr; | |
758 | ||
759 | s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); | |
760 | ||
761 | strcpy(ifr.ifr_name, "can0"); | |
762 | ioctl(s, SIOCGIFINDEX, &ifr); | |
763 | ||
764 | addr.can_family = AF_CAN; | |
765 | addr.can_ifindex = ifr.ifr_ifindex; | |
766 | ||
767 | connect(s, (struct sockaddr *)&addr, sizeof(addr)); | |
768 | ||
769 | (..) | |
770 | ||
771 | The broadcast manager socket is able to handle any number of in flight | |
772 | transmissions or receive filters concurrently. The different RX/TX jobs are | |
773 | distinguished by the unique can_id in each BCM message. However additional | |
774 | CAN_BCM sockets are recommended to communicate on multiple CAN interfaces. | |
775 | When the broadcast manager socket is bound to 'any' CAN interface (=> the | |
776 | interface index is set to zero) the configured receive filters apply to any | |
777 | CAN interface unless the sendto() syscall is used to overrule the 'any' CAN | |
778 | interface index. When using recvfrom() instead of read() to retrieve BCM | |
779 | socket messages the originating CAN interface is provided in can_ifindex. | |
780 | ||
781 | ||
782 | Broadcast Manager Operations | |
783 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
784 | ||
785 | The opcode defines the operation for the broadcast manager to carry out, | |
786 | or details the broadcast managers response to several events, including | |
787 | user requests. | |
788 | ||
789 | Transmit Operations (user space to broadcast manager): | |
790 | ||
791 | TX_SETUP: | |
792 | Create (cyclic) transmission task. | |
793 | ||
794 | TX_DELETE: | |
795 | Remove (cyclic) transmission task, requires only can_id. | |
796 | ||
797 | TX_READ: | |
798 | Read properties of (cyclic) transmission task for can_id. | |
799 | ||
800 | TX_SEND: | |
801 | Send one CAN frame. | |
802 | ||
803 | Transmit Responses (broadcast manager to user space): | |
804 | ||
805 | TX_STATUS: | |
806 | Reply to TX_READ request (transmission task configuration). | |
807 | ||
808 | TX_EXPIRED: | |
809 | Notification when counter finishes sending at initial interval | |
810 | 'ival1'. Requires the TX_COUNTEVT flag to be set at TX_SETUP. | |
811 | ||
812 | Receive Operations (user space to broadcast manager): | |
813 | ||
814 | RX_SETUP: | |
815 | Create RX content filter subscription. | |
816 | ||
817 | RX_DELETE: | |
818 | Remove RX content filter subscription, requires only can_id. | |
819 | ||
820 | RX_READ: | |
821 | Read properties of RX content filter subscription for can_id. | |
822 | ||
823 | Receive Responses (broadcast manager to user space): | |
824 | ||
825 | RX_STATUS: | |
826 | Reply to RX_READ request (filter task configuration). | |
827 | ||
828 | RX_TIMEOUT: | |
829 | Cyclic message is detected to be absent (timer ival1 expired). | |
830 | ||
831 | RX_CHANGED: | |
832 | BCM message with updated CAN frame (detected content change). | |
833 | Sent on first message received or on receipt of revised CAN messages. | |
834 | ||
835 | ||
836 | Broadcast Manager Message Flags | |
837 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
838 | ||
839 | When sending a message to the broadcast manager the 'flags' element may | |
840 | contain the following flag definitions which influence the behaviour: | |
841 | ||
842 | SETTIMER: | |
843 | Set the values of ival1, ival2 and count | |
844 | ||
845 | STARTTIMER: | |
846 | Start the timer with the actual values of ival1, ival2 | |
847 | and count. Starting the timer leads simultaneously to emit a CAN frame. | |
848 | ||
849 | TX_COUNTEVT: | |
850 | Create the message TX_EXPIRED when count expires | |
851 | ||
852 | TX_ANNOUNCE: | |
853 | A change of data by the process is emitted immediately. | |
854 | ||
855 | TX_CP_CAN_ID: | |
856 | Copies the can_id from the message header to each | |
857 | subsequent frame in frames. This is intended as usage simplification. For | |
858 | TX tasks the unique can_id from the message header may differ from the | |
859 | can_id(s) stored for transmission in the subsequent struct can_frame(s). | |
860 | ||
861 | RX_FILTER_ID: | |
862 | Filter by can_id alone, no frames required (nframes=0). | |
863 | ||
864 | RX_CHECK_DLC: | |
865 | A change of the DLC leads to an RX_CHANGED. | |
866 | ||
867 | RX_NO_AUTOTIMER: | |
868 | Prevent automatically starting the timeout monitor. | |
869 | ||
870 | RX_ANNOUNCE_RESUME: | |
871 | If passed at RX_SETUP and a receive timeout occurred, a | |
872 | RX_CHANGED message will be generated when the (cyclic) receive restarts. | |
873 | ||
874 | TX_RESET_MULTI_IDX: | |
875 | Reset the index for the multiple frame transmission. | |
876 | ||
877 | RX_RTR_FRAME: | |
878 | Send reply for RTR-request (placed in op->frames[0]). | |
879 | ||
75191707 OH |
880 | CAN_FD_FRAME: |
881 | The CAN frames following the bcm_msg_head are struct canfd_frame's | |
7d597739 RS |
882 | |
883 | Broadcast Manager Transmission Timers | |
884 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
885 | ||
886 | Periodic transmission configurations may use up to two interval timers. | |
887 | In this case the BCM sends a number of messages ('count') at an interval | |
888 | 'ival1', then continuing to send at another given interval 'ival2'. When | |
889 | only one timer is needed 'count' is set to zero and only 'ival2' is used. | |
890 | When SET_TIMER and START_TIMER flag were set the timers are activated. | |
891 | The timer values can be altered at runtime when only SET_TIMER is set. | |
892 | ||
893 | ||
894 | Broadcast Manager message sequence transmission | |
895 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
896 | ||
897 | Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic | |
898 | TX task configuration. The number of CAN frames is provided in the 'nframes' | |
899 | element of the BCM message head. The defined number of CAN frames are added | |
900 | as array to the TX_SETUP BCM configuration message: | |
901 | ||
902 | .. code-block:: C | |
903 | ||
904 | /* create a struct to set up a sequence of four CAN frames */ | |
905 | struct { | |
906 | struct bcm_msg_head msg_head; | |
907 | struct can_frame frame[4]; | |
908 | } mytxmsg; | |
909 | ||
910 | (..) | |
911 | mytxmsg.msg_head.nframes = 4; | |
912 | (..) | |
913 | ||
914 | write(s, &mytxmsg, sizeof(mytxmsg)); | |
915 | ||
916 | With every transmission the index in the array of CAN frames is increased | |
917 | and set to zero at index overflow. | |
918 | ||
919 | ||
920 | Broadcast Manager Receive Filter Timers | |
921 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
922 | ||
923 | The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP. | |
924 | When the SET_TIMER flag is set the timers are enabled: | |
925 | ||
926 | ival1: | |
927 | Send RX_TIMEOUT when a received message is not received again within | |
928 | the given time. When START_TIMER is set at RX_SETUP the timeout detection | |
929 | is activated directly - even without a former CAN frame reception. | |
930 | ||
931 | ival2: | |
932 | Throttle the received message rate down to the value of ival2. This | |
933 | is useful to reduce messages for the application when the signal inside the | |
a266ef69 | 934 | CAN frame is stateless as state changes within the ival2 period may get |
7d597739 RS |
935 | lost. |
936 | ||
937 | Broadcast Manager Multiplex Message Receive Filter | |
938 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
939 | ||
940 | To filter for content changes in multiplex message sequences an array of more | |
941 | than one CAN frames can be passed in a RX_SETUP configuration message. The | |
942 | data bytes of the first CAN frame contain the mask of relevant bits that | |
943 | have to match in the subsequent CAN frames with the received CAN frame. | |
944 | If one of the subsequent CAN frames is matching the bits in that frame data | |
945 | mark the relevant content to be compared with the previous received content. | |
946 | Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN | |
947 | filters) can be added as array to the TX_SETUP BCM configuration message: | |
948 | ||
949 | .. code-block:: C | |
950 | ||
951 | /* usually used to clear CAN frame data[] - beware of endian problems! */ | |
952 | #define U64_DATA(p) (*(unsigned long long*)(p)->data) | |
953 | ||
954 | struct { | |
955 | struct bcm_msg_head msg_head; | |
956 | struct can_frame frame[5]; | |
957 | } msg; | |
958 | ||
959 | msg.msg_head.opcode = RX_SETUP; | |
960 | msg.msg_head.can_id = 0x42; | |
961 | msg.msg_head.flags = 0; | |
962 | msg.msg_head.nframes = 5; | |
963 | U64_DATA(&msg.frame[0]) = 0xFF00000000000000ULL; /* MUX mask */ | |
964 | U64_DATA(&msg.frame[1]) = 0x01000000000000FFULL; /* data mask (MUX 0x01) */ | |
965 | U64_DATA(&msg.frame[2]) = 0x0200FFFF000000FFULL; /* data mask (MUX 0x02) */ | |
966 | U64_DATA(&msg.frame[3]) = 0x330000FFFFFF0003ULL; /* data mask (MUX 0x33) */ | |
967 | U64_DATA(&msg.frame[4]) = 0x4F07FC0FF0000000ULL; /* data mask (MUX 0x4F) */ | |
968 | ||
969 | write(s, &msg, sizeof(msg)); | |
970 | ||
971 | ||
972 | Broadcast Manager CAN FD Support | |
973 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
974 | ||
975 | The programming API of the CAN_BCM depends on struct can_frame which is | |
976 | given as array directly behind the bcm_msg_head structure. To follow this | |
977 | schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head | |
978 | flags indicates that the concatenated CAN frame structures behind the | |
979 | bcm_msg_head are defined as struct canfd_frame: | |
980 | ||
981 | .. code-block:: C | |
982 | ||
983 | struct { | |
984 | struct bcm_msg_head msg_head; | |
985 | struct canfd_frame frame[5]; | |
986 | } msg; | |
987 | ||
988 | msg.msg_head.opcode = RX_SETUP; | |
989 | msg.msg_head.can_id = 0x42; | |
990 | msg.msg_head.flags = CAN_FD_FRAME; | |
991 | msg.msg_head.nframes = 5; | |
992 | (..) | |
993 | ||
994 | When using CAN FD frames for multiplex filtering the MUX mask is still | |
995 | expected in the first 64 bit of the struct canfd_frame data section. | |
996 | ||
997 | ||
998 | Connected Transport Protocols (SOCK_SEQPACKET) | |
999 | ---------------------------------------------- | |
1000 | ||
1001 | (to be written) | |
1002 | ||
1003 | ||
1004 | Unconnected Transport Protocols (SOCK_DGRAM) | |
1005 | -------------------------------------------- | |
1006 | ||
1007 | (to be written) | |
1008 | ||
1009 | ||
1010 | .. _socketcan-core-module: | |
1011 | ||
1012 | SocketCAN Core Module | |
1013 | ===================== | |
1014 | ||
1015 | The SocketCAN core module implements the protocol family | |
1016 | PF_CAN. CAN protocol modules are loaded by the core module at | |
1017 | runtime. The core module provides an interface for CAN protocol | |
1018 | modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`). | |
1019 | ||
1020 | ||
1021 | can.ko Module Params | |
1022 | -------------------- | |
1023 | ||
1024 | - **stats_timer**: | |
1025 | To calculate the SocketCAN core statistics | |
1026 | (e.g. current/maximum frames per second) this 1 second timer is | |
1027 | invoked at can.ko module start time by default. This timer can be | |
1028 | disabled by using stattimer=0 on the module commandline. | |
1029 | ||
1030 | - **debug**: | |
1031 | (removed since SocketCAN SVN r546) | |
1032 | ||
1033 | ||
1034 | procfs content | |
1035 | -------------- | |
1036 | ||
1037 | As described in :ref:`socketcan-receive-lists` the SocketCAN core uses several filter | |
1038 | lists to deliver received CAN frames to CAN protocol modules. These | |
1039 | receive lists, their filters and the count of filter matches can be | |
1040 | checked in the appropriate receive list. All entries contain the | |
1041 | device and a protocol module identifier:: | |
1042 | ||
1043 | foo@bar:~$ cat /proc/net/can/rcvlist_all | |
1044 | ||
1045 | receive list 'rx_all': | |
1046 | (vcan3: no entry) | |
1047 | (vcan2: no entry) | |
1048 | (vcan1: no entry) | |
1049 | device can_id can_mask function userdata matches ident | |
1050 | vcan0 000 00000000 f88e6370 f6c6f400 0 raw | |
1051 | (any: no entry) | |
1052 | ||
1053 | In this example an application requests any CAN traffic from vcan0:: | |
1054 | ||
1055 | rcvlist_all - list for unfiltered entries (no filter operations) | |
1056 | rcvlist_eff - list for single extended frame (EFF) entries | |
1057 | rcvlist_err - list for error message frames masks | |
1058 | rcvlist_fil - list for mask/value filters | |
1059 | rcvlist_inv - list for mask/value filters (inverse semantic) | |
1060 | rcvlist_sff - list for single standard frame (SFF) entries | |
1061 | ||
1062 | Additional procfs files in /proc/net/can:: | |
1063 | ||
1064 | stats - SocketCAN core statistics (rx/tx frames, match ratios, ...) | |
1065 | reset_stats - manual statistic reset | |
75191707 | 1066 | version - prints SocketCAN core and ABI version (removed in Linux 5.10) |
7d597739 RS |
1067 | |
1068 | ||
1069 | Writing Own CAN Protocol Modules | |
1070 | -------------------------------- | |
1071 | ||
1072 | To implement a new protocol in the protocol family PF_CAN a new | |
1073 | protocol has to be defined in include/linux/can.h . | |
1074 | The prototypes and definitions to use the SocketCAN core can be | |
1075 | accessed by including include/linux/can/core.h . | |
1076 | In addition to functions that register the CAN protocol and the | |
1077 | CAN device notifier chain there are functions to subscribe CAN | |
1078 | frames received by CAN interfaces and to send CAN frames:: | |
1079 | ||
1080 | can_rx_register - subscribe CAN frames from a specific interface | |
1081 | can_rx_unregister - unsubscribe CAN frames from a specific interface | |
1082 | can_send - transmit a CAN frame (optional with local loopback) | |
1083 | ||
1084 | For details see the kerneldoc documentation in net/can/af_can.c or | |
1085 | the source code of net/can/raw.c or net/can/bcm.c . | |
1086 | ||
1087 | ||
1088 | CAN Network Drivers | |
1089 | =================== | |
1090 | ||
1091 | Writing a CAN network device driver is much easier than writing a | |
1092 | CAN character device driver. Similar to other known network device | |
1093 | drivers you mainly have to deal with: | |
1094 | ||
1095 | - TX: Put the CAN frame from the socket buffer to the CAN controller. | |
1096 | - RX: Put the CAN frame from the CAN controller to the socket buffer. | |
1097 | ||
482a4360 | 1098 | See e.g. at Documentation/networking/netdevices.rst . The differences |
7d597739 RS |
1099 | for writing CAN network device driver are described below: |
1100 | ||
1101 | ||
1102 | General Settings | |
1103 | ---------------- | |
1104 | ||
1105 | .. code-block:: C | |
1106 | ||
1107 | dev->type = ARPHRD_CAN; /* the netdevice hardware type */ | |
1108 | dev->flags = IFF_NOARP; /* CAN has no arp */ | |
1109 | ||
75191707 | 1110 | dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> Classical CAN interface */ |
7d597739 RS |
1111 | |
1112 | or alternative, when the controller supports CAN with flexible data rate: | |
1113 | dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */ | |
1114 | ||
1115 | The struct can_frame or struct canfd_frame is the payload of each socket | |
1116 | buffer (skbuff) in the protocol family PF_CAN. | |
1117 | ||
1118 | ||
1119 | .. _socketcan-local-loopback2: | |
1120 | ||
1121 | Local Loopback of Sent Frames | |
1122 | ----------------------------- | |
1123 | ||
1124 | As described in :ref:`socketcan-local-loopback1` the CAN network device driver should | |
1125 | support a local loopback functionality similar to the local echo | |
1126 | e.g. of tty devices. In this case the driver flag IFF_ECHO has to be | |
1127 | set to prevent the PF_CAN core from locally echoing sent frames | |
1128 | (aka loopback) as fallback solution:: | |
1129 | ||
1130 | dev->flags = (IFF_NOARP | IFF_ECHO); | |
1131 | ||
1132 | ||
1133 | CAN Controller Hardware Filters | |
1134 | ------------------------------- | |
1135 | ||
1136 | To reduce the interrupt load on deep embedded systems some CAN | |
1137 | controllers support the filtering of CAN IDs or ranges of CAN IDs. | |
1138 | These hardware filter capabilities vary from controller to | |
1139 | controller and have to be identified as not feasible in a multi-user | |
1140 | networking approach. The use of the very controller specific | |
1141 | hardware filters could make sense in a very dedicated use-case, as a | |
1142 | filter on driver level would affect all users in the multi-user | |
1143 | system. The high efficient filter sets inside the PF_CAN core allow | |
1144 | to set different multiple filters for each socket separately. | |
1145 | Therefore the use of hardware filters goes to the category 'handmade | |
1146 | tuning on deep embedded systems'. The author is running a MPC603e | |
1147 | @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus | |
1148 | load without any problems ... | |
1149 | ||
1150 | ||
85700ac1 DT |
1151 | Switchable Termination Resistors |
1152 | -------------------------------- | |
1153 | ||
1154 | CAN bus requires a specific impedance across the differential pair, | |
1155 | typically provided by two 120Ohm resistors on the farthest nodes of | |
1156 | the bus. Some CAN controllers support activating / deactivating a | |
1157 | termination resistor(s) to provide the correct impedance. | |
1158 | ||
1159 | Query the available resistances:: | |
1160 | ||
1161 | $ ip -details link show can0 | |
1162 | ... | |
1163 | termination 120 [ 0, 120 ] | |
1164 | ||
1165 | Activate the terminating resistor:: | |
1166 | ||
1167 | $ ip link set dev can0 type can termination 120 | |
1168 | ||
1169 | Deactivate the terminating resistor:: | |
1170 | ||
1171 | $ ip link set dev can0 type can termination 0 | |
1172 | ||
1173 | To enable termination resistor support to a can-controller, either | |
1174 | implement in the controller's struct can-priv:: | |
1175 | ||
1176 | termination_const | |
1177 | termination_const_cnt | |
1178 | do_set_termination | |
1179 | ||
1180 | or add gpio control with the device tree entries from | |
1181 | Documentation/devicetree/bindings/net/can/can-controller.yaml | |
1182 | ||
1183 | ||
7d597739 RS |
1184 | The Virtual CAN Driver (vcan) |
1185 | ----------------------------- | |
1186 | ||
1187 | Similar to the network loopback devices, vcan offers a virtual local | |
1188 | CAN interface. A full qualified address on CAN consists of | |
1189 | ||
1190 | - a unique CAN Identifier (CAN ID) | |
1191 | - the CAN bus this CAN ID is transmitted on (e.g. can0) | |
1192 | ||
1193 | so in common use cases more than one virtual CAN interface is needed. | |
1194 | ||
1195 | The virtual CAN interfaces allow the transmission and reception of CAN | |
1196 | frames without real CAN controller hardware. Virtual CAN network | |
1197 | devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ... | |
1198 | When compiled as a module the virtual CAN driver module is called vcan.ko | |
1199 | ||
1200 | Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel | |
1201 | netlink interface to create vcan network devices. The creation and | |
1202 | removal of vcan network devices can be managed with the ip(8) tool:: | |
1203 | ||
1204 | - Create a virtual CAN network interface: | |
1205 | $ ip link add type vcan | |
1206 | ||
1207 | - Create a virtual CAN network interface with a specific name 'vcan42': | |
1208 | $ ip link add dev vcan42 type vcan | |
1209 | ||
1210 | - Remove a (virtual CAN) network interface 'vcan42': | |
1211 | $ ip link del vcan42 | |
1212 | ||
1213 | ||
1214 | The CAN Network Device Driver Interface | |
1215 | --------------------------------------- | |
1216 | ||
1217 | The CAN network device driver interface provides a generic interface | |
1218 | to setup, configure and monitor CAN network devices. The user can then | |
1219 | configure the CAN device, like setting the bit-timing parameters, via | |
1220 | the netlink interface using the program "ip" from the "IPROUTE2" | |
1221 | utility suite. The following chapter describes briefly how to use it. | |
1222 | Furthermore, the interface uses a common data structure and exports a | |
1223 | set of common functions, which all real CAN network device drivers | |
1224 | should use. Please have a look to the SJA1000 or MSCAN driver to | |
1225 | understand how to use them. The name of the module is can-dev.ko. | |
1226 | ||
1227 | ||
1228 | Netlink interface to set/get devices properties | |
1229 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1230 | ||
1231 | The CAN device must be configured via netlink interface. The supported | |
1232 | netlink message types are defined and briefly described in | |
1233 | "include/linux/can/netlink.h". CAN link support for the program "ip" | |
1234 | of the IPROUTE2 utility suite is available and it can be used as shown | |
1235 | below: | |
1236 | ||
1237 | Setting CAN device properties:: | |
1238 | ||
1239 | $ ip link set can0 type can help | |
1240 | Usage: ip link set DEVICE type can | |
1241 | [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] | | |
1242 | [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1 | |
1243 | phase-seg2 PHASE-SEG2 [ sjw SJW ] ] | |
1244 | ||
1245 | [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] | | |
1246 | [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1 | |
1247 | dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ] | |
1248 | ||
1249 | [ loopback { on | off } ] | |
1250 | [ listen-only { on | off } ] | |
1251 | [ triple-sampling { on | off } ] | |
1252 | [ one-shot { on | off } ] | |
1253 | [ berr-reporting { on | off } ] | |
1254 | [ fd { on | off } ] | |
1255 | [ fd-non-iso { on | off } ] | |
1256 | [ presume-ack { on | off } ] | |
75191707 | 1257 | [ cc-len8-dlc { on | off } ] |
7d597739 RS |
1258 | |
1259 | [ restart-ms TIME-MS ] | |
1260 | [ restart ] | |
1261 | ||
1262 | Where: BITRATE := { 1..1000000 } | |
1263 | SAMPLE-POINT := { 0.000..0.999 } | |
1264 | TQ := { NUMBER } | |
1265 | PROP-SEG := { 1..8 } | |
1266 | PHASE-SEG1 := { 1..8 } | |
1267 | PHASE-SEG2 := { 1..8 } | |
1268 | SJW := { 1..4 } | |
1269 | RESTART-MS := { 0 | NUMBER } | |
1270 | ||
1271 | Display CAN device details and statistics:: | |
1272 | ||
1273 | $ ip -details -statistics link show can0 | |
1274 | 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10 | |
1275 | link/can | |
1276 | can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100 | |
1277 | bitrate 125000 sample_point 0.875 | |
1278 | tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 | |
1279 | sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 | |
1280 | clock 8000000 | |
1281 | re-started bus-errors arbit-lost error-warn error-pass bus-off | |
1282 | 41 17457 0 41 42 41 | |
1283 | RX: bytes packets errors dropped overrun mcast | |
1284 | 140859 17608 17457 0 0 0 | |
1285 | TX: bytes packets errors dropped carrier collsns | |
1286 | 861 112 0 41 0 0 | |
1287 | ||
1288 | More info to the above output: | |
1289 | ||
1290 | "<TRIPLE-SAMPLING>" | |
1291 | Shows the list of selected CAN controller modes: LOOPBACK, | |
1292 | LISTEN-ONLY, or TRIPLE-SAMPLING. | |
1293 | ||
1294 | "state ERROR-ACTIVE" | |
1295 | The current state of the CAN controller: "ERROR-ACTIVE", | |
1296 | "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED" | |
1297 | ||
1298 | "restart-ms 100" | |
1299 | Automatic restart delay time. If set to a non-zero value, a | |
1300 | restart of the CAN controller will be triggered automatically | |
1301 | in case of a bus-off condition after the specified delay time | |
1302 | in milliseconds. By default it's off. | |
1303 | ||
1304 | "bitrate 125000 sample-point 0.875" | |
1305 | Shows the real bit-rate in bits/sec and the sample-point in the | |
1306 | range 0.000..0.999. If the calculation of bit-timing parameters | |
1307 | is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the | |
1308 | bit-timing can be defined by setting the "bitrate" argument. | |
1309 | Optionally the "sample-point" can be specified. By default it's | |
1310 | 0.000 assuming CIA-recommended sample-points. | |
1311 | ||
1312 | "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1" | |
1313 | Shows the time quanta in ns, propagation segment, phase buffer | |
1314 | segment 1 and 2 and the synchronisation jump width in units of | |
1315 | tq. They allow to define the CAN bit-timing in a hardware | |
1316 | independent format as proposed by the Bosch CAN 2.0 spec (see | |
1317 | chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf). | |
1318 | ||
1319 | "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000" | |
1320 | Shows the bit-timing constants of the CAN controller, here the | |
1321 | "sja1000". The minimum and maximum values of the time segment 1 | |
1322 | and 2, the synchronisation jump width in units of tq, the | |
1323 | bitrate pre-scaler and the CAN system clock frequency in Hz. | |
1324 | These constants could be used for user-defined (non-standard) | |
1325 | bit-timing calculation algorithms in user-space. | |
1326 | ||
1327 | "re-started bus-errors arbit-lost error-warn error-pass bus-off" | |
1328 | Shows the number of restarts, bus and arbitration lost errors, | |
1329 | and the state changes to the error-warning, error-passive and | |
1330 | bus-off state. RX overrun errors are listed in the "overrun" | |
1331 | field of the standard network statistics. | |
1332 | ||
1333 | Setting the CAN Bit-Timing | |
1334 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1335 | ||
1336 | The CAN bit-timing parameters can always be defined in a hardware | |
1337 | independent format as proposed in the Bosch CAN 2.0 specification | |
1338 | specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2" | |
1339 | and "sjw":: | |
1340 | ||
1341 | $ ip link set canX type can tq 125 prop-seg 6 \ | |
1342 | phase-seg1 7 phase-seg2 2 sjw 1 | |
1343 | ||
1344 | If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA | |
1345 | recommended CAN bit-timing parameters will be calculated if the bit- | |
1346 | rate is specified with the argument "bitrate":: | |
1347 | ||
1348 | $ ip link set canX type can bitrate 125000 | |
1349 | ||
1350 | Note that this works fine for the most common CAN controllers with | |
1351 | standard bit-rates but may *fail* for exotic bit-rates or CAN system | |
1352 | clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some | |
1353 | space and allows user-space tools to solely determine and set the | |
1354 | bit-timing parameters. The CAN controller specific bit-timing | |
1355 | constants can be used for that purpose. They are listed by the | |
1356 | following command:: | |
1357 | ||
1358 | $ ip -details link show can0 | |
1359 | ... | |
1360 | sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 | |
1361 | ||
1362 | ||
1363 | Starting and Stopping the CAN Network Device | |
1364 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1365 | ||
1366 | A CAN network device is started or stopped as usual with the command | |
1367 | "ifconfig canX up/down" or "ip link set canX up/down". Be aware that | |
1368 | you *must* define proper bit-timing parameters for real CAN devices | |
1369 | before you can start it to avoid error-prone default settings:: | |
1370 | ||
1371 | $ ip link set canX up type can bitrate 125000 | |
1372 | ||
1373 | A device may enter the "bus-off" state if too many errors occurred on | |
1374 | the CAN bus. Then no more messages are received or sent. An automatic | |
1375 | bus-off recovery can be enabled by setting the "restart-ms" to a | |
1376 | non-zero value, e.g.:: | |
1377 | ||
1378 | $ ip link set canX type can restart-ms 100 | |
1379 | ||
1380 | Alternatively, the application may realize the "bus-off" condition | |
1381 | by monitoring CAN error message frames and do a restart when | |
1382 | appropriate with the command:: | |
1383 | ||
1384 | $ ip link set canX type can restart | |
1385 | ||
1386 | Note that a restart will also create a CAN error message frame (see | |
1387 | also :ref:`socketcan-network-problem-notifications`). | |
1388 | ||
1389 | ||
1390 | .. _socketcan-can-fd-driver: | |
1391 | ||
1392 | CAN FD (Flexible Data Rate) Driver Support | |
1393 | ------------------------------------------ | |
1394 | ||
1395 | CAN FD capable CAN controllers support two different bitrates for the | |
1396 | arbitration phase and the payload phase of the CAN FD frame. Therefore a | |
1397 | second bit timing has to be specified in order to enable the CAN FD bitrate. | |
1398 | ||
1399 | Additionally CAN FD capable CAN controllers support up to 64 bytes of | |
75191707 | 1400 | payload. The representation of this length in can_frame.len and |
7d597739 RS |
1401 | canfd_frame.len for userspace applications and inside the Linux network |
1402 | layer is a plain value from 0 .. 64 instead of the CAN 'data length code'. | |
75191707 | 1403 | The data length code was a 1:1 mapping to the payload length in the Classical |
7d597739 RS |
1404 | CAN frames anyway. The payload length to the bus-relevant DLC mapping is |
1405 | only performed inside the CAN drivers, preferably with the helper | |
3ab4ce0d | 1406 | functions can_fd_dlc2len() and can_fd_len2dlc(). |
7d597739 RS |
1407 | |
1408 | The CAN netdevice driver capabilities can be distinguished by the network | |
1409 | devices maximum transfer unit (MTU):: | |
1410 | ||
75191707 | 1411 | MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => Classical CAN device |
7d597739 RS |
1412 | MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device |
1413 | ||
1414 | The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. | |
75191707 | 1415 | N.B. CAN FD capable devices can also handle and send Classical CAN frames. |
7d597739 RS |
1416 | |
1417 | When configuring CAN FD capable CAN controllers an additional 'data' bitrate | |
1418 | has to be set. This bitrate for the data phase of the CAN FD frame has to be | |
1419 | at least the bitrate which was configured for the arbitration phase. This | |
1420 | second bitrate is specified analogue to the first bitrate but the bitrate | |
1421 | setting keywords for the 'data' bitrate start with 'd' e.g. dbitrate, | |
1422 | dsample-point, dsjw or dtq and similar settings. When a data bitrate is set | |
1423 | within the configuration process the controller option "fd on" can be | |
1424 | specified to enable the CAN FD mode in the CAN controller. This controller | |
1425 | option also switches the device MTU to 72 (CANFD_MTU). | |
1426 | ||
1427 | The first CAN FD specification presented as whitepaper at the International | |
1428 | CAN Conference 2012 needed to be improved for data integrity reasons. | |
1429 | Therefore two CAN FD implementations have to be distinguished today: | |
1430 | ||
1431 | - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default) | |
1432 | - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper | |
1433 | ||
1434 | Finally there are three types of CAN FD controllers: | |
1435 | ||
1436 | 1. ISO compliant (fixed) | |
1437 | 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c) | |
1438 | 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD) | |
1439 | ||
1440 | The current ISO/non-ISO mode is announced by the CAN controller driver via | |
1441 | netlink and displayed by the 'ip' tool (controller option FD-NON-ISO). | |
1442 | The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for | |
1443 | switchable CAN FD controllers only. | |
1444 | ||
1445 | Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate:: | |
1446 | ||
1447 | $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \ | |
1448 | dbitrate 4000000 dsample-point 0.8 fd on | |
1449 | $ ip -details link show can0 | |
1450 | 5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \ | |
1451 | mode DEFAULT group default qlen 10 | |
1452 | link/can promiscuity 0 | |
1453 | can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 | |
1454 | bitrate 500000 sample-point 0.750 | |
1455 | tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1 | |
1456 | pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \ | |
1457 | brp-inc 1 | |
1458 | dbitrate 4000000 dsample-point 0.800 | |
1459 | dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1 | |
1460 | pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \ | |
1461 | dbrp-inc 1 | |
1462 | clock 80000000 | |
1463 | ||
1464 | Example when 'fd-non-iso on' is added on this switchable CAN FD adapter:: | |
1465 | ||
1466 | can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 | |
1467 | ||
1468 | ||
1469 | Supported CAN Hardware | |
1470 | ---------------------- | |
1471 | ||
1472 | Please check the "Kconfig" file in "drivers/net/can" to get an actual | |
1473 | list of the support CAN hardware. On the SocketCAN project website | |
1474 | (see :ref:`socketcan-resources`) there might be further drivers available, also for | |
1475 | older kernel versions. | |
1476 | ||
1477 | ||
1478 | .. _socketcan-resources: | |
1479 | ||
1480 | SocketCAN Resources | |
1481 | =================== | |
1482 | ||
1483 | The Linux CAN / SocketCAN project resources (project site / mailing list) | |
1484 | are referenced in the MAINTAINERS file in the Linux source tree. | |
1485 | Search for CAN NETWORK [LAYERS|DRIVERS]. | |
1486 | ||
1487 | Credits | |
1488 | ======= | |
1489 | ||
1490 | - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver) | |
1491 | - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) | |
1492 | - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) | |
1493 | - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver interface, MSCAN driver) | |
1494 | - Robert Schwebel (design reviews, PTXdist integration) | |
1495 | - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) | |
1496 | - Benedikt Spranger (reviews) | |
1497 | - Thomas Gleixner (LKML reviews, coding style, posting hints) | |
1498 | - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver) | |
1499 | - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) | |
1500 | - Klaus Hitschler (PEAK driver integration) | |
1501 | - Uwe Koppe (CAN netdevices with PF_PACKET approach) | |
1502 | - Michael Schulze (driver layer loopback requirement, RT CAN drivers review) | |
1503 | - Pavel Pisa (Bit-timing calculation) | |
1504 | - Sascha Hauer (SJA1000 platform driver) | |
1505 | - Sebastian Haas (SJA1000 EMS PCI driver) | |
1506 | - Markus Plessing (SJA1000 EMS PCI driver) | |
1507 | - Per Dalen (SJA1000 Kvaser PCI driver) | |
1508 | - Sam Ravnborg (reviews, coding style, kbuild help) |