1 /**
2 \defgroup can_interface_gr CAN Interface
3 \brief Driver API for CAN Bus Peripheral (%Driver_CAN.h)
4 \details
5
6 The <b>Controller Area Network</b> Interface Bus (CAN) implements a multi-master serial bus for connecting
7 microcontrollers and devices, also known as nodes, to communicate with each other in applications without a host computer.
8 CAN is a message-based protocol, designed originally for automotive applications, but meanwhile used also in many other surroundings.
9 The complexity of the node can range from a simple I/O device up to an embedded computer with a CAN interface and sophisticated software.
10 The node may also be a gateway allowing a standard computer to communicate over a USB or Ethernet port to the devices on a CAN network.
11 Devices are connected to the bus through a host processor, a CAN controller, and a CAN transceiver.
12
13
14 The CAN Driver API allows to implement CAN Interfaces that conform to the
15 <a href="https://www.bosch-semiconductors.com/" target="_blank">
16 CAN specifications available from BOSCH</a>:
17 - CAN 2.0B: CAN Specification 2.0B (released Sep. 1991) which is now superseded by ISO 11898-1.
18 - CAN FD: CAN with Flexible Data Rate introduced in 2012 (released April 17th, 2012).
19
20 Wikipedia offers more information about the <a href="https://en.wikipedia.org/wiki/CAN_bus" target="_blank"><b>CAN Bus</b></a>.
21
22 **CAN 2.0B**
23 Every CAN CMSIS-Driver supports the CAN 2.0B standard
24
25 CAN 2.0B supports:
26 - message can contain up to 8 data bytes
27 - bitrates of up to 1Mbits/s
28 - \ref Remote_Frame requests
29
30 \anchor CAN_FD
31 <b>CAN FD</b>
32
33 Support for CAN FD depends on the hardware.
34 A CMSIS-Driver that supports CAN FD has the capability \ref ARM_CAN_CAPABILITIES data field \b fd_mode = \token{1}, which can be
35 retrieved with the function \ref ARM_CAN_GetCapabilities.
36
37 CAN FD supports:
38 - message can contain up to 64 data bytes
39 - faster data transfers with faster bitrate used during the data phase
40
41 CAN FD does not support \ref Remote_Frame requests.
42
43 <b>Block Diagram</b>
44
45 The CAN Driver API defines a <b>CAN</b> interface for middleware components. The CAN Driver supports multiple
46 nodes, which are able to send and receive messages, but not simultaneously.
47
48 \image html CAN_Node.png "CAN Node Schematic"
49
50 CAN API
51 -------
52
53 The following header files define the Application Programming Interface (API) for the CAN interface:
54 - \b %Driver_CAN.h : Driver API for CAN Bus Peripheral
55
56 The driver implementation is a typical part of the Device Family Pack (DFP) that supports the
57 peripherals of the microcontroller family.
58
59
60 <b>Driver Functions</b>
61
62 The driver functions are published in the access struct as explained in \ref DriverFunctions
63 - \ref ARM_DRIVER_CAN : access struct for CAN driver functions
64
65 <b>Example Code</b>
66
67 The following example code shows the usage of the CAN interface.
68
69 \code
70
71 #include <stdio.h>
72 #include <string.h>
73 #include "cmsis_os.h"
74
75 #include "Driver_CAN.h"
76
77 // CAN Driver Controller selector
78 #define CAN_CONTROLLER 1 // CAN Controller number
79
80 #define _CAN_Driver_(n) Driver_CAN##n
81 #define CAN_Driver_(n) _CAN_Driver_(n)
82 extern ARM_DRIVER_CAN CAN_Driver_(CAN_CONTROLLER);
83 #define ptrCAN (&CAN_Driver_(CAN_CONTROLLER))
84
85 uint32_t rx_obj_idx = 0xFFFFFFFFU;
86 uint8_t rx_data[8];
87 ARM_CAN_MSG_INFO rx_msg_info;
88 uint32_t tx_obj_idx = 0xFFFFFFFFU;
89 uint8_t tx_data[8];
90 ARM_CAN_MSG_INFO tx_msg_info;
91
92 static void Error_Handler (void) { while (1); }
93
94 void CAN_SignalUnitEvent (uint32_t event) {}
95
96 void CAN_SignalObjectEvent (uint32_t obj_idx, uint32_t event) {
97
98 if (obj_idx == rx_obj_idx) { // If receive object event
99 if (event == ARM_CAN_EVENT_RECEIVE) { // If message was received successfully
100 if (ptrCAN->MessageRead(rx_obj_idx, &rx_msg_info, rx_data, 8U) > 0U) {
101 // Read received message
102 // process received message ...
103 }
104 }
105 }
106 if (obj_idx == tx_obj_idx) { // If transmit object event
107 if (event == ARM_CAN_EVENT_SEND_COMPLETE) { // If message was sent successfully
108 // acknowledge sent message ...
109 }
110 }
111 }
112
113 int main (void) {
114 ARM_CAN_CAPABILITIES can_cap;
115 ARM_CAN_OBJ_CAPABILITIES can_obj_cap;
116 int32_t status;
117 uint32_t i, num_objects;
118
119 can_cap = ptrCAN->GetCapabilities (); // Get CAN driver capabilities
120 num_objects = can_cap.num_objects; // Number of receive/transmit objects
121
122 status = ptrCAN->Initialize (CAN_SignalUnitEvent, CAN_SignalObjectEvent); // Initialize CAN driver
123 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
124
125 status = ptrCAN->PowerControl (ARM_POWER_FULL); // Power-up CAN controller
126 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
127
128 status = ptrCAN->SetMode (ARM_CAN_MODE_INITIALIZATION); // Activate initialization mode
129 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
130
131 status = ptrCAN->SetBitrate (ARM_CAN_BITRATE_NOMINAL, // Set nominal bitrate
132 100000U, // Set bitrate to 100 kbit/s
133 ARM_CAN_BIT_PROP_SEG(5U) | // Set propagation segment to 5 time quanta
134 ARM_CAN_BIT_PHASE_SEG1(1U) | // Set phase segment 1 to 1 time quantum (sample point at 87.5% of bit time)
135 ARM_CAN_BIT_PHASE_SEG2(1U) | // Set phase segment 2 to 1 time quantum (total bit is 8 time quanta long)
136 ARM_CAN_BIT_SJW(1U)); // Resynchronization jump width is same as phase segment 2
137 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
138
139 for (i = 0U; i < num_objects; i++) { // Find first available object for receive and transmit
140 can_obj_cap = ptrCAN->ObjectGetCapabilities (i); // Get object capabilities
141 if ((rx_obj_idx == 0xFFFFFFFFU) && (can_obj_cap.rx == 1U)) { rx_obj_idx = i; }
142 else if ((tx_obj_idx == 0xFFFFFFFFU) && (can_obj_cap.tx == 1U)) { tx_obj_idx = i; break; }
143 }
144 if ((rx_obj_idx == 0xFFFFFFFFU) || (tx_obj_idx == 0xFFFFFFFFU)) { Error_Handler(); }
145
146 // Set filter to receive messages with extended ID 0x12345678 to receive object
147 status = ptrCAN->ObjectSetFilter(rx_obj_idx, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x12345678U), 0U);
148 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
149
150 status = ptrCAN->ObjectConfigure(tx_obj_idx, ARM_CAN_OBJ_TX); // Configure transmit object
151 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
152
153 status = ptrCAN->ObjectConfigure(rx_obj_idx, ARM_CAN_OBJ_RX); // Configure receive object
154 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
155
156 status = ptrCAN->SetMode (ARM_CAN_MODE_NORMAL); // Activate normal operation mode
157 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
158
159 memset(&tx_msg_info, 0U, sizeof(ARM_CAN_MSG_INFO)); // Clear message info structure
160 tx_msg_info.id = ARM_CAN_EXTENDED_ID(0x12345678U); // Set extended ID for transmit message
161 tx_data[0] = 0xFFU; // Initialize transmit data
162 while (1) {
163 tx_data[0]++; // Increment transmit data
164 status = ptrCAN->MessageSend(tx_obj_idx, &tx_msg_info, tx_data, 1U); // Send data message with 1 data byte
165 if (status != 1U) { Error_Handler(); }
166 for (i = 0U; i < 1000000U; i++) { __nop(); } // Wait a little while
167 }
168 }
169 \endcode
170
171
172 \section can_objects CAN Message Objects
173
174 The CMSIS-Driver for the CAN interface provides multiple CAN message objects, which can be seen as individual communication channels.
175 The number of available CAN message objects depends on the CAN peripheral. The function \ref ARM_CAN_GetCapabilities returns
176 the maximum number of available CAN message objects. The number is encoded in the structure \ref ARM_CAN_CAPABILITIES in the data field \em num_objects.
177 CAN message objects are addressed with the functions listed below, whereby the parameter \em obj_idx addresses an individual object.
178 The valid range for \em obj_idx is \token{[0 .. (\em num_objects - 1)]}.
179
180 Function | Description
181 :----------------------------------|:--------------------------------------------
182 \ref ARM_CAN_ObjectGetCapabilities | Retrieves message object capabilities such as receive, transmit, \ref Remote_Frame automatic handling and \ref can_filtering.
183 \ref ARM_CAN_ObjectSetFilter | Allows to set-up CAN ID filtering for the message object.
184 \ref ARM_CAN_ObjectConfigure | Allows to configure the message object for receive, transmit or \ref Remote_Frame automatic handling.
185 \ref ARM_CAN_MessageRead | Read received message from the message object.
186 \ref ARM_CAN_MessageSend | Send CAN message or send \ref Remote_Frame or set CAN message to be sent automatically on reception of matching \ref Remote_Frame on the message object.
187 \ref ARM_CAN_SignalObjectEvent | Callback function that signals a message transfer or a received message overrun.
188
189 Each CAN message object may have different capabilities. Before using a CAN message object, call the
190 function \ref ARM_CAN_ObjectGetCapabilities to verify the available features.
191
192
193 \section can_filtering CAN Message Filtering
194
195 The CMSIS-Driver for the CAN interface supports ID filtering for the receiving message objects. The receiving CAN node examines the identifier
196 to decide if it was relevant. This filtering is done by the CAN peripheral according the settings configured with the function \ref ARM_CAN_ObjectSetFilter.
197
198 The function \ref ARM_CAN_ObjectGetCapabilities retrieves the filter capabilities of the CAN message objects stored in \ref ARM_CAN_OBJ_CAPABILITIES.
199
200 Data Fields | CAN Messages Object can be filtered with ...
201 :--------------------------|:--------------------------------------------
202 \em exact_filtering | an exact ID value set by using the function \ref ARM_CAN_ObjectSetFilter with \em control = \ref ARM_CAN_FILTER_ID_EXACT_ADD.
203 \em range_filtering | a range ID value set by using the function \ref ARM_CAN_ObjectSetFilter with \em control = \ref ARM_CAN_FILTER_ID_RANGE_ADD.
204 \em mask_filtering | a mask ID value set by as using the function \ref ARM_CAN_ObjectSetFilter with \em control = \ref ARM_CAN_FILTER_ID_MASKABLE_ADD.
205 \em multiple_filters | ... several filters to capture multiple ID values, or ID value ranges.
206
207 <b>CAN message filtering using an exact ID</b>
208
209 Example: accept in message object #1 only frames with extended ID = 0x1567.
210 \code
211 status = ptrCAN->ObjectSetFilter (1, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x1567), 0);
212 if (status != ARM_DRIVER_OK) ... // error handling
213 \endcode
214
215 Example: accept in message object #2 frames with extended ID = 0x3167 and extended ID = 0x42123.
216 \code
217 status = ptrCAN->ObjectSetFilter (2, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x3167), 0);
218 if (status != ARM_DRIVER_OK) ... // error handling
219 status = ptrCAN->ObjectSetFilter (2, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x42123), 0);
220 if (status != ARM_DRIVER_OK) ... // error handling
221 \endcode
222
223 <b>CAN message filtering using a range ID</b>
224
225 Example: accept in message object #3 only frames with extended ID >= 0x1567 and extended ID <= 0x1577.
226 \code
227 status = ptrCAN->ObjectSetFilter (3, ARM_CAN_FILTER_ID_RANGE_ADD, ARM_CAN_EXTENDED_ID(0x1567), ARM_CAN_EXTENDED_ID(0x1577));
228 if (status != ARM_DRIVER_OK) ... // error handling
229 \endcode
230
231
232 <b>CAN message filtering using a mask ID</b>
233
234 Using the function \ref ARM_CAN_ObjectSetFilter with \em control = \ref ARM_CAN_FILTER_ID_MASKABLE_ADD allows to specify with \em arg a mask value.
235 - if a mask bit is \token{0}, the corresponding \em ID bit will be accepted, regardless of the value.
236 - if a mask bit is \token{1}, the corresponding \em ID bit will be compared with the value of the ID filter bit; if they match the message will be accepted otherwise the frame is rejected.
237
238 Example: accept in message object #0 only frames with extended IDs 0x1560 to 0x156F.
239 \code
240 status = ptrCAN->ObjectSetFilter (0, ARM_CAN_FILTER_ID_MASKABLE_ADD, ARM_CAN_EXTENDED_ID(0x1560), 0x1FFFFFF0);
241 if (status != ARM_DRIVER_OK) ... // error handling
242 \endcode
243
244 Example: accept in message object #2 only frames with extended IDs 0x35603, 0x35613, 0x35623, and 0x35633.
245 \code
246 status = ptrCAN->ObjectSetFilter (2, ARM_CAN_FILTER_ID_MASKABLE_ADD, ARM_CAN_EXTENDED_ID(0x35603), 0x1FFFFFCF);
247 if (status != ARM_DRIVER_OK) ... // error handling
248 \endcode
249
250 Example: accept any message in object #4 regardless of the ID.
251 \code
252 status = ptrCAN->ObjectSetFilter (4, ARM_CAN_FILTER_ID_MASKABLE_ADD, ARM_CAN_EXTENDED_ID(0), 0);
253 if (status != ARM_DRIVER_OK) ... // error handling
254 \endcode
255
256 \section Remote_Frame Remote Frame
257
258 In general, data transmission is performed on an autonomous basis with the data source node sending out Data Frames.
259
260 However, sending a <b>Remote Frame</b> allows a destination node to request the data from the source node.
261 The examples below shows the data exchange using a <b>Remote Transmission Request (RTR)</b>.
262
263 <b>Example for automatic Data Message response on RTR</b>
264
265 For automatic data message response on an RTR, the object is configured with the function \ref ARM_CAN_ObjectConfigure \em obj_cfg = \ref ARM_CAN_OBJ_RX_RTR_TX_DATA.
266
267 In this case, the function \ref ARM_CAN_MessageSend sets a data message that is transmitted when an RTR with a matching CAN ID is received.
268 If \ref ARM_CAN_MessageSend was not called before the RTR is received, the response is hardware dependent (either last data message is repeated
269 or no data message is sent until \ref ARM_CAN_MessageSend is called).
270
271 After data transmission is completed, the driver calls a callback function \ref ARM_CAN_SignalObjectEvent with \em event = \ref ARM_CAN_EVENT_SEND_COMPLETE
272 and the related \em obj_idx.
273
274 <b>Example:</b>
275 \code
276 status = ptrCAN->ObjectSetFilter(0, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x12345678U), 0U);
277 if (status != ARM_DRIVER_OK) ... // error handling
278 status = trCAN->ObjectConfigure(0, ARM_CAN_OBJ_RX_RTR_TX_DATA);
279 if (status != ARM_DRIVER_OK) ... // error handling
280
281 memset(&tx_msg_info, 0, sizeof(ARM_CAN_MSG_INFO)); // Clear transmit message structure
282 tx_msg_info.id = ARM_CAN_EXTENDED_ID(0x12345678U); // Set ID of message
283 data_buf[0] = '1'; data_buf[1] = '2'; // Prepare data to transmit
284 data_buf[2] = '3'; data_buf[3] = '4';
285 data_buf[4] = '5'; data_buf[5] = '6';
286 data_buf[6] = '7'; data_buf[7] = '8';
287 ptrCAN->MessageSend(0, &tx_msg_info, data_buf, 8); // Start send message that will be triggered on RTR reception
288 \endcode
289
290
291 <b>Example for automatic Data Message reception using RTR</b>
292
293 For automatic data message reception on an RTR, the object is configured with the function \ref ARM_CAN_ObjectConfigure \em obj_cfg = \ref ARM_CAN_OBJ_TX_RTR_RX_DATA.
294
295 The receiver or consumer requests data with transmission of an RTR with the \ref ARM_CAN_MessageSend. This RTR requests from the transmitter or producer to send the data message.
296 Once the data message is received, the driver calls a callback function \ref ARM_CAN_SignalObjectEvent with \em event = \ref ARM_CAN_EVENT_RECEIVE
297 and the related \em obj_idx. The received data message can then be read with the function \ref ARM_CAN_MessageRead.
298
299 <b>Example:</b>
300 \code
301 status = ptrCAN->ObjectSetFilter(0, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x12345678U), 0U);
302 if (status != ARM_DRIVER_OK) ... // error handling
303 status = ptrCAN->ObjectConfigure(0, ARM_CAN_OBJ_TX_RTR_RX_DATA);
304 if (status != ARM_DRIVER_OK) ... // error handling
305 memset(&tx_msg_info, 0, sizeof(ARM_CAN_MSG_INFO)); // Clear transmit message structure
306 tx_msg_info.id = ARM_CAN_EXTENDED_ID(0x12345678U); // Set ID of message
307 tx_msg_info.rtr = 1; // Set RTR flag of message to send RTR
308 tx_msg_info.dlc = 1; // Set data length code of message to 1 to request 1 data byte
309 ptrCAN->MesageSend(0, &tx_msg_info, 0, 0); // Send RTR
310
311 // Wait for ARM_CAN_EVENT_RECEIVE
312 ptrCAN->MessageRead(0, &rx_msg_info, data_buf, 8); // Read received message
313 \endcode
314
315
316 @{
317 *****************************************************************************************************************/
318
319 /**
320 \struct ARM_DRIVER_CAN
321 \details
322 The functions of the CAN are accessed by function pointers exposed by this structure. Refer to \ref DriverFunctions for overview information.
323
324 Each instance of a CAN provides such an access structure.
325 The instance is identified by a postfix number in the symbol name of the access structure, for example:
326 - \b Driver_CAN0 is the name of the access struct of the first instance (no. 0).
327 - \b Driver_CAN1 is the name of the access struct of the second instance (no. 1).
328
329 A configuration setting in the middleware allows you to connect the middleware to a specific driver instance <b>Driver_CAN<i>n</i></b>.
330 *******************************************************************************************************************/
331
332 /**
333 \struct ARM_CAN_CAPABILITIES
334 \details
335 A CAN driver can be implemented with different capabilities encoded in the data fields of this structure.
336
337 <b>Returned by:</b>
338 - \ref ARM_CAN_GetCapabilities
339
340 \sa \ref ARM_CAN_OBJ_CAPABILITIES for information about CAN objects.
341 *******************************************************************************************************************/
342
343 /**
344 \struct ARM_CAN_STATUS
345 \details
346 Structure with information about the status of the CAN unit state and errors.
347 The data fields encode the unit bus state, last error code, transmitter error count, and receiver error count.
348
349 <b>Returned by:</b>
350 - \ref ARM_CAN_GetStatus
351 *****************************************************************************************************************/
352
353 /**
354 \struct ARM_CAN_MSG_INFO
355 \brief CAN Message Information
356 \details
357 Structure with information about the CAN message.
358
359 In CAN mode, the following \ref ARM_CAN_MSG_INFO data fields are ignored: \em edl, \em brs, \em esi. \n
360 In CAN FD mode, the following \ref ARM_CAN_MSG_INFO data field is ignored: \em rtr.
361
362 <b>Parameter for:</b>
363 - \ref ARM_CAN_MessageSend
364 - \ref ARM_CAN_MessageRead
365
366 \sa \ref can_filtering
367 \sa \ref Remote_Frame
368 *****************************************************************************************************************/
369
370 /**
371 \typedef ARM_CAN_SignalUnitEvent_t
372 \details
373 Provides the typedef for the callback function \ref ARM_CAN_SignalUnitEvent.
374
375 <b>Parameter for:</b>
376 - \ref ARM_CAN_Initialize
377 *******************************************************************************************************************/
378
379 /**
380 \typedef ARM_CAN_SignalObjectEvent_t
381 \details
382 Provides the typedef for the callback function \ref ARM_CAN_SignalObjectEvent.
383
384 <b>Parameter for:</b>
385 - \ref ARM_CAN_Initialize
386 *******************************************************************************************************************/
387
388 /**
389 \defgroup can_status_code_ctrls CAN Status Error Codes
390 \ingroup can_interface_gr
391 \brief Status codes of the CAN driver.
392 \details
393
394 The following callback notification unit events are generated:
395 @{
396 \def ARM_CAN_UNIT_STATE_INACTIVE
397 \def ARM_CAN_UNIT_STATE_ACTIVE
398 \def ARM_CAN_UNIT_STATE_PASSIVE
399 \def ARM_CAN_UNIT_STATE_BUS_OFF
400 \def ARM_CAN_LEC_NO_ERROR
401 \def ARM_CAN_LEC_BIT_ERROR
402 \def ARM_CAN_LEC_STUFF_ERROR
403 \def ARM_CAN_LEC_CRC_ERROR
404 \def ARM_CAN_LEC_FORM_ERROR
405 \def ARM_CAN_LEC_ACK_ERROR
406 @}
407 *******************************************************************************************************************/
408
409 /**
410 \defgroup CAN_unit_events CAN Unit Events
411 \ingroup can_interface_gr
412 \brief Callback unit events notified via \ref ARM_CAN_SignalUnitEvent.
413 \details
414 The CAN driver generates callback unit events that are notified via the function \ref ARM_CAN_SignalUnitEvent.
415
416 The following callback notification unit events are generated:
417 @{
418 \def ARM_CAN_EVENT_UNIT_INACTIVE
419 \sa \ref ARM_CAN_SignalUnitEvent
420 \def ARM_CAN_EVENT_UNIT_ACTIVE
421 \sa \ref ARM_CAN_SignalUnitEvent
422 \def ARM_CAN_EVENT_UNIT_WARNING
423 \sa \ref ARM_CAN_SignalUnitEvent
424 \def ARM_CAN_EVENT_UNIT_PASSIVE
425 \sa \ref ARM_CAN_SignalUnitEvent
426 \def ARM_CAN_EVENT_UNIT_BUS_OFF
427 \sa \ref ARM_CAN_SignalUnitEvent
428 @}
429 *******************************************************************************************************************/
430
431 /**
432 \defgroup CAN_events CAN Object Events
433 \brief Callback objects events notified via \ref ARM_CAN_SignalObjectEvent.
434 \details
435 The CAN driver generates callback objects events that are notified via the function \ref ARM_CAN_SignalObjectEvent.
436
437 The following callback notification object events are generated:
438 @{
439 \def ARM_CAN_EVENT_SEND_COMPLETE
440 \sa \ref ARM_CAN_SignalObjectEvent
441 \def ARM_CAN_EVENT_RECEIVE
442 \sa \ref ARM_CAN_SignalObjectEvent
443 \def ARM_CAN_EVENT_RECEIVE_OVERRUN
444 \sa \ref ARM_CAN_SignalObjectEvent
445 @}
446 *******************************************************************************************************************/
447
448 /**
449 \defgroup can_control CAN Control Codes
450 \ingroup can_interface_gr
451 \brief Codes to configure the CAN driver.
452 \details
453 @{
454 The various CAN control codes define:
455
456 - \ref can_identifer_ctrls specify CAN identifier. Refer to \ref ARM_CAN_ObjectConfigure.
457 - \ref can_mode_ctrls control CAN interface operation. Refer to \ref ARM_CAN_Control.
458 - \ref can_timeseg_ctrls specify CAN bit rate and timing. Refer to \ref ARM_CAN_SetBitrate.
459 - \ref can_bus_mode_ctrls specify CAN bus operating mode. Refer to \ref ARM_CAN_SetMode.
460 - \ref can_filter_operation_ctrls specify CAN filter operations. Refer to \ref ARM_CAN_ObjectSetFilter.
461 - \ref can_obj_config_ctrls specify CAN object configuration modes. Refer to \ref ARM_CAN_ObjectConfigure.
462 *****************************************************************************************************************/
463
464 /**
465 \defgroup can_identifer_ctrls CAN Identifier
466 \brief Set object to standard or extended.
467 \details
468
469 @{
470 \def ARM_CAN_STANDARD_ID(id)
471 \sa \ref ARM_CAN_ObjectConfigure
472 \def ARM_CAN_EXTENDED_ID(id)
473 \sa \ref ARM_CAN_ObjectConfigure
474 @}
475 *******************************************************************************************************************/
476
477 /**
478 \defgroup can_mode_ctrls CAN Operation Codes
479 \brief Set CAN operation modes.
480 \details
481
482 These controls set the CAN operation using the function \ref ARM_CAN_Control.
483
484 @{
485 \def ARM_CAN_SET_FD_MODE
486 \sa \ref ARM_CAN_Control
487 \def ARM_CAN_ABORT_MESSAGE_SEND
488 \sa \ref ARM_CAN_Control
489 \def ARM_CAN_ABORT_MESSAGE_SEND
490 \sa \ref ARM_CAN_Control
491 \def ARM_CAN_CONTROL_RETRANSMISSION
492 \sa \ref ARM_CAN_Control
493 \def ARM_CAN_SET_TRANSCEIVER_DELAY
494 \sa \ref ARM_CAN_Control
495
496 @}
497 *****************************************************************************************************************/
498
499 /**
500 \defgroup can_bus_mode_ctrls CAN Bus Communication Mode
501 @{
502 \brief Set or initialize the CAN bus
503 \typedef ARM_CAN_MODE
504 \details
505 The enumerations below initialize and set the bus communication mode.
506
507 <b>Parameter for:</b>
508 - \ref ARM_CAN_SetMode
509 @}
510 */
511
512 /**
513 \defgroup can_timeseg_ctrls CAN Bit Timing Codes
514 @{
515 \brief Set bit timing
516 \details
517 The following codes are used with the function \ref ARM_CAN_SetBitrate.
518
519 \def ARM_CAN_BIT_PROP_SEG(x)
520 \sa \ref ARM_CAN_SetBitrate
521 \def ARM_CAN_BIT_PHASE_SEG1(x)
522 \sa \ref ARM_CAN_SetBitrate
523 \def ARM_CAN_BIT_PHASE_SEG2(x)
524 \sa \ref ARM_CAN_SetBitrate
525 \def ARM_CAN_BIT_SJW(x)
526 \sa \ref ARM_CAN_SetBitrate
527
528 *******************************************************************************************************************/
529
530 /**
531 \typedef ARM_CAN_BITRATE_SELECT
532 \brief Set the bit rate.
533 \details
534 Provides the typedef for setting the bit rate.
535
536 <b>Parameter for:</b>
537 - \ref ARM_CAN_SetBitrate
538 *******************************************************************************************************************/
539 /**
540 @}
541 */
542
543 /**
544 \defgroup can_filter_operation_ctrls CAN Filter Operation Codes
545 @{
546 \brief Set CAN filter manipulation codes.
547
548 \typedef ARM_CAN_FILTER_OPERATION
549 \details
550
551 \b ARM_CAN_FILTER_OPERATION provides the controls for setting the filter type.
552 Refer to \ref can_filtering for details.
553
554 <b>Parameter for:</b>
555 - \ref ARM_CAN_ObjectSetFilter
556 @}
557 *****************************************************************************************************************/
558
559 /**
560 \defgroup can_obj_config_ctrls CAN Object Configuration Codes
561 @{
562 \brief CAN Object Configuration codes
563 \typedef ARM_CAN_OBJ_CONFIG
564 \details
565 Provides defined values for the configuration of CAN objects.
566
567 <b>Parameter for:</b>
568 - \ref ARM_CAN_ObjectConfigure
569 @}
570 **************************************************************************************************************************/
571
572 /**
573 @}
574 */ /* End Control Code */
575
576 /**
577 \struct ARM_CAN_OBJ_CAPABILITIES
578 @{
579 \details
580 A CAN object can be implemented with different capabilities encoded in the
581 data fields of this structure.
582
583 <b>Returned by</b>:
584 - \ref ARM_CAN_ObjectGetCapabilities
585
586 \sa \ref ARM_CAN_ObjectConfigure
587 \sa \ref ARM_CAN_MessageSend
588 \sa \ref ARM_CAN_MessageRead
589 \sa \ref ARM_CAN_MSG_INFO
590 \sa \ref can_filtering
591 @}
592 *****************************************************************************************************************/
593
594
595 //
596 // Functions
597 //
ARM_CAN_GetVersion(void)598 ARM_DRIVER_VERSION ARM_CAN_GetVersion (void) {
599 return { 0, 0 };
600 }
601 /**
602 \fn ARM_DRIVER_VERSION ARM_CAN_GetVersion (void)
603 \details
604 The function \b ARM_CAN_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
605 - API version is the version of the CMSIS-Driver specification used to implement this driver.
606 - Driver version is source code version of the actual driver implementation.
607
608 Example:
609 \code
610 extern ARM_DRIVER_CAN Driver_CAN0;
611 ARM_DRIVER_CAN *drv_info;
612
613 void setup_can (void) {
614 ARM_DRIVER_VERSION version;
615
616 drv_info = &Driver_CAN0;
617 version = drv_info->GetVersion ();
618 if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
619 // error handling
620 return;
621 }
622 }
623 \endcode
624 *******************************************************************************************************************/
625
ARM_CAN_GetCapabilities(void)626 ARM_CAN_CAPABILITIES ARM_CAN_GetCapabilities (void) {
627 return { 0 };
628 }
629 /**
630 \fn ARM_CAN_CAPABILITIES ARM_CAN_GetCapabilities (void)
631 \details
632 The function \b ARM_CAN_GetCapabilities returns information about the capabilities in this driver implementation.
633 The data fields of the structure \ref ARM_CAN_CAPABILITIES encode various capabilities.
634
635 Example:
636 \code
637 extern ARM_DRIVER_CAN Driver_CAN0;
638 ARM_DRIVER_CAN *drv_info;
639
640 void read_capabilities (void) {
641 ARM_CAN_CAPABILITIES drv_capabilities;
642
643 drv_info = &Driver_CAN0;
644 drv_capabilities = drv_info->GetCapabilities ();
645 // interrogate capabilities
646
647 }
648 \endcode
649 *******************************************************************************************************************/
650
651
ARM_CAN_Initialize(ARM_CAN_SignalUnitEvent_t cb_unit_event,ARM_CAN_SignalObjectEvent_t cb_object_event)652 int32_t ARM_CAN_Initialize (ARM_CAN_SignalUnitEvent_t cb_unit_event, ARM_CAN_SignalObjectEvent_t cb_object_event) {
653 return ARM_DRIVER_OK;
654 }
655 /**
656 \fn int32_t ARM_CAN_Initialize (ARM_CAN_SignalUnitEvent_t cb_unit_event, ARM_CAN_SignalObjectEvent_t cb_object_event)
657 \details
658 The function \b initializes the CAN interface.
659
660 The function performs the following operations:
661 - Initializes the resources needed for the CAN interface, for example dynamic memory allocation, RTOS object allocation, and possibly hardware pin configuration.
662 - Registers the \ref ARM_CAN_SignalUnitEvent callback function.
663 - Registers the \ref ARM_CAN_SignalObjectEvent callback function.
664
665 The parameter \em cb_unit_event is a pointer to the \ref ARM_CAN_SignalUnitEvent callback function; use a NULL pointer
666 when no callback signals are required.
667
668 The parameter \em cb_object_event is a pointer to the \ref ARM_CAN_SignalObjectEvent callback function; use a NULL pointer
669 when no callback signals are required.
670
671 \b Example:
672 - see \ref can_interface_gr
673
674 **************************************************************************************************************************/
675
676
ARM_CAN_Uninitialize(void)677 int32_t ARM_CAN_Uninitialize (void) {
678 return ARM_DRIVER_OK;
679 }
680 /**
681 \fn int32_t ARM_CAN_Uninitialize (void)
682 \details
683 The function \b ARM_CAN_Uninitialize de-initializes the resources of the CAN interface.
684 It is called to release the software resources used by the interface such as deallocate any RTOS objects, dynamic memory and pin de-configuration.
685 *******************************************************************************************************************/
686
ARM_CAN_PowerControl(ARM_POWER_STATE state)687 int32_t ARM_CAN_PowerControl (ARM_POWER_STATE state) {
688 return ARM_DRIVER_OK;
689 }
690 /**
691 \fn int32_t ARM_CAN_PowerControl (ARM_POWER_STATE state)
692 \details
693 The function \b ARM_CAN_PowerControl controls the power modes of the CAN interface.
694
695 The parameter \em state can be:
696 - ARM_POWER_FULL: Activate clocks and driver functionality as if peripheral was reset.
697 - ARM_POWER_OFF: Unconditionally put peripheral into non-functional (reset) state.
698 - ARM_POWER_LOW: Put peripheral into low power consumption state ready to wake up on bus event.
699
700 **************************************************************************************************************************/
701
ARM_CAN_GetClock(void)702 uint32_t ARM_CAN_GetClock (void) {
703 return ARM_DRIVER_OK;
704 }
705 /**
706 \fn uint32_t ARM_CAN_GetClock (void)
707 \details
708 The function \b ARM_CAN_GetClock returns the CAN base clock frequency in \token{[Hz]}.
709 This value may be used to validate the \em bitrate for the function \ref ARM_CAN_SetBitrate.
710
711 <b>Example</b>:
712 \code
713 CAN_clock = ARM_CAN_GetClock(); // CAN base clock frequency
714 \endcode
715
716 **************************************************************************************************************************/
717
ARM_CAN_SetBitrate(ARM_CAN_BITRATE_SELECT select,uint32_t bitrate,uint32_t bit_segments)718 int32_t ARM_CAN_SetBitrate (ARM_CAN_BITRATE_SELECT select, uint32_t bitrate, uint32_t bit_segments) {
719 return ARM_DRIVER_OK;
720 }
721 /**
722 \fn int32_t ARM_CAN_SetBitrate (ARM_CAN_BITRATE_SELECT select, uint32_t bitrate, uint32_t bit_segments)
723 \details
724 The function \b ARM_CAN_SetBitrate sets the CAN communication bit rate.
725
726 The parameter \em select selects the bit rate affected by function call as defined in \ref ARM_CAN_BITRATE_SELECT and listed in the table below.
727
728 Parameter \em select | CAN Mode Bit Rate
729 :--------------------------------------------|:------------------------------
730 \ref ARM_CAN_BITRATE_NOMINAL | Select nominal (flexible data-rate arbitration) bitrate (CAN 2.0B)
731 \ref ARM_CAN_BITRATE_FD_DATA | Select flexible data-rate data bitrate (\ref CAN_FD)
732
733 The parameter \em bitrate is the bit rate for the selected CAN mode.
734
735 The parameter \em bit_segments is used to setup the time quanta for sampling (see picture below).
736 The values listed in the table below are ORed and specify the various sampling segments.
737 The CAN controller samples each bit on the bus at the <i>Sample Point</i>.
738
739 <table class="cmtable" summary="">
740 <tr>
741 <th>Parameter \em bit_segments</th>
742 <th>Bit</th>
743 <th> for \em select = \ref ARM_CAN_BITRATE_NOMINAL \n (CAN specification)</th>
744 <th> for \em select = \ref ARM_CAN_BITRATE_NOMINAL \n (CAN FD specification)</th>
745 <th> for \em select = \ref ARM_CAN_BITRATE_FD_DATA \n (CAN FD specification)</th>
746 </tr>
747 <tr>
748 <td>\ref ARM_CAN_BIT_PROP_SEG(<i>x</i>) \n
749 Propagation Time Segment \n (PROP_SEG)
750 </td>
751 <td>0..7 </td>
752 <td>\em x = \token{[1..8]}</td>
753 <td>\em x = \token{[1..32] or more}</td>
754 <td>\em x = \token{[0..8]}</td>
755 </tr>
756 <tr>
757 <td>\ref ARM_CAN_BIT_PHASE_SEG1(<i>x</i>) \n
758 Phase Buffer Segment 1 \n (PHASE_SEG1)
759 </td>
760 <td>8..15 </td>
761 <td>\em x = \token{[1..8]}</td>
762 <td>\em x = \token{[1..32] or more}</td>
763 <td>\em x = \token{[1..8]}</td>
764 </tr>
765 <tr>
766 <td rowspan="2">\ref ARM_CAN_BIT_PHASE_SEG2(<i>x</i>) \n
767 Phase Buffer Segment 2 \n (PHASE_SEG2)
768 </td>
769 <td rowspan="2">16..23 </td>
770 <td>\em x = \token{[1..8]} </td>
771 <td>\em x = \token{[1..32] or more}</td>
772 <td>\em x = \token{[1..8]}</td>
773 <tr>
774 <td colspan="3">The maximum allowed value is \token{x = MAX (PHASE_SEG1, IPT)}.
775 IPT = Information Processing Time. Usually, IPT = \token{2}.
776 Exceptions apply. Read the specifications of your CAN controller.</td>
777 </tr>
778 <tr>
779 <td rowspan="2">\ref ARM_CAN_BIT_SJW(<i>x</i>) \n
780 (Re-)Synchronization Jump Width \n (SJW).
781 </td>
782 <td rowspan="2">24..31 </td>
783 <td>\em x = \token{[1..4]}</td>
784 <td>\em x = \token{[1..4]}</td>
785 <td>\em x = \token{[1..4]}</td>
786 <tr>
787 <td colspan="3">The maximum allowed value is \token{x = MIN (MIN (PHASE_SEG1, PHASE_SEG2), 4)}.
788 SJW is not allowed to be greater than either PHASE segment.
789 </td>
790 </tr>
791 </table>
792
793 <p>
794 The picture shows a Nominal Bit Time with 10 time quanta.
795 \image html CAN_Bit_Timing.png "CAN Bit Timing"
796 </p>
797
798 The time quanta (N) per bit is:
799 \code
800 N = 1 + PROP_SEG + PHASE_SEG1 + PHASE_SEG2; // note SYNC_SEG is always 1
801 \endcode
802
803 The driver uses this value and the CAN clock to calculate a suitable prescaler value (P).
804 If the driver cannot achieve the requested \em bitrate it returns with \ref ARM_CAN_INVALID_BITRATE.
805 The formula for the \em bitrate is:
806 \code
807 bitrate = (CAN_Clock / P) / N;
808 \endcode
809
810 <b>Example</b>:
811 \code
812 status = ptrCAN->SetBitrate (ARM_CAN_BITRATE_NOMINAL, // Set nominal bitrate
813 125000U, // Set bitrate to 125 kbit/s
814 ARM_CAN_BIT_PROP_SEG(5U) | // Set propagation segment to 5 time quanta
815 ARM_CAN_BIT_PHASE_SEG1(1U) | // Set phase segment 1 to 1 time quantum (sample point at 87.5% of bit time)
816 ARM_CAN_BIT_PHASE_SEG2(1U) | // Set phase segment 2 to 1 time quantum (total bit is 8 time quanta long)
817 ARM_CAN_BIT_SJW(1U)); // Resynchronization jump width is same as phase segment 2
818 \endcode
819
820 In this example, N = 8 and with a CAN_Clock = 8MHz the prescaler (P) is calculated by the driver to 8.
821 **************************************************************************************************************************/
822
ARM_CAN_SetMode(ARM_CAN_MODE mode)823 int32_t ARM_CAN_SetMode (ARM_CAN_MODE mode) {
824 return ARM_DRIVER_OK;
825 }
826 /**
827 \fn int32_t ARM_CAN_SetMode (ARM_CAN_MODE mode)
828 \details
829 The function \b ARM_CAN_SetMode sets the CAN bus communication mode using the parameter \em mode.
830
831 The table lists the values for \em mode.
832
833 <table class="cmtable" summary="">
834 <tr><th>Parameter \em mode</th>
835 <th>Bus Communication Mode</th>
836 <th>supported when \ref ARM_CAN_OBJ_CAPABILITIES data field</th>
837 </tr>
838 <tr><td>\ref ARM_CAN_MODE_INITIALIZATION</td>
839 <td>Initialization mode; Used to setup communication parameters for the reception
840 objects and global filtering, while peripheral is not active on the bus.
841 Refer to \ref can_filtering for details.</td>
842 <td><i>always supported</i></td>
843 </tr>
844 <tr><td>\ref ARM_CAN_MODE_NORMAL</td>
845 <td>Normal operation mode. Used when peripheral is in active mode to
846 receive, transmit, and acknowledge messages on the bus. Depending on the current unit state,
847 it can generate error or overload messages. Verify the unit state with \ref ARM_CAN_GetStatus.
848 <td><i>always supported</i></td>
849 </tr>
850 <tr><td>\ref ARM_CAN_MODE_RESTRICTED</td>
851 <td>Restricted operation mode. Used for monitoring the bus communication non-intrusively
852 without transmitting.</td>
853 <td>\em restricted_mode = \token{1}</td>
854 </tr>
855 <tr><td>\ref ARM_CAN_MODE_MONITOR</td>
856 <td>Bus monitoring mode.</td>
857 <td>\em monitor_mode = \token{1}</td>
858 </tr>
859 <tr><td>\ref ARM_CAN_MODE_LOOPBACK_INTERNAL</td>
860 <td>Test mode; loopback of CAN transmission to its receiver. No transmission visible on CAN bus.</td>
861 <td>\em internal_loopback = \token{1}</td>
862 </tr>
863 <tr><td>\ref ARM_CAN_MODE_LOOPBACK_EXTERNAL</td>
864 <td>Test mode; loopback of CAN transmission to its receiver. Transmission is visible on CAN bus.</td>
865 <td>\em external_loopback = \token{1}</td>
866 </tr>
867 </table>
868 **************************************************************************************************************************/
869
ARM_CAN_ObjectGetCapabilities(uint32_t obj_idx)870 ARM_CAN_OBJ_CAPABILITIES ARM_CAN_ObjectGetCapabilities (uint32_t obj_idx) {
871 // your code
872 // return type ARM_CAN_OBJ_CAPABILITIES;
873 }
874 /**
875 \fn ARM_CAN_OBJ_CAPABILITIES ARM_CAN_ObjectGetCapabilities (uint32_t obj_idx)
876 \details
877 The function \b ARM_CAN_ObjectGetCapabilities retrieves the capabilities of a CAN object.
878 The structure \ref ARM_CAN_OBJ_CAPABILITIES stores the values.
879
880 The parameter \em obj_idx is the message object index.
881
882 \sa ARM_CAN_ObjectConfigure
883 \sa ARM_CAN_ObjectSetFilter
884 **************************************************************************************************************************/
885
ARM_CAN_ObjectSetFilter(uint32_t obj_idx,ARM_CAN_FILTER_OPERATION operation,uint32_t id,uint32_t arg)886 int32_t ARM_CAN_ObjectSetFilter (uint32_t obj_idx, ARM_CAN_FILTER_OPERATION operation, uint32_t id, uint32_t arg) {
887 return ARM_DRIVER_OK;
888 }
889 /**
890 \fn int32_t ARM_CAN_ObjectSetFilter (uint32_t obj_idx, ARM_CAN_FILTER_OPERATION operation, uint32_t id, uint32_t arg)
891 \details
892 The function \b ARM_CAN_ObjectSetFilter sets or removes the filter for message reception. Refer to \ref can_filtering for details on filtering.
893
894 The parameter \em obj_idx is the message object index. \n
895 The parameter \em operation is the operation on the filter as listed in the table below and
896 which are defined in the structure \ref ARM_CAN_FILTER_OPERATION.
897
898 Parameter \em operation | Operation on Filter | supported when \ref ARM_CAN_OBJ_CAPABILITIES data field
899 :---------------------------------------|:------------------------------|:------------------------------------------
900 \ref ARM_CAN_FILTER_ID_EXACT_ADD | Add exact ID filter | \em exact_filtering = \token{1}
901 \ref ARM_CAN_FILTER_ID_EXACT_REMOVE | Remove exact ID filter | \em exact_filtering = \token{1}
902 \ref ARM_CAN_FILTER_ID_RANGE_ADD | Add range ID filter | \em range_filtering = \token{1}
903 \ref ARM_CAN_FILTER_ID_RANGE_REMOVE | Remove range ID filter | \em range_filtering = \token{1}
904 \ref ARM_CAN_FILTER_ID_MASKABLE_ADD | Add maskable ID filter | \em mask_filtering = \token{1}
905 \ref ARM_CAN_FILTER_ID_MASKABLE_REMOVE | Remove maskable ID filter | \em mask_filtering = \token{1}
906
907 The parameter \em id is the identifier of the filter or defines the start of the filter range (depends on the filter operation). \n
908 The parameter \em arg is the mask of the filter or defines the end of the filter range (depends on the filter operation).
909
910 \sa ARM_CAN_ObjectConfigure
911 **************************************************************************************************************************/
912
ARM_CAN_ObjectConfigure(uint32_t obj_idx,ARM_CAN_OBJ_CONFIG obj_cfg)913 int32_t ARM_CAN_ObjectConfigure (uint32_t obj_idx, ARM_CAN_OBJ_CONFIG obj_cfg) {
914 return ARM_DRIVER_OK;
915 }
916 /**
917 \fn int32_t ARM_CAN_ObjectConfigure (uint32_t obj_idx, ARM_CAN_OBJ_CONFIG obj_cfg)
918 \details
919 The function \b ARM_CAN_ObjectConfigure configures the message object, which can be a mailbox or FIFO.
920 Refer to \ref can_filtering for details.
921
922 The parameter \em obj_idx specifies the message object index. \n
923 The parameter \em obj_cfg configures the \b object with values as shown in the following table.
924
925 <table class="cmtable" summary="">
926 <tr>
927 <th>Parameter \em obj_cfg</th>
928 <th>Object Configuration</th>
929 <th>supported when \ref ARM_CAN_OBJ_CAPABILITIES data field</th>
930 </tr>
931 <tr>
932 <td>\ref ARM_CAN_OBJ_INACTIVE</td>
933 <td>Deactivate object (default after \ref ARM_CAN_Initialize)
934 </td>
935 <td><i>always supported</i></td>
936 </tr>
937 <tr>
938 <td>\ref ARM_CAN_OBJ_RX</td>
939 <td>Receive object; read received message with \ref ARM_CAN_MessageRead.
940 </td>
941 <td>\em rx = \token{1}</td>
942 </tr>
943 <tr>
944 <td>\ref ARM_CAN_OBJ_TX </td>
945 <td>Transmit object; send message with \ref ARM_CAN_MessageSend.
946 </td>
947 <td>\em tx = \token{1}</td>
948 </tr>
949 <tr>
950 <td>\ref ARM_CAN_OBJ_RX_RTR_TX_DATA</td>
951 <td>\ref Remote_Frame Receive; when \b RTR is received data message is transmitted; set data message with \ref ARM_CAN_MessageSend.
952 </td>
953 <td>\em rx_rtr_tx_data = \token{1}</td>
954 </tr>
955 <tr>
956 <td>\ref ARM_CAN_OBJ_TX_RTR_RX_DATA</td>
957 <td>\ref Remote_Frame Transmit; a \b RTR is sent with \ref ARM_CAN_MessageSend to trigger object reception; read received data message with \ref ARM_CAN_MessageRead.
958 </td>
959 <td>\em tx_rtr_rx_data = \token{1}</td>
960 </tr>
961 </table>
962
963 When the \b object is deactivated, it is not used for data communication.
964
965 \sa ARM_CAN_ObjectSetFilter
966 **************************************************************************************************************************/
967
ARM_CAN_MessageSend(uint32_t obj_idx,ARM_CAN_MSG_INFO * msg_info,const uint8_t * data,uint8_t size)968 int32_t ARM_CAN_MessageSend (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, const uint8_t *data, uint8_t size) {
969 return ARM_DRIVER_OK;
970 }
971 /**
972 \fn int32_t ARM_CAN_MessageSend (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, const uint8_t *data, uint8_t size)
973 \details
974 The function \b ARM_CAN_MessageSend sends a CAN message on the CAN bus, or sets data message that will be automatically returned upon RTR reception with matching CAN ID.
975
976 Only one message can be sent with a call to this function (for CAN up to \token{8} bytes; for CAN FD up to \token{64} bytes of data).
977 A message transmission can be terminated with a call to the function \ref ARM_CAN_Control with \em control = \ref ARM_CAN_ABORT_MESSAGE_SEND.
978
979 The parameter \em obj_idx specifies the message object index.
980
981 The parameter \em msg_info is a pointer to the structure \ref ARM_CAN_MSG_INFO, which contains the following relevant data fields for sending message:
982 - \em id: Identifier of the message; bit \token{31} specifies if this is an \token{11-bit} or \token{29-bit} identifier.
983 - \em rtr: Specifies if Remote Transmission Request should be sent (\em dlc is used for number of requested bytes), otherwise the data message will be sent. Refer to \ref Remote_Frame for details.
984 - \em edl: Specifies if Extended Data Length is used; for CAN FD, message can contain up to \token{64} data bytes.
985 - \em brs: Specifies if Bit Rate Switching is to be used; for CAN FD, the bit rate can be increased during data phase.
986 - \em dlc: Data Length Code of requested data bytes when sending Remote Transmission Request.
987
988 The parameter \em data is a pointer to the data buffer.\n
989 The parameter \em size is the number of data bytes to send.\n
990
991 The function returns the number of bytes accepted to be sent or \ref ARM_DRIVER_ERROR_BUSY if the hardware is not
992 ready to accept a new message for transmission.
993
994 When the message is sent, the callback function \ref ARM_CAN_SignalObjectEvent is called signalling \ref ARM_CAN_EVENT_SEND_COMPLETE
995 on specified object.
996
997 \sa \ref can_filtering
998
999 <b>Example:</b>
1000
1001 \code
1002 status = ptrCAN->ObjectConfigure(0, ARM_CAN_OBJ_TX);
1003 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
1004
1005 memset(&tx_msg_info, 0, sizeof(ARM_CAN_MSG_INFO)); // Clear transmit message structure
1006 tx_msg_info.id = ARM_CAN_EXTENDED_ID(0x12345678U); // Set ID of message
1007 data_buf[0] = '1'; data_buf[1] = '2'; // Prepare data to transmit
1008 data_buf[2] = '3'; data_buf[3] = '4';
1009 data_buf[4] = '5'; data_buf[5] = '6';
1010 data_buf[6] = '7'; data_buf[7] = '8';
1011 status = ptrCAN->MesageSend(0, &tx_msg_info, data_buf, 8); // Send message
1012 if (status != ARM_DRIVER_OK ) { Error_Handler(); }
1013 \endcode
1014 **************************************************************************************************************************/
1015
ARM_CAN_MessageRead(uint32_t obj_idx,ARM_CAN_MSG_INFO * msg_info,uint8_t * data,uint8_t size)1016 int32_t ARM_CAN_MessageRead (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, uint8_t *data, uint8_t size) {
1017 return ARM_DRIVER_OK;
1018 }
1019 /**
1020 \fn int32_t ARM_CAN_MessageRead (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, uint8_t *data, uint8_t size)
1021 \details
1022 The function \b ARM_CAN_MessageRead reads the message received on the CAN bus, if \em obj_idx was configured for reception or
1023 for automatic Data Message reception using RTR and the callback function \ref ARM_CAN_SignalObjectEvent was called
1024 signalling \ref ARM_CAN_EVENT_RECEIVE.
1025 If the message was overrun by another received message, then the callback function \ref ARM_CAN_SignalObjectEvent
1026 will be called signalling \ref ARM_CAN_EVENT_RECEIVE_OVERRUN.
1027
1028 The function can read a maximum of \token{8} data bytes for CAN and \token{64} bytes for CAN FD.
1029
1030 The parameter \em obj_idx specifies the message object index. \n
1031 The parameter \em msg_info is a pointer to the CAN information structure. \n
1032 The parameter \em data is a pointer to the data buffer for reading data. \n
1033 The parameter \em size is data buffer size in bytes and indicates the maximum number of bytes that can be read.
1034
1035 The function returns the number of read data in bytes or the \ref execution_status.
1036
1037 All data fields of the structure \ref ARM_CAN_MSG_INFO are updated as described below:
1038 - id: Identifier of the message that was received, bit \token{31} specifies if it is a \token{11-bit} identifier or \token{29-bit} identifier.
1039 - rtr: \token{1} = Remote Frame Request was received (\em dlc is number of requested bytes). \token{0} = data message
1040 - edl: \token{1} = CAN FD Extended Data Length message was received. \token{0} = not Extended Data Length message.
1041 - brs: \token{1} = CAN FD Bit Rate Switching was used for message transfer. \token{0} = no Bit Rate Switching was used.
1042 - esi: \token{1} = CAN FD Error State Indicator is active for received message. \token{0} = Error State Indicator is not active.
1043 - dlc: Data Length Code is the number of data bytes in the received message or number of data bytes requested by RTR.
1044
1045 Message reception can be disabled by de-configuring the receive object with the function \ref ARM_CAN_ObjectConfigure.
1046 **************************************************************************************************************************/
1047
ARM_CAN_Control(uint32_t control,uint32_t arg)1048 int32_t ARM_CAN_Control (uint32_t control, uint32_t arg) {
1049 return ARM_DRIVER_OK;
1050 }
1051 /**
1052 \fn int32_t ARM_CAN_Control (uint32_t control, uint32_t arg)
1053 \details
1054 The function \b ARM_CAN_Control controls the CAN interface settings and executes various operations.
1055
1056 The parameter \em control specifies various operations that are listed in the table below.
1057
1058 The parameters \em arg provides, depending on the \em control value, additional information or set values.
1059
1060 Parameter \em control | Operation
1061 :--------------------------------------------|:------------------------------
1062 \ref ARM_CAN_SET_FD_MODE | Select <a href="#CAN_FD"><b>CAN FD</b></a> mode; \em arg : \token{0} = CAN 2.0B; \token{1} = CAN FD.
1063 \ref ARM_CAN_ABORT_MESSAGE_SEND | Abort sending of CAN message; \em arg : object index
1064 \ref ARM_CAN_CONTROL_RETRANSMISSION | Enable/disable automatic retransmission; \em arg : \token{0 = disable, 1 = enable (default state)}
1065 \ref ARM_CAN_SET_TRANSCEIVER_DELAY | Set transceiver delay; \em arg : delay in time quanta
1066
1067 Verify the CAN interface capabilities with \ref ARM_CAN_GetCapabilities.
1068 *******************************************************************************************************************/
1069
ARM_CAN_GetStatus(void)1070 ARM_CAN_STATUS ARM_CAN_GetStatus (void) {
1071 return ARM_DRIVER_OK;
1072 }
1073 /**
1074 \fn ARM_CAN_STATUS ARM_CAN_GetStatus (void)
1075 \details
1076 The function \b ARM_CAN_GetStatus retrieves runtime information on CAN bus and CAN unit state.
1077
1078 The following defines give information about the current unit involvement in bus communication:
1079
1080 Unit State | Description
1081 :--------------------------------------|:------------
1082 \ref ARM_CAN_UNIT_STATE_INACTIVE | Unit state: Not active on the bus. Unit is in initialization state.
1083 \ref ARM_CAN_UNIT_STATE_ACTIVE | Unit state: Active on the bus. Unit can generate active error frames.
1084 \ref ARM_CAN_UNIT_STATE_PASSIVE | Unit state: Error passive. Unit is interacting on the bus but does not send active error frames.
1085 \ref ARM_CAN_UNIT_STATE_BUS_OFF | Unit state: Bus-off. Unit does not participate on the bus but monitors it and can recover to active state.
1086
1087 The following defines are error codes of the last error that happened on the bus:
1088
1089 Last Error Code | Description
1090 :--------------------------------------|:------------
1091 \ref ARM_CAN_LEC_NO_ERROR | No error. There was no error since last read of status or last successful transmit or receive.
1092 \ref ARM_CAN_LEC_BIT_ERROR | Bit error. The bit monitored is different than the bit sent (except during arbitration phase).
1093 \ref ARM_CAN_LEC_STUFF_ERROR | Bit stuffing error. There were 6 consecutive same bit levels on the bus.
1094 \ref ARM_CAN_LEC_CRC_ERROR | CRC error. CRC of received data is not as expected.
1095 \ref ARM_CAN_LEC_FORM_ERROR | Illegal fixed-form bit. Error in fixed form bits.
1096 \ref ARM_CAN_LEC_ACK_ERROR | Acknowledgment error. Message was not acknowledged by any receiver on the bus.
1097
1098 *******************************************************************************************************************/
1099
ARM_CAN_SignalUnitEvent(uint32_t event)1100 void ARM_CAN_SignalUnitEvent (uint32_t event) {
1101 // function body
1102 }
1103 /**
1104 \fn void ARM_CAN_SignalUnitEvent (uint32_t event)
1105 \details
1106 The function \b ARM_CAN_SignalUnitEvent is a callback function registered by the function \ref ARM_CAN_Initialize.
1107
1108 The parameter \em event indicates unit event that occurred during driver operation.
1109
1110 The following callback notifications are generated:
1111
1112 Parameter \em event | Value |Description
1113 :----------------------------------|:-----:|:-------------------------------------------------
1114 \ref ARM_CAN_EVENT_UNIT_INACTIVE | 0 | Unit entered Inactive state.
1115 \ref ARM_CAN_EVENT_UNIT_ACTIVE | 1 | Unit entered Error Active state.
1116 \ref ARM_CAN_EVENT_UNIT_WARNING | 2 | Unit entered Error Warning state (one or both error counters >= \token{96}).
1117 \ref ARM_CAN_EVENT_UNIT_PASSIVE | 3 | Unit entered Error Passive state.
1118 \ref ARM_CAN_EVENT_UNIT_BUS_OFF | 4 | Unit entered Bus-off state.
1119
1120 \sa \ref ARM_CAN_GetStatus
1121 *******************************************************************************************************************/
1122
ARM_CAN_SignalObjectEvent(uint32_t obj_idx,uint32_t event)1123 void ARM_CAN_SignalObjectEvent (uint32_t obj_idx, uint32_t event) {
1124 // function body
1125 }
1126 /**
1127 \fn void ARM_CAN_SignalObjectEvent (uint32_t obj_idx, uint32_t event)
1128 \details
1129 The function \b ARM_CAN_SignalObjectEvent is a callback function registered by the function \ref ARM_CAN_Initialize and
1130 signals a CAN message object event.
1131
1132 The parameter \em obj_idx is the index of the message object. \n
1133 The parameter \em event indicates object event that occurred during driver operation.
1134
1135 The following events can be generated:
1136
1137 Parameter \em event | Bit | Description
1138 :------------------------------------|:---:|:-------------------------------------------------------------------------
1139 \ref ARM_CAN_EVENT_SEND_COMPLETE | 0 | Message was sent successfully by the \em obj_idx object.
1140 \ref ARM_CAN_EVENT_RECEIVE | 1 | Message was received successfully by the \em obj_idx object.
1141 \ref ARM_CAN_EVENT_RECEIVE_OVERRUN | 2 | Message was overwritten before it was read on the \em obj_idx object.
1142
1143 \sa \ref ARM_CAN_MessageSend
1144 \sa \ref ARM_CAN_MessageRead
1145 \sa \ref ARM_CAN_ObjectConfigure
1146 *******************************************************************************************************************/
1147
1148 /**
1149 @}
1150 */
1151 // End CAN Interface
1152
