Safe API Framework 0.1.0 build 384e6ae
Layered API framework for safety-related applications (ERTMS RBC reference targeting CENELEC EN 50128 SIL 4)
Loading...
Searching...
No Matches
Cross-Comparator (2-way channel comparison)

Files

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

Data Structures

struct  rte_cross_comparator_config_t
 Configuration for rte_cross_comparator_init(). More...
struct  rte_cross_comparator_storage_t
 Storage for one cross-comparator instance (opaque to caller). No dynamic memory. More...

Macros

#define RTE_CROSS_COMPARATOR_MAX_MESSAGE_SIZE   256U
 Maximum payload size rte_cross_comparator_execute() supports.

Typedefs

typedef rte_cross_comparator_storage_t rte_cross_comparator_t
 Opaque handle to a cross-comparator instance.

Functions

rte_status_t rte_cross_comparator_init (rte_cross_comparator_storage_t *storage, const rte_cross_comparator_config_t *config)
 Initializes a cross-comparator with zero registered channels.
rte_status_t rte_cross_comparator_register_channel (rte_cross_comparator_t *cmp, rte_channel_t *channel)
 Registers one already-initialized channel (channel A, then B).
rte_status_t rte_cross_comparator_execute (rte_cross_comparator_t *cmp, size_t data_size, rte_voting_result_t *result, void *out_data, size_t *out_size)
 Receives from both registered channels and compares them.
rte_status_t rte_cross_comparator_execute_buffers (rte_cross_comparator_t *cmp, const void *local_data, const void *peer_data, size_t data_size, rte_voting_result_t *result, void *out_data, size_t *out_size)
 Compares two already-in-hand data buffers directly, with the same on_disagreement-then-unconditional-safestate semantics as rte_cross_comparator_execute() - no rte_channel_t registration needed. Added per direct request as part of the RCA/OCORA compatibility initiative's Phase 2b (see docs/rca/ at the workspace root and TODO.dox): an integrator whose local/peer data already arrived through its own transport (e.g. RBC_GP's kind-multiplexed peer_channel, which carries cross-compare traffic alongside checkpoint/site-state frames on one shared link - not something a generic comparator API can transparently subsume) no longer needs to hand-wire two pure in-memory rte_channel_t "already arrived" adapters (send() that is never called, recv() that just returns a buffer) purely to satisfy rte_cross_comparator_execute()'s channel-based interface - this collapses that boilerplate to one call.
rte_status_t rte_cross_comparator_get_aggregated_health (const rte_cross_comparator_t *cmp, uint32_t *healthy_count, uint32_t *total_disagreements)
 Aggregated health across both registered channels.
rte_status_t rte_cross_comparator_destroy (rte_cross_comparator_t *cmp)
 Destroys a cross-comparator instance.

Detailed Description

Macro Definition Documentation

◆ RTE_CROSS_COMPARATOR_MAX_MESSAGE_SIZE

#define RTE_CROSS_COMPARATOR_MAX_MESSAGE_SIZE   256U

Maximum payload size rte_cross_comparator_execute() supports.

Definition at line 82 of file rte_cross_comparator.h.

Typedef Documentation

◆ rte_cross_comparator_t

typedef rte_cross_comparator_storage_t rte_cross_comparator_t

Opaque handle to a cross-comparator instance.

Definition at line 98 of file rte_cross_comparator.h.

Function Documentation

◆ rte_cross_comparator_init()

rte_status_t rte_cross_comparator_init ( rte_cross_comparator_storage_t * storage,
const rte_cross_comparator_config_t * config )

Initializes a cross-comparator with zero registered channels.

Parameters
[out]storagePre-allocated storage. Must not be NULL.
[in]configConfiguration. Must not be NULL.
Returns
RTE_STATUS_OK on success
RTE_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 rte_cross_comparator.c.

◆ rte_cross_comparator_register_channel()

rte_status_t rte_cross_comparator_register_channel ( rte_cross_comparator_t * cmp,
rte_channel_t * channel )

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

Parameters
[in]cmpCross-comparator handle. Must not be NULL and must be initialized.
[in]channelAlready rte_channel_init()'d channel. Must not be NULL.
Returns
RTE_STATUS_OK on success (first call registers A, second registers B)
RTE_STATUS_INVALID_PARAM if cmp/channel is NULL
RTE_STATUS_NOT_INITIALIZED if cmp was never initialized
RTE_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 rte_cross_comparator.c.

◆ rte_cross_comparator_execute()

rte_status_t rte_cross_comparator_execute ( rte_cross_comparator_t * cmp,
size_t data_size,
rte_voting_result_t * result,
void * out_data,
size_t * out_size )

Receives from both registered channels and compares them.

