Controller Area Network (CAN) Driver Interface.
The Controller Area Network (CAN) driver is a single instance driver that provides a simple interface to transmit and receive messages on a CAN bus. Messages are broadcast to the entire CAN network and each device is responsible for filtering and handling the received messages as necessary. The application is responsible for interpreting the received data.
To use the CAN driver to send and receive messages over the CAN bus, the application calls the following APIs:
The following code example initializes the CAN driver with the default configuration, transmits a CAN FD message, and waits to read any received messages.
More details on usage are provided in the following subsections.
CAN_init() must be called before any other CAN APIs. This function initializes common driver resources and calls the device-specific initialization function to configure the bit rate and message RAM.
After initializing the CAN driver by calling CAN_init(), the application can open a CAN instance by calling CAN_open(). This function takes an index into the CAN_config
[] array, and a CAN parameters data structure. The CAN instance is specified by the index of the CAN in CAN_config
[]. Calling CAN_open() a second time with the same index previously passed to CAN_open() will result in an error. You can, though, re-use the index if the instance is closed via CAN_close().
If no CAN_Params structure is passed to CAN_open(), default values are used. If the open call is successful, it returns a non-NULL value. The CAN driver APIs are non-blocking; there is no configurable return behavior.
Example initializing the CAN driver with a custom message RAM configuration to receive only filtered message IDs:
Example initializing the CAN driver with a specific raw bit rate timing:
The default message RAM configuration is as follows:
The number of default Tx and Rx buffers varies depending on the size of the device's message RAM. Check the doxygen for the device-specific CAN implementation to find the message RAM size. If using a custom message RAM configuration, utilize the entire space by maximizing the number of Rx/Tx buffers for optimal performance.
CAN_write() will return immediately after the message is loaded into the CAN controller's message RAM and pending transfer; it does not wait for the CAN message to be transmitted on the bus before returning. The CAN controller will automatically handle transmission retries in the event of a failure.
When a message is received in Rx FIFO0/1 or a dedicated Rx buffer, the CAN driver's IRQ handler automatically reads the Rx buffer element from the CAN controller's message RAM and stores it in a ring buffer whose size is configurable in SysConfig. When CAN_read() is called, the Rx buffer element is copied from the ring buffer to the application. If the ring buffer becomes full, any new messages received will be lost until the application frees space in the ring buffer by calling CAN_read().
#include <stdint.h>
#include <stddef.h>
#include <ti/drivers/utils/StructRingBuf.h>
#include <ti/devices/DeviceFamily.h>
#include <third_party/mcan/MCAN.h>
Go to the source code of this file.
Data Structures | |
struct | CAN_MsgRAMConfig |
CAN Message RAM configuration. More... | |
struct | CAN_DataBitRateTimingRaw |
Structure defining the raw MCAN CAN FD data phase bit rate configuration. More... | |
struct | CAN_BitRateTimingRaw |
Structure defining the raw MCAN bit rate configuration. More... | |
struct | CAN_Params |
CAN Parameters. More... | |
struct | CAN_Object |
CAN Object. More... | |
struct | CAN_HWAttrs |
CAN hardware attributes. More... | |
struct | CAN_Config_ |
CAN Global configuration. More... | |
Macros | |
#define | CAN_STATUS_SUCCESS ((int_fast16_t)0) |
Successful status code. More... | |
#define | CAN_STATUS_ERROR ((int_fast16_t)-1) |
Generic error status code. More... | |
#define | CAN_STATUS_NOT_SUPPORTED ((int_fast16_t)-2) |
Not supported status code. More... | |
#define | CAN_STATUS_TX_BUF_FULL ((int_fast16_t)-3) |
Tx buffer full status code. More... | |
#define | CAN_STATUS_NO_RX_MSG_AVAIL ((int_fast16_t)-4) |
No received message available status code. More... | |
#define | CAN_EVENT_SPI_XFER_ERROR (0x200U) |
A SPI transfer error occurred. More... | |
#define | CAN_EVENT_BIT_ERR_UNCORRECTED (0x100U) |
An uncorrected bit error occurred. More... | |
#define | CAN_EVENT_RX_RING_BUFFER_FULL (0x80U) |
The driver's Rx ring buffer was full. More... | |
#define | CAN_EVENT_RX_FIFO_MSG_LOST (0x40U) |
A message was lost for hardware Rx FIFO. More... | |
#define | CAN_EVENT_ERR_PASSIVE (0x20U) |
State change to error passive. More... | |
#define | CAN_EVENT_ERR_ACTIVE (0x10U) |
State change to error active. More... | |
#define | CAN_EVENT_BUS_OFF (0x08U) |
State change to bus off. More... | |
#define | CAN_EVENT_BUS_ON (0x04U) |
State change to bus on. More... | |
#define | CAN_EVENT_TX_FINISHED (0x02U) |
A CAN message transmission was completed. More... | |
#define | CAN_EVENT_RX_DATA_AVAIL (0x01U) |
Received CAN message data is available. More... | |
#define | CAN_DLC_0B ((uint32_t)0U) |
#define | CAN_DLC_1B ((uint32_t)1U) |
#define | CAN_DLC_2B ((uint32_t)2U) |
#define | CAN_DLC_3B ((uint32_t)3U) |
#define | CAN_DLC_4B ((uint32_t)4U) |
#define | CAN_DLC_5B ((uint32_t)5U) |
#define | CAN_DLC_6B ((uint32_t)6U) |
#define | CAN_DLC_7B ((uint32_t)7U) |
#define | CAN_DLC_8B ((uint32_t)8U) |
#define | CAN_DLC_12B ((uint32_t)9U) |
#define | CAN_DLC_16B ((uint32_t)10U) |
#define | CAN_DLC_20B ((uint32_t)11U) |
#define | CAN_DLC_24B ((uint32_t)12U) |
#define | CAN_DLC_32B ((uint32_t)13U) |
#define | CAN_DLC_48B ((uint32_t)14U) |
#define | CAN_DLC_64B ((uint32_t)15U) |
#define | CAN_FEC_DISABLE_FILTER 0U |
#define | CAN_FEC_STORE_RXFIFO0 1U |
#define | CAN_FEC_STORE_RXFIFO1 2U |
#define | CAN_FEC_REJECT_ID 3U |
#define | CAN_FEC_SET_PRIO 4U |
#define | CAN_FEC_SET_PRIO_STORE_RXFIFO0 5U |
#define | CAN_FEC_SET_PRIO_STORE_RXFIFO1 6U |
#define | CAN_FEC_STORE_RXBUF 7U |
#define | CAN_FILTER_RANGE 0U |
#define | CAN_FILTER_DUAL_ID 1U |
#define | CAN_FILTER_WITH_MASK 2U |
#define | CAN_FILTER_DISABLE 3U |
Typedefs | |
typedef MCAN_RxBufElement | CAN_RxBufElement |
A CAN Rx buffer element struct for CAN_read(). More... | |
typedef MCAN_TxBufElement | CAN_TxBufElement |
A CAN Tx buffer element struct for CAN_write() and CAN_writeBuffer(). More... | |
typedef struct CAN_Config_ * | CAN_Handle |
A handle that is returned from a CAN_open() call. More... | |
typedef void(* | CAN_EventCbk) (CAN_Handle handle, uint32_t event, uint32_t data, void *userArg) |
The definition of a callback function used by the CAN driver. More... | |
typedef struct CAN_Config_ | CAN_Config |
CAN Global configuration. More... | |
Functions | |
void | CAN_init (void) |
This function initializes the CAN module. More... | |
void | CAN_Params_init (CAN_Params *params) |
Initializes the CAN_Params struct to its default values. More... | |
CAN_Handle | CAN_open (uint_least8_t index, CAN_Params *params) |
Initializes a CAN driver instance and returns a handle. More... | |
void | CAN_close (CAN_Handle handle) |
Closes a CAN peripheral specified by handle. More... | |
int_fast16_t | CAN_read (CAN_Handle handle, CAN_RxBufElement *elem) |
Reads a received CAN message. More... | |
int_fast16_t | CAN_write (CAN_Handle handle, const CAN_TxBufElement *elem) |
Sends CAN message using the Tx FIFO/Queue. More... | |
int_fast16_t | CAN_writeBuffer (CAN_Handle handle, uint32_t bufIdx, const CAN_TxBufElement *elem) |
Sends CAN message using a dedicated Tx Buffer. More... | |
int_fast16_t | CAN_enableLoopbackExt (CAN_Handle handle) |
Enables external loopback test mode. More... | |
int_fast16_t | CAN_enableLoopbackInt (CAN_Handle handle) |
Enables internal loopback test mode. More... | |
int_fast16_t | CAN_disableLoopback (CAN_Handle handle) |
Disables loopback test mode. More... | |
Variables | |
const CAN_Config | CAN_config [] |
const uint_least8_t | CAN_count |
#define CAN_DLC_0B ((uint32_t)0U) |
#define CAN_DLC_1B ((uint32_t)1U) |
#define CAN_DLC_2B ((uint32_t)2U) |
#define CAN_DLC_3B ((uint32_t)3U) |
#define CAN_DLC_4B ((uint32_t)4U) |
#define CAN_DLC_5B ((uint32_t)5U) |
#define CAN_DLC_6B ((uint32_t)6U) |
#define CAN_DLC_7B ((uint32_t)7U) |
#define CAN_DLC_8B ((uint32_t)8U) |
#define CAN_DLC_12B ((uint32_t)9U) |
Equivalent to CAN_DLC_8B for classic CAN
#define CAN_DLC_16B ((uint32_t)10U) |
Equivalent to CAN_DLC_8B for classic CAN
#define CAN_DLC_20B ((uint32_t)11U) |
Equivalent to CAN_DLC_8B for classic CAN
#define CAN_DLC_24B ((uint32_t)12U) |
Equivalent to CAN_DLC_8B for classic CAN
#define CAN_DLC_32B ((uint32_t)13U) |
Equivalent to CAN_DLC_8B for classic CAN
#define CAN_DLC_48B ((uint32_t)14U) |
Equivalent to CAN_DLC_8B for classic CAN
#define CAN_DLC_64B ((uint32_t)15U) |
Equivalent to CAN_DLC_8B for classic CAN
#define CAN_FEC_DISABLE_FILTER 0U |
#define CAN_FEC_STORE_RXFIFO0 1U |
#define CAN_FEC_STORE_RXFIFO1 2U |
#define CAN_FEC_REJECT_ID 3U |
#define CAN_FEC_SET_PRIO 4U |
#define CAN_FEC_SET_PRIO_STORE_RXFIFO0 5U |
#define CAN_FEC_SET_PRIO_STORE_RXFIFO1 6U |
#define CAN_FEC_STORE_RXBUF 7U |
#define CAN_FILTER_RANGE 0U |
#define CAN_FILTER_DUAL_ID 1U |
#define CAN_FILTER_WITH_MASK 2U |
#define CAN_FILTER_DISABLE 3U |
typedef MCAN_RxBufElement CAN_RxBufElement |
A CAN Rx buffer element struct for CAN_read().
typedef MCAN_TxBufElement CAN_TxBufElement |
A CAN Tx buffer element struct for CAN_write() and CAN_writeBuffer().
typedef struct CAN_Config_* CAN_Handle |
A handle that is returned from a CAN_open() call.
typedef void(* CAN_EventCbk) (CAN_Handle handle, uint32_t event, uint32_t data, void *userArg) |
The definition of a callback function used by the CAN driver.
[in] | handle | A CAN_Handle returned from CAN_open |
[in] | event | CAN_EVENT that has occurred. |
[in] | data | Data is event dependent:
|
[in] | userArg | A user supplied argument specified in CAN_Params. |
typedef struct CAN_Config_ CAN_Config |
CAN Global configuration.
The CAN_Config structure contains a set of pointers used to characterize the CAN driver implementation.
void CAN_init | ( | void | ) |
This function initializes the CAN module.
void CAN_Params_init | ( | CAN_Params * | params | ) |
Initializes the CAN_Params struct to its default values.
params | An pointer to CAN_Params structure for initialization |
Defaults values are: .msgRAMConfig = NULL .bitTiming = NULL .eventCbk = NULL .eventMask = 0U .userArg = NULL
CAN_Handle CAN_open | ( | uint_least8_t | index, |
CAN_Params * | params | ||
) |
Initializes a CAN driver instance and returns a handle.
Initializes a CAN driver instance, configures the CAN device in normal operational mode, and returns a handle. Since the MCAN IP is highly configurable, the message RAM configuration and raw bit timings may be provided in the parameter block. Raw bit timings are required to use transmitter delay compensation. Invalid message RAM configuration or bit timing parameters will cause this function to fail.
index | Logical peripheral number for the CAN indexed into the CAN_config table |
params | Pointer to a parameter block, if NULL it will use default values. |
void CAN_close | ( | CAN_Handle | handle | ) |
Closes a CAN peripheral specified by handle.
handle | A CAN_Handle returned from CAN_open |
int_fast16_t CAN_read | ( | CAN_Handle | handle, |
CAN_RxBufElement * | elem | ||
) |
Reads a received CAN message.
handle | A CAN_Handle returned from CAN_open |
elem | A pointer to a CAN_RxBufElement. |
CAN_STATUS_SUCCESS | if successful. |
CAN_STATUS_NO_RX_MSG_AVAIL | if no messages are available. |
int_fast16_t CAN_write | ( | CAN_Handle | handle, |
const CAN_TxBufElement * | elem | ||
) |
Sends CAN message using the Tx FIFO/Queue.
handle | A CAN_Handle returned from CAN_open |
elem | A pointer to a CAN_TxBufElement. |
CAN_STATUS_SUCCESS | if successful. |
CAN_STATUS_ERROR | if no Tx FIFO/Queue is configured. |
CAN_STATUS_TX_BUF_FULL | if the Tx buffer is full. |
int_fast16_t CAN_writeBuffer | ( | CAN_Handle | handle, |
uint32_t | bufIdx, | ||
const CAN_TxBufElement * | elem | ||
) |
Sends CAN message using a dedicated Tx Buffer.
Dedicated Tx buffers are intended for message transmission under complete control of the application. A custom message RAM config with dedicated Tx buffer(s) must be provided during CAN_init in order to utilize this function.
handle | A CAN_Handle returned from CAN_open |
bufIdx | Index of the dedicated Tx buffer. |
elem | A pointer to a CAN_TxBufElement. |
CAN_STATUS_SUCCESS | if successful. |
CAN_STATUS_ERROR | if the Tx buffer index is invalid or the buffer already has a Tx request pending. |
int_fast16_t CAN_enableLoopbackExt | ( | CAN_Handle | handle | ) |
Enables external loopback test mode.
handle | A CAN_Handle returned from CAN_open |
CAN_STATUS_SUCCESS | if successful. |
CAN_STATUS_NOT_SUPPORTED | if this feature is not supported. |
int_fast16_t CAN_enableLoopbackInt | ( | CAN_Handle | handle | ) |
Enables internal loopback test mode.
handle | A CAN_Handle returned from CAN_open |
CAN_STATUS_SUCCESS | if successful. |
CAN_STATUS_NOT_SUPPORTED | if this feature is not supported. |
int_fast16_t CAN_disableLoopback | ( | CAN_Handle | handle | ) |
Disables loopback test mode.
handle | A CAN_Handle returned from CAN_open |
CAN_STATUS_SUCCESS | if successful. |
CAN_STATUS_NOT_SUPPORTED | if this feature is not supported. |
const CAN_Config CAN_config[] |
const uint_least8_t CAN_count |