sai.c File Reference

Safe Application Intermediate (SAI) sub-layer, EC-counter variant (Subset-098 v4.0.0 §5.4.7/§5.4.9). More...

#include "safecomm/sai/sai.h"
#include <string.h>

Include dependency graph for sai.c:

Go to the source code of this file.

Macros
#define	SAI_MSG_EC_START   0x81U
#define	SAI_MSG_EC_DATA   0x86U
#define	SAI_HEADER_LEN   19U
#define	SAI_START_EXTRA_LEN   6U

Functions
static void	pack_u16_be (uint16_t v, uint8_t buf[2])
static uint16_t	unpack_u16_be (const uint8_t buf[2])
static void	pack_u32_be (uint32_t v, uint8_t buf[4])
static uint32_t	unpack_u32_be (const uint8_t buf[4])
static int	ec_state_from_delta (int32_t delta)
safecomm_status_t	safecomm_sai_init (safecomm_sai_conn_t *conn, safecomm_saf_conn_t *saf, const safecomm_sai_config_t *cfg)
	Initialise a SAI connection object over an already-initialised SaF connection.
safecomm_status_t	safecomm_sai_start (safecomm_sai_conn_t *conn)
	Run the EC initialisation exchange (§5.4.9.3): send our ExecutionCycleStart, wait for the peer's, and compute the EC ratio. saf must already be in DATA (its own AU1-3/AR handshake done).
safecomm_status_t	safecomm_sai_send (safecomm_sai_conn_t *conn, const uint8_t *pdu, size_t pdu_len)
	Wrap one user PDU in a SAI header (message type, sequence number, our EC counter) and send it through the underlying SaF connection.
safecomm_status_t	safecomm_sai_recv (safecomm_sai_conn_t *conn, uint8_t *out, size_t out_cap, size_t *out_len)
	Receive, unwrap and check one SAI-protected PDU.
void	safecomm_sai_tick (safecomm_sai_conn_t *conn)
	Advance our own EC by one: call this once per cfg.ec_period_ms elapsed on the caller's clock. Updates the expected-EC estimate and the freshness state (§5.4.9.4.4-7) even if no message arrived in this cycle (using the last one received).

Detailed Description

Safe Application Intermediate (SAI) sub-layer, EC-counter variant (Subset-098 v4.0.0 §5.4.7/§5.4.9).

See sai.h for what is and is not implemented.

Definition in file sai.c.

Macro Definition Documentation

SAI_MSG_EC_START

#define SAI_MSG_EC_START   0x81U

Definition at line 12 of file sai.c.

SAI_MSG_EC_DATA

#define SAI_MSG_EC_DATA   0x86U

Definition at line 13 of file sai.c.

SAI_HEADER_LEN

#define SAI_HEADER_LEN   19U

Definition at line 16 of file sai.c.

SAI_START_EXTRA_LEN

#define SAI_START_EXTRA_LEN   6U

Definition at line 17 of file sai.c.

Function Documentation

pack_u16_be()

void pack_u16_be ( uint16_t v, uint8_t buf[2] )

static

Definition at line 19 of file sai.c.

unpack_u16_be()

uint16_t unpack_u16_be ( const uint8_t buf[2] )

static

Definition at line 25 of file sai.c.

pack_u32_be()

void pack_u32_be ( uint32_t v, uint8_t buf[4] )

static

Definition at line 30 of file sai.c.

unpack_u32_be()

uint32_t unpack_u32_be ( const uint8_t buf[4] )

static

Definition at line 38 of file sai.c.

ec_state_from_delta()

int ec_state_from_delta ( int32_t delta )

static

Definition at line 44 of file sai.c.

safecomm_sai_init()

safecomm_status_t safecomm_sai_init	(	safecomm_sai_conn_t *	conn,
		safecomm_saf_conn_t *	saf,
		const safecomm_sai_config_t *	cfg )

Initialise a SAI connection object over an already-initialised SaF connection.

Parameters

conn	caller-allocated, will be fully overwritten. Non-NULL.
saf	the underlying SaF connection (kept by reference; not copied, not owned). Non-NULL.
cfg	static configuration, copied. Non-NULL.

Returns

SAFECOMM_STATUS_OK / _INVALID_PARAM.

Definition at line 52 of file sai.c.

safecomm_sai_start()

safecomm_status_t safecomm_sai_start

(

safecomm_sai_conn_t *

conn

)

Run the EC initialisation exchange (§5.4.9.3): send our ExecutionCycleStart, wait for the peer's, and compute the EC ratio. saf must already be in DATA (its own AU1-3/AR handshake done).

Parameters

conn	an initialised SAI connection. Non-NULL.

Returns

SAFECOMM_STATUS_OK, or whatever the underlying safecomm_saf_send/recv returned on failure.

Definition at line 73 of file sai.c.

safecomm_sai_send()

safecomm_status_t safecomm_sai_send	(	safecomm_sai_conn_t *	conn,
		const uint8_t *	pdu,
		size_t	pdu_len )

Wrap one user PDU in a SAI header (message type, sequence number, our EC counter) and send it through the underlying SaF connection.

Parameters

conn	a started SAI connection. Non-NULL.
pdu	user bytes. Non-NULL when pdu_len > 0.
pdu_len	length of pdu.

Returns

SAFECOMM_STATUS_OK, or whatever safecomm_saf_send() returned.

Definition at line 127 of file sai.c.

safecomm_sai_recv()

safecomm_status_t safecomm_sai_recv	(	safecomm_sai_conn_t *	conn,
		uint8_t *	out,
		size_t	out_cap,
		size_t *	out_len )

Receive, unwrap and check one SAI-protected PDU.

Parameters

conn	a started SAI connection. Non-NULL.
out	destination for the user bytes. Non-NULL.
out_cap	capacity of out.
out_len	receives the user-byte count. Non-NULL.

Returns

SAFECOMM_STATUS_OK; SAFECOMM_STATUS_SEQ_ERROR if the SAI sequence number is outside the accepted window (§5.4.7.2); SAFECOMM_STATUS_TIMEOUT if the EC freshness check reaches the alarm state (§5.4.9.4.7); SAFECOMM_STATUS_STATE for anything that isn't an EC-protected data message; otherwise whatever safecomm_saf_recv() returned. None of these release the underlying SaF connection — that stays the caller's decision (§5.4.10.1.4-6: a configurable number of successive errors before releasing, which is a policy this module leaves to its caller).

Definition at line 156 of file sai.c.

safecomm_sai_tick()

void safecomm_sai_tick

(

safecomm_sai_conn_t *

conn

)

Advance our own EC by one: call this once per cfg.ec_period_ms elapsed on the caller's clock. Updates the expected-EC estimate and the freshness state (§5.4.9.4.4-7) even if no message arrived in this cycle (using the last one received).

Parameters

conn	a started SAI connection. Non-NULL.

Definition at line 213 of file sai.c.