[socketcan-devel.git] / patch-series / net-2.6.23 / 07-can-doc.diff

DESC
CAN: Add documentation
EDESC
This patch adds documentation for the PF_CAN protocol family.

Signed-off-by: Oliver Hartkopp <oliver.hartkopp@volkswagen.de>
Signed-off-by: Urs Thuermann <urs.thuermann@volkswagen.de>

---
 Documentation/networking/00-INDEX |    2 
 Documentation/networking/can.txt  |  635 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 637 insertions(+)

Index: net-2.6.23/Documentation/networking/can.txt
===================================================================
--- /dev/null   1970-01-01 00:00:00.000000000 +0000
+++ net-2.6.23/Documentation/networking/can.txt 2007-07-09 10:42:09.000000000 +0200
@@ -0,0 +1,635 @@
+============================================================================
+
+can.txt
+
+Readme file for the Controller Area Network Protocol Family (aka Socket CAN)
+
+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 loopback
+    3.3 network security issues (capabilities)
+    3.4 network problem notifications
+
+  4 How to use Socket CAN
+    4.1 RAW protocol sockets with can_filters (SOCK_RAW)
+      4.1.1 RAW socket option CAN_RAW_FILTER
+      4.1.2 RAW socket option CAN_RAW_ERR_FILTER
+      4.1.3 RAW socket option CAN_RAW_LOOPBACK
+      4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
+    4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
+    4.3 connected transport protocols (SOCK_SEQPACKET)
+    4.4 unconnected transport protocols (SOCK_DGRAM)
+
+  5 Socket CAN core module
+    5.1 can.ko module params
+    5.2 procfs content
+    5.3 writing own CAN protocol modules
+
+  6 CAN network drivers
+    6.1 general settings
+    6.2 loopback
+    6.3 CAN controller hardware filters
+    6.4 currently supported CAN hardware
+    6.5 todo
+
+  7 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 wide-spread 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.  Device
+drivers for CAN controller hardware register 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 can not 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 decive, 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
+  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)multplexing
+  CAN frames between them, (sophisticated) queueing of CAN frames, and
+  providing an API for device driver 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 networklayer. In opposite to the commonly known
+  TCP/IP and ethernet networking the CAN bus is a broadcast-only(!)
+  medium that has no MAC-layer adressing like ethernet. The CAN-identifier
+  (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
+  have to be choosen unique 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 treatened 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 interrested 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 chapter 5).
+  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 loopback
+
+  As known from other networking concepts the data exchanging
+  applications may run on the same or different nodes without any
+  change (except if 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
+  expample (2) as it would receive in example (1) there is need for
+  some kind of local loopback on the appropriate node.
+
+  The Linux network devices (by default) just can handle the
+  transmission and receiption of media dependend frames. Due to the
+  arbritration on the CAN bus the transmission of a low prio CAN-ID
+  may be delayed from the receipition 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 to perform the loopback for
+  some reason the SocketCAN core can do this task as a fallback solution.
+  See chapter 6.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
+  seperate socket. See sockopts from the CAN RAW sockets in chapter 4.1 .
+
+  * = 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 occurance 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 on the same
+  way like 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 (interrested) type of errors may be
+  selected. The receiption of error frames is disabled by default.
+
+4. How to use Socket CAN
+------------------------
+
+  Like TCP/IP, you first need to open a socket for communicating over a
+  CAN network. Since Socket CAN implements a new protocol family, you
+  need to pass PF_CAN as the first argument to the socket(2) system
+  call. Currently, there are two CAN protocols to choose from, the raw
+  socket protocol and the broadcast manager (BCM). So to open a socket,
+  you would write
+
+    s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
+
+  and
+
+    s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
+
+  respectively.  After the successful creation of the socket, you would
+  normally use the bind(2) system call to bind the socket to a CAN
+  interface (which is different to TCP/IP due to different addressing
+  - see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM)
+  the socket, you can read(2) and write(2) from/to the socket or use
+  send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
+  on the socket as usual. There are also CAN specific socket options
+  described below.
+
+  The basic CAN frame structure and the sockaddr structure are defined
+  in include/linux/can.h:
+
+    struct can_frame {
+            canid_t can_id;  /* 32 bit CAN_ID + EFF/RTR/ERR flags */
+            __u8    can_dlc; /* data length code: 0 .. 8 */
+            __u8    data[8] __attribute__((aligned(8)));
+    };
+
+  The alignment of the (linear) payload data[] to a 64bit boundary
+  allows the user to define own structs and unions to easily access the
+  CAN payload. There is no given byteorder on the CAN bus by
+  default. A read(2) system call on a CAN_RAW socket transfers a
+  struct can_frame to the user space.
+
+  The sockaddr_can structure has an interface index analogue to the
+  PF_PACKET socket, that also binds to a specific interface:
+
+    struct sockaddr_can {
+            sa_family_t can_family;
+            int         can_ifindex;
+            union {
+                    struct { canid_t rx_id, tx_id; } tp16;
+                    struct { canid_t rx_id, tx_id; } tp20;
+                    struct { canid_t rx_id, tx_id; } mcnet;
+                    struct { canid_t rx_id, tx_id; } isotp;
+                    struct { int     lcu,   type;  } bap;
+            } can_addr;
+    };
+
+  To determine the interface index the an appropriate ioctl() has to
+  be used (example for CAN_RAW sockets without error checking):
+
+    int s;
+    struct sockaddr_can addr;
+    struct ifreq ifr;
+
+    s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
+
+    strcpy(ifr.ifr_name, "can0" );
+    ioctl(s, SIOCGIFINDEX, &ifr);
+
+    addr.can_family = AF_CAN;
+    addr.can_ifindex = ifr.ifr_ifindex;
+
+    bind(s, (struct sockaddr *)&addr, sizeof(addr));
+
+    (..)
+
+  To bind a socket to all(!) CAN interfaces the interface index might
+  be 0 (zero). In this case the socket receives CAN frames from every
+  enabled CAN interface. To determine the originating CAN interface
+  the system call recvfrom(2) may be used instead of read(2). To send
+  on a socket that is bound to 'any' interface sendto(2) is needed to
+  specify the outgoing interface.
+
+  Reading CAN frames from a bound CAN_RAW socket (see above) consists
+  of reading a struct can_frame:
+
+    struct can_frame frame;
+
+    nbytes = read(s, &frame, sizeof(struct can_frame));
+
+    if (nbytes < 0) {
+            perror("can raw socket read");
+            return 1;
+    }
+
+    /* paraniod check ... */
+    if (nbytes < sizeof(struct can_frame)) {
+            fprintf(stderr, "read: incomplete CAN frame\n");
+            return 1;
+    }
+
+    /* do something with the received CAN frame */
+
+  Writing CAN frames can be done analogue with the write(2) system call:
+
+    nbytes = write(s, &frame, sizeof(struct can_frame));
+
+  When the CAN interface is bound to 'any' existing CAN interface
+  (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the
+  information about the originating CAN interface is needed:
+
+    struct sockaddr_can addr;
+    struct ifreq ifr;
+    socklen_t len = sizeof(addr);
+    struct can_frame frame;
+
+    nbytes = recvfrom(s, &frame, sizeof(struct can_frame),
+                      0, (struct sockaddr*)&addr, &len);
+
+    /* get interface name of the received CAN frame */
+    ifr.ifr_ifindex = addr.can_ifindex;
+    ioctl(s, SIOCGIFNAME, &ifr);
+    printf("Received a CAN frame from interface %s", ifr.ifr_name);
+
+  To write CAN frames on sockets bound to 'any' CAN interface the
+  outgoing interface has to be defined certainly.
+
+    strcpy(ifr.ifr_name, "can0");
+    ioctl(s, SIOCGIFINDEX, &ifr);
+    addr.can_ifindex = ifr.ifr_ifindex;
+    addr.can_family  = AF_CAN;
+
+    nbytes = sendto(s, &frame, sizeof(struct can_frame),
+                    0, (struct sockaddr*)&addr, sizeof(addr));
+
+  4.1 RAW protocol sockets with can_filters (SOCK_RAW)
+
+  Using CAN_RAW sockets is extensively comparable to the commonly
+  known access to CAN character devices. To meet the new possibilities
+  provided by the multi user SocketCAN approach, some reasonable
+  defaults are set at RAW socket bindung time:
+
+  - The filters are set to excatly one filter receiving everything
+  - The socket only receives valid data frames (=> no error frames)
+  - The loopback of sent CAN frames is enabled (see chapter 3.2)
+  - The socket does not receive it's own sent frames (in loopback mode)
+
+  These default settings may be changed before or after binding the socket.
+  To use the referenced definitions of the socket options for CAN_RAW
+  sockets include linux/can/raw.h .
+
+  4.1.1 RAW socket option CAN_RAW_FILTER
+
+  The receiption of CAN frames using CAN_RAW sockets can be controlled
+  by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
+
+  The CAN filter structure is defined in include/linux/can.h:
+
+    struct can_filter {
+            canid_t can_id;
+            canid_t can_mask;
+    };
+
+  A filter matches, when
+
+    <received_can_id> & mask == can_id & mask
+
+  which is analogue to known CAN controllers hardware filter semantics.
+  The filter can be inverted in this semantic, when the CAN_INV_FILTER
+  bit is set in can_id element of the can_filter structure. In
+  opposite to CAN controller hardware filters the user may set 0 .. n
+  receive filters for each open socket separately:
+
+    struct can_filter rfilter[2];
+
+    rfilter[0].can_id   = 0x123;
+    rfilter[0].can_mask = CAN_SFF_MASK;
+    rfilter[1].can_id   = 0x200;
+    rfilter[1].can_mask = 0x700;
+
+    setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter));
+
+  To disable the receiption of CAN frames on the selected CAN_RAW socket:
+
+    setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
+
+  To set the filters to zero filters is quite obsolete as not readed
+  data causes the raw socket to discard the received CAN frames. But
+  having this 'send only' use-case we may remove the receive list in the
+  Kernel to save a little (really a very little!) CPU usage.
+
+  4.1.2 RAW socket option CAN_RAW_ERR_FILTER
+
+  As described in chapter 3.4 the CAN interface driver can generate so
+  called Error Frames that can optionally be passed to the user
+  application on the same way like other CAN frames. The possible
+  errors are devided into different error classes that may be filtered
+  using the appropriate error mask. To register for every possible
+  error condition CAN_ERR_MASK can be used as value for the error mask.
+  The values for the error mask are defined in linux/can/error.h .
+
+    can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF );
+
+    setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER,
+               &err_mask, sizeof(err_mask));
+
+  4.1.3 RAW socket option CAN_RAW_LOOPBACK
+
+  To meet multi user needs the local loopback is enabled by default
+  (see chapter 3.2 for details). But in some embedded use-cases
+  (e.g. when only one application uses the CAN bus) this loopback
+  functionality can be disabled (separately for each socket):
+
+    int loopback = 0; /* 0 = disabled, 1 = enabled (default) */
+
+    setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback));
+
+  4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
+
+  When the local loopback is enabled, all the sent CAN frames are
+  looped back to the open CAN sockets that registered for the CAN
+  frames' CAN-ID on this given interface to meet the multi user
+  needs. The receiption of the CAN frames on the same socket that was
+  sending the CAN frame is assumed to be unwanted and therefore
+  disabled by default. This default behaviour may be changed on
+  demand:
+
+    int set_recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */
+
+    setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS,
+               &recv_own_msgs, sizeof(recv_own_msgs));
+
+  4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
+  4.3 connected transport protocols (SOCK_SEQPACKET)
+  4.4 unconnected transport protocols (SOCK_DGRAM)
+
+
+5. Socket CAN core module
+-------------------------
+
+  The Socket CAN core module implements the protocol family
+  PF_CAN. CAN protocol modules are loaded by the core module at
+  runtime. The core module provides an interface for CAN protocol
+  modules to subscribe needed CAN IDs (see chapter 3.1).
+
+  5.1 can.ko module params
+
+  - stats_timer: To calculate the Socket CAN core statistics
+    (e.g. current/maximum frames per second) this 1 second timer is
+    invoked at can.ko module start time by default. This timer can be
+    disabled giving stattimer=0 on the module comandline.
+
+  - debug: When the Kconfig option CONFIG_CAN_DEBUG_CORE is set at
+    compile time, the debug output code is compiled into the module.
+    debug = 0x01 => print general debug information
+    debug = 0x02 => print content of processed CAN frames
+    debug = 0x04 => print content of processed socket buffers
+
+    It is possible or have ORed values e.g. 3 or 7 for an output off
+    all available debug information. Using 0x02 and 0x04 may flood
+    your kernel log - so be careful.
+
+  5.2 procfs content
+
+  As described in chapter 3.1 the Socket CAN core uses several filter
+  lists to deliver received CAN frames to CAN protocol modules. These
+  receive lists, their filters and the count of filter matches can be
+  checked in the appropriate receive list. All entries contain the
+  device and a protocol module identifier:
+
+    foo@bar:~$ cat /proc/net/can/rcvlist_all
+
+    receive list 'rx_all':
+      (vcan3: no entry)
+      (vcan2: no entry)
+      (vcan1: no entry)
+      device   can_id   can_mask  function  userdata   matches  ident
+       vcan0     000    00000000  f88e6370  f6c6f400         0  raw
+      (any: no entry)
+
+  In this example an application requests any CAN traffic from vcan0.
+
+    rcvlist_all - list for unfiltered entries (no filter operations)
+    rcvlist_eff - list for single extended frame (EFF) entries
+    rcvlist_err - list for error frames masks
+    rcvlist_fil - list for mask/value filters
+    rcvlist_inv - list for mask/value filters (inverse semantic)
+    rcvlist_sff - list for single standard frame (SFF) entries
+
+  Additional procfs files in /proc/net/can
+
+    stats       - Socket CAN core statistics (rx/tx frames, match ratios, ...)
+    reset_stats - manual statistic reset
+    version     - prints the Socket CAN core version and the ABI version
+
+  5.3 writing own CAN protocol modules
+
+  To implement a new protocol in the protocol family PF_CAN a new
+  protocol has to be defined in include/linux/can.h .
+  The prototypes and definitions to use the Socket CAN core can be
+  accessed by including include/linux/can/core.h .
+  Additionally to functions that register the CAN protocol and the
+  CAN device notifier chain there are functions to subscribe CAN
+  frames received by CAN interfaces and to send CAN frames:
+
+    can_rx_register   - subscribe CAN frames from a specific interface
+    can_rx_unregister - unsubscribe CAN frames from a specific interface
+    can_send          - transmit a CAN frame (optional with local loopback)
+
+  For details see the kerneldoc documentation in net/can/af_can.c or
+  the source code of net/can/raw.c or net/can/bcm.c .
+
+6. CAN network drivers
+----------------------
+
+  Writing a CAN network device driver is much easier than writing a
+  CAN character device driver. Analogue to other know network device
+  drivers you mainly have to deal with:
+
+  - TX: Put the CAN frame from the socket buffer to the CAN controller.
+  - RX: Put the CAN frame from the CAN controller to the socket buffer.
+
+  See e.g. at Documentation/networking/netdevices.txt . The differences
+  for writing CAN network device driver are described below:
+
+  6.1 general settings
+
+    dev->type  = ARPHRD_CAN; /* the netdevice hardware type */
+    dev->flags = IFF_NOARP;  /* CAN has no arp */
+
+    dev->mtu   = sizeof(struct can_frame);
+
+  The struct can_frame is the payload of each socket buffer in the
+  protocol family PF_CAN.
+
+  6.2 loopback
+
+  As described in chapter 3.2 the CAN network device driver should
+  support a local loopback functionality. If so the driver flag
+  IFF_LOOPBACK has to be set to omit the PF_CAN core to perform the
+  loopback as fallback solution:
+
+    dev->flags = (IFF_NOARP | IFF_LOOPBACK);
+
+  6.3 CAN controller hardware filters
+
+  To reduce the interrupt load on deep embedded systems some CAN
+  controllers support the filtering of CAN IDs or ranges of CAN IDs.
+  These hardware filter capabilities vary from controller to
+  controller and have to be identified as not feasible in a multi-user
+  networking approach. The use of the very controller specific
+  hardware filters could make sense in a very dedicated use-case, as a
+  filter on driver level would affect all users in the multi-user
+  system. The high efficient filter sets inside the PF_CAN core allow
+  to set different multiple filters for each socket separately.
+  Therefore the use of hardware filters goes to the category 'handmade
+  tuning on deep embedded systems'. The author is running a MPC603e
+  @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
+  load without any problems ...
+
+  6.4 currently supported CAN hardware (May 2007)
+
+  On the project website http://developer.berlios.de/projects/socketcan
+  there are different drivers available:
+
+    vcan:    Virtual CAN interface driver (if no real hardware is available)
+    sja1000: Philips SJA1000 CAN controller (recommended)
+    i82527:  Intel i82527 CAN controller
+    mscan:   Motorola/Freescale CAN controller (e.g. inside SOC MPC5200)
+    slcan:   For a bunch of CAN adaptors that are attached via a
+             serial line ASCII protocol (for serial / USB adaptors)
+
+  Additionally the different CAN adaptors (ISA/PCI/PCMCIA/USB/Parport)
+  from PEAK Systemtechnik support the CAN netdevice driver modell
+  since Linux driver v6.0: http://www.peak-system.com/linux/index.htm
+
+  Please check the Mailing Lists on the berlios OSS project website.
+
+  6.5 todo (May 2007)
+
+  The configuration interface for CAN network drivers is still an open
+  issue that has not been finalized in the socketcan project. Also the
+  idea of having a library module (candev.ko) that holds functions
+  that are needed by all CAN netdevices is not ready to ship.
+  Your contribution is welcome.
+
+7. Credits
+----------
+
+  Oliver Hartkopp (PF_CAN core, filters, drivers, bcm)
+  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)
+  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)
Index: net-2.6.23/Documentation/networking/00-INDEX
===================================================================
--- net-2.6.23.orig/Documentation/networking/00-INDEX   2007-07-09 10:41:38.000000000 +0200
+++ net-2.6.23/Documentation/networking/00-INDEX        2007-07-09 10:42:09.000000000 +0200
@@ -26,6 +26,8 @@
        - info on the driver for Baycom style amateur radio modems
 bridge.txt
        - where to get user space programs for ethernet bridging with Linux.
+can.txt
+       - documentation on CAN protocol family.
 comx.txt
        - info on drivers for COMX line of synchronous serial adapters.
 cops.txt