--- /dev/null
+============================================================================
+
+overview.txt : introduction and general concepts
+
+Part of the documentation for the socketCAN subsystem
+
+This file contains:
+
+ 1 Overview / What is Socket CAN
+
+ 2 Motivation / Why using the socket API
+
+ 3 Socket CAN concept
+ 3.1 receive lists
+ 3.2 local loopback of sent frames
+ 3.3 network security issues (capabilities)
+ 3.4 network problem notifications
+
+ 4 Socket CAN resources
+
+ 5 Credits
+
+============================================================================
+
+1. Overview / What is Socket CAN
+--------------------------------
+
+ 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, Socket CAN 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.
+
+2. Motivation / Why using the socket API
+----------------------------------------
+
+ There have been CAN implementations for Linux before Socket CAN 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.
+
+ Socket CAN 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, so to 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
+ Socket CAN does.
+
+ The use of the networking framework of the Linux kernel is just the
+ natural and most appropriate way to implement CAN for Linux.
+
+3. Socket CAN concept
+---------------------
+
+ As described in chapter 2 it is the main goal of Socket CAN 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.
+
+ 3.1 receive lists
+
+ The network transparent access of multiple applications leads to the
+ problem that different applications may be interested in the same
+ CAN-IDs from the same CAN network interface. The Socket CAN core
+ module - which implements the protocol family CAN - provides several
+ high efficient receive lists for this reason. If e.g. a user space
+ application opens a CAN RAW socket, the raw protocol module itself
+ requests the (range of) CAN-IDs from the Socket CAN core that are
+ requested by the user. The subscription and unsubscription of
+ CAN-IDs can be done for specific CAN interfaces or for all(!) known
+ CAN interfaces with the can_rx_(un)register() functions provided to
+ CAN protocol modules by the SocketCAN core (see can-core.txt).
+ To optimize the CPU usage at runtime the receive lists are split up
+ into several specific lists per device that match the requested
+ filter complexity for a given use-case.
+
+ 3.2 local loopback of sent frames
+
+ As known from other networking concepts the data exchanging
+ applications may run on the same or different nodes without any
+ change (except for the according addressing information):
+
+ ___ ___ ___ _______ ___
+ | _ | | _ | | _ | | _ _ | | _ |
+ ||A|| ||B|| ||C|| ||A| |B|| ||C||
+ |___| |___| |___| |_______| |___|
+ | | | | |
+ -----------------(1)- CAN bus -(2)---------------
+
+ To ensure that application A receives the same information in the
+ example (2) as it would receive in example (1) there is need for
+ some kind of local loopback of the sent CAN frames on the appropriate
+ node.
+
+ The Linux network devices (by default) just can handle the
+ transmission and reception of media dependent frames. Due to the
+ arbitration on the CAN bus the transmission of a low prio CAN-ID
+ may be delayed by the reception of a high prio CAN frame. To
+ reflect the correct* traffic on the node the loopback of the sent
+ data has to be performed right after a successful transmission. If
+ the CAN network interface is not capable of performing the loopback for
+ some reason the SocketCAN core can do this task as a fallback solution.
+ See can-drivers.txt, chapter 1.2 for details (recommended).
+
+ The loopback functionality is enabled by default to reflect standard
+ networking behaviour for CAN applications. Due to some requests from
+ the RT-SocketCAN group the loopback optionally may be disabled for each
+ separate socket. See sockopts from the CAN RAW sockets in can-raw.txt.
+
+ * = you really like to have this when you're running analyser tools
+ like 'candump' or 'cansniffer' on the (same) node.
+
+ 3.3 network security issues (capabilities)
+
+ The Controller Area Network is a local field bus transmitting only
+ broadcast messages without any routing and security concepts.
+ In the majority of cases the user application has to deal with
+ raw CAN frames. Therefore it might be reasonable NOT to restrict
+ the CAN access only to the user root, as known from other networks.
+ Since the currently implemented CAN_RAW and CAN_BCM sockets can only
+ send and receive frames to/from CAN interfaces it does not affect
+ security of others networks to allow all users to access the CAN.
+ To enable non-root users to access CAN_RAW and CAN_BCM protocol
+ sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be
+ selected at kernel compile time.
+
+ 3.4 network problem notifications
+
+ The use of the CAN bus may lead to several problems on the physical
+ and media access control layer. Detecting and logging of these lower
+ layer problems is a vital requirement for CAN users to identify
+ hardware issues on the physical transceiver layer as well as
+ arbitration problems and error frames caused by the different
+ ECUs. The occurrence of detected errors are important for diagnosis
+ and have to be logged together with the exact timestamp. For this
+ reason the CAN interface driver can generate so called Error Frames
+ that can optionally be passed to the user application in the same
+ way as other CAN frames. Whenever an error on the physical layer
+ or the MAC layer is detected (e.g. by the CAN controller) the driver
+ creates an appropriate error frame. Error frames can be requested by
+ the user application using the common CAN filter mechanisms. Inside
+ this filter definition the (interested) type of errors may be
+ selected. The reception of error frames is disabled by default.
+ The format of the CAN error frame is briefly decribed in the Linux
+ header file "include/linux/can/error.h".
+
+4. Socket CAN resources
+-----------------------
+
+ You can find further resources for Socket CAN like user space tools,
+ support for old kernel versions, more drivers, mailing lists, etc.
+ at the BerliOS OSS project website for Socket CAN:
+
+ http://developer.berlios.de/projects/socketcan
+
+ If you have questions, bug fixes, etc., don't hesitate to post them to
+ the Socketcan-Users mailing list. But please search the archives first.
+
+5. Credits
+----------
+
+ Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
+ Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
+ Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
+ Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews,
+ CAN device driver interface, MSCAN driver)
+ Robert Schwebel (design reviews, PTXdist integration)
+ Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
+ Benedikt Spranger (reviews)
+ Thomas Gleixner (LKML reviews, coding style, posting hints)
+ Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
+ Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
+ Klaus Hitschler (PEAK driver integration)
+ Uwe Koppe (CAN netdevices with PF_PACKET approach)
+ Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
+ Pavel Pisa (Bit-timing calculation)
+ Sascha Hauer (SJA1000 platform driver)
+ Sebastian Haas (SJA1000 EMS PCI driver)
+ Markus Plessing (SJA1000 EMS PCI driver)
+ Per Dalen (SJA1000 Kvaser PCI driver)
+ Sam Ravnborg (reviews, coding style, kbuild help)
+
projects / socketcan-devel.git / blobdiff