1 ============================================================================
3 can-bcm.txt : Broadcast Manager API
5 Part of the documentation for the socketCAN subsystem
9 1 Broadcast Manager protocol sockets (SOCK_DGRAM)
10 1.1 Opening BCM sockets
11 1.2 BCM messages (struct bcm_msg_head)
20 ============================================================================
22 1. Broadcast Manager protocol sockets (SOCK_DGRAM)
23 --------------------------------------------------
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.
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
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
38 - One-time transmission of CAN messages
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
44 - RTR replies to messages
45 - Time-out monitoring of frames
46 - Frequency reduction of messages (throttle function) to the user
49 1.1 Opening BCM sockets
51 To use Broadcast-Manager include the file "bcm.h".
52 A socket for Broadcast-Manager is created with:
54 s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
56 The CAN interface is assigned with a call to connect() on the socket.
58 addr.can_family = AF_CAN;
59 strcpy(ifr.ifr_name, "can0");
60 ioctl(s, SIOCGIFINDEX, &ifr);
61 addr.can_ifindex = ifr.ifr_ifindex;
63 connect(s, (struct sockaddr *)&addr, sizeof(addr));
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.
72 1.2 BCM messages (struct bcm_msg_head)
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:
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];
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:
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)));
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.
103 The transmit and receive path of the BCM are two independent functional
106 For the transmit path the following opcodes exist:
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
114 For the receive path the following opcodes exist:
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)
120 The Broadcast-Manager sends response messages in the same form. The
121 BCM sends these opcodes:
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)
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
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.
134 In addition, there are optional flags which can influence the BCM behavior:
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
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
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).