CAN ISO-TP Protocol

CAN ISO-TP Protocol. More...

Data Structures
struct	isotp_msg_id
	ISO-TP message id struct. More...
struct	isotp_fc_opts
	ISO-TP frame control options struct. More...

Macros
#define	ISOTP_N_OK   0
	Completed successfully.
#define	ISOTP_N_TIMEOUT_A   -1
	Ar/As has timed out.
#define	ISOTP_N_TIMEOUT_BS   -2
	Reception of next FC has timed out.
#define	ISOTP_N_TIMEOUT_CR   -3
	Cr has timed out.
#define	ISOTP_N_WRONG_SN   -4
	Unexpected sequence number.
#define	ISOTP_N_INVALID_FS   -5
	Invalid flow status received.
#define	ISOTP_N_UNEXP_PDU   -6
	Unexpected PDU received.
#define	ISOTP_N_WFT_OVRN   -7
	Maximum number of WAIT flowStatus PDUs exceeded.
#define	ISOTP_N_BUFFER_OVERFLW   -8
	FlowStatus OVFLW PDU was received.
#define	ISOTP_N_ERROR   -9
	General error.
#define	ISOTP_NO_FREE_FILTER   -10
	Implementation specific errors.
#define	ISOTP_NO_NET_BUF_LEFT   -11
	No net buffer left to allocate.
#define	ISOTP_NO_BUF_DATA_LEFT   -12
	Not sufficient space in the buffer left for the data.
#define	ISOTP_NO_CTX_LEFT   -13
	No context buffer left to allocate.
#define	ISOTP_RECV_TIMEOUT   -14
	Timeout for recv.
#define	ISOTP_FIXED_ADDR_SA_POS   (CONFIG_ISOTP_FIXED_ADDR_SA_POS)
	Position of fixed source address (SA)
#define	ISOTP_FIXED_ADDR_SA_MASK   (CONFIG_ISOTP_FIXED_ADDR_SA_MASK)
	Mask to obtain fixed source address (SA)
#define	ISOTP_FIXED_ADDR_TA_POS   (CONFIG_ISOTP_FIXED_ADDR_TA_POS)
	Position of fixed target address (TA)
#define	ISOTP_FIXED_ADDR_TA_MASK   (CONFIG_ISOTP_FIXED_ADDR_TA_MASK)
	Mask to obtain fixed target address (TA)
#define	ISOTP_FIXED_ADDR_PRIO_POS   (CONFIG_ISOTP_FIXED_ADDR_PRIO_POS)
	Position of priority in fixed addressing mode.
#define	ISOTP_FIXED_ADDR_PRIO_MASK   (CONFIG_ISOTP_FIXED_ADDR_PRIO_MASK)
	Mask for priority in fixed addressing mode.
#define	ISOTP_FIXED_ADDR_RX_MASK   (CONFIG_ISOTP_FIXED_ADDR_RX_MASK)
	CAN filter RX mask to match any priority and source address (SA)

Typedefs
typedef void(*	isotp_tx_callback_t) (int error_nr, void *arg)
	Transmission callback.

Functions
int	isotp_bind (struct isotp_recv_ctx *rctx, const struct device *can_dev, const struct isotp_msg_id *rx_addr, const struct isotp_msg_id *tx_addr, const struct isotp_fc_opts *opts, k_timeout_t timeout)
	Bind an address to a receiving context.
void	isotp_unbind (struct isotp_recv_ctx *rctx)
	Unbind a context from the interface.
int	isotp_recv (struct isotp_recv_ctx *rctx, uint8_t *data, size_t len, k_timeout_t timeout)
	Read out received data from fifo.
int	isotp_recv_net (struct isotp_recv_ctx *rctx, struct net_buf **buffer, k_timeout_t timeout)
	Get the net buffer on data reception.
int	isotp_send (struct isotp_send_ctx *sctx, const struct device *can_dev, const uint8_t *data, size_t len, const struct isotp_msg_id *tx_addr, const struct isotp_msg_id *rx_addr, isotp_tx_callback_t complete_cb, void *cb_arg)
	Send data.

ISO-TP message ID flags
#define	ISOTP_MSG_EXT_ADDR   BIT(0)
	Message uses ISO-TP extended addressing (first payload byte of CAN frame)
#define	ISOTP_MSG_FIXED_ADDR   BIT(1)
	Message uses ISO-TP fixed addressing (according to SAE J1939).
#define	ISOTP_MSG_IDE   BIT(2)
	Message uses extended (29-bit) CAN ID.
#define	ISOTP_MSG_FDF   BIT(3)
	Message uses CAN FD format (FDF)
#define	ISOTP_MSG_BRS   BIT(4)
	Message uses CAN FD Baud Rate Switch (BRS).

Detailed Description

CAN ISO-TP Protocol.

Macro Definition Documentation

ISOTP_FIXED_ADDR_PRIO_MASK

#define ISOTP_FIXED_ADDR_PRIO_MASK   (CONFIG_ISOTP_FIXED_ADDR_PRIO_MASK)

#include <zephyr/canbus/isotp.h>

