Transport API

Functions for creating, driving, sending through, and receiving from an ISO-TP link. More...

Data Structures
struct	IsoTpLink
	State for one independent, full-duplex ISO-TP conversation. More...

Typedefs
typedef struct IsoTpLink	IsoTpLink
	State for one independent, full-duplex ISO-TP conversation.

Functions
void	isotp_init_link (IsoTpLink *link, uint32_t sendid, uint8_t *sendbuf, uint32_t sendbufsize, uint8_t *recvbuf, uint32_t recvbufsize)
	Initialise an ISO-TP link and its caller-owned buffers.
uint8_t	isotp_get_tx_dl (const IsoTpLink *link)
	Return the effective transmit data length for a link.
void	isotp_destroy_link (IsoTpLink *link)
	Clear a link's state and callback registrations.
void	isotp_on_can_message (IsoTpLink *link, const uint8_t *data, uint8_t len)
	Process one CAN frame already routed to this link.
int	isotp_send (IsoTpLink *link, const uint8_t payload[], uint32_t size)
	Start transmitting a payload with the link's configured CAN identifier.
int	isotp_send_with_id (IsoTpLink *link, uint32_t id, const uint8_t payload[], uint32_t size)
	Start transmitting with a one-time CAN identifier override.
int	isotp_receive (IsoTpLink *link, uint8_t *payload, const uint32_t payload_size, uint32_t *out_size)
	Copy and consume one completed, non-streaming message.
void	isotp_set_tx_done_cb (IsoTpLink *link, isotp_tx_done_cb cb, void *arg)
	Register or clear the successful-transmission callback.

Detailed Description

Functions for creating, driving, sending through, and receiving from an ISO-TP link.

Typedef Documentation

IsoTpLink

typedef struct IsoTpLink IsoTpLink

State for one independent, full-duplex ISO-TP conversation.

Allocate one link for each conversation that can have independent send or receive state. Initialise it with isotp_init_link() before use and keep the object and its buffers alive for the complete lifetime of the link.

Calls that access the same link must be serialised. Applications may observe the documented status/result members and set user_send_can_arg when enabled; all other members are implementation state.

Function Documentation

isotp_destroy_link()

void isotp_destroy_link

(

IsoTpLink *

link

)

Clear a link's state and callback registrations.

No memory is freed because the library owns no allocation. The caller retains ownership of the link and both buffers. Passing NULL has no effect.

Parameters

[in,out]

link

Link to clear, or NULL.

isotp_get_tx_dl()

uint8_t isotp_get_tx_dl

(

const IsoTpLink *

link

)

Return the effective transmit data length for a link.

Parameters

[in]

link

Initialised link, or NULL.

Returns

The configured TX_DL, with 8 used as a defensive fallback for a zero-valued field; returns 0 when link is NULL.

isotp_init_link()

void isotp_init_link	(	IsoTpLink *	link,
		uint32_t	sendid,
		uint8_t *	sendbuf,
		uint32_t	sendbufsize,
		uint8_t *	recvbuf,
		uint32_t	recvbufsize )

Initialise an ISO-TP link and its caller-owned buffers.

The complete link object is cleared. Its transmit identifier is set to sendid, TX_DL is set to ISO_TP_DEFAULT_TX_DL, and receive and transmit state become idle.

Parameters

[out]	link	Link object to initialise. Must not be NULL.
[in]	sendid	CAN arbitration identifier used by isotp_send() and by Flow Control responses.
[in,out]	sendbuf	Persistent buffer into which outgoing payloads are copied. Must not be NULL when sendbufsize is nonzero.
[in]	sendbufsize	Capacity of sendbuf and therefore the maximum payload accepted for transmission.
[in,out]	recvbuf	Persistent reassembly or streaming buffer. Must not be NULL when recvbufsize is nonzero.
[in]	recvbufsize	Capacity of recvbuf. Without streaming, incoming messages larger than this are rejected.

Precondition

The link is not being used by another call.

See also

isotp_set_tx_dl()

Examples

isotp_example_callbacks.c, isotp_example_can_fd.c, isotp_example_polling.c, and isotp_example_streaming.c.

isotp_on_can_message()

void isotp_on_can_message	(	IsoTpLink *	link,
		const uint8_t *	data,
		uint8_t	len )

