Controller Area Network - Peripheral Abstraction Layer (CAN PAL)

Detailed Description

The S32 SDK provides a Peripheral Abstraction Layer for Controller Area Network (CAN) modules of S32 SDK devices.

The CAN PAL driver allows communication over a CAN bus. It was designed to be portable across all platforms and IPs which support CAN communication.

How to integrate CAN PAL in your application

Unlike the other drivers, CAN PAL modules need to include a configuration file named can_pal_cfg.h, which allows the user to specify which IPSs are used and how many resources are allocated for each of them (state structures). The following code example shows how to configure one instance for each available CAN IP.

#ifndef can_pal_cfg_H
#define can_pal_cfg_H
/* Define which IP instance will be used in current project */
#define CAN_OVER_FLEXCAN
/* Define the resources necessary for current project */
#define NO_OF_FLEXCAN_INSTS_FOR_CAN 1U
#endif /* can_pal_cfg_H */

The following table contains the matching between platforms and available IPs

IP/MCU S32K116S32K142S32K144S32K146S32K148S32V234MPC5748GMPC5746CMPC5744P
FlexCAN YES YES YES YES YES YES YES YES YES

Features

Initialization

In order to use the CAN PAL driver it must be first initialized, using CAN_Init() function. Once initialized, it cannot be initialized again for the same CAN module instance until it is de-initialized, using CAN_Deinit(). Different CAN modules instances can function independently of each other.

The can_user_config_t structure allows you to configure the following:

The bitrate is represented by a can_time_segment_t structure, with the following fields:

In order to use a buffer for transmission/reception, it has to be initialized using either CAN_ConfigRxBuff or CAN_ConfigTxBuff.

After having the buffer configured, you can start sending/receiving data by calling one of the following functions:

FlexCAN Rx FIFO extension

When used over FlexCAN, the PAL allows extending the basic configuration with an Rx FIFO feature. The Rx FIFO is receive-only and 6-message deep. The application can read the received messages sequentially, in the order they were received, by repeatedly reading the data from buffer 0 (zero). A powerful filtering scheme is provided to accept only frames intended for the target application. The FIFO and filtering criteria are configured by passing a structure of extension_flexcan_rx_fifo_t type, through the extension field of the user configuration structure.

/* ID Filter table */
flexcan_id_table_t filterTable[] = {
{
.isExtendedFrame = false,
.isRemoteFrame = false,
.id = 1U
},
...
};
/* Rx FIFO extension */
extension_flexcan_rx_fifo_t can_pal1_rx_fifo_ext0 = {
/* User must pass reference to the ID filter table. */
.idFilterTable = NULL
};
can_pal1_rx_fifo_ext0.idFilterTable = filterTable;

The number of elements in the ID filter table is defined by the following formula:

Each element in the ID filter table specifies an ID to be used as acceptance criteria for the FIFO as follows:

When Rx FIFO feature is enabled, buffer 0 (zero) cannot be used for transmission or reconfigured for reception using CAN_ConfigRxBuff() and CAN_SetRxFilter() functions.

Important Notes

Example code

#define TX_BUFF_IDX 0U
#define RX_BUFF_IDX 1U
uint32_t msgID = 0xAB;
/* CAN PAL instance information */
const can_instance_t can_pal1_instance = {CAN_INST_TYPE_FLEXCAN, 0U};
/* User configuration structure */
can_user_config_t config = {
.maxBuffNum = 2U,
.peClkSrc = CAN_CLK_SOURCE_OSC,
.enableFD = false,
.payloadSize = CAN_PAYLOAD_SIZE_8,
.nominalBitrate = {
.propSeg = 7,
.phaseSeg1 = 4,
.phaseSeg2 = 1,
.preDivider = 0,
.rJumpwidth = 1
},
.dataBitrate = {
.propSeg = 7,
.phaseSeg1 = 4,
.phaseSeg2 = 1,
.preDivider = 0,
.rJumpwidth = 1
},
.extension = NULL
};
/* Initialize CAN */
CAN_Init(&can_pal1_instance, &config);
/* Buffer configuration */
can_buff_config_t buffConfig = {
.enableFD = false,
.enableBRS = false,
.fdPadding = 0xCC,
.idType = CAN_MSG_ID_STD,
.isRemote = false
};
CAN_ConfigTxBuff(&can_pal1_instance, TX_BUFF_IDX, &buffConfig);
CAN_ConfigRxBuff(&can_pal1_instance, RX_BUFF_IDX, &buffConfig, msgID);
can_message_t recvMsg, sendMsg = {
.id = msgID,
.length = 5U,
.data = {"Hello"}
};
/* Send data using buffer configured for transmission */
CAN_Send(&can_pal1_instance, TX_BUFF_IDX, &sendMsg);
while(CAN_GetTransferStatus(&can_pal1_instance, TX_BUFF_IDX) == STATUS_BUSY);
/* Receive data using buffer configured for reception */
CAN_Receive(&can_pal1_instance, RX_BUFF_IDX, &recvMsg);
while(CAN_GetTransferStatus(&can_pal1_instance, RX_BUFF_IDX) == STATUS_BUSY);
/* De-initialize CAN */
CAN_Deinit(&can_pal1_instance);

