Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
CAN Interface

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.
 
static int can_get_min_bitrate (const struct device *dev, uint32_t *min_bitrate)
 Get minimum supported bitrate.
 
uint32_t can_get_bitrate_max (const struct device *dev)
 Get maximum supported bitrate.
 
static int can_get_max_bitrate (const struct device *dev, uint32_t *max_bitrate)
 Get maximum supported bitrate.
 
const struct can_timingcan_get_timing_min (const struct device *dev)
 Get the minimum supported timing parameter values.
 
const struct can_timingcan_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_timingcan_get_timing_data_min (const struct device *dev)
 Get the minimum supported timing parameter values for the data phase.
 
const struct can_timingcan_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_calc_prescaler (const struct device *dev, struct can_timing *timing, uint32_t bitrate)
 Fill in the prescaler value for a given bitrate and timing.
 
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 devicecan_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_MAX_STD_ID   CAN_STD_ID_MASK __DEPRECATED_MACRO
 Maximum value 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_EXT_ID   CAN_EXT_ID_MASK __DEPRECATED_MACRO
 Maximum value 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__)
#define DEVICE_DT_NAME(node_id)
Return a string name for a devicetree node.
Definition device.h:159
#define UTIL_CAT(a,...)
Definition util_internal.h:104

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_idThe devicetree node identifier.
init_fnName of the init function of the driver.
pmPM device resources reference (NULL if device does not use PM).
dataPointer to the device's private data.
configThe address to the structure containing the configuration information for this instance of the driver.
levelThe initialization level. See SYS_INIT() for details.
prioPriority within the selected initialization level. See SYS_INIT() for details.
apiProvides 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__)
#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:766
#define DT_DRV_INST(inst)
Node identifier for an instance of a DT_DRV_COMPAT compatible.
Definition devicetree.h:3759

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

Parameters
instInstance 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_MAX_EXT_ID

#define CAN_MAX_EXT_ID   CAN_EXT_ID_MASK __DEPRECATED_MACRO

#include <zephyr/drivers/can.h>

Maximum value for an extended (29-bit) CAN identifier.

Deprecated
Use CAN_EXT_ID_MASK instead.

◆ CAN_MAX_STD_ID

#define CAN_MAX_STD_ID   CAN_STD_ID_MASK __DEPRECATED_MACRO

#include <zephyr/drivers/can.h>

Maximum value for a standard (11-bit) CAN identifier.

Deprecated
Use CAN_STD_ID_MASK instead.

◆ 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)
#define K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align)
Statically define and initialize a message queue.
Definition kernel.h:4590
CAN frame structure.
Definition can.h:172

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
nameName of the message queue.
max_framesMaximum 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)
#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

#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
devPointer to the device structure for the driver instance.
frameReceived frame.
user_dataUser 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
devPointer to the device structure for the driver instance.
stateState of the CAN controller.
err_cntCAN controller error counter values.
user_dataUser 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
devPointer to the device structure for the driver instance.
errorStatus of the performed send operation. See the list of return values for can_send() for value descriptions.
user_dataUser 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
devPointer to the device structure for the driver instance.
callbackThis function is called by the CAN controller driver whenever a frame matching the filter is received.
user_dataUser data to pass to callback function.
filterPointer to a can_filter structure defining the filter.
Return values
filter_idon success.
-ENOSPCif there are no free filters.
-EINVALif the requested filter type is invalid.
-ENOTSUPif 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
devPointer to the device structure for the driver instance.
msgqPointer to the already initialized k_msgq struct.
filterPointer to a can_filter structure defining the filter.
Return values
filter_idon success.
-ENOSPCif there are no free filters.
-ENOTSUPif 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_bytesNumber of bytes.
Return values
DataLength Code (DLC).

◆ can_calc_prescaler()

int can_calc_prescaler ( const struct device * dev,
struct can_timing * timing,
uint32_t bitrate )

#include <zephyr/drivers/can.h>

Fill in the prescaler value for a given bitrate and timing.

Fill the prescaler value in the timing struct. The sjw, prop_seg, phase_seg1 and phase_seg2 must be given.

The returned bitrate error is remainder of the division of the clock rate by the bitrate times the timing segments.

Deprecated
This function allows for bitrate errors, but bitrate errors between nodes on the same network leads to them drifting apart after the start-of-frame (SOF) synchronization has taken place.
Parameters
devPointer to the device structure for the driver instance.
timingResult is written into the can_timing struct provided.
bitrateTarget bitrate.
Return values
0or positive bitrate error.
Negativeerror code on error.

◆ 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
devPointer to the device structure for the driver instance.
[out]resResult is written into the can_timing struct provided.
bitrateTarget bitrate in bits/s.
sample_pntSample point in permille of the entire bit time or 0 for automatic sample point location.
Return values
0or positive sample point error on success.
-EINVALif the requested bitrate or sample point is out of range.
-ENOTSUPif the requested bitrate is not supported.
-EIOif 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
devPointer to the device structure for the driver instance.
[out]resResult is written into the can_timing struct provided.
bitrateTarget bitrate for the data phase in bits/s
sample_pntSample point for the data phase in permille of the entire bit time or 0 for automatic sample point location.
Return values
0or positive sample point error on success.
-EINVALif the requested bitrate or sample point is out of range.
-ENOTSUPif the requested bitrate is not supported.
-EIOif 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
dlcData Length Code (DLC).
Return values
Numberof 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
frameCAN frame.
filterCAN 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.

