README

   1 $Id$
   2
   3
   4 1. What is Socket CAN
   5
   6 The socketcan package is an implementation of CAN protocols
   7 (Controller Area Network) for Linux.  CAN is a networking technology
   8 which has wide-spread use in automation, embedded devices, and
   9 automotive fields.  While there have been other CAN implementations
  10 for Linux based on character devices, Socket CAN uses the Berkeley
  11 socket API, the Linux network stack and implements the CAN device
  12 drivers as network interfaces.  The CAN socket API has been designed
  13 as similar as possible to the TCP/IP protocols to allow programmers,
  14 familiar with network programming, to easily learn how to use CAN
  15 sockets.
  16
  17
  18 2. How to compile and install
  19
  20 2a. Compile and install the kernel modules
  21
  22 To compile the Socket CAN sources, you need the Linux kernel sources
  23 for the kernel running on your target system, configured like that
  24 kernel.
  25
  26 Then you should chdir to the socketcan source directory and call make
  27 to compile all the sources:
  28
  29     $ cd socketcan/kernel/<version>
  30     $ make KERNELDIR=<kernel-source>
  31
  32 where version is 2.4 or 2.6, depending on the kernel version you run
  33 on your target, and <kernel-source> should be replaced by the
  34 directory where your target kernel source is installed.  If you
  35 compile on the target machine and the configured kernel is in
  36 /usr/src/linux, you can omit the KERNELDIR argument to make.
  37
  38 Not only the kernel version and configuration must match the kernel
  39 runnung on your target system, but also the version of GCC used to
  40 compile the source code.  So you may have to write
  41
  42     $ make KERNELDIR=<kernel-source> CC=gcc-<gcc-version>
  43
  44 or something like that to call the appropriate compiler.
  45
  46 [ NOTE:  currently, there is no Makefile in socketcan/kernel/<version>
  47          you have to descend into each subdirectory and run make there.
  48 ]
  49
  50 To install the kernel modules, you must create a directory to install
  51 the modules in, copy the kernel modules to that directory and run
  52 depmod(8) to let modprobe find the newly installed modules:
  53
  54     # mkdir /lib/modules/$(uname -r)/socketcan
  55     # find -name \*.ko | xargs install -t /lib/modules/$(uname -r)/socketcan
  56     # depmod $(uname -r)
  57
  58 2b. Compile and install the user space utilities and test programs
  59
  60 ...
  61
  62 [ Run make in can-utils and test dirs and cp binaries to /usr/local ]
  63
  64
  65 3. How to use socketcan
  66
  67 Like TCP/IP, you first need to open a socket for communicating over a
  68 CAN network.  Since Socket CAN implements a new protocol family, you
  69 need to pass PF_CAN as the first argument to the socket(2) system
  70 call.  Currently, there are two CAN protocols to choose from, the raw
  71 socket protocol and the broadcast manager (BCM).  So to open a socket,
  72 you would write
  73
  74     s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
  75
  76 and
  77
  78     s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
  79
  80 respectively.  After opening, you would normally use the bind(2)
  81 system call to bind to a CAN ID, then you can read(2) and write(2)
  82 from/to the socket or use send(2), sendto(2), sendmsg(2) and the recv*
  83 counterpart operations on the socket as usual.  There are also CAN
  84 specific socket options described in the bcm(7) and can-raw(7) manual
  85 pages.  Complete documentation can be found in the LaTeX file,
  86 currently only available in German.
  87
  88
  89 4. Why using the socket API
  90
  91 There have been CAN implementations for Linux before Socket CAN so the
  92 question arises, why we have started another project.  Most existing
  93 implementations come as a device driver for some CAN hardware, they
  94 are based on character devices and provide comparatively little
  95 functionality.  Usually, there is only a hardware-specific device
  96 driver which provides a character device interface to send and
  97 receive raw CAN frames, directly to/from the controller hardware.
  98 Queueing of frames and higher-level transport protocols like ISO-TP
  99 have to be implemented in user space applications.  Also, most
 100 character-device implementations support only one single process to
 101 open the device at a time, similar to a serial interface.  Exchanging
 102 the CAN controller requires employment of another device driver and
 103 often the need for adaption of large parts of the application to the
 104 new driver's API.
 105
 106 Socket CAN was designed to overcome all of these limitations.  A new
 107 protocol family has been implemented which provides a socket interface
 108 to user space applications and which builds upon the Linux network
 109 layer, so to use all of the provided queueing functionality.  Device
 110 drivers for CAN controller hardware register itself with the Linux
 111 network layer as a network device, so that CAN frames from the
 112 controller can be passed up to the network layer and on to the CAN
 113 protocol family module and also vice-versa.  Also, the protocol family
 114 module provides an API for transport protocol modules to register, so
 115 that any number of transport protocols can be loaded or unloaded
 116 dynamically.  In fact, the can core module alone does not provide any
 117 protocol and can not be used without loading at least one additional
 118 protocol module.  Multiple sockets can be opened at the same time,
 119 on different or the same protocol module and they can listen/send
 120 frames on different or the same CAN IDs.  Several sockets listening on
 121 the same interface for frames with the same CAN ID are all passed the
 122 same received matching CAN frames.  An application wishing to
 123 communicate using a specific transport protocol, e.g. ISO-TP, just
 124 selects that protocol when opening the socket, and then can read and
 125 write application data byte streams, without having to deal with
 126 CAN-IDs, frames, etc.
 127
 128 Similar functionality visible from user-space could be provided by a
 129 character decive, too, but this would lead to a technically inelegant
 130 solution for a couple of reasons:
 131
 132 * Intricate usage.  Instead of passing a protocol argument to
 133   socket(2) and using bind(2) to select a CAN interface and CAN ID, an
 134   application would have to do all these operations using ioctl(2)s.
 135
 136 * Code duplication.  A character device cannot make use of the Linux
 137   network queueing code, so all that code would have to be duplicated
 138   for CAN networking.
 139
 140 * Abstraction.  In most existing character-device implementations, the
 141   hardware-specific device driver for a CAN controller directly
 142   provides the character device for the application to work with.
 143   This is at least very unusual in Unix systems, for both, char and
 144   block devices.  For example you don't have a character device for a
 145   certain UART of a serial interface, a certain sound chip in your
 146   computer, a SCSI or IDE controller providing access to your hard
 147   disk or tape streamer device.  Instead, you have abstraction layers
 148   which provide a unified character or block device interface to the
 149   application on the one hand, and a interface for hardware-specific
 150   device drivers on the other hand.  These abstractions are provided
 151   by subsystems like the tty layer, the audio subsystem or the SCSI
 152   and IDE subsystems for the devices mentioned above.
 153
 154   The easiest way to implement a CAN device driver is as a character
 155   without such a (complete) abstraction layer, as is done by most
 156   existing drivers.  The right way, however, would be to add such a
 157   layer with all the functionality like registering for certain CAN
 158   IDs, supporting several open file descriptors and (de)multplexing
 159   CAN frames between them, (sophisticated) queueing of CAN frames, and
 160   providing an API for device driver to register with.  However, then
 161   it would be no more difficult, or may be even easier, to use the
 162   networking framework provided by the Linux kernel, and this is what
 163   Socket CAN does.
 164
 165 Although CAN is not really a well-designed networking technology and
 166 the 'N' in CAN feels just wrong (at least in the opinion of one
 167 socketcan authors), use of the networking framework of the Linux
 168 kernel is just the natural and most appropriate way to implement CAN
 169 for Linux.