begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_CAN.c

   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="http://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="http://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 **CAN FD**
  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 **Block Diagram**
  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 **Driver Functions**
  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 **Example Code**
  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 \if TODO_later
 193 ARM_CAN_ObjectGetCapabilities may depend on the mode (CAN_FD does not support RTR).  Let's clarify that once we have several implementations
 194 \endif
 195
 196
 197 \section can_filtering CAN Message Filtering
 198
 199 The CMSIS-Driver for the CAN interface supports ID filtering for the receiving message objects. The receiving CAN node examines the identifier
 200 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.
 201
 202 The function \ref ARM_CAN_ObjectGetCapabilities retrieves the filter capabilities of the CAN message objects stored in \ref ARM_CAN_OBJ_CAPABILITIES.
 203
 204 Data Fields                | CAN Messages Object can be filtered with ...
 205 :--------------------------|:--------------------------------------------
 206 \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.
 207 \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.
 208 \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.
 209 \em multiple_filters       | ... several filters to capture multiple ID values, or ID value ranges.
 210
 211 <b>CAN message filtering using an exact ID</b>
 212
 213 Example: accept in message object #1 only frames with extended ID = 0x1567.
 214 \code
 215   status = ptrCAN->ObjectSetFilter (1, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x1567), 0);
 216   if (status != ARM_DRIVER_OK) ... // error handling
 217 \endcode
 218
 219 Example: accept in message object #2 frames with extended ID = 0x3167 and extended ID = 0x42123.
 220 \code
 221   status = ptrCAN->ObjectSetFilter (2, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x3167), 0);
 222   if (status != ARM_DRIVER_OK) ... // error handling
 223   status = ptrCAN->ObjectSetFilter (2, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x42123), 0);
 224   if (status != ARM_DRIVER_OK) ... // error handling
 225 \endcode
 226
 227 <b>CAN message filtering using a range ID</b>
 228
 229 Example: accept in message object #3 only frames with extended ID >= 0x1567 and extended ID <= 0x1577.
 230 \code
 231   status = ptrCAN->ObjectSetFilter (3, ARM_CAN_FILTER_ID_RANGE_ADD, ARM_CAN_EXTENDED_ID(0x1567), ARM_CAN_EXTENDED_ID(0x1577));
 232   if (status != ARM_DRIVER_OK) ... // error handling
 233 \endcode
 234
 235
 236 <b>CAN message filtering using a mask ID</b>
 237
 238 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.
 239  - if a mask bit is \token{0}, the corresponding \em ID bit will be accepted, regardless of the value.
 240  - 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.
 241
 242 Example: accept in message object #0 only frames with extended IDs 0x1560 to 0x156F.
 243 \code
 244   status = ptrCAN->ObjectSetFilter (0, ARM_CAN_FILTER_ID_MASKABLE_ADD, ARM_CAN_EXTENDED_ID(0x1560), 0x1FFFFFF0);
 245   if (status != ARM_DRIVER_OK) ... // error handling
 246 \endcode
 247
 248 Example: accept in message object #2 only frames with extended IDs 0x35603, 0x35613, 0x35623, and 0x35633.
 249 \code
 250   status = ptrCAN->ObjectSetFilter (2, ARM_CAN_FILTER_ID_MASKABLE_ADD, ARM_CAN_EXTENDED_ID(0x35603), 0x1FFFFFCF);
 251   if (status != ARM_DRIVER_OK) ... // error handling
 252 \endcode
 253
 254 Example: accept any message in object #4 regardless of the ID.
 255 \code
 256   status = ptrCAN->ObjectSetFilter (4, ARM_CAN_FILTER_ID_MASKABLE_ADD, ARM_CAN_EXTENDED_ID(0), 0);
 257   if (status != ARM_DRIVER_OK) ... // error handling
 258 \endcode
 259
 260 \if TODO_later
 261   - it seems that this needs to be broken up into 4 different cases.
 262
 263 If object does not support \ref ARM_CAN_OBJ_RX_RTR_TX_DATA setting, which can be checked in
 264 message object's capabilities by using \ref ARM_CAN_ObjectGetCapabilities function, then RTR can be received on receive object but no automatism for
 265 data message response is available in that case.
 266
 267 If object does not support \ref ARM_CAN_OBJ_TX_RTR_RX_DATA
 268 setting, which can be checked in message object's capabilities by using \ref ARM_CAN_ObjectGetCapabilities function, then RTR can be sent on transmit object but no
 269 automatism for data message reception is available in that case.
 270
 271 ARM_CAN_ObjectGetCapabilities may depend on the mode (CAN_FD does not support RTR).  Let's clarify that once we have several implementations
 272 \endif
 273
 274 \section Remote_Frame Remote Frame
 275
 276 In general, data transmission is performed on an autonomous basis with the data source node sending out Data Frames.
 277
 278 However, sending a <b>Remote Frame</b> allows a destination node to request the data from the source node.
 279 The examples below shows the data exchange using a <b>Remote Transmission Request (RTR)</b>.
 280
 281 **Example for automatic Data Message response on RTR**
 282
 283 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.
 284
 285 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.
 286 If  \ref ARM_CAN_MessageSend was not called before the RTR is received, the response is hardware dependent (either last data message is repeated
 287 or no data message is sent until \ref ARM_CAN_MessageSend is called).
 288
 289 After data transmission is completed, the driver calls a callback function \ref ARM_CAN_SignalObjectEvent with \em event = \ref ARM_CAN_EVENT_SEND_COMPLETE
 290 and the related \em obj_idx.
 291
 292 <b>Example:</b>
 293 \code
 294   status = ptrCAN->ObjectSetFilter(0, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x12345678U), 0U);
 295   if (status != ARM_DRIVER_OK) ... // error handling
 296   status = trCAN->ObjectConfigure(0, ARM_CAN_OBJ_RX_RTR_TX_DATA);
 297   if (status != ARM_DRIVER_OK) ... // error handling
 298
 299   memset(&tx_msg_info, 0, sizeof(ARM_CAN_MSG_INFO));            // Clear transmit message structure
 300   tx_msg_info.id  = ARM_CAN_EXTENDED_ID(0x12345678U);           // Set ID of message
 301   data_buf[0] = '1';  data_buf[1] = '2';                        // Prepare data to transmit
 302   data_buf[2] = '3';  data_buf[3] = '4';
 303   data_buf[4] = '5';  data_buf[5] = '6';
 304   data_buf[6] = '7';  data_buf[7] = '8';
 305   ptrCAN->MessageSend(0, &tx_msg_info, data_buf, 8);            // Start send message that will be triggered on RTR reception
 306 \endcode
 307
 308
 309 **Example for automatic Data Message reception using RTR**
 310
 311 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.
 312
 313 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.
 314 Once the data message is received, the driver calls a callback function \ref ARM_CAN_SignalObjectEvent with \em event = \ref ARM_CAN_EVENT_RECEIVE
 315 and the related \em obj_idx. The received data message can then be read with the function \ref ARM_CAN_MessageRead.
 316
 317 <b>Example:</b>
 318 \code
 319   status = ptrCAN->ObjectSetFilter(0, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x12345678U), 0U);
 320   if (status != ARM_DRIVER_OK) ... // error handling
 321   status = ptrCAN->ObjectConfigure(0, ARM_CAN_OBJ_TX_RTR_RX_DATA);
 322   if (status != ARM_DRIVER_OK) ... // error handling
 323   memset(&tx_msg_info, 0, sizeof(ARM_CAN_MSG_INFO));            // Clear transmit message structure
 324   tx_msg_info.id  = ARM_CAN_EXTENDED_ID(0x12345678U);           // Set ID of message
 325   tx_msg_info.rtr = 1;                                          // Set RTR flag of message to send RTR
 326   tx_msg_info.dlc = 1;                                          // Set data length code of message to 1 to request 1 data byte
 327   ptrCAN->MesageSend(0, &tx_msg_info, 0, 0);                    // Send RTR
 328
 329   // Wait for ARM_CAN_EVENT_RECEIVE
 330   ptrCAN->MessageRead(0, &rx_msg_info, data_buf, 8);            // Read received message
 331 \endcode
 332
 333
 334 @{
 335 *****************************************************************************************************************/
 336
 337 /**
 338 \struct     ARM_DRIVER_CAN
 339 \details
 340 The functions of the CAN are accessed by function pointers exposed by this structure. Refer to \ref DriverFunctions for overview information.
 341
 342 Each instance of a CAN provides such an access structure.
 343 The instance is identified by a postfix number in the symbol name of the access structure, for example:
 344  - \b Driver_CAN0 is the name of the access struct of the first instance (no. 0).
 345  - \b Driver_CAN1 is the name of the access struct of the second instance (no. 1).
 346
 347 A configuration setting in the middleware allows you to connect the middleware to a specific driver instance <b>Driver_CAN<i>n</i></b>.
 348 *******************************************************************************************************************/
 349
 350 /**
 351 \struct     ARM_CAN_CAPABILITIES
 352 \details
 353 A CAN driver can be implemented with different capabilities encoded in the data fields of this structure.
 354
 355 <b>Returned by:</b>
 356   - \ref ARM_CAN_GetCapabilities
 357
 358 \sa \ref ARM_CAN_OBJ_CAPABILITIES for information about CAN objects.
 359 *******************************************************************************************************************/
 360
 361 /**
 362 \struct     ARM_CAN_STATUS
 363 \details
 364 Structure with information about the status of the CAN unit state and errors.
 365 The data fields encode the unit bus state, last error code, transmitter error count, and receiver error count.
 366
 367 <b>Returned by:</b>
 368   - \ref ARM_CAN_GetStatus
 369 *****************************************************************************************************************/
 370
 371 /**
 372 \struct     ARM_CAN_MSG_INFO
 373 \brief      CAN Message Information
 374 \details
 375 Structure with information about the CAN message.
 376
 377 In CAN mode, the following \ref ARM_CAN_MSG_INFO data fields are ignored: \em edl, \em brs, \em esi. \n
 378 In CAN FD mode, the following \ref ARM_CAN_MSG_INFO data field is ignored: \em rtr.
 379
 380 <b>Parameter for:</b>
 381   - \ref ARM_CAN_MessageSend
 382   - \ref ARM_CAN_MessageRead
 383
 384 \sa \ref can_filtering
 385 \sa \ref Remote_Frame
 386 *****************************************************************************************************************/
 387
 388 /**
 389 \typedef    ARM_CAN_SignalUnitEvent_t
 390 \details
 391 Provides the typedef for the callback function \ref ARM_CAN_SignalUnitEvent.
 392
 393 <b>Parameter for:</b>
 394   - \ref ARM_CAN_Initialize
 395 *******************************************************************************************************************/
 396
 397 /**
 398 \typedef    ARM_CAN_SignalObjectEvent_t
 399 \details
 400 Provides the typedef for the callback function \ref ARM_CAN_SignalObjectEvent.
 401
 402 <b>Parameter for:</b>
 403   - \ref ARM_CAN_Initialize
 404 *******************************************************************************************************************/
 405
 406 /**
 407 \defgroup can_status_code_ctrls Status Error Codes
 408 \ingroup can_interface_gr
 409 \brief Status codes of the CAN driver.
 410 \details
 411
 412 The following callback notification unit events are generated:
 413 @{
 414 \def ARM_CAN_UNIT_STATE_INACTIVE
 415 \def ARM_CAN_UNIT_STATE_ACTIVE
 416 \def ARM_CAN_UNIT_STATE_PASSIVE
 417 \def ARM_CAN_LEC_NO_ERROR
 418 \def ARM_CAN_LEC_BIT_ERROR
 419 \def ARM_CAN_LEC_STUFF_ERROR
 420 \def ARM_CAN_LEC_CRC_ERROR
 421 \def ARM_CAN_LEC_FORM_ERROR
 422 \def ARM_CAN_LEC_ACK_ERROR
 423 @}
 424 *******************************************************************************************************************/
 425
 426 /**
 427 \defgroup CAN_unit_events CAN Unit Events
 428 \ingroup can_interface_gr
 429 \brief Callback unit events notified via \ref ARM_CAN_SignalUnitEvent.
 430 \details
 431 The CAN driver generates callback unit events that are notified via the function \ref ARM_CAN_SignalUnitEvent.
 432
 433 The following callback notification unit events are generated:
 434 @{
 435 \def ARM_CAN_EVENT_UNIT_ACTIVE
 436 \sa \ref ARM_CAN_SignalUnitEvent
 437 \def ARM_CAN_EVENT_UNIT_WARNING
 438 \sa \ref ARM_CAN_SignalUnitEvent
 439 \def ARM_CAN_EVENT_UNIT_PASSIVE
 440 \sa \ref ARM_CAN_SignalUnitEvent
 441 \def ARM_CAN_EVENT_UNIT_BUS_OFF
 442 \sa \ref ARM_CAN_SignalUnitEvent
 443 @}
 444 *******************************************************************************************************************/
 445
 446 /**
 447 \defgroup CAN_events CAN Object Events
 448 \brief Callback objects events notified via \ref ARM_CAN_SignalObjectEvent.
 449 \details
 450 The CAN driver generates callback objects events that are notified via the function \ref ARM_CAN_SignalObjectEvent.
 451
 452 The following callback notification object events are generated:
 453 @{
 454 \def ARM_CAN_EVENT_SEND_COMPLETE
 455 \sa \ref ARM_CAN_SignalObjectEvent
 456 \def ARM_CAN_EVENT_RECEIVE
 457 \sa \ref ARM_CAN_SignalObjectEvent
 458 \def ARM_CAN_EVENT_RECEIVE_OVERRUN
 459 \sa \ref ARM_CAN_SignalObjectEvent
 460 @}
 461 *******************************************************************************************************************/
 462
 463 /**
 464 \defgroup can_control CAN Control Codes
 465 \ingroup can_interface_gr
 466 \brief   Codes to configure the CAN driver.
 467 \details
 468 @{
 469 The various CAN control codes define:
 470
 471   - \ref can_identifer_ctrls          specify CAN identifier. Refer to \ref ARM_CAN_ObjectConfigure.
 472   - \ref can_mode_ctrls               control CAN interface operation. Refer to \ref ARM_CAN_Control.
 473   - \ref can_timeseg_ctrls            specify CAN bit rate and timing. Refer to \ref ARM_CAN_SetBitrate.
 474   - \ref can_bus_mode_ctrls           specify CAN bus operating mode. Refer to \ref ARM_CAN_SetMode.
 475   - \ref can_filter_operation_ctrls   specify CAN filter operations.  Refer to \ref ARM_CAN_ObjectSetFilter.
 476   - \ref can_obj_config_ctrls         specify CAN object configuration modes. Refer to \ref ARM_CAN_ObjectConfigure.
 477 *****************************************************************************************************************/
 478
 479 /**
 480 \defgroup can_identifer_ctrls CAN Identifier
 481 \brief Set object to standard or extended.
 482 \details
 483
 484 @{
 485 \def ARM_CAN_STANDARD_ID(id)
 486 \sa \ref ARM_CAN_ObjectConfigure
 487 \def ARM_CAN_EXTENDED_ID(id)
 488 \sa \ref ARM_CAN_ObjectConfigure
 489 @}
 490 *******************************************************************************************************************/
 491
 492 /**
 493 \defgroup can_mode_ctrls CAN Operation Codes
 494 \brief Set CAN operation modes.
 495 \details
 496
 497 These controls set the CAN operation using the function \ref ARM_CAN_Control.
 498
 499 @{
 500 \def ARM_CAN_SET_FD_MODE
 501 \sa \ref ARM_CAN_Control
 502 \def ARM_CAN_ABORT_MESSAGE_SEND
 503 \sa \ref ARM_CAN_Control
 504 \def ARM_CAN_ABORT_MESSAGE_SEND
 505 \sa \ref ARM_CAN_Control
 506 \def ARM_CAN_CONTROL_RETRANSMISSION
 507 \sa \ref ARM_CAN_Control
 508 \def ARM_CAN_SET_TRANSCEIVER_DELAY
 509 \sa \ref ARM_CAN_Control
 510
 511 @}
 512 *****************************************************************************************************************/
 513
 514 /**
 515 \defgroup can_bus_mode_ctrls CAN Bus Communication Mode
 516 @{
 517 \brief Set or initialize the CAN bus
 518 \enum ARM_CAN_MODE
 519 \details
 520 The enumerations below initialize and set the bus communication mode.
 521
 522 <b>Parameter for:</b>
 523   - \ref ARM_CAN_SetMode
 524 @}
 525 */
 526
 527 /**
 528 \defgroup can_timeseg_ctrls CAN Bit Timing Codes
 529 @{
 530 \brief Set bit timing
 531 \details
 532 The following codes are used with the function \ref ARM_CAN_SetBitrate.
 533
 534 \def ARM_CAN_BIT_PROP_SEG(x)
 535 \sa \ref ARM_CAN_SetBitrate
 536 \def ARM_CAN_BIT_PHASE_SEG1(x)
 537 \sa \ref ARM_CAN_SetBitrate
 538 \def ARM_CAN_BIT_PHASE_SEG2(x)
 539 \sa \ref ARM_CAN_SetBitrate
 540 \def ARM_CAN_BIT_SJW(x)
 541 \sa \ref ARM_CAN_SetBitrate
 542
 543 *******************************************************************************************************************/
 544
 545 /**
 546 \enum ARM_CAN_BITRATE_SELECT
 547 \brief Set the bit rate.
 548 \details
 549 Provides the typedef for setting the bit rate.
 550
 551 <b>Parameter for:</b>
 552   - \ref ARM_CAN_SetBitrate
 553 *******************************************************************************************************************/
 554 /**
 555 @}
 556 */
 557
 558 /**
 559 \defgroup can_filter_operation_ctrls CAN Filter Operation Codes
 560 @{
 561 \brief Set CAN filter manipulation codes.
 562
 563 \enum ARM_CAN_FILTER_OPERATION
 564 \details
 565
 566 \b ARM_CAN_FILTER_OPERATION provides the controls for setting the filter type.
 567 Refer to \ref can_filtering for details.
 568
 569 <b>Parameter for:</b>
 570  - \ref ARM_CAN_ObjectSetFilter
 571 @}
 572 *****************************************************************************************************************/
 573
 574 /**
 575 \defgroup can_obj_config_ctrls CAN Object Configuration Codes
 576 @{
 577 \brief CAN Object Configuration codes
 578 \enum ARM_CAN_OBJ_CONFIG
 579 \details
 580 Provides defined values for the configuration of CAN objects.
 581
 582 <b>Parameter for:</b>
 583   - \ref ARM_CAN_ObjectConfigure
 584 @}
 585 **************************************************************************************************************************/
 586
 587 /**
 588 @}
 589 */   /* End Control Code */
 590
 591 /**
 592 \struct ARM_CAN_OBJ_CAPABILITIES
 593 @{
 594 \details
 595 A CAN object can be implemented with different capabilities encoded in the
 596 data fields of this structure.
 597
 598 <b>Returned by</b>:
 599  - \ref ARM_CAN_ObjectGetCapabilities
 600
 601 \sa \ref ARM_CAN_ObjectConfigure
 602 \sa \ref ARM_CAN_MessageSend
 603 \sa \ref ARM_CAN_MessageRead
 604 \sa \ref ARM_CAN_MSG_INFO
 605 \sa \ref can_filtering
 606 @}
 607 *****************************************************************************************************************/
 608
 609
 610 //
 611 //   Functions
 612 //
 613 ARM_DRIVER_VERSION ARM_CAN_GetVersion (void)  {
 614   return { 0, 0 };
 615 }
 616 /**
 617 \fn       ARM_DRIVER_VERSION ARM_CAN_GetVersion (void)
 618 \details
 619 The function \b ARM_CAN_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
 620  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 621  - Driver version is source code version of the actual driver implementation.
 622
 623 Example:
 624 \code
 625 extern ARM_DRIVER_CAN Driver_CAN0;
 626 ARM_DRIVER_CAN *drv_info;
 627
 628 void setup_can (void)  {
 629   ARM_DRIVER_VERSION  version;
 630
 631   drv_info = &Driver_CAN0;
 632   version = drv_info->GetVersion ();
 633   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 634     // error handling
 635     return;
 636   }
 637 }
 638 \endcode
 639 *******************************************************************************************************************/
 640
 641 ARM_CAN_CAPABILITIES ARM_CAN_GetCapabilities (void)  {
 642   return { 0 };
 643 }
 644 /**
 645 \fn       ARM_CAN_CAPABILITIES ARM_CAN_GetCapabilities (void)
 646 \details
 647 The function \b ARM_CAN_GetCapabilities returns information about the capabilities in this driver implementation.
 648 The data fields of the structure \ref ARM_CAN_CAPABILITIES encode various capabilities.
 649
 650 Example:
 651 \code
 652 extern ARM_DRIVER_CAN Driver_CAN0;
 653 ARM_DRIVER_CAN *drv_info;
 654
 655 void read_capabilities (void)  {
 656   ARM_CAN_CAPABILITIES drv_capabilities;
 657
 658   drv_info = &Driver_CAN0;
 659   drv_capabilities = drv_info->GetCapabilities ();
 660   // interrogate capabilities
 661
 662 }
 663 \endcode
 664 *******************************************************************************************************************/
 665
 666
 667 int32_t ARM_CAN_Initialize (ARM_CAN_SignalUnitEvent_t cb_unit_event, ARM_CAN_SignalObjectEvent_t cb_object_event)  {
 668   return ARM_DRIVER_OK;
 669 }
 670 /**
 671 \fn int32_t ARM_CAN_Initialize (ARM_CAN_SignalUnitEvent_t cb_unit_event, ARM_CAN_SignalObjectEvent_t cb_object_event)
 672 \details
 673 The function \b initializes the CAN interface.
 674
 675 The function performs the following operations:
 676   - Initializes the resources needed for the CAN interface, for example dynamic memory allocation, RTOS object allocation, and possibly hardware pin configuration.
 677   - Registers the \ref ARM_CAN_SignalUnitEvent callback function.
 678   - Registers the \ref ARM_CAN_SignalObjectEvent callback function.
 679
 680 The parameter \em cb_unit_event is a pointer to the \ref ARM_CAN_SignalUnitEvent callback function; use a NULL pointer
 681 when no callback signals are required.
 682
 683 The parameter \em cb_object_event is a pointer to the \ref ARM_CAN_SignalObjectEvent callback function; use a NULL pointer
 684 when no callback signals are required.
 685
 686 \b Example:
 687  - see \ref can_interface_gr
 688
 689 **************************************************************************************************************************/
 690
 691
 692 int32_t ARM_CAN_Uninitialize (void)  {
 693   return ARM_DRIVER_OK;
 694 }
 695 /**
 696 \fn       int32_t ARM_CAN_Uninitialize (void)
 697 \details
 698 The function \b ARM_CAN_Uninitialize de-initializes the resources of the CAN interface.
 699 It is called to release the software resources used by the interface such as deallocate any RTOS objects, dynamic memory and pin de-configuration.
 700 *******************************************************************************************************************/
 701
 702 int32_t ARM_CAN_PowerControl (ARM_POWER_STATE state)  {
 703   return ARM_DRIVER_OK;
 704 }
 705 /**
 706 \fn int32_t ARM_CAN_PowerControl (ARM_POWER_STATE state)
 707 \details
 708 The function \b ARM_CAN_PowerControl controls the power modes of the CAN interface.
 709
 710 The parameter \em state can be:
 711     - ARM_POWER_FULL: Activate clocks and driver functionality as if peripheral was reset.
 712     - ARM_POWER_OFF:  Unconditionally put peripheral into non-functional (reset) state.
 713     - ARM_POWER_LOW:  Put peripheral into low power consumption state ready to wake up on bus event.
 714
 715 **************************************************************************************************************************/
 716
 717 uint32_t ARM_CAN_GetClock (void)  {
 718   return ARM_DRIVER_OK;
 719 }
 720 /**
 721 \fn          uint32_t ARM_CAN_GetClock (void)
 722 \details
 723 The function \b ARM_CAN_GetClock returns the CAN base clock frequency in \token{[Hz]}.
 724 This value may be used to validate the \em bitrate for the function \ref ARM_CAN_SetBitrate.
 725
 726 <b>Example</b>:
 727 \code
 728   CAN_clock = ARM_CAN_GetClock();  // CAN base clock frequency
 729 \endcode
 730
 731 **************************************************************************************************************************/
 732
 733 int32_t ARM_CAN_SetBitrate (ARM_CAN_BITRATE_SELECT select, uint32_t bitrate, uint32_t bit_segments)  {
 734   return ARM_DRIVER_OK;
 735 }
 736 /**
 737 \fn          int32_t ARM_CAN_SetBitrate (ARM_CAN_BITRATE_SELECT select, uint32_t bitrate, uint32_t bit_segments)
 738 \details
 739 The function \b ARM_CAN_SetBitrate sets the CAN communication bit rate.
 740
 741 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.
 742
 743 Parameter \em select                         | CAN Mode Bit Rate
 744 :--------------------------------------------|:------------------------------
 745 \ref ARM_CAN_BITRATE_NOMINAL                 | Select nominal (flexible data-rate arbitration) bitrate (CAN 2.0B)
 746 \ref ARM_CAN_BITRATE_FD_DATA                 | Select flexible data-rate data bitrate (\ref CAN_FD)
 747
 748 The parameter \em bitrate is the bit rate for the selected CAN mode.
 749
 750 The parameter \em bit_segments is used to setup the time quanta for sampling (see picture below).
 751 The values listed in the table below are ORed and specify the various sampling segments.
 752 The CAN controller samples each bit on the bus at the <i>Sample Point</i>.
 753
 754 <table class="cmtable" summary="">
 755 <tr>
 756   <th>Parameter \em bit_segments</th>
 757   <th>Bit</th>
 758   <th> for \em select = \ref ARM_CAN_BITRATE_NOMINAL \n (CAN specification)</th>
 759   <th> for \em select = \ref ARM_CAN_BITRATE_NOMINAL \n (CAN FD specification)</th>
 760   <th> for \em select = \ref ARM_CAN_BITRATE_FD_DATA \n (CAN FD specification)</th>
 761 </tr>
 762 <tr>
 763   <td>\ref ARM_CAN_BIT_PROP_SEG(<i>x</i>) \n
 764       Propagation Time Segment \n (PROP_SEG)
 765   </td>
 766   <td>0..7 </td>
 767   <td>\em x = \token{[1..8]}</td>
 768   <td>\em x = \token{[1..32] or more}</td>
 769   <td>\em x = \token{[0..8]}</td>
 770 </tr>
 771 <tr>
 772   <td>\ref ARM_CAN_BIT_PHASE_SEG1(<i>x</i>) \n
 773        Phase Buffer Segment 1 \n (PHASE_SEG1)
 774   </td>
 775   <td>8..15 </td>
 776   <td>\em x = \token{[1..8]}</td>
 777   <td>\em x = \token{[1..32] or more}</td>
 778   <td>\em x = \token{[1..8]}</td>
 779 </tr>
 780 <tr>
 781   <td rowspan="2">\ref ARM_CAN_BIT_PHASE_SEG2(<i>x</i>) \n
 782       Phase Buffer Segment 2 \n (PHASE_SEG2)
 783   </td>
 784   <td rowspan="2">16..23 </td>
 785   <td>\em x = \token{[1..8]} </td>
 786   <td>\em x = \token{[1..32] or more}</td>
 787   <td>\em x = \token{[1..8]}</td>
 788 <tr>
 789   <td colspan="3">The maximum allowed value is \token{x = MAX (PHASE_SEG1, IPT)}.
 790                   IPT = Information Processing Time. Usually, IPT = \token{2}.
 791                                   Exceptions apply. Read the specifications of your CAN controller.</td>
 792 </tr>
 793 <tr>
 794   <td rowspan="2">\ref ARM_CAN_BIT_SJW(<i>x</i>) \n
 795       (Re-)Synchronization Jump Width \n (SJW).
 796   </td>
 797   <td rowspan="2">24..31 </td>
 798   <td>\em x = \token{[1..4]}</td>
 799   <td>\em x = \token{[1..4]}</td>
 800   <td>\em x = \token{[1..4]}</td>
 801 <tr>
 802   <td colspan="3">The maximum allowed value is \token{x = MIN (MIN (PHASE_SEG1, PHASE_SEG2), 4)}.
 803                   SJW is not allowed to be greater than either PHASE segment.
 804   </td>
 805 </tr>
 806 </table>
 807
 808 <p>
 809 The picture shows a Nominal Bit Time with 10 time quanta.
 810 \image html CAN_Bit_Timing.png  "CAN Bit Timing"
 811 </p>
 812
 813 The time quanta (N) per bit is:
 814 \code
 815   N = 1 + PROP_SEG + PHASE_SEG1 + PHASE_SEG2; // note SYNC_SEG is always 1
 816 \endcode
 817
 818 The driver uses this value and the CAN clock to calculate a suitable prescaler value (P).
 819 If the driver cannot achieve the requested \em bitrate it returns with \ref ARM_CAN_INVALID_BITRATE.
 820 The formula for the \em bitrate is:
 821 \code
 822   bitrate = (CAN_Clock / P) / N;
 823 \endcode
 824
 825 <b>Example</b>:
 826 \code
 827 status = ptrCAN->SetBitrate    (ARM_CAN_BITRATE_NOMINAL,              // Set nominal bitrate
 828                                 125000U,                              // Set bitrate to 125 kbit/s
 829                                 ARM_CAN_BIT_PROP_SEG(5U)   |          // Set propagation segment to 5 time quanta
 830                                 ARM_CAN_BIT_PHASE_SEG1(1U) |          // Set phase segment 1 to 1 time quantum (sample point at 87.5% of bit time)
 831                                 ARM_CAN_BIT_PHASE_SEG2(1U) |          // Set phase segment 2 to 1 time quantum (total bit is 8 time quanta long)
 832                                 ARM_CAN_BIT_SJW(1U));                 // Resynchronization jump width is same as phase segment 2
 833 \endcode
 834
 835 In this example, N = 8 and with a CAN_Clock = 8MHz the prescaler (P) is calculated by the driver to 8.
 836 **************************************************************************************************************************/
 837
 838 int32_t ARM_CAN_SetMode (ARM_CAN_MODE mode)  {
 839   return ARM_DRIVER_OK;
 840 }
 841 /**
 842 \fn  int32_t ARM_CAN_SetMode (ARM_CAN_MODE mode)
 843 \details
 844 The function \b ARM_CAN_SetMode sets the CAN bus communication mode using the parameter \em mode.
 845
 846 The table lists the values for \em mode.
 847
 848 <table class="cmtable" summary="">
 849     <tr><th>Parameter \em mode</th>
 850         <th>Bus Communication Mode</th>
 851         <th>supported when \ref ARM_CAN_OBJ_CAPABILITIES data field</th>
 852     </tr>
 853     <tr><td>\ref ARM_CAN_MODE_INITIALIZATION</td>
 854         <td>Initialization mode; Used to setup communication parameters for the reception
 855             objects and global filtering, while peripheral is not active on the bus.
 856             Refer to \ref can_filtering for details.</td>
 857         <td><i>always supported</i></td>
 858     </tr>
 859     <tr><td>\ref ARM_CAN_MODE_NORMAL</td>
 860         <td>Normal operation mode. Used when peripheral is in active mode to
 861             receive, transmit, and acknowledge messages on the bus. Depending on the current unit state,
 862             it can generate error or overload messages. Verify the unit state with \ref ARM_CAN_GetStatus.
 863         <td><i>always supported</i></td>
 864     </tr>
 865     <tr><td>\ref ARM_CAN_MODE_RESTRICTED</td>
 866         <td>Restricted operation mode. Used for monitoring the bus communication non-intrusively
 867             without transmitting.</td>
 868         <td>\em restricted_mode = \token{1}</td>
 869     </tr>
 870     <tr><td>\ref ARM_CAN_MODE_MONITOR</td>
 871         <td>Bus monitoring mode.</td>
 872         <td>\em monitor_mode = \token{1}</td>
 873     </tr>
 874     <tr><td>\ref ARM_CAN_MODE_LOOPBACK_INTERNAL</td>
 875         <td>Test mode; loopback of CAN transmission to its receiver. No transmission visible on CAN bus.</td>
 876         <td>\em internal_loopback = \token{1}</td>
 877     </tr>
 878     <tr><td>\ref ARM_CAN_MODE_LOOPBACK_EXTERNAL</td>
 879         <td>Test mode; loopback of CAN transmission to its receiver. Transmission is visible on CAN bus.</td>
 880         <td>\em external_loopback = \token{1}</td>
 881     </tr>
 882 </table>
 883 **************************************************************************************************************************/
 884
 885 ARM_CAN_OBJ_CAPABILITIES ARM_CAN_ObjectGetCapabilities (uint32_t obj_idx)  {
 886    // your code
 887    // return type ARM_CAN_OBJ_CAPABILITIES;
 888 }
 889 /**
 890 \fn          ARM_CAN_OBJ_CAPABILITIES ARM_CAN_ObjectGetCapabilities (uint32_t obj_idx)
 891 \details
 892 The function \b  ARM_CAN_ObjectGetCapabilities retrieves the capabilities of a CAN object.
 893 The structure \ref ARM_CAN_OBJ_CAPABILITIES stores the values.
 894
 895 The parameter \em obj_idx is the message object index.
 896
 897 \sa ARM_CAN_ObjectConfigure
 898 \sa ARM_CAN_ObjectSetFilter
 899 **************************************************************************************************************************/
 900
 901 int32_t ARM_CAN_ObjectSetFilter (uint32_t obj_idx, ARM_CAN_FILTER_OPERATION operation, uint32_t id, uint32_t arg)  {
 902   return ARM_DRIVER_OK;
 903 }
 904 /**
 905 \fn          int32_t ARM_CAN_ObjectSetFilter (uint32_t obj_idx, ARM_CAN_FILTER_OPERATION operation, uint32_t id, uint32_t arg)
 906 \details
 907 The function \b ARM_CAN_ObjectSetFilter sets or removes the filter for message reception. Refer to \ref can_filtering for details on filtering.
 908
 909 The parameter \em obj_idx is the message object index. \n
 910 The parameter \em operation is the operation on the filter as listed in the table below and
 911 which are defined in the structure \ref ARM_CAN_FILTER_OPERATION.
 912
 913 Parameter \em operation                 |  Operation on Filter          | supported when \ref ARM_CAN_OBJ_CAPABILITIES data field
 914 :---------------------------------------|:------------------------------|:------------------------------------------
 915 \ref ARM_CAN_FILTER_ID_EXACT_ADD        | Add    exact ID filter        | \em exact_filtering = \token{1}
 916 \ref ARM_CAN_FILTER_ID_EXACT_REMOVE     | Remove exact ID filter        | \em exact_filtering = \token{1}
 917 \ref ARM_CAN_FILTER_ID_RANGE_ADD        | Add    range ID filter        | \em range_filtering = \token{1}
 918 \ref ARM_CAN_FILTER_ID_RANGE_REMOVE     | Remove range ID filter        | \em range_filtering = \token{1}
 919 \ref ARM_CAN_FILTER_ID_MASKABLE_ADD     | Add    maskable ID filter     | \em mask_filtering = \token{1}
 920 \ref ARM_CAN_FILTER_ID_MASKABLE_REMOVE  | Remove maskable ID filter     | \em mask_filtering = \token{1}
 921
 922 The parameter \em id is the identifier of the filter or defines the start of the filter range (depends on the filter operation). \n
 923 The parameter \em arg is the mask of the filter or defines the end of the filter range (depends on the filter operation).
 924
 925 \sa ARM_CAN_ObjectConfigure
 926 **************************************************************************************************************************/
 927
 928 int32_t ARM_CAN_ObjectConfigure (uint32_t obj_idx, ARM_CAN_OBJ_CONFIG obj_cfg)  {
 929   return ARM_DRIVER_OK;
 930 }
 931 /**
 932 \fn int32_t ARM_CAN_ObjectConfigure (uint32_t obj_idx, ARM_CAN_OBJ_CONFIG obj_cfg)
 933 \details
 934 The function \b ARM_CAN_ObjectConfigure configures the message object, which can be a mailbox or FIFO.
 935 Refer to \ref can_filtering for details.
 936
 937 The parameter \em obj_idx specifies the message object index. \n
 938 The parameter \em obj_cfg configures the \b object with values as shown in the following table.
 939
 940 <table class="cmtable" summary="">
 941 <tr>
 942   <th>Parameter \em obj_cfg</th>
 943   <th>Object Configuration</th>
 944   <th>supported when \ref ARM_CAN_OBJ_CAPABILITIES data field</th>
 945 </tr>
 946 <tr>
 947    <td>\ref ARM_CAN_OBJ_INACTIVE</td>
 948    <td>Deactivate object (default after \ref ARM_CAN_Initialize)
 949    </td>
 950    <td><i>always supported</i></td>
 951 </tr>
 952 <tr>
 953    <td>\ref ARM_CAN_OBJ_RX</td>
 954    <td>Receive object; read received message with \ref ARM_CAN_MessageRead.
 955    </td>
 956    <td>\em rx = \token{1}</td>
 957 </tr>
 958 <tr>
 959    <td>\ref ARM_CAN_OBJ_TX </td>
 960    <td>Transmit object; send message with \ref ARM_CAN_MessageSend.
 961    </td>
 962    <td>\em tx = \token{1}</td>
 963 </tr>
 964 <tr>
 965    <td>\ref ARM_CAN_OBJ_RX_RTR_TX_DATA</td>
 966    <td>\ref Remote_Frame Receive; when \b RTR is received data message is transmitted; set data message with \ref ARM_CAN_MessageSend.
 967    </td>
 968    <td>\em  rx_rtr_tx_data = \token{1}</td>
 969 </tr>
 970 <tr>
 971    <td>\ref ARM_CAN_OBJ_TX_RTR_RX_DATA</td>
 972    <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.
 973    </td>
 974    <td>\em  tx_rtr_rx_data = \token{1}</td>
 975 </tr>
 976 </table>
 977
 978 When the \b object is deactivated, it is not used for data communication.
 979
 980 \sa ARM_CAN_ObjectSetFilter
 981 **************************************************************************************************************************/
 982 /*
 983 TODO_later:
 984 we add this info later (once we have a CAN FD implementation)
 985 Hi Reinhard,
 986
 987 here is the explanation regarding message object structure fields:
 988
 989 Send:
 990
 991   Send Data Message using MessageSend function (parameters usage):
 992   id = id
 993   rtr = 0
 994   edl = for CAN FD it specifies if extended data length encoding of DLC is used
 995   brs = for CAN FD it specifies if baud rate switching is used during data phase
 996   esi - not used
 997  dlc - not used
 998   data = pointer to data to be sent
 999   size = number of data bytes to send (up to 8 for CAN, up to 64 for CAN FD)
1000   function returns number data bytes accepted to be sent or -error
1001
1002   Send RTR Message using MessageSend function (parameters usage):
1003   id = id
1004   rtr = 1
1005   edl - not used (CAN FD does not support RTR)
1006   brs - not used (CAN FD does not support RTR)
1007   esi - not used
1008  dlc = number of requested data bytes (up to 8 for CAN)
1009   data - not used
1010   size - not used
1011   function returns 0 or -error
1012
1013 Receive:
1014
1015   Read received message using MessageRead function (updated information):
1016   id = updated with received id
1017   rtr = updated with RTR information (if data message received = 0, if RTR message received = 1)
1018   edl = for CAN FD it specifies if received message has extended data length used for DLC encoding
1019   brs = for CAN FD it specifies if baud rate switching was used during data reception
1020   esi = for CAN FD it specifies Error State Indicator (if message was received with error)
1021  dlc = DLC of received message, for RTR it specifies number of requested data bytes, for data message it specifies number of data bytes received
1022   function returns number of data bytes read or -error (if RTR was read it returns 0)
1023
1024
1025 */
1026
1027 int32_t ARM_CAN_MessageSend (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, const uint8_t *data, uint8_t size)  {
1028   return ARM_DRIVER_OK;
1029 }
1030 /**
1031 \fn          int32_t ARM_CAN_MessageSend (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, const uint8_t *data, uint8_t size)
1032 \details
1033 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.
1034
1035 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).
1036 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.
1037
1038 The parameter \em obj_idx specifies the message object index.
1039
1040 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:
1041     - \em id:  Identifier of the message; bit \token{31} specifies if this is an \token{11-bit} or \token{29-bit} identifier.
1042     - \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.
1043     - \em edl: Specifies if Extended Data Length is used; for CAN FD, message can contain up to \token{64} data bytes.
1044     - \em brs: Specifies if Bit Rate Switching is to be used; for CAN FD, the bit rate can be increased during data phase.
1045     - \em dlc: Data Length Code of requested data bytes when sending Remote Transmission Request.
1046
1047 The parameter \em data is a pointer to the data buffer.\n
1048 The parameter \em size is the number of data bytes to send.\n
1049
1050 The function returns the number of bytes accepted to be sent or \ref ARM_DRIVER_ERROR_BUSY if the hardware is not
1051 ready to accept a new message for transmission.
1052
1053 When the message is sent, the callback function \ref ARM_CAN_SignalObjectEvent is called signalling \ref ARM_CAN_EVENT_SEND_COMPLETE
1054 on specified object.
1055
1056 \sa \ref can_filtering
1057
1058 <b>Example:</b>
1059
1060 \code
1061   status = ptrCAN->ObjectConfigure(0, ARM_CAN_OBJ_TX);
1062   if (status != ARM_DRIVER_OK ) { Error_Handler(); }
1063
1064   memset(&tx_msg_info, 0, sizeof(ARM_CAN_MSG_INFO));            // Clear transmit message structure
1065   tx_msg_info.id  = ARM_CAN_EXTENDED_ID(0x12345678U);           // Set ID of message
1066   data_buf[0] = '1';  data_buf[1] = '2';                        // Prepare data to transmit
1067   data_buf[2] = '3';  data_buf[3] = '4';
1068   data_buf[4] = '5';  data_buf[5] = '6';
1069   data_buf[6] = '7';  data_buf[7] = '8';
1070   status = ptrCAN->MesageSend(0, &tx_msg_info, data_buf, 8);    // Send message
1071   if (status != ARM_DRIVER_OK ) { Error_Handler(); }
1072 \endcode
1073 **************************************************************************************************************************/
1074
1075 int32_t ARM_CAN_MessageRead (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, uint8_t *data, uint8_t size)  {
1076   return ARM_DRIVER_OK;
1077 }
1078 /**
1079 \fn          int32_t ARM_CAN_MessageRead (uint32_t obj_idx, ARM_CAN_MSG_INFO *msg_info, uint8_t *data, uint8_t size)
1080 \details
1081 The function \b ARM_CAN_MessageRead reads the message received on the CAN bus, if \em obj_idx was configured for reception or
1082 for automatic Data Message reception using RTR and the callback function \ref ARM_CAN_SignalObjectEvent was called
1083 signalling \ref ARM_CAN_EVENT_RECEIVE.
1084 If the message was overrun by another received message, then the callback function \ref ARM_CAN_SignalObjectEvent
1085 will be called signalling \ref ARM_CAN_EVENT_RECEIVE_OVERRUN.
1086
1087 The function can read a maximum of \token{8} data bytes for CAN and \token{64} bytes for CAN FD.
1088
1089 The parameter \em obj_idx specifies the message object index. \n
1090 The parameter \em msg_info is a pointer to the CAN information structure. \n
1091 The parameter \em data is a pointer to the data buffer for reading data. \n
1092 The parameter \em size is data buffer size in bytes and indicates the maximum number of bytes that can be read.
1093
1094 The function returns the number of read data in bytes or the \ref execution_status.
1095
1096 All data fields of the structure \ref ARM_CAN_MSG_INFO are updated as described below:
1097     - 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.
1098     - rtr: \token{1} = Remote Frame Request was received (\em dlc is number of requested bytes).  \token{0} = data message
1099     - edl: \token{1} = CAN FD Extended Data Length message was received.  \token{0} = not Extended Data Length message.
1100     - brs: \token{1} = CAN FD Bit Rate Switching was used for message transfer. \token{0} = no Bit Rate Switching was used.
1101     - esi: \token{1} = CAN FD Error State Indicator is active for received message.  \token{0} = Error State Indicator is not active.
1102     - dlc: Data Length Code is the number of data bytes in the received message or number of data bytes requested by RTR.
1103
1104 Message reception can be disabled by de-configuring the receive object with the function \ref ARM_CAN_ObjectConfigure.
1105 **************************************************************************************************************************/
1106
1107 int32_t ARM_CAN_Control (uint32_t control, uint32_t arg)  {
1108   return ARM_DRIVER_OK;
1109 }
1110 /**
1111 \fn   int32_t ARM_CAN_Control (uint32_t control, uint32_t arg)
1112 \details
1113 The function \b ARM_CAN_Control controls the CAN interface settings and executes various operations.
1114
1115 The parameter \em control specifies various operations that are listed in the table below.
1116
1117 The parameters \em arg provides, depending on the \em control value, additional information or set values.
1118
1119 Parameter \em control                        | Operation
1120 :--------------------------------------------|:------------------------------
1121 \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.
1122 \ref ARM_CAN_ABORT_MESSAGE_SEND              | Abort sending of CAN message;      \em arg : object index
1123 \ref ARM_CAN_CONTROL_RETRANSMISSION          | Enable/disable automatic retransmission; \em arg : \token{0 = disable, 1 = enable (default state)}
1124 \ref ARM_CAN_SET_TRANSCEIVER_DELAY           | Set transceiver delay; \em arg : delay in time quanta
1125
1126 Verify the CAN interface capabilities with \ref ARM_CAN_GetCapabilities.
1127 *******************************************************************************************************************/
1128
1129 ARM_CAN_STATUS ARM_CAN_GetStatus (void)  {
1130   return ARM_DRIVER_OK;
1131 }
1132 /**
1133 \fn            ARM_CAN_STATUS ARM_CAN_GetStatus (void)
1134 \details
1135 The function \b ARM_CAN_GetStatus retrieves runtime information on CAN bus and CAN unit state.
1136
1137 The following defines give information about the current unit involvement in bus communication:
1138
1139 Unit State                             | Description
1140 :--------------------------------------|:------------
1141 \ref ARM_CAN_UNIT_STATE_INACTIVE       | Unit is not active on bus (initialize or error bus off).
1142 \ref ARM_CAN_UNIT_STATE_ACTIVE         | Unit is active on bus (can generate active error frame).
1143 \ref ARM_CAN_UNIT_STATE_PASSIVE        | Error passive (can not generate active error frame). Unit is interacting on the bus but does not send active error or overload frames.
1144
1145 The following defines are error codes of the last error that happened on the bus:
1146
1147 Last Error Code                        | Description
1148 :--------------------------------------|:------------
1149 \ref ARM_CAN_LEC_NO_ERROR              | No error. There was no error since last read of status or last successful transmit or receive.
1150 \ref ARM_CAN_LEC_BIT_ERROR             | Bit error. The bit monitored is different than the bit sent (except during arbitration phase).
1151 \ref ARM_CAN_LEC_STUFF_ERROR           | Bit stuffing error. There were 6 consecutive same bit levels on the bus.
1152 \ref ARM_CAN_LEC_CRC_ERROR             | CRC error. CRC of received data is not as expected.
1153 \ref ARM_CAN_LEC_FORM_ERROR            | Illegal fixed-form bit. Error in fixed form bits.
1154 \ref ARM_CAN_LEC_ACK_ERROR             | Acknowledgment error. Message was not acknowledged by any receiver on the bus.
1155
1156 *******************************************************************************************************************/
1157
1158 void ARM_CAN_SignalUnitEvent (uint32_t event)  {
1159  // function body
1160 }
1161 /**
1162 \fn      void ARM_CAN_SignalUnitEvent (uint32_t event)
1163 \details
1164 The function \b ARM_CAN_SignalUnitEvent is a callback function registered by the function \ref ARM_CAN_Initialize.
1165
1166 The parameter \em event indicates unit event that occurred during driver operation.
1167
1168 The following callback notifications are generated:
1169
1170 Parameter \em event                | Value |Description
1171 :----------------------------------|:-----:|:-------------------------------------------------
1172 \ref ARM_CAN_EVENT_UNIT_ACTIVE     |   0   | Unit became active on the bus.
1173 \ref ARM_CAN_EVENT_UNIT_WARNING    |   1   | Unit error counter reached >= \token{96}.
1174 \ref ARM_CAN_EVENT_UNIT_PASSIVE    |   2   | Unit became passive on the bus.
1175 \ref ARM_CAN_EVENT_UNIT_BUS_OFF    |   3   | Unit became inactive on the bus.
1176
1177 \sa \ref ARM_CAN_GetStatus
1178 *******************************************************************************************************************/
1179
1180 void ARM_CAN_SignalObjectEvent (uint32_t obj_idx, uint32_t event)  {
1181   // function body
1182 }
1183 /**
1184 \fn          void ARM_CAN_SignalObjectEvent (uint32_t obj_idx, uint32_t event)
1185 \details
1186 The function \b ARM_CAN_SignalObjectEvent is a callback function registered by the function \ref ARM_CAN_Initialize and
1187 signals a CAN message object event.
1188
1189 The parameter \em obj_idx  is the index of the message object. \n
1190 The parameter \em event indicates object event that occurred during driver operation.
1191
1192 The following events can be generated:
1193
1194  Parameter \em event                 | Bit | Description
1195 :------------------------------------|:---:|:-------------------------------------------------------------------------
1196  \ref ARM_CAN_EVENT_SEND_COMPLETE    |  0  | Message was sent successfully by the \em obj_idx object.
1197  \ref ARM_CAN_EVENT_RECEIVE          |  1  | Message was received successfully by the \em obj_idx object.
1198  \ref ARM_CAN_EVENT_RECEIVE_OVERRUN  |  2  | Message was overwritten before it was read on the \em obj_idx object.
1199
1200 \sa \ref ARM_CAN_MessageSend
1201 \sa \ref ARM_CAN_MessageRead
1202 \sa \ref ARM_CAN_ObjectConfigure
1203 *******************************************************************************************************************/
1204
1205 /**
1206 @}
1207 */
1208 // End CAN Interface