kernel/2.6/Documentation/networking/can/overview.txt

   1 ============================================================================
   2
   3 overview.txt : introduction and general concepts
   4
   5 Part of the documentation for the socketCAN subsystem
   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 Socket CAN resources
  20
  21   5 Credits
  22
  23 ============================================================================
  24
  25 1. Overview / What is Socket CAN
  26 --------------------------------
  27
  28   The socketcan package is an implementation of CAN protocols
  29   (Controller Area Network) for Linux.  CAN is a networking technology
  30   which has widespread use in automation, embedded devices, and
  31   automotive fields.  While there have been other CAN implementations
  32   for Linux based on character devices, Socket CAN uses the Berkeley
  33   socket API, the Linux network stack and implements the CAN device
  34   drivers as network interfaces.  The CAN socket API has been designed
  35   as similar as possible to the TCP/IP protocols to allow programmers,
  36   familiar with network programming, to easily learn how to use CAN
  37   sockets.
  38
  39 2. Motivation / Why using the socket API
  40 ----------------------------------------
  41
  42   There have been CAN implementations for Linux before Socket CAN so the
  43   question arises, why we have started another project.  Most existing
  44   implementations come as a device driver for some CAN hardware, they
  45   are based on character devices and provide comparatively little
  46   functionality.  Usually, there is only a hardware-specific device
  47   driver which provides a character device interface to send and
  48   receive raw CAN frames, directly to/from the controller hardware.
  49   Queueing of frames and higher-level transport protocols like ISO-TP
  50   have to be implemented in user space applications.  Also, most
  51   character-device implementations support only one single process to
  52   open the device at a time, similar to a serial interface.  Exchanging
  53   the CAN controller requires employment of another device driver and
  54   often the need for adaption of large parts of the application to the
  55   new driver's API.
  56
  57   Socket CAN was designed to overcome all of these limitations.  A new
  58   protocol family has been implemented which provides a socket interface
  59   to user space applications and which builds upon the Linux network
  60   layer, so to use all of the provided queueing functionality.  A device
  61   driver for CAN controller hardware registers itself with the Linux
  62   network layer as a network device, so that CAN frames from the
  63   controller can be passed up to the network layer and on to the CAN
  64   protocol family module and also vice-versa.  Also, the protocol family
  65   module provides an API for transport protocol modules to register, so
  66   that any number of transport protocols can be loaded or unloaded
  67   dynamically.  In fact, the can core module alone does not provide any
  68   protocol and cannot be used without loading at least one additional
  69   protocol module.  Multiple sockets can be opened at the same time,
  70   on different or the same protocol module and they can listen/send
  71   frames on different or the same CAN IDs.  Several sockets listening on
  72   the same interface for frames with the same CAN ID are all passed the
  73   same received matching CAN frames.  An application wishing to
  74   communicate using a specific transport protocol, e.g. ISO-TP, just
  75   selects that protocol when opening the socket, and then can read and
  76   write application data byte streams, without having to deal with
  77   CAN-IDs, frames, etc.
  78
  79   Similar functionality visible from user-space could be provided by a
  80   character device, too, but this would lead to a technically inelegant
  81   solution for a couple of reasons:
  82
  83 * Intricate usage.  Instead of passing a protocol argument to
  84   socket(2) and using bind(2) to select a CAN interface and CAN ID, an
  85   application would have to do all these operations using ioctl(2)s.
  86
  87 * Code duplication.  A character device cannot make use of the Linux
  88   network queueing code, so all that code would have to be duplicated
  89   for CAN networking.
  90
  91 * Abstraction.  In most existing character-device implementations, the
  92   hardware-specific device driver for a CAN controller directly
  93   provides the character device for the application to work with.
  94   This is at least very unusual in Unix systems for both, char and
  95   block devices.  For example you don't have a character device for a
  96   certain UART of a serial interface, a certain sound chip in your
  97   computer, a SCSI or IDE controller providing access to your hard
  98   disk or tape streamer device.  Instead, you have abstraction layers
  99   which provide a unified character or block device interface to the
 100   application on the one hand, and a interface for hardware-specific
 101   device drivers on the other hand.  These abstractions are provided
 102   by subsystems like the tty layer, the audio subsystem or the SCSI
 103   and IDE subsystems for the devices mentioned above.
 104
 105   The easiest way to implement a CAN device driver is as a character
 106   device without such a (complete) abstraction layer, as is done by most
 107   existing drivers.  The right way, however, would be to add such a
 108   layer with all the functionality like registering for certain CAN
 109   IDs, supporting several open file descriptors and (de)multiplexing
 110   CAN frames between them, (sophisticated) queueing of CAN frames, and
 111   providing an API for device drivers to register with.  However, then
 112   it would be no more difficult, or may be even easier, to use the
 113   networking framework provided by the Linux kernel, and this is what
 114   Socket CAN does.
 115
 116   The use of the networking framework of the Linux kernel is just the
 117   natural and most appropriate way to implement CAN for Linux.
 118
 119 3. Socket CAN concept
 120 ---------------------
 121
 122   As described in chapter 2 it is the main goal of Socket CAN to
 123   provide a socket interface to user space applications which builds
 124   upon the Linux network layer. In contrast to the commonly known
 125   TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
 126   medium that has no MAC-layer addressing like ethernet. The CAN-identifier
 127   (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
 128   have to be chosen uniquely on the bus. When designing a CAN-ECU
 129   network the CAN-IDs are mapped to be sent by a specific ECU.
 130   For this reason a CAN-ID can be treated best as a kind of source address.
 131
 132   3.1 receive lists
 133
 134   The network transparent access of multiple applications leads to the
 135   problem that different applications may be interested in the same
 136   CAN-IDs from the same CAN network interface. The Socket CAN core
 137   module - which implements the protocol family CAN - provides several
 138   high efficient receive lists for this reason. If e.g. a user space
 139   application opens a CAN RAW socket, the raw protocol module itself
 140   requests the (range of) CAN-IDs from the Socket CAN core that are
 141   requested by the user. The subscription and unsubscription of
 142   CAN-IDs can be done for specific CAN interfaces or for all(!) known
 143   CAN interfaces with the can_rx_(un)register() functions provided to
 144   CAN protocol modules by the SocketCAN core (see can-core.txt).
 145   To optimize the CPU usage at runtime the receive lists are split up
 146   into several specific lists per device that match the requested
 147   filter complexity for a given use-case.
 148
 149   3.2 local loopback of sent frames
 150
 151   As known from other networking concepts the data exchanging
 152   applications may run on the same or different nodes without any
 153   change (except for the according addressing information):
 154
 155          ___   ___   ___                   _______   ___
 156         | _ | | _ | | _ |                 | _   _ | | _ |
 157         ||A|| ||B|| ||C||                 ||A| |B|| ||C||
 158         |___| |___| |___|                 |_______| |___|
 159           |     |     |                       |       |
 160         -----------------(1)- CAN bus -(2)---------------
 161
 162   To ensure that application A receives the same information in the
 163   example (2) as it would receive in example (1) there is need for
 164   some kind of local loopback of the sent CAN frames on the appropriate
 165   node.
 166
 167   The Linux network devices (by default) just can handle the
 168   transmission and reception of media dependent frames. Due to the
 169   arbitration on the CAN bus the transmission of a low prio CAN-ID
 170   may be delayed by the reception of a high prio CAN frame. To
 171   reflect the correct* traffic on the node the loopback of the sent
 172   data has to be performed right after a successful transmission. If
 173   the CAN network interface is not capable of performing the loopback for
 174   some reason the SocketCAN core can do this task as a fallback solution.
 175   See can-drivers.txt, chapter 1.2 for details (recommended).
 176
 177   The loopback functionality is enabled by default to reflect standard
 178   networking behaviour for CAN applications. Due to some requests from
 179   the RT-SocketCAN group the loopback optionally may be disabled for each
 180   separate socket. See sockopts from the CAN RAW sockets in can-raw.txt.
 181
 182   * = you really like to have this when you're running analyser tools
 183       like 'candump' or 'cansniffer' on the (same) node.
 184
 185   3.3 network security issues (capabilities)
 186
 187   The Controller Area Network is a local field bus transmitting only
 188   broadcast messages without any routing and security concepts.
 189   In the majority of cases the user application has to deal with
 190   raw CAN frames. Therefore it might be reasonable NOT to restrict
 191   the CAN access only to the user root, as known from other networks.
 192   Since the currently implemented CAN_RAW and CAN_BCM sockets can only
 193   send and receive frames to/from CAN interfaces it does not affect
 194   security of others networks to allow all users to access the CAN.
 195   To enable non-root users to access CAN_RAW and CAN_BCM protocol
 196   sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be
 197   selected at kernel compile time.
 198
 199   3.4 network problem notifications
 200
 201   The use of the CAN bus may lead to several problems on the physical
 202   and media access control layer. Detecting and logging of these lower
 203   layer problems is a vital requirement for CAN users to identify
 204   hardware issues on the physical transceiver layer as well as
 205   arbitration problems and error frames caused by the different
 206   ECUs. The occurrence of detected errors are important for diagnosis
 207   and have to be logged together with the exact timestamp. For this
 208   reason the CAN interface driver can generate so called Error Frames
 209   that can optionally be passed to the user application in the same
 210   way as other CAN frames. Whenever an error on the physical layer
 211   or the MAC layer is detected (e.g. by the CAN controller) the driver
 212   creates an appropriate error frame. Error frames can be requested by
 213   the user application using the common CAN filter mechanisms. Inside
 214   this filter definition the (interested) type of errors may be
 215   selected. The reception of error frames is disabled by default.
 216   The format of the CAN error frame is briefly decribed in the Linux
 217   header file "include/linux/can/error.h".
 218
 219 4. Socket CAN resources
 220 -----------------------
 221
 222   You can find further resources for Socket CAN like user space tools,
 223   support for old kernel versions, more drivers, mailing lists, etc.
 224   at the BerliOS OSS project website for Socket CAN:
 225
 226     http://developer.berlios.de/projects/socketcan
 227
 228   If you have questions, bug fixes, etc., don't hesitate to post them to
 229   the Socketcan-Users mailing list. But please search the archives first.
 230
 231 5. Credits
 232 ----------
 233
 234   Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
 235   Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
 236   Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
 237   Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews,
 238                        CAN device driver interface, MSCAN driver)
 239   Robert Schwebel (design reviews, PTXdist integration)
 240   Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
 241   Benedikt Spranger (reviews)
 242   Thomas Gleixner (LKML reviews, coding style, posting hints)
 243   Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
 244   Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
 245   Klaus Hitschler (PEAK driver integration)
 246   Uwe Koppe (CAN netdevices with PF_PACKET approach)
 247   Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
 248   Pavel Pisa (Bit-timing calculation)
 249   Sascha Hauer (SJA1000 platform driver)
 250   Sebastian Haas (SJA1000 EMS PCI driver)
 251   Markus Plessing (SJA1000 EMS PCI driver)
 252   Per Dalen (SJA1000 Kvaser PCI driver)
 253   Sam Ravnborg (reviews, coding style, kbuild help)
 254