can: update documentation for DLC usage in Classical CAN

+52 -16

1 changed file

expand all

Documentation

networking

can.rst

+52 -16

Documentation/networking/can.rst

··· 228 228 on the socket as usual. There are also CAN specific socket options 229 229 described below. 230 230 231 - The basic CAN frame structure and the sockaddr structure are defined 232 - in include/linux/can.h: 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: 233 233 234 234 .. code-block:: C 235 235 236 236 struct can_frame { 237 237 canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ 238 - __u8 can_dlc; /* frame payload length in byte (0 .. 8) */ 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 + }; 239 246 __u8 __pad; /* padding */ 240 247 __u8 __res0; /* reserved / padding */ 241 - __u8 __res1; /* reserved / padding */ 248 + __u8 len8_dlc; /* optional DLC for 8 byte payload length (9 .. 15) */ 242 249 __u8 data[8] __attribute__((aligned(8))); 243 250 }; 251 + 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). 244 260 245 261 The alignment of the (linear) payload data[] to a 64bit boundary 246 262 allows the user to define their own structs and unions to easily access ··· 275 259 union { 276 260 /* transport protocol class address info (e.g. ISOTP) */ 277 261 struct { canid_t rx_id, tx_id; } tp; 262 + 263 + /* J1939 address information */ 264 + struct { 265 + /* 8 byte name when using dynamic addressing */ 266 + __u64 name; 267 + 268 + /* pgn: 269 + * 8 bit: PS in PDU2 case, else 0 270 + * 8 bit: PF 271 + * 1 bit: DP 272 + * 1 bit: reserved 273 + */ 274 + __u32 pgn; 275 + 276 + /* 1 byte address */ 277 + __u8 addr; 278 + } j1939; 278 279 279 280 /* reserved for future CAN protocols address information */ 280 281 } can_addr; ··· 404 371 bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g. 405 372 the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that 406 373 switches the socket into a mode that allows the handling of CAN FD frames 407 - and (legacy) CAN frames simultaneously (see :ref:`socketcan-rawfd`). 374 + and Classical CAN frames simultaneously (see :ref:`socketcan-rawfd`). 408 375 409 376 The struct canfd_frame is defined in include/linux/can.h: 410 377 ··· 430 397 length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve 431 398 the easy handling of the length information the canfd_frame.len element 432 399 contains a plain length value from 0 .. 64. So both canfd_frame.len and 433 - can_frame.can_dlc are equal and contain a length information and no DLC. 400 + can_frame.len are equal and contain a length information and no DLC. 434 401 For details about the distinction of CAN and CAN FD capable devices and 435 402 the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`. 436 403 ··· 440 407 441 408 .. code-block:: C 442 409 443 - #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame 410 + #define CAN_MTU (sizeof(struct can_frame)) == 16 => Classical CAN frame 444 411 #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame 445 412 446 413 ··· 642 609 printf("got CAN FD frame with length %d\n", cfd.len); 643 610 /* cfd.flags contains valid data */ 644 611 } else if (nbytes == CAN_MTU) { 645 - printf("got legacy CAN frame with length %d\n", cfd.len); 612 + printf("got Classical CAN frame with length %d\n", cfd.len); 646 613 /* cfd.flags is undefined */ 647 614 } else { 648 615 fprintf(stderr, "read: invalid CAN(FD) frame\n"); ··· 656 623 printf("%02X ", cfd.data[i]); 657 624 658 625 When reading with size CANFD_MTU only returns CAN_MTU bytes that have 659 - been received from the socket a legacy CAN frame has been read into the 626 + been received from the socket a Classical CAN frame has been read into the 660 627 provided CAN FD structure. Note that the canfd_frame.flags data field is 661 628 not specified in the struct can_frame and therefore it is only valid in 662 629 CANFD_MTU sized CAN FD frames. ··· 666 633 To build a CAN FD aware application use struct canfd_frame as basic CAN 667 634 data structure for CAN_RAW based applications. When the application is 668 635 executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES 669 - socket option returns an error: No problem. You'll get legacy CAN frames 636 + socket option returns an error: No problem. You'll get Classical CAN frames 670 637 or CAN FD frames and can process them the same way. 671 638 672 639 When sending to CAN devices make sure that the device is capable to handle ··· 875 842 RX_RTR_FRAME: 876 843 Send reply for RTR-request (placed in op->frames[0]). 877 844 845 + CAN_FD_FRAME: 846 + The CAN frames following the bcm_msg_head are struct canfd_frame's 878 847 879 848 Broadcast Manager Transmission Timers 880 849 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ··· 1061 1026 1062 1027 stats - SocketCAN core statistics (rx/tx frames, match ratios, ...) 1063 1028 reset_stats - manual statistic reset 1064 - version - prints the SocketCAN core version and the ABI version 1029 + version - prints SocketCAN core and ABI version (removed in Linux 5.10) 1065 1030 1066 1031 1067 1032 Writing Own CAN Protocol Modules ··· 1105 1070 dev->type = ARPHRD_CAN; /* the netdevice hardware type */ 1106 1071 dev->flags = IFF_NOARP; /* CAN has no arp */ 1107 1072 1108 - dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */ 1073 + dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> Classical CAN interface */ 1109 1074 1110 1075 or alternative, when the controller supports CAN with flexible data rate: 1111 1076 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */ ··· 1219 1184 [ fd { on | off } ] 1220 1185 [ fd-non-iso { on | off } ] 1221 1186 [ presume-ack { on | off } ] 1187 + [ cc-len8-dlc { on | off } ] 1222 1188 1223 1189 [ restart-ms TIME-MS ] 1224 1190 [ restart ] ··· 1362 1326 second bit timing has to be specified in order to enable the CAN FD bitrate. 1363 1327 1364 1328 Additionally CAN FD capable CAN controllers support up to 64 bytes of 1365 - payload. The representation of this length in can_frame.can_dlc and 1329 + payload. The representation of this length in can_frame.len and 1366 1330 canfd_frame.len for userspace applications and inside the Linux network 1367 1331 layer is a plain value from 0 .. 64 instead of the CAN 'data length code'. 1368 - The data length code was a 1:1 mapping to the payload length in the legacy 1332 + The data length code was a 1:1 mapping to the payload length in the Classical 1369 1333 CAN frames anyway. The payload length to the bus-relevant DLC mapping is 1370 1334 only performed inside the CAN drivers, preferably with the helper 1371 1335 functions can_fd_dlc2len() and can_fd_len2dlc(). ··· 1373 1337 The CAN netdevice driver capabilities can be distinguished by the network 1374 1338 devices maximum transfer unit (MTU):: 1375 1339 1376 - MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => 'legacy' CAN device 1340 + MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => Classical CAN device 1377 1341 MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device 1378 1342 1379 1343 The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. 1380 - N.B. CAN FD capable devices can also handle and send legacy CAN frames. 1344 + N.B. CAN FD capable devices can also handle and send Classical CAN frames. 1381 1345 1382 1346 When configuring CAN FD capable CAN controllers an additional 'data' bitrate 1383 1347 has to be set. This bitrate for the data phase of the CAN FD frame has to be

Configure Feed

Configure Feed