CAN Interface

CAN Platform interface

CAN Overview

The Controller Area Network (CAN) interface serves as a foundational abstraction for communication between electronic control units (ECUs) or nodes in embedded systems. It provides a standardized protocol that facilitates reliable, real-time data exchange in distributed systems, making it a cornerstone of automotive and industrial communication.

A CAN interface acts as a communication endpoint on a shared bus, enabling multiple devices to transmit and receive data efficiently. It supports robust communication by integrating priority-based arbitration, error detection, and fault confinement mechanisms, ensuring data integrity even in harsh environments

CAN Types

CAN : Represents standard CAN operation, supporting up to 1 Mbps with a maximum payload of 8 bytes.
CAN_FD : Represents CAN-FD (Flexible Data Rate) operation, supporting higher data rates (up to 8 Mbps) and payloads up to 64 bytes.

Supported Communication Modes

The following modes of CAN communication are supported:

Blocking - Here the read/write function waits(blocked) till the operation is performed or time out.
Non-Blocking - The read/write function returns immediately with appropriate return values.

The HAL will support different modes of operations such as Idle, Init, Normal, Sleep, Test etc.

Application Interface

The below table captures the functions that are to be called from the application layer.

API Functions
Function	Description
rs_can_open	To open the CAN interface.
rs_can_set_config	To configure the CAN interface.
rs_can_configure_rx_filters	To configure the CAN rx filters
rs_can_set_tx_buffers	To set up the transmit buffers to the CAN interface to be used for the CAN stack
rs_can_set_rx_buffers	To set up the receive buffers to the CAN to be used for the CAN stack
rs_can_set_mode	To set up the operation mode for the CAN stack
rs_can_transmit	To transmit the CAN frame data to the CAN interface
rs_can_put_transmit_buf	To release the transmit buffer of CAN.
rs_can_register_callback	To registers the given callback function for CAN operation
rs_can_close	To close the CAN interface.

Error Code

Every API’s for the CAN returns some success or failure values. Please refer below section,

RAPIDSEA ERROR CODES

Implementation Guide

This section explains how to implement the CAN interface using the RAPIDSEA stack, the steps to be followed are

Configure the preferred method of RX or TX communication(Blocking / Non-Blocking).
Configure the CAN interface.
Then call the open call of the CAN interface.
Perform the transmit and receive operations as required and handle the error codes.
Close the CAN interface.

Documentation from the relevant header as follows:

Defines

RS_CAN_TYPE_CAN

CAN TYpe.

CAN operation

RS_CAN_TYPE_CAN_FD: CAN-FD operation.

RS_CAN_BLOCKING

Blocking mode.

Blocking Mode operation

RS_CAN_NON_BLOCKING: Non-Blocking Mode operation.

RS_CAN_OP_MODE_STOP

Operation mode.

In stopped state, not functioning

RS_CAN_OP_MODE_INIT: In initialization state.

RS_CAN_OP_MODE_NORMAL: In normal operating state.

RS_CAN_OP_MODE_SLEEP: In sleep mode, ready to be woken up.

RS_CAN_OP_MODE_TEST: In test mode, for loopback testing etc.

RS_CAN_BUFFER_APP_MANAGED

CAN Buffer management.

Single transmission/reception managed by application

RS_CAN_BUFFER_MODULE_MANAGED_RING: Multiple transmission/reception buffer ring managed by CAN module.

RS_CAN_CALLBACK_ON_TRANSMIT

CAN Callback reasons.

On successful transmission

RS_CAN_CALLBACK_ON_RECEIVE: On successful reception.

RS_CAN_CALLBACK_ON_RX_OVERRUN: On receive overrun.

RS_CAN_CALLBACK_ON_TRANSMIT_TIMEOUT: On transmit timeout.

RS_CAN_CALLBACK_ON_TRANSMIT_COMPLETE: On transmit complete.

RS_CAN_CALLBACK_ON_TRANSMIT_ERROR: On transmit error.

RS_CAN_CALLBACK_ON_RX_FIFO_NOT_EMPTY: On data availability in Rx FIFO

RS_CAN_CALLBACK_ON_RX_FIFO_FULL: On Rx FIFO being full

RS_CAN_CALLBACK_ON_ERROR: On Other errors

RS_CAN_MAX_NUM_CALLBACKS: Max num of callbacks.

RS_CAN_DATA_STATUS_FREE: CAN Data is not used.

RS_CAN_DATA_STATUS_IN_USE: CAN Data is in use.

RS_CAN_RX_FILTER_ENABLE_EXTENDED_ID

CAN RX Filters.

Enable extended ID

RS_CAN_RX_FILTER_REMOTE_FRAME: Remote frame.

RS_CAN_RX_FILTER_RECEIVE_OWN_FRAME: Recieve own frame.

RS_CAN_RX_FILTER_MASK_EXTENDED_ID: MAsk extended ID.

