ongoing documentation.

git-svn-id: svn://svn.berlios.de//socketcan/trunk@302 030b6a49-0b11-0410-94ab-b0dab22257f2

diff --git a/kernel/2.6/Documentation/networking/can.txt b/kernel/2.6/Documentation/networking/can.txt
index 1239a315281ff83b4b7ca59d1e1fc97a9cc22831..715b44d28639c27f0407f8ad50008ce9eab5552e 100644 (file)
--- a/kernel/2.6/Documentation/networking/can.txt
+++ b/kernel/2.6/Documentation/networking/can.txt
@@ -18,6 +18,10 @@ This file contains
 
   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)
@@ -311,6 +315,36 @@ solution for a couple of reasons:
   specify the outgoing interface.
 
   4.1 RAW protocol sockets with can_filters (SOCK_RAW)
+
+  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));
+
+  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)
@@ -342,8 +376,55 @@ solution for a couple of reasons:
     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
 ----------------------
 
@@ -360,7 +441,7 @@ solution for a couple of reasons:
   6.1 general settings
 
     dev->type  = ARPHRD_CAN; /* the netdevice hardware type */
-    dev->flags = IFF_NOARP; /* CAN has no arp */
+    dev->flags = IFF_NOARP;  /* CAN has no arp */
 
     dev->mtu   = sizeof(struct can_frame);