sapi_dual_msgchannel.h File Reference

"Channel" layer of ADR-020: one EN 50159-defended message channel over one already-open sapi_netlink_handle_t. More...

#include <stdint.h>
#include "safeapi/redundancy/checksum/sapi_checksum.h"
#include "safeapi/oal/netlink/sapi_netlink.h"
#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"

Include dependency graph for sapi_dual_msgchannel.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sapi_dual_msgchannel_t
	One sapi_dual_msgchannel_t instance's state. Caller-owned storage (REQ-DUAL-MSGCHANNEL-001); opaque in practice, exposed here (not via SAFEAPI_DECLARE_STORAGE) only because its size is already small and fixed - callers must still treat every field as private and only reach it through the functions below. More...
struct	sapi_dual_msgchannel_config_t
	Configuration for sapi_dual_msgchannel_init(). More...

Macros
#define	SAPI_DUAL_MSGCHANNEL_MAX_PAYLOAD   248U
	Max payload bytes usable via sapi_dual_msgchannel_send()/ _receive() - bounded by sapi_vital_message_t's own fixed 248-byte payload field (sapi_checksum.h).

Functions
sapi_status_t	sapi_dual_msgchannel_init (sapi_dual_msgchannel_t *channel, const sapi_dual_msgchannel_config_t *config)
	Initializes a sapi_dual_msgchannel_t: starts both sequence counters at 0.
sapi_status_t	sapi_dual_msgchannel_send (sapi_dual_msgchannel_t *channel, const uint8_t *payload, uint8_t payload_size, sapi_duration_ms_t timeout_ms, uint32_t *out_sequence)
	Wraps payload in a sapi_vital_message_t (this channel's own sender_id and next sequence_number) and sends it over config->link, blocking at most timeout_ms.
sapi_status_t	sapi_dual_msgchannel_receive (sapi_dual_msgchannel_t *channel, uint8_t *out_payload, uint8_t payload_max_size, sapi_duration_ms_t timeout_ms, uint8_t *out_payload_size, uint32_t *out_sequence)
	Receives one frame over config->link, blocking at most timeout_ms, verifies its CRC-64 and sequence continuity (sapi_checksum_vital_message_verify() against channel->expected_sequence) and its sender_id against config->expected_peer_id, and extracts the payload.
sapi_status_t	sapi_dual_msgchannel_reset_sequence (sapi_dual_msgchannel_t *channel)
	Resets both sequence counters to 0. Intended to be called by the caller (typically sapi_dual_channel_t) exactly once, immediately after config->link has been freshly (re)established with the peer - mirrors safeAPIRBC2oo2's own precedent (channel_ab.c's cycle_resync_requested handling after a peer link reconnects) for why a fresh link needs a fresh, mutually agreed starting sequence rather than fighting over whatever counters were left over from before the disconnect.

Detailed Description

"Channel" layer of ADR-020: one EN 50159-defended message channel over one already-open sapi_netlink_handle_t.

Every frame sent/received is a sapi_vital_message_t (sapi_checksum.h - already the framework's established EN 50159-style envelope, reused here rather than reinvented, the same way sapi_channel_checkpoint() (ADR-017) already reuses it): sequence_number defends against repetition/deletion/resequencing, sender_id (checked against config->expected_peer_id on receive) defends against masquerade, timestamp_ms supports delay/staleness detection by the caller, and crc64 defends against corruption. See ADR-020 section 1.

This is the lower of the two protocol layers ADR-020 defines - sapi_dual_channel_t (sapi_dual_channel.h) is the upper layer, adding its own DATA/ACK/STATE frame-kind header inside this layer's payload and redundant-link fan-out on top of a single sapi_dual_msgchannel_t like this one.

REQ-DUAL-MSGCHANNEL-001: no dynamic allocation; caller supplies storage and an already-open sapi_netlink_handle_t. REQ-DUAL-MSGCHANNEL-002: send/receive never block longer than the caller-supplied timeout_ms. REQ-DUAL-MSGCHANNEL-003: sapi_checksum_crc64_init() must already have been called by the application before any sapi_dual_msgchannel_* call (module-global singleton state, ADR-020 does not re-init it). REQ-DUAL-MSGCHANNEL-004: sender_id is checked against config->expected_peer_id before CRC/sequence verification; a mismatch is rejected with SAPI_STATUS_HARDWARE_FAULT without advancing expected_sequence (masquerade defense). REQ-DUAL-MSGCHANNEL-005: a CRC or sequence-continuity failure yields SAPI_STATUS_DATA_CORRUPTION and leaves expected_sequence unchanged.

Definition in file sapi_dual_msgchannel.h.