Data Structures

struct  can_time_segment_t
 CAN bit timing variables Implements : can_time_segment_t_Class. More...
 
struct  can_buff_config_t
 CAN buffer configuration Implements : can_buff_config_t_Class. More...
 
struct  can_message_t
 CAN message format Implements : can_message_t_Class. More...
 
struct  can_user_config_t
 CAN controller configuration Implements : can_user_config_t_Class. More...
 

Enumerations

enum  can_operation_modes_t { CAN_NORMAL_MODE = 0U, CAN_LOOPBACK_MODE = 2U, CAN_DISABLE_MODE = 4U }
 CAN controller operation modes Implements : can_operation_modes_t_Class. More...
 
enum  can_fd_payload_size_t { CAN_PAYLOAD_SIZE_8 = 0, CAN_PAYLOAD_SIZE_16, CAN_PAYLOAD_SIZE_32, CAN_PAYLOAD_SIZE_64 }
 CAN buffer payload sizes Implements : can_fd_payload_size_t_Class. More...
 
enum  can_bitrate_phase_t { CAN_NOMINAL_BITRATE, CAN_FD_DATA_BITRATE }
 CAN bitrate phase (nominal/data) Implements : can_bitrate_phase_t_Class. More...
 
enum  can_msg_id_type_t { CAN_MSG_ID_STD, CAN_MSG_ID_EXT }
 CAN Message Buffer ID type Implements : can_msg_id_type_t_Class. More...
 
enum  can_clk_source_t { CAN_CLK_SOURCE_OSC = 0U, CAN_CLK_SOURCE_PERIPH = 1U }
 CAN PE clock sources Implements : can_clk_source_t_Class. More...
 

Functions

status_t CAN_Init (const can_instance_t *const instance, const can_user_config_t *config)
 Initializes the CAN module. More...
 
status_t CAN_Deinit (const can_instance_t *const instance)
 De-initializes the CAN module. More...
 
status_t CAN_SetBitrate (const can_instance_t *const instance, can_bitrate_phase_t phase, const can_time_segment_t *bitTiming)
 Configures the CAN bitrate. More...
 
status_t CAN_GetBitrate (const can_instance_t *const instance, can_bitrate_phase_t phase, can_time_segment_t *bitTiming)
 Returns the CAN bitrate. More...
 
status_t CAN_ConfigTxBuff (const can_instance_t *const instance, uint32_t buffIdx, const can_buff_config_t *config)
 Configures a buffer for transmission. More...
 
status_t CAN_ConfigRemoteResponseBuff (const can_instance_t *const instance, uint32_t buffIdx, const can_buff_config_t *config, const can_message_t *message)
 Configures a transmit buffer for remote frame response. More...
 
status_t CAN_ConfigRxBuff (const can_instance_t *const instance, uint32_t buffIdx, const can_buff_config_t *config, uint32_t acceptedId)
 Configures a buffer for reception. More...
 
status_t CAN_Send (const can_instance_t *const instance, uint32_t buffIdx, const can_message_t *message)
 Sends a CAN frame using the specified buffer. More...
 
status_t CAN_SendBlocking (const can_instance_t *const instance, uint32_t buffIdx, const can_message_t *message, uint32_t timeoutMs)
 Sends a CAN frame using the specified buffer, in a blocking manner. More...
 
status_t CAN_Receive (const can_instance_t *const instance, uint32_t buffIdx, can_message_t *message)
 Receives a CAN frame using the specified message buffer. More...
 
status_t CAN_ReceiveBlocking (const can_instance_t *const instance, uint32_t buffIdx, can_message_t *message, uint32_t timeoutMs)
 Receives a CAN frame using the specified buffer, in a blocking manner. More...
 
status_t CAN_AbortTransfer (const can_instance_t *const instance, uint32_t buffIdx)
 Ends a non-blocking CAN transfer early. More...
 
status_t CAN_SetRxFilter (const can_instance_t *const instance, can_msg_id_type_t idType, uint32_t buffIdx, uint32_t mask)
 Configures an ID filter for a specific reception buffer. More...
 
status_t CAN_GetTransferStatus (const can_instance_t *const instance, uint32_t buffIdx)
 Returns the state of the previous CAN transfer. More...
 
