CAN Interface . More...

Data Structures
struct	can_frame
	CAN frame structure. More...

struct	can_filter
	CAN filter structure. More...

struct	can_bus_err_cnt
	CAN controller error counters. More...

struct	can_timing
	CAN bus timing structure. More...

struct	can_device_state
	CAN specific device state which allows for CAN device class specific additions. More...

Macros
#define	CAN_STATS_BIT_ERROR_INC(dev_)
	Increment the bit error counter for a CAN device.

#define	CAN_STATS_BIT0_ERROR_INC(dev_)
	Increment the bit0 error counter for a CAN device.

#define	CAN_STATS_BIT1_ERROR_INC(dev_)
	Increment the bit1 (recessive) error counter for a CAN device.

#define	CAN_STATS_STUFF_ERROR_INC(dev_)
	Increment the stuffing error counter for a CAN device.

#define	CAN_STATS_CRC_ERROR_INC(dev_)
	Increment the CRC error counter for a CAN device.

#define	CAN_STATS_FORM_ERROR_INC(dev_)
	Increment the form error counter for a CAN device.

#define	CAN_STATS_ACK_ERROR_INC(dev_)
	Increment the acknowledge error counter for a CAN device.

#define	CAN_STATS_RX_OVERRUN_INC(dev_)
	Increment the RX overrun counter for a CAN device.

#define	CAN_STATS_RESET(dev_)
	Zero all statistics for a CAN device.

#define	CAN_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, ...)
	Like DEVICE_DT_DEFINE() with CAN device specifics.

#define	CAN_DEVICE_DT_INST_DEFINE(inst, ...)
	Like CAN_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible.

Typedefs
typedef uint32_t	can_mode_t
	Provides a type to hold CAN controller configuration flags.

typedef void(*	can_tx_callback_t) (const struct device dev, int error, void user_data)
	Defines the application callback handler function signature.

typedef void(*	can_rx_callback_t) (const struct device dev, struct can_frame frame, void *user_data)
	Defines the application callback handler function signature for receiving.

typedef void(*	can_state_change_callback_t) (const struct device dev, enum can_state state, struct can_bus_err_cnt err_cnt, void user_data)
	Defines the state change callback handler function signature.

Enumerations
enum	can_state { CAN_STATE_ERROR_ACTIVE , CAN_STATE_ERROR_WARNING , CAN_STATE_ERROR_PASSIVE , CAN_STATE_BUS_OFF , CAN_STATE_STOPPED }
	Defines the state of the CAN controller. More...

CAN controller configuration
int	can_get_core_clock (const struct device dev, uint32_t rate)
	Get the CAN core clock rate.

uint32_t	can_get_bitrate_min (const struct device *dev)
	Get minimum supported bitrate.

uint32_t	can_get_bitrate_max (const struct device *dev)
	Get maximum supported bitrate.

const struct can_timing *	can_get_timing_min (const struct device *dev)
	Get the minimum supported timing parameter values.

const struct can_timing *	can_get_timing_max (const struct device *dev)
	Get the maximum supported timing parameter values.

int	can_calc_timing (const struct device dev, struct can_timing res, uint32_t bitrate, uint16_t sample_pnt)
	Calculate timing parameters from bitrate and sample point.

const struct can_timing *	can_get_timing_data_min (const struct device *dev)
	Get the minimum supported timing parameter values for the data phase.

const struct can_timing *	can_get_timing_data_max (const struct device *dev)
	Get the maximum supported timing parameter values for the data phase.

int	can_calc_timing_data (const struct device dev, struct can_timing res, uint32_t bitrate, uint16_t sample_pnt)
	Calculate timing parameters for the data phase.

int	can_set_timing_data (const struct device dev, const struct can_timing timing_data)
	Configure the bus timing for the data phase of a CAN FD controller.

int	can_set_bitrate_data (const struct device *dev, uint32_t bitrate_data)
	Set the bitrate for the data phase of the CAN FD controller.

int	can_set_timing (const struct device dev, const struct can_timing timing)
	Configure the bus timing of a CAN controller.

int	can_get_capabilities (const struct device dev, can_mode_t cap)
	Get the supported modes of the CAN controller.

const struct device *	can_get_transceiver (const struct device *dev)
	Get the CAN transceiver associated with the CAN controller.

int	can_start (const struct device *dev)
	Start the CAN controller.

int	can_stop (const struct device *dev)
	Stop the CAN controller.

int	can_set_mode (const struct device *dev, can_mode_t mode)
	Set the CAN controller to the given operation mode.

can_mode_t	can_get_mode (const struct device *dev)
	Get the operation mode of the CAN controller.

int	can_set_bitrate (const struct device *dev, uint32_t bitrate)
	Set the bitrate of the CAN controller.

Transmitting CAN frames
int	can_send (const struct device dev, const struct can_frame frame, k_timeout_t timeout, can_tx_callback_t callback, void *user_data)
	Queue a CAN frame for transmission on the CAN bus.

Receiving CAN frames
int	can_add_rx_filter (const struct device dev, can_rx_callback_t callback, void user_data, const struct can_filter *filter)
	Add a callback function for a given CAN filter.

int	can_add_rx_filter_msgq (const struct device dev, struct k_msgq msgq, const struct can_filter *filter)
	Simple wrapper function for adding a message queue for a given filter.

void	can_remove_rx_filter (const struct device *dev, int filter_id)
	Remove a CAN RX filter.

int	can_get_max_filters (const struct device *dev, bool ide)
	Get maximum number of RX filters.

#define	CAN_MSGQ_DEFINE(name, max_frames)
	Statically define and initialize a CAN RX message queue.

