Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
can.h File Reference

Controller Area Network (CAN) driver API. More...

#include <errno.h>
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <string.h>
#include <zephyr/sys_clock.h>
#include <zephyr/sys/util.h>
#include <zephyr/stats/stats.h>
#include <zephyr/syscalls/can.h>

Go to the source code of this file.

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_)    STATS_INC(Z_CAN_GET_STATS(dev_), bit_error)
 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_)    STATS_INC(Z_CAN_GET_STATS(dev_), stuff_error)
 Increment the stuffing error counter for a CAN device.
 
#define CAN_STATS_CRC_ERROR_INC(dev_)    STATS_INC(Z_CAN_GET_STATS(dev_), crc_error)
 Increment the CRC error counter for a CAN device.
 
#define CAN_STATS_FORM_ERROR_INC(dev_)    STATS_INC(Z_CAN_GET_STATS(dev_), form_error)
 Increment the form error counter for a CAN device.
 
#define CAN_STATS_ACK_ERROR_INC(dev_)    STATS_INC(Z_CAN_GET_STATS(dev_), ack_error)
 Increment the acknowledge error counter for a CAN device.
 
#define CAN_STATS_RX_OVERRUN_INC(dev_)    STATS_INC(Z_CAN_GET_STATS(dev_), rx_overrun)
 Increment the RX overrun counter for a CAN device.
 
#define CAN_STATS_RESET(dev_)    stats_reset(&(Z_CAN_GET_STATS(dev_).s_hdr))
 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, ...)    CAN_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
 Like CAN_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible.
 
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.
 

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

Functions

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

Receiving CAN frames

#define CAN_MSGQ_DEFINE(name, max_frames)    K_MSGQ_DEFINE(name, sizeof(struct can_frame), max_frames, 4)
 Statically define and initialize a CAN RX message queue.
 
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.
 

Detailed Description

Controller Area Network (CAN) driver API.