status_t CAN_InstallEventCallback (const can_instance_t *const instance, can_callback_t callback, void *callbackParam)
 Installs a callback function for the IRQ handler. More...
 

Enumeration Type Documentation

CAN bitrate phase (nominal/data) Implements : can_bitrate_phase_t_Class.

Enumerator
CAN_NOMINAL_BITRATE 

Nominal (FD arbitration) bitrate

CAN_FD_DATA_BITRATE 

FD data bitrate

Definition at line 73 of file can_pal.h.

CAN PE clock sources Implements : can_clk_source_t_Class.

Enumerator
CAN_CLK_SOURCE_OSC 

The CAN engine clock source is the oscillator clock.

CAN_CLK_SOURCE_PERIPH 

The CAN engine clock source is the peripheral clock.

Definition at line 89 of file can_pal.h.

CAN buffer payload sizes Implements : can_fd_payload_size_t_Class.

Enumerator
CAN_PAYLOAD_SIZE_8 

CAN message buffer payload size in bytes

CAN_PAYLOAD_SIZE_16 

CAN message buffer payload size in bytes

CAN_PAYLOAD_SIZE_32 

CAN message buffer payload size in bytes

CAN_PAYLOAD_SIZE_64 

CAN message buffer payload size in bytes

Definition at line 52 of file can_pal.h.

CAN Message Buffer ID type Implements : can_msg_id_type_t_Class.

Enumerator
CAN_MSG_ID_STD 

Standard ID

CAN_MSG_ID_EXT 

Extended ID

Definition at line 81 of file can_pal.h.

CAN controller operation modes Implements : can_operation_modes_t_Class.

Enumerator
CAN_NORMAL_MODE 

Normal mode or user mode

CAN_LOOPBACK_MODE 

Loop-back mode

CAN_DISABLE_MODE 

Module disable mode

Definition at line 43 of file can_pal.h.

Function Documentation

status_t CAN_AbortTransfer ( const can_instance_t *const  instance,
uint32_t  buffIdx 
)

Ends a non-blocking CAN transfer early.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
Returns
STATUS_SUCCESS if successful; STATUS_CAN_NO_TRANSFER_IN_PROGRESS if no transfer was running

Definition at line 885 of file can_pal.c.

status_t CAN_ConfigRemoteResponseBuff ( const can_instance_t *const  instance,
uint32_t  buffIdx,
const can_buff_config_t config,
const can_message_t message 
)

Configures a transmit buffer for remote frame response.

Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
[in]configbuffer configuration.
[in]messageframe to be sent as remote response.
Returns
STATUS_SUCCESS if successful; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 535 of file can_pal.c.

status_t CAN_ConfigRxBuff ( const can_instance_t *const  instance,
uint32_t  buffIdx,
const can_buff_config_t config,
uint32_t  acceptedId 
)

Configures a buffer for reception.

This function configures a buffer for reception.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver. The user should not reconfigure this buffer for classical buffer reception.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
[in]configbuffer configuration.
[in]acceptedIdID used for accepting frames.
Returns
STATUS_SUCCESS if successful; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 598 of file can_pal.c.

status_t CAN_ConfigTxBuff ( const can_instance_t *const  instance,
uint32_t  buffIdx,
const can_buff_config_t config 
)

Configures a buffer for transmission.

This function configures a buffer for transmission.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver. The user should not reconfigure this buffer for transmission.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
[in]configbuffer configuration.
Returns
STATUS_SUCCESS if successful; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 472 of file can_pal.c.

status_t CAN_Deinit ( const can_instance_t *const  instance)

De-initializes the CAN module.

This function de-initializes the CAN module.

Parameters
[in]instanceInstance information structure
Returns
STATUS_SUCCESS if successful; STATUS_ERROR if unsuccessful or invalid instance number;

Definition at line 358 of file can_pal.c.

status_t CAN_GetBitrate ( const can_instance_t *const  instance,
can_bitrate_phase_t  phase,
can_time_segment_t bitTiming 
)

Returns the CAN bitrate.

This function returns the CAN configured bitrate.

Parameters
[in]instanceInstance information structure.
[in]phaseselects between nominal/data phase bitrate.
[out]bitTimingconfigured bit timing variables.
Returns
STATUS_SUCCESS if successful; STATUS_ERROR if invalid instance number is used;

Definition at line 432 of file can_pal.c.

status_t CAN_GetTransferStatus ( const can_instance_t *const  instance,
uint32_t  buffIdx 
)

Returns the state of the previous CAN transfer.

When performing an async transfer, call this function to ascertain the state of the current transfer: in progress or complete.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
Returns
STATUS_SUCCESS if successful; STATUS_BUSY if a resource is busy; STATUS_ERROR if invalid instance number is used;

Definition at line 967 of file can_pal.c.

status_t CAN_Init ( const can_instance_t *const  instance,
const can_user_config_t config 
)