Mask for priority in fixed addressing mode.

ISOTP_FIXED_ADDR_PRIO_POS

#define ISOTP_FIXED_ADDR_PRIO_POS   (CONFIG_ISOTP_FIXED_ADDR_PRIO_POS)

#include <zephyr/canbus/isotp.h>

Position of priority in fixed addressing mode.

ISOTP_FIXED_ADDR_RX_MASK

#define ISOTP_FIXED_ADDR_RX_MASK   (CONFIG_ISOTP_FIXED_ADDR_RX_MASK)

#include <zephyr/canbus/isotp.h>

CAN filter RX mask to match any priority and source address (SA)

ISOTP_FIXED_ADDR_SA_MASK

#define ISOTP_FIXED_ADDR_SA_MASK   (CONFIG_ISOTP_FIXED_ADDR_SA_MASK)

#include <zephyr/canbus/isotp.h>

Mask to obtain fixed source address (SA)

ISOTP_FIXED_ADDR_SA_POS

#define ISOTP_FIXED_ADDR_SA_POS   (CONFIG_ISOTP_FIXED_ADDR_SA_POS)

#include <zephyr/canbus/isotp.h>

Position of fixed source address (SA)

ISOTP_FIXED_ADDR_TA_MASK

#define ISOTP_FIXED_ADDR_TA_MASK   (CONFIG_ISOTP_FIXED_ADDR_TA_MASK)

#include <zephyr/canbus/isotp.h>

Mask to obtain fixed target address (TA)

ISOTP_FIXED_ADDR_TA_POS

#define ISOTP_FIXED_ADDR_TA_POS   (CONFIG_ISOTP_FIXED_ADDR_TA_POS)

#include <zephyr/canbus/isotp.h>

Position of fixed target address (TA)

ISOTP_MSG_BRS

#define ISOTP_MSG_BRS   BIT(4)

#include <zephyr/canbus/isotp.h>

Message uses CAN FD Baud Rate Switch (BRS).

Only valid in combination with ISOTP_MSG_FDF.

ISOTP_MSG_EXT_ADDR

#define ISOTP_MSG_EXT_ADDR   BIT(0)

#include <zephyr/canbus/isotp.h>

Message uses ISO-TP extended addressing (first payload byte of CAN frame)

ISOTP_MSG_FDF

#define ISOTP_MSG_FDF   BIT(3)

#include <zephyr/canbus/isotp.h>

Message uses CAN FD format (FDF)

ISOTP_MSG_FIXED_ADDR

#define ISOTP_MSG_FIXED_ADDR   BIT(1)

#include <zephyr/canbus/isotp.h>

Message uses ISO-TP fixed addressing (according to SAE J1939).

Only valid in combination with ISOTP_MSG_IDE.

ISOTP_MSG_IDE

#define ISOTP_MSG_IDE   BIT(2)

#include <zephyr/canbus/isotp.h>

Message uses extended (29-bit) CAN ID.

ISOTP_N_BUFFER_OVERFLW

#define ISOTP_N_BUFFER_OVERFLW   -8

#include <zephyr/canbus/isotp.h>

FlowStatus OVFLW PDU was received.

ISOTP_N_ERROR

#define ISOTP_N_ERROR   -9

#include <zephyr/canbus/isotp.h>

General error.

ISOTP_N_INVALID_FS

#define ISOTP_N_INVALID_FS   -5

#include <zephyr/canbus/isotp.h>

Invalid flow status received.

ISOTP_N_OK

#define ISOTP_N_OK   0

#include <zephyr/canbus/isotp.h>

Completed successfully.

ISOTP_N_TIMEOUT_A

#define ISOTP_N_TIMEOUT_A   -1

#include <zephyr/canbus/isotp.h>

Ar/As has timed out.

ISOTP_N_TIMEOUT_BS

#define ISOTP_N_TIMEOUT_BS   -2

#include <zephyr/canbus/isotp.h>

Reception of next FC has timed out.

ISOTP_N_TIMEOUT_CR

#define ISOTP_N_TIMEOUT_CR   -3

#include <zephyr/canbus/isotp.h>

Cr has timed out.

ISOTP_N_UNEXP_PDU

#define ISOTP_N_UNEXP_PDU   -6

#include <zephyr/canbus/isotp.h>

Unexpected PDU received.

ISOTP_N_WFT_OVRN

#define ISOTP_N_WFT_OVRN   -7

#include <zephyr/canbus/isotp.h>

Maximum number of WAIT flowStatus PDUs exceeded.

ISOTP_N_WRONG_SN

#define ISOTP_N_WRONG_SN   -4

#include <zephyr/canbus/isotp.h>

Unexpected sequence number.

ISOTP_NO_BUF_DATA_LEFT

#define ISOTP_NO_BUF_DATA_LEFT   -12

#include <zephyr/canbus/isotp.h>

Not sufficient space in the buffer left for the data.

ISOTP_NO_CTX_LEFT

#define ISOTP_NO_CTX_LEFT   -13

#include <zephyr/canbus/isotp.h>

No context buffer left to allocate.

