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
458 This flag can be interpreted as a 'transmission confirmation' when the
459 CAN driver supports the echo of frames on driver level, see
471 known access to CAN character devices. To meet the new possibilities
477 - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`)
482 sockets, include <linux/can/raw.h>.
490 The reception of CAN frames using CAN_RAW sockets can be controlled
493 The CAN filter structure is defined in include/linux/can.h:
508 which is analogous to known CAN controllers hardware filter semantics.
509 The filter can be inverted in this semantic, when the CAN_INV_FILTER
511 contrast to CAN controller hardware filters the user may set 0 .. n
525 To disable the reception of CAN frames on the selected CAN_RAW socket:
532 data causes the raw socket to discard the received CAN frames. But
536 CAN Filter Usage Optimisation
539 The CAN filters are processed in per-device filter lists at CAN frame
541 while walking through the filter lists the CAN core provides an optimized
542 filter handling when the filter subscription focusses on a single CAN ID.
544 For the possible 2048 SFF CAN identifiers the identifier is used as an index
546 For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as
549 To benefit from the optimized filters for single CAN identifiers the
552 can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is
560 both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass.
562 To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the
580 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
581 called Error Message Frames that can optionally be passed to the user
582 application in the same way as other CAN frames. The possible
585 error condition CAN_ERR_MASK can be used as value for the error mask.
586 The values for the error mask are defined in linux/can/error.h:
601 (e.g. when only one application uses the CAN bus) this loopback
602 functionality can be disabled (separately for each socket):
614 When the local loopback is enabled, all the sent CAN frames are
615 looped back to the open CAN sockets that registered for the CAN
616 frames' CAN-ID on this given interface to meet the multi user
617 needs. The reception of the CAN frames on the same socket that was
618 sending the CAN frame is assumed to be unwanted and therefore
629 Note that reception of a socket's own CAN frames are subject to the same
630 filtering as other CAN frames (see :ref:`socketcan-rawfilter`).
637 CAN FD support in CAN_RAW sockets can be enabled with a new socket option
642 Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames
643 and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames
662 printf("got CAN FD frame with length %d\n", cfd.len);
665 printf("got Classical CAN frame with length %d\n", cfd.len);
668 fprintf(stderr, "read: invalid CAN(FD) frame\n");
672 /* the content can be handled independently from the received MTU size */
679 been received from the socket a Classical CAN frame has been read into the
680 provided CAN FD structure. Note that the canfd_frame.flags data field is
682 CANFD_MTU sized CAN FD frames.
684 Implementation hint for new CAN applications:
686 To build a CAN FD aware application use struct canfd_frame as basic CAN
689 socket option returns an error: No problem. You'll get Classical CAN frames
690 or CAN FD frames and can process them the same way.
692 When sending to CAN devices make sure that the device is capable to handle
693 CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU.
694 The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
700 The CAN_RAW socket can set multiple CAN identifier specific filters that
705 This socket option joines the given CAN filters in the way that only CAN
706 frames are passed to user space that matched *all* given CAN filters. The
710 where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or
711 CAN ID ranges from the incoming traffic.
718 interface to filter and send (e.g. cyclic) CAN messages in kernel space.
720 Receive filters can be used to down sample frequent messages; detect events
724 Periodic transmission tasks of CAN frames or a sequence of CAN frames can be
726 possible transmit intervals can be altered.
728 A BCM socket is not intended for sending individual CAN frames using the
732 defined in the linux/can/bcm.h include. The BCM message consists of a
733 message header with a command ('opcode') followed by zero or more CAN frames.
748 The aligned payload 'frames' uses the same basic CAN frame structure defined
749 at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
776 CAN_BCM sockets are recommended to communicate on multiple CAN interfaces.
777 When the broadcast manager socket is bound to 'any' CAN interface (=> the
779 CAN interface unless the sendto() syscall is used to overrule the 'any' CAN
781 socket messages the originating CAN interface is provided in can_ifindex.
803 Send one CAN frame.
834 BCM message with updated CAN frame (detected content change).
835 Sent on first message received or on receipt of revised CAN messages.
849 and count. Starting the timer leads simultaneously to emit a CAN frame.
883 The CAN frames following the bcm_msg_head are struct canfd_frame's
893 The timer values can be altered at runtime when only SET_TIMER is set.
899 Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic
900 TX task configuration. The number of CAN frames is provided in the 'nframes'
901 element of the BCM message head. The defined number of CAN frames are added
906 /* create a struct to set up a sequence of four CAN frames */
918 With every transmission the index in the array of CAN frames is increased
931 is activated directly - even without a former CAN frame reception.
936 CAN frame is stateless as state changes within the ival2 period may get
943 than one CAN frames can be passed in a RX_SETUP configuration message. The
944 data bytes of the first CAN frame contain the mask of relevant bits that
945 have to match in the subsequent CAN frames with the received CAN frame.
946 If one of the subsequent CAN frames is matching the bits in that frame data
948 Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN
949 filters) can be added as array to the TX_SETUP BCM configuration message:
953 /* usually used to clear CAN frame data[] - beware of endian problems! */
974 Broadcast Manager CAN FD Support
979 schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head
980 flags indicates that the concatenated CAN frame structures behind the
996 When using CAN FD frames for multiplex filtering the MUX mask is still
1018 PF_CAN. CAN protocol modules are loaded by the core module at
1019 runtime. The core module provides an interface for CAN protocol
1020 modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`).
1023 can.ko Module Params
1029 invoked at can.ko module start time by default. This timer can be
1040 lists to deliver received CAN frames to CAN protocol modules. These
1041 receive lists, their filters and the count of filter matches can be
1045 foo@bar:~$ cat /proc/net/can/rcvlist_all
1055 In this example an application requests any CAN traffic from vcan0::
1064 Additional procfs files in /proc/net/can::
1071 Writing Own CAN Protocol Modules
1075 protocol has to be defined in include/linux/can.h .
1076 The prototypes and definitions to use the SocketCAN core can be
1077 accessed by including include/linux/can/core.h .
1078 In addition to functions that register the CAN protocol and the
1079 CAN device notifier chain there are functions to subscribe CAN
1080 frames received by CAN interfaces and to send CAN frames::
1082 can_rx_register - subscribe CAN frames from a specific interface
1083 can_rx_unregister - unsubscribe CAN frames from a specific interface
1084 can_send - transmit a CAN frame (optional with local loopback)
1086 For details see the kerneldoc documentation in net/can/af_can.c or
1087 the source code of net/can/raw.c or net/can/bcm.c .
1090 CAN Network Drivers
1093 Writing a CAN network device driver is much easier than writing a
1094 CAN character device driver. Similar to other known network device
1097 - TX: Put the CAN frame from the socket buffer to the CAN controller.
1098 - RX: Put the CAN frame from the CAN controller to the socket buffer.
1101 for writing CAN network device driver are described below:
1110 dev->flags = IFF_NOARP; /* CAN has no arp */
1112 dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> Classical CAN interface */
1114 or alternative, when the controller supports CAN with flexible data rate:
1115 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
1126 As described in :ref:`socketcan-local-loopback1` the CAN network device driver should
1135 CAN Controller Hardware Filters
1138 To reduce the interrupt load on deep embedded systems some CAN
1139 controllers support the filtering of CAN IDs or ranges of CAN IDs.
1149 @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
1156 CAN bus requires a specific impedance across the differential pair,
1158 the bus. Some CAN controllers support activating / deactivating a
1169 $ ip link set dev can0 type can termination 120
1173 $ ip link set dev can0 type can termination 0
1175 To enable termination resistor support to a can-controller, either
1176 implement in the controller's struct can-priv::
1183 Documentation/devicetree/bindings/net/can/can-controller.yaml
1186 The Virtual CAN Driver (vcan)
1190 CAN interface. A full qualified address on CAN consists of
1192 - a unique CAN Identifier (CAN ID)
1193 - the CAN bus this CAN ID is transmitted on (e.g. can0)
1195 so in common use cases more than one virtual CAN interface is needed.
1197 The virtual CAN interfaces allow the transmission and reception of CAN
1198 frames without real CAN controller hardware. Virtual CAN network
1200 When compiled as a module the virtual CAN driver module is called vcan.ko
1204 removal of vcan network devices can be managed with the ip(8) tool::
1206 - Create a virtual CAN network interface:
1209 - Create a virtual CAN network interface with a specific name 'vcan42':
1212 - Remove a (virtual CAN) network interface 'vcan42':
1216 The CAN Network Device Driver Interface
1219 The CAN network device driver interface provides a generic interface
1220 to setup, configure and monitor CAN network devices. The user can then
1221 configure the CAN device, like setting the bit-timing parameters, via
1225 set of common functions, which all real CAN network device drivers
1227 understand how to use them. The name of the module is can-dev.ko.
1233 The CAN device must be configured via netlink interface. The supported
1235 "include/linux/can/netlink.h". CAN link support for the program "ip"
1236 of the IPROUTE2 utility suite is available and it can be used as shown
1239 Setting CAN device properties::
1241 $ ip link set can0 type can help
1242 Usage: ip link set DEVICE type can
1273 Display CAN device details and statistics::
1277 link/can
1278 can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
1293 Shows the list of selected CAN controller modes: LOOPBACK,
1297 The current state of the CAN controller: "ERROR-ACTIVE",
1302 restart of the CAN controller will be triggered automatically
1310 bit-timing can be defined by setting the "bitrate" argument.
1311 Optionally the "sample-point" can be specified. By default it's
1317 tq. They allow to define the CAN bit-timing in a hardware
1318 independent format as proposed by the Bosch CAN 2.0 spec (see
1322 Shows the bit-timing constants of the CAN controller, here the
1325 bitrate pre-scaler and the CAN system clock frequency in Hz.
1335 Setting the CAN Bit-Timing
1338 The CAN bit-timing parameters can always be defined in a hardware
1339 independent format as proposed in the Bosch CAN 2.0 specification
1343 $ ip link set canX type can tq 125 prop-seg 6 \
1347 recommended CAN bit-timing parameters will be calculated if the bit-
1350 $ ip link set canX type can bitrate 125000
1352 Note that this works fine for the most common CAN controllers with
1353 standard bit-rates but may *fail* for exotic bit-rates or CAN system
1356 bit-timing parameters. The CAN controller specific bit-timing
1357 constants can be used for that purpose. They are listed by the
1365 Starting and Stopping the CAN Network Device
1368 A CAN network device is started or stopped as usual with the command
1370 you *must* define proper bit-timing parameters for real CAN devices
1371 before you can start it to avoid error-prone default settings::
1373 $ ip link set canX up type can bitrate 125000
1376 the CAN bus. Then no more messages are received or sent. An automatic
1377 bus-off recovery can be enabled by setting the "restart-ms" to a
1380 $ ip link set canX type can restart-ms 100
1383 by monitoring CAN error message frames and do a restart when
1386 $ ip link set canX type can restart
1388 Note that a restart will also create a CAN error message frame (see
1392 .. _socketcan-can-fd-driver:
1394 CAN FD (Flexible Data Rate) Driver Support
1397 CAN FD capable CAN controllers support two different bitrates for the
1398 arbitration phase and the payload phase of the CAN FD frame. Therefore a
1399 second bit timing has to be specified in order to enable the CAN FD bitrate.
1401 Additionally CAN FD capable CAN controllers support up to 64 bytes of
1404 layer is a plain value from 0 .. 64 instead of the CAN 'data length code'.
1406 CAN frames anyway. The payload length to the bus-relevant DLC mapping is
1407 only performed inside the CAN drivers, preferably with the helper
1410 The CAN netdevice driver capabilities can be distinguished by the network
1413 MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => Classical CAN device
1414 MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device
1416 The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
1417 N.B. CAN FD capable devices can also handle and send Classical CAN frames.
1419 When configuring CAN FD capable CAN controllers an additional 'data' bitrate
1420 has to be set. This bitrate for the data phase of the CAN FD frame has to be
1425 within the configuration process the controller option "fd on" can be
1426 specified to enable the CAN FD mode in the CAN controller. This controller
1429 The first CAN FD specification presented as whitepaper at the International
1430 CAN Conference 2012 needed to be improved for data integrity reasons.
1431 Therefore two CAN FD implementations have to be distinguished today:
1433 - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
1434 - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
1436 Finally there are three types of CAN FD controllers:
1440 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
1442 The current ISO/non-ISO mode is announced by the CAN controller driver via
1444 The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
1445 switchable CAN FD controllers only.
1449 $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
1454 link/can promiscuity 0
1455 can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1466 Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
1468 can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1471 Supported CAN Hardware
1474 Please check the "Kconfig" file in "drivers/net/can" to get an actual
1475 list of the support CAN hardware. On the SocketCAN project website
1485 The Linux CAN / SocketCAN project resources (project site / mailing list)
1487 Search for CAN NETWORK [LAYERS|DRIVERS].
1495 - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver inter…
1501 - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
1503 - Uwe Koppe (CAN netdevices with PF_PACKET approach)
1504 - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)