Cross-Comparator (2-way channel comparison)

Files
file	src/redundancy/cross_comparator/sapi_cross_comparator.c
	Pairwise channel comparison (ADR-025): validates parameters, receives from both registered channels, and compares them.

Data Structures
struct	sapi_cross_comparator_config_t
	Configuration for sapi_cross_comparator_init(). More...
struct	sapi_cross_comparator_storage_t
	Storage for one cross-comparator instance (opaque to caller). No dynamic memory. More...

Macros
#define	SAPI_CROSS_COMPARATOR_MAX_MESSAGE_SIZE   256U
	Maximum payload size sapi_cross_comparator_execute() supports.

Typedefs
typedef sapi_cross_comparator_storage_t	sapi_cross_comparator_t
	Opaque handle to a cross-comparator instance.

Functions
sapi_status_t	sapi_cross_comparator_init (sapi_cross_comparator_storage_t *storage, const sapi_cross_comparator_config_t *config)
	Initializes a cross-comparator with zero registered channels.
sapi_status_t	sapi_cross_comparator_register_channel (sapi_cross_comparator_t *cmp, sapi_channel_t *channel)
	Registers one already-initialized channel (channel A, then B).
sapi_status_t	sapi_cross_comparator_execute (sapi_cross_comparator_t *cmp, size_t data_size, sapi_voting_result_t *result, void *out_data, size_t *out_size)
	Receives from both registered channels and compares them.
sapi_status_t	sapi_cross_comparator_get_aggregated_health (const sapi_cross_comparator_t *cmp, uint32_t *healthy_count, uint32_t *total_disagreements)
	Aggregated health across both registered channels.
sapi_status_t	sapi_cross_comparator_destroy (sapi_cross_comparator_t *cmp)
	Destroys a cross-comparator instance.

Detailed Description

Macro Definition Documentation

SAPI_CROSS_COMPARATOR_MAX_MESSAGE_SIZE

#define SAPI_CROSS_COMPARATOR_MAX_MESSAGE_SIZE   256U

Maximum payload size sapi_cross_comparator_execute() supports.

Definition at line 59 of file sapi_cross_comparator.h.

Typedef Documentation

sapi_cross_comparator_t

typedef sapi_cross_comparator_storage_t sapi_cross_comparator_t

Opaque handle to a cross-comparator instance.

Definition at line 75 of file sapi_cross_comparator.h.

Function Documentation

sapi_cross_comparator_init()

sapi_status_t sapi_cross_comparator_init	(	sapi_cross_comparator_storage_t *	storage,
		const sapi_cross_comparator_config_t *	config )

Initializes a cross-comparator with zero registered channels.

Parameters

[out]	storage	Pre-allocated storage. Must not be NULL.
[in]	config	Configuration. Must not be NULL.

Returns

SAPI_STATUS_OK on success

SAPI_STATUS_INVALID_PARAM if storage or config is NULL

REQ-CROSSCOMPARATOR-001: No dynamic allocation; exactly 2 channel slots.

Definition at line 30 of file sapi_cross_comparator.c.

sapi_cross_comparator_register_channel()

sapi_status_t sapi_cross_comparator_register_channel	(	sapi_cross_comparator_t *	cmp,
		sapi_channel_t *	channel )

Registers one already-initialized channel (channel A, then B).

Parameters

[in]	cmp	Cross-comparator handle. Must not be NULL and must be initialized.
[in]	channel	Already sapi_channel_init()'d channel. Must not be NULL.

Returns

SAPI_STATUS_OK on success (first call registers A, second registers B)

SAPI_STATUS_INVALID_PARAM if cmp/channel is NULL

SAPI_STATUS_NOT_INITIALIZED if cmp was never initialized

SAPI_STATUS_RESOURCE_EXHAUSTED if both A and B are already registered (a 3rd call)

REQ-CROSSCOMPARATOR-002: A 3rd registration attempt is rejected without disturbing the 2 already-registered channels.

Definition at line 57 of file sapi_cross_comparator.c.

sapi_cross_comparator_execute()

sapi_status_t sapi_cross_comparator_execute	(	sapi_cross_comparator_t *	cmp,
		size_t	data_size,
		sapi_voting_result_t *	result,
		void *	out_data,
		size_t *	out_size )

Receives from both registered channels and compares them.

Parameters

[in]	cmp	Cross-comparator handle. Must not be NULL, initialized, with exactly 2 channels registered.
[in]	data_size	Bytes to receive/compare per channel; must be > 0 and <= SAPI_CROSS_COMPARATOR_MAX_MESSAGE_SIZE.
[out]	result	Comparison outcome. Can be NULL.
[out]	out_data	Receives channel A's data on AGREED. Can be NULL if the caller only cares about result.
[out]	out_size	Bytes written to out_data. Can be NULL.

Returns

SAPI_STATUS_OK if result is SAPI_VOTING_AGREED

SAPI_STATUS_INVALID_PARAM for a bad argument, or if fewer than 2 channels are registered

SAPI_STATUS_HARDWARE_FAULT otherwise (DISAGREED/TIMEOUT/ INSUFFICIENT_QUORUM - the latter meaning one or both channels are marked unhealthy)

Postcondition

On SAPI_VOTING_DISAGREED, if config->trigger_safestate_on_disagreement is true, this function does not return.

REQ-CROSSCOMPARATOR-003: Both channels must be healthy and successfully receive data_size bytes before comparison is attempted; otherwise short-circuits to TIMEOUT/INSUFFICIENT_QUORUM. REQ-CROSSCOMPARATOR-004: Uses config->compare if registered, else a full memcmp() - CRC-64 transport integrity is a separate, already- applied concern, never itself treated as the comparison.

Definition at line 96 of file sapi_cross_comparator.c.

sapi_cross_comparator_get_aggregated_health()

sapi_status_t sapi_cross_comparator_get_aggregated_health	(	const sapi_cross_comparator_t *	cmp,
		uint32_t *	healthy_count,
		uint32_t *	total_disagreements )

Aggregated health across both registered channels.

Parameters

[in]	cmp	Cross-comparator handle. Must not be NULL.
[out]	healthy_count	Number of currently-healthy registered channels (0, 1, or 2). Can be NULL.
[out]	total_disagreements	Running count of DISAGREED results. Can be NULL.

Returns

SAPI_STATUS_OK on success

SAPI_STATUS_INVALID_PARAM if cmp is NULL

Definition at line 199 of file sapi_cross_comparator.c.

sapi_cross_comparator_destroy()

sapi_status_t sapi_cross_comparator_destroy

(

sapi_cross_comparator_t *

cmp

)

Destroys a cross-comparator instance.

Parameters

[in]

cmp

Cross-comparator handle. May be NULL.

Returns

SAPI_STATUS_OK always.

Safety:

Idempotent; safe to call with NULL.

Definition at line 240 of file sapi_cross_comparator.c.