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