ISOTP_NO_FREE_FILTER

#define ISOTP_NO_FREE_FILTER   -10

#include <zephyr/canbus/isotp.h>

Implementation specific errors.

Can't bind or send because the CAN device has no filter left

ISOTP_NO_NET_BUF_LEFT

#define ISOTP_NO_NET_BUF_LEFT   -11

#include <zephyr/canbus/isotp.h>

No net buffer left to allocate.

ISOTP_RECV_TIMEOUT

#define ISOTP_RECV_TIMEOUT   -14

#include <zephyr/canbus/isotp.h>

Timeout for recv.

Typedef Documentation

isotp_tx_callback_t

typedef void(* isotp_tx_callback_t) (int error_nr, void *arg)

#include <zephyr/canbus/isotp.h>

Transmission callback.

This callback is called when a transmission is completed.

Parameters

error_nr	ISOTP_N_OK on success, ISOTP_N_* on error
arg	Callback argument passed to the send function

Function Documentation

isotp_bind()

int isotp_bind	(	struct isotp_recv_ctx *	rctx,
		const struct device *	can_dev,
		const struct isotp_msg_id *	rx_addr,
		const struct isotp_msg_id *	tx_addr,
		const struct isotp_fc_opts *	opts,
		k_timeout_t	timeout
	)

#include <zephyr/canbus/isotp.h>

Bind an address to a receiving context.

This function binds an RX and TX address combination to an RX context. When data arrives from the specified address, it is buffered and can be read by calling isotp_recv. When calling this routine, a filter is applied in the CAN device, and the context is initialized. The context must be valid until calling unbind.

Parameters

rctx	Context to store the internal states.
can_dev	The CAN device to be used for sending and receiving.
rx_addr	Identifier for incoming data.
tx_addr	Identifier for FC frames.
opts	Flow control options.
timeout	Timeout for FF SF buffer allocation.

Return values

ISOTP_N_OK	on success
ISOTP_NO_FREE_FILTER	if CAN device has no filters left.

isotp_recv()

int isotp_recv	(	struct isotp_recv_ctx *	rctx,
		uint8_t *	data,
		size_t	len,
		k_timeout_t	timeout
	)

#include <zephyr/canbus/isotp.h>

Read out received data from fifo.

This function reads the data from the receive FIFO of the context. It blocks if the FIFO is empty. If an error occurs, the function returns a negative number and leaves the data buffer unchanged.

Parameters

rctx	Context that is already bound.
data	Pointer to a buffer where the data is copied to.
len	Size of the buffer.
timeout	Timeout for incoming data.

Return values

Number	of bytes copied on success
ISOTP_RECV_TIMEOUT	when "timeout" timed out
ISOTP_N_*	on error

isotp_recv_net()

int isotp_recv_net	(	struct isotp_recv_ctx *	rctx,
		struct net_buf **	buffer,
		k_timeout_t	timeout
	)

#include <zephyr/canbus/isotp.h>

Get the net buffer on data reception.

This function reads incoming data into net-buffers. It blocks until the entire packet is received, BS is reached, or an error occurred. If BS was zero, the data is in a single net_buf. Otherwise, the data is fragmented in chunks of BS size. The net-buffers are referenced and must be freed with net_buf_unref after the data is processed.

Parameters

rctx	Context that is already bound.
buffer	Pointer where the net_buf pointer is written to.
timeout	Timeout for incoming data.

Return values

Remaining	data length for this transfer if BS > 0, 0 for BS = 0
ISOTP_RECV_TIMEOUT	when "timeout" timed out
ISOTP_N_*	on error

isotp_send()

int isotp_send	(	struct isotp_send_ctx *	sctx,
		const struct device *	can_dev,
		const uint8_t *	data,
		size_t	len,
		const struct isotp_msg_id *	tx_addr,
		const struct isotp_msg_id *	rx_addr,
		isotp_tx_callback_t	complete_cb,
		void *	cb_arg
	)

#include <zephyr/canbus/isotp.h>

Send data.

This function is used to send data to a peer that listens to the tx_addr. An internal work-queue is used to transfer the segmented data. Data and context must be valid until the transmission has finished. If a complete_cb is given, this function is non-blocking, and the callback is called on completion with the return value as a parameter.

Parameters

sctx	Context to store the internal states.
can_dev	The CAN device to be used for sending and receiving.
data	Data to be sent.
len	Length of the data to be sent.
rx_addr	Identifier for FC frames.
tx_addr	Identifier for outgoing frames the receiver listens on.
complete_cb	Function called on completion or NULL.
cb_arg	Argument passed to the complete callback.

Return values

ISOTP_N_OK	on success
ISOTP_N_*	on error

isotp_unbind()

void isotp_unbind

(

struct isotp_recv_ctx *

rctx

)

#include <zephyr/canbus/isotp.h>

Unbind a context from the interface.

This function removes the binding from isotp_bind. The filter is detached from the CAN device, and if a transmission is ongoing, buffers are freed. The context can be discarded safely after calling this function.

Parameters

rctx	Context that should be unbound.