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 basic CAN frame structure and the sockaddr structure are defined
232 in include/linux/can.h:
247 the CAN payload. There is no given byteorder on the CAN bus by
263 /* reserved for future CAN protocols address information */
288 To bind a socket to all(!) CAN interfaces the interface index must
289 be 0 (zero). In this case the socket receives CAN frames from every
290 enabled CAN interface. To determine the originating CAN interface
295 Reading CAN frames from a bound CAN_RAW socket (see above) consists
305 perror("can raw socket read");
311 fprintf(stderr, "read: incomplete CAN frame\n");
315 /* do something with the received CAN frame */
317 Writing CAN frames can be done similarly, with the write(2) system call::
321 When the CAN interface is bound to 'any' existing CAN interface
323 information about the originating CAN interface is needed:
335 /* get interface name of the received CAN frame */
338 printf("Received a CAN frame from interface %s", ifr.ifr_name);
340 To write CAN frames on sockets bound to 'any' CAN interface the
353 An accurate timestamp can be obtained with an ioctl(2) call after reading
362 at the reception of a CAN frame.
364 Remark about CAN FD (flexible data rate) support:
366 Generally the handling of CAN FD is very similar to the formerly described
367 examples. The new CAN FD capable CAN controllers support two different
368 bitrates for the arbitration phase and the payload phase of the CAN FD frame
370 kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight
373 switches the socket into a mode that allows the handling of CAN FD frames
374 and (legacy) CAN frames simultaneously (see :ref:`socketcan-rawfd`).
376 The struct canfd_frame is defined in include/linux/can.h:
383 __u8 flags; /* additional flags for CAN FD */
393 all structure elements can be used as-is - only the data[] becomes extended.
401 For details about the distinction of CAN and CAN FD capable devices and
402 the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`.
404 The length of the two CAN(FD) frame structures define the maximum transfer
405 unit (MTU) of the CAN(FD) network interface and skbuff data length. Two
406 definitions are specified for CAN specific MTUs in include/linux/can.h:
410 #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame
411 #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame
420 known access to CAN character devices. To meet the new possibilities
426 - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`)
431 sockets, include <linux/can/raw.h>.
439 The reception of CAN frames using CAN_RAW sockets can be controlled
442 The CAN filter structure is defined in include/linux/can.h:
457 which is analogous to known CAN controllers hardware filter semantics.
458 The filter can be inverted in this semantic, when the CAN_INV_FILTER
460 contrast to CAN controller hardware filters the user may set 0 .. n
474 To disable the reception of CAN frames on the selected CAN_RAW socket:
481 data causes the raw socket to discard the received CAN frames. But
485 CAN Filter Usage Optimisation
488 The CAN filters are processed in per-device filter lists at CAN frame
490 while walking through the filter lists the CAN core provides an optimized
491 filter handling when the filter subscription focusses on a single CAN ID.
493 For the possible 2048 SFF CAN identifiers the identifier is used as an index
495 For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as
498 To benefit from the optimized filters for single CAN identifiers the
501 can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is
509 both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass.
511 To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the
529 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
530 called Error Message Frames that can optionally be passed to the user
531 application in the same way as other CAN frames. The possible
534 error condition CAN_ERR_MASK can be used as value for the error mask.
535 The values for the error mask are defined in linux/can/error.h:
550 (e.g. when only one application uses the CAN bus) this loopback
551 functionality can be disabled (separately for each socket):
563 When the local loopback is enabled, all the sent CAN frames are
564 looped back to the open CAN sockets that registered for the CAN
565 frames' CAN-ID on this given interface to meet the multi user
566 needs. The reception of the CAN frames on the same socket that was
567 sending the CAN frame is assumed to be unwanted and therefore
584 CAN FD support in CAN_RAW sockets can be enabled with a new socket option
589 Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames
590 and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames
609 printf("got CAN FD frame with length %d\n", cfd.len);
612 printf("got legacy CAN frame with length %d\n", cfd.len);
615 fprintf(stderr, "read: invalid CAN(FD) frame\n");
619 /* the content can be handled independently from the received MTU size */
626 been received from the socket a legacy CAN frame has been read into the
627 provided CAN FD structure. Note that the canfd_frame.flags data field is
629 CANFD_MTU sized CAN FD frames.
631 Implementation hint for new CAN applications:
633 To build a CAN FD aware application use struct canfd_frame as basic CAN
636 socket option returns an error: No problem. You'll get legacy CAN frames
637 or CAN FD frames and can process them the same way.
639 When sending to CAN devices make sure that the device is capable to handle
640 CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU.
641 The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
647 The CAN_RAW socket can set multiple CAN identifier specific filters that
652 This socket option joines the given CAN filters in the way that only CAN
653 frames are passed to user space that matched *all* given CAN filters. The
657 where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or
658 CAN ID ranges from the incoming traffic.
671 This flag can be interpreted as a 'transmission confirmation' when the
672 CAN driver supports the echo of frames on driver level, see
681 interface to filter and send (e.g. cyclic) CAN messages in kernel space.
683 Receive filters can be used to down sample frequent messages; detect events
687 Periodic transmission tasks of CAN frames or a sequence of CAN frames can be
689 possible transmit intervals can be altered.
691 A BCM socket is not intended for sending individual CAN frames using the
695 defined in the linux/can/bcm.h include. The BCM message consists of a
696 message header with a command ('opcode') followed by zero or more CAN frames.
711 The aligned payload 'frames' uses the same basic CAN frame structure defined
712 at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
739 CAN_BCM sockets are recommended to communicate on multiple CAN interfaces.
740 When the broadcast manager socket is bound to 'any' CAN interface (=> the
742 CAN interface unless the sendto() syscall is used to overrule the 'any' CAN
744 socket messages the originating CAN interface is provided in can_ifindex.
766 Send one CAN frame.
797 BCM message with updated CAN frame (detected content change).
798 Sent on first message received or on receipt of revised CAN messages.
812 and count. Starting the timer leads simultaneously to emit a CAN frame.
854 The timer values can be altered at runtime when only SET_TIMER is set.
860 Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic
861 TX task configuration. The number of CAN frames is provided in the 'nframes'
862 element of the BCM message head. The defined number of CAN frames are added
867 /* create a struct to set up a sequence of four CAN frames */
879 With every transmission the index in the array of CAN frames is increased
892 is activated directly - even without a former CAN frame reception.
897 CAN frame is stateless as state changes within the ival2 periode may get
904 than one CAN frames can be passed in a RX_SETUP configuration message. The
905 data bytes of the first CAN frame contain the mask of relevant bits that
906 have to match in the subsequent CAN frames with the received CAN frame.
907 If one of the subsequent CAN frames is matching the bits in that frame data
909 Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN
910 filters) can be added as array to the TX_SETUP BCM configuration message:
914 /* usually used to clear CAN frame data[] - beware of endian problems! */
935 Broadcast Manager CAN FD Support
940 schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head
941 flags indicates that the concatenated CAN frame structures behind the
957 When using CAN FD frames for multiplex filtering the MUX mask is still
979 PF_CAN. CAN protocol modules are loaded by the core module at
980 runtime. The core module provides an interface for CAN protocol
981 modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`).
984 can.ko Module Params
990 invoked at can.ko module start time by default. This timer can be
1001 lists to deliver received CAN frames to CAN protocol modules. These
1002 receive lists, their filters and the count of filter matches can be
1006 foo@bar:~$ cat /proc/net/can/rcvlist_all
1016 In this example an application requests any CAN traffic from vcan0::
1025 Additional procfs files in /proc/net/can::
1032 Writing Own CAN Protocol Modules
1036 protocol has to be defined in include/linux/can.h .
1037 The prototypes and definitions to use the SocketCAN core can be
1038 accessed by including include/linux/can/core.h .
1039 In addition to functions that register the CAN protocol and the
1040 CAN device notifier chain there are functions to subscribe CAN
1041 frames received by CAN interfaces and to send CAN frames::
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)
1047 For details see the kerneldoc documentation in net/can/af_can.c or
1048 the source code of net/can/raw.c or net/can/bcm.c .
1051 CAN Network Drivers
1054 Writing a CAN network device driver is much easier than writing a
1055 CAN character device driver. Similar to other known network device
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.
1062 for writing CAN network device driver are described below:
1071 dev->flags = IFF_NOARP; /* CAN has no arp */
1073 dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */
1075 or alternative, when the controller supports CAN with flexible data rate:
1076 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
1087 As described in :ref:`socketcan-local-loopback1` the CAN network device driver should
1096 CAN Controller Hardware Filters
1099 To reduce the interrupt load on deep embedded systems some CAN
1100 controllers support the filtering of CAN IDs or ranges of CAN IDs.
1110 @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
1114 The Virtual CAN Driver (vcan)
1118 CAN interface. A full qualified address on CAN consists of
1120 - a unique CAN Identifier (CAN ID)
1121 - the CAN bus this CAN ID is transmitted on (e.g. can0)
1123 so in common use cases more than one virtual CAN interface is needed.
1125 The virtual CAN interfaces allow the transmission and reception of CAN
1126 frames without real CAN controller hardware. Virtual CAN network
1128 When compiled as a module the virtual CAN driver module is called vcan.ko
1132 removal of vcan network devices can be managed with the ip(8) tool::
1134 - Create a virtual CAN network interface:
1137 - Create a virtual CAN network interface with a specific name 'vcan42':
1140 - Remove a (virtual CAN) network interface 'vcan42':
1144 The CAN Network Device Driver Interface
1147 The CAN network device driver interface provides a generic interface
1148 to setup, configure and monitor CAN network devices. The user can then
1149 configure the CAN device, like setting the bit-timing parameters, via
1153 set of common functions, which all real CAN network device drivers
1155 understand how to use them. The name of the module is can-dev.ko.
1161 The CAN device must be configured via netlink interface. The supported
1163 "include/linux/can/netlink.h". CAN link support for the program "ip"
1164 of the IPROUTE2 utility suite is available and it can be used as shown
1167 Setting CAN device properties::
1169 $ ip link set can0 type can help
1170 Usage: ip link set DEVICE type can
1200 Display CAN device details and statistics::
1204 link/can
1205 can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
1220 Shows the list of selected CAN controller modes: LOOPBACK,
1224 The current state of the CAN controller: "ERROR-ACTIVE",
1229 restart of the CAN controller will be triggered automatically
1237 bit-timing can be defined by setting the "bitrate" argument.
1238 Optionally the "sample-point" can be specified. By default it's
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
1249 Shows the bit-timing constants of the CAN controller, here the
1252 bitrate pre-scaler and the CAN system clock frequency in Hz.
1262 Setting the CAN Bit-Timing
1265 The CAN bit-timing parameters can always be defined in a hardware
1266 independent format as proposed in the Bosch CAN 2.0 specification
1270 $ ip link set canX type can tq 125 prop-seg 6 \
1274 recommended CAN bit-timing parameters will be calculated if the bit-
1277 $ ip link set canX type can bitrate 125000
1279 Note that this works fine for the most common CAN controllers with
1280 standard bit-rates but may *fail* for exotic bit-rates or CAN system
1283 bit-timing parameters. The CAN controller specific bit-timing
1284 constants can be used for that purpose. They are listed by the
1292 Starting and Stopping the CAN Network Device
1295 A CAN network device is started or stopped as usual with the command
1297 you *must* define proper bit-timing parameters for real CAN devices
1298 before you can start it to avoid error-prone default settings::
1300 $ ip link set canX up type can bitrate 125000
1303 the CAN bus. Then no more messages are received or sent. An automatic
1304 bus-off recovery can be enabled by setting the "restart-ms" to a
1307 $ ip link set canX type can restart-ms 100
1310 by monitoring CAN error message frames and do a restart when
1313 $ ip link set canX type can restart
1315 Note that a restart will also create a CAN error message frame (see
1319 .. _socketcan-can-fd-driver:
1321 CAN FD (Flexible Data Rate) Driver Support
1324 CAN FD capable CAN controllers support two different bitrates for the
1325 arbitration phase and the payload phase of the CAN FD frame. Therefore a
1326 second bit timing has to be specified in order to enable the CAN FD bitrate.
1328 Additionally CAN FD capable CAN controllers support up to 64 bytes of
1331 layer is a plain value from 0 .. 64 instead of the CAN 'data length code'.
1333 CAN frames anyway. The payload length to the bus-relevant DLC mapping is
1334 only performed inside the CAN drivers, preferably with the helper
1337 The CAN netdevice driver capabilities can be distinguished by the network
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
1343 The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
1344 N.B. CAN FD capable devices can also handle and send legacy CAN frames.
1346 When configuring CAN FD capable CAN controllers an additional 'data' bitrate
1347 has to be set. This bitrate for the data phase of the CAN FD frame has to be
1352 within the configuration process the controller option "fd on" can be
1353 specified to enable the CAN FD mode in the CAN controller. This controller
1356 The first CAN FD specification presented as whitepaper at the International
1357 CAN Conference 2012 needed to be improved for data integrity reasons.
1358 Therefore two CAN FD implementations have to be distinguished today:
1360 - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
1361 - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
1363 Finally there are three types of CAN FD controllers:
1367 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
1369 The current ISO/non-ISO mode is announced by the CAN controller driver via
1371 The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
1372 switchable CAN FD controllers only.
1376 $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
1381 link/can promiscuity 0
1382 can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1393 Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
1395 can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1398 Supported CAN Hardware
1401 Please check the "Kconfig" file in "drivers/net/can" to get an actual
1402 list of the support CAN hardware. On the SocketCAN project website
1412 The Linux CAN / SocketCAN project resources (project site / mailing list)
1414 Search for CAN NETWORK [LAYERS|DRIVERS].
1422 - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver inter…
1428 - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
1430 - Uwe Koppe (CAN netdevices with PF_PACKET approach)
1431 - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)