busmust_sys/api.rs
1use types::*;
2use std::os::raw::{c_char, c_int, c_ushort, c_void};
3
4#[cfg(target_arch = "x86_64")]
5#[link(name = "bmapi64")]
6#[allow(non_snake_case)]
7extern "C" {
8 /// Initialize BM API library, this function shall be called before any other API calls and shall only be called once.
9 ///
10 /// returns: [BMStatus]
11 ///
12 pub fn BM_Init() -> BMStatus;
13
14 /// Un-initialize BM API library, this function shall be called after any other API calls and shall only be called once.
15 ///
16 /// returns: [BMStatus]
17 ///
18 pub fn BM_UnInit() -> BMStatus;
19
20 /// Enumerate all connected Busmust device.
21 ///
22 /// # Arguments
23 ///
24 /// * `channel_infos`: An array of [BMChannelInfo] structure which holds info of all the enumerated Busmust devices.
25 /// * `n_channels`: Number of device channels available, which is also the number of valid entries in `channel_infos`,
26 /// this param must be initialized with the maximum length of the `channel_infos` array when calling this function.
27 ///
28 /// returns: [BMStatus]
29 ///
30 pub fn BM_Enumerate(channel_infos: *mut BMChannelInfo, n_channels: *mut c_int) -> BMStatus;
31
32 /// Open the specified CAN device port.
33 ///
34 /// # Arguments
35 ///
36 /// * `port`: Index of the port, starting from zero, note this is the index of all enumerated ports.
37 ///
38 /// returns: Handle to the opened CAN device channel, return NULL if failed to open the specified port.
39 ///
40 pub fn BM_OpenCan(port: c_ushort) -> *const c_void;
41
42 /// Open the specified device port using given configuration.
43 ///
44 /// # Arguments
45 ///
46 /// * `handle`: Handle to the opened device channel.
47 /// * `channel_info`: Info of the device channel to open, usually the info is filled by [BM_Enumerate].
48 /// * `mode`: CAN operation mode option of the opened channel, see [BMCanMode] for details.
49 /// * `term`: Terminal resistor option of the opened channel, see [BMTerminalResistor] for details.
50 /// * `bit_rate`: Bitrate option of the opened channel, see [BMBitrate] for details.
51 /// * `rx_filter_list`: CAN acceptance filters option of the opened channel, see [BMRxFilter] for details.
52 /// * `rc_filter_count`: Number of acceptance filters, usually there could be up to 2 filters.
53 ///
54 /// returns: [BMStatus]
55 ///
56 pub fn BM_OpenEx(handle: *mut *mut c_void, channel_info: *const BMChannelInfo,
57 mode: BMCanMode, term: BMTerminalResistor, bit_rate: *const BMBitrate,
58 rx_filter_list: *const BMRxFilter, rc_filter_count: c_int) -> BMStatus;
59
60 /// Close an opened channel.
61 ///
62 /// # Arguments
63 ///
64 /// * `channel_handle`: Handle to the channel to be closed.
65 ///
66 /// returns: [BMStatus]
67 ///
68 pub fn BM_Close(channel_handle: *const c_void) -> BMStatus;
69
70 /// Reset an opened channel.
71 /// The configuration options will not lost when the channel is reset, so [BM_Reset] is basically identical to [BM_Close] and then [BM_OpenEx].
72 ///
73 /// # Arguments
74 ///
75 /// * `channel_handle`: Handle to the channel to be reset.
76 ///
77 /// returns: [BMStatus]
78 ///
79 pub fn BM_Reset(channel_handle: *const c_void) -> BMStatus;
80
81 /// Activate an opened channel, and thus goes on bus for the selected port and channels.
82 /// At this point, the user can transmit and receive messages on the bus.
83 /// Channel is default to be activated after [BM_OpenEx] is called.
84 ///
85 /// # Arguments
86 ///
87 /// * `channel_handle`: Handle to the channel to be activated.
88 ///
89 /// returns: [BMStatus]
90 ///
91 pub fn BM_Activate(channel_handle: *const c_void) -> BMStatus;
92
93 /// Deactivate an opened channel, and thus the selected channels goes off the bus and stay in BUSOFF state until re-activation.
94 /// Any call to [BM_Write] or [BM_Read] will return [BMStatus::BusOff] immediately if the channel is deactivated.
95 ///
96 /// # Arguments
97 ///
98 /// * `channel_handle`: Handle to the channel to be deactivated.
99 ///
100 /// returns: [BMStatus]
101 ///
102 pub fn BM_Deactivate(channel_handle: *const c_void) -> BMStatus;
103
104 /// Clear TX&RX message buffer of an opened channel.
105 /// This function is available since BM API 1.3, hardware status will not be changed when clearing buffer.
106 ///
107 /// # Arguments
108 ///
109 /// * `channel_handle`: Handle to the channel to be cleared.
110 ///
111 /// returns: [BMStatus]
112 ///
113 pub fn BM_ClearBuffer(channel_handle: *const c_void) -> BMStatus;
114
115 /// Read a message/event out of the given channel.
116 /// This function is non-blocked, and thus will return [BMStatus::ReceiveBufferEmpty] if no message is received.
117 /// Please use notifications to wait for RX events and then read message/event out of BM API internal RX buffer, otherwise you could also poll the device periodically.
118 ///
119 /// # Arguments
120 ///
121 /// * `channel_handle`: Handle to the channel to read from.
122 /// * `data`: A caller-allocated buffer to hold the message/event output, see [BMData] for details.
123 ///
124 /// returns: [BMStatus]
125 ///
126 pub fn BM_Read(channel_handle: *const c_void, data: *const BMData) -> BMStatus;
127
128
129 /// Read multiple messages/events out of the given channel.
130 ///
131 /// # Arguments
132 ///
133 /// * `channel_handle`: Handle to the channel to read from.
134 /// * `data`: A caller-allocated buffer to hold the messages/events array output, see [BMData] for details.
135 /// * `n_messages`: Number of read messages, user shall initialize this param with the size (in messages) of the data buffer.
136 /// * `timeout`: Timeout (in milliseconds) before the message is received successfully from the bus.
137 /// Set any negative number (i.e. -1) to wait infinitely.
138 /// Set 0 if you would like to receive asynchronously: read from BM API internal buffer and return immediately, use [BM_WaitForNotifications] before reading.
139 ///
140 /// returns: [BMStatus]
141 ///
142 pub fn BM_ReadMultiple(channel_handle: *const c_void, data: *const BMData, n_messages: *mut c_int, timeout: c_int) -> BMStatus;
143
144 /// Read data block using ISO-TP protocol.
145 /// This API enables rapid transmission using ISO-TP without app intervention.
146 ///
147 /// # Arguments
148 ///
149 /// * `channel_handle`: Handle to the channel to read from.
150 /// * `data`: A caller-allocated buffer to hold the data.
151 /// * `n_bytes`: Length of the received data block, in bytes. Caller must initialize this argument with the size of the caller-allocated buffer.
152 /// * `timeout`: Timeout (in milliseconds) before the message is received successfully from the bus.
153 /// Set any negative number (i.e. -1) to wait infinitely.
154 /// Set 0 if you would like to receive asynchronously: read from BM API internal buffer and return immediately, use [BM_WaitForNotifications] before reading.
155 /// * `config`: ISO-TP configuration used by current transfer.
156 ///
157 /// returns: [BMStatus]
158 ///
159 pub fn BM_ReadIsotp(channel_handle: *const c_void, data: *const u8, n_bytes: *mut c_int, timeout: c_int, config: *const BMIsotpConfig) -> BMStatus;
160
161 /// Read CAN message out of the given channel.
162 /// Note this function is a simple wrapper of [BM_Read], see [BM_Read] for details.
163 ///
164 /// # Arguments
165 ///
166 /// * `channel_handle`: Handle to the channel to read from.
167 /// * `msg`: A caller-allocated buffer to hold the CAN message output, see [BMCanMessage] for details.
168 /// * `channel`: The source channel ID from which the message is received, starting from zero, could be NULL if not required.
169 /// * `timestamp`: The device local high precision timestamp in microseconds, when the message is physically received on the CAN bus, could be NULL if not required.
170 ///
171 /// returns: [BMStatus]
172 ///
173 pub fn BM_ReadCanMessage(channel_handle: *const c_void, msg: *mut BMCanMessage, channel: *mut c_int, timestamp: *mut c_int) -> BMStatus;
174
175 /// Read multiple CAN messages out of the given channel.
176 /// This function is non-blocked, and thus will return [BMStatus::ReceiveBufferEmpty] if not all messages are received.
177 /// Please use notifications to wait for RX events and then read message/event out of BM API internal RX buffer, otherwise you could also poll the device periodically.
178 ///
179 /// # Arguments
180 ///
181 /// * `channel_handle`: Handle to the channel to read from.
182 /// * `msgs`: A caller-allocated buffer to hold the CAN message array output, see [BMCanMessage] for details.
183 /// * `n_messages`: Number of read messages, user shall initialize this param with the size (in messages) of the data buffer.
184 /// * `timeout`: Timeout (in milliseconds) before the message is received successfully from the bus.
185 /// Set any negative number (i.e. -1) to wait infinitely.
186 /// Set 0 if you would like to receive asynchronously: read from BM API internal buffer and return immediately, use [BM_WaitForNotifications] before reading.
187 /// * `channels`: The source channel ID from which the message is received, starting from zero, could be NULL if not required.
188 /// * `timestamps`: The device local high precision timestamp array in microseconds, when the message is physically transmitted on the CAN bus, could be NULL if not required.
189 ///
190 /// returns: [BMStatus]
191 ///
192 pub fn BM_ReadMultipleCanMessage(channel_handle: *const c_void, msgs: *mut BMCanMessage, n_messages: *mut c_int, timeout: c_int, channels: *mut c_int, timestamps: *mut c_int) -> BMStatus;
193
194 /// Write a message/event to the given channel.
195 ///
196 /// # Arguments
197 ///
198 /// * `channel_handle`: Handle to the channel to write to.
199 /// * `data`: A caller-allocated buffer to hold the message/event input, see [BMData] for details.
200 /// * `timeout`: Timeout (in milliseconds) before the message is transmitted successfully to the bus.
201 /// Set any negative number (i.e. -1) to wait infinitely.
202 /// Set 0 if you would like to transmit asynchronously: put to BM API internal buffer and return immediately, then receive `TXCMPLT` event over [BM_Read] later.
203 /// * `timestamp`: The device local high precision timestamp in microseconds, when the message is physically transmitted on the CAN bus, could be NULL if not required.
204 ///
205 /// returns: BMStatus
206 ///
207 pub fn BM_Write(channel_handle: *const c_void, data: *const BMData, timeout: c_int, timestamp: *mut c_int) -> BMStatus;
208
209 /// Write multiple messages/events to the given channel.
210 /// This function is allowed to be called from multiple threads since BM API 1.3.
211 ///
212 /// # Arguments
213 ///
214 /// * `channel_handle`: Handle to the channel to write to.
215 /// * `msgs`: A caller-allocated buffer to hold the messages/events array input, see [BMData] for details.
216 /// * `n_messages` Number of written messages, user shall initialize this param with the size (in messages) of the data buffer.
217 /// * `timeout`: Timeout (in milliseconds) before the message is transmitted successfully to the bus.
218 /// Set any negative number (i.e. -1) to wait infinitely.
219 /// Set 0 if you would like to transmit asynchronously: put to BM API internal buffer and return immediately, then receive `TXCMPLT` event over [BM_Read] later.
220 /// * `timestamp`: The device local high precision timestamp array in microseconds, when the message is physically transmitted on the CAN bus, could be NULL if not required.
221 ///
222 /// returns: [BMStatus]
223 ///
224 pub fn BM_WriteMultiple(channel_handle: *const c_void, msgs: *const BMData, n_messages: *mut c_int, timeout: c_int, timestamps: *mut c_int) -> BMStatus;
225
226
227 /// Write data block using ISO-TP protocol.
228 /// This API enables rapid transmission using ISO-TP without app intervention.
229 ///
230 /// # Arguments
231 ///
232 /// * `channel_handle`: Handle to the channel to write to.
233 /// * `data`: A caller-allocated buffer to hold the data to be sent.
234 /// * `n_bytes`: Length of the data block, in bytes.
235 /// * `timeout`: Timeout (in milliseconds) before any message segment is transmitted successfully to the bus.
236 /// Note this is only for bus level timeout waiting for CAN ACK, for setting ISO-TP protocol timeouts, see [BMIsotpConfig].
237 /// * `config`: ISO-TP configuration used by current transfer.
238 ///
239 /// returns: [BMStatus]
240 ///
241 pub fn BM_WriteIsotp(channel_handle: *const c_void, data: *const u8, n_bytes: c_int, timeout: c_int, config: *const BMIsotpConfig) -> BMStatus;
242
243 /// Write CAN message to the given channel.
244 /// Note this function is a simple wrapper to [BM_Write], see [BM_Write] for details.
245 ///
246 /// # Arguments
247 ///
248 /// * `channel_handle`: Handle to the channel to write to.
249 /// * `msg`: A caller-allocated buffer to hold the CAN message output, see [BMCanMessage] for details.
250 /// * `reserved`: The target channel ID to which the message is transmitted, starting from zero. This parameter is reserved for future, always 0 now.
251 /// * `timeout`: Timeout (in milliseconds) before the message is transmitted successfully to the bus.
252 /// Set any negative number (i.e. -1) to wait infinitely.
253 /// Set 0 if you would like to transmit asynchronously: put to BM API internal buffer and return immediately, then receive `TXCMPLT` event over [BM_Read] later.
254 /// * `timestamp`: The device local high precision timestamp in microseconds, when the message is physically transmitted on the CAN bus, could be NULL if not required.
255 ///
256 /// returns: BMStatus
257 ///
258 pub fn BM_WriteCanMessage(channel_handle: *const c_void, msg: *const BMCanMessage, reserved: c_int, timeout: c_int, timestamp: *mut c_int) -> BMStatus;
259
260 /// Write multiple CAN messages to the given channel.
261 /// This function is allowed to be called from multiple threads since BM API 1.3.
262 ///
263 /// # Arguments
264 ///
265 /// * `channel_handle`: Handle to the channel to write to.
266 /// * `msgs`: A caller-allocated buffer to hold the CAN message array input, see [BMCanMessage] for details.
267 /// * `n_messages`: Number of written messages, user shall initialize this param with the size (in messages) of the data buffer.
268 /// * `reserved`: The target channel ID to which the message is transmitted, starting from zero. This parameter is reserved for future, set to NULL.
269 /// * `timeout`: Timeout (in milliseconds) before the message is transmitted successfully to the bus.
270 /// Set any negative number (i.e. -1) to wait infinitely.
271 /// Set 0 if you would like to transmit asynchronously: put to BM API internal buffer and return immediately, then receive `TXCMPLT` event over [BM_Read] later.
272 /// * `timestamp`: The device local high precision timestamp array in microseconds, when the message is physically transmitted on the CAN bus, could be NULL if not required.
273 ///
274 /// returns: BMStatus
275 ///
276 pub fn BM_WriteMultipleCanMessage(channel_handle: *const c_void, msgs: *const BMCanMessage, n_messages: *mut c_int, reserved: c_int, timeout: c_int, timestamps: *mut c_int) -> BMStatus;
277
278 /// Get current CAN status of the given channel.
279 ///
280 /// # Arguments
281 ///
282 /// * `channel_handle`: Handle to the channel to operate on.
283 /// * `status_info`: Detailed information of current CAN status, see [BMCanStatusInfo] for details.
284 ///
285 /// returns: [BMStatus]
286 ///
287 pub fn BM_GetStatus(channel_handle: *const c_void, status_info: *mut BMCanStatusInfo) -> BMStatus;
288
289 /// Get current local high precision device timestamp, in microseconds.
290 ///
291 /// # Arguments
292 ///
293 /// * `channel_handle`: Handle to the channel to operate on.
294 /// * `timestamp`: Timestamp value.
295 ///
296 /// returns: [BMStatus]
297 ///
298 pub fn BM_GetTimestamp(channel_handle: *const c_void, timestamp: *mut c_int) -> BMStatus;
299
300 /// Set CAN mode option of the given channel.
301 ///
302 /// # Arguments
303 ///
304 /// * `channel_handle`: Handle to the channel to operate on.
305 /// * `mode`: Expected CAN mode, see [BMCanMode] for details.
306 ///
307 pub fn BM_SetCanMode(channel_handle: *const c_void, mode: BMCanMode) -> BMStatus;
308
309 /// Set terminal resistor option of the given channel.
310 ///
311 /// # Arguments
312 ///
313 /// * `channel_handle`: Handle to the channel to operate on.
314 /// * `tres`: Expected terminal resistor value, see [BMTerminalResistor] for details.
315 ///
316 /// returns: [BMStatus]
317 ///
318 pub fn BM_SetTerminalRegister(channel_handle: *const c_void, tres: BMTerminalResistor) -> BMStatus;
319
320 /// Set bitrate option of the given channel.
321 ///
322 /// # Arguments
323 ///
324 /// * `channel_handle`: Handle to the channel to operate on.
325 /// * `bitrate`: Expected bitrate, see [BMBitrate] for details.
326 ///
327 /// returns: [BMStatus]
328 ///
329 pub fn BM_SetBitrate(channel_handle: *const c_void, bitrate: *const BMBitrate) -> BMStatus;
330
331 /// Set TX tasks option of the given channel.
332 ///
333 /// # Arguments
334 ///
335 /// * `channel_handle`: Handle to the channel to operate on.
336 /// * `tx_tasks`: An array of TX task information, see [BMTxTask] for details.
337 /// * `n_tx_tasks`: Number of valid TX tasks in the array.
338 ///
339 /// returns: [BMStatus]
340 ///
341 pub fn BM_SetTxTasks(channel_handle: *const c_void, tx_tasks: *const BMTxTask, n_tx_tasks: c_int) -> BMStatus;
342
343 /// Set RX filters option of the given channel.
344 ///
345 /// # Arguments
346 ///
347 /// * `channel_handle`: Handle to the channel to operate on.
348 /// * `rx_filters`: An array of RX filter information, see [BMRxFilter] for details.
349 /// * `n_rx_filters`: Number of valid RX filters in the array.
350 ///
351 /// returns: [BMStatus]
352 ///
353 pub fn BM_SetRxFilters(channel_handle: *const c_void, rx_filters: *const BMRxFilter, n_rx_filters: c_int) -> BMStatus;
354
355 /// Get the platform/OS independent notification handle for the given channel, so that the application could wait for notifications later.
356 ///
357 /// # Arguments
358 ///
359 /// * `channel_handle`: Handle to the channel that owns the notification handle.
360 /// * `notification`: The platform/OS independent notification handle.
361 ///
362 /// returns: [BMStatus]
363 ///
364 pub fn BM_GetNotification(channel_handle: *const c_void, notification: *mut *mut c_void) -> BMStatus;
365
366
367 /// A platform/OS independent implementation to wait for single/multiple notification handles.
368 ///
369 /// # Arguments
370 ///
371 /// * `handles`: An array of channel notification handles.
372 /// * `n_handles`: Number of valid notification handles.
373 /// * `timeout_ms`: This function will block the current thread for at most `timeout_ms` milliseconds if no notification is received.
374 ///
375 /// returns: This function returns an index into the handles array for which a notification has been received.
376 ///
377 pub fn BM_WaitForNotifications(handles: *const *const c_void, n_handles: c_int, timeout_ms: c_int) -> c_int;
378
379
380 /// Translate error code to string, this is a helper function to ease application programming.
381 ///
382 /// # Arguments
383 ///
384 /// * `status`: The error code to be translated.
385 /// * `buffer`: A caller-allocated string buffer to hold the translated string.
386 /// * `length`: Number in bytes of the string buffer.
387 /// * `reserved`: Reserved.
388 ///
389 pub fn BM_GetErrorText(status: BMStatus, buffer: *mut c_char, length: usize, reserved: c_ushort);
390
391 /// Translate data (i.e. CAN message) to string, this is a helper function to ease application programming.
392 ///
393 /// # Arguments
394 ///
395 /// * `data`: The message data to be translated.
396 /// * `buffer`: A caller-allocated string buffer to hold the translated string.
397 /// * `length`: Number in bytes of the string buffer.
398 /// * `reserved`: Reserved.
399 ///
400 pub fn BM_GetDataText(data: *const BMData, buffer: *mut c_char, length: usize, reserved: c_ushort);
401
402 /// Set library log level.
403 ///
404 /// # Arguments
405 ///
406 /// * `level`: Target log level, all messages equal to or less than this level will be printed on debug console.
407 ///
408 pub fn BM_SetLogLevel(level: BMLogLevel);
409
410 /// Get library log level.
411 ///
412 /// returns: Current log level, all messages equal to or less than this level are currently printed on debug console.
413 ///
414 pub fn BM_GetLogLevel() -> BMLogLevel;
415}