sapi_dual_channel.h File Reference

"DualChannel" layer of ADR-020: wraps 1..N redundant sapi_dual_msgchannel_t links for fault-tolerant, always-send + bounded-ACK-wait delivery. More...

#include <stdint.h>
#include <stdbool.h>
#include "safeapi/redundancy/dual/sapi_dual_frames.h"
#include "safeapi/redundancy/dual/sapi_dual_msgchannel.h"
#include "safeapi/redundancy/dual/sapi_dual_types.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_channel.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_channel_t
	One sapi_dual_channel_t instance's state. Caller-owned storage; every field is private - reach it only through the functions below. More...
struct	sapi_dual_channel_config_t
	Configuration for sapi_dual_channel_init(). More...

Macros
#define	SAPI_DUAL_CHANNEL_MAX_LINKS   4U
	Maximum number of redundant links one sapi_dual_channel_t may be configured with. Fixed, not dynamic (REQ-OAL-COMMON-010).
#define	SAPI_DUAL_CHANNEL_MAX_PAYLOAD   (SAPI_DUAL_MSGCHANNEL_MAX_PAYLOAD - 4U)
	Max application payload bytes usable via sapi_dual_channel_send()/_receive() - Layer-1's own SAPI_DUAL_MSGCHANNEL_MAX_PAYLOAD minus this layer's 4-byte sapi_dual_frame_header_t.

Typedefs
typedef void(*)	sapi_dual_channel_status_callback_t(sapi_dual_channel_status_t new_status, sapi_dual_channel_status_t old_status, void *user_ctx)
	Optional callback invoked whenever sapi_dual_channel_get_status()'s value changes (ADR-020 section 2's "indicate to the user via callback if registered" requirement). Called synchronously from inside sapi_dual_channel_send() (the only place aggregate status is recomputed) - keep this fast; it is on the same call path as the send it was triggered by.

Functions
sapi_status_t	sapi_dual_channel_init (sapi_dual_channel_t *channel, const sapi_dual_channel_config_t *config)
	Initializes a sapi_dual_channel_t: initializes every configured redundant link (sapi_dual_msgchannel_init()) and starts sapi_dual_channel_get_status() at SAPI_DUAL_CHANNEL_STATUS_DOWN (no traffic has been sent/received yet).
sapi_status_t	sapi_dual_channel_send (sapi_dual_channel_t *channel, const uint8_t *payload, uint8_t payload_size, uint32_t *out_ack_link_count)
	Sends payload as a DATA frame on every configured redundant link - never gated by any negotiated state (ADR-020 section 2: the real payload traffic itself is the liveness check). For each link, waits up to config->ack_timeout_ms for that link's own ACK (matched by sequence number, not just "an ACK arrived") before moving on; a DATA or STATE frame received from the peer while waiting is still auto-ACKed/staged as a side effect, not dropped.
sapi_status_t	sapi_dual_channel_receive (sapi_dual_channel_t *channel, uint8_t *out_payload, uint8_t max_size, sapi_duration_ms_t timeout_ms, uint8_t *out_size)
	Returns the most recently staged inbound DATA frame, actively polling the configured links (each auto-ACked on arrival - see sapi_dual_channel_send()'s own doc) if none was already staged from a previous sapi_dual_channel_send() call's own incidental polling.
sapi_status_t	sapi_dual_channel_send_heartbeat (sapi_dual_channel_t *channel, uint32_t *out_ack_count)
	Sends a sapi_dual_state_frame_t (sapi_dual_frames.h) on every configured redundant link - fire-and-forget, no ACK wait (unlike sapi_dual_channel_send()'s DATA frames), matching the periodic-beacon nature of state negotiation. Intended to be called by a sapi_dual_negotiator_t, not directly by application code - see ADR-020 section 3.
sapi_status_t	sapi_dual_channel_send_state_frame (sapi_dual_channel_t *channel, sapi_dual_state_t state, bool channel_degraded, uint64_t timestamp_ms)
sapi_status_t	sapi_dual_channel_receive_state_frame (sapi_dual_channel_t *channel, sapi_duration_ms_t timeout_ms, sapi_dual_state_frame_t *out_frame)
	Returns the most recently staged inbound STATE frame, actively polling the configured links if none was already staged. Intended to be called by a sapi_dual_negotiator_t - see ADR-020 section 3.
sapi_dual_channel_status_t	sapi_dual_channel_get_status (const sapi_dual_channel_t *channel)
	Returns the aggregate connection status across every configured redundant link, as of the most recent sapi_dual_channel_send() call (ADR-020 section 2). SAPI_DUAL_CHANNEL_STATUS_DOWN before the first send.
bool	sapi_dual_channel_is_link_up (const sapi_dual_channel_t *channel, uint32_t link_index)
	Returns whether one specific configured link is currently considered up, as of the most recent sapi_dual_channel_send() call - for diagnostics/logging (e.g. which specific redundant path is the one that's down), not a safety-decision input on its own (see sapi_dual_channel_get_status() for the aggregate).

Detailed Description

"DualChannel" layer of ADR-020: wraps 1..N redundant sapi_dual_msgchannel_t links for fault-tolerant, always-send + bounded-ACK-wait delivery.

sapi_dual_channel_t has no knowledge of sapi_dual_negotiator_t (ADR-020 section 3's ownership direction: the negotiator depends on this module, not the other way around) - it exposes two independent frame flows over the same redundant links:

• sapi_dual_channel_send()/_receive(): application DATA, always sent on every configured link, each link's send waits up to config->ack_timeout_ms for that specific link's ACK before that link is counted as down for this round (ADR-020 section 2) - inbound DATA frames are auto-ACKed and staged for the next _receive() call.
• sapi_dual_channel_send_state_frame()/_receive_state_frame(): a narrower, negotiator-facing pair for fire-and-forget sapi_dual_state_frame_t beacons (sapi_dual_frames.h), sharing the same redundant links and the same DOWN/DEGRADED/FULL bookkeeping, but never counted toward or against DATA's own ACK accounting.

REQ-DUAL-CHANNEL-001: no dynamic allocation; fixed array of at most SAPI_DUAL_CHANNEL_MAX_LINKS redundant links. REQ-DUAL-CHANNEL-002: sapi_dual_channel_send() always transmits DATA on every configured link, never gated by any negotiated sapi_dual_state_t. REQ-DUAL-CHANNEL-003: aggregate status is recomputed after every send and status_callback fires only on an actual change. REQ-DUAL-CHANNEL-004: DATA and STATE frame flows share links and status bookkeeping; STATE traffic is fire-and-forget and never counted toward or against DATA's own ACK accounting. REQ-DUAL-CHANNEL-005: sapi_dual_channel_receive()/_receive_state_frame() poll every configured link on every call, never stopping early, so one link cannot starve another of its own auto-ACK. REQ-DUAL-CHANNEL-006: an inbound frame shorter than this layer's own header, or shorter than its kind's full fixed size, is reported as SAPI_STATUS_DATA_CORRUPTION.

Definition in file sapi_dual_channel.h.