RS_CAN_RX_FILTER_MASK_REMOTE_FRAME: Mask remote frame.

RS_CAN_RX_FILTER_ENABLED: Enable filter.

RS_CAN_RX_FILTER_DLC_CHECK_DISABLED: Disable DLC check filter.

RS_CAN_RX_FILTER_MODE_RANGE: Range filter from value id to mask.

RS_CAN_RX_FILTER_MODE_DUAL: Dual ID filter for value id or mask.

RS_CAN_RX_FILTER_MODE_CLASSIC: Classic filter: value id = filter, mask = mask.

RS_CAN_BIT_ERR: To indicate CAN bit error.

RS_CAN_ACK_ERR: To indicate CAN acknowledge error.

RS_CAN_STUFF_ERR: To indicate CAN stuff error.

RS_CAN_FORM_ERR: To indicate CAN form error.

RS_CAN_BUS_ERR: To indicate CAN bus error.

RS_CAN_CRC_ERR: To indicate CAN crc error.

RS_ENABLE_BIT_TIMING: Enable bit mangling.

RS_CAN_RX_SW_FILTER_ACCEPT

RS_CAN_RX_SW_FILTER_REJECT

Typedefs

typedef struct tag_rs_can_data rs_can_data_t: Structure for configuring the CAN interface.

typedef struct tag_rs_can_data_ptr_with_ts rs_can_data_ptr_with_ts_t

typedef struct tag_rs_can_buf_config rs_can_buf_config_t: Structure for CAN buffer config.

typedef struct tag_rs_can_rx_filter rs_can_rx_filter_t: Structure for configuring Receive Filter.

typedef struct tag_rs_can_config rs_can_config_t: Structure for configuring the CAN interface.

typedef struct tag_rs_can_instance rs_can_instance_t: Structure for the CAN instance.

typedef void (*rs_can_callback)(void *ptr_arg, rs_ret_val_t reason, rs_can_data_t *ptr_rx_data)

Callback function format.

This callback function is called on completion of given activity

Param handle:: [in] - Handle to the CAN interface
Param reason:: [in] - Result of the last operation requested in non-blocking mode
Param ptr_rx_data:: [in] - Pointer to receive buffer on reception or NULL
Return:: None

Functions

rs_ret_val_t rs_can_set_config(rs_can_config_t *ptr_can_config, uint8_t u8_channel, uint8_t u8_non_blocking, uint32_t u32_baudrate, uint32_t u32_data_baudrate)

rs_handle_t rs_can_open(rs_can_instance_t *ptr_can_instance, rs_can_config_t *ptr_config)

rs_ret_val_t rs_can_set_tx_buffers(rs_handle_t handle, rs_can_data_t *ptr_tx_buffers, uint32_t u32_num_tx_buffers)

Set CAN transmit buffers and configure to the can configure.

This function configuration the CAN transmit buffers

Parameters:

handle – [in] - Handle to the CAN interface
ptr_tx_buffers – [in] - Pointer to the transmit buffers
u32_num_tx_buffers – [in] - number of transmit buffers

Returns:

0 on success or error code on failure

rs_ret_val_t rs_can_set_rx_buffers(rs_handle_t handle, rs_can_data_t *ptr_rx_buffers, uint32_t u32_num_rx_buffers)

Set CAN Receive buffers and configure to the can configure.

This function configuration the CAN receive buffers

Parameters:

handle – [in] - Handle to the CAN interface
ptr_tx_buffers – [in] - Pointer to the receive buffers
u32_num_tx_buffers – [in] - number of receive buffers

Returns:

0 on success or error code on failure

rs_ret_val_t rs_can_configure_rx_filters(rs_handle_t handle, rs_can_rx_filter_t *ptr_filters, uint32_t u32_num_filters)

Configure the receive filter in CAN configure.

This function configuration the CAN receive filter

Parameters:

handle – [in] - Handle to the CAN interface
ptr_filters – [in] - Pointer to the receive filter.
u32_num_tx_buffers – [in] - number of receive filter.

Returns:

0 on success or error code on failure

rs_ret_val_t rs_can_set_mode(rs_handle_t handle, uint8_t u8_op_mode)

Set CAN operate mode.

This function Set CAN operate mode.

Parameters:: u8_op_mode – [in] - CAN operation mode.
Returns:: 0 on success or error code on failure

rs_ret_val_t rs_can_transmit(rs_handle_t handle, void *ptr_tx_data)

rs_ret_val_t rs_can_register_callback(rs_handle_t handle, rs_can_callback ptr_func, void *ptr_arg)

rs_ret_val_t rs_can_put_transmit_buf(rs_handle_t handle, rs_can_data_t *ptr_tx_data)

Puts data into the CAN transmit buffer.

This function places the provided CAN data into the transmit buffer.

Parameters:

