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

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