diff options
Diffstat (limited to 'Documentation/networking/can.txt')
-rw-r--r-- | Documentation/networking/can.txt | 186 |
1 files changed, 162 insertions, 24 deletions
diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index ac295399f0d..820f55344ed 100644 --- a/Documentation/networking/can.txt +++ b/Documentation/networking/can.txt | |||
@@ -22,7 +22,8 @@ This file contains | |||
22 | 4.1.2 RAW socket option CAN_RAW_ERR_FILTER | 22 | 4.1.2 RAW socket option CAN_RAW_ERR_FILTER |
23 | 4.1.3 RAW socket option CAN_RAW_LOOPBACK | 23 | 4.1.3 RAW socket option CAN_RAW_LOOPBACK |
24 | 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS | 24 | 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS |
25 | 4.1.5 RAW socket returned message flags | 25 | 4.1.5 RAW socket option CAN_RAW_FD_FRAMES |
26 | 4.1.6 RAW socket returned message flags | ||
26 | 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) | 27 | 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) |
27 | 4.3 connected transport protocols (SOCK_SEQPACKET) | 28 | 4.3 connected transport protocols (SOCK_SEQPACKET) |
28 | 4.4 unconnected transport protocols (SOCK_DGRAM) | 29 | 4.4 unconnected transport protocols (SOCK_DGRAM) |
@@ -41,7 +42,8 @@ This file contains | |||
41 | 6.5.1 Netlink interface to set/get devices properties | 42 | 6.5.1 Netlink interface to set/get devices properties |
42 | 6.5.2 Setting the CAN bit-timing | 43 | 6.5.2 Setting the CAN bit-timing |
43 | 6.5.3 Starting and stopping the CAN network device | 44 | 6.5.3 Starting and stopping the CAN network device |
44 | 6.6 supported CAN hardware | 45 | 6.6 CAN FD (flexible data rate) driver support |
46 | 6.7 supported CAN hardware | ||
45 | 47 | ||
46 | 7 Socket CAN resources | 48 | 7 Socket CAN resources |
47 | 49 | ||
@@ -232,16 +234,16 @@ solution for a couple of reasons: | |||
232 | arbitration problems and error frames caused by the different | 234 | arbitration problems and error frames caused by the different |
233 | ECUs. The occurrence of detected errors are important for diagnosis | 235 | ECUs. The occurrence of detected errors are important for diagnosis |
234 | and have to be logged together with the exact timestamp. For this | 236 | and have to be logged together with the exact timestamp. For this |
235 | reason the CAN interface driver can generate so called Error Frames | 237 | reason the CAN interface driver can generate so called Error Message |
236 | that can optionally be passed to the user application in the same | 238 | Frames that can optionally be passed to the user application in the |
237 | way as other CAN frames. Whenever an error on the physical layer | 239 | same way as other CAN frames. Whenever an error on the physical layer |
238 | or the MAC layer is detected (e.g. by the CAN controller) the driver | 240 | or the MAC layer is detected (e.g. by the CAN controller) the driver |
239 | creates an appropriate error frame. Error frames can be requested by | 241 | creates an appropriate error message frame. Error messages frames can |
240 | the user application using the common CAN filter mechanisms. Inside | 242 | be requested by the user application using the common CAN filter |
241 | this filter definition the (interested) type of errors may be | 243 | mechanisms. Inside this filter definition the (interested) type of |
242 | selected. The reception of error frames is disabled by default. | 244 | errors may be selected. The reception of error messages is disabled |
243 | The format of the CAN error frame is briefly described in the Linux | 245 | by default. The format of the CAN error message frame is briefly |
244 | header file "include/linux/can/error.h". | 246 | described in the Linux header file "include/linux/can/error.h". |
245 | 247 | ||
246 | 4. How to use Socket CAN | 248 | 4. How to use Socket CAN |
247 | ------------------------ | 249 | ------------------------ |
@@ -273,7 +275,7 @@ solution for a couple of reasons: | |||
273 | 275 | ||
274 | struct can_frame { | 276 | struct can_frame { |
275 | canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ | 277 | canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ |
276 | __u8 can_dlc; /* data length code: 0 .. 8 */ | 278 | __u8 can_dlc; /* frame payload length in byte (0 .. 8) */ |
277 | __u8 data[8] __attribute__((aligned(8))); | 279 | __u8 data[8] __attribute__((aligned(8))); |
278 | }; | 280 | }; |
279 | 281 | ||
@@ -375,6 +377,51 @@ solution for a couple of reasons: | |||
375 | nbytes = sendto(s, &frame, sizeof(struct can_frame), | 377 | nbytes = sendto(s, &frame, sizeof(struct can_frame), |
376 | 0, (struct sockaddr*)&addr, sizeof(addr)); | 378 | 0, (struct sockaddr*)&addr, sizeof(addr)); |
377 | 379 | ||
380 | Remark about CAN FD (flexible data rate) support: | ||
381 | |||
382 | Generally the handling of CAN FD is very similar to the formerly described | ||
383 | examples. The new CAN FD capable CAN controllers support two different | ||
384 | bitrates for the arbitration phase and the payload phase of the CAN FD frame | ||
385 | and up to 64 bytes of payload. This extended payload length breaks all the | ||
386 | kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight | ||
387 | bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g. | ||
388 | the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that | ||
389 | switches the socket into a mode that allows the handling of CAN FD frames | ||
390 | and (legacy) CAN frames simultaneously (see section 4.1.5). | ||
391 | |||
392 | The struct canfd_frame is defined in include/linux/can.h: | ||
393 | |||
394 | struct canfd_frame { | ||
395 | canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ | ||
396 | __u8 len; /* frame payload length in byte (0 .. 64) */ | ||
397 | __u8 flags; /* additional flags for CAN FD */ | ||
398 | __u8 __res0; /* reserved / padding */ | ||
399 | __u8 __res1; /* reserved / padding */ | ||
400 | __u8 data[64] __attribute__((aligned(8))); | ||
401 | }; | ||
402 | |||
403 | The struct canfd_frame and the existing struct can_frame have the can_id, | ||
404 | the payload length and the payload data at the same offset inside their | ||
405 | structures. This allows to handle the different structures very similar. | ||
406 | When the content of a struct can_frame is copied into a struct canfd_frame | ||
407 | all structure elements can be used as-is - only the data[] becomes extended. | ||
408 | |||
409 | When introducing the struct canfd_frame it turned out that the data length | ||
410 | code (DLC) of the struct can_frame was used as a length information as the | ||
411 | length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve | ||
412 | the easy handling of the length information the canfd_frame.len element | ||
413 | contains a plain length value from 0 .. 64. So both canfd_frame.len and | ||
414 | can_frame.can_dlc are equal and contain a length information and no DLC. | ||
415 | For details about the distinction of CAN and CAN FD capable devices and | ||
416 | the mapping to the bus-relevant data length code (DLC), see chapter 6.6. | ||
417 | |||
418 | The length of the two CAN(FD) frame structures define the maximum transfer | ||
419 | unit (MTU) of the CAN(FD) network interface and skbuff data length. Two | ||
420 | definitions are specified for CAN specific MTUs in include/linux/can.h : | ||
421 | |||
422 | #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame | ||
423 | #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame | ||
424 | |||
378 | 4.1 RAW protocol sockets with can_filters (SOCK_RAW) | 425 | 4.1 RAW protocol sockets with can_filters (SOCK_RAW) |
379 | 426 | ||
380 | Using CAN_RAW sockets is extensively comparable to the commonly | 427 | Using CAN_RAW sockets is extensively comparable to the commonly |
@@ -383,7 +430,7 @@ solution for a couple of reasons: | |||
383 | defaults are set at RAW socket binding time: | 430 | defaults are set at RAW socket binding time: |
384 | 431 | ||
385 | - The filters are set to exactly one filter receiving everything | 432 | - The filters are set to exactly one filter receiving everything |
386 | - The socket only receives valid data frames (=> no error frames) | 433 | - The socket only receives valid data frames (=> no error message frames) |
387 | - The loopback of sent CAN frames is enabled (see chapter 3.2) | 434 | - The loopback of sent CAN frames is enabled (see chapter 3.2) |
388 | - The socket does not receive its own sent frames (in loopback mode) | 435 | - The socket does not receive its own sent frames (in loopback mode) |
389 | 436 | ||
@@ -434,7 +481,7 @@ solution for a couple of reasons: | |||
434 | 4.1.2 RAW socket option CAN_RAW_ERR_FILTER | 481 | 4.1.2 RAW socket option CAN_RAW_ERR_FILTER |
435 | 482 | ||
436 | As described in chapter 3.4 the CAN interface driver can generate so | 483 | As described in chapter 3.4 the CAN interface driver can generate so |
437 | called Error Frames that can optionally be passed to the user | 484 | called Error Message Frames that can optionally be passed to the user |
438 | application in the same way as other CAN frames. The possible | 485 | application in the same way as other CAN frames. The possible |
439 | errors are divided into different error classes that may be filtered | 486 | errors are divided into different error classes that may be filtered |
440 | using the appropriate error mask. To register for every possible | 487 | using the appropriate error mask. To register for every possible |
@@ -472,7 +519,69 @@ solution for a couple of reasons: | |||
472 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, | 519 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, |
473 | &recv_own_msgs, sizeof(recv_own_msgs)); | 520 | &recv_own_msgs, sizeof(recv_own_msgs)); |
474 | 521 | ||
475 | 4.1.5 RAW socket returned message flags | 522 | 4.1.5 RAW socket option CAN_RAW_FD_FRAMES |
523 | |||
524 | CAN FD support in CAN_RAW sockets can be enabled with a new socket option | ||
525 | CAN_RAW_FD_FRAMES which is off by default. When the new socket option is | ||
526 | not supported by the CAN_RAW socket (e.g. on older kernels), switching the | ||
527 | CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT. | ||
528 | |||
529 | Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames | ||
530 | and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames | ||
531 | when reading from the socket. | ||
532 | |||
533 | CAN_RAW_FD_FRAMES enabled: CAN_MTU and CANFD_MTU are allowed | ||
534 | CAN_RAW_FD_FRAMES disabled: only CAN_MTU is allowed (default) | ||
535 | |||
536 | Example: | ||
537 | [ remember: CANFD_MTU == sizeof(struct canfd_frame) ] | ||
538 | |||
539 | struct canfd_frame cfd; | ||
540 | |||
541 | nbytes = read(s, &cfd, CANFD_MTU); | ||
542 | |||
543 | if (nbytes == CANFD_MTU) { | ||
544 | printf("got CAN FD frame with length %d\n", cfd.len); | ||
545 | /* cfd.flags contains valid data */ | ||
546 | } else if (nbytes == CAN_MTU) { | ||
547 | printf("got legacy CAN frame with length %d\n", cfd.len); | ||
548 | /* cfd.flags is undefined */ | ||
549 | } else { | ||
550 | fprintf(stderr, "read: invalid CAN(FD) frame\n"); | ||
551 | return 1; | ||
552 | } | ||
553 | |||
554 | /* the content can be handled independently from the received MTU size */ | ||
555 | |||
556 | printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len); | ||
557 | for (i = 0; i < cfd.len; i++) | ||
558 | printf("%02X ", cfd.data[i]); | ||
559 | |||
560 | When reading with size CANFD_MTU only returns CAN_MTU bytes that have | ||
561 | been received from the socket a legacy CAN frame has been read into the | ||
562 | provided CAN FD structure. Note that the canfd_frame.flags data field is | ||
563 | not specified in the struct can_frame and therefore it is only valid in | ||
564 | CANFD_MTU sized CAN FD frames. | ||
565 | |||
566 | As long as the payload length is <=8 the received CAN frames from CAN FD | ||
567 | capable CAN devices can be received and read by legacy sockets too. When | ||
568 | user-generated CAN FD frames have a payload length <=8 these can be send | ||
569 | by legacy CAN network interfaces too. Sending CAN FD frames with payload | ||
570 | length > 8 to a legacy CAN network interface returns an -EMSGSIZE error. | ||
571 | |||
572 | Implementation hint for new CAN applications: | ||
573 | |||
574 | To build a CAN FD aware application use struct canfd_frame as basic CAN | ||
575 | data structure for CAN_RAW based applications. When the application is | ||
576 | executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES | ||
577 | socket option returns an error: No problem. You'll get legacy CAN frames | ||
578 | or CAN FD frames and can process them the same way. | ||
579 | |||
580 | When sending to CAN devices make sure that the device is capable to handle | ||
581 | CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU. | ||
582 | The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. | ||
583 | |||
584 | 4.1.6 RAW socket returned message flags | ||
476 | 585 | ||
477 | When using recvmsg() call, the msg->msg_flags may contain following flags: | 586 | When using recvmsg() call, the msg->msg_flags may contain following flags: |
478 | 587 | ||
@@ -527,7 +636,7 @@ solution for a couple of reasons: | |||
527 | 636 | ||
528 | rcvlist_all - list for unfiltered entries (no filter operations) | 637 | rcvlist_all - list for unfiltered entries (no filter operations) |
529 | rcvlist_eff - list for single extended frame (EFF) entries | 638 | rcvlist_eff - list for single extended frame (EFF) entries |
530 | rcvlist_err - list for error frames masks | 639 | rcvlist_err - list for error message frames masks |
531 | rcvlist_fil - list for mask/value filters | 640 | rcvlist_fil - list for mask/value filters |
532 | rcvlist_inv - list for mask/value filters (inverse semantic) | 641 | rcvlist_inv - list for mask/value filters (inverse semantic) |
533 | rcvlist_sff - list for single standard frame (SFF) entries | 642 | rcvlist_sff - list for single standard frame (SFF) entries |
@@ -573,10 +682,13 @@ solution for a couple of reasons: | |||
573 | dev->type = ARPHRD_CAN; /* the netdevice hardware type */ | 682 | dev->type = ARPHRD_CAN; /* the netdevice hardware type */ |
574 | dev->flags = IFF_NOARP; /* CAN has no arp */ | 683 | dev->flags = IFF_NOARP; /* CAN has no arp */ |
575 | 684 | ||
576 | dev->mtu = sizeof(struct can_frame); | 685 | dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */ |
577 | 686 | ||
578 | The struct can_frame is the payload of each socket buffer in the | 687 | or alternative, when the controller supports CAN with flexible data rate: |
579 | protocol family PF_CAN. | 688 | dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */ |
689 | |||
690 | The struct can_frame or struct canfd_frame is the payload of each socket | ||
691 | buffer (skbuff) in the protocol family PF_CAN. | ||
580 | 692 | ||
581 | 6.2 local loopback of sent frames | 693 | 6.2 local loopback of sent frames |
582 | 694 | ||
@@ -784,15 +896,41 @@ solution for a couple of reasons: | |||
784 | $ ip link set canX type can restart-ms 100 | 896 | $ ip link set canX type can restart-ms 100 |
785 | 897 | ||
786 | Alternatively, the application may realize the "bus-off" condition | 898 | Alternatively, the application may realize the "bus-off" condition |
787 | by monitoring CAN error frames and do a restart when appropriate with | 899 | by monitoring CAN error message frames and do a restart when |
788 | the command: | 900 | appropriate with the command: |
789 | 901 | ||
790 | $ ip link set canX type can restart | 902 | $ ip link set canX type can restart |
791 | 903 | ||
792 | Note that a restart will also create a CAN error frame (see also | 904 | Note that a restart will also create a CAN error message frame (see |
793 | chapter 3.4). | 905 | also chapter 3.4). |
906 | |||
907 | 6.6 CAN FD (flexible data rate) driver support | ||
908 | |||
909 | CAN FD capable CAN controllers support two different bitrates for the | ||
910 | arbitration phase and the payload phase of the CAN FD frame. Therefore a | ||
911 | second bittiming has to be specified in order to enable the CAN FD bitrate. | ||
912 | |||
913 | Additionally CAN FD capable CAN controllers support up to 64 bytes of | ||
914 | payload. The representation of this length in can_frame.can_dlc and | ||
915 | canfd_frame.len for userspace applications and inside the Linux network | ||
916 | layer is a plain value from 0 .. 64 instead of the CAN 'data length code'. | ||
917 | The data length code was a 1:1 mapping to the payload length in the legacy | ||
918 | CAN frames anyway. The payload length to the bus-relevant DLC mapping is | ||
919 | only performed inside the CAN drivers, preferably with the helper | ||
920 | functions can_dlc2len() and can_len2dlc(). | ||
921 | |||
922 | The CAN netdevice driver capabilities can be distinguished by the network | ||
923 | devices maximum transfer unit (MTU): | ||
924 | |||
925 | MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => 'legacy' CAN device | ||
926 | MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device | ||
927 | |||
928 | The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. | ||
929 | N.B. CAN FD capable devices can also handle and send legacy CAN frames. | ||
930 | |||
931 | FIXME: Add details about the CAN FD controller configuration when available. | ||
794 | 932 | ||
795 | 6.6 Supported CAN hardware | 933 | 6.7 Supported CAN hardware |
796 | 934 | ||
797 | Please check the "Kconfig" file in "drivers/net/can" to get an actual | 935 | Please check the "Kconfig" file in "drivers/net/can" to get an actual |
798 | list of the support CAN hardware. On the Socket CAN project website | 936 | list of the support CAN hardware. On the Socket CAN project website |