Process one CAN frame already routed to this link.

The application must filter arbitration identifiers before calling this function. Frames shorter than two bytes or longer than ISO_TP_MAX_CAN_FRAME_SIZE are ignored. Valid frames update receive or transmit flow-control state and may synchronously send a Flow Control frame. A registered receive callback may run before this function returns.

Parameters

[in,out]	link	Initialised link. Must not be NULL.
[in]	data	Frame payload, valid for at least len bytes. Must not be NULL.
[in]	len	CAN payload length in bytes.

Examples

isotp_example_callbacks.c, isotp_example_polling.c, and isotp_example_streaming.c.

isotp_receive()

int isotp_receive	(	IsoTpLink *	link,
		uint8_t *	payload,
		const uint32_t	payload_size,
		uint32_t *	out_size )

Copy and consume one completed, non-streaming message.

At most payload_size bytes are copied. The completed message is released even when the destination is too small, so any uncopied remainder is lost.

Parameters

[in,out]	link	Initialised link. Must not be NULL.
[out]	payload	Destination buffer. Must not be NULL.
[in]	payload_size	Capacity of payload.
[out]	out_size	Number of bytes copied. Must not be NULL.

Return values

ISOTP_RET_OK	A completed message was copied and consumed.
ISOTP_RET_NO_DATA	No complete message is available.
ISOTP_RET_ERROR	Streaming reception is active, or a receive callback is registered in a build that supports callbacks.

Examples

isotp_example_polling.c.

isotp_send()

int isotp_send	(	IsoTpLink *	link,
		const uint8_t	payload[],
		uint32_t	size )

Start transmitting a payload with the link's configured CAN identifier.

The payload is copied into the link's send buffer. A Single Frame is sent synchronously. For a segmented message, only the First Frame is sent here; isotp_poll() sends the remaining Consecutive Frames after Flow Control.

Parameters

[in,out]	link	Initialised link. Must not be NULL.
[in]	payload	Payload to copy. Must be valid for at least size bytes.
[in]	size	Payload size. It must not exceed the link's send-buffer capacity.

Return values

ISOTP_RET_OK	The Single Frame or First Frame was accepted by the driver.
ISOTP_RET_OVERFLOW	The payload exceeds the link's send buffer.
ISOTP_RET_INPROGRESS	Another segmented transmission is active.

Returns

Any other value returned by isotp_user_send_can().

Warning

ISOTP_RET_OK does not mean a segmented transmission is complete. Keep polling until the completion callback runs or send_status is no longer ISOTP_SEND_STATUS_INPROGRESS, then inspect send_protocol_result.

Examples

isotp_example_polling.c.

isotp_send_with_id()

int isotp_send_with_id	(	IsoTpLink *	link,
		uint32_t	id,
		const uint8_t	payload[],
		uint32_t	size )

Start transmitting with a one-time CAN identifier override.

Behaviour and return values are the same as isotp_send(), except id is used instead of the identifier stored in the link. This is commonly used for a functional-addressing request. ISO-TP functional requests must fit in a Single Frame; the library does not enforce that addressing rule.

Parameters

[in,out]	link	Initialised link, or NULL.
[in]	id	CAN arbitration identifier for this transmission.
[in]	payload	Payload to copy. Must be valid for at least size bytes.
[in]	size	Payload size.

Return values

ISOTP_RET_ERROR	The link is NULL.
ISOTP_RET_OK	The Single Frame or First Frame was accepted by the driver.
ISOTP_RET_OVERFLOW	The payload exceeds the link's send buffer.
ISOTP_RET_INPROGRESS	Another segmented transmission is active.

Returns

Any other value returned by isotp_user_send_can().

isotp_set_tx_done_cb()

void isotp_set_tx_done_cb	(	IsoTpLink *	link,
		isotp_tx_done_cb	cb,
		void *	arg )

Register or clear the successful-transmission callback.

A Single Frame invokes the callback synchronously from isotp_send() or isotp_send_with_id(). A segmented transmission invokes it from isotp_poll() after the final Consecutive Frame is accepted.

Parameters

[in,out]	link	Initialised link. Passing NULL has no effect.
[in]	cb	Callback to register, or NULL to disable notification.
[in]	arg	Application value passed to cb.

Examples

isotp_example_callbacks.c.