===================================
SocketCAN - Controller Area Network
===================================
Overview / What is SocketCAN
============================
The socketcan package is an implementation of CAN protocols
(Controller Area Network) for Linux. CAN is a networking technology
which has widespread use in automation, embedded devices, and
automotive fields. While there have been other CAN implementations
for Linux based on character devices, SocketCAN uses the Berkeley
socket API, the Linux network stack and implements the CAN device
drivers as network interfaces. The CAN socket API has been designed
as similar as possible to the TCP/IP protocols to allow programmers,
familiar with network programming, to easily learn how to use CAN
sockets.
.. _socketcan-motivation:
Motivation / Why Using the Socket API
=====================================
There have been CAN implementations for Linux before SocketCAN so the
question arises, why we have started another project. Most existing
implementations come as a device driver for some CAN hardware, they
are based on character devices and provide comparatively little
functionality. Usually, there is only a hardware-specific device
driver which provides a character device interface to send and
receive raw CAN frames, directly to/from the controller hardware.
Queueing of frames and higher-level transport protocols like ISO-TP
have to be implemented in user space applications. Also, most
character-device implementations support only one single process to
open the device at a time, similar to a serial interface. Exchanging
the CAN controller requires employment of another device driver and
often the need for adaption of large parts of the application to the
new driver's API.
SocketCAN was designed to overcome all of these limitations. A new
protocol family has been implemented which provides a socket interface
to user space applications and which builds upon the Linux network
layer, enabling use all of the provided queueing functionality. A device
driver for CAN controller hardware registers itself with the Linux
network layer as a network device, so that CAN frames from the
controller can be passed up to the network layer and on to the CAN
protocol family module and also vice-versa. Also, the protocol family
module provides an API for transport protocol modules to register, so
that any number of transport protocols can be loaded or unloaded
dynamically. In fact, the can core module alone does not provide any
protocol and cannot be used without loading at least one additional
protocol module. Multiple sockets can be opened at the same time,
on different or the same protocol module and they can listen/send
frames on different or the same CAN IDs. Several sockets listening on
the same interface for frames with the same CAN ID are all passed the
same received matching CAN frames. An application wishing to
communicate using a specific transport protocol, e.g. ISO-TP, just
selects that protocol when opening the socket, and then can read and
write application data byte streams, without having to deal with
CAN-IDs, frames, etc.
Similar functionality visible from user-space could be provided by a
character device, too, but this would lead to a technically inelegant
solution for a couple of reasons:
* **Intricate usage:** Instead of passing a protocol argument to
socket(2) and using bind(2) to select a CAN interface and CAN ID, an
application would have to do all these operations using ioctl(2)s.
* **Code duplication:** A character device cannot make use of the Linux
network queueing code, so all that code would have to be duplicated
for CAN networking.
* **Abstraction:** In most existing character-device implementations, the
hardware-specific device driver for a CAN controller directly
provides the character device for the application to work with.
This is at least very unusual in Unix systems for both, char and
block devices. For example you don't have a character device for a
certain UART of a serial interface, a certain sound chip in your
computer, a SCSI or IDE controller providing access to your hard
disk or tape streamer device. Instead, you have abstraction layers
which provide a unified character or block device interface to the
application on the one hand, and a interface for hardware-specific
device drivers on the other hand. These abstractions are provided
by subsystems like the tty layer, the audio subsystem or the SCSI
and IDE subsystems for the devices mentioned above.
The easiest way to implement a CAN device driver is as a character
device without such a (complete) abstraction layer, as is done by most
existing drivers. The right way, however, would be to add such a
layer with all the functionality like registering for certain CAN
IDs, supporting several open file descriptors and (de)multiplexing
CAN frames between them, (sophisticated) queueing of CAN frames, and
providing an API for device drivers to register with. However, then
it would be no more difficult, or may be even easier, to use the
networking framework provided by the Linux kernel, and this is what
SocketCAN does.
The use of the networking framework of the Linux kernel is just the
natural and most appropriate way to implement CAN for Linux.
.. _socketcan-concept:
SocketCAN Concept
=================
As described in :ref:`socketcan-motivation` the main goal of SocketCAN is to
provide a socket interface to user space applications which builds
upon the Linux network layer. In contrast to the commonly known
TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
medium that has no MAC-layer addressing like ethernet. The CAN-identifier
(can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
have to be chosen uniquely on the bus. When designing a CAN-ECU
network the CAN-IDs are mapped to be sent by a specific ECU.
For this reason a CAN-ID can be treated best as a kind of source address.
.. _socketcan-receive-lists:
Receive Lists
-------------
The network transparent access of multiple applications leads to the
problem that d