The latest development version of this page may be more current than this released 1.14.1 version.

CAN

Overview

API Reference

group can_interface

CAN Interface.

Defines

CAN_EX_ID
CAN_MAX_STD_ID
CAN_STD_ID_MASK
CAN_EXT_ID_MASK
CAN_MAX_DLC
CAN_MAX_DLEN
CAN_TX_OK

send successfully

CAN_TX_ERR

general send error

CAN_TX_ARB_LOST

bus arbitration lost during sending

CAN_TX_BUS_OFF

controller is in bus off state

CAN_TX_UNKNOWN

unexpected error

CAN_NO_FREE_FILTER

attach_* failed because there is no unused filter left

CAN_TIMEOUT

operation timed out

CAN_DEFINE_MSGQ(name, size)

Statically define and initialize a can message queue.

The message queue’s ring buffer contains space for size messages.

Parameters
  • name: Name of the message queue.
  • size: Number of can messages.

Typedefs

typedef u32_t canid_t
typedef can_tx_callback_t

Define the application callback handler function signature.

Parameters
  • error_flags: status of the performed send operation

typedef can_rx_callback_t

Define the application callback handler function signature for receiving.

Parameters
  • received: message

typedef int (*can_configure_t)(struct device *dev, enum can_mode mode, u32_t bitrate)
typedef int (*can_send_t)(struct device *dev, const struct zcan_frame *msg, s32_t timeout, can_tx_callback_t callback_isr)
typedef int (*can_attach_msgq_t)(struct device *dev, struct k_msgq *msg_q, const struct zcan_filter *filter)
typedef int (*can_attach_isr_t)(struct device *dev, can_rx_callback_t isr, const struct zcan_filter *filter)
typedef void (*can_detach_t)(struct device *dev, int filter_id)

Enums

enum can_ide

can_ide enum Define if the message has a standard (11bit) or extended (29bit) identifier

Values:

CAN_STANDARD_IDENTIFIER
CAN_EXTENDED_IDENTIFIER
enum can_rtr

can_rtr enum Define if the message is a data or remote frame

Values:

CAN_DATAFRAME
CAN_REMOTEREQUEST
enum can_mode

can_mode enum Defines the mode of the can controller

Values:

CAN_NORMAL_MODE
CAN_SILENT_MODE
CAN_LOOPBACK_MODE
CAN_SILENT_LOOPBACK_MODE

Functions

int can_send(struct device *dev, const struct zcan_frame *msg, s32_t timeout, can_tx_callback_t callback_isr)

Perform data transfer to CAN bus.

This routine provides a generic interface to perform data transfer to the can bus. Use can_write() for simple write.

  • Parameters
    • dev: Pointer to the device structure for the driver instance.
    • msg: Message to transfer.
    • timeout: Waiting for empty tx mailbox timeout in ms or K_FOREVER.
    • callback_isr: Is called when message was sent or a transmission error occurred. If NULL, this function is blocking until message is sent. This must be NULL if called from user mode.
    Return Value
    • 0: If successful.
    • CAN_TX_*: on failure.

static int z_impl_can_send(struct device *dev, const struct zcan_frame *msg, s32_t timeout, can_tx_callback_t callback_isr)
static int can_write(struct device *dev, const u8_t *data, u8_t length, u32_t id, enum can_rtr rtr, s32_t timeout)

Write a set amount of data to the can bus.

This routine writes a set amount of data synchronously.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • data: Data to send.
  • length: Number of bytes to write (max. 8).
  • id: Identifier of the can message.
  • rtr: Send remote transmission request or data frame
  • timeout: Waiting for empty tx mailbox timeout in ms or K_FOREVER
Return Value
  • 0: If successful.
  • -EIO: General input / output error.
  • -EINVAL: if length > 8.

int can_attach_msgq(struct device *dev, struct k_msgq *msg_q, const struct zcan_filter *filter)

Attach a message queue to a single or group of identifiers.

This routine attaches a message queue to identifiers specified by a filter. Whenever the filter matches, the message is pushed to the queue If a message passes more than one filter the priority of the match is hardware dependent. A message queue can be attached to more than one filter. The message queue must me initialized before, and the caller must have appropriate permissions on it.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • msg_q: Pointer to the already initialized message queue.
  • filter: Pointer to a zcan_filter structure defining the id filtering.
Return Value
  • filter: id on success.
  • CAN_NO_FREE_FILTER: if there is no filter left.

static int z_impl_can_attach_msgq(struct device *dev, struct k_msgq *msg_q, const struct zcan_filter *filter)
static int can_attach_isr(struct device *dev, can_rx_callback_t isr, const struct zcan_filter *filter)

Attach an isr callback function to a single or group of identifiers.

This routine attaches an isr callback to identifiers specified by a filter. Whenever the filter matches, the callback function is called with isr context. If a message passes more than one filter the priority of the match is hardware dependent. A callback function can be attached to more than one filter.

  • Parameters
    • dev: Pointer to the device structure for the driver instance.
    • isr: Callback function pointer.
    • filter: Pointer to a zcan_filter structure defining the id filtering.
    Return Value
    • filter: id on success.
    • CAN_NO_FREE_FILTER: if there is no filter left.

void can_detach(struct device *dev, int filter_id)

Detach an isr or message queue from the identifier filtering.

This routine detaches an isr callback or message queue from the identifier filtering.

  • Parameters
    • dev: Pointer to the device structure for the driver instance.
    • filter_id: filter id returned by can_attach_isr or can_attach_msgq.
    Return Value
    • none:

static void z_impl_can_detach(struct device *dev, int filter_id)
int can_configure(struct device *dev, enum can_mode mode, u32_t bitrate)

Configure operation of a host controller.

Parameters
  • dev: Pointer to the device structure for the driver instance.
  • mode: Operation mode
  • bitrate: bus-speed in Baud/s
Return Value
  • 0: If successful.
  • -EIO: General input / output error, failed to configure device.

static int z_impl_can_configure(struct device *dev, enum can_mode mode, u32_t bitrate)
static void can_copy_frame_to_zframe(const struct can_frame *frame, struct zcan_frame *zframe)

Converter that translates between can_frame and zcan_frame structs.

Parameters

static void can_copy_zframe_to_frame(const struct zcan_frame *zframe, struct can_frame *frame)

Converter that translates between zcan_frame and can_frame structs.

Parameters

static void can_copy_filter_to_zfilter(const struct can_filter *filter, struct zcan_filter *zfilter)

Converter that translates between can_filter and zcan_frame_filter structs.

Parameters
  • filter: Pointer to can_filter struct.
  • zfilter: Pointer to zcan_frame_filter struct.

static void can_copy_zfilter_to_filter(const struct zcan_filter *zfilter, struct can_filter *filter)

Converter that translates between zcan_filter and can_filter structs.

Parameters

struct can_frame
#include <can.h>

CAN frame structure that is compatible with Linux. This is mainly used by Socket CAN code.

Used to pass CAN messages from userspace to the socket CAN and vice versa.

struct can_filter
#include <can.h>

CAN filter that is compatible with Linux. This is mainly used by Socket CAN code.

A filter matches, when “received_can_id & mask == can_id & mask”

struct zcan_frame
#include <can.h>

CAN message structure.

Used to pass can messages from userspace to the driver and from driver to userspace

struct zcan_filter
#include <can.h>

CAN filter structure.

Used to pass can identifier filter information to the driver. rtr_mask and *_id_mask are used to mask bits of the rtr and id fields. If the mask bit is 0, the value of the corresponding bit in the id or rtr field don’t care for the filter matching.