CAN bus error reporting and handling
int	can_get_state (const struct device dev, enum can_state state, struct can_bus_err_cnt *err_cnt)
	Get current CAN controller state.

int	can_recover (const struct device *dev, k_timeout_t timeout)
	Recover from bus-off state.

static void	can_set_state_change_callback (const struct device dev, can_state_change_callback_t callback, void user_data)
	Set a callback for CAN controller state change events.

CAN statistics
uint32_t	can_stats_get_bit_errors (const struct device *dev)
	Get the bit error counter for a CAN device.

uint32_t	can_stats_get_bit0_errors (const struct device *dev)
	Get the bit0 error counter for a CAN device.

uint32_t	can_stats_get_bit1_errors (const struct device *dev)
	Get the bit1 error counter for a CAN device.

uint32_t	can_stats_get_stuff_errors (const struct device *dev)
	Get the stuffing error counter for a CAN device.

uint32_t	can_stats_get_crc_errors (const struct device *dev)
	Get the CRC error counter for a CAN device.

uint32_t	can_stats_get_form_errors (const struct device *dev)
	Get the form error counter for a CAN device.

uint32_t	can_stats_get_ack_errors (const struct device *dev)
	Get the acknowledge error counter for a CAN device.

uint32_t	can_stats_get_rx_overruns (const struct device *dev)
	Get the RX overrun counter for a CAN device.

CAN utility functions
static uint8_t	can_dlc_to_bytes (uint8_t dlc)
	Convert from Data Length Code (DLC) to the number of data bytes.

static uint8_t	can_bytes_to_dlc (uint8_t num_bytes)
	Convert from number of bytes to Data Length Code (DLC)

static bool	can_frame_matches_filter (const struct can_frame frame, const struct can_filter filter)
	Check if a CAN frame matches a CAN filter.

CAN frame definitions
#define	CAN_STD_ID_MASK 0x7FFU
	Bit mask for a standard (11-bit) CAN identifier.

#define	CAN_EXT_ID_MASK 0x1FFFFFFFU
	Bit mask for an extended (29-bit) CAN identifier.

#define	CAN_MAX_DLC 8U
	Maximum data length code for CAN 2.0A/2.0B.

#define	CANFD_MAX_DLC 15U
	Maximum data length code for CAN FD.

CAN controller mode flags

#define	CAN_MODE_NORMAL 0
	Normal mode.

#define	CAN_MODE_LOOPBACK BIT(0)
	Controller is in loopback mode (receives own frames).

#define	CAN_MODE_LISTENONLY BIT(1)
	Controller is not allowed to send dominant bits.

#define	CAN_MODE_FD BIT(2)
	Controller allows transmitting/receiving CAN FD frames.

#define	CAN_MODE_ONE_SHOT BIT(3)
	Controller does not retransmit in case of lost arbitration or missing ACK.

#define	CAN_MODE_3_SAMPLES BIT(4)
	Controller uses triple sampling mode.

#define	CAN_MODE_MANUAL_RECOVERY BIT(5)
	Controller requires manual recovery after entering bus-off state.

CAN frame flags

#define	CAN_FRAME_IDE BIT(0)
	Frame uses extended (29-bit) CAN ID.

#define	CAN_FRAME_RTR BIT(1)
	Frame is a Remote Transmission Request (RTR)

#define	CAN_FRAME_FDF BIT(2)
	Frame uses CAN FD format (FDF)

#define	CAN_FRAME_BRS BIT(3)
	Frame uses CAN FD Baud Rate Switch (BRS).

#define	CAN_FRAME_ESI BIT(4)
	CAN FD Error State Indicator (ESI).

CAN filter flags

#define	CAN_FILTER_IDE BIT(0)
	Filter matches frames with extended (29-bit) CAN IDs.

Detailed Description

CAN Interface .

Since: 1.12

Version: 1.1.0

Macro Definition Documentation

◆ CAN_DEVICE_DT_DEFINE

#define CAN_DEVICE_DT_DEFINE	(	node_id,
		init_fn,
		pm,
		data,
		config,
		level,
		prio,
		api,
		... )

#include <zephyr/drivers/can.h>

Value:

        Z_CAN_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id));         \
        Z_CAN_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn)             \
        Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id),           \
                        DEVICE_DT_NAME(node_id),                        \
                        &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init),  \
                        pm, data, config, level, prio, api,             \
                        &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
                        __VA_ARGS__)

Like DEVICE_DT_DEFINE() with CAN device specifics.

Defines a device which implements the CAN API. May generate a custom device_state container struct and init_fn wrapper when needed depending on CONFIG_CAN_STATS.

Parameters

node_id	The devicetree node identifier.
init_fn	Name of the init function of the driver.
pm	PM device resources reference (NULL if device does not use PM).
data	Pointer to the device's private data.
config	The address to the structure containing the configuration information for this instance of the driver.
level	The initialization level. See SYS_INIT() for details.
prio	Priority within the selected initialization level. See SYS_INIT() for details.
api	Provides an initial pointer to the API function struct used by the driver. Can be NULL.

◆ CAN_DEVICE_DT_INST_DEFINE

#define CAN_DEVICE_DT_INST_DEFINE	(		inst,
			... )

#include <zephyr/drivers/can.h>

Value:

CAN_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)

CAN_DEVICE_DT_DEFINE

#define CAN_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api,...)

Like DEVICE_DT_DEFINE() with CAN device specifics.

Definition can.h:757

DT_DRV_INST

#define DT_DRV_INST(inst)

Node identifier for an instance of a DT_DRV_COMPAT compatible.

Definition devicetree.h:3869

Like CAN_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible.

Parameters

inst	Instance number. This is replaced by `DT_DRV_COMPAT(inst)` in the call to CAN_DEVICE_DT_DEFINE().
...	Other parameters as expected by CAN_DEVICE_DT_DEFINE().

