AM263Px MCU+ SDK: canfd.h File Reference

| AM263Px MCU+ SDK 26.00.00 |

Data Structures
canfd.h File Reference
APIs for SOC Specific Device Drivers » APIs for CANFD

## Introduction

This is the header file for the CANFD driver which exposes the data structures and exported API which can be used by the applications to use the CANFD driver.

The CANFD driver provides functionality of transferring data between CANFD peripherals. This driver does not interpret any of the data sent to or received from using this peripheral.

The CANFD header file should be included in an application as follows:

#include <ti/drivers/canfd/canfd.h>

## Initializing the driver

The CANFD Driver needs to be initialized once across the System. This is done using the CANFD_open. None of the CANFD API's can be used without invoking this API.

Once the CANFD Driver has been initialized; the bit timing can be configured using CANFD_configBitTime. This APIs can be called multiple times to reconfigure bit timings.

## Creating the message objects

Message objects are used to transmit or receive data over the CANFD peripheral. A message object is created using CANFD_createMsgObject.

## Sending and receiving data

Data is transmitted using the CANFD_write. The application will be notified when the transmit is complete if it has enabled dataInterruptEnable and registered a callback function appDataCallBack when initializing the CANFD driver.

If the receive interrupts are enabled using dataInterruptEnable field and a callback function appCallBack has been registered when initializing the CANFD driver, the driver notifies the application when the data has arrived. The application needs to call the CANFD_read function to read the received data.

## Error and status handling

The application can monitor the ECC error, Bus off error and Protocol Errors by enabling the error interrupts errInterruptEnable. The driver will call the registered callback function appErrCallBack to indicate which error fields caused the interrupt. It is up to the application to take appropriate action.

## Get/Set Options

Helper APIs to get and set various statistics, error counters, ECC diagnostics, power down have been provided. Refer to CANFD_Option for more information.

## Limitation

The CANFD driver does not support the DMA or power down.

Go to the source code of this file.

typedef struct CANFD_Config_s * | CANFD_Handle
| A handle that is returned from a CANFD_open() call. More...
uint32_t | gCANFDConfigNum
| Externally defined driver configuration array size. More...

## CANFD ECC error type
#define | CANFD_MCAN_ECC_ERR_TYPE_SEC (0U)
#define | CANFD_MCAN_ECC_ERR_TYPE_DED (1U)
typedef uint32_t | CANFD_MCANECCErrType
| This enumeration defines the MCAN ECC Error Types. More...

## Data Structures
struct | CANFD_MCANLoopbackCfgParams
struct | CANFD_MCANBitTimingParams
struct | CANFD_MCANTdcConfig
struct | CANFD_MCANGlobalFiltConfig
struct | CANFD_MCANMsgRAMCfgParams
struct | CANFD_MCANECCConfigParams
struct | CANFD_MCANErrCntStatus
struct | CANFD_MCANProtocolStatus
struct | CANFD_MCANECCErrForceParams
struct | CANFD_MCANECCErrStatus
union | CANFD_ErrStatusResp
struct | CANFD_Attrs
struct | CANFD_OptionTLV
struct | CANFD_OpenParams
struct | CANFD_Object
struct | CANFD_Config
struct | CANFD_DmaMsgConfig
struct | CANFD_DmaRxBuf
struct | CANFD_MessageObject
struct | CANFD_MCANMsgObjectStats

