kernel/2.6/Documentation/networking/can/can-raw.txt

   1 ============================================================================
   2
   3 can-raw.txt : Raw CAN sockets
   4
   5 Part of the documentation for the socketCAN subsystem
   6
   7 This file contains
   8
   9   1 RAW protocol sockets with can_filters (SOCK_RAW)
  10     1.1 RAW socket option CAN_RAW_FILTER
  11     1.2 RAW socket option CAN_RAW_ERR_FILTER
  12     1.3 RAW socket option CAN_RAW_LOOPBACK
  13     1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
  14     1.5 RAW socket returned message flags
  15
  16 ============================================================================
  17
  18 1. RAW protocol sockets with can_filters (SOCK_RAW)
  19 ---------------------------------------------------
  20
  21   Using CAN_RAW sockets is extensively comparable to the commonly
  22   known access to CAN character devices. To meet the new possibilities
  23   provided by the multi user SocketCAN approach, some reasonable
  24   defaults are set at RAW socket binding time:
  25
  26   - The filters are set to exactly one filter receiving everything
  27   - The socket only receives valid data frames (=> no error frames)
  28   - The loopback of sent CAN frames is enabled (see overview.txt, chapter 3.2)
  29   - The socket does not receive its own sent frames (in loopback mode)
  30
  31   These default settings may be changed before or after binding the socket.
  32   To use the referenced definitions of the socket options for CAN_RAW
  33   sockets, include <linux/can/raw.h>.
  34
  35   1.1 RAW socket option CAN_RAW_FILTER
  36
  37   The reception of CAN frames using CAN_RAW sockets can be controlled
  38   by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
  39
  40   The CAN filter structure is defined in include/linux/can.h:
  41
  42     struct can_filter {
  43             canid_t can_id;
  44             canid_t can_mask;
  45     };
  46
  47   A filter matches, when
  48
  49     <received_can_id> & mask == can_id & mask
  50
  51   which is analogous to known CAN controllers hardware filter semantics.
  52   The filter can be inverted in this semantic, when the CAN_INV_FILTER
  53   bit is set in can_id element of the can_filter structure. In
  54   contrast to CAN controller hardware filters the user may set 0 .. n
  55   receive filters for each open socket separately:
  56
  57     struct can_filter rfilter[2];
  58
  59     rfilter[0].can_id   = 0x123;
  60     rfilter[0].can_mask = CAN_SFF_MASK;
  61     rfilter[1].can_id   = 0x200;
  62     rfilter[1].can_mask = 0x700;
  63
  64     setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter));
  65
  66   To disable the reception of CAN frames on the selected CAN_RAW socket:
  67
  68     setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
  69
  70   To set the filters to zero filters is quite obsolete as not read
  71   data causes the raw socket to discard the received CAN frames. But
  72   having this 'send only' use-case we may remove the receive list in the
  73   Kernel to save a little (really a very little!) CPU usage.
  74
  75   1.2 RAW socket option CAN_RAW_ERR_FILTER
  76
  77   As described in overview.txt (chapter 3.4) the CAN interface driver
  78   can generate so called Error Frames that can optionally be passed
  79   to the user application in the same way as other CAN frames. The possible
  80   errors are divided into different error classes that may be filtered
  81   using the appropriate error mask. To register for every possible
  82   error condition CAN_ERR_MASK can be used as value for the error mask.
  83   The values for the error mask are defined in linux/can/error.h .
  84
  85     can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF );
  86
  87     setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER,
  88                &err_mask, sizeof(err_mask));
  89
  90   1.3 RAW socket option CAN_RAW_LOOPBACK
  91
  92   To meet multi user needs the local loopback is enabled by default
  93   (see overview.txt, chapter 3.2, for details). But in some embedded
  94   use-cases (e.g. when only one application uses the CAN bus) this
  95   loopback functionality can be disabled (separately for each socket):
  96
  97     int loopback = 0; /* 0 = disabled, 1 = enabled (default) */
  98
  99     setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback));
 100
 101   1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
 102
 103   When the local loopback is enabled, all the sent CAN frames are
 104   looped back to the open CAN sockets that registered for the CAN
 105   frames' CAN-ID on this given interface to meet the multi user
 106   needs. The reception of the CAN frames on the same socket that was
 107   sending the CAN frame is assumed to be unwanted and therefore
 108   disabled by default. This default behaviour may be changed on
 109   demand:
 110
 111     int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */
 112
 113     setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS,
 114                &recv_own_msgs, sizeof(recv_own_msgs));
 115
 116   1.5 RAW socket returned message flags
 117
 118   When using recvmsg() call, the msg->msg_flags may contain following flags:
 119
 120     MSG_DONTROUTE: set when the received frame was created on the local host.
 121
 122     MSG_CONFIRM: set when the frame was sent via the socket it is received on.
 123       This flag can be interpreted as a 'transmission confirmation' when the
 124       CAN driver supports the echo of frames on driver level, see 3.2 and 6.2.
 125       In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set.
 126