============================================================================

can-raw.txt : Raw CAN sockets

Part of the documentation for the socketCAN subsystem

This file contains

  R. RAW protocol sockets with can_filters (SOCK_RAW)
    R.1 RAW socket option CAN_RAW_FILTER
    R.2 RAW socket option CAN_RAW_ERR_FILTER
    R.3 RAW socket option CAN_RAW_LOOPBACK
    R.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
    R.5 RAW socket returned message flags

============================================================================

R. 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 binding time:

  - The filters are set to exactly one filter receiving everything
  - The socket only receives valid data frames (=> no error frames)
  - The loopback of sent CAN frames is enabled (see overview.txt, chapter 3.2)
  - The socket does not receive its 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>.

  R.1 RAW socket option CAN_RAW_FILTER

  The reception 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 analogous 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
  contrast 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 reception 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 read
  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.

  R.2 RAW socket option CAN_RAW_ERR_FILTER

  As described in overview.txt (chapter 3.4) 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. The possible
  errors are divided 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));

  R.3 RAW socket option CAN_RAW_LOOPBACK

  To meet multi user needs the local loopback is enabled by default
  (see overview.txt, 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));

  R.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 reception 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 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));

  R.5 RAW socket returned message flags

  When using recvmsg() call, the msg->msg_flags may contain following flags:

    MSG_DONTROUTE: set when the received frame was created on the local host.

    MSG_CONFIRM: set when the frame was sent via the socket it is received on.
      This flag can be interpreted as a 'transmission confirmation' when the
      CAN driver supports the echo of frames on driver level, see 3.2 and 6.2.
      In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set.