Lines Matching full:can
8 The socketcan package is an implementation of CAN protocols
9 (Controller Area Network) for Linux. CAN is a networking technology
11 automotive fields. While there have been other CAN implementations
13 socket API, the Linux network stack and implements the CAN device
14 drivers as network interfaces. The CAN socket API has been designed
16 familiar with network programming, to easily learn how to use CAN
25 There have been CAN implementations for Linux before SocketCAN so the
27 implementations come as a device driver for some CAN hardware, they
31 receive raw CAN frames, directly to/from the controller hardware.
36 the CAN controller requires employment of another device driver and
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
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
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
58 selects that protocol when opening the socket, and then can read and
60 CAN-IDs, frames, etc.
67 socket(2) and using bind(2) to select a CAN interface and CAN ID, an
72 for CAN networking.
75 hardware-specific device driver for a CAN controller directly
88 The easiest way to implement a CAN device driver is as a character
91 layer with all the functionality like registering for certain CAN
93 CAN frames between them, (sophisticated) queueing of CAN frames, and
100 natural and most appropriate way to implement CAN for Linux.
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.
126 CAN-IDs from the same CAN network interface. The SocketCAN core
127 module - which implements the protocol family CAN - provides several
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
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`).
156 -----------------(1)- CAN bus -(2)---------------
160 some kind of local loopback of the sent CAN frames on the appropriate
163 The Linux network devices (by default) just can handle 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
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.
174 networking behaviour for CAN applications. Due to some requests from
176 separate socket. See sockopts from the CAN RAW sockets in :ref:`socketcan-raw-sockets`.
187 The use of the CAN bus may lead to several problems on the physical
189 layer problems is a vital requirement for CAN users to identify
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
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".
210 CAN network. Since SocketCAN implements a new protocol family, you
212 call. Currently, there are two CAN protocols to choose from, the raw
223 normally use the bind(2) system call to bind the socket to a CAN
226 the socket, you can read(2) and write(2) from/to the socket or use
228 on the socket as usual. There are also CAN specific socket options
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:
239 /* CAN frame payload length in byte (0 .. CAN_MAX_DLEN)
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
263 the CAN payload. There is no given byteorder on the CAN bus by
296 /* reserved for future CAN protocols address information */
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
328 Reading CAN frames from a bound CAN_RAW socket (see above) consists
338 perror("can raw socket read");
344 fprintf(stderr, "read: incomplete CAN frame\n");
348 /* do something with the received CAN frame */
350 Writing CAN frames can be done similarly, with the write(2) system call::
354 When the CAN interface is bound to 'any' existing CAN interface
356 information about the originating CAN interface is needed:
368 /* get interface name of the received CAN frame */
371 printf("Received a CAN frame from interface %s", ifr.ifr_name);
373 To write CAN frames on sockets bound to 'any' CAN interface the
386 An accurate timestamp can be obtained with an ioctl(2) call after reading
395 at the reception of a CAN frame.
397 Remark about CAN FD (flexible data rate) support:
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
403 kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight
406 switches the socket into a mode that allows the handling of CAN FD frames
407 and Classical CAN frames simultaneously (see :ref:`socketcan-rawfd`).
409 The struct canfd_frame is defined in include/linux/can.h:
416 __u8 flags; /* additional flags for CAN FD */
426 all structure elements can be used as-is - only the data[] becomes extended.
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`.
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:
443 #define CAN_MTU (sizeof(struct can_frame)) == 16 => Classical CAN frame
444 #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame
453 known access to CAN character devices. To meet the new possibilities
459 - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`)
464 sockets, include <linux/can/raw.h>.
472 The reception of CAN frames using CAN_RAW sockets can be controlled
475 The CAN filter structure is defined in include/linux/can.h:
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
493 contrast to CAN controller hardware filters the user may set 0 .. n
507 To disable the reception of CAN frames on the selected CAN_RAW socket:
514 data causes the raw socket to discard the received CAN frames. But
518 CAN Filter Usage Optimisation
521 The CAN filters are processed in per-device filter lists at CAN frame
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.
526 For the possible 2048 SFF CAN identifiers the identifier is used as an index
528 For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as
531 To benefit from the optimized filters for single CAN identifiers the
534 can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is
542 both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass.
544 To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the
562 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
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
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:
583 (e.g. when only one application uses the CAN bus) this loopback
584 functionality can be disabled (separately for each socket):
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
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`).
619 CAN FD support in CAN_RAW sockets can be enabled with a new socket option
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
644 printf("got CAN FD frame with length %d\n", cfd.len);
647 printf("got Classical CAN frame with length %d\n", cfd.len);
650 fprintf(stderr, "read: invalid CAN(FD) frame\n");
654 /* the content can be handled independently from the received MTU size */
661 been received from the socket a Classical CAN frame has been read into the
662 provided CAN FD structure. Note that the canfd_frame.flags data field is
664 CANFD_MTU sized CAN FD frames.
666 Implementation hint for new CAN applications:
668 To build a CAN FD aware application use struct canfd_frame as basic CAN
671 socket option returns an error: No problem. You'll get Classical CAN frames
672 or CAN FD frames and can process them the same way.
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.
682 The CAN_RAW socket can set multiple CAN identifier specific filters that
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
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.
706 This flag can be interpreted as a 'transmission confirmation' when the
707 CAN driver supports the echo of frames on driver level, see
716 interface to filter and send (e.g. cyclic) CAN messages in kernel space.
718 Receive filters can be used to down sample frequent messages; detect events
722 Periodic transmission tasks of CAN frames or a sequence of CAN frames can be
724 possible transmit intervals can be altered.
726 A BCM socket is not intended for sending individual CAN frames using the
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.
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
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
777 CAN interface unless the sendto() syscall is used to overrule the 'any' CAN
779 socket messages the originating CAN interface is provided in can_ifindex.
801 Send one CAN frame.
832 BCM message with updated CAN frame (detected content change).
833 Sent on first message received or on receipt of revised CAN messages.
847 and count. Starting the timer leads simultaneously to emit a CAN frame.
881 The CAN frames following the bcm_msg_head are struct canfd_frame's
891 The timer values can be altered at runtime when only SET_TIMER is set.
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
904 /* create a struct to set up a sequence of four CAN frames */
916 With every transmission the index in the array of CAN frames is increased
929 is activated directly - even without a former CAN frame reception.
934 CAN frame is stateless as state changes within the ival2 period may get
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
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:
951 /* usually used to clear CAN frame data[] - beware of endian problems! */
972 Broadcast Manager CAN FD Support
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
994 When using CAN FD frames for multiplex filtering the MUX mask is still
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`).
1021 can.ko Module Params
1027 invoked at can.ko module start time by default. This timer can be
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
1043 foo@bar:~$ cat /proc/net/can/rcvlist_all
1053 In this example an application requests any CAN traffic from vcan0::
1062 Additional procfs files in /proc/net/can::
1069 Writing Own CAN Protocol Modules
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::
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)
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 .
1088 CAN Network Drivers
1091 Writing a CAN network device driver is much easier than writing a
1092 CAN character device driver. Similar to other known network device
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.
1099 for writing CAN network device driver are described below:
1108 dev->flags = IFF_NOARP; /* CAN has no arp */
1110 dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> Classical CAN interface */
1112 or alternative, when the controller supports CAN with flexible data rate:
1113 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
1124 As described in :ref:`socketcan-local-loopback1` the CAN network device driver should
1133 CAN Controller Hardware Filters
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.
1147 @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
1154 CAN bus requires a specific impedance across the differential pair,
1156 the bus. Some CAN controllers support activating / deactivating a
1167 $ ip link set dev can0 type can termination 120
1171 $ ip link set dev can0 type can termination 0
1173 To enable termination resistor support to a can-controller, either
1174 implement in the controller's struct can-priv::
1181 Documentation/devicetree/bindings/net/can/can-controller.yaml
1184 The Virtual CAN Driver (vcan)
1188 CAN interface. A full qualified address on CAN consists of
1190 - a unique CAN Identifier (CAN ID)
1191 - the CAN bus this CAN ID is transmitted on (e.g. can0)
1193 so in common use cases more than one virtual CAN interface is needed.
1195 The virtual CAN interfaces allow the transmission and reception of CAN
1196 frames without real CAN controller hardware. Virtual CAN network
1198 When compiled as a module the virtual CAN driver module is called vcan.ko
1202 removal of vcan network devices can be managed with the ip(8) tool::
1204 - Create a virtual CAN network interface:
1207 - Create a virtual CAN network interface with a specific name 'vcan42':
1210 - Remove a (virtual CAN) network interface 'vcan42':
1214 The CAN Network Device Driver Interface
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
1223 set of common functions, which all real CAN network device drivers
1225 understand how to use them. The name of the module is can-dev.ko.
1231 The CAN device must be configured via netlink interface. The supported
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
1237 Setting CAN device properties::
1239 $ ip link set can0 type can help
1240 Usage: ip link set DEVICE type can
1271 Display CAN device details and statistics::
1275 link/can
1276 can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
1291 Shows the list of selected CAN controller modes: LOOPBACK,
1295 The current state of the CAN controller: "ERROR-ACTIVE",
1300 restart of the CAN controller will be triggered automatically
1308 bit-timing can be defined by setting the "bitrate" argument.
1309 Optionally the "sample-point" can be specified. By default it's
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
1320 Shows the bit-timing constants of the CAN controller, here the
1323 bitrate pre-scaler and the CAN system clock frequency in Hz.
1333 Setting the CAN Bit-Timing
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
1341 $ ip link set canX type can tq 125 prop-seg 6 \
1345 recommended CAN bit-timing parameters will be calculated if the bit-
1348 $ ip link set canX type can bitrate 125000
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
1354 bit-timing parameters. The CAN controller specific bit-timing
1355 constants can be used for that purpose. They are listed by the
1363 Starting and Stopping the CAN Network Device
1366 A CAN network device is started or stopped as usual with the command
1368 you *must* define proper bit-timing parameters for real CAN devices
1369 before you can start it to avoid error-prone default settings::
1371 $ ip link set canX up type can bitrate 125000
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
1378 $ ip link set canX type can restart-ms 100
1381 by monitoring CAN error message frames and do a restart when
1384 $ ip link set canX type can restart
1386 Note that a restart will also create a CAN error message frame (see
1390 .. _socketcan-can-fd-driver:
1392 CAN FD (Flexible Data Rate) Driver Support
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.
1399 Additionally CAN FD capable CAN controllers support up to 64 bytes of
1402 layer is a plain value from 0 .. 64 instead of the CAN 'data length code'.
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
1408 The CAN netdevice driver capabilities can be distinguished by the network
1411 MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => Classical CAN device
1412 MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device
1414 The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
1415 N.B. CAN FD capable devices can also handle and send Classical CAN frames.
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
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
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:
1431 - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
1432 - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
1434 Finally there are three types of CAN FD controllers:
1438 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
1440 The current ISO/non-ISO mode is announced by the CAN controller driver via
1442 The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
1443 switchable CAN FD controllers only.
1447 $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
1452 link/can promiscuity 0
1453 can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1464 Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
1466 can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1469 Supported CAN Hardware
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
1483 The Linux CAN / SocketCAN project resources (project site / mailing list)
1485 Search for CAN NETWORK [LAYERS|DRIVERS].
1493 - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver inter…
1499 - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
1501 - Uwe Koppe (CAN netdevices with PF_PACKET approach)
1502 - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)