◆ CAN_EXT_ID_MASK

#define CAN_EXT_ID_MASK 0x1FFFFFFFU

#include <zephyr/drivers/can.h>

Bit mask for an extended (29-bit) CAN identifier.

◆ CAN_FILTER_IDE

#define CAN_FILTER_IDE BIT(0)

#include <zephyr/drivers/can.h>

Filter matches frames with extended (29-bit) CAN IDs.

◆ CAN_FRAME_BRS

#define CAN_FRAME_BRS BIT(3)

#include <zephyr/drivers/can.h>

Frame uses CAN FD Baud Rate Switch (BRS).

Only valid in combination with CAN_FRAME_FDF.

◆ CAN_FRAME_ESI

#define CAN_FRAME_ESI BIT(4)

#include <zephyr/drivers/can.h>

CAN FD Error State Indicator (ESI).

Indicates that the transmitting node is in error-passive state. Only valid in combination with CAN_FRAME_FDF.

◆ CAN_FRAME_FDF

#define CAN_FRAME_FDF BIT(2)

#include <zephyr/drivers/can.h>

Frame uses CAN FD format (FDF)

◆ CAN_FRAME_IDE

#define CAN_FRAME_IDE BIT(0)

#include <zephyr/drivers/can.h>

Frame uses extended (29-bit) CAN ID.

◆ CAN_FRAME_RTR

#define CAN_FRAME_RTR BIT(1)

#include <zephyr/drivers/can.h>

Frame is a Remote Transmission Request (RTR)

◆ CAN_MAX_DLC

#define CAN_MAX_DLC 8U

#include <zephyr/drivers/can.h>

Maximum data length code for CAN 2.0A/2.0B.

◆ CAN_MODE_3_SAMPLES

#define CAN_MODE_3_SAMPLES BIT(4)

#include <zephyr/drivers/can.h>

Controller uses triple sampling mode.

◆ CAN_MODE_FD

#define CAN_MODE_FD BIT(2)

#include <zephyr/drivers/can.h>

Controller allows transmitting/receiving CAN FD frames.

◆ CAN_MODE_LISTENONLY

#define CAN_MODE_LISTENONLY BIT(1)

#include <zephyr/drivers/can.h>

Controller is not allowed to send dominant bits.

◆ CAN_MODE_LOOPBACK

#define CAN_MODE_LOOPBACK BIT(0)

#include <zephyr/drivers/can.h>

Controller is in loopback mode (receives own frames).

◆ CAN_MODE_MANUAL_RECOVERY

#define CAN_MODE_MANUAL_RECOVERY BIT(5)

#include <zephyr/drivers/can.h>

Controller requires manual recovery after entering bus-off state.

◆ CAN_MODE_NORMAL

#define CAN_MODE_NORMAL 0

#include <zephyr/drivers/can.h>

Normal mode.

◆ CAN_MODE_ONE_SHOT

#define CAN_MODE_ONE_SHOT BIT(3)

#include <zephyr/drivers/can.h>

Controller does not retransmit in case of lost arbitration or missing ACK.

◆ CAN_MSGQ_DEFINE

#define CAN_MSGQ_DEFINE	(		name,
			max_frames )

#include <zephyr/drivers/can.h>

Value:

K_MSGQ_DEFINE(name, sizeof(struct can_frame), max_frames, 4)

K_MSGQ_DEFINE

#define K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align)

Statically define and initialize a message queue.

Definition kernel.h:4618

can_frame

CAN frame structure.

Definition can.h:163

Statically define and initialize a CAN RX message queue.

The message queue's ring buffer contains space for max_frames CAN frames.

See also: can_add_rx_filter_msgq()

Parameters

name	Name of the message queue.
max_frames	Maximum number of CAN frames that can be queued.

◆ CAN_STATS_ACK_ERROR_INC

#define CAN_STATS_ACK_ERROR_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

STATS_INC(Z_CAN_GET_STATS(dev_), ack_error)

STATS_INC

#define STATS_INC(group__, var__)

Definition stats.h:364

Increment the acknowledge error counter for a CAN device.

The acknowledge error counter is incremented when the CAN controller does not monitor a dominant bit in the ACK slot.

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_BIT0_ERROR_INC

#define CAN_STATS_BIT0_ERROR_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

        do {                                                    \
                STATS_INC(Z_CAN_GET_STATS(dev_), bit0_error);   \
                CAN_STATS_BIT_ERROR_INC(dev_);                  \
        } while (0)

Increment the bit0 error counter for a CAN device.

The bit0 error counter is incremented when the CAN controller is unable to transmit a dominant bit.

Incrementing this counter will automatically increment the bit error counter.

See also: CAN_STATS_BIT_ERROR_INC()

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_BIT1_ERROR_INC

#define CAN_STATS_BIT1_ERROR_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

        do {                                                    \
                STATS_INC(Z_CAN_GET_STATS(dev_), bit1_error);   \
                CAN_STATS_BIT_ERROR_INC(dev_);                  \
        } while (0)

Increment the bit1 (recessive) error counter for a CAN device.

The bit1 error counter is incremented when the CAN controller is unable to transmit a recessive bit.

Incrementing this counter will automatically increment the bit error counter.

See also: CAN_STATS_BIT_ERROR_INC()

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_BIT_ERROR_INC

#define CAN_STATS_BIT_ERROR_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

STATS_INC(Z_CAN_GET_STATS(dev_), bit_error)

Increment the bit error counter for a CAN device.

The bit error counter is incremented when the CAN controller is unable to transmit either a dominant or a recessive bit.

