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

   1 ============================================================================
   2
   3 can-bcm.txt : Broadcast Manager API
   4
   5 Part of the documentation for the socketCAN subsystem
   6
   7 This file contains:
   8
   9   1 Broadcast Manager protocol sockets (SOCK_DGRAM)
  10     1.1 Opening BCM sockets
  11     1.2 BCM messages (struct bcm_msg_head)
  12     1.3 TX_SETUP opcode
  13     1.4 TX_DELETE opcode
  14     1.5 TX_READ opcode
  15     1.6 TX_SEND opcode
  16     1.7 RX_SETUP opcode
  17     1.8 RX_DELETE opcode
  18     1.9 RX_READ opcode
  19
  20 ============================================================================
  21
  22 1. Broadcast Manager protocol sockets (SOCK_DGRAM)
  23 --------------------------------------------------
  24
  25   The Broadcast Manager (BCM) provides functions to send CAN frames
  26   once or periodically, as well as notify applications of changes in
  27   received CAN frames, recognizing specific CAN IDs.
  28
  29   Capabilities on the trasmission side:
  30   - Cyclic transmission of a CAN frame with a given interval
  31   - Modification of message content and intervals at runtime (e.g.
  32     switching to a new interval with or without immediate restart of
  33     the timer)
  34   - Automatically switching to a second interval after a certain number
  35     of frames has been sent
  36   - Instant transmission of changed frames, without influencing the
  37     interval cycle
  38   - One-time transmission of CAN messages
  39
  40   Capabilities on the receiving side:
  41   - Receive filter to detect changes in frame ID, data or length (DLC)
  42   - Receive filter for multiplex frames (e.g. with packet counters in
  43     the data field)
  44   - RTR replies to messages
  45   - Time-out monitoring of frames
  46   - Frequency reduction of messages (throttle function) to the user
  47     application
  48
  49   1.1 Opening BCM sockets
  50
  51   To use Broadcast-Manager include the file "bcm.h".
  52   A socket for Broadcast-Manager is created with:
  53
  54     s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
  55
  56   The CAN interface is assigned with a call to connect() on the socket.
  57
  58     addr.can_family = AF_CAN;
  59     strcpy(ifr.ifr_name, "can0");
  60     ioctl(s, SIOCGIFINDEX, &ifr);
  61     addr.can_ifindex = ifr.ifr_ifindex;
  62
  63     connect(s, (struct sockaddr *)&addr, sizeof(addr));
  64
  65   If a process must operate on multiple CAN buses, it must open several
  66   sockets. It is also possible for a process to open multiple sockets
  67   on a single CAN-bus, if it makes sense for the application programmer
  68   to structure different data flows.
  69   Every single instance of Broadcast-Manager is able to manage any number of
  70   filter and/or send requests.
  71
  72   1.2 BCM messages (struct bcm_msg_head)
  73
  74   All messages from the (user) process to Broadcast-Manager have the same
  75   structure. It consists of a message header with the command (opcode),
  76   several options and zero or more CAN frames, depending on the command
  77   used and the action requested:
  78
  79     struct bcm_msg_head {
  80         int opcode;                   /* command */
  81         int flags;                    /* special flags */
  82         int count;                    /* run 'count' times ival1 then ival2 */
  83         struct timeval ival1, ival2;  /* intervals */
  84         canid_t can_id;               /* 32 Bit SFF/EFF. MSB set at EFF */
  85         int nframes;                  /* number of can_frame's in the next field */
  86         struct can_frame frames[0];
  87     };
  88
  89   The value of nframes indicates how many user data frames follow the
  90   message header. The user data frames are used to describe the actual
  91   content of a CAN message:
  92
  93     struct can_frame {
  94         canid_t can_id;      /* 32 bit CAN_ID + EFF/RTR flags */
  95         __u8    can_dlc;     /* data length code: 0 .. 8 */
  96         __u8    data[8] __attribute__ ((aligned(8)));
  97     };
  98
  99   The opcode defines the type of message. Messages from the user to
 100   BCM control the operations of the BCM, replies from the BCM indicate
 101   certain changes to the user, such as timeouts, etc.
 102
 103   The transmit and receive path of the BCM are two independent functional
 104   blocks.
 105
 106   For the transmit path the following opcodes exist:
 107
 108    TX_SETUP: for setting up and modifying transmission requests
 109    TX_DELETE: to remove send requests
 110    TX_READ: to read out the current broadcasting commands
 111             (for debugging purposes)
 112    TX_SEND: for sending a single CAN message
 113
 114   For the receive path the following opcodes exist:
 115
 116    RX_SETUP: for setting and modifying receive filters
 117    RX_DELETE: for deleting receive filters
 118    RX_READ: to read out the current receive filter (for debugging purposes)
 119
 120   The Broadcast-Manager sends response messages in the same form. The
 121   BCM sends these opcodes:
 122
 123    TX_STATUS: in response to TX_READ
 124    TX_EXPIRED: is sent when the counter count reaches ival1 (only if
 125                flag TX_COUNTEVT is set, see below)
 126
 127    RX_STATUS: in response to RX_READ
 128    RX_TIMEOUT: sent if the time-controlled reception of a message failed
 129    RX_CHANGED: sent if the first or a revised CAN message was received
 130
 131   Each of these opcode needs CAN ID specified either in the "can_id" field or
 132   in the first can_frame structure attached to the command.
 133
 134   In addition, there are optional flags which can influence the BCM behavior:
 135
 136    SETTIMER: set the value of ival1, ival2 and count
 137    STARTTIMER: start the timer with the actual value of ival1, ival2 and count.
 138         Starting the timer leads simultaneously to the transmission of a can_frame
 139    TX_COUNTEVT: create the message TX_EXPIRED when count is reached
 140    TX_ANNOUNCE: a change of data by the process is emitted with a new frame,
 141         regardless of the timer status
 142    TX_CP_CAN_ID: copies the can_id from the message header attached to each
 143         of can_frame. This is intended only as usage simplification
 144    TX_RESET_MULTI_IDX: forces a reset of the index counter from the update
 145         to be sent by multiplex message even if it would not be necessary
 146         because of the length
 147    RX_FILTER_ID: there is no filtering of the user data. A match with the
 148         received message can_id automatically leads to a RX_CHANGED. Use
 149         caution in cyclic messages. If RX_FILTER_ID flag is set, the CAN frame
 150         in RX_SETUP can be ignored (i.e., nframes = 0)
 151    RX_RTR_FRAME: the filter passed is used as CAN message to be sent when
 152         receiving an RTR frame
 153    RX_CHECK_DLC: a change of the DLC leads to an RX_CHANGED message to the user
 154         application
 155    RX_NO_AUTOTIMER: if the timer ival1 in the RX_SETUP has been set equal to
 156         zero, on receipt of the CAN message the timer for the timeout
 157         monitoring is automatically started. Setting this flag prevents the
 158         automatic reset of the start timer
 159    RX_ANNOUNCE_RESUME: refers also to the time-out supervision of RX_SETUP. By
 160         setting this flag, when an RX-outs occours, a RX_CHANGED will be
 161         generated when the (cyclic) receive restarts. This will happen even
 162         if the user data have not changed
 163
 164   1.3 TX_SETUP opcode
 165   1.4 TX_DELETE opcode
 166
 167   This opcode will delete the entry for transmission of the CAN frame with
 168   the specified can_id CAN identifier. The message length for the command
 169   TX_DELETE is sizeof(bcm_msg_head) (only the header).
 170
 171   1.5 TX_READ opcode
 172   1.6 TX_SEND opcode
 173   1.7 RX_SETUP opcode
 174   1.8 RX_DELETE opcode
 175   1.9 RX_READ opcode
 176