## Macros
Return status
Return status when the API execution was successful
#define | MCAN_STATUS_SUCCESS ((int32_t)0)
#define | MCAN_STATUS_FAILURE ((int32_t)-1)
| Return status when the API execution was not successful due to a failure. More...
Transfer Mode
This determines whether the driver operates synchronously or asynchronously In CANFD_TRANSFER_MODE_BLOCKING mode CANFD_write() blocks code execution until the transaction has completed In CANFD_TRANSFER_MODE_CALLBACK CANFD_write() does not block code execution and instead calls a CANFD_TransferCallbackFxn callback function when the transaction has completed
#define | CANFD_TRANSFER_MODE_BLOCKING (0U)
| CANFD_write() blocks execution. This mode can only be used when called within a Task context More...
#define | CANFD_TRANSFER_MODE_CALLBACK (1U)
| CANFD_write() does not block code execution and will call a CANFD_TransferCallbackFxn. This mode can be used in a Task, Swi, or Hwi context More...
Operating Mode
Values used to determine the CANFD driver operation.
#define | CANFD_OPER_MODE_POLLED (0U)
#define | CANFD_OPER_MODE_INTERRUPT (1U)
#define | CANFD_OPER_MODE_DMA (2U)
#define | MCAN_MSG_RAM_STD_ELEM_SIZE (1U)
| The section has a list of all the data structures which are exposed to the application. More...
#define | MCAN_MSG_RAM_EXT_ELEM_SIZE (2U)
| Extended ID Filter Element Size. More...
#define | MCAN_MSG_HEADER_SIZE (8U)
| MCAN Header size in Bytes. More...
#define | MCAN_FRAME_TYPE_FD (1U)
| MCAN Frame type FD. More...
#define | MCAN_MSG_RAM_TX_RX_ELEM_SIZE (18U)
| Tx/Rx Element Size. 18 words = 18 * 4 = 72 bytes: 8 bytes of header and 64 bytes of data. More...
#define | XTD_MSGID_MASK (0x1fffffffU)
| Message Identifier Masks. More...
#define | STD_MSGID_MASK (0x7ffU)
#define | STD_MSGID_SHIFT (18U)
#define | MCAN_MAX_PAYLOAD_BYTES (64U)
| Maximum payload supported by CAN-FD protocol in bytes. More...
#define | MCAN_MAX_RX_BUFFERS (64U)
| Maximum number of Rx buffers. More...
#define | MCAN_MAX_TX_BUFFERS (32U)
| Maximum number of Tx buffers. More...
#define | CANFD_UTILS_ARRAYSIZE(x) (sizeof(x) / sizeof(x[0]))
| Macro to get the size of an array. More...
#define | CANFD_UTILS_GETARRAYINDEX(member, array) (member - &array[0])
| Get the index of the given element within an array. More...
#define | CANFD_UTILS_ARRAYISMEMBER(member, array)
| Macro to determine if a member is part of an array. More...
#define | MCAN_INTR_MASK
| Defines all the interrupt are enabled. More...
#define | CANFD_DMA_TX_COMPLETION_INTERMEDIATE (1U)
| completion type for Tx in dma mode - Intermediate completion More...
#define | CANFD_DMA_TX_COMPLETION_FINAL (2U)
| completion type for Tx in dma mode - Final completion More...
#define | CANFD_DMA_RX_COMPLETION_INTERMEDIATE (1U)
| completion type for Rx in dma mode - Intermediate completion More...
#define | CANFD_DMA_RX_COMPLETION_FINAL (2U)
| completion type for Rx in dma mode - Final completion More...
#define | CANFD_MAX_DLC_MAPPING (16U)
| Maximum data to DLC mapping supported. Refer MCAN_DataLengthSize. More...
CANFD Driver State
This macros defines the values used to represent the CANFD driver state
#define | CANFD_DRIVER_STATE_UNINIT (0U)
#define | CANFD_DRIVER_STATE_STARTED (1U)
#define | CANFD_DRIVER_STATE_STOPPED (2U)
#define | CCANFD_DRIVER_STATE_SLEEP (3U)

## Typedefs
CANFD Option TLV
Options TLV data structure Specifies the option type, length, value.
typedef void(* | CANFD_TransferCallbackFxn) (void *args, CANFD_Reason reason)
| The definition of a callback function used by the CANFD driver when used in CANFD_TRANSFER_MODE_CALLBACK. More...
typedef void(* | CANFD_ErrorCallbackFxn) (void *args, CANFD_Reason reason, CANFD_ErrStatusResp *errStatusResp)
| The definition of a callback function used by the CANFD driver when used in CANFD_TRANSFER_MODE_CALLBACK in case of error. More...
CANFD Message Handle
CANFD message object handle returned by the CANFD_createMsgObject() API call.
typedef CANFD_MessageObject * | CANFD_MsgObjHandle

