044d9ee9325491260eae9c0f32235ced7032ea47
1 /**
2 * @file canfd.h
3 *
4 * @brief
5 * This is the header file for the CANFD driver which exposes the
6 * data structures and exported API which can be used by the
7 * applications to use the CANFD driver.
8 *
9 * \par
10 * NOTE:
11 * (C) Copyright 2020 Texas Instruments, Inc.
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 *
17 * Redistributions of source code must retain the above copyright
18 * notice, this list of conditions and the following disclaimer.
19 *
20 * Redistributions in binary form must reproduce the above copyright
21 * notice, this list of conditions and the following disclaimer in the
22 * documentation and/or other materials provided with the
23 * distribution.
24 *
25 * Neither the name of Texas Instruments Incorporated nor the names of
26 * its contributors may be used to endorse or promote products derived
27 * from this software without specific prior written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
30 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
31 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
32 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
33 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
34 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
36 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
37 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
38 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
39 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 */
42 /** @mainpage CANFD Driver
43 *
44 * The CANFD driver provides functionality of transferring data between CANFD peripherals.
45 * This driver does not interpret any of the data sent to or received from using this peripheral.
46 *
47 *
48 * The CANFD header file should be included in an application as follows:
49 * @code
50 * #include <ti/drivers/canfd/canfd.h>
51 * @endcode
52 *
53 * ## Initializing the driver #
54 * The CANFD Driver needs to be initialized once across the System. This is
55 * done using the #CANFD_init. None of the CANFD API's can be used without invoking
56 * this API.
57 *
58 * Once the CANFD Driver has been initialized; the bit timing can be configured using #CANFD_configBitTime.
59 * This APIs can be called multiple times to reconfigure bit timings.
60 *
61 * ## Creating the message objects #
62 * Message objects are used to transmit or receive data over the CANFD peripheral. A message object is created
63 * using #CANFD_createMsgObject.
64 *
65 * ## Sending and receiving data #
66 * Data is transmitted using the #CANFD_transmitData. The application will be notified when the transmit is
67 * complete if it has enabled dataInterruptEnable and registered a callback function appDataCallBack when
68 * initializing the CANFD driver.
69 *
70 * If the receive interrupts are enabled using dataInterruptEnable field and a callback function appCallBack
71 * has been registered when initializing the CANFD driver, the driver notifies the application
72 * when the data has arrived. The application needs to call the #CANFD_getData function to read the received data.
74 *
75 * ## Error and status handling #
76 * The application can monitor the ECC error, Bus off error and Protocol Errors by enabling the error interrupts errInterruptEnable.
77 * The driver will call the registered callback function appErrCallBack to indicate which error fields caused the interrupt.
78 * It is up to the application to take appropriate action.
79 *
80 * ## Get/Set Options #
81 * Helper APIs to get and set various statistics, error counters, ECC diagnostics, power down have been provided.
82 * Refer to #CANFD_Option for more information.
83 *
84 * ## Limitation #
85 * The CANFD driver does not support the DMA or power down.
86 *
87 * The canfd/include/hw_mcanss.h has the register layer definitons for the CANFD controller module.
88 *
89 */
91 /** @defgroup CANFD_DRIVER CANFD Driver
92 */
94 #ifndef CANFD_H_
95 #define CANFD_H_
97 #ifdef __cplusplus
98 extern "C" {
99 #endif
101 #include <stdint.h>
102 #include <stddef.h>
105 /**
106 @defgroup CANFD_DRIVER_EXTERNAL_FUNCTION CANFD Driver External Functions
107 @ingroup CANFD_DRIVER
108 @brief
109 * The section has a list of all the exported API which the applications need to
110 * invoke in order to use the CANFD driver
111 */
113 /**
114 @defgroup CANFD_DRIVER_EXTERNAL_DATA_STRUCTURE CANFD Driver External Data Structures
115 @ingroup CANFD_DRIVER
116 @brief
117 * The section has a list of all the data structures which are exposed to the application
118 */
120 /**
121 @defgroup CANFD_DRIVER_ERROR_CODE CANFD Driver Error code
122 @ingroup CANFD_DRIVER
123 @brief
124 * The section has a list of all the error codes which are returned to the application.
125 * Base error code for the CANFD module is defined in the
126 * \include ti/common/mmwave_error.h
127 @{ */
129 /**
130 * @brief No Error
131 */
132 #define CANFD_EOK (0)
134 /**
135 * @brief Error Code: Invalid argument
136 */
137 #define CANFD_EINVAL (-1)
139 /**
140 * @brief Error Code: Operation cannot be implemented because a previous
141 * operation is still not complete.
142 */
143 #define CANFD_EINUSE (-2)
145 /**
146 * @brief Error Code: Operation is not implemented.
147 */
148 #define CANFD_ENOTIMPL (-3)
150 /**
151 * @brief Error Code: Out of memory
152 */
153 #define CANFD_ENOMEM (-4)
154 /** @}*/
157 /** @addtogroup CANFD_DRIVER_EXTERNAL_DATA_STRUCTURE
158 @{ */
160 /*!
161 * @brief CANFD module handle returned by the CANFD_init() API call.
162 */
163 typedef void* CANFD_Handle;
165 /*!
166 * @brief CANFD message object handle returned by the CANFD_createMsgObject() API call.
167 */
168 typedef void* CANFD_MsgObjHandle;
170 /*!
171 * @brief Enumerates the values used to represent the MCAN mode of operation
172 */
173 typedef enum CANFD_MCANOperationMode_t
174 {
175 /*! MCAN normal mode */
176 CANFD_MCANOperationMode_NORMAL = 0U,
178 /*! MCAN SW initialization mode */
179 CANFD_MCANOperationMode_SW_INIT = 1U
180 }CANFD_MCANOperationMode;
182 /*!
183 * @brief This enumeration defines the values used to set the direction of message object
184 */
185 typedef enum CANFD_Direction_t
186 {
187 /*! Message object used to receive data */
188 CANFD_Direction_RX,
190 /*! Message object used to transmit data */
191 CANFD_Direction_TX
192 } CANFD_Direction;
194 /*!
195 * @brief This enumeration defines the values used to represent the CAN Identifier Type
196 */
197 typedef enum CANFD_MCANXidType_t
198 {
199 /*! 11bit MCAN Identifier */
200 CANFD_MCANXidType_11_BIT,
202 /*! 29bit MCAN Identifier */
203 CANFD_MCANXidType_29_BIT
204 } CANFD_MCANXidType;
206 /*!
207 * @brief This enumeration defines the CAN frame type
208 */
209 typedef enum CANFD_MCANFrameType_t
210 {
211 /*! Classic Frame */
212 CANFD_MCANFrameType_CLASSIC,
214 /*! FD Frame */
215 CANFD_MCANFrameType_FD
216 } CANFD_MCANFrameType;
218 /**
219 * @brief This enumeration defines the MCAN timeout counter configuration
220 */
221 typedef enum CANFD_MCANTimeOutSelect_t
222 {
223 /*! Continuous operation Mode */
224 CANFD_MCANTimeOutSelect_CONT = 0U,
226 /*! Timeout controlled by Tx Event FIFO */
227 CANFD_MCANTimeOutSelect_TX_EVENT_FIFO = 1U,
229 /*! Timeout controlled by Rx FIFO 0 */
230 CANFD_MCANTimeOutSelect_RX_FIFO0 = 2U,
232 /*! Timeout controlled by Rx FIFO 1 */
233 CANFD_MCANTimeOutSelect_RX_FIFO1 = 3U
234 }CANFD_MCANTimeOutSelect;
236 /**
237 * @brief This enumeration defines the MCAN ECC Error Types
238 */
239 typedef enum CANFD_MCANECCErrType_t
240 {
241 /*! ECC Single Error Correction */
242 CANFD_MCANECCErrType_SEC = 0U,
244 /*! ECC Single Error Detection */
245 CANFD_MCANECCErrType_DED = 1U
246 }CANFD_MCANECCErrType;
248 /**
249 * @brief This enumeration defines the MCAN Loopback mode
250 */
251 typedef enum CANFD_MCANLoopBackMode_t
252 {
253 /*! This mode can be used for hot self-test and this mode will not affect bus state. */
254 CANFD_MCANLoopBackMode_INTERNAL = 0U,
256 /*! In this mode, MCAN the MCAN treats its own transmitted messages as received messages
257 * and stores them (if they pass acceptance filtering) into an Rx Buffer or an Rx FIFO.
258 * This mode will affect bus state.
259 */
260 CANFD_MCANLoopBackMode_EXTERNAL = 1U
261 }CANFD_MCANLoopBackMode;
263 /**
264 * @brief This enumeration defines the MCAN's communication state
265 */
266 typedef enum CANFD_MCANCommState_t
267 {
268 /*! MCAN is synchronizing on CANFD communication */
269 CANFD_MCANCommState_SYNCHRONIZING = 0U,
271 /*! MCAN is neither receiver nor transmitter */
272 CANFD_MCANCommState_IDLE = 1U,
274 /*! MCAN is operating as receiver */
275 CANFD_MCANCommState_RECEIVER = 2U,
277 /*! MCAN is operating as transmitter */
278 CANFD_MCANCommState_TRANSMITTER = 3U
279 }CANFD_MCANCommState;
281 /**
282 * @brief This enumeration defines the MCAN's Error Code
283 */
284 typedef enum CANFD_MCANErrCode_t
285 {
286 /*! No error occurred since LEC has been reset by
287 * successful reception or transmission.
288 */
289 CANFD_MCANErrCode_NO_ERROR = 0U,
291 /*! More than 5 equal bits in a sequence have occurred in a part of
292 * a received message where this is not allowed.
293 */
294 CANFD_MCANErrCode_STUFF_ERROR = 1U,
296 /*! A fixed format part of a received frame has the wrong format. */
297 CANFD_MCANErrCode_FORM_ERROR = 2U,
299 /*! The message transmitted by the MCAN was not acknowledged by another node. */
300 CANFD_MCANErrCode_ACK_ERROR = 3U,
302 /*! During the transmission of a message (with the exception of
303 * the arbitration field), the device wanted to send a
304 * recessive level (bit of logical value 1),
305 * but the monitored bus value was dominant.
306 */
307 CANFD_MCANErrCode_BIT1_ERROR = 4U,
309 /*! During the transmission of a message (or acknowledge bit,
310 * or active error flag, or overload flag), the device wanted to send
311 * a dominant level (data or identifier bit logical value 0),
312 * but the monitored bus value was recessive. During Bus_Off recovery
313 * this status is set each time a sequence of 11 recessive bits has been
314 * monitored. This enables the CPU to monitor the proceeding of
315 * the Bus_Off recovery sequence (indicating the bus is not stuck at
316 * dominant or continuously disturbed).
317 */
318 CANFD_MCANErrCode_BIT0_ERROR = 5U,
320 /*! The CRC check sum of a received message was incorrect.
321 * The CRC of an incoming message does not match with the
322 * CRC calculated from the received data.
323 */
324 CANFD_MCANErrCode_CRC_ERROR = 6U,
326 /*! Any read access to the Protocol Status Register re-initializes the LEC to 7.
327 * When the LEC shows the value 7, no CANFD bus event was detected since the last
328 * CPU read access to the Protocol Status Register.
329 */
330 CANFD_MCANErrCode_NO_CHANGE = 7U
331 }CANFD_MCANErrCode;
333 /**
334 * @brief This enumeration describes a list of all the reasons for which the driver will
335 * invoke application callback functions.
336 */
337 typedef enum CANFD_Reason_t
338 {
339 /**
340 * @brief Data has been received and the application is required to read and process the data.
341 */
342 CANFD_Reason_RX = 0x1,
344 /**
345 * @brief Data has been succesfully transmitted.
346 */
347 CANFD_Reason_TX_COMPLETION = 0x2,
349 /**
350 * @brief Data transmission is succesfully canceled.
351 */
352 CANFD_Reason_TX_CANCELED = 0x3,
354 /**
355 * @brief Data has been succesfully transmitted.
356 */
357 CANFD_Reason_ECC_ERROR = 0x4,
359 /**
360 * @brief Bus Off condition detected.
361 */
362 CANFD_Reason_BUSOFF = 0x5,
364 /**
365 * @brief Protocol error in data phase detected.
366 */
367 CANFD_Reason_PROTOCOL_ERR_DATA_PHASE = 0x6,
369 /**
370 * @brief Protocol error in arbitration phase detected.
371 */
372 CANFD_Reason_PROTOCOL_ERR_ARB_PHASE = 0x7
373 }CANFD_Reason;
375 /*!
376 * @brief This enumeration defines the values used to represent the GET/SET options
377 *
378 * @sa
379 * CANFD_OptionTLV
380 */
381 typedef enum CANFD_Option_t
382 {
383 /*! Used to get the MCAN Tx and Rx error counters
384 * @sa CANFD_getOptions
385 *
386 * NOTE: The length in the TLV should be sizeof(CANFD_MCANErrCntStatus) for this option.
387 */
388 CANFD_Option_MCAN_ERROR_COUNTER,
390 /*! Used to get the MCAN protocol status
391 * @sa CANFD_getOptions
392 *
393 * NOTE: The length in the TLV should be sizeof(CANFD_MCANProtocolStatus) for this option.
394 */
395 CANFD_Option_MCAN_PROTOCOL_STATUS,
397 /*! Used to get the MCAN message object software maintained statistics
398 * @sa CANFD_getOptions
399 *
400 * NOTE: The length in the TLV should be sizeof(CANFD_MCANMsgObjectStats) for this option.
401 * Application must fill in the message object handle for which the statistics is requested.
402 *
403 */
404 CANFD_Option_MCAN_MSG_OBJECT_STATS,
406 /*! Used to put the MCAN module in init or operational state
407 * @sa CANFD_setOptions
408 *
409 * NOTE: The length in the TLV should be 1 byte for this option.
410 * Valid values: Refer to (CANFD_MCANOperationMode)
411 */
412 CANFD_Option_MCAN_MODE,
414 /*! Used to enable or disable internal/external loopback mode
415 * @sa CANFD_setOptions
416 *
417 * NOTE: The length in the TLV should be sizeof(CANFD_MCANLoopbackCfgParams) for this option.
418 *
419 */
420 CANFD_Option_MCAN_LOOPBACK,
422 /*! Used to request a local power down or wakeup from a local power down
423 * @sa CANFD_setOptions
424 *
425 * NOTE: The length in the TLV should be 1 byte for this option.
426 * Valid values are
427 * 1 - MCAN Sleep
428 * 0 - MCAN Wakeup
429 *
430 */
431 CANFD_Option_MCAN_POWER_DOWN
432 } CANFD_Option;
434 /**
435 * @brief Data structure defines the MCAN Loopback parameters.
436 */
437 typedef struct CANFD_MCANLoopbackCfgParams_t
438 {
439 /*! Enable or disable loopback mode
440 * Valid values are
441 * 0 - Disable
442 * 1 - Enable
443 */
444 uint32_t enable;
446 /*! Loopback mode: Internal or External */
447 CANFD_MCANLoopBackMode mode;
448 }CANFD_MCANLoopbackCfgParams;
450 /**
451 * @brief Data structure defines the parameters for bit timing calculation.
452 * Bit timing related to data phase will be valid only in case where
453 * MCAN is put in CANFD mode and will be '0' otherwise.
454 */
455 typedef struct CANFD_MCANBitTimingParams_t
456 {
457 /*! Nominal Baud Rate Pre-scaler */
458 uint32_t nomBrp;
460 /*! NominalProp Segment value */
461 uint32_t nomPropSeg;
463 /*! NominalPhase Segment1 value */
464 uint32_t nomPseg1;
466 /*! NominalPhase Segment2 value */
467 uint32_t nomPseg2;
469 /*! Nominal (Re)Synchronization Jump Width */
470 uint32_t nomSjw;
472 /*! Nominal Baud Rate Pre-scaler */
473 uint32_t dataBrp;
475 /*! NominalProp Segment value */
476 uint32_t dataPropSeg;
478 /*! NominalPhase Segment1 value */
479 uint32_t dataPseg1;
481 /*! NominalPhase Segment2 value */
482 uint32_t dataPseg2;
484 /*! Nominal (Re)Synchronization Jump Width */
485 uint32_t dataSjw;
486 }CANFD_MCANBitTimingParams;
488 /**
489 * @brief Data structure defines the MCAN Transmitter Delay Compensation parameters.
490 */
491 typedef struct CANFD_MCANTdcConfig_t
492 {
493 /*! Transmitter Delay Compensation Filter Window Length
494 * Range: [0x0-0x7F]
495 */
496 uint32_t tdcf;
498 /*! Transmitter Delay Compensation Offset
499 * Range: [0x0-0x7F]
500 */
501 uint32_t tdco;
502 }CANFD_MCANTdcConfig;
504 /**
505 * @brief Data structure defines the MCAN Global Filter Configuration parameters.
506 */
507 typedef struct CANFD_MCANGlobalFiltConfig_t
508 {
509 /*! Reject Remote Frames Extended
510 * 0 = Filter remote frames with 29-bit extended IDs
511 * 1 = Reject all remote frames with 29-bit extended IDs
512 */
513 uint32_t rrfe;
515 /*! Reject Remote Frames Standard
516 * 0 = Filter remote frames with 11-bit standard IDs
517 * 1 = Reject all remote frames with 11-bit standard IDs
518 */
519 uint32_t rrfs;
521 /*! Accept Non-matching Frames Extended
522 * 0 = Accept in Rx FIFO 0
523 * 1 = Accept in Rx FIFO 1
524 * others = Reject
525 */
526 uint32_t anfe;
528 /*! Accept Non-matching Frames Standard
529 * 0 = Accept in Rx FIFO 0
530 * 1 = Accept in Rx FIFO 1
531 * others = Reject
532 */
533 uint32_t anfs;
534 }CANFD_MCANGlobalFiltConfig;
536 /**
537 * @brief Data structure defines the MCAN Message RAM Configuration Parameters.
538 * Message RAM can contain following sections:
539 * Standard ID filters, Extended ID filters, TX FIFO(or TX Q),
540 * TX Buffers, TX EventFIFO, RX FIFO0, RX FIFO1, RX Buffer.
541 * Note: If particular section in the RAM is not used then it's size
542 * should be initialized to '0'
543 * (Number of buffers in case of Tx/Rx buffer).
544 */
545 typedef struct CANFD_MCANMsgRAMCfgParams_t
546 {
547 /*! List Size: Standard ID
548 * 0 = No standard Message ID filter
549 * 1-127 = Number of standard Message ID filter elements
550 * others = Values greater than 128 are interpreted as 128
551 */
552 uint32_t lss;
554 /*! List Size: Extended ID
555 * 0 = No standard Message ID filter
556 * 1-64 = Number of standard Message ID filter elements
557 * others = Values greater than 64 are interpreted as 64
558 */
559 uint32_t lse;
561 /*! Number of Dedicated Transmit Buffers
562 * 0 = No Dedicated Tx Buffers
563 * 1-32 = Number of Dedicated Tx Buffers
564 * others = Values greater than 32 are interpreted as 32
565 */
566 uint32_t txBufNum;
568 /*! Transmit FIFO/Queue Size
569 * 0 = No Tx FIFO/Queue
570 * 1-32 = Number of Tx Buffers used for Tx FIFO/Queue
571 * others = Values greater than 32 are interpreted as 32
572 */
573 uint32_t txFIFOSize;
575 /*! Tx FIFO/Queue Mode
576 * 0 = Tx FIFO operation
577 * 1 = Tx Queue operation
578 */
579 uint32_t txBufMode;
581 /*! Event FIFO Size
582 * 0 = Tx Event FIFO disabled
583 * 1-32 = Number of Tx Event FIFO elements
584 * others = Values greater than 32 are interpreted as 32
585 */
586 uint32_t txEventFIFOSize;
588 /*! Tx Event FIFO Watermark
589 * 0 = Watermark interrupt disabled
590 * 1-32 = Level for Tx Event FIFO watermark interrupt
591 * others = Watermark interrupt disabled
592 */
593 uint32_t txEventFIFOWaterMark;
595 /*! Rx FIFO0 Size
596 * 0 = No Rx FIFO
597 * 1-64 = Number of Rx FIFO elements
598 * others = Values greater than 64 are interpreted as 64
599 */
600 uint32_t rxFIFO0size;
602 /*! Rx FIFO0 Watermark
603 * 0 = Watermark interrupt disabled
604 * 1-63 = Level for Rx FIFO 0 watermark interrupt
605 * others = Watermark interrupt disabled
606 */
607 uint32_t rxFIFO0waterMark;
609 /*! Rx FIFO0 Operation Mode
610 * 0 = FIFO blocking mode
611 * 1 = FIFO overwrite mode
612 */
613 uint32_t rxFIFO0OpMode;
615 /*! Rx FIFO1 Size
616 * 0 = No Rx FIFO
617 * 1-64 = Number of Rx FIFO elements
618 * others = Values greater than 64 are interpreted as 64
619 */
620 uint32_t rxFIFO1size;
622 /*! Rx FIFO1 Watermark
623 * 0 = Watermark interrupt disabled
624 * 1-63 = Level for Rx FIFO 1 watermark interrupt
625 * others = Watermark interrupt disabled
626 */
627 uint32_t rxFIFO1waterMark;
629 /*! Rx FIFO1 Operation Mode
630 * 0 = FIFO blocking mode
631 * 1 = FIFO overwrite mode
632 */
633 uint32_t rxFIFO1OpMode;
634 }CANFD_MCANMsgRAMCfgParams;
636 /**
637 * @brief Data structure defines the MCAN ECC configuration parameters.
638 */
639 typedef struct CANFD_MCANECCConfigParams_t
640 {
641 /*! Enable/disable ECC
642 * 0 = Disable ECC
643 * 1 = Enable ECC
644 */
645 uint32_t enable;
647 /*! Enable/disable ECC Check
648 * 0 = Disable ECC Check
649 * 1 = Enable ECC Check
650 */
651 uint32_t enableChk;
653 /*! Enable/disable Read Modify Write operation
654 * 0 = Disable Read Modify Write operation
655 * 1 = Enable Read Modify Write operation
656 */
657 uint32_t enableRdModWr;
658 }CANFD_MCANECCConfigParams;
660 /**
661 * @brief Data structure defines the MCAN error logging counters status.
662 */
663 typedef struct CANFD_MCANErrCntStatus_t
664 {
665 /*! Transmit Error Counter */
666 uint32_t transErrLogCnt;
668 /*! Receive Error Counter */
669 uint32_t recErrCnt;
671 /*! Receive Error Passive
672 * 0 = The Receive Error Counter is below the error passive level(128)
673 * 1 = The Receive Error Counter has reached the error passive level(128)
674 */
675 uint32_t rpStatus;
677 /*! CAN Error Logging */
678 uint32_t canErrLogCnt;
679 }CANFD_MCANErrCntStatus;
681 /**
682 * @brief Data structure defines the MCAN protocol status.
683 */
684 typedef struct CANFD_MCANProtocolStatus_t
685 {
686 /*! Last Error Code
687 * Refer enum #CANFD_MCANErrCode
688 */
689 uint32_t lastErrCode;
691 /*! Activity - Monitors the module's CAN communication state.
692 * refer enum #CANFD_MCANCommState
693 */
694 uint32_t act;
696 /*! Error Passive
697 * 0 = The M_CAN is in the Error_Active state
698 * 1 = The M_CAN is in the Error_Passive state
699 */
700 uint32_t errPassive;
702 /*! Warning Status
703 * 0 = Both error counters are below the Error_Warning limit of 96
704 * 1 = At least one of error counter has reached the Error_Warning
705 * limit of 96
706 */
707 uint32_t warningStatus;
709 /*! Bus_Off Status
710 * 0 = The M_CAN is not Bus_Off
711 * 1 = The M_CAN is in Bus_Off state
712 */
713 uint32_t busOffStatus;
715 /*! Data Phase Last Error Code
716 * Refer enum #CANFD_MCANErrCode
717 */
718 uint32_t dlec;
720 /*! ESI flag of last received CAN FD Message
721 * 0 = Last received CAN FD message did not have its ESI flag set
722 * 1 = Last received CAN FD message had its ESI flag set
723 */
724 uint32_t resi;
726 /*! BRS flag of last received CAN FD Message
727 * 0 = Last received CAN FD message did not have its BRS flag set
728 * 1 = TLast received CAN FD message had its BRS flag set
729 */
730 uint32_t rbrs;
732 /*! Received a CAN FD Message
733 * 0 = Since this bit was reset by the CPU, no CAN FD message has been
734 * received
735 * 1 = Message in CAN FD format with FDF flag set has been received
736 */
737 uint32_t rfdf;
739 /*! Protocol Exception Event
740 * 0 = No protocol exception event occurred since last read access
741 * 1 = Protocol exception event occurred
742 */
743 uint32_t pxe;
745 /*! Transmitter Delay Compensation Value */
746 uint32_t tdcv;
747 }CANFD_MCANProtocolStatus;
749 /**
750 * @brief Data structure defines the ECC Error forcing.
751 */
752 typedef struct CANFD_MCANECCErrForceParams_t
753 {
754 /*! Error type to be forced
755 * Refer enum #CANFD_MCANECCErrType.
756 */
757 uint32_t errType;
759 /*! Row address where error needs to be applied. */
760 uint32_t rowNum;
762 /*! Column/Data bit that needs to be flipped when
763 * force_sec or force_ded is set
764 */
765 uint32_t bit1;
767 /*! Data bit that needs to be flipped when force_ded is set */
768 uint32_t bit2;
770 /*! Force Error once
771 * 1: The error will inject an error to the specified row only once
772 */
773 uint32_t errOnce;
775 /*! Force error on the next RAM read */
776 uint32_t errForce;
777 }CANFD_MCANECCErrForceParams;
779 /**
780 * @brief Data structure defines the ECC Error Status.
781 */
782 typedef struct CANFD_MCANECCErrStatus_t
783 {
784 /*! Single Bit Error Status
785 * 0 = No Single Bit Error pending
786 * 1 = Single Bit Error pending
787 */
788 uint32_t secErr;
790 /*! Double Bit Error Status
791 * 0 = No Double Bit Error pending
792 * 1 = Double Bit Error pending
793 */
794 uint32_t dedErr;
796 /*! Indicates the row/address where the single or double bit
797 * error occurred.
798 */
799 uint32_t row;
801 /*! Indicates the bit position in the ram data that is in error
802 */
803 uint32_t bit1;
805 /*! Indicates the bit position in the ram data that is in error
806 * Valid only in case of DED.
807 */
808 uint32_t bit2;
809 }CANFD_MCANECCErrStatus;
811 /*!
812 * @brief
813 * Response structure definition for Error and status information.
814 */
815 typedef struct CANFD_ErrStatusResp_t
816 {
817 union
818 {
819 /*! ECC Error Status. */
820 CANFD_MCANECCErrStatus eccErrStatus;
822 /*! Protocol Status. */
823 CANFD_MCANProtocolStatus protocolStatus;
824 }u;
825 } CANFD_ErrStatusResp;
827 /**
828 * @brief
829 * Application specified callback function which is invoked
830 * by the CANFD driver once transmit is complete or data has been received for the
831 * specified message object.
832 *
833 * @param[in] handle
834 * Message object handle for which the callback function is invoked.
835 * @param[in] reason
836 * Cause of the interrupt which prompted the callback.
837 *
838 * @retval
839 * Not applicable
840 */
841 typedef void (*CANFD_DataAppCallBack)(CANFD_MsgObjHandle handle, CANFD_Reason reason);
843 /**
844 * @brief
845 * Application specified callback function which is invoked
846 * by the CANFD driver on error or status change.
847 *
848 * @param[in] handle
849 * Handle to the CANFD Driver
850 * @param[in] reason
851 * Cause of the interrupt which prompted the callback.
852 * @param[in] errStatusResp
853 * Response structure populated with the value of the fields that caused the error or status interrupt.
854 * Processing of this structure is dependent on the callback reason.
855 *
856 * @retval
857 * Not applicable
858 */
859 typedef void (*CANFD_ErrStatusAppCallBack)(CANFD_Handle handle, CANFD_Reason reason, CANFD_ErrStatusResp* errStatusResp);
861 /**
862 * @brief Data structure defines the MCAN initialization parameters.
863 */
864 typedef struct CANFD_MCANInitParams_t
865 {
866 /*! FD Operation Enable
867 * 0 = FD operation disabled
868 * 1 = FD operation enabled
869 */
870 uint32_t fdMode;
872 /*! Bit Rate Switch Enable
873 * This is valid only when opMode = 1.
874 * 0 = Bit rate switching for transmissions disabled
875 * 1 = Bit rate switching for transmissions enabled
876 */
877 uint32_t brsEnable;
879 /*! Transmit Pause
880 * 0 = Transmit pause disabled
881 * 1 = Transmit pause enabled
882 */
883 uint32_t txpEnable;
885 /*! FEdge Filtering during Bus Integration
886 * 0 = Edge filtering disabled
887 * 1 = Two consecutive dominant tq required to detect an edge for
888 * hard synchronization
889 */
890 uint32_t efbi;
892 /*! Protocol Exception Handling Disable
893 * 0 = Protocol exception handling enabled
894 * 1 = Protocol exception handling disabled
895 */
896 uint32_t pxhddisable;
898 /*! Disable Automatic Retransmission
899 * 0 = Automatic retransmission of messages not transmitted successfully
900 * enabled
901 * 1 = Automatic retransmission disabled
902 */
903 uint32_t darEnable;
905 /*! Wakeup Request Enable
906 * 0 = Wakeup request is disabled
907 * 1 = Wakeup request is enabled
908 */
909 uint32_t wkupReqEnable;
911 /*! Auto-Wakeup Enable
912 * 0 = Auto-Wakeup is disabled
913 * 1 = Auto-Wakeup is enabled
914 */
915 uint32_t autoWkupEnable;
917 /*! Emulation/Debug Suspend Enable
918 * 0 = Emulation/Debug Suspend is disabled
919 * 1 = Emulation/Debug Suspend is enabled
920 */
921 uint32_t emulationEnable;
923 /*! Emulation/Debug Suspend Fast Ack Enable
924 * 0 = Emulation/Debug Suspend does not wait for idle/immediate effect
925 * 1 = Emulation/Debug Suspend waits for idle/graceful stop
926 */
927 uint32_t emulationFAck;
929 /*! Clock Stop Fast Ack Enable
930 * 0 = Clock Stop does not wait for idle/immediate effect
931 * 1 = Clock Stop waits for idle/graceful stop
932 */
933 uint32_t clkStopFAck;
935 /*! Start value of the Message RAM Watchdog Counter
936 * Range:[0x0-0xFF]
937 */
938 uint32_t wdcPreload;
940 /*! Transmitter Delay Compensation Enable
941 * 0 = Transmitter Delay Compensation is disabled
942 * 1 = Transmitter Delay Compensation is enabled
943 */
944 uint32_t tdcEnable;
946 /*! Transmitter Delay Compensation parameters.
947 * Refer struct #CANFD_MCANTdcConfig.
948 */
949 CANFD_MCANTdcConfig tdcConfig;
951 /*! Bus Monitoring Mode
952 * 0 = Bus Monitoring Mode is disabled
953 * 1 = Bus Monitoring Mode is enabled
954 */
955 uint32_t monEnable;
957 /*! Restricted Operation Mode
958 * 0 = Normal CAN operation
959 * 1 = Restricted Operation Mode active
960 * This mode should not be combined with test modes.
961 */
962 uint32_t asmEnable;
964 /*! Timestamp Counter Prescaler.
965 * Range:[0x0-0xF]
966 */
967 uint32_t tsPrescalar;
969 /*! Timeout source selection.
970 * 00b: Timestamp counter value always 0x0000
971 * 01b: Timestamp counter value incremented according to tsPrescalar
972 * 10b: External timestamp counter value used
973 * 11b: Same as 00b
974 */
975 uint32_t tsSelect;
977 /*! Time-out counter source select.
978 * Refer enum #CANFD_MCANTimeOutSelect.
979 */
980 CANFD_MCANTimeOutSelect timeoutSelect;
982 /*! Start value of the Timeout Counter (down-counter).
983 * The Timeout Counter is decremented in multiples of CAN bit times [1-16]
984 * depending on the configuration of the tsPrescalar.
985 * Range: [0x0-0xFFFF]
986 */
987 uint32_t timeoutPreload;
989 /*! Timeout Counter Enable
990 * 0 - Timeout Counter is disabled
991 * 1 - Timeout Counter is enabled
992 */
993 uint32_t timeoutCntEnable;
995 /*! Global Filter Configuration parameters.
996 * Refer struct #CANFD_MCANGlobalFiltConfig.
997 */
998 CANFD_MCANGlobalFiltConfig filterConfig;
1000 /*! Message RAM Configuration parameters.
1001 * Refer struct #CANFD_MCANMsgRAMCfgParams.
1002 */
1003 CANFD_MCANMsgRAMCfgParams msgRAMConfig;
1005 /*! ECC Configuration parameters.
1006 * Refer struct #CANFD_MCANECCConfigParams.
1007 */
1008 CANFD_MCANECCConfigParams eccConfig;
1010 /*! Enable/Disable error/status interrupts
1011 * Note: Must be enabled to receive error and status interrupts. */
1012 uint32_t errInterruptEnable;
1014 /*! Enable/Disable data interrupts.
1015 * Note: Must be enabled to receive transmit complete and data receive interrupts. */
1016 uint32_t dataInterruptEnable;
1018 /**
1019 * @brief Application specified callback function which is invoked
1020 * by the CANFD driver on error or status interrrupts if errInterruptEnable is set to 1.
1021 */
1022 CANFD_ErrStatusAppCallBack appErrCallBack;
1024 /**
1025 * @brief Application specified callback function which is invoked
1026 * by the CANFD driver once Tx complete or data receive interrupt has been received
1027 * if dataInterruptEnable is set to 1.
1028 */
1029 CANFD_DataAppCallBack appDataCallBack;
1030 }CANFD_MCANInitParams;
1032 /*!
1033 * @brief
1034 * Parameters used to configure the receive and transmit message objects.
1035 */
1036 typedef struct CAN_MCANMsgObjCfgParams_t
1037 {
1038 /*! Message object direction. For valid values refer to enum #CANFD_Direction. */
1039 CANFD_Direction direction;
1041 /*! MCAN Id type: Standard / Extended Identifier. For valid values refer enum #CANFD_MCANXidType. */
1042 CANFD_MCANXidType msgIdType;
1044 /*! Message Identifier - [28:0] are valid bits. */
1045 uint32_t msgIdentifier;
1046 } CANFD_MCANMsgObjCfgParams;
1048 /*!
1049 * @brief
1050 * Parameters used to configure a receive message objects for a range of message identifiers.
1051 */
1052 typedef struct CAN_MCANRxMsgObjRangeCfgParams_t
1053 {
1054 /*! MCAN Id type: Standard / Extended Identifier. For valid values refer enum #CANFD_MCANXidType. */
1055 CANFD_MCANXidType msgIdType;
1057 /*! Starting Message Identifier - [28:0] are valid bits. */
1058 uint32_t startMsgIdentifier;
1060 /*! Ending Message Identifier - [28:0] are valid bits. */
1061 uint32_t endMsgIdentifier;
1062 } CANFD_MCANRxMsgObjRangeCfgParams;
1064 /*!
1065 * @brief Data structure defines the software maintained message object statistics.
1066 */
1067 typedef struct CANFD_MCANMsgObjectStats_t
1068 {
1069 /*! Message Object Handle for which the statistics is requested */
1070 CANFD_MsgObjHandle handle;
1072 /*! Message Object direction */
1073 uint32_t direction;
1075 /*! Starting range of the Message Id to which the configuration belongs.
1076 * For Tx and single Message Id objects the startMsgIdentifier = endMsgIdentifier */
1077 uint32_t startMsgIdentifier;
1079 /*! Ending range of the Message Id to which the configuration belongs
1080 * For Tx and single Message Id objects the startMsgIdentifier = endMsgIdentifier. */
1081 uint32_t endMsgIdentifier;
1083 /*! Number of interrupts received */
1084 uint32_t interruptsRxed;
1086 /*! Number of messages processed */
1087 uint32_t messageProcessed;
1088 } CANFD_MCANMsgObjectStats;
1090 /**
1091 * @brief
1092 * Options TLV data structure
1093 *
1094 * @details
1095 * Specifies the option type, length, value.
1096 */
1097 typedef struct CANFD_OptionTLV_t
1098 {
1099 /**
1100 * @brief Option Name
1101 */
1102 CANFD_Option type;
1104 /**
1105 * @brief Option Length
1106 */
1107 int32_t length;
1109 /**
1110 * @brief Option Value
1111 */
1112 void* value;
1113 }CANFD_OptionTLV;
1115 /** @}*/
1117 /** @addtogroup CANFD_DRIVER_EXTERNAL_FUNCTION
1118 @{ */
1120 /**
1121 * @b Description
1122 * @n
1123 * Function initializes the CANFD driver instance with the specified hardware attributes.
1124 * It resets and configures the MCAN module, sets up the Message RAM and ECC Aggregator.
1125 * It configures the CANFD driver with the control parameters.
1126 *
1127 * @param[in] instanceId
1128 * CANFD Instance Id.
1129 * Note: Currently only 1 instance of CANFD is supported.
1130 * Valid value is 0.
1131 * @param[in] configParams
1132 * CANFD module configuration parameters
1133 * @param[out] errCode
1134 * Error code populated on error
1135 *
1136 * @retval
1137 * Success - Handle to the CANFD Driver
1138 * @retval
1139 * Error - NULL
1140 */
1142 CANFD_Handle CANFD_init(uint8_t instanceId, const CANFD_MCANInitParams* configParams, int32_t* errCode);
1144 /**
1145 * @b Description
1146 * @n
1147 * Function closes the CANFD driver instance and cleanups all the memory allocated by the CANFD driver.
1148 *
1149 * @param[in] handle
1150 * Handle to the CANFD Driver
1151 * @param[out] errCode
1152 * Error code populated on error
1153 *
1154 * @retval
1155 * Success - 0
1156 * @retval
1157 * Error - <0
1158 */
1160 extern int32_t CANFD_deinit(CANFD_Handle handle, int32_t* errCode);
1162 /**
1163 * @b Description
1164 * @n
1165 * Function configures the bit time parameters for the CANFD module.
1166 *
1167 * @param[in] handle
1168 * Handle to the CANFD Driver
1169 * @param[in] bitTimeParams
1170 * Bit time configuration parameters
1171 * @param[out] errCode
1172 * Error code populated on error
1173 *
1174 * @retval
1175 * Success - 0
1176 * @retval
1177 * Error - <0
1178 */
1179 extern int32_t CANFD_configBitTime(CANFD_Handle handle, const CANFD_MCANBitTimingParams* bitTimeParams, int32_t* errCode);
1181 /**
1182 * @b Description
1183 * @n
1184 * Function configures the receive or transmit message object.
1185 * It also enables Tx completion and Tx cancelation interrupts .
1186 * The callback function will be invoked on data transmit complete for transmit message objects
1187 * OR
1188 * upon receiving data for receive message objects. The application MUST then call CANFD_getData() API to process the received data.
1189 *
1190 * @param[in] handle
1191 * Handle to the CANFD Driver
1192 * @param[in] msgObjectParams
1193 * Message Object configuration parameters
1194 * @param[out] errCode
1195 * Error code populated on error
1196 *
1197 * @retval
1198 * Success - Handle to the message object.
1199 * @retval
1200 * Error - NULL
1201 */
1202 extern CANFD_MsgObjHandle CANFD_createMsgObject(CANFD_Handle handle, const CANFD_MCANMsgObjCfgParams* msgObjectParams, int32_t* errCode);
1204 /**
1205 * @b Description
1206 * @n
1207 * Function configures a receive message objects for a range of message identifiers.
1208 * It also enables Rx interrupts.
1209 * The callback function will be invoked upon receiving data for receive message objects.
1210 * The application MUST then call CANFD_getData() API to process the received data.
1211 *
1212 * @param[in] handle
1213 * Handle to the CANFD Driver
1214 * @param[in] msgObjectParams
1215 * Message Object configuration parameters
1216 * @param[out] errCode
1217 * Error code populated on error
1218 *
1219 * @retval
1220 * Success - Handle to the message object.
1221 * @retval
1222 * Error - NULL
1223 */
1224 extern CANFD_MsgObjHandle CANFD_createRxRangeMsgObject(CANFD_Handle handle, const CANFD_MCANRxMsgObjRangeCfgParams* msgObjectParams, int32_t* errCode);
1226 /**
1227 * @b Description
1228 * @n
1229 * Function deletes a message object.
1230 *
1231 * @param[in] handle
1232 * Handle to the message object
1233 * @param[out] errCode
1234 * Error code populated on error
1235 *
1236 * @retval
1237 * Success - 0
1238 * @retval
1239 * Error - <0
1240 */
1241 extern int32_t CANFD_deleteMsgObject(CANFD_MsgObjHandle handle, int32_t* errCode);
1243 /**
1244 * @b Description
1245 * @n
1246 * Function used by the application to transmit data.
1247 *
1248 * @param[in] handle
1249 * Handle to the message object
1250 * @param[in] id
1251 * Message Identifier
1252 * @param[in] frameType
1253 * Frame type - Classic or FD
1254 * @param[in] dataLength
1255 * Data Length to be transmitted.
1256 * Valid values: 1 to 64 bytes.
1257 * @param[in] data
1258 * Data to be transmitted
1259 * @param[out] errCode
1260 * Error code populated on error
1261 *
1262 * @retval
1263 * Success - 0
1264 * @retval
1265 * Error - <0
1266 */
1267 extern int32_t CANFD_transmitData(CANFD_MsgObjHandle handle, uint32_t id, CANFD_MCANFrameType frameType, uint32_t dataLength, const uint8_t* data, int32_t* errCode);
1269 /**
1270 * @b Description
1271 * @n
1272 * Function used by the application to cancel a pending data transmit.
1273 *
1274 * @param[in] handle
1275 * Handle to the message object
1276 * @param[out] errCode
1277 * Error code populated on error
1278 *
1279 * @retval
1280 * Success - 0
1281 * @retval
1282 * Error - <0
1283 */
1284 extern int32_t CANFD_transmitDataCancel(CANFD_MsgObjHandle handle, int32_t* errCode);
1286 /**
1287 * @b Description
1288 * @n
1289 * Function is used by the application to get the CAN message from message RAM using a receive message object.
1290 * NOTE: This API must ONLY be called from the callback context.
1291 *
1292 * @param[in] handle
1293 * Handle to the message object
1294 * @param[out] id
1295 * Message Identifier
1296 * @param[out] ptrFrameType
1297 * Frame type - Classic or FD
1298 * @param[out] idType
1299 * Meassage Id type - 11 bit standard or 29 bit extended
1300 * @param[out] ptrDataLength
1301 * Data Length of the received frame.
1302 * Valid values: 1 to 64 bytes.
1303 * @param[out] data
1304 * Received data.
1305 * @param[out] errCode
1306 * Error code populated on error
1307 *
1308 * @retval
1309 * Success - 0
1310 * @retval
1311 * Error - <0
1312 */
1313 extern int32_t CANFD_getData(CANFD_MsgObjHandle handle, uint32_t* id, CANFD_MCANFrameType* ptrFrameType, CANFD_MCANXidType* idType, uint32_t* ptrDataLength, uint8_t* data, int32_t* errCode);
1315 /**
1316 * @b Description
1317 * @n
1318 * Function is used by the application to get the error and status information from the driver.
1319 *
1320 * @param[in] handle
1321 * Handle to the CANFD Driver
1322 * @param[out] ptrOptInfo
1323 * Option info in TLV format which is populated with the requested information
1324 * @param[out] errCode
1325 * Error code populated on error
1326 *
1327 * @retval
1328 * Success - 0
1329 * @retval
1330 * Error - <0
1331 */
1332 extern int32_t CANFD_getOptions(CANFD_Handle handle, const CANFD_OptionTLV* ptrOptInfo, int32_t* errCode);
1334 /**
1335 * @b Description
1336 * @n
1337 * Function is used by the application to configure the driver options.
1338 *
1339 * @param[in] handle
1340 * Handle to the CANFD Driver
1341 * @param[in] ptrOptInfo
1342 * Option info in TLV format which is used to configure the driver
1343 * @param[out] errCode
1344 * Error code populated on error
1345 *
1346 * @retval
1347 * Success - 0
1348 * @retval
1349 * Error - <0
1350 */
1351 extern int32_t CANFD_setOptions(CANFD_Handle handle, const CANFD_OptionTLV* ptrOptInfo, int32_t* errCode);
1352 /** @}*/
1354 #ifdef __cplusplus
1355 }
1356 #endif
1358 #endif /* #ifndef CANFD_H_ */