Group isotp_link¶

Transport layer of one ISO-TP connection: segmentation, flow control, timing. More...

Classes¶

Type	Name
struct	isotp_link Link state.
struct	isotp_link_config Link configuration passed to isotp_link_init .

Public Types¶

Type	Name
typedef int(*	isotp_can_write_fn Write one CAN frame to the bus.
typedef void(*	isotp_message_handler_t Handle one complete received message.
typedef void(*	isotp_result_fn Report the outcome of a transmission or a failed reception.
enum	isotp_rx_state Receiver state.
enum	isotp_tx_state Transmitter state.

Public Functions¶

Type	Name
void	isotp_link_config_default (struct isotp_link_config * config) Fill a configuration with the defaults of isotp_config.h .
int	isotp_link_init (struct isotp_link * link, const struct isotp_link_config * config) Initialize a link: copy the configuration, clear both directions.
uint32_t	isotp_link_invalid_frames (const struct isotp_link * link) Malformed frames ignored since isotp_link_init (0 for NULL).
void	isotp_link_poll (struct isotp_link * link, uint32_t now_us) Advance the timers: send the next Consecutive Frame, detect timeouts.
void	isotp_link_receive (struct isotp_link * link, const uint8_t * data, size_t length, uint32_t now_us) Process one received CAN frame addressed to this link.
int	isotp_link_rx_result (const struct isotp_link * link) N_Result of the last finished or failed reception (ISOTP_N_ERROR for NULL).
int	isotp_link_send (struct isotp_link * link, const uint8_t * payload, uint32_t length, uint32_t now_us) Start sending one message to the peer.
int	isotp_link_send_functional (const struct isotp_link * link, uint32_t can_id, const uint8_t * payload, uint32_t length) Send a Single Frame with a functional (broadcast) CAN ID.
bool	isotp_link_tx_busy (const struct isotp_link * link) True while a segmented transmission is in progress (false for NULL).
int	isotp_link_tx_result (const struct isotp_link * link) N_Result of the last finished transmission (ISOTP_N_ERROR for NULL).

Detailed Description¶

A link connects this node to one peer: it sends with the CAN ID isotp_link_config::tx_id and receives the frames the application routes to it (normally the frames with the peer's CAN ID). The link never reads a clock or touches hardware. The integrator passes every received CAN frame to isotp_link_receive, provides the frame writer isotp_can_write_fn, and calls isotp_link_poll regularly; the current time in microseconds is an argument of every call.

Transmission and reception are independent (full duplex). A complete received message is delivered to isotp_link_config::on_message; the end of a transmission is reported to isotp_link_config::on_tx_done.

A link is not thread-safe. Call isotp_link_receive and isotp_link_poll from one context (for example a CAN task, not an interrupt handler) and serialize isotp_link_send with them.

** **

Lifecycle: isotp_link_config_default, isotp_link_init.
Message flow: isotp_link_receive, isotp_link_send, isotp_link_send_functional, isotp_link_poll.
Diagnostics: isotp_link_tx_busy, isotp_link_tx_result, isotp_link_rx_result, isotp_link_invalid_frames.

Public Types Documentation¶

typedef isotp_can_write_fn¶

Write one CAN frame to the bus.

typedef int(* isotp_can_write_fn) (void *context, uint32_t can_id, const uint8_t *data, size_t length);

Parameters:

context Value of isotp_link_config::write_context.
can_id CAN identifier of the frame.
data Frame data; valid only during the call.
length Number of data bytes, 1..8.

Return value:

0 Frame queued for transmission.
ISOTP_BUSY No space in the transmit queue; the link retries a Consecutive Frame on the next isotp_link_poll.
Other Driver error: the transmission ends with ISOTP_N_ERROR.

typedef isotp_message_handler_t¶

Handle one complete received message.

typedef void(* isotp_message_handler_t) (const uint8_t *data, uint32_t length, void *context);

The data is valid only for the duration of the callback; copy what must be kept. The handler may call isotp_link_send on the same link to answer.

Parameters:

data Message bytes.
length Message length in bytes.
context Value of isotp_link_config::app_context.

typedef isotp_result_fn¶

Report the outcome of a transmission or a failed reception.

typedef void(* isotp_result_fn) (int n_result, void *context);

Parameters:

n_result ISOTP_N_* code.
context Value of isotp_link_config::app_context.

enum isotp_rx_state¶

Receiver state.

enum isotp_rx_state {
    ISOTP_RX_IDLE = 0,
    ISOTP_RX_RECEIVING
};

enum isotp_tx_state¶

Transmitter state.

enum isotp_tx_state {
    ISOTP_TX_IDLE = 0,
    ISOTP_TX_WAIT_FC,
    ISOTP_TX_SEND_CF
};

Public Functions Documentation¶

function isotp_link_config_default¶

Fill a configuration with the defaults of isotp_config.h .

void isotp_link_config_default (
    struct isotp_link_config * config
)

CAN ID 0, no writer, no callbacks, no padding (padding value 0xCC), ISOTP_DEFAULT_* flow control and timeouts.

Parameters:

config Configuration to fill; nothing happens when NULL.

function isotp_link_init¶

Initialize a link: copy the configuration, clear both directions.

int isotp_link_init (
    struct isotp_link * link,
    const struct isotp_link_config * config
)

Parameters:

link Link state to initialize.
config Configuration copied into the link.

Return value:

ISOTP_OK Link ready.
ISOTP_ERROR NULL argument, no writer, or a value out of range.

function isotp_link_invalid_frames¶

Malformed frames ignored since isotp_link_init (0 for NULL).

uint32_t isotp_link_invalid_frames (
    const struct isotp_link * link
)

function isotp_link_poll¶

Advance the timers: send the next Consecutive Frame, detect timeouts.

void isotp_link_poll (
    struct isotp_link * link,
    uint32_t now_us
)

Sends at most one Consecutive Frame per call, when the separation time has passed. Call it at least as often as the shortest STmin you want to achieve (for example from a 1 ms tick or a loop).

Parameters:

link Link state.
now_us Current time in microseconds.

function isotp_link_receive¶

Process one received CAN frame addressed to this link.

void isotp_link_receive (
    struct isotp_link * link,
    const uint8_t * data,
    size_t length,
    uint32_t now_us
)

Single Frames and the last Consecutive Frame complete a message and call the message handler. A First Frame is answered with a Flow Control frame. Malformed frames are ignored and counted; unexpected Consecutive and Flow Control frames are ignored.

Parameters:

link Link state.
data CAN frame data.
length CAN data length, 1..8.
now_us Current time in microseconds (free-running, wraps at 2^32).

function isotp_link_rx_result¶

N_Result of the last finished or failed reception (ISOTP_N_ERROR for NULL).

int isotp_link_rx_result (
    const struct isotp_link * link
)

function isotp_link_send¶

Start sending one message to the peer.

int isotp_link_send (
    struct isotp_link * link,
    const uint8_t * payload,
    uint32_t length,
    uint32_t now_us
)

A message of up to 7 bytes is sent at once as a Single Frame and reported to on_tx_done before the call returns. A longer message is copied into the link, its First Frame is sent, and the rest follows from isotp_link_poll as the receiver's flow control allows.

Parameters:

link Link state.
payload Message bytes.
length Message length, 1..ISOTP_TX_BUFFER_SIZE.
now_us Current time in microseconds.

Return value:

ISOTP_OK Message accepted.
ISOTP_BUSY A segmented transmission is in progress, or the writer is busy.
ISOTP_ERROR Invalid argument or message too long.
Other Error returned by the writer.

function isotp_link_send_functional¶

Send a Single Frame with a functional (broadcast) CAN ID.

int isotp_link_send_functional (
    const struct isotp_link * link,
    uint32_t can_id,
    const uint8_t * payload,
    uint32_t length
)

ISO 15765-2 allows only unsegmented messages with functional addressing. The frame is independent of the link's transmission state and does not call on_tx_done.

Parameters:

link Link state.
can_id Functional CAN ID.
payload Message bytes.
length Message length, 1..7.

Return value:

ISOTP_OK Frame written.
ISOTP_ERROR Invalid argument or message longer than 7 bytes.
Other Error returned by the writer.

function isotp_link_tx_busy¶

True while a segmented transmission is in progress (false for NULL).

bool isotp_link_tx_busy (
    const struct isotp_link * link
)

function isotp_link_tx_result¶

N_Result of the last finished transmission (ISOTP_N_ERROR for NULL).

int isotp_link_tx_result (
    const struct isotp_link * link
)