## Enumerations
CANFD Element Size
This enumeration defines the MCAN FIFO/Buffer element Size
enum | CANFD_MCANElemSize { CANFD_MCANElemSize_8BYTES = 0U, CANFD_MCANElemSize_12BYTES = 1U, CANFD_MCANElemSize_16BYTES = 2U, CANFD_MCANElemSize_20BYTES = 3U, CANFD_MCANElemSize_24BYTES = 4U, CANFD_MCANElemSize_32BYTES = 5U, CANFD_MCANElemSize_48BYTES = 6U, CANFD_MCANElemSize_64BYTES = 7U }
CANFD Operation Mode
Enumerates the values used to represent the MCAN mode of operation
enum | CANFD_MCANOperationMode { CANFD_MCANOperationMode_NORMAL = 0U, CANFD_MCANOperationMode_SW_INIT = 1U }
CANFD Direction
This enumeration defines the values used to set the direction of message object
enum | CANFD_Direction { CANFD_Direction_RX, CANFD_Direction_TX }
CANFD Identifier Type
This enumeration defines the values used to represent the CAN Identifier Type
enum | CANFD_MCANXidType { CANFD_MCANXidType_11_BIT, CANFD_MCANXidType_29_BIT }
CANFD Frame Type
This enumeration defines the CAN frame type
enum | CANFD_MCANFrameType { CANFD_MCANFrameType_CLASSIC, CANFD_MCANFrameType_FD }
CANFD Time out select
This enumeration defines the MCAN timeout counter configuration
enum | CANFD_MCANTimeOutSelect { CANFD_MCANTimeOutSelect_CONT = 0U, CANFD_MCANTimeOutSelect_TX_EVENT_FIFO = 1U, CANFD_MCANTimeOutSelect_RX_FIFO0 = 2U, CANFD_MCANTimeOutSelect_RX_FIFO1 = 3U }
CANFD Loopback mode
This enumeration defines the MCAN Loopback mode
enum | CANFD_MCANLoopBackMode { CANFD_MCANLoopBackMode_INTERNAL = 0U, CANFD_MCANLoopBackMode_EXTERNAL = 1U }
CANFD Communication State
This enumeration defines the MCAN's communication state
enum | CANFD_MCANCommState { CANFD_MCANCommState_SYNCHRONIZING = 0U, CANFD_MCANCommState_IDLE = 1U, CANFD_MCANCommState_RECEIVER = 2U, CANFD_MCANCommState_TRANSMITTER = 3U }
CANFD Error Code
This enumeration defines the MCAN's Error Code
enum | CANFD_MCANErrCode { CANFD_MCANErrCode_NO_ERROR = 0U, CANFD_MCANErrCode_STUFF_ERROR = 1U, CANFD_MCANErrCode_FORM_ERROR = 2U, CANFD_MCANErrCode_ACK_ERROR = 3U, CANFD_MCANErrCode_BIT1_ERROR = 4U, CANFD_MCANErrCode_BIT0_ERROR = 5U, CANFD_MCANErrCode_CRC_ERROR = 6U, CANFD_MCANErrCode_NO_CHANGE = 7U }
CANFD reason
This enumeration describes a list of all the reasons for which the driver will invoke application callback functions.
enum | CANFD_Reason { CANFD_Reason_RX = 0x1, CANFD_Reason_TX_COMPLETION = 0x2, CANFD_Reason_TX_CANCELED = 0x3, CANFD_Reason_ECC_ERROR = 0x4, CANFD_Reason_BUSOFF = 0x5, CANFD_Reason_PROTOCOL_ERR_DATA_PHASE = 0x6, CANFD_Reason_PROTOCOL_ERR_ARB_PHASE = 0x7, CANFD_Reason_SRC_RX_FIFO0_MSG_LOST = 0x8, CANFD_Reason_SRC_RX_FIFO1_MSG_LOST = 0x9 }
CANFD Option
This enumeration defines the values used to represent the GET/SET options See also CANFD_OptionTLV
enum | CANFD_Option { CANFD_Option_MCAN_ERROR_COUNTER, CANFD_Option_MCAN_PROTOCOL_STATUS, CANFD_Option_MCAN_MSG_OBJECT_STATS, CANFD_Option_MCAN_MODE, CANFD_Option_MCAN_LOOPBACK, CANFD_Option_MCAN_POWER_DOWN }

