kernel/2.6/Documentation/networking/can.txt

   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 loopback
  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.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
  22     4.3 connected transport protocols (SOCK_SEQPACKET)
  23     4.4 unconnected transport protocols (SOCK_DGRAM)
  24
  25   5 Socket CAN core module
  26     5.1 can.ko module params
  27     5.2 procfs content
  28     5.3 writing own CAN protocol modules
  29
  30   6 CAN network drivers
  31     6.1 general settings
  32     6.2 loopback
  33     6.3 CAN controller hardware filters
  34     6.4 currently supported CAN hardware
  35     6.5 todo
  36
  37   7 Credits
  38
  39 ============================================================================
  40
  41 1. Overview / What is Socket CAN
  42 --------------------------------
  43
  44 The socketcan package is an implementation of CAN protocols
  45 (Controller Area Network) for Linux.  CAN is a networking technology
  46 which has wide-spread use in automation, embedded devices, and
  47 automotive fields.  While there have been other CAN implementations
  48 for Linux based on character devices, Socket CAN uses the Berkeley
  49 socket API, the Linux network stack and implements the CAN device
  50 drivers as network interfaces.  The CAN socket API has been designed
  51 as similar as possible to the TCP/IP protocols to allow programmers,
  52 familiar with network programming, to easily learn how to use CAN
  53 sockets.
  54
  55 2. Motivation / Why using the socket API
  56 ----------------------------------------
  57
  58 There have been CAN implementations for Linux before Socket CAN so the
  59 question arises, why we have started another project.  Most existing
  60 implementations come as a device driver for some CAN hardware, they
  61 are based on character devices and provide comparatively little
  62 functionality.  Usually, there is only a hardware-specific device
  63 driver which provides a character device interface to send and
  64 receive raw CAN frames, directly to/from the controller hardware.
  65 Queueing of frames and higher-level transport protocols like ISO-TP
  66 have to be implemented in user space applications.  Also, most
  67 character-device implementations support only one single process to
  68 open the device at a time, similar to a serial interface.  Exchanging
  69 the CAN controller requires employment of another device driver and
  70 often the need for adaption of large parts of the application to the
  71 new driver's API.
  72
  73 Socket CAN was designed to overcome all of these limitations.  A new
  74 protocol family has been implemented which provides a socket interface
  75 to user space applications and which builds upon the Linux network
  76 layer, so to use all of the provided queueing functionality.  Device
  77 drivers for CAN controller hardware register itself with the Linux
  78 network layer as a network device, so that CAN frames from the
  79 controller can be passed up to the network layer and on to the CAN
  80 protocol family module and also vice-versa.  Also, the protocol family
  81 module provides an API for transport protocol modules to register, so
  82 that any number of transport protocols can be loaded or unloaded
  83 dynamically.  In fact, the can core module alone does not provide any
  84 protocol and can not be used without loading at least one additional
  85 protocol module.  Multiple sockets can be opened at the same time,
  86 on different or the same protocol module and they can listen/send
  87 frames on different or the same CAN IDs.  Several sockets listening on
  88 the same interface for frames with the same CAN ID are all passed the
  89 same received matching CAN frames.  An application wishing to
  90 communicate using a specific transport protocol, e.g. ISO-TP, just
  91 selects that protocol when opening the socket, and then can read and
  92 write application data byte streams, without having to deal with
  93 CAN-IDs, frames, etc.
  94
  95 Similar functionality visible from user-space could be provided by a
  96 character decive, too, but this would lead to a technically inelegant
  97 solution for a couple of reasons:
  98
  99 * Intricate usage.  Instead of passing a protocol argument to
 100   socket(2) and using bind(2) to select a CAN interface and CAN ID, an
 101   application would have to do all these operations using ioctl(2)s.
 102
 103 * Code duplication.  A character device cannot make use of the Linux
 104   network queueing code, so all that code would have to be duplicated
 105   for CAN networking.
 106
 107 * Abstraction.  In most existing character-device implementations, the
 108   hardware-specific device driver for a CAN controller directly
 109   provides the character device for the application to work with.
 110   This is at least very unusual in Unix systems, for both, char and
 111   block devices.  For example you don't have a character device for a
 112   certain UART of a serial interface, a certain sound chip in your
 113   computer, a SCSI or IDE controller providing access to your hard
 114   disk or tape streamer device.  Instead, you have abstraction layers
 115   which provide a unified character or block device interface to the
 116   application on the one hand, and a interface for hardware-specific
 117   device drivers on the other hand.  These abstractions are provided
 118   by subsystems like the tty layer, the audio subsystem or the SCSI
 119   and IDE subsystems for the devices mentioned above.
 120
 121   The easiest way to implement a CAN device driver is as a character
 122   without such a (complete) abstraction layer, as is done by most
 123   existing drivers.  The right way, however, would be to add such a
 124   layer with all the functionality like registering for certain CAN
 125   IDs, supporting several open file descriptors and (de)multplexing
 126   CAN frames between them, (sophisticated) queueing of CAN frames, and
 127   providing an API for device driver to register with.  However, then
 128   it would be no more difficult, or may be even easier, to use the
 129   networking framework provided by the Linux kernel, and this is what
 130   Socket CAN does.
 131
 132   The use of the networking framework of the Linux kernel is just the
 133   natural and most appropriate way to implement CAN for Linux.
 134
 135 3. Socket CAN concept
 136 ---------------------
 137
 138   As described in chapter 2 it is the main goal of Socket CAN to
 139   provide a socket interface to user space applications which builds
 140   upon the Linux networklayer. In opposite to the commonly known
 141   TCP/IP and ethernet networking the CAN bus is a broadcast-only(!)
 142   medium that has no MAC-layer adressing like ethernet. The CAN-identifier
 143   (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
 144   have to be choosen unique on the bus. When designing a CAN-ECU
 145   network the CAN-IDs are mapped to be sent by a specific ECU.
 146   For this reason a CAN-ID can be treatened best as a kind of source address.
 147
 148   3.1 receive lists
 149
 150   The network transparent access of multiple applications leads to the
 151   problem that different applications may be interrested in the same
 152   CAN-IDs from the same CAN network interface. The Socket CAN core
 153   module - which implements the protocol family CAN - provides several
 154   high efficient receive lists for this reason. If e.g. a user space
 155   application opens a CAN RAW socket, the raw protocol module itself
 156   requests the (range of) CAN-IDs from the Socket CAN core that are
 157   requested by the user. The subscription and unsubscription of
 158   CAN-IDs can be done for specific CAN interfaces or for all(!) known
 159   CAN interfaces with the can_rx_(un)register() functions provided to
 160   CAN protocol modules by the SocketCAN core (see chapter 5).
 161   To optimize the CPU usage at runtime the receive lists are split up
 162   into several specific lists per device that match the requested
 163   filter complexity for a given use-case.
 164
 165   3.2 loopback
 166
 167   As known from other networking concepts the data exchanging
 168   applications may run on the same or different nodes without any
 169   change (except if the according addressing information):
 170
 171          ___   ___   ___                   _______   ___
 172         | _ | | _ | | _ |                 | _   _ | | _ |
 173         ||A|| ||B|| ||C||                 ||A| |B|| ||C||
 174         |___| |___| |___|                 |_______| |___|
 175           |     |     |                       |       |
 176         -----------------(1)- CAN bus -(2)---------------
 177
 178   To ensure that application A receives the same information in the
 179   expample (2) as it would receive in example (1) there is need for
 180   some kind of local loopback on the appropriate node.
 181
 182   The Linux network devices (by default) just can handle the
 183   transmission and receiption of media dependend frames. Due to the
 184   arbritration on the CAN bus the transmission of a low prio CAN-ID
 185   may be delayed from the receipition of a high prio CAN frame. To
 186   reflect the correct* traffic on the node the loopback of the sent
 187   data has to be performed right after a successful transmission. If
 188   the CAN network interface is not capable to perform the loopback for
 189   some reason the SocketCAN core can do this task as a fallback solution.
 190   See chapter 6.2 for details (recommended).
 191
 192   The loopback functionality is enabled by default to reflect standard
 193   networking behaviour for CAN applications. Due to some requests from
 194   the RT-SocketCAN group the loopback optionally may be disabled for each
 195   seperate socket. See sockopts from the CAN RAW sockets in chapter 4.1 .
 196
 197   * = you really like to have this when you're running analyser tools
 198       like 'candump' or 'cansniffer' on the (same) node.
 199
 200   3.3 network security issues (capabilities)
 201
 202   The Controller Area Network is a local field bus transmitting only
 203   broadcast messages without any routing and security concepts.
 204   In the majority of cases the user application has to deal with
 205   raw CAN frames. Therefore it might be reasonable NOT to restrict
 206   the CAN access only to the user root, as known from other networks.
 207   Since the currently implemented CAN_RAW and CAN_BCM sockets can only
 208   send and receive frames to/from CAN interfaces it does not affect
 209   security of others networks to allow all users to access the CAN.
 210   To enable non-root users to access CAN_RAW and CAN_BCM protocol
 211   sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be
 212   selected at kernel compile time.
 213
 214   3.4 network problem notifications
 215
 216   The use of the CAN bus may lead to several problems on the physical
 217   and media access control layer. Detecting and logging of these lower
 218   layer problems is a vital requirement for CAN users to identify
 219   hardware issues on the physical transceiver layer as well as
 220   arbitration problems and error frames caused by the different
 221   ECUs. The occurance of detected errors are important for diagnosis
 222   and have to be logged together with the exact timestamp. For this
 223   reason the CAN interface driver can generate so called Error Frames
 224   that can optionally be passed to the user application on the same
 225   way like other CAN frames. Whenever an error on the physical layer
 226   or the MAC layer is detected (e.g. by the CAN controller) the driver
 227   creates an appropriate error frame. Error frames can be requested by
 228   the user application using the common CAN filter mechanisms. Inside
 229   this filter definition the (interrested) type of errors may be
 230   selected. The receiption of error frames is disabled by default.
 231
 232 4. How to use Socket CAN
 233 ------------------------
 234
 235   Like TCP/IP, you first need to open a socket for communicating over a
 236   CAN network. Since Socket CAN implements a new protocol family, you
 237   need to pass PF_CAN as the first argument to the socket(2) system
 238   call. Currently, there are two CAN protocols to choose from, the raw
 239   socket protocol and the broadcast manager (BCM). So to open a socket,
 240   you would write
 241
 242     s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
 243
 244   and
 245
 246     s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
 247
 248   respectively.  After the successful creation of the socket, you would
 249   normally use the bind(2) system call to bind the socket to a CAN
 250   interface (which is different to TCP/IP due to different addressing
 251   - see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM)
 252   the socket, you can read(2) and write(2) from/to the socket or use
 253   send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
 254   on the socket as usual. There are also CAN specific socket options
 255   described below.
 256
 257   The basic CAN frame structure and the sockaddr structure are defined
 258   in include/linux/can.h:
 259
 260     struct can_frame {
 261             canid_t can_id;  /* 32 bit CAN_ID + EFF/RTR/ERR flags */
 262             __u8    can_dlc; /* data length code: 0 .. 8 */
 263             __u8    data[8] __attribute__((aligned(8)));
 264     };
 265
 266   The alignment of the (linear) payload data[] to a 64bit boundary
 267   allows the user to define own structs and unions to easily access the
 268   CAN payload. There is no given byteorder on the CAN bus by
 269   default. A read(2) system call on a CAN_RAW socket transfers a
 270   struct can_frame to the user space.
 271
 272   The sockaddr_can structure has an interface index analogue to the
 273   PF_PACKET socket, that also binds to a specific interface:
 274
 275     struct sockaddr_can {
 276             sa_family_t can_family;
 277             int         can_ifindex;
 278             union {
 279                     struct { canid_t rx_id, tx_id; } tp16;
 280                     struct { canid_t rx_id, tx_id; } tp20;
 281                     struct { canid_t rx_id, tx_id; } mcnet;
 282                     struct { canid_t rx_id, tx_id; } isotp;
 283                     struct { int     lcu,   type;  } bap;
 284             } can_addr;
 285     };
 286
 287   To determine the interface index the an appropriate ioctl() has to
 288   be used (example for CAN_RAW sockets without error checking):
 289
 290     int s;
 291     struct sockaddr_can addr;
 292     struct ifreq ifr;
 293
 294     s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
 295
 296     strcpy(ifr.ifr_name, "can0" );
 297     ioctl(s, SIOCGIFINDEX, &ifr);
 298
 299     addr.can_family = AF_CAN;
 300     addr.can_ifindex = ifr.ifr_ifindex;
 301
 302     bind(s, (struct sockaddr *)&addr, sizeof(addr));
 303
 304     (..)
 305
 306   To bind a socket to all(!) CAN interfaces the interface index might
 307   be 0 (zero). In this case the socket receives CAN frames from every
 308   enabled CAN interface. To determine the originating CAN interface
 309   the system call recvfrom(2) may be used instead of read(2). To send
 310   on a socket that is bound to 'any' interface sendto(2) is needed to
 311   specify the outgoing interface.
 312
 313   4.1 RAW protocol sockets with can_filters (SOCK_RAW)
 314   4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
 315   4.3 connected transport protocols (SOCK_SEQPACKET)
 316   4.4 unconnected transport protocols (SOCK_DGRAM)
 317
 318
 319 5. Socket CAN core module
 320 -------------------------
 321
 322   The Socket CAN core module implements the protocol family
 323   PF_CAN. CAN protocol modules are loaded by the core module at
 324   runtime. The core module provides an interface for CAN protocol
 325   modules to subscribe needed CAN IDs (see chapter 3.1).
 326
 327   5.1 can.ko module params
 328
 329   - stats_timer: To calculate the Socket CAN core statistics
 330     (e.g. current/maximum frames per second) this 1 second timer is
 331     invoked at can.ko module start time by default. This timer can be
 332     disabled giving stattimer=0 on the module comandline.
 333
 334   - debug: When the Kconfig option CONFIG_CAN_DEBUG_CORE is set at
 335     compile time, the debug output code is compiled into the module.
 336     debug = 0x01 => print general debug information
 337     debug = 0x02 => print content of processed CAN frames
 338     debug = 0x04 => print content of processed socket buffers
 339
 340     It is possible or have ORed values e.g. 3 or 7 for an output off
 341     all available debug information. Using 0x02 and 0x04 may flood
 342     your kernel log - so be careful.
 343
 344   5.2 procfs content
 345   5.3 writing own CAN protocol modules
 346
 347 6. CAN network drivers
 348 ----------------------
 349
 350   Writing a CAN network device driver is much easier than writing a
 351   CAN character device driver. Analogue to other know network device
 352   drivers you mainly have to deal with:
 353
 354   - TX: Put the CAN frame from the socket buffer to the CAN controller.
 355   - RX: Put the CAN frame from the CAN controller to the socket buffer.
 356
 357   See e.g. at Documentation/networking/netdevices.txt . The differences
 358   for writing CAN network device driver are described below:
 359
 360   6.1 general settings
 361
 362     dev->type  = ARPHRD_CAN; /* the netdevice hardware type */
 363     dev->flags = IFF_NOARP; /* CAN has no arp */
 364
 365     dev->mtu   = sizeof(struct can_frame);
 366
 367   The struct can_frame is the payload of each socket buffer in the
 368   protocol family PF_CAN.
 369
 370   6.2 loopback
 371
 372   As described in chapter 3.2 the CAN network device driver should
 373   support a local loopback functionality. If so the driver flag
 374   IFF_LOOPBACK has to be set to omit the PF_CAN core to perform the
 375   loopback as fallback solution:
 376
 377     dev->flags = (IFF_NOARP | IFF_LOOPBACK);
 378
 379   6.3 CAN controller hardware filters
 380
 381   To reduce the interrupt load on deep embedded systems some CAN
 382   controllers support the filtering of CAN IDs or ranges of CAN IDs.
 383   These hardware filter capabilities vary from controller to
 384   controller and have to be identified as not feasible in a multi-user
 385   networking approach. The use of the very controller specific
 386   hardware filters could make sense in a very dedicated use-case, as a
 387   filter on driver level would affect all users in the multi-user
 388   system. The high efficient filter sets inside the PF_CAN core allow
 389   to set different multiple filters for each socket separately.
 390   Therefore the use of hardware filters goes to the category 'handmade
 391   tuning on deep embedded systems'. The author is running a MPC603e
 392   @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
 393   load without any problems ...
 394
 395   6.4 currently supported CAN hardware (May 2007)
 396
 397   On the project website http://developer.berlios.de/projects/socketcan
 398   there are different drivers available:
 399
 400     vcan:    Virtual CAN interface driver (if no real hardware is available)
 401     sja1000: Philips SJA1000 CAN controller (recommended)
 402     i82527:  Intel i82527 CAN controller
 403     mscan:   Motorola/Freescale CAN controller (e.g. inside SOC MPC5200)
 404     slcan:   For a bunch of CAN adaptors that are attached via a
 405              serial line ASCII protocol (for serial / USB adaptors)
 406
 407   Additionally the different CAN adaptors (ISA/PCI/PCMCIA/USB/Parport)
 408   from PEAK Systemtechnik support the CAN netdevice driver modell
 409   since Linux driver v6.0: http://www.peak-system.com/linux/index.htm
 410
 411   Please check the Mailing Lists on the berlios OSS project website.
 412
 413   6.5 todo (May 2007)
 414
 415   The configuration interface for CAN network drivers is still an open
 416   issue that has not been finalized in the socketcan project. Also the
 417   idea of having a library module (candev.ko) that holds functions
 418   that are needed by all CAN netdevices is not ready to ship.
 419   Your contribution is welcome.
 420
 421 7. Credits
 422 ----------
 423
 424   Oliver Hartkopp (PF_CAN core, filters, drivers, bcm)
 425   Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
 426   Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
 427   Wolfgang Grandegger (RT-SocketCAN core & drivers)
 428   Robert Schwebel (OSELAS integration)
 429   Marc Kleine-Budde (Kernel 2.6 cleanups, reviews, drivers)
 430   Benedikt Spranger (reviews)
 431   Thomas Gleixner (LKML reviews, coding style, posting hints)
 432   Andrey Volkov (kernel subtree structure, ioctls, mscan driver)
 433   Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
 434   Klaus Hitschler (PEAK driver integration)
 435   Uwe Koppe (CAN netdevices with PF_PACKET approach)
 436   Michael Schulze (driver layer loopback requirement, RT CAN drivers review)