Note: This error counter should only be incremented if the CAN controller is unable to distinguish between failure to transmit a dominant versus failure to transmit a recessive bit. If the CAN controller supports distinguishing between the two, the bit0 or bit1 error counter shall be incremented instead.

See also: CAN_STATS_BIT0_ERROR_INC(); CAN_STATS_BIT1_ERROR_INC()

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_CRC_ERROR_INC

#define CAN_STATS_CRC_ERROR_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

STATS_INC(Z_CAN_GET_STATS(dev_), crc_error)

Increment the CRC error counter for a CAN device.

The CRC error counter is incremented when the CAN controller detects a frame with an invalid CRC.

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_FORM_ERROR_INC

#define CAN_STATS_FORM_ERROR_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

STATS_INC(Z_CAN_GET_STATS(dev_), form_error)

Increment the form error counter for a CAN device.

The form error counter is incremented when the CAN controller detects a fixed-form bit field containing illegal bits.

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_RESET

#define CAN_STATS_RESET ( dev_ )

#include <zephyr/drivers/can.h>

Value:

stats_reset(&(Z_CAN_GET_STATS(dev_).s_hdr))

Zero all statistics for a CAN device.

The driver is responsible for resetting the statistics before starting the CAN controller.

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_RX_OVERRUN_INC

#define CAN_STATS_RX_OVERRUN_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

STATS_INC(Z_CAN_GET_STATS(dev_), rx_overrun)

Increment the RX overrun counter for a CAN device.

The RX overrun counter is incremented when the CAN controller receives a CAN frame matching an installed filter but lacks the capacity to store it (either due to an already full RX mailbox or a full RX FIFO).

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STATS_STUFF_ERROR_INC

#define CAN_STATS_STUFF_ERROR_INC ( dev_ )

#include <zephyr/drivers/can.h>

Value:

STATS_INC(Z_CAN_GET_STATS(dev_), stuff_error)

Increment the stuffing error counter for a CAN device.

The stuffing error counter is incremented when the CAN controller detects a bit stuffing error.

Parameters

dev_	Pointer to the device structure for the driver instance.

◆ CAN_STD_ID_MASK

#define CAN_STD_ID_MASK 0x7FFU

#include <zephyr/drivers/can.h>

Bit mask for a standard (11-bit) CAN identifier.

◆ CANFD_MAX_DLC

#define CANFD_MAX_DLC 15U

#include <zephyr/drivers/can.h>

Maximum data length code for CAN FD.

Typedef Documentation

◆ can_mode_t

typedef uint32_t can_mode_t

#include <zephyr/drivers/can.h>

Provides a type to hold CAN controller configuration flags.

The lower 24 bits are reserved for common CAN controller mode flags. The upper 8 bits are reserved for CAN controller/driver specific flags.

See also: CAN_MODE_FLAGS.

◆ can_rx_callback_t

typedef void(* can_rx_callback_t) (const struct device *dev, struct can_frame *frame, void *user_data)

#include <zephyr/drivers/can.h>

Defines the application callback handler function signature for receiving.

Parameters

dev	Pointer to the device structure for the driver instance.
frame	Received frame.
user_data	User data provided when the filter was added.

◆ can_state_change_callback_t

typedef void(* can_state_change_callback_t) (const struct device *dev, enum can_state state, struct can_bus_err_cnt err_cnt, void *user_data)

#include <zephyr/drivers/can.h>

Defines the state change callback handler function signature.

Parameters

dev	Pointer to the device structure for the driver instance.
state	State of the CAN controller.
err_cnt	CAN controller error counter values.
user_data	User data provided the callback was set.

◆ can_tx_callback_t

typedef void(* can_tx_callback_t) (const struct device *dev, int error, void *user_data)

#include <zephyr/drivers/can.h>

Defines the application callback handler function signature.

Parameters

dev	Pointer to the device structure for the driver instance.
error	Status of the performed send operation. See the list of return values for can_send() for value descriptions.
user_data	User data provided when the frame was sent.

Enumeration Type Documentation

◆ can_state

enum can_state

#include <zephyr/drivers/can.h>

Defines the state of the CAN controller.

Enumerator
CAN_STATE_ERROR_ACTIVE	Error-active state (RX/TX error count < 96).
CAN_STATE_ERROR_WARNING	Error-warning state (RX/TX error count < 128).
CAN_STATE_ERROR_PASSIVE	Error-passive state (RX/TX error count < 256).
CAN_STATE_BUS_OFF	Bus-off state (RX/TX error count >= 256).
CAN_STATE_STOPPED	CAN controller is stopped and does not participate in CAN communication.

Function Documentation

◆ can_add_rx_filter()

int can_add_rx_filter	(	const struct device *	dev,
		can_rx_callback_t	callback,
		void *	user_data,
		const struct can_filter *	filter )

#include <zephyr/drivers/can.h>

Add a callback function for a given CAN filter.

Add a callback to CAN identifiers specified by a filter. When a received CAN frame matching the filter is received by the CAN controller, the callback function is called in interrupt context.

If a received frame matches more than one filter (i.e., the filter IDs/masks or flags overlap), the priority of the match is hardware dependent.

The same callback function can be used for multiple filters.

Parameters

dev	Pointer to the device structure for the driver instance.
callback	This function is called by the CAN controller driver whenever a frame matching the filter is received.
user_data	User data to pass to callback function.
filter	Pointer to a can_filter structure defining the filter.

Return values

filter_id	on success.
-ENOSPC	if there are no free filters.
-EINVAL	if the requested filter type is invalid.
-ENOTSUP	if the requested filter type is not supported.

◆ can_add_rx_filter_msgq()

int can_add_rx_filter_msgq	(	const struct device *	dev,
		struct k_msgq *	msgq,
		const struct can_filter *	filter )

#include <zephyr/drivers/can.h>