## Functions
CANFD Dma Config
CANFD DMA Configuration, these are filled by SysCfg based on the DMA driver(EDMA/UDMA) that is selected
void | CANFD_init (void)
| This function initializes each driver instance object and create a driver lock. More...
void | CANFD_deinit (void)
| This function de-initializes each driver instance object and delete a driver lock. More...
CANFD_Handle | CANFD_open (uint32_t index, CANFD_OpenParams *openPrms)
| This function opens a given CANFD peripheral. More...
void | CANFD_close (CANFD_Handle handle)
| Function to close a CANFD peripheral specified by the CANFD handle. More...
int32_t | CANFD_configBitTime (CANFD_Handle handle, const CANFD_MCANBitTimingParams *bitTimeParams)
| Function configures the bit time parameters for the CANFD module. More...
int32_t | CANFD_createMsgObject (CANFD_Handle handle, CANFD_MessageObject *ptrCanMsgObj)
| Function configures the receive or transmit message object. It also enables Tx completion and Tx cancelation interrupts. The callback function will be invoked on data transmit complete for transmit message objects OR upon receiving data for receive message objects. The application MUST then call CANFD_read() API to process the received data. More...
int32_t | CANFD_createRxRangeMsgObject (CANFD_Handle handle, CANFD_MessageObject *ptrCanMsgObj)
| Function configures a receive message objects for a range of message identifiers. It also enables Rx interrupts. The callback function will be invoked upon receiving data for receive message objects. The application MUST then call CANFD_read() API to process the received data. More...
int32_t | CANFD_deleteMsgObject (CANFD_MsgObjHandle handle)
| Function deletes a message object. More...
int32_t | CANFD_write (CANFD_MsgObjHandle handle, uint32_t id, CANFD_MCANFrameType frameType, uint32_t numMsgs, const uint8_t *data)
| Function used by the application to transmit data. More...
int32_t | CANFD_writeCancel (CANFD_MsgObjHandle handle)
| Function used by the application to cancel a pending data transmit. More...
int32_t | CANFD_writeDma (CANFD_MsgObjHandle handle, uint32_t id, CANFD_MCANFrameType frameType, uint32_t numMsgs, const void *data)
| Function used by the application to initiate transmit data in dma mode. DMA mode is recommended to be used when multiple msgs needs to be transmitted. This will transmit first msg and configure the dma to copy subsequent msgs in message ram. Once first msg transfer is completed the CANFD_dmaTxCompletionCallback function is called. Application needs to call the API CANFD_writeDmaTriggerNext to trigger transmission of subsequent msgs. More...
int32_t | CANFD_writeDmaTriggerNext (CANFD_MsgObjHandle handle)
| Function used by the application to start transmission of next msg in dma mode. Transfer should be initiated using the API CANFD_writeDma before calling this function. This should be called after the previous transfer is completed and CANFD_dmaTxCompletionCallback is called. More...
uint32_t | CANFD_getFilterEventConfig (uint32_t eventNum)
int32_t | CANFD_read (CANFD_MsgObjHandle rxMsgHandle, uint32_t numMsgs, uint8_t *data)
| Function is used by the application to get the CAN message from message RAM using a receive message object. NOTE: This API must ONLY be called from the callback context. Function is used by the application to get the CAN message from message RAM using a receive message object. More...
int32_t | CANFD_readDmaConfig (CANFD_MsgObjHandle handle, const void *data, uint32_t numMsgs)
| Function is used by the application to configure reading the received msgs from message ram. This API will configure the DMA to copy msg from MCAN message ram to application buffer. For every message received the CANFD_dmaRxCompletionCallback will be called by driver by pointing to the latest msg in the data buffer. More...
int32_t | CANFD_getOptions (CANFD_Handle handle, const CANFD_OptionTLV *ptrOptInfo)
| Function is used by the application to get the error and status information from the driver. More...
int32_t | CANFD_setOptions (CANFD_Handle handle, const CANFD_OptionTLV *ptrOptInfo)
| Function is used by the application to configure the driver options. More...
void | CANFD_int0Isr (void *args)
| The function is the registered interrupt 0 ISR for the CANFD Driver. More...
void | CANFD_int1Isr (void *args)
| The function is the registered interrupt 1 ISR for the CANFD Driver. More...
void | CANFD_transferCallBack (void *args, CANFD_Reason reason)
| Application specified callback function which is invoked by the CANFD driver once transmit is complete or data has been received for the specified message object. More...
void | CANFD_errStatusCallBack (CANFD_Handle handle, CANFD_Reason reason, CANFD_ErrStatusResp *errStatusResp)
| Application specified callback function which is invoked by the CANFD driver on error or status change. More...
int32_t | CANFD_dmaOpen (CANFD_Handle canfdHandle, CANFD_DmaChConfig dmaChCfg)
| API to open an CANFD DMA channel. More...
int32_t | CANFD_dmaClose (CANFD_Handle canfdHandle)
| API to close an CANFD DMA channel. More...
int32_t | CANFD_createDmaTxMsgObject (const CANFD_Object *ptrCanFdObj, CANFD_MessageObject *ptrCanMsgObj)
| API to configure dma for the Tx message object. Called from the API CANFD_createMsgObject. More...
int32_t | CANFD_deleteDmaTxMsgObject (const CANFD_Object *ptrCanFdObj, const CANFD_MessageObject *ptrCanMsgObj)
| API to delete dma configuration for the Tx message object. Called from the API CANFD_deleteMsgObject. More...
int32_t | CANFD_configureDmaTx (const CANFD_Object *ptrCanFdObj, CANFD_MessageObject *ptrCanMsgObj, uint32_t dataLengthPerMsg, uint32_t numMsgs, const void *data)
| API to enable dma event transfer for the Tx. Called from the API CANFD_writeDma. More...
int32_t | CANFD_cancelDmaTx (const CANFD_Object *ptrCanFdObj, const CANFD_MessageObject *ptrCanMsgObj)
| API to disbale dma event transfer for the Tx to cancel the transfer. More...
void | CANFD_dmaTxCompletionCallback (CANFD_MessageObject *ptrCanMsgObj, const void *data, uint32_t completionType)
| Callback function for the Tx completion. This is called for each message in the array of msgs provided in CANFD_configureDmaTx. Data will point to the current transmitted message. For intermediate message transfer completion the completionType will be set to CANFD_DMA_TX_COMPLETION_INTERMEDIATE for last message transfer completion the completionType will be set to CANFD_DMA_TX_COMPLETION_FINAL. More...
int32_t | CANFD_createDmaRxMsgObject (const CANFD_Object *ptrCanFdObj, CANFD_MessageObject *ptrCanMsgObj)
| API to configure dma for the Rx message object. Called from the CANFD_createMsgObject. More...
int32_t | CANFD_deleteDmaRxMsgObject (const CANFD_Object *ptrCanFdObj, const CANFD_MessageObject *ptrCanMsgObj)
| API to delete dma configuration for the Rx message object. Called from the CANFD_deleteMsgObject. More...
int32_t | CANFD_configureDmaRx (const CANFD_Object *ptrCanFdObj, CANFD_MessageObject *ptrCanMsgObj, uint32_t dataLengthPerMsg, uint32_t numMsgs, const void *data)
| API to enable dma event transfer for the Rx. Called from the API CANFD_readDma. More...
void | CANFD_dmaRxCompletionCallback (CANFD_MessageObject *ptrCanMsgObj, const void *data, uint32_t completionType)
| Callback function for the Rx completion. This is called for each message in the array of msgs provided in CANFD_configureDmaRx. Data will point to the current received message. For intermediate message transfer completion the completionType will be set to CANFD_DMA_RX_COMPLETION_INTERMEDIATE for last message transfer completion the completionType will be set to CANFD_DMA_RX_COMPLETION_FINAL. More...
int32_t | CANFD_isDataSizeValid (uint32_t dataSize)
| Function to validate the data Size. More...
int32_t | CANFD_getEndianVal (CANFD_Handle canfdHandle)
| This function return endianness value of MCAN module. More...
void | CANFD_getRevisionId (CANFD_Handle canfdHandle)
| This API is used get the MCAN revision ID. More...
void | CANFD_addClockStopRequest (CANFD_Handle canfdHandle, uint32_t enable)
| This API add clock stop request for MCAN module to put it in power down mode. More...
uint32_t | CANFD_clockStopReq (CANFD_Handle canfdHandle)
| This API get clock stop acknowledgement for MCAN module. It return whether MCAN is power down mode or not. More...
uint32_t | CANFD_getClkStopAck (CANFD_Handle canfdHandle)
| This API will return clock stop acknowledgement for MCAN module. More...
uint32_t | CANFD_getRxPinState (CANFD_Handle canfdHandle)
| This API will return Rx pin state of MCAN module. More...
void | CANFD_setTxPinState (CANFD_Handle canfdHandle, uint32_t state)
| This API will set Tx pin state of MCAN module. More...
uint32_t | CANFD_getTxPinState (CANFD_Handle canfdHandle)
| This API will return Tx pin state of MCAN module. More...
void | CANFD_getBitTime (CANFD_Handle canfdHandle)
| This API will get the configured bit timings for MCAN module. More...
uint32_t | CANFD_getTSCounterVal (CANFD_Handle canfdHandle)
| This API will return current timestamp counter value. More...
void | CANFD_resetTSCounter (CANFD_Handle canfdHandle)
| This API will reset timestamp counter value. More...