handle – [in] - Handle to the CAN interface
ptr_rx_data – [in] - Pointer to transmit buffer on reception or NULL

Returns:

0 on success or error code on failure

rs_can_data_t *rs_can_get_transmit_buf(rs_handle_t handle)

Retrieves the CAN transmit buffer.

This function returns a pointer to the CAN transmit buffer

Parameters:: handle – [in] - Handle to the CAN interface
Returns:: rs_can_data_t structure pointer on success or NULL on failure

rs_ret_val_t rs_can_rx_sw_filter(rs_handle_t handle, uint32_t u32_rx_can_id, uint8_t u8_mail_box_num)

Check the list of CAN RX filters and checks if the provided CAN ID matches any filter’s ID.

This function check through the list of CAN RX filters and checks if the provided CAN ID matches any filter’s ID.

Parameters:

ptr_rx_filters – [in] - Pointer to the CAN filter configuration structure
u8_num_rx_filter – [in] - number of RX filters
u32_rx_can_id – [in] - Reception of CAN ID
u8_mail_box_num – [in] - Reception of an mailbox number

Returns:

Return 0 on success or negative on failure

rs_ret_val_t rs_can_close(rs_handle_t handle)

UN-initializes the CAN interface.

This function UN-initializes the CAN interface and releases the handle

Parameters:: handle – [in] - Handle to the CAN interface
Returns:: 0 on success or error code on failure

struct tag_rs_can_data

#include <rs_can.h>

Structure for configuring the CAN interface.

Public Members

uint8_t ext_id: CAN extended or standard.

uint8_t can_data_len: CAN data length.

uint8_t rtr: CAN frame RTR or DATA.

uint8_t error_indication: Data packet status.

uint32_t timestamp: Transmit/Receive time stamp.

uint8_t status: Data packet status.

uint8_t mailbox: Mailbox.

uint16_t reserved: Reserved.

uint32_t can_id: CAN ID.

uint8_t arr_can_data[8]: CAN Data.

struct tag_rs_can_data_ptr_with_ts

Public Members

uint8_t *ptr_data: Pointer to CAN data.

rs_timestamp_t ts: Received timestamp.

struct tag_rs_can_buf_config

#include <rs_can.h>

Structure for CAN buffer config.

Public Members

uint8_t write_index: Write index of the Buffer.

uint8_t read_index: Read index of the Buffer.

uint16_t num_buffers: Total number of Buffers.

rs_can_data_t *ptr_can_data: Pointer to the CAN data.

rs_buffer_mgr_t buffer_mgr: Buffer-Array-backed-FIFO buffer manager.

struct tag_rs_can_rx_filter

#include <rs_can.h>

Structure for configuring Receive Filter.

Public Members

uint32_t id: ID to filter.

uint32_t id_mask: Mask to apply for filtering.

uint16_t prop: Properties.

uint16_t dlc_check: Enable data length check.

uint16_t mailbox: Mailbox to be associated with.

uint16_t reserved: Mailbox to be associated with.

uint16_t sw_filter_type: 0 for acceptance filter or 1 for rejection

uint16_t num_sw_filters: Number of SW IDs.

uint32_t *ptr_can_ids: CAN IDs to be rejected/accepted.

uint8_t reserved1[8]: Reserved.

struct tag_rs_can_config

#include <rs_can.h>

Structure for configuring the CAN interface.

Public Members

uint8_t port: Index to CAN Port.

uint16_t num_std_filter: Number of standard filter.

uint16_t num_extd_filter: Number of extended filter.

uint8_t support_FD: support CAN FD

uint8_t op_mode: Mode of operation.

uint8_t non_blocking: Blocking / Non-blocking.

uint8_t enable_bit_timing: Enable bit timing.

uint32_t baudrate: Baud rate for attribute.

uint32_t baudrate_data: Baud rate for data.

uint16_t num_tx_buffers: Number of transmit buffers to be allocated.

uint16_t num_rx_buffers: Number of receive buffers to be allocated.

rs_can_rx_filter_t *ptr_std_filter: Pointer to the standard filter.

rs_can_rx_filter_t *ptr_ext_filter: Pointer to the extended filter.

uint32_t can_rx_filter_count

void *ptr_can_handle

rs_can_rx_filter_t *ptr_can_rx_filter: Pointer to the extended filter.

struct tag_rs_can_instance

#include <rs_can.h>

Structure for the CAN instance.

Public Members

rs_can_config_t *ptr_can_config: Pointer to the CAN configuration.

rs_callback_info_t callback_info[RS_CAN_MAX_NUM_CALLBACKS]: Callback info storage.

rs_callback_mgr_t callback_mgr: Callback manager.

rs_can_buf_config_t tx_buffer_config: CAN transmit buffer configuration.

rs_can_buf_config_t rx_buffer_config: CAN receive buffer configuration.