Parameters
[in]cmpCross-comparator handle. Must not be NULL, initialized, with exactly 2 channels registered.
[in]data_sizeBytes to receive/compare per channel; must be > 0 and <= RTE_CROSS_COMPARATOR_MAX_MESSAGE_SIZE.
[out]resultComparison outcome. Can be NULL.
[out]out_dataReceives channel A's data on AGREED. Can be NULL if the caller only cares about result.
[out]out_sizeBytes written to out_data. Can be NULL.
Returns
RTE_STATUS_OK if result is RTE_VOTING_AGREED
RTE_STATUS_INVALID_PARAM for a bad argument, or if fewer than 2 channels are registered
RTE_STATUS_HARDWARE_FAULT otherwise (DISAGREED/TIMEOUT/ INSUFFICIENT_QUORUM - the latter meaning one or both channels are marked unhealthy)
Postcondition
On RTE_VOTING_DISAGREED, this function invokes config->on_disagreement (if set) and then unconditionally enters config->safestate_level - it does not return unless that level is RTE_SAFESTATE_LEVEL_DEGRADED (the only level rte_safestate_enter() may return from).

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 164 of file rte_cross_comparator.c.

◆ rte_cross_comparator_execute_buffers()

rte_status_t rte_cross_comparator_execute_buffers ( rte_cross_comparator_t * cmp,
const void * local_data,
const void * peer_data,
size_t data_size,
rte_voting_result_t * result,
void * out_data,
size_t * out_size )

Compares two already-in-hand data buffers directly, with the same on_disagreement-then-unconditional-safestate semantics as rte_cross_comparator_execute() - no rte_channel_t registration needed. Added per direct request as part of the RCA/OCORA compatibility initiative's Phase 2b (see docs/rca/ at the workspace root and TODO.dox): an integrator whose local/peer data already arrived through its own transport (e.g. RBC_GP's kind-multiplexed peer_channel, which carries cross-compare traffic alongside checkpoint/site-state frames on one shared link - not something a generic comparator API can transparently subsume) no longer needs to hand-wire two pure in-memory rte_channel_t "already arrived" adapters (send() that is never called, recv() that just returns a buffer) purely to satisfy rte_cross_comparator_execute()'s channel-based interface - this collapses that boilerplate to one call.

A cross-comparator used with this function does not need rte_cross_comparator_register_channel() called on it at all - only rte_cross_comparator_init(). Mixing the two calling styles on the same rte_cross_comparator_t is allowed (this function ignores any registered channels; rte_cross_comparator_execute() ignores this function's own lack of them) but is not a pattern any current caller uses.

Parameters
[in]cmpCross-comparator handle (rte_cross_comparator_init()'d). Must not be NULL.
[in]local_dataThis side's own data. Must not be NULL.
[in]peer_dataThe counterpart's data, already received via whatever transport the caller owns. Must not be NULL.
[in]data_sizeBytes to compare; must be > 0 and <= RTE_CROSS_COMPARATOR_MAX_MESSAGE_SIZE.
[out]resultComparison outcome (always RTE_VOTING_AGREED or RTE_VOTING_DISAGREED - there is no I/O here, so TIMEOUT/INSUFFICIENT_QUORUM never occur). Can be NULL.
[out]out_dataReceives local_data on AGREED. Can be NULL.
[out]out_sizeBytes written to out_data. Can be NULL.
Returns
RTE_STATUS_OK if result is RTE_VOTING_AGREED.
RTE_STATUS_INVALID_PARAM for a bad argument.
RTE_STATUS_HARDWARE_FAULT on RTE_VOTING_DISAGREED - but see
Postcondition
: this function does not return in that case.
On RTE_VOTING_DISAGREED, identical to rte_cross_comparator_execute(): invokes config->on_disagreement (if set) and then unconditionally enters config->safestate_level.

Definition at line 224 of file rte_cross_comparator.c.

◆ rte_cross_comparator_get_aggregated_health()

rte_status_t rte_cross_comparator_get_aggregated_health ( const rte_cross_comparator_t * cmp,
uint32_t * healthy_count,
uint32_t * total_disagreements )

Aggregated health across both registered channels.

Parameters
[in]cmpCross-comparator handle. Must not be NULL.
[out]healthy_countNumber of currently-healthy registered channels (0, 1, or 2). Can be NULL.
[out]total_disagreementsRunning count of DISAGREED results. Can be NULL.
Returns
RTE_STATUS_OK on success
RTE_STATUS_INVALID_PARAM if cmp is NULL

Definition at line 251 of file rte_cross_comparator.c.

◆ rte_cross_comparator_destroy()

rte_status_t rte_cross_comparator_destroy ( rte_cross_comparator_t * cmp)

Destroys a cross-comparator instance.

Parameters
[in]cmpCross-comparator handle. May be NULL.
Returns
RTE_STATUS_OK always.
Safety:
Idempotent; safe to call with NULL.

Definition at line 292 of file rte_cross_comparator.c.