Parameters
devPointer 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.

Parameters
devPointer to the device structure for the driver instance.
Returns
Minimum supported bitrate in bits/s

◆ 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
devPointer to the device structure for the driver instance.
[out]capSupported capabilities.
Return values
0If successful.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
[out]rateCAN core clock rate in Hz.
Returns
0 on success, or a negative error code on error

◆ can_get_max_bitrate()

static int can_get_max_bitrate ( const struct device * dev,
uint32_t * max_bitrate )
inlinestatic

#include <zephyr/drivers/can.h>

Get maximum supported bitrate.

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

Deprecated
Use can_get_bitrate_max() instead.
Parameters
devPointer to the device structure for the driver instance.
[out]max_bitrateMaximum supported bitrate in bits/s
Return values
0If successful.
-EIOGeneral input/output error.
-ENOSYSIf this function is not implemented by the driver.

◆ 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
devPointer to the device structure for the driver instance.
ideGet the maximum standard (11-bit) CAN ID filters if false, or extended (29-bit) CAN ID filters if true.
Return values
Positivenumber of maximum concurrent filters.
-EIOGeneral input/output error.
-ENOSYSIf this function is not implemented by the driver.

◆ can_get_min_bitrate()

static int can_get_min_bitrate ( const struct device * dev,
uint32_t * min_bitrate )
inlinestatic

#include <zephyr/drivers/can.h>

Get minimum supported bitrate.

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

Deprecated
Use can_get_bitrate_min() instead.
Parameters
devPointer to the device structure for the driver instance.
[out]min_bitrateMinimum supported bitrate in bits/s
Return values
-EIOGeneral input/output error.
-ENOSYSIf 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
devPointer 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
devPointer to the device structure for the driver instance.
[out]statePointer to the state destination enum or NULL.
[out]err_cntPointer to the err_cnt destination structure or NULL.
Return values
0If successful.
-EIOGeneral 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
devPointer 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
devPointer 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
devPointer 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
devPointer 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
devPointer 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
devPointer to the device structure for the driver instance.
timeoutTimeout for waiting for the recovery or K_FOREVER.
Return values
0on success.
-ENOTSUPif the CAN controller is not in manual recovery mode.
-ENETDOWNif the CAN controller is in stopped state.
-EAGAINon timeout.
-ENOSYSIf 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
devPointer to the device structure for the driver instance.
filter_idFilter 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
devPointer to the device structure for the driver instance.
frameCAN frame to transmit.
timeoutTimeout waiting for a empty TX mailbox or K_FOREVER.
callbackOptional 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_dataUser data to pass to callback function.
Return values
0if successful.
-EINVALif an invalid parameter was passed to the function.
-ENOTSUPif an unsupported parameter was passed to the function.
-ENETDOWNif the CAN controller is in stopped state.
-ENETUNREACHif the CAN controller is in bus-off state.
-EBUSYif CAN bus arbitration was lost (only applicable if automatic retransmissions are disabled).
-EIOif a general transmit error occurred (e.g. missing ACK if automatic retransmissions are disabled).
-EAGAINon 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
devPointer to the device structure for the driver instance.
bitrateDesired arbitration phase bitrate.
Return values
0If successful.
-EBUSYif the CAN controller is not in stopped state.
-EINVALif the requested bitrate is out of range.
-ENOTSUPif the requested bitrate not supported by the CAN controller/transceiver combination.
-ERANGEif the resulting sample point is off by more than +/- 5%.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
bitrate_dataDesired data phase bitrate.
Return values
0If successful.
-EBUSYif the CAN controller is not in stopped state.
-EINVALif the requested bitrate is out of range.
-ENOTSUPif the requested bitrate not supported by the CAN controller/transceiver combination.
-ERANGEif the resulting sample point is off by more than +/- 5%.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
modeOperation mode.
Return values
0If successful.
-EBUSYif the CAN controller is not in stopped state.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
callbackCallback function.
user_dataUser 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
devPointer to the device structure for the driver instance.
timingBus timings.
Return values
0If successful.
-EBUSYif the CAN controller is not in stopped state.
-ENOTSUPif the timing parameters are not supported by the driver.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
timing_dataBus timings for data phase
Return values
0If successful.
-EBUSYif the CAN controller is not in stopped state.
-EIOGeneral input/output error, failed to configure device.
-ENOTSUPif the timing parameters are not supported by the driver.
-ENOSYSif 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
devPointer to the device structure for the driver instance.
Return values
0if successful.
-EALREADYif the device is already started.
-EIOGeneral 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
devPointer 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
devPointer 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
devPointer 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
devPointer 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
devPointer 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
devPointer 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
devPointer 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
devPointer 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
devPointer to the device structure for the driver instance.
Return values
0if successful.
-EALREADYif the device is already stopped.
-EIOGeneral input/output error, failed to stop device.