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