Simple wrapper function for adding a message queue for a given filter.

Wrapper function for can_add_rx_filter() which puts received CAN frames matching the filter in a message queue instead of calling a callback.

If a received frame matches more than one filter (i.e., the filter IDs/masks or flags overlap), the priority of the match is hardware dependent.

The same message queue can be used for multiple filters.

Note: The message queue must be initialized before calling this function and the caller must have appropriate permissions on it.

Warning: Message queue overruns are silently ignored and overrun frames discarded. Custom error handling can be implemented by using can_add_rx_filter() and k_msgq_put() directly.

Parameters

dev	Pointer to the device structure for the driver instance.
msgq	Pointer to the already initialized k_msgq struct.
filter	Pointer to a can_filter structure defining the filter.

Return values

filter_id	on success.
-ENOSPC	if there are no free filters.
-ENOTSUP	if the requested filter type is not supported.

◆ can_bytes_to_dlc()

static uint8_t can_bytes_to_dlc ( uint8_t num_bytes )

inlinestatic

#include <zephyr/drivers/can.h>

Convert from number of bytes to Data Length Code (DLC)

Parameters

num_bytes Number of bytes.

Return values

Data	Length Code (DLC).

◆ can_calc_timing()

int can_calc_timing	(	const struct device *	dev,
		struct can_timing *	res,
		uint32_t	bitrate,
		uint16_t	sample_pnt )

#include <zephyr/drivers/can.h>

Calculate timing parameters from bitrate and sample point.

Calculate the timing parameters from a given bitrate in bits/s and the sampling point in permill (1/1000) of the entire bit time. The bitrate must always match perfectly. If no result can be reached for the given parameters, -EINVAL is returned.

If the sample point is set to 0, this function defaults to a sample point of 75.0% for bitrates over 800 kbit/s, 80.0% for bitrates over 500 kbit/s, and 87.5% for all other bitrates.

Note: The requested sample_pnt will not always be matched perfectly. The algorithm calculates the best possible match.

Parameters

	dev	Pointer to the device structure for the driver instance.
[out]	res	Result is written into the can_timing struct provided.
	bitrate	Target bitrate in bits/s.
	sample_pnt	Sample point in permille of the entire bit time or 0 for automatic sample point location.

Return values

0	or positive sample point error on success.
-EINVAL	if the requested bitrate or sample point is out of range.
-ENOTSUP	if the requested bitrate is not supported.
-EIO	if can_get_core_clock() is not available.

◆ can_calc_timing_data()

int can_calc_timing_data	(	const struct device *	dev,
		struct can_timing *	res,
		uint32_t	bitrate,
		uint16_t	sample_pnt )

#include <zephyr/drivers/can.h>

Calculate timing parameters for the data phase.

Same as can_calc_timing() but with the maximum and minimum values from the data phase.

Note: CONFIG_CAN_FD_MODE must be selected for this function to be available.

Parameters

	dev	Pointer to the device structure for the driver instance.
[out]	res	Result is written into the can_timing struct provided.
	bitrate	Target bitrate for the data phase in bits/s
	sample_pnt	Sample point for the data phase in permille of the entire bit time or 0 for automatic sample point location.

Return values

0	or positive sample point error on success.
-EINVAL	if the requested bitrate or sample point is out of range.
-ENOTSUP	if the requested bitrate is not supported.
-EIO	if can_get_core_clock() is not available.

◆ can_dlc_to_bytes()

static uint8_t can_dlc_to_bytes ( uint8_t dlc )

inlinestatic

#include <zephyr/drivers/can.h>

Convert from Data Length Code (DLC) to the number of data bytes.

Parameters

dlc	Data Length Code (DLC).

Return values

Number of bytes.

◆ can_frame_matches_filter()

static bool can_frame_matches_filter	(	const struct can_frame *	frame,
		const struct can_filter *	filter )

inlinestatic

#include <zephyr/drivers/can.h>

Check if a CAN frame matches a CAN filter.

Parameters

frame	CAN frame.
filter	CAN filter.

Returns: true if the CAN frame matches the CAN filter, false otherwise

◆ can_get_bitrate_max()

uint32_t can_get_bitrate_max ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get maximum supported bitrate.

Get the maximum supported bitrate for the CAN controller/transceiver combination.

Note: The maximum bitrate represents limitations of the CAN controller/transceiver combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock rate and the maximum CAN timing limits.

See also: can_get_core_clock(); can_get_timing_max(); can_get_timing_data_max()

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Maximum supported bitrate in bits/s

◆ can_get_bitrate_min()

uint32_t can_get_bitrate_min ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get minimum supported bitrate.

Get the minimum supported bitrate for the CAN controller/transceiver combination.

Note: The minimum bitrate represents limitations of the CAN controller/transceiver combination. Whether the CAN controller can achieve this bitrate depends on the CAN core clock rate and the minimum CAN timing limits.

See also: can_get_core_clock(); can_get_timing_min(); can_get_timing_data_min()

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Minimum supported bitrate in bits/s. A value of 0 means the lower limit is unspecified.

◆ can_get_capabilities()

int can_get_capabilities	(	const struct device *	dev,
		can_mode_t *	cap )

#include <zephyr/drivers/can.h>

Get the supported modes of the CAN controller.

The returned capabilities may not necessarily be supported at the same time (e.g. some CAN controllers support both CAN_MODE_LOOPBACK and CAN_MODE_LISTENONLY, but not at the same time).

Parameters

	dev	Pointer to the device structure for the driver instance.
[out]	cap	Supported capabilities.

Return values

0	If successful.
-EIO	General input/output error, failed to get capabilities.

◆ can_get_core_clock()

int can_get_core_clock	(	const struct device *	dev,
		uint32_t *	rate )

#include <zephyr/drivers/can.h>

Get the CAN core clock rate.

Returns the CAN core clock rate. One minimum time quantum (mtq) is 1/(core clock rate). The CAN core clock can be further divided by the CAN clock prescaler (see the can_timing struct), providing the time quantum (tq).

Parameters

	dev	Pointer to the device structure for the driver instance.
[out]	rate	CAN core clock rate in Hz.

Returns: 0 on success, or a negative error code on error

◆ can_get_max_filters()

int can_get_max_filters	(	const struct device *	dev,
		bool	ide )

#include <zephyr/drivers/can.h>

Get maximum number of RX filters.

Get the maximum number of concurrent RX filters for the CAN controller.

Parameters

dev	Pointer to the device structure for the driver instance.
ide	Get the maximum standard (11-bit) CAN ID filters if false, or extended (29-bit) CAN ID filters if true.

Return values

Positive	number of maximum concurrent filters.
-EIO	General input/output error.
-ENOSYS	If this function is not implemented by the driver.

◆ can_get_mode()

can_mode_t can_get_mode ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the operation mode of the CAN controller.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Current operation mode.

◆ can_get_state()

int can_get_state	(	const struct device *	dev,
		enum can_state *	state,
		struct can_bus_err_cnt *	err_cnt )

#include <zephyr/drivers/can.h>

Get current CAN controller state.

Returns the current state and optionally the error counter values of the CAN controller.

Parameters

	dev	Pointer to the device structure for the driver instance.
[out]	state	Pointer to the state destination enum or NULL.
[out]	err_cnt	Pointer to the err_cnt destination structure or NULL.

Return values

0	If successful.
-EIO	General input/output error, failed to get state.

◆ can_get_timing_data_max()

const struct can_timing * can_get_timing_data_max ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the maximum supported timing parameter values for the data phase.

Same as can_get_timing_max() but for the maximum values for the data phase.

Note: CONFIG_CAN_FD_MODE must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Pointer to the maximum supported timing parameter values, or NULL if CAN FD support is not implemented by the driver.

◆ can_get_timing_data_min()

const struct can_timing * can_get_timing_data_min ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the minimum supported timing parameter values for the data phase.

Same as can_get_timing_min() but for the minimum values for the data phase.

Note: CONFIG_CAN_FD_MODE must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Pointer to the minimum supported timing parameter values, or NULL if CAN FD support is not implemented by the driver.

◆ can_get_timing_max()

const struct can_timing * can_get_timing_max ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the maximum supported timing parameter values.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Pointer to the maximum supported timing parameter values.

◆ can_get_timing_min()

const struct can_timing * can_get_timing_min ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the minimum supported timing parameter values.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Pointer to the minimum supported timing parameter values.

◆ can_get_transceiver()

const struct device * can_get_transceiver ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the CAN transceiver associated with the CAN controller.

Get a pointer to the device structure for the CAN transceiver associated with the CAN controller.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: Pointer to the device structure for the associated CAN transceiver driver instance, or NULL if no transceiver is associated.

◆ can_recover()

int can_recover	(	const struct device *	dev,
		k_timeout_t	timeout )

#include <zephyr/drivers/can.h>

Recover from bus-off state.

Recover the CAN controller from bus-off state to error-active state.

Note: CONFIG_CAN_MANUAL_RECOVERY_MODE must be enabled for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.
timeout	Timeout for waiting for the recovery or `K_FOREVER`.

Return values

0	on success.
-ENOTSUP	if the CAN controller is not in manual recovery mode.
-ENETDOWN	if the CAN controller is in stopped state.
-EAGAIN	on timeout.
-ENOSYS	If this function is not implemented by the driver.

◆ can_remove_rx_filter()

void can_remove_rx_filter	(	const struct device *	dev,
		int	filter_id )

#include <zephyr/drivers/can.h>

Remove a CAN RX filter.

This routine removes a CAN RX filter based on the filter ID returned by can_add_rx_filter() or can_add_rx_filter_msgq().

Parameters

dev	Pointer to the device structure for the driver instance.
filter_id	Filter ID

◆ can_send()

int can_send	(	const struct device *	dev,
		const struct can_frame *	frame,
		k_timeout_t	timeout,
		can_tx_callback_t	callback,
		void *	user_data )

#include <zephyr/drivers/can.h>

Queue a CAN frame for transmission on the CAN bus.

Queue a CAN frame for transmission on the CAN bus with optional timeout and completion callback function.

Queued CAN frames are transmitted in order according to the their priority:

The lower the CAN-ID, the higher the priority.
Data frames have higher priority than Remote Transmission Request (RTR) frames with identical CAN-IDs.
Frames with standard (11-bit) identifiers have higher priority than frames with extended (29-bit) identifiers with identical base IDs (the higher 11 bits of the extended identifier).
Transmission order for queued frames with the same priority is hardware dependent.

Note: If transmitting segmented messages spanning multiple CAN frames with identical CAN-IDs, the sender must ensure to only queue one frame at a time if FIFO order is required.

By default, the CAN controller will automatically retry transmission in case of lost bus arbitration or missing acknowledge. Some CAN controllers support disabling automatic retransmissions via CAN_MODE_ONE_SHOT.

Parameters

dev	Pointer to the device structure for the driver instance.
frame	CAN frame to transmit.
timeout	Timeout waiting for a empty TX mailbox or `K_FOREVER`.
callback	Optional callback for when the frame was sent or a transmission error occurred. If `NULL`, this function is blocking until frame is sent. The callback must be `NULL` if called from user mode.
user_data	User data to pass to callback function.

Return values

0	if successful.
-EINVAL	if an invalid parameter was passed to the function.
-ENOTSUP	if an unsupported parameter was passed to the function.
-ENETDOWN	if the CAN controller is in stopped state.
-ENETUNREACH	if the CAN controller is in bus-off state.
-EBUSY	if CAN bus arbitration was lost (only applicable if automatic retransmissions are disabled).
-EIO	if a general transmit error occurred (e.g. missing ACK if automatic retransmissions are disabled).
-EAGAIN	on timeout.

◆ can_set_bitrate()

int can_set_bitrate	(	const struct device *	dev,
		uint32_t	bitrate )

#include <zephyr/drivers/can.h>

Set the bitrate of the CAN controller.

CAN in Automation (CiA) 301 v4.2.0 recommends a sample point location of 87.5% percent for all bitrates. However, some CAN controllers have difficulties meeting this for higher bitrates.

This function defaults to using a sample point of 75.0% for bitrates over 800 kbit/s, 80.0% for bitrates over 500 kbit/s, and 87.5% for all other bitrates. This is in line with the sample point locations used by the Linux kernel.

See also: can_set_bitrate_data()

Parameters

dev	Pointer to the device structure for the driver instance.
bitrate	Desired arbitration phase bitrate.

Return values

0	If successful.
-EBUSY	if the CAN controller is not in stopped state.
-EINVAL	if the requested bitrate is out of range.
-ENOTSUP	if the requested bitrate not supported by the CAN controller/transceiver combination.
-ERANGE	if the resulting sample point is off by more than +/- 5%.
-EIO	General input/output error, failed to set bitrate.

◆ can_set_bitrate_data()

int can_set_bitrate_data	(	const struct device *	dev,
		uint32_t	bitrate_data )

#include <zephyr/drivers/can.h>

Set the bitrate for the data phase of the CAN FD controller.

CAN in Automation (CiA) 301 v4.2.0 recommends a sample point location of 87.5% percent for all bitrates. However, some CAN controllers have difficulties meeting this for higher bitrates.

This function defaults to using a sample point of 75.0% for bitrates over 800 kbit/s, 80.0% for bitrates over 500 kbit/s, and 87.5% for all other bitrates. This is in line with the sample point locations used by the Linux kernel.

Note: CONFIG_CAN_FD_MODE must be selected for this function to be available.

See also: can_set_bitrate()

Parameters

dev	Pointer to the device structure for the driver instance.
bitrate_data	Desired data phase bitrate.

Return values

0	If successful.
-EBUSY	if the CAN controller is not in stopped state.
-EINVAL	if the requested bitrate is out of range.
-ENOTSUP	if the requested bitrate not supported by the CAN controller/transceiver combination.
-ERANGE	if the resulting sample point is off by more than +/- 5%.
-EIO	General input/output error, failed to set bitrate.

◆ can_set_mode()

int can_set_mode	(	const struct device *	dev,
		can_mode_t	mode )

#include <zephyr/drivers/can.h>

Set the CAN controller to the given operation mode.

Parameters

dev	Pointer to the device structure for the driver instance.
mode	Operation mode.

Return values

0	If successful.
-EBUSY	if the CAN controller is not in stopped state.
-EIO	General input/output error, failed to configure device.

◆ can_set_state_change_callback()

static void can_set_state_change_callback	(	const struct device *	dev,
		can_state_change_callback_t	callback,
		void *	user_data )

inlinestatic

#include <zephyr/drivers/can.h>

Set a callback for CAN controller state change events.

Set the callback for CAN controller state change events. The callback function will be called in interrupt context.

Only one callback can be registered per controller. Calling this function again overrides any previously registered callback.

Parameters

dev	Pointer to the device structure for the driver instance.
callback	Callback function.
user_data	User data to pass to callback function.

◆ can_set_timing()

int can_set_timing	(	const struct device *	dev,
		const struct can_timing *	timing )

#include <zephyr/drivers/can.h>

Configure the bus timing of a CAN controller.

See also: can_set_timing_data()

Parameters

dev	Pointer to the device structure for the driver instance.
timing	Bus timings.

Return values

0	If successful.
-EBUSY	if the CAN controller is not in stopped state.
-ENOTSUP	if the timing parameters are not supported by the driver.
-EIO	General input/output error, failed to configure device.

◆ can_set_timing_data()

int can_set_timing_data	(	const struct device *	dev,
		const struct can_timing *	timing_data )

#include <zephyr/drivers/can.h>

Configure the bus timing for the data phase of a CAN FD controller.

Note: CONFIG_CAN_FD_MODE must be selected for this function to be available.

See also: can_set_timing()

Parameters

dev	Pointer to the device structure for the driver instance.
timing_data	Bus timings for data phase

Return values

0	If successful.
-EBUSY	if the CAN controller is not in stopped state.
-EIO	General input/output error, failed to configure device.
-ENOTSUP	if the timing parameters are not supported by the driver.
-ENOSYS	if CAN FD support is not implemented by the driver.

◆ can_start()

int can_start ( const struct device * dev )

#include <zephyr/drivers/can.h>

Start the CAN controller.

Bring the CAN controller out of CAN_STATE_STOPPED. This will reset the RX/TX error counters, enable the CAN controller to participate in CAN communication, and enable the CAN transceiver, if supported.

Starting the CAN controller resets all the CAN controller statistics.

See also: can_stop(); can_transceiver_enable()

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

0	if successful.
-EALREADY	if the device is already started.
-EIO	General input/output error, failed to start device.

◆ can_stats_get_ack_errors()

uint32_t can_stats_get_ack_errors ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the acknowledge error counter for a CAN device.

The acknowledge error counter is incremented when the CAN controller does not monitor a dominant bit in the ACK slot.

Note: CONFIG_CAN_STATS must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: acknowledge error counter

◆ can_stats_get_bit0_errors()

uint32_t can_stats_get_bit0_errors ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the bit0 error counter for a CAN device.

The bit0 error counter is incremented when the CAN controller is unable to transmit a dominant bit.

Note: CONFIG_CAN_STATS must be selected for this function to be available.

See also: can_stats_get_bit_errors()

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: bit0 error counter

◆ can_stats_get_bit1_errors()

uint32_t can_stats_get_bit1_errors ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the bit1 error counter for a CAN device.

The bit1 error counter is incremented when the CAN controller is unable to transmit a recessive bit.

Note: CONFIG_CAN_STATS must be selected for this function to be available.

See also: can_stats_get_bit_errors()

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: bit1 error counter

◆ can_stats_get_bit_errors()

uint32_t can_stats_get_bit_errors ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the bit error counter for a CAN device.

The bit error counter is incremented when the CAN controller is unable to transmit either a dominant or a recessive bit.

Note: CONFIG_CAN_STATS must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: bit error counter

◆ can_stats_get_crc_errors()

uint32_t can_stats_get_crc_errors ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the CRC error counter for a CAN device.

The CRC error counter is incremented when the CAN controller detects a frame with an invalid CRC.

Note: CONFIG_CAN_STATS must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: CRC error counter

◆ can_stats_get_form_errors()

uint32_t can_stats_get_form_errors ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the form error counter for a CAN device.

The form error counter is incremented when the CAN controller detects a fixed-form bit field containing illegal bits.

Note: CONFIG_CAN_STATS must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: form error counter

◆ can_stats_get_rx_overruns()

uint32_t can_stats_get_rx_overruns ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the RX overrun counter for a CAN device.

The RX overrun counter is incremented when the CAN controller receives a CAN frame matching an installed filter but lacks the capacity to store it (either due to an already full RX mailbox or a full RX FIFO).

Note: CONFIG_CAN_STATS must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: RX overrun counter

◆ can_stats_get_stuff_errors()

uint32_t can_stats_get_stuff_errors ( const struct device * dev )

#include <zephyr/drivers/can.h>

Get the stuffing error counter for a CAN device.

The stuffing error counter is incremented when the CAN controller detects a bit stuffing error.

Note: CONFIG_CAN_STATS must be selected for this function to be available.

Parameters

dev	Pointer to the device structure for the driver instance.

Returns: stuffing error counter

◆ can_stop()

int can_stop ( const struct device * dev )

#include <zephyr/drivers/can.h>

Stop the CAN controller.

Bring the CAN controller into CAN_STATE_STOPPED. This will disallow the CAN controller from participating in CAN communication, abort any pending CAN frame transmissions, and disable the CAN transceiver, if supported.

See also: can_start(); can_transceiver_disable()

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

0	if successful.
-EALREADY	if the device is already stopped.
-EIO	General input/output error, failed to stop device.

Data Structures

Macros

Typedefs

Enumerations

CAN controller configuration

Transmitting CAN frames

Receiving CAN frames

CAN bus error reporting and handling

CAN statistics

CAN utility functions

CAN frame definitions

CAN controller mode flags

CAN frame flags

CAN filter flags

Detailed Description

Macro Definition Documentation

◆ CAN_DEVICE_DT_DEFINE

◆ CAN_DEVICE_DT_INST_DEFINE

◆ CAN_EXT_ID_MASK

◆ CAN_FILTER_IDE

◆ CAN_FRAME_BRS

◆ CAN_FRAME_ESI

◆ CAN_FRAME_FDF

◆ CAN_FRAME_IDE

◆ CAN_FRAME_RTR

◆ CAN_MAX_DLC

◆ CAN_MODE_3_SAMPLES

◆ CAN_MODE_FD

◆ CAN_MODE_LISTENONLY

◆ CAN_MODE_LOOPBACK

◆ CAN_MODE_MANUAL_RECOVERY

◆ CAN_MODE_NORMAL

◆ CAN_MODE_ONE_SHOT

◆ CAN_MSGQ_DEFINE

◆ CAN_STATS_ACK_ERROR_INC

◆ CAN_STATS_BIT0_ERROR_INC

◆ CAN_STATS_BIT1_ERROR_INC

◆ CAN_STATS_BIT_ERROR_INC

◆ CAN_STATS_CRC_ERROR_INC

◆ CAN_STATS_FORM_ERROR_INC

◆ CAN_STATS_RESET

◆ CAN_STATS_RX_OVERRUN_INC

◆ CAN_STATS_STUFF_ERROR_INC

◆ CAN_STD_ID_MASK

◆ CANFD_MAX_DLC

Typedef Documentation

◆ can_mode_t

◆ can_rx_callback_t

◆ can_state_change_callback_t

◆ can_tx_callback_t

Enumeration Type Documentation

◆ can_state

Function Documentation

◆ can_add_rx_filter()

◆ can_add_rx_filter_msgq()

◆ can_bytes_to_dlc()

◆ can_calc_timing()

◆ can_calc_timing_data()

◆ can_dlc_to_bytes()

◆ can_frame_matches_filter()

◆ can_get_bitrate_max()

◆ can_get_bitrate_min()

◆ can_get_capabilities()

◆ can_get_core_clock()

◆ can_get_max_filters()

◆ can_get_mode()

◆ can_get_state()

◆ can_get_timing_data_max()

◆ can_get_timing_data_min()

◆ can_get_timing_max()

◆ can_get_timing_min()

◆ can_get_transceiver()

◆ can_recover()

◆ can_remove_rx_filter()

◆ can_send()

◆ can_set_bitrate()

◆ can_set_bitrate_data()

◆ can_set_mode()

◆ can_set_state_change_callback()

◆ can_set_timing()