^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) SocketCAN - Controller Area Network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Overview / What is SocketCAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) The socketcan package is an implementation of CAN protocols
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) (Controller Area Network) for Linux. CAN is a networking technology
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) which has widespread use in automation, embedded devices, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) automotive fields. While there have been other CAN implementations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) for Linux based on character devices, SocketCAN uses the Berkeley
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) socket API, the Linux network stack and implements the CAN device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) drivers as network interfaces. The CAN socket API has been designed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) as similar as possible to the TCP/IP protocols to allow programmers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) familiar with network programming, to easily learn how to use CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) sockets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) .. _socketcan-motivation:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Motivation / Why Using the Socket API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) There have been CAN implementations for Linux before SocketCAN so the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) question arises, why we have started another project. Most existing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) implementations come as a device driver for some CAN hardware, they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) are based on character devices and provide comparatively little
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) functionality. Usually, there is only a hardware-specific device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) driver which provides a character device interface to send and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) receive raw CAN frames, directly to/from the controller hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Queueing of frames and higher-level transport protocols like ISO-TP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) have to be implemented in user space applications. Also, most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) character-device implementations support only one single process to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) open the device at a time, similar to a serial interface. Exchanging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) the CAN controller requires employment of another device driver and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) often the need for adaption of large parts of the application to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) new driver's API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) SocketCAN was designed to overcome all of these limitations. A new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) protocol family has been implemented which provides a socket interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) to user space applications and which builds upon the Linux network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) layer, enabling use all of the provided queueing functionality. A device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) driver for CAN controller hardware registers itself with the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) network layer as a network device, so that CAN frames from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) controller can be passed up to the network layer and on to the CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) protocol family module and also vice-versa. Also, the protocol family
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) module provides an API for transport protocol modules to register, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) that any number of transport protocols can be loaded or unloaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) dynamically. In fact, the can core module alone does not provide any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) protocol and cannot be used without loading at least one additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) protocol module. Multiple sockets can be opened at the same time,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) on different or the same protocol module and they can listen/send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) frames on different or the same CAN IDs. Several sockets listening on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) the same interface for frames with the same CAN ID are all passed the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) same received matching CAN frames. An application wishing to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) communicate using a specific transport protocol, e.g. ISO-TP, just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) selects that protocol when opening the socket, and then can read and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) write application data byte streams, without having to deal with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) CAN-IDs, frames, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Similar functionality visible from user-space could be provided by a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) character device, too, but this would lead to a technically inelegant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) solution for a couple of reasons:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) * **Intricate usage:** Instead of passing a protocol argument to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) socket(2) and using bind(2) to select a CAN interface and CAN ID, an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) application would have to do all these operations using ioctl(2)s.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) * **Code duplication:** A character device cannot make use of the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) network queueing code, so all that code would have to be duplicated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) for CAN networking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) * **Abstraction:** In most existing character-device implementations, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) hardware-specific device driver for a CAN controller directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) provides the character device for the application to work with.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) This is at least very unusual in Unix systems for both, char and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) block devices. For example you don't have a character device for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) certain UART of a serial interface, a certain sound chip in your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) computer, a SCSI or IDE controller providing access to your hard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) disk or tape streamer device. Instead, you have abstraction layers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) which provide a unified character or block device interface to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) application on the one hand, and a interface for hardware-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) device drivers on the other hand. These abstractions are provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) by subsystems like the tty layer, the audio subsystem or the SCSI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) and IDE subsystems for the devices mentioned above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) The easiest way to implement a CAN device driver is as a character
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) device without such a (complete) abstraction layer, as is done by most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) existing drivers. The right way, however, would be to add such a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) layer with all the functionality like registering for certain CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) IDs, supporting several open file descriptors and (de)multiplexing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) CAN frames between them, (sophisticated) queueing of CAN frames, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) providing an API for device drivers to register with. However, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) it would be no more difficult, or may be even easier, to use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) networking framework provided by the Linux kernel, and this is what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) SocketCAN does.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) The use of the networking framework of the Linux kernel is just the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) natural and most appropriate way to implement CAN for Linux.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) .. _socketcan-concept:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) SocketCAN Concept
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) As described in :ref:`socketcan-motivation` the main goal of SocketCAN is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) provide a socket interface to user space applications which builds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) upon the Linux network layer. In contrast to the commonly known
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) medium that has no MAC-layer addressing like ethernet. The CAN-identifier
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) have to be chosen uniquely on the bus. When designing a CAN-ECU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) network the CAN-IDs are mapped to be sent by a specific ECU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) For this reason a CAN-ID can be treated best as a kind of source address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) .. _socketcan-receive-lists:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Receive Lists
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) The network transparent access of multiple applications leads to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) problem that different applications may be interested in the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) CAN-IDs from the same CAN network interface. The SocketCAN core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) module - which implements the protocol family CAN - provides several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) high efficient receive lists for this reason. If e.g. a user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) application opens a CAN RAW socket, the raw protocol module itself
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) requests the (range of) CAN-IDs from the SocketCAN core that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) requested by the user. The subscription and unsubscription of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) CAN-IDs can be done for specific CAN interfaces or for all(!) known
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) CAN interfaces with the can_rx_(un)register() functions provided to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) CAN protocol modules by the SocketCAN core (see :ref:`socketcan-core-module`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) To optimize the CPU usage at runtime the receive lists are split up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) into several specific lists per device that match the requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) filter complexity for a given use-case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) .. _socketcan-local-loopback1:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) Local Loopback of Sent Frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) As known from other networking concepts the data exchanging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) applications may run on the same or different nodes without any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) change (except for the according addressing information):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) .. code::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) ___ ___ ___ _______ ___
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) | _ | | _ | | _ | | _ _ | | _ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) ||A|| ||B|| ||C|| ||A| |B|| ||C||
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) |___| |___| |___| |_______| |___|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) | | | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) -----------------(1)- CAN bus -(2)---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) To ensure that application A receives the same information in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) example (2) as it would receive in example (1) there is need for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) some kind of local loopback of the sent CAN frames on the appropriate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) node.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) The Linux network devices (by default) just can handle the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) transmission and reception of media dependent frames. Due to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) arbitration on the CAN bus the transmission of a low prio CAN-ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) may be delayed by the reception of a high prio CAN frame. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) reflect the correct [#f1]_ traffic on the node the loopback of the sent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) data has to be performed right after a successful transmission. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) the CAN network interface is not capable of performing the loopback for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) some reason the SocketCAN core can do this task as a fallback solution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) See :ref:`socketcan-local-loopback1` for details (recommended).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) The loopback functionality is enabled by default to reflect standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) networking behaviour for CAN applications. Due to some requests from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) the RT-SocketCAN group the loopback optionally may be disabled for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) separate socket. See sockopts from the CAN RAW sockets in :ref:`socketcan-raw-sockets`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) .. [#f1] you really like to have this when you're running analyser
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) tools like 'candump' or 'cansniffer' on the (same) node.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) .. _socketcan-network-problem-notifications:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) Network Problem Notifications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) The use of the CAN bus may lead to several problems on the physical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) and media access control layer. Detecting and logging of these lower
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) layer problems is a vital requirement for CAN users to identify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) hardware issues on the physical transceiver layer as well as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) arbitration problems and error frames caused by the different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) ECUs. The occurrence of detected errors are important for diagnosis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) and have to be logged together with the exact timestamp. For this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) reason the CAN interface driver can generate so called Error Message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Frames that can optionally be passed to the user application in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) same way as other CAN frames. Whenever an error on the physical layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) or the MAC layer is detected (e.g. by the CAN controller) the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) creates an appropriate error message frame. Error messages frames can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) be requested by the user application using the common CAN filter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) mechanisms. Inside this filter definition the (interested) type of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) errors may be selected. The reception of error messages is disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) by default. The format of the CAN error message frame is briefly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) described in the Linux header file "include/uapi/linux/can/error.h".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) How to use SocketCAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) Like TCP/IP, you first need to open a socket for communicating over a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) CAN network. Since SocketCAN implements a new protocol family, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) need to pass PF_CAN as the first argument to the socket(2) system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) call. Currently, there are two CAN protocols to choose from, the raw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) socket protocol and the broadcast manager (BCM). So to open a socket,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) you would write::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) and::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) respectively. After the successful creation of the socket, you would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) normally use the bind(2) system call to bind the socket to a CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) interface (which is different from TCP/IP due to different addressing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) - see :ref:`socketcan-concept`). After binding (CAN_RAW) or connecting (CAN_BCM)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) the socket, you can read(2) and write(2) from/to the socket or use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) on the socket as usual. There are also CAN specific socket options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) The basic CAN frame structure and the sockaddr structure are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) in include/linux/can.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) struct can_frame {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) __u8 can_dlc; /* frame payload length in byte (0 .. 8) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) __u8 __pad; /* padding */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) __u8 __res0; /* reserved / padding */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) __u8 __res1; /* reserved / padding */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) __u8 data[8] __attribute__((aligned(8)));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) The alignment of the (linear) payload data[] to a 64bit boundary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) allows the user to define their own structs and unions to easily access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) the CAN payload. There is no given byteorder on the CAN bus by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) default. A read(2) system call on a CAN_RAW socket transfers a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) struct can_frame to the user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) The sockaddr_can structure has an interface index like the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) PF_PACKET socket, that also binds to a specific interface:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) struct sockaddr_can {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) sa_family_t can_family;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) int can_ifindex;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) /* transport protocol class address info (e.g. ISOTP) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) struct { canid_t rx_id, tx_id; } tp;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) /* reserved for future CAN protocols address information */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) } can_addr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) To determine the interface index an appropriate ioctl() has to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) be used (example for CAN_RAW sockets without error checking):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) int s;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) struct sockaddr_can addr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) struct ifreq ifr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) strcpy(ifr.ifr_name, "can0" );
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) ioctl(s, SIOCGIFINDEX, &ifr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) addr.can_family = AF_CAN;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) addr.can_ifindex = ifr.ifr_ifindex;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) bind(s, (struct sockaddr *)&addr, sizeof(addr));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) (..)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) To bind a socket to all(!) CAN interfaces the interface index must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) be 0 (zero). In this case the socket receives CAN frames from every
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) enabled CAN interface. To determine the originating CAN interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) the system call recvfrom(2) may be used instead of read(2). To send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) on a socket that is bound to 'any' interface sendto(2) is needed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) specify the outgoing interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) Reading CAN frames from a bound CAN_RAW socket (see above) consists
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) of reading a struct can_frame:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) struct can_frame frame;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) nbytes = read(s, &frame, sizeof(struct can_frame));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) if (nbytes < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) perror("can raw socket read");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) return 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) /* paranoid check ... */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) if (nbytes < sizeof(struct can_frame)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) fprintf(stderr, "read: incomplete CAN frame\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) return 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) /* do something with the received CAN frame */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) Writing CAN frames can be done similarly, with the write(2) system call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) nbytes = write(s, &frame, sizeof(struct can_frame));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) When the CAN interface is bound to 'any' existing CAN interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) information about the originating CAN interface is needed:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) struct sockaddr_can addr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) struct ifreq ifr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) socklen_t len = sizeof(addr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) struct can_frame frame;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) nbytes = recvfrom(s, &frame, sizeof(struct can_frame),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) 0, (struct sockaddr*)&addr, &len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) /* get interface name of the received CAN frame */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) ifr.ifr_ifindex = addr.can_ifindex;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) ioctl(s, SIOCGIFNAME, &ifr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) printf("Received a CAN frame from interface %s", ifr.ifr_name);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) To write CAN frames on sockets bound to 'any' CAN interface the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) outgoing interface has to be defined certainly:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) strcpy(ifr.ifr_name, "can0");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) ioctl(s, SIOCGIFINDEX, &ifr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) addr.can_ifindex = ifr.ifr_ifindex;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) addr.can_family = AF_CAN;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) nbytes = sendto(s, &frame, sizeof(struct can_frame),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) 0, (struct sockaddr*)&addr, sizeof(addr));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) An accurate timestamp can be obtained with an ioctl(2) call after reading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) a message from the socket:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) struct timeval tv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) ioctl(s, SIOCGSTAMP, &tv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) The timestamp has a resolution of one microsecond and is set automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) at the reception of a CAN frame.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) Remark about CAN FD (flexible data rate) support:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) Generally the handling of CAN FD is very similar to the formerly described
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) examples. The new CAN FD capable CAN controllers support two different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) bitrates for the arbitration phase and the payload phase of the CAN FD frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) and up to 64 bytes of payload. This extended payload length breaks all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) switches the socket into a mode that allows the handling of CAN FD frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) and (legacy) CAN frames simultaneously (see :ref:`socketcan-rawfd`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) The struct canfd_frame is defined in include/linux/can.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) struct canfd_frame {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) __u8 len; /* frame payload length in byte (0 .. 64) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) __u8 flags; /* additional flags for CAN FD */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) __u8 __res0; /* reserved / padding */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) __u8 __res1; /* reserved / padding */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) __u8 data[64] __attribute__((aligned(8)));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) The struct canfd_frame and the existing struct can_frame have the can_id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) the payload length and the payload data at the same offset inside their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) structures. This allows to handle the different structures very similar.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) When the content of a struct can_frame is copied into a struct canfd_frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) all structure elements can be used as-is - only the data[] becomes extended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) When introducing the struct canfd_frame it turned out that the data length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) code (DLC) of the struct can_frame was used as a length information as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) the easy handling of the length information the canfd_frame.len element
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) contains a plain length value from 0 .. 64. So both canfd_frame.len and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) can_frame.can_dlc are equal and contain a length information and no DLC.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) For details about the distinction of CAN and CAN FD capable devices and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) The length of the two CAN(FD) frame structures define the maximum transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) unit (MTU) of the CAN(FD) network interface and skbuff data length. Two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) definitions are specified for CAN specific MTUs in include/linux/can.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) .. _socketcan-raw-sockets:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) RAW Protocol Sockets with can_filters (SOCK_RAW)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) ------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) Using CAN_RAW sockets is extensively comparable to the commonly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) known access to CAN character devices. To meet the new possibilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) provided by the multi user SocketCAN approach, some reasonable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) defaults are set at RAW socket binding time:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) - The filters are set to exactly one filter receiving everything
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) - The socket only receives valid data frames (=> no error message frames)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) - The socket does not receive its own sent frames (in loopback mode)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) These default settings may be changed before or after binding the socket.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) To use the referenced definitions of the socket options for CAN_RAW
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) sockets, include <linux/can/raw.h>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) .. _socketcan-rawfilter:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) RAW socket option CAN_RAW_FILTER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) The reception of CAN frames using CAN_RAW sockets can be controlled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) The CAN filter structure is defined in include/linux/can.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) struct can_filter {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) canid_t can_id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) canid_t can_mask;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) A filter matches, when:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) <received_can_id> & mask == can_id & mask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) which is analogous to known CAN controllers hardware filter semantics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) The filter can be inverted in this semantic, when the CAN_INV_FILTER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) bit is set in can_id element of the can_filter structure. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) contrast to CAN controller hardware filters the user may set 0 .. n
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) receive filters for each open socket separately:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) struct can_filter rfilter[2];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) rfilter[0].can_id = 0x123;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) rfilter[0].can_mask = CAN_SFF_MASK;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) rfilter[1].can_id = 0x200;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) rfilter[1].can_mask = 0x700;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) To disable the reception of CAN frames on the selected CAN_RAW socket:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) To set the filters to zero filters is quite obsolete as to not read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) data causes the raw socket to discard the received CAN frames. But
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) having this 'send only' use-case we may remove the receive list in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) Kernel to save a little (really a very little!) CPU usage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) CAN Filter Usage Optimisation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) .............................
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) The CAN filters are processed in per-device filter lists at CAN frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) reception time. To reduce the number of checks that need to be performed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) while walking through the filter lists the CAN core provides an optimized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) filter handling when the filter subscription focusses on a single CAN ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) For the possible 2048 SFF CAN identifiers the identifier is used as an index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) to access the corresponding subscription list without any further checks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) hash function to retrieve the EFF table index.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) To benefit from the optimized filters for single CAN identifiers the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) CAN_SFF_MASK or CAN_EFF_MASK have to be set into can_filter.mask together
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) with set CAN_EFF_FLAG and CAN_RTR_FLAG bits. A set CAN_EFF_FLAG bit in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) subscribed. E.g. in the example from above:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) rfilter[0].can_id = 0x123;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) rfilter[0].can_mask = CAN_SFF_MASK;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) filter has to be defined in this way to benefit from the optimized filters:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) struct can_filter rfilter[2];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) rfilter[0].can_id = 0x123;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) rfilter[0].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_SFF_MASK);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) rfilter[1].can_id = 0x12345678 | CAN_EFF_FLAG;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) rfilter[1].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_EFF_MASK);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) RAW Socket Option CAN_RAW_ERR_FILTER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generate so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) called Error Message Frames that can optionally be passed to the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) application in the same way as other CAN frames. The possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) errors are divided into different error classes that may be filtered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) using the appropriate error mask. To register for every possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) error condition CAN_ERR_MASK can be used as value for the error mask.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) The values for the error mask are defined in linux/can/error.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF );
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) &err_mask, sizeof(err_mask));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) RAW Socket Option CAN_RAW_LOOPBACK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) To meet multi user needs the local loopback is enabled by default
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) (see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) (e.g. when only one application uses the CAN bus) this loopback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) functionality can be disabled (separately for each socket):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) int loopback = 0; /* 0 = disabled, 1 = enabled (default) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) RAW socket option CAN_RAW_RECV_OWN_MSGS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) When the local loopback is enabled, all the sent CAN frames are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) looped back to the open CAN sockets that registered for the CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) frames' CAN-ID on this given interface to meet the multi user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) needs. The reception of the CAN frames on the same socket that was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) sending the CAN frame is assumed to be unwanted and therefore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) disabled by default. This default behaviour may be changed on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) demand:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) &recv_own_msgs, sizeof(recv_own_msgs));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) .. _socketcan-rawfd:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) RAW Socket Option CAN_RAW_FD_FRAMES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) CAN FD support in CAN_RAW sockets can be enabled with a new socket option
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) CAN_RAW_FD_FRAMES which is off by default. When the new socket option is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) not supported by the CAN_RAW socket (e.g. on older kernels), switching the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) when reading from the socket:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) CAN_RAW_FD_FRAMES enabled: CAN_MTU and CANFD_MTU are allowed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) CAN_RAW_FD_FRAMES disabled: only CAN_MTU is allowed (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) Example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) [ remember: CANFD_MTU == sizeof(struct canfd_frame) ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) struct canfd_frame cfd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) nbytes = read(s, &cfd, CANFD_MTU);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) if (nbytes == CANFD_MTU) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) printf("got CAN FD frame with length %d\n", cfd.len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) /* cfd.flags contains valid data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) } else if (nbytes == CAN_MTU) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) printf("got legacy CAN frame with length %d\n", cfd.len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) /* cfd.flags is undefined */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) } else {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) fprintf(stderr, "read: invalid CAN(FD) frame\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) return 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) /* the content can be handled independently from the received MTU size */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) for (i = 0; i < cfd.len; i++)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) printf("%02X ", cfd.data[i]);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) When reading with size CANFD_MTU only returns CAN_MTU bytes that have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) been received from the socket a legacy CAN frame has been read into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) provided CAN FD structure. Note that the canfd_frame.flags data field is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) not specified in the struct can_frame and therefore it is only valid in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) CANFD_MTU sized CAN FD frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) Implementation hint for new CAN applications:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) To build a CAN FD aware application use struct canfd_frame as basic CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) data structure for CAN_RAW based applications. When the application is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) socket option returns an error: No problem. You'll get legacy CAN frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) or CAN FD frames and can process them the same way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) When sending to CAN devices make sure that the device is capable to handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) RAW socket option CAN_RAW_JOIN_FILTERS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) The CAN_RAW socket can set multiple CAN identifier specific filters that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) lead to multiple filters in the af_can.c filter processing. These filters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) are indenpendent from each other which leads to logical OR'ed filters when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) applied (see :ref:`socketcan-rawfilter`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) This socket option joines the given CAN filters in the way that only CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) frames are passed to user space that matched *all* given CAN filters. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) semantic for the applied filters is therefore changed to a logical AND.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) This is useful especially when the filterset is a combination of filters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) CAN ID ranges from the incoming traffic.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) RAW Socket Returned Message Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) When using recvmsg() call, the msg->msg_flags may contain following flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) MSG_DONTROUTE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) set when the received frame was created on the local host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) MSG_CONFIRM:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) set when the frame was sent via the socket it is received on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) This flag can be interpreted as a 'transmission confirmation' when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) CAN driver supports the echo of frames on driver level, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) Broadcast Manager Protocol Sockets (SOCK_DGRAM)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) -----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) The Broadcast Manager protocol provides a command based configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) interface to filter and send (e.g. cyclic) CAN messages in kernel space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) Receive filters can be used to down sample frequent messages; detect events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) such as message contents changes, packet length changes, and do time-out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) monitoring of received messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) Periodic transmission tasks of CAN frames or a sequence of CAN frames can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) created and modified at runtime; both the message content and the two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) possible transmit intervals can be altered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) A BCM socket is not intended for sending individual CAN frames using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) struct can_frame as known from the CAN_RAW socket. Instead a special BCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) configuration message is defined. The basic BCM configuration message used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) to communicate with the broadcast manager and the available operations are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) defined in the linux/can/bcm.h include. The BCM message consists of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) message header with a command ('opcode') followed by zero or more CAN frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) The broadcast manager sends responses to user space in the same form:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) struct bcm_msg_head {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) __u32 opcode; /* command */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) __u32 flags; /* special flags */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) __u32 count; /* run 'count' times with ival1 */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) struct timeval ival1, ival2; /* count and subsequent interval */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) canid_t can_id; /* unique can_id for task */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) __u32 nframes; /* number of can_frames following */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) struct can_frame frames[0];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) The aligned payload 'frames' uses the same basic CAN frame structure defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) messages to the broadcast manager from user space have this structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) Note a CAN_BCM socket must be connected instead of bound after socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) creation (example without error checking):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) int s;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) struct sockaddr_can addr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) struct ifreq ifr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) strcpy(ifr.ifr_name, "can0");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) ioctl(s, SIOCGIFINDEX, &ifr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) addr.can_family = AF_CAN;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) addr.can_ifindex = ifr.ifr_ifindex;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) connect(s, (struct sockaddr *)&addr, sizeof(addr));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) (..)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) The broadcast manager socket is able to handle any number of in flight
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) transmissions or receive filters concurrently. The different RX/TX jobs are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) distinguished by the unique can_id in each BCM message. However additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) CAN_BCM sockets are recommended to communicate on multiple CAN interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) When the broadcast manager socket is bound to 'any' CAN interface (=> the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) interface index is set to zero) the configured receive filters apply to any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) CAN interface unless the sendto() syscall is used to overrule the 'any' CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) interface index. When using recvfrom() instead of read() to retrieve BCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) socket messages the originating CAN interface is provided in can_ifindex.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) Broadcast Manager Operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) The opcode defines the operation for the broadcast manager to carry out,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) or details the broadcast managers response to several events, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) user requests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) Transmit Operations (user space to broadcast manager):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) TX_SETUP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) Create (cyclic) transmission task.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) TX_DELETE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) Remove (cyclic) transmission task, requires only can_id.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) TX_READ:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) Read properties of (cyclic) transmission task for can_id.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) TX_SEND:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) Send one CAN frame.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) Transmit Responses (broadcast manager to user space):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) TX_STATUS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771) Reply to TX_READ request (transmission task configuration).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) TX_EXPIRED:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) Notification when counter finishes sending at initial interval
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) 'ival1'. Requires the TX_COUNTEVT flag to be set at TX_SETUP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) Receive Operations (user space to broadcast manager):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) RX_SETUP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) Create RX content filter subscription.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) RX_DELETE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) Remove RX content filter subscription, requires only can_id.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) RX_READ:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) Read properties of RX content filter subscription for can_id.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) Receive Responses (broadcast manager to user space):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) RX_STATUS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) Reply to RX_READ request (filter task configuration).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) RX_TIMEOUT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) Cyclic message is detected to be absent (timer ival1 expired).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) RX_CHANGED:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) BCM message with updated CAN frame (detected content change).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) Sent on first message received or on receipt of revised CAN messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) Broadcast Manager Message Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) When sending a message to the broadcast manager the 'flags' element may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) contain the following flag definitions which influence the behaviour:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) SETTIMER:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) Set the values of ival1, ival2 and count
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) STARTTIMER:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) Start the timer with the actual values of ival1, ival2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) and count. Starting the timer leads simultaneously to emit a CAN frame.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) TX_COUNTEVT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) Create the message TX_EXPIRED when count expires
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) TX_ANNOUNCE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) A change of data by the process is emitted immediately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) TX_CP_CAN_ID:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) Copies the can_id from the message header to each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) subsequent frame in frames. This is intended as usage simplification. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) TX tasks the unique can_id from the message header may differ from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) can_id(s) stored for transmission in the subsequent struct can_frame(s).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) RX_FILTER_ID:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) Filter by can_id alone, no frames required (nframes=0).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) RX_CHECK_DLC:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) A change of the DLC leads to an RX_CHANGED.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) RX_NO_AUTOTIMER:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) Prevent automatically starting the timeout monitor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) RX_ANNOUNCE_RESUME:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) If passed at RX_SETUP and a receive timeout occurred, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) RX_CHANGED message will be generated when the (cyclic) receive restarts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) TX_RESET_MULTI_IDX:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) Reset the index for the multiple frame transmission.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) RX_RTR_FRAME:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) Send reply for RTR-request (placed in op->frames[0]).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) Broadcast Manager Transmission Timers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) Periodic transmission configurations may use up to two interval timers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) In this case the BCM sends a number of messages ('count') at an interval
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) 'ival1', then continuing to send at another given interval 'ival2'. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) only one timer is needed 'count' is set to zero and only 'ival2' is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) When SET_TIMER and START_TIMER flag were set the timers are activated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) The timer values can be altered at runtime when only SET_TIMER is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) Broadcast Manager message sequence transmission
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) TX task configuration. The number of CAN frames is provided in the 'nframes'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) element of the BCM message head. The defined number of CAN frames are added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) as array to the TX_SETUP BCM configuration message:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) /* create a struct to set up a sequence of four CAN frames */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) struct bcm_msg_head msg_head;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) struct can_frame frame[4];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) } mytxmsg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) (..)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) mytxmsg.msg_head.nframes = 4;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) (..)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) write(s, &mytxmsg, sizeof(mytxmsg));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) With every transmission the index in the array of CAN frames is increased
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) and set to zero at index overflow.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883) Broadcast Manager Receive Filter Timers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) When the SET_TIMER flag is set the timers are enabled:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) ival1:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) Send RX_TIMEOUT when a received message is not received again within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) the given time. When START_TIMER is set at RX_SETUP the timeout detection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) is activated directly - even without a former CAN frame reception.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894) ival2:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) Throttle the received message rate down to the value of ival2. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) is useful to reduce messages for the application when the signal inside the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) CAN frame is stateless as state changes within the ival2 periode may get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) lost.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) Broadcast Manager Multiplex Message Receive Filter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) To filter for content changes in multiplex message sequences an array of more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904) than one CAN frames can be passed in a RX_SETUP configuration message. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) data bytes of the first CAN frame contain the mask of relevant bits that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) have to match in the subsequent CAN frames with the received CAN frame.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) If one of the subsequent CAN frames is matching the bits in that frame data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) mark the relevant content to be compared with the previous received content.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909) Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) filters) can be added as array to the TX_SETUP BCM configuration message:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) /* usually used to clear CAN frame data[] - beware of endian problems! */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) #define U64_DATA(p) (*(unsigned long long*)(p)->data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) struct bcm_msg_head msg_head;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) struct can_frame frame[5];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920) } msg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) msg.msg_head.opcode = RX_SETUP;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) msg.msg_head.can_id = 0x42;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924) msg.msg_head.flags = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) msg.msg_head.nframes = 5;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) U64_DATA(&msg.frame[0]) = 0xFF00000000000000ULL; /* MUX mask */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) U64_DATA(&msg.frame[1]) = 0x01000000000000FFULL; /* data mask (MUX 0x01) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) U64_DATA(&msg.frame[2]) = 0x0200FFFF000000FFULL; /* data mask (MUX 0x02) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) U64_DATA(&msg.frame[3]) = 0x330000FFFFFF0003ULL; /* data mask (MUX 0x33) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) U64_DATA(&msg.frame[4]) = 0x4F07FC0FF0000000ULL; /* data mask (MUX 0x4F) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932) write(s, &msg, sizeof(msg));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) Broadcast Manager CAN FD Support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) The programming API of the CAN_BCM depends on struct can_frame which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) given as array directly behind the bcm_msg_head structure. To follow this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) flags indicates that the concatenated CAN frame structures behind the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942) bcm_msg_head are defined as struct canfd_frame:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947) struct bcm_msg_head msg_head;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) struct canfd_frame frame[5];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949) } msg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) msg.msg_head.opcode = RX_SETUP;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) msg.msg_head.can_id = 0x42;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) msg.msg_head.flags = CAN_FD_FRAME;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) msg.msg_head.nframes = 5;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955) (..)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) When using CAN FD frames for multiplex filtering the MUX mask is still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958) expected in the first 64 bit of the struct canfd_frame data section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) Connected Transport Protocols (SOCK_SEQPACKET)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962) ----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964) (to be written)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967) Unconnected Transport Protocols (SOCK_DGRAM)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) (to be written)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973) .. _socketcan-core-module:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) SocketCAN Core Module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) The SocketCAN core module implements the protocol family
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979) PF_CAN. CAN protocol modules are loaded by the core module at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980) runtime. The core module provides an interface for CAN protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984) can.ko Module Params
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987) - **stats_timer**:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988) To calculate the SocketCAN core statistics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) (e.g. current/maximum frames per second) this 1 second timer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990) invoked at can.ko module start time by default. This timer can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) disabled by using stattimer=0 on the module commandline.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993) - **debug**:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994) (removed since SocketCAN SVN r546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997) procfs content
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) As described in :ref:`socketcan-receive-lists` the SocketCAN core uses several filter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001) lists to deliver received CAN frames to CAN protocol modules. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) receive lists, their filters and the count of filter matches can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003) checked in the appropriate receive list. All entries contain the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) device and a protocol module identifier::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006) foo@bar:~$ cat /proc/net/can/rcvlist_all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) receive list 'rx_all':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) (vcan3: no entry)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010) (vcan2: no entry)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011) (vcan1: no entry)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012) device can_id can_mask function userdata matches ident
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013) vcan0 000 00000000 f88e6370 f6c6f400 0 raw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) (any: no entry)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) In this example an application requests any CAN traffic from vcan0::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018) rcvlist_all - list for unfiltered entries (no filter operations)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) rcvlist_eff - list for single extended frame (EFF) entries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020) rcvlist_err - list for error message frames masks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021) rcvlist_fil - list for mask/value filters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022) rcvlist_inv - list for mask/value filters (inverse semantic)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) rcvlist_sff - list for single standard frame (SFF) entries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025) Additional procfs files in /proc/net/can::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) stats - SocketCAN core statistics (rx/tx frames, match ratios, ...)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028) reset_stats - manual statistic reset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029) version - prints the SocketCAN core version and the ABI version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032) Writing Own CAN Protocol Modules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035) To implement a new protocol in the protocol family PF_CAN a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036) protocol has to be defined in include/linux/can.h .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037) The prototypes and definitions to use the SocketCAN core can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) accessed by including include/linux/can/core.h .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) In addition to functions that register the CAN protocol and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040) CAN device notifier chain there are functions to subscribe CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041) frames received by CAN interfaces and to send CAN frames::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043) can_rx_register - subscribe CAN frames from a specific interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) can_rx_unregister - unsubscribe CAN frames from a specific interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045) can_send - transmit a CAN frame (optional with local loopback)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047) For details see the kerneldoc documentation in net/can/af_can.c or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1048) the source code of net/can/raw.c or net/can/bcm.c .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1049)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1050)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1051) CAN Network Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1052) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1053)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1054) Writing a CAN network device driver is much easier than writing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1055) CAN character device driver. Similar to other known network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1056) drivers you mainly have to deal with:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1057)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1058) - TX: Put the CAN frame from the socket buffer to the CAN controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1059) - RX: Put the CAN frame from the CAN controller to the socket buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1060)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1061) See e.g. at Documentation/networking/netdevices.rst . The differences
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1062) for writing CAN network device driver are described below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1063)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1064)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1065) General Settings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1066) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1067)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1068) .. code-block:: C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1069)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1070) dev->type = ARPHRD_CAN; /* the netdevice hardware type */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1071) dev->flags = IFF_NOARP; /* CAN has no arp */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1072)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1073) dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1074)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1075) or alternative, when the controller supports CAN with flexible data rate:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1076) dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1077)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1078) The struct can_frame or struct canfd_frame is the payload of each socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1079) buffer (skbuff) in the protocol family PF_CAN.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1080)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1081)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1082) .. _socketcan-local-loopback2:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1083)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1084) Local Loopback of Sent Frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1085) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1086)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1087) As described in :ref:`socketcan-local-loopback1` the CAN network device driver should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1088) support a local loopback functionality similar to the local echo
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1089) e.g. of tty devices. In this case the driver flag IFF_ECHO has to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1090) set to prevent the PF_CAN core from locally echoing sent frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1091) (aka loopback) as fallback solution::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1092)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1093) dev->flags = (IFF_NOARP | IFF_ECHO);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1094)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1095)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1096) CAN Controller Hardware Filters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1097) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1098)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1099) To reduce the interrupt load on deep embedded systems some CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1100) controllers support the filtering of CAN IDs or ranges of CAN IDs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1101) These hardware filter capabilities vary from controller to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1102) controller and have to be identified as not feasible in a multi-user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1103) networking approach. The use of the very controller specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1104) hardware filters could make sense in a very dedicated use-case, as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1105) filter on driver level would affect all users in the multi-user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1106) system. The high efficient filter sets inside the PF_CAN core allow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1107) to set different multiple filters for each socket separately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1108) Therefore the use of hardware filters goes to the category 'handmade
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1109) tuning on deep embedded systems'. The author is running a MPC603e
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1110) @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1111) load without any problems ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1114) The Virtual CAN Driver (vcan)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1115) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1117) Similar to the network loopback devices, vcan offers a virtual local
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1118) CAN interface. A full qualified address on CAN consists of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1120) - a unique CAN Identifier (CAN ID)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1121) - the CAN bus this CAN ID is transmitted on (e.g. can0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1123) so in common use cases more than one virtual CAN interface is needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1125) The virtual CAN interfaces allow the transmission and reception of CAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1126) frames without real CAN controller hardware. Virtual CAN network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1127) devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1128) When compiled as a module the virtual CAN driver module is called vcan.ko
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1130) Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1131) netlink interface to create vcan network devices. The creation and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1132) removal of vcan network devices can be managed with the ip(8) tool::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1134) - Create a virtual CAN network interface:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1135) $ ip link add type vcan
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1137) - Create a virtual CAN network interface with a specific name 'vcan42':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1138) $ ip link add dev vcan42 type vcan
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1140) - Remove a (virtual CAN) network interface 'vcan42':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1141) $ ip link del vcan42
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1144) The CAN Network Device Driver Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1145) ---------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1147) The CAN network device driver interface provides a generic interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1148) to setup, configure and monitor CAN network devices. The user can then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1149) configure the CAN device, like setting the bit-timing parameters, via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1150) the netlink interface using the program "ip" from the "IPROUTE2"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1151) utility suite. The following chapter describes briefly how to use it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1152) Furthermore, the interface uses a common data structure and exports a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1153) set of common functions, which all real CAN network device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1154) should use. Please have a look to the SJA1000 or MSCAN driver to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1155) understand how to use them. The name of the module is can-dev.ko.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1158) Netlink interface to set/get devices properties
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1159) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1161) The CAN device must be configured via netlink interface. The supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1162) netlink message types are defined and briefly described in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1163) "include/linux/can/netlink.h". CAN link support for the program "ip"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1164) of the IPROUTE2 utility suite is available and it can be used as shown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1165) below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1167) Setting CAN device properties::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1169) $ ip link set can0 type can help
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1170) Usage: ip link set DEVICE type can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1171) [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1172) [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1173) phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1175) [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1176) [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1177) dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1179) [ loopback { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1180) [ listen-only { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1181) [ triple-sampling { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1182) [ one-shot { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1183) [ berr-reporting { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1184) [ fd { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1185) [ fd-non-iso { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1186) [ presume-ack { on | off } ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1188) [ restart-ms TIME-MS ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1189) [ restart ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1191) Where: BITRATE := { 1..1000000 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1192) SAMPLE-POINT := { 0.000..0.999 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1193) TQ := { NUMBER }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1194) PROP-SEG := { 1..8 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1195) PHASE-SEG1 := { 1..8 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1196) PHASE-SEG2 := { 1..8 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1197) SJW := { 1..4 }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1198) RESTART-MS := { 0 | NUMBER }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1200) Display CAN device details and statistics::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1202) $ ip -details -statistics link show can0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1203) 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1204) link/can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1205) can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1206) bitrate 125000 sample_point 0.875
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1207) tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1208) sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1209) clock 8000000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1210) re-started bus-errors arbit-lost error-warn error-pass bus-off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1211) 41 17457 0 41 42 41
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1212) RX: bytes packets errors dropped overrun mcast
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1213) 140859 17608 17457 0 0 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1214) TX: bytes packets errors dropped carrier collsns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1215) 861 112 0 41 0 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1217) More info to the above output:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1219) "<TRIPLE-SAMPLING>"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1220) Shows the list of selected CAN controller modes: LOOPBACK,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1221) LISTEN-ONLY, or TRIPLE-SAMPLING.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1223) "state ERROR-ACTIVE"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1224) The current state of the CAN controller: "ERROR-ACTIVE",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1225) "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1227) "restart-ms 100"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1228) Automatic restart delay time. If set to a non-zero value, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1229) restart of the CAN controller will be triggered automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1230) in case of a bus-off condition after the specified delay time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1231) in milliseconds. By default it's off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1233) "bitrate 125000 sample-point 0.875"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1234) Shows the real bit-rate in bits/sec and the sample-point in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1235) range 0.000..0.999. If the calculation of bit-timing parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1236) is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1237) bit-timing can be defined by setting the "bitrate" argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1238) Optionally the "sample-point" can be specified. By default it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1239) 0.000 assuming CIA-recommended sample-points.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1241) "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1242) Shows the time quanta in ns, propagation segment, phase buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1243) segment 1 and 2 and the synchronisation jump width in units of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1244) tq. They allow to define the CAN bit-timing in a hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1245) independent format as proposed by the Bosch CAN 2.0 spec (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1246) chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1248) "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1249) Shows the bit-timing constants of the CAN controller, here the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1250) "sja1000". The minimum and maximum values of the time segment 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1251) and 2, the synchronisation jump width in units of tq, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1252) bitrate pre-scaler and the CAN system clock frequency in Hz.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1253) These constants could be used for user-defined (non-standard)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1254) bit-timing calculation algorithms in user-space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1256) "re-started bus-errors arbit-lost error-warn error-pass bus-off"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1257) Shows the number of restarts, bus and arbitration lost errors,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1258) and the state changes to the error-warning, error-passive and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1259) bus-off state. RX overrun errors are listed in the "overrun"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1260) field of the standard network statistics.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1262) Setting the CAN Bit-Timing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1263) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1265) The CAN bit-timing parameters can always be defined in a hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1266) independent format as proposed in the Bosch CAN 2.0 specification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1267) specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1268) and "sjw"::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1270) $ ip link set canX type can tq 125 prop-seg 6 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1271) phase-seg1 7 phase-seg2 2 sjw 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1273) If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1274) recommended CAN bit-timing parameters will be calculated if the bit-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1275) rate is specified with the argument "bitrate"::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1277) $ ip link set canX type can bitrate 125000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1279) Note that this works fine for the most common CAN controllers with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1280) standard bit-rates but may *fail* for exotic bit-rates or CAN system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1281) clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1282) space and allows user-space tools to solely determine and set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1283) bit-timing parameters. The CAN controller specific bit-timing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1284) constants can be used for that purpose. They are listed by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1285) following command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1287) $ ip -details link show can0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1288) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1289) sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1292) Starting and Stopping the CAN Network Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1293) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1295) A CAN network device is started or stopped as usual with the command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1296) "ifconfig canX up/down" or "ip link set canX up/down". Be aware that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1297) you *must* define proper bit-timing parameters for real CAN devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1298) before you can start it to avoid error-prone default settings::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1300) $ ip link set canX up type can bitrate 125000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1302) A device may enter the "bus-off" state if too many errors occurred on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1303) the CAN bus. Then no more messages are received or sent. An automatic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1304) bus-off recovery can be enabled by setting the "restart-ms" to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1305) non-zero value, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1307) $ ip link set canX type can restart-ms 100
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1309) Alternatively, the application may realize the "bus-off" condition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1310) by monitoring CAN error message frames and do a restart when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1311) appropriate with the command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1313) $ ip link set canX type can restart
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1315) Note that a restart will also create a CAN error message frame (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1316) also :ref:`socketcan-network-problem-notifications`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1319) .. _socketcan-can-fd-driver:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1321) CAN FD (Flexible Data Rate) Driver Support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1322) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1324) CAN FD capable CAN controllers support two different bitrates for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1325) arbitration phase and the payload phase of the CAN FD frame. Therefore a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1326) second bit timing has to be specified in order to enable the CAN FD bitrate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1328) Additionally CAN FD capable CAN controllers support up to 64 bytes of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1329) payload. The representation of this length in can_frame.can_dlc and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1330) canfd_frame.len for userspace applications and inside the Linux network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1331) layer is a plain value from 0 .. 64 instead of the CAN 'data length code'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1332) The data length code was a 1:1 mapping to the payload length in the legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1333) CAN frames anyway. The payload length to the bus-relevant DLC mapping is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1334) only performed inside the CAN drivers, preferably with the helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1335) functions can_dlc2len() and can_len2dlc().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1337) The CAN netdevice driver capabilities can be distinguished by the network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1338) devices maximum transfer unit (MTU)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1340) MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => 'legacy' CAN device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1341) MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1343) The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1344) N.B. CAN FD capable devices can also handle and send legacy CAN frames.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1346) When configuring CAN FD capable CAN controllers an additional 'data' bitrate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1347) has to be set. This bitrate for the data phase of the CAN FD frame has to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1348) at least the bitrate which was configured for the arbitration phase. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1349) second bitrate is specified analogue to the first bitrate but the bitrate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1350) setting keywords for the 'data' bitrate start with 'd' e.g. dbitrate,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1351) dsample-point, dsjw or dtq and similar settings. When a data bitrate is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1352) within the configuration process the controller option "fd on" can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1353) specified to enable the CAN FD mode in the CAN controller. This controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1354) option also switches the device MTU to 72 (CANFD_MTU).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1356) The first CAN FD specification presented as whitepaper at the International
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1357) CAN Conference 2012 needed to be improved for data integrity reasons.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1358) Therefore two CAN FD implementations have to be distinguished today:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1360) - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1361) - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1363) Finally there are three types of CAN FD controllers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1365) 1. ISO compliant (fixed)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1366) 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1367) 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1369) The current ISO/non-ISO mode is announced by the CAN controller driver via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1370) netlink and displayed by the 'ip' tool (controller option FD-NON-ISO).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1371) The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1372) switchable CAN FD controllers only.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1374) Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1376) $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1377) dbitrate 4000000 dsample-point 0.8 fd on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1378) $ ip -details link show can0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1379) 5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1380) mode DEFAULT group default qlen 10
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1381) link/can promiscuity 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1382) can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1383) bitrate 500000 sample-point 0.750
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1384) tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1385) pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1386) brp-inc 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1387) dbitrate 4000000 dsample-point 0.800
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1388) dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1389) pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1390) dbrp-inc 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1391) clock 80000000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1393) Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1395) can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1398) Supported CAN Hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1399) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1401) Please check the "Kconfig" file in "drivers/net/can" to get an actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1402) list of the support CAN hardware. On the SocketCAN project website
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1403) (see :ref:`socketcan-resources`) there might be further drivers available, also for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1404) older kernel versions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1407) .. _socketcan-resources:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1408)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1409) SocketCAN Resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1410) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1412) The Linux CAN / SocketCAN project resources (project site / mailing list)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1413) are referenced in the MAINTAINERS file in the Linux source tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1414) Search for CAN NETWORK [LAYERS|DRIVERS].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1415)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1416) Credits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1417) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1419) - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1420) - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1421) - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1422) - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver interface, MSCAN driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1423) - Robert Schwebel (design reviews, PTXdist integration)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1424) - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1425) - Benedikt Spranger (reviews)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1426) - Thomas Gleixner (LKML reviews, coding style, posting hints)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1427) - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1428) - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1429) - Klaus Hitschler (PEAK driver integration)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1430) - Uwe Koppe (CAN netdevices with PF_PACKET approach)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1431) - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1432) - Pavel Pisa (Bit-timing calculation)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1433) - Sascha Hauer (SJA1000 platform driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1434) - Sebastian Haas (SJA1000 EMS PCI driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1435) - Markus Plessing (SJA1000 EMS PCI driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1436) - Per Dalen (SJA1000 Kvaser PCI driver)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1437) - Sam Ravnborg (reviews, coding style, kbuild help)
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags