Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 1 | ============================================================================ |
| 2 | |
| 3 | can.txt |
| 4 | |
| 5 | Readme file for the Controller Area Network Protocol Family (aka Socket CAN) |
| 6 | |
| 7 | This file contains |
| 8 | |
| 9 | 1 Overview / What is Socket CAN |
| 10 | |
| 11 | 2 Motivation / Why using the socket API |
| 12 | |
| 13 | 3 Socket CAN concept |
| 14 | 3.1 receive lists |
| 15 | 3.2 local loopback of sent frames |
| 16 | 3.3 network security issues (capabilities) |
| 17 | 3.4 network problem notifications |
| 18 | |
| 19 | 4 How to use Socket CAN |
| 20 | 4.1 RAW protocol sockets with can_filters (SOCK_RAW) |
| 21 | 4.1.1 RAW socket option CAN_RAW_FILTER |
| 22 | 4.1.2 RAW socket option CAN_RAW_ERR_FILTER |
| 23 | 4.1.3 RAW socket option CAN_RAW_LOOPBACK |
| 24 | 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS |
| 25 | 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) |
| 26 | 4.3 connected transport protocols (SOCK_SEQPACKET) |
| 27 | 4.4 unconnected transport protocols (SOCK_DGRAM) |
| 28 | |
| 29 | 5 Socket CAN core module |
| 30 | 5.1 can.ko module params |
| 31 | 5.2 procfs content |
| 32 | 5.3 writing own CAN protocol modules |
| 33 | |
| 34 | 6 CAN network drivers |
| 35 | 6.1 general settings |
| 36 | 6.2 local loopback of sent frames |
| 37 | 6.3 CAN controller hardware filters |
Oliver Hartkopp | e5d2304 | 2008-09-23 14:53:14 -0700 | [diff] [blame] | 38 | 6.4 The virtual CAN driver (vcan) |
| 39 | 6.5 currently supported CAN hardware |
| 40 | 6.6 todo |
Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 41 | |
| 42 | 7 Credits |
| 43 | |
| 44 | ============================================================================ |
| 45 | |
| 46 | 1. Overview / What is Socket CAN |
| 47 | -------------------------------- |
| 48 | |
| 49 | The socketcan package is an implementation of CAN protocols |
| 50 | (Controller Area Network) for Linux. CAN is a networking technology |
| 51 | which has widespread use in automation, embedded devices, and |
| 52 | automotive fields. While there have been other CAN implementations |
| 53 | for Linux based on character devices, Socket CAN uses the Berkeley |
| 54 | socket API, the Linux network stack and implements the CAN device |
| 55 | drivers as network interfaces. The CAN socket API has been designed |
| 56 | as similar as possible to the TCP/IP protocols to allow programmers, |
| 57 | familiar with network programming, to easily learn how to use CAN |
| 58 | sockets. |
| 59 | |
| 60 | 2. Motivation / Why using the socket API |
| 61 | ---------------------------------------- |
| 62 | |
| 63 | There have been CAN implementations for Linux before Socket CAN so the |
| 64 | question arises, why we have started another project. Most existing |
| 65 | implementations come as a device driver for some CAN hardware, they |
| 66 | are based on character devices and provide comparatively little |
| 67 | functionality. Usually, there is only a hardware-specific device |
| 68 | driver which provides a character device interface to send and |
| 69 | receive raw CAN frames, directly to/from the controller hardware. |
| 70 | Queueing of frames and higher-level transport protocols like ISO-TP |
| 71 | have to be implemented in user space applications. Also, most |
| 72 | character-device implementations support only one single process to |
| 73 | open the device at a time, similar to a serial interface. Exchanging |
| 74 | the CAN controller requires employment of another device driver and |
| 75 | often the need for adaption of large parts of the application to the |
| 76 | new driver's API. |
| 77 | |
| 78 | Socket CAN was designed to overcome all of these limitations. A new |
| 79 | protocol family has been implemented which provides a socket interface |
| 80 | to user space applications and which builds upon the Linux network |
| 81 | layer, so to use all of the provided queueing functionality. A device |
| 82 | driver for CAN controller hardware registers itself with the Linux |
| 83 | network layer as a network device, so that CAN frames from the |
| 84 | controller can be passed up to the network layer and on to the CAN |
| 85 | protocol family module and also vice-versa. Also, the protocol family |
| 86 | module provides an API for transport protocol modules to register, so |
| 87 | that any number of transport protocols can be loaded or unloaded |
| 88 | dynamically. In fact, the can core module alone does not provide any |
| 89 | protocol and cannot be used without loading at least one additional |
| 90 | protocol module. Multiple sockets can be opened at the same time, |
| 91 | on different or the same protocol module and they can listen/send |
| 92 | frames on different or the same CAN IDs. Several sockets listening on |
| 93 | the same interface for frames with the same CAN ID are all passed the |
| 94 | same received matching CAN frames. An application wishing to |
| 95 | communicate using a specific transport protocol, e.g. ISO-TP, just |
| 96 | selects that protocol when opening the socket, and then can read and |
| 97 | write application data byte streams, without having to deal with |
| 98 | CAN-IDs, frames, etc. |
| 99 | |
| 100 | Similar functionality visible from user-space could be provided by a |
| 101 | character device, too, but this would lead to a technically inelegant |
| 102 | solution for a couple of reasons: |
| 103 | |
| 104 | * Intricate usage. Instead of passing a protocol argument to |
| 105 | socket(2) and using bind(2) to select a CAN interface and CAN ID, an |
| 106 | application would have to do all these operations using ioctl(2)s. |
| 107 | |
| 108 | * Code duplication. A character device cannot make use of the Linux |
| 109 | network queueing code, so all that code would have to be duplicated |
| 110 | for CAN networking. |
| 111 | |
| 112 | * Abstraction. In most existing character-device implementations, the |
| 113 | hardware-specific device driver for a CAN controller directly |
| 114 | provides the character device for the application to work with. |
| 115 | This is at least very unusual in Unix systems for both, char and |
| 116 | block devices. For example you don't have a character device for a |
| 117 | certain UART of a serial interface, a certain sound chip in your |
| 118 | computer, a SCSI or IDE controller providing access to your hard |
| 119 | disk or tape streamer device. Instead, you have abstraction layers |
| 120 | which provide a unified character or block device interface to the |
| 121 | application on the one hand, and a interface for hardware-specific |
| 122 | device drivers on the other hand. These abstractions are provided |
| 123 | by subsystems like the tty layer, the audio subsystem or the SCSI |
| 124 | and IDE subsystems for the devices mentioned above. |
| 125 | |
| 126 | The easiest way to implement a CAN device driver is as a character |
| 127 | device without such a (complete) abstraction layer, as is done by most |
| 128 | existing drivers. The right way, however, would be to add such a |
| 129 | layer with all the functionality like registering for certain CAN |
| 130 | IDs, supporting several open file descriptors and (de)multiplexing |
| 131 | CAN frames between them, (sophisticated) queueing of CAN frames, and |
| 132 | providing an API for device drivers to register with. However, then |
| 133 | it would be no more difficult, or may be even easier, to use the |
| 134 | networking framework provided by the Linux kernel, and this is what |
| 135 | Socket CAN does. |
| 136 | |
| 137 | The use of the networking framework of the Linux kernel is just the |
| 138 | natural and most appropriate way to implement CAN for Linux. |
| 139 | |
| 140 | 3. Socket CAN concept |
| 141 | --------------------- |
| 142 | |
| 143 | As described in chapter 2 it is the main goal of Socket CAN to |
| 144 | provide a socket interface to user space applications which builds |
| 145 | upon the Linux network layer. In contrast to the commonly known |
| 146 | TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) |
| 147 | medium that has no MAC-layer addressing like ethernet. The CAN-identifier |
| 148 | (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs |
| 149 | have to be chosen uniquely on the bus. When designing a CAN-ECU |
| 150 | network the CAN-IDs are mapped to be sent by a specific ECU. |
| 151 | For this reason a CAN-ID can be treated best as a kind of source address. |
| 152 | |
| 153 | 3.1 receive lists |
| 154 | |
| 155 | The network transparent access of multiple applications leads to the |
| 156 | problem that different applications may be interested in the same |
| 157 | CAN-IDs from the same CAN network interface. The Socket CAN core |
| 158 | module - which implements the protocol family CAN - provides several |
| 159 | high efficient receive lists for this reason. If e.g. a user space |
| 160 | application opens a CAN RAW socket, the raw protocol module itself |
| 161 | requests the (range of) CAN-IDs from the Socket CAN core that are |
| 162 | requested by the user. The subscription and unsubscription of |
| 163 | CAN-IDs can be done for specific CAN interfaces or for all(!) known |
| 164 | CAN interfaces with the can_rx_(un)register() functions provided to |
| 165 | CAN protocol modules by the SocketCAN core (see chapter 5). |
| 166 | To optimize the CPU usage at runtime the receive lists are split up |
| 167 | into several specific lists per device that match the requested |
| 168 | filter complexity for a given use-case. |
| 169 | |
| 170 | 3.2 local loopback of sent frames |
| 171 | |
| 172 | As known from other networking concepts the data exchanging |
| 173 | applications may run on the same or different nodes without any |
| 174 | change (except for the according addressing information): |
| 175 | |
| 176 | ___ ___ ___ _______ ___ |
| 177 | | _ | | _ | | _ | | _ _ | | _ | |
| 178 | ||A|| ||B|| ||C|| ||A| |B|| ||C|| |
| 179 | |___| |___| |___| |_______| |___| |
| 180 | | | | | | |
| 181 | -----------------(1)- CAN bus -(2)--------------- |
| 182 | |
| 183 | To ensure that application A receives the same information in the |
| 184 | example (2) as it would receive in example (1) there is need for |
| 185 | some kind of local loopback of the sent CAN frames on the appropriate |
| 186 | node. |
| 187 | |
| 188 | The Linux network devices (by default) just can handle the |
| 189 | transmission and reception of media dependent frames. Due to the |
Matt LaPlante | d919588 | 2008-07-25 19:45:33 -0700 | [diff] [blame] | 190 | arbitration on the CAN bus the transmission of a low prio CAN-ID |
Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 191 | may be delayed by the reception of a high prio CAN frame. To |
| 192 | reflect the correct* traffic on the node the loopback of the sent |
| 193 | data has to be performed right after a successful transmission. If |
| 194 | the CAN network interface is not capable of performing the loopback for |
| 195 | some reason the SocketCAN core can do this task as a fallback solution. |
| 196 | See chapter 6.2 for details (recommended). |
| 197 | |
| 198 | The loopback functionality is enabled by default to reflect standard |
| 199 | networking behaviour for CAN applications. Due to some requests from |
| 200 | the RT-SocketCAN group the loopback optionally may be disabled for each |
| 201 | separate socket. See sockopts from the CAN RAW sockets in chapter 4.1. |
| 202 | |
| 203 | * = you really like to have this when you're running analyser tools |
| 204 | like 'candump' or 'cansniffer' on the (same) node. |
| 205 | |
| 206 | 3.3 network security issues (capabilities) |
| 207 | |
| 208 | The Controller Area Network is a local field bus transmitting only |
| 209 | broadcast messages without any routing and security concepts. |
| 210 | In the majority of cases the user application has to deal with |
| 211 | raw CAN frames. Therefore it might be reasonable NOT to restrict |
| 212 | the CAN access only to the user root, as known from other networks. |
| 213 | Since the currently implemented CAN_RAW and CAN_BCM sockets can only |
| 214 | send and receive frames to/from CAN interfaces it does not affect |
| 215 | security of others networks to allow all users to access the CAN. |
| 216 | To enable non-root users to access CAN_RAW and CAN_BCM protocol |
| 217 | sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be |
| 218 | selected at kernel compile time. |
| 219 | |
| 220 | 3.4 network problem notifications |
| 221 | |
| 222 | The use of the CAN bus may lead to several problems on the physical |
| 223 | and media access control layer. Detecting and logging of these lower |
| 224 | layer problems is a vital requirement for CAN users to identify |
| 225 | hardware issues on the physical transceiver layer as well as |
| 226 | arbitration problems and error frames caused by the different |
| 227 | ECUs. The occurrence of detected errors are important for diagnosis |
| 228 | and have to be logged together with the exact timestamp. For this |
| 229 | reason the CAN interface driver can generate so called Error Frames |
| 230 | that can optionally be passed to the user application in the same |
| 231 | way as other CAN frames. Whenever an error on the physical layer |
| 232 | or the MAC layer is detected (e.g. by the CAN controller) the driver |
| 233 | creates an appropriate error frame. Error frames can be requested by |
| 234 | the user application using the common CAN filter mechanisms. Inside |
| 235 | this filter definition the (interested) type of errors may be |
| 236 | selected. The reception of error frames is disabled by default. |
| 237 | |
| 238 | 4. How to use Socket CAN |
| 239 | ------------------------ |
| 240 | |
| 241 | Like TCP/IP, you first need to open a socket for communicating over a |
| 242 | CAN network. Since Socket CAN implements a new protocol family, you |
| 243 | need to pass PF_CAN as the first argument to the socket(2) system |
| 244 | call. Currently, there are two CAN protocols to choose from, the raw |
| 245 | socket protocol and the broadcast manager (BCM). So to open a socket, |
| 246 | you would write |
| 247 | |
| 248 | s = socket(PF_CAN, SOCK_RAW, CAN_RAW); |
| 249 | |
| 250 | and |
| 251 | |
| 252 | s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); |
| 253 | |
| 254 | respectively. After the successful creation of the socket, you would |
| 255 | normally use the bind(2) system call to bind the socket to a CAN |
| 256 | interface (which is different from TCP/IP due to different addressing |
| 257 | - see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM) |
| 258 | the socket, you can read(2) and write(2) from/to the socket or use |
| 259 | send(2), sendto(2), sendmsg(2) and the recv* counterpart operations |
| 260 | on the socket as usual. There are also CAN specific socket options |
| 261 | described below. |
| 262 | |
| 263 | The basic CAN frame structure and the sockaddr structure are defined |
| 264 | in include/linux/can.h: |
| 265 | |
| 266 | struct can_frame { |
| 267 | canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ |
| 268 | __u8 can_dlc; /* data length code: 0 .. 8 */ |
| 269 | __u8 data[8] __attribute__((aligned(8))); |
| 270 | }; |
| 271 | |
| 272 | The alignment of the (linear) payload data[] to a 64bit boundary |
| 273 | allows the user to define own structs and unions to easily access the |
| 274 | CAN payload. There is no given byteorder on the CAN bus by |
| 275 | default. A read(2) system call on a CAN_RAW socket transfers a |
| 276 | struct can_frame to the user space. |
| 277 | |
| 278 | The sockaddr_can structure has an interface index like the |
| 279 | PF_PACKET socket, that also binds to a specific interface: |
| 280 | |
| 281 | struct sockaddr_can { |
| 282 | sa_family_t can_family; |
| 283 | int can_ifindex; |
| 284 | union { |
Oliver Hartkopp | 56690c2 | 2008-04-15 00:46:38 -0700 | [diff] [blame] | 285 | /* transport protocol class address info (e.g. ISOTP) */ |
| 286 | struct { canid_t rx_id, tx_id; } tp; |
| 287 | |
| 288 | /* reserved for future CAN protocols address information */ |
Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 289 | } can_addr; |
| 290 | }; |
| 291 | |
| 292 | To determine the interface index an appropriate ioctl() has to |
| 293 | be used (example for CAN_RAW sockets without error checking): |
| 294 | |
| 295 | int s; |
| 296 | struct sockaddr_can addr; |
| 297 | struct ifreq ifr; |
| 298 | |
| 299 | s = socket(PF_CAN, SOCK_RAW, CAN_RAW); |
| 300 | |
| 301 | strcpy(ifr.ifr_name, "can0" ); |
| 302 | ioctl(s, SIOCGIFINDEX, &ifr); |
| 303 | |
| 304 | addr.can_family = AF_CAN; |
| 305 | addr.can_ifindex = ifr.ifr_ifindex; |
| 306 | |
| 307 | bind(s, (struct sockaddr *)&addr, sizeof(addr)); |
| 308 | |
| 309 | (..) |
| 310 | |
| 311 | To bind a socket to all(!) CAN interfaces the interface index must |
| 312 | be 0 (zero). In this case the socket receives CAN frames from every |
| 313 | enabled CAN interface. To determine the originating CAN interface |
| 314 | the system call recvfrom(2) may be used instead of read(2). To send |
| 315 | on a socket that is bound to 'any' interface sendto(2) is needed to |
| 316 | specify the outgoing interface. |
| 317 | |
| 318 | Reading CAN frames from a bound CAN_RAW socket (see above) consists |
| 319 | of reading a struct can_frame: |
| 320 | |
| 321 | struct can_frame frame; |
| 322 | |
| 323 | nbytes = read(s, &frame, sizeof(struct can_frame)); |
| 324 | |
| 325 | if (nbytes < 0) { |
| 326 | perror("can raw socket read"); |
| 327 | return 1; |
| 328 | } |
| 329 | |
Matt LaPlante | 19f5946 | 2009-04-27 15:06:31 +0200 | [diff] [blame^] | 330 | /* paranoid check ... */ |
Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 331 | if (nbytes < sizeof(struct can_frame)) { |
| 332 | fprintf(stderr, "read: incomplete CAN frame\n"); |
| 333 | return 1; |
| 334 | } |
| 335 | |
| 336 | /* do something with the received CAN frame */ |
| 337 | |
| 338 | Writing CAN frames can be done similarly, with the write(2) system call: |
| 339 | |
| 340 | nbytes = write(s, &frame, sizeof(struct can_frame)); |
| 341 | |
| 342 | When the CAN interface is bound to 'any' existing CAN interface |
| 343 | (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the |
| 344 | information about the originating CAN interface is needed: |
| 345 | |
| 346 | struct sockaddr_can addr; |
| 347 | struct ifreq ifr; |
| 348 | socklen_t len = sizeof(addr); |
| 349 | struct can_frame frame; |
| 350 | |
| 351 | nbytes = recvfrom(s, &frame, sizeof(struct can_frame), |
| 352 | 0, (struct sockaddr*)&addr, &len); |
| 353 | |
| 354 | /* get interface name of the received CAN frame */ |
| 355 | ifr.ifr_ifindex = addr.can_ifindex; |
| 356 | ioctl(s, SIOCGIFNAME, &ifr); |
| 357 | printf("Received a CAN frame from interface %s", ifr.ifr_name); |
| 358 | |
| 359 | To write CAN frames on sockets bound to 'any' CAN interface the |
| 360 | outgoing interface has to be defined certainly. |
| 361 | |
| 362 | strcpy(ifr.ifr_name, "can0"); |
| 363 | ioctl(s, SIOCGIFINDEX, &ifr); |
| 364 | addr.can_ifindex = ifr.ifr_ifindex; |
| 365 | addr.can_family = AF_CAN; |
| 366 | |
| 367 | nbytes = sendto(s, &frame, sizeof(struct can_frame), |
| 368 | 0, (struct sockaddr*)&addr, sizeof(addr)); |
| 369 | |
| 370 | 4.1 RAW protocol sockets with can_filters (SOCK_RAW) |
| 371 | |
| 372 | Using CAN_RAW sockets is extensively comparable to the commonly |
| 373 | known access to CAN character devices. To meet the new possibilities |
| 374 | provided by the multi user SocketCAN approach, some reasonable |
| 375 | defaults are set at RAW socket binding time: |
| 376 | |
| 377 | - The filters are set to exactly one filter receiving everything |
| 378 | - The socket only receives valid data frames (=> no error frames) |
| 379 | - The loopback of sent CAN frames is enabled (see chapter 3.2) |
| 380 | - The socket does not receive its own sent frames (in loopback mode) |
| 381 | |
| 382 | These default settings may be changed before or after binding the socket. |
| 383 | To use the referenced definitions of the socket options for CAN_RAW |
| 384 | sockets, include <linux/can/raw.h>. |
| 385 | |
| 386 | 4.1.1 RAW socket option CAN_RAW_FILTER |
| 387 | |
| 388 | The reception of CAN frames using CAN_RAW sockets can be controlled |
| 389 | by defining 0 .. n filters with the CAN_RAW_FILTER socket option. |
| 390 | |
| 391 | The CAN filter structure is defined in include/linux/can.h: |
| 392 | |
| 393 | struct can_filter { |
| 394 | canid_t can_id; |
| 395 | canid_t can_mask; |
| 396 | }; |
| 397 | |
| 398 | A filter matches, when |
| 399 | |
| 400 | <received_can_id> & mask == can_id & mask |
| 401 | |
| 402 | which is analogous to known CAN controllers hardware filter semantics. |
| 403 | The filter can be inverted in this semantic, when the CAN_INV_FILTER |
| 404 | bit is set in can_id element of the can_filter structure. In |
| 405 | contrast to CAN controller hardware filters the user may set 0 .. n |
| 406 | receive filters for each open socket separately: |
| 407 | |
| 408 | struct can_filter rfilter[2]; |
| 409 | |
| 410 | rfilter[0].can_id = 0x123; |
| 411 | rfilter[0].can_mask = CAN_SFF_MASK; |
| 412 | rfilter[1].can_id = 0x200; |
| 413 | rfilter[1].can_mask = 0x700; |
| 414 | |
| 415 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); |
| 416 | |
| 417 | To disable the reception of CAN frames on the selected CAN_RAW socket: |
| 418 | |
| 419 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); |
| 420 | |
| 421 | To set the filters to zero filters is quite obsolete as not read |
| 422 | data causes the raw socket to discard the received CAN frames. But |
| 423 | having this 'send only' use-case we may remove the receive list in the |
| 424 | Kernel to save a little (really a very little!) CPU usage. |
| 425 | |
| 426 | 4.1.2 RAW socket option CAN_RAW_ERR_FILTER |
| 427 | |
| 428 | As described in chapter 3.4 the CAN interface driver can generate so |
| 429 | called Error Frames that can optionally be passed to the user |
| 430 | application in the same way as other CAN frames. The possible |
| 431 | errors are divided into different error classes that may be filtered |
| 432 | using the appropriate error mask. To register for every possible |
| 433 | error condition CAN_ERR_MASK can be used as value for the error mask. |
| 434 | The values for the error mask are defined in linux/can/error.h . |
| 435 | |
| 436 | can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF ); |
| 437 | |
| 438 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, |
| 439 | &err_mask, sizeof(err_mask)); |
| 440 | |
| 441 | 4.1.3 RAW socket option CAN_RAW_LOOPBACK |
| 442 | |
| 443 | To meet multi user needs the local loopback is enabled by default |
| 444 | (see chapter 3.2 for details). But in some embedded use-cases |
| 445 | (e.g. when only one application uses the CAN bus) this loopback |
| 446 | functionality can be disabled (separately for each socket): |
| 447 | |
| 448 | int loopback = 0; /* 0 = disabled, 1 = enabled (default) */ |
| 449 | |
| 450 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback)); |
| 451 | |
| 452 | 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS |
| 453 | |
| 454 | When the local loopback is enabled, all the sent CAN frames are |
| 455 | looped back to the open CAN sockets that registered for the CAN |
| 456 | frames' CAN-ID on this given interface to meet the multi user |
| 457 | needs. The reception of the CAN frames on the same socket that was |
| 458 | sending the CAN frame is assumed to be unwanted and therefore |
| 459 | disabled by default. This default behaviour may be changed on |
| 460 | demand: |
| 461 | |
| 462 | int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */ |
| 463 | |
| 464 | setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, |
| 465 | &recv_own_msgs, sizeof(recv_own_msgs)); |
| 466 | |
| 467 | 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) |
| 468 | 4.3 connected transport protocols (SOCK_SEQPACKET) |
| 469 | 4.4 unconnected transport protocols (SOCK_DGRAM) |
| 470 | |
| 471 | |
| 472 | 5. Socket CAN core module |
| 473 | ------------------------- |
| 474 | |
| 475 | The Socket CAN core module implements the protocol family |
| 476 | PF_CAN. CAN protocol modules are loaded by the core module at |
| 477 | runtime. The core module provides an interface for CAN protocol |
| 478 | modules to subscribe needed CAN IDs (see chapter 3.1). |
| 479 | |
| 480 | 5.1 can.ko module params |
| 481 | |
| 482 | - stats_timer: To calculate the Socket CAN core statistics |
| 483 | (e.g. current/maximum frames per second) this 1 second timer is |
| 484 | invoked at can.ko module start time by default. This timer can be |
Matt LaPlante | d919588 | 2008-07-25 19:45:33 -0700 | [diff] [blame] | 485 | disabled by using stattimer=0 on the module commandline. |
Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 486 | |
| 487 | - debug: (removed since SocketCAN SVN r546) |
| 488 | |
| 489 | 5.2 procfs content |
| 490 | |
| 491 | As described in chapter 3.1 the Socket CAN core uses several filter |
| 492 | lists to deliver received CAN frames to CAN protocol modules. These |
| 493 | receive lists, their filters and the count of filter matches can be |
| 494 | checked in the appropriate receive list. All entries contain the |
| 495 | device and a protocol module identifier: |
| 496 | |
| 497 | foo@bar:~$ cat /proc/net/can/rcvlist_all |
| 498 | |
| 499 | receive list 'rx_all': |
| 500 | (vcan3: no entry) |
| 501 | (vcan2: no entry) |
| 502 | (vcan1: no entry) |
| 503 | device can_id can_mask function userdata matches ident |
| 504 | vcan0 000 00000000 f88e6370 f6c6f400 0 raw |
| 505 | (any: no entry) |
| 506 | |
| 507 | In this example an application requests any CAN traffic from vcan0. |
| 508 | |
| 509 | rcvlist_all - list for unfiltered entries (no filter operations) |
| 510 | rcvlist_eff - list for single extended frame (EFF) entries |
| 511 | rcvlist_err - list for error frames masks |
| 512 | rcvlist_fil - list for mask/value filters |
| 513 | rcvlist_inv - list for mask/value filters (inverse semantic) |
| 514 | rcvlist_sff - list for single standard frame (SFF) entries |
| 515 | |
| 516 | Additional procfs files in /proc/net/can |
| 517 | |
| 518 | stats - Socket CAN core statistics (rx/tx frames, match ratios, ...) |
| 519 | reset_stats - manual statistic reset |
| 520 | version - prints the Socket CAN core version and the ABI version |
| 521 | |
| 522 | 5.3 writing own CAN protocol modules |
| 523 | |
| 524 | To implement a new protocol in the protocol family PF_CAN a new |
| 525 | protocol has to be defined in include/linux/can.h . |
| 526 | The prototypes and definitions to use the Socket CAN core can be |
| 527 | accessed by including include/linux/can/core.h . |
| 528 | In addition to functions that register the CAN protocol and the |
| 529 | CAN device notifier chain there are functions to subscribe CAN |
| 530 | frames received by CAN interfaces and to send CAN frames: |
| 531 | |
| 532 | can_rx_register - subscribe CAN frames from a specific interface |
| 533 | can_rx_unregister - unsubscribe CAN frames from a specific interface |
| 534 | can_send - transmit a CAN frame (optional with local loopback) |
| 535 | |
| 536 | For details see the kerneldoc documentation in net/can/af_can.c or |
| 537 | the source code of net/can/raw.c or net/can/bcm.c . |
| 538 | |
| 539 | 6. CAN network drivers |
| 540 | ---------------------- |
| 541 | |
| 542 | Writing a CAN network device driver is much easier than writing a |
| 543 | CAN character device driver. Similar to other known network device |
| 544 | drivers you mainly have to deal with: |
| 545 | |
| 546 | - TX: Put the CAN frame from the socket buffer to the CAN controller. |
| 547 | - RX: Put the CAN frame from the CAN controller to the socket buffer. |
| 548 | |
| 549 | See e.g. at Documentation/networking/netdevices.txt . The differences |
| 550 | for writing CAN network device driver are described below: |
| 551 | |
| 552 | 6.1 general settings |
| 553 | |
| 554 | dev->type = ARPHRD_CAN; /* the netdevice hardware type */ |
| 555 | dev->flags = IFF_NOARP; /* CAN has no arp */ |
| 556 | |
| 557 | dev->mtu = sizeof(struct can_frame); |
| 558 | |
| 559 | The struct can_frame is the payload of each socket buffer in the |
| 560 | protocol family PF_CAN. |
| 561 | |
| 562 | 6.2 local loopback of sent frames |
| 563 | |
| 564 | As described in chapter 3.2 the CAN network device driver should |
| 565 | support a local loopback functionality similar to the local echo |
| 566 | e.g. of tty devices. In this case the driver flag IFF_ECHO has to be |
| 567 | set to prevent the PF_CAN core from locally echoing sent frames |
| 568 | (aka loopback) as fallback solution: |
| 569 | |
| 570 | dev->flags = (IFF_NOARP | IFF_ECHO); |
| 571 | |
| 572 | 6.3 CAN controller hardware filters |
| 573 | |
| 574 | To reduce the interrupt load on deep embedded systems some CAN |
| 575 | controllers support the filtering of CAN IDs or ranges of CAN IDs. |
| 576 | These hardware filter capabilities vary from controller to |
| 577 | controller and have to be identified as not feasible in a multi-user |
| 578 | networking approach. The use of the very controller specific |
| 579 | hardware filters could make sense in a very dedicated use-case, as a |
| 580 | filter on driver level would affect all users in the multi-user |
| 581 | system. The high efficient filter sets inside the PF_CAN core allow |
| 582 | to set different multiple filters for each socket separately. |
| 583 | Therefore the use of hardware filters goes to the category 'handmade |
| 584 | tuning on deep embedded systems'. The author is running a MPC603e |
| 585 | @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus |
| 586 | load without any problems ... |
| 587 | |
Oliver Hartkopp | e5d2304 | 2008-09-23 14:53:14 -0700 | [diff] [blame] | 588 | 6.4 The virtual CAN driver (vcan) |
| 589 | |
| 590 | Similar to the network loopback devices, vcan offers a virtual local |
| 591 | CAN interface. A full qualified address on CAN consists of |
| 592 | |
| 593 | - a unique CAN Identifier (CAN ID) |
| 594 | - the CAN bus this CAN ID is transmitted on (e.g. can0) |
| 595 | |
| 596 | so in common use cases more than one virtual CAN interface is needed. |
| 597 | |
| 598 | The virtual CAN interfaces allow the transmission and reception of CAN |
| 599 | frames without real CAN controller hardware. Virtual CAN network |
| 600 | devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ... |
| 601 | When compiled as a module the virtual CAN driver module is called vcan.ko |
| 602 | |
| 603 | Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel |
| 604 | netlink interface to create vcan network devices. The creation and |
| 605 | removal of vcan network devices can be managed with the ip(8) tool: |
| 606 | |
| 607 | - Create a virtual CAN network interface: |
| 608 | ip link add type vcan |
| 609 | |
| 610 | - Create a virtual CAN network interface with a specific name 'vcan42': |
| 611 | ip link add dev vcan42 type vcan |
| 612 | |
| 613 | - Remove a (virtual CAN) network interface 'vcan42': |
| 614 | ip link del vcan42 |
| 615 | |
| 616 | The tool 'vcan' from the SocketCAN SVN repository on BerliOS is obsolete. |
| 617 | |
| 618 | Virtual CAN network device creation in older Kernels: |
| 619 | In Linux Kernel versions < 2.6.24 the vcan driver creates 4 vcan |
| 620 | netdevices at module load time by default. This value can be changed |
| 621 | with the module parameter 'numdev'. E.g. 'modprobe vcan numdev=8' |
| 622 | |
| 623 | 6.5 currently supported CAN hardware |
Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 624 | |
| 625 | On the project website http://developer.berlios.de/projects/socketcan |
| 626 | there are different drivers available: |
| 627 | |
| 628 | vcan: Virtual CAN interface driver (if no real hardware is available) |
| 629 | sja1000: Philips SJA1000 CAN controller (recommended) |
| 630 | i82527: Intel i82527 CAN controller |
| 631 | mscan: Motorola/Freescale CAN controller (e.g. inside SOC MPC5200) |
| 632 | ccan: CCAN controller core (e.g. inside SOC h7202) |
| 633 | slcan: For a bunch of CAN adaptors that are attached via a |
| 634 | serial line ASCII protocol (for serial / USB adaptors) |
| 635 | |
| 636 | Additionally the different CAN adaptors (ISA/PCI/PCMCIA/USB/Parport) |
| 637 | from PEAK Systemtechnik support the CAN netdevice driver model |
| 638 | since Linux driver v6.0: http://www.peak-system.com/linux/index.htm |
| 639 | |
| 640 | Please check the Mailing Lists on the berlios OSS project website. |
| 641 | |
Oliver Hartkopp | e5d2304 | 2008-09-23 14:53:14 -0700 | [diff] [blame] | 642 | 6.6 todo |
Oliver Hartkopp | f7ab97f | 2007-11-16 16:09:28 -0800 | [diff] [blame] | 643 | |
| 644 | The configuration interface for CAN network drivers is still an open |
| 645 | issue that has not been finalized in the socketcan project. Also the |
| 646 | idea of having a library module (candev.ko) that holds functions |
| 647 | that are needed by all CAN netdevices is not ready to ship. |
| 648 | Your contribution is welcome. |
| 649 | |
| 650 | 7. Credits |
| 651 | ---------- |
| 652 | |
| 653 | Oliver Hartkopp (PF_CAN core, filters, drivers, bcm) |
| 654 | Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) |
| 655 | Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) |
| 656 | Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews) |
| 657 | Robert Schwebel (design reviews, PTXdist integration) |
| 658 | Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) |
| 659 | Benedikt Spranger (reviews) |
| 660 | Thomas Gleixner (LKML reviews, coding style, posting hints) |
| 661 | Andrey Volkov (kernel subtree structure, ioctls, mscan driver) |
| 662 | Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) |
| 663 | Klaus Hitschler (PEAK driver integration) |
| 664 | Uwe Koppe (CAN netdevices with PF_PACKET approach) |
| 665 | Michael Schulze (driver layer loopback requirement, RT CAN drivers review) |