Initializes the CAN module.

This function initializes and enables the requested CAN module.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver.
Parameters
[in]instanceInstance information structure
[in]configThe configuration structure
Returns
STATUS_SUCCESS if successful; STATUS_ERROR if unsuccessful or invalid instance number;

Definition at line 251 of file can_pal.c.

status_t CAN_InstallEventCallback ( const can_instance_t *const  instance,
can_callback_t  callback,
void *  callbackParam 
)

Installs a callback function for the IRQ handler.

Parameters
[in]instanceInstance information structure.
[in]callbackThe callback function.
[in]callbackParamUser parameter passed to the callback function through the state parameter.
Returns
STATUS_SUCCESS if successful; STATUS_ERROR if invalid instance number is used;

Definition at line 1006 of file can_pal.c.

status_t CAN_Receive ( const can_instance_t *const  instance,
uint32_t  buffIdx,
can_message_t message 
)

Receives a CAN frame using the specified message buffer.

This function receives a CAN frame using a configured buffer. The function returns immediately. If a callback is installed, it will be invoked after the frame was received and read into the specified buffer.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver. The user should use this buffer to receive frames in the FIFO.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
[out]messagereceived message.
Returns
STATUS_SUCCESS if successful; STATUS_BUSY if the current buffer is involved in another transfer; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 779 of file can_pal.c.

status_t CAN_ReceiveBlocking ( const can_instance_t *const  instance,
uint32_t  buffIdx,
can_message_t message,
uint32_t  timeoutMs 
)

Receives a CAN frame using the specified buffer, in a blocking manner.

This function receives a CAN frame using a configured buffer. The function blocks until either a frame was received, or the specified timeout expired.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver. The user should use this buffer to receive frames in the FIFO.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
[out]messagereceived message.
[in]timeoutMsA timeout for the transfer in milliseconds.
Returns
STATUS_SUCCESS if successful; STATUS_BUSY if the current buffer is involved in another transfer; STATUS_TIMEOUT if the timeout is reached; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 831 of file can_pal.c.

status_t CAN_Send ( const can_instance_t *const  instance,
uint32_t  buffIdx,
const can_message_t message 
)

Sends a CAN frame using the specified buffer.

This function sends a CAN frame using a configured buffer. The function returns immediately. If a callback is installed, it will be invoked after the frame was sent.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver. The user should not use this buffer for transmission.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
[in]messagemessage to be sent.
Returns
STATUS_SUCCESS if successful; STATUS_BUSY if the current buffer is involved in another transfer; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 660 of file can_pal.c.

status_t CAN_SendBlocking ( const can_instance_t *const  instance,
uint32_t  buffIdx,
const can_message_t message,
uint32_t  timeoutMs 
)

Sends a CAN frame using the specified buffer, in a blocking manner.

This function sends a CAN frame using a configured buffer. The function blocks until either the frame was sent, or the specified timeoutMs expired.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver. The user should not use this buffer for transmission.
Parameters
[in]instanceInstance information structure.
[in]buffIdxbuffer index.
[in]messagemessage to be sent.
[in]timeoutMsA timeout for the transfer in milliseconds.
Returns
STATUS_SUCCESS if successful; STATUS_BUSY if the current buffer is involved in another transfer; STATUS_TIMEOUT if the timeout is reached; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 719 of file can_pal.c.

status_t CAN_SetBitrate ( const can_instance_t *const  instance,
can_bitrate_phase_t  phase,
const can_time_segment_t bitTiming 
)

Configures the CAN bitrate.

This function configures the CAN bit timing variables.

Parameters
[in]instanceInstance information structure.
[in]phaseselects between nominal/data phase bitrate.
[in]bitTimingbit timing variables.
Returns
STATUS_SUCCESS if successful; STATUS_ERROR if invalid instance number is used;

Definition at line 392 of file can_pal.c.

status_t CAN_SetRxFilter ( const can_instance_t *const  instance,
can_msg_id_type_t  idType,
uint32_t  buffIdx,
uint32_t  mask 
)

Configures an ID filter for a specific reception buffer.

This function configures an ID filter for each reception buffer.

Note
When the Rx FIFO extension is used, buffer 0 (zero) is used to read the contents of the FIFO and is configured at the initialization of the driver. The user should not reconfigure the Rx filter for this buffer.
Parameters
[in]instanceInstance information structure.
[in]idTypeselects between standard and extended ID.
[in]buffIdxbuffer index.
[in]maskmask value for ID filtering.
Returns
STATUS_SUCCESS if successful; STATUS_CAN_BUFF_OUT_OF_RANGE if the buffer index is out of range; STATUS_ERROR if invalid instance number is used;

Definition at line 924 of file can_pal.c.