ab_gp_channel_types.h

Go to the documentation of this file.

#ifndef RTE_EXAMPLE_AB_GP_CHANNEL_TYPES_H
#define RTE_EXAMPLE_AB_GP_CHANNEL_TYPES_H

 
#include <stdbool.h>
#include <stdint.h>
 
#include "rte/app/appmanager/rte_appmanager.h"
#include "rte/redundancy/channel_service/rte_channel_service.h"
#include "rte/redundancy/channel_link/rte_channel.h"
#include "rte/redundancy/checksum/rte_checksum.h"
#include "rte/redundancy/cross_comparator/rte_cross_comparator.h"
#include "rte/redundancy/config/rte_redundancy_config.h"
#include "rte/redundancy/dual/rte_dual_channel.h"
#include "rte/redundancy/dual/rte_dual_negotiator.h"
#include "rte/redundancy/site_role/rte_site_role.h"
#include "rte/oal/memory/rte_mem_util.h"
#include "rte/oal/netlink/rte_netlink.h"
#include "rte/utils/status/rte_status.h"
#include "rte/oal/timer/rte_timer.h"
#include "rte/utils/types/rte_types.h"
#include "rte/redundancy/voter/rte_voter.h"
#include "rte/redundancy/watchdog/rte_watchdog.h"
 
#include "../../common/rbc_wire_types.h"
#include "../../common/site_config.h"
#include "ab_gp_config.h"
#include "../db/ab_gp_db.h"
#include "../train/ab_gp_train.h"
#include "ab_gp_saf_train.h"
#include "ab_gp_util_link_gate.h"
#include "ab_gp_cycle_ticks.h"
#include "ab_gp_sibling_state.h"
 
#define AB_SAMPLE_WIRE_SIZE \
    (4U + ((uint32_t)RTE_EXAMPLE_MAX_TRAINS * RTE_EXAMPLE_TRAIN_SESSION_WIRE_SIZE) + 8U)
 
#define PEER_MSG_KIND_AB_SAMPLE          1U
#define PEER_MSG_KIND_CHECKPOINT_REQUEST 2U
#define PEER_MSG_KIND_CHECKPOINT_REPLY   3U
#define PEER_MSG_KIND_SITE_STATE         4U
#define PEER_MSG_KIND_KM114_DIGEST       5U
#define PEER_MSG_KIND_SAF_RB             6U
#define PEER_MSG_KIND_STARTUP_TS         7U
 
#define PEER_LINK_PAYLOAD_SIZE \
    ((AB_SAMPLE_WIRE_SIZE > sizeof(rte_vital_message_t)) ? AB_SAMPLE_WIRE_SIZE : sizeof(rte_vital_message_t))
 
#define PEER_WIRE_FRAME_SIZE (1U + PEER_LINK_PAYLOAD_SIZE)

#define AB_GP_DEFERRED_PEER_FRAMES 4U

#define AB_GP_STAGED_SEND_BYTES_SIZE \
    ((PEER_WIRE_FRAME_SIZE > (uint32_t)RBC_TRAIN_ENVELOPE_WIRE_SIZE) ? PEER_WIRE_FRAME_SIZE \
                                                                      : (uint32_t)RBC_TRAIN_ENVELOPE_WIRE_SIZE)

#define AB_GP_MAX_STAGED_SENDS_PER_CYCLE 16U
 
typedef enum
{
    AB_GP_STAGE_DEST_PEER = 0,
    AB_GP_STAGE_DEST_RELAY = 1,
    AB_GP_STAGE_DEST_CROSSCOMPARE = 2
} ab_gp_stage_dest_kind_t;
 
typedef struct
{
    ab_gp_stage_dest_kind_t   dest_kind;
    rte_example_relay_kind_t relay_kind;  
    uint8_t                   relay_index; 
    uint8_t                   bytes[AB_GP_STAGED_SEND_BYTES_SIZE];
    size_t                    size;
} ab_gp_staged_send_t;

typedef struct ab_gp_com_s
{
    rte_channel_service_t  peer_channel;
    rte_channel_service_t  crosscompare_channel;
    /* ADR-036: ONE relay link per {kind} (was per {kind, instance}) -
     * every train's Train/IL traffic multiplexes onto the one link and
     * A/B route by the envelope's own train_id. */
    rte_channel_service_t  relay_channel[RTE_EXAMPLE_RELAY_KIND_COUNT];
    /* ISS-020: limits the cycle thread's open attempts of relay_channel[RTE_EXAMPLE_RELAY_KIND_UTIL] while the
     * status service is unreachable (ab_gp_util_link_gate.h). Zeroed with the context in ab_gp_channel_open_link(). */
    ab_gp_util_link_gate_t util_gate;
} ab_gp_com_t;

typedef void (*ab_gp_com_envelope_cb)(void *user_ctx, rte_example_relay_kind_t kind, uint8_t index, const uint8_t *bytes);
typedef void (*ab_gp_com_peer_frame_cb)(void *user_ctx, uint8_t kind, const uint8_t *payload, size_t size);

typedef struct ab_gp_channel_context_s
{
    bool                    is_role_a;
    rte_example_site_t     site;
    char                    role_tag_buf[16];
    const char             *role_tag;
    /* RCA/OCORA Phase 8 (see docs/rca/ at the workspace root and TODO.md's
     * "RCA/OCORA compatibility" section): the resolved app-level
     * redundancy topology config, loaded once at startup
     * (ab_gp_channel_open_link()) from etc/config/redundancy.json (or
     * RTE_REDUNDANCY_CONFIG_FILE). GP validates this against what it can
     * actually run today (2oo2/2oo2_redundant, replica_count==2 only -
     * ab_gp_channel_open_link() fails fast, not silently, on anything
     * else) and logs it for visibility - not yet wired to actually change
     * how many peer channels are opened or which comparator runs (still
     * always exactly one ab-peer link + rte_cross_comparator) - that
     * remains real, not-yet-started follow-up work, see TODO.md. */
    rte_redundancy_config_t redundancy;
    /* rte_channel_config_t::name for ctx->checkpoint_vc (e.g.
     * "ChannelAtoB"/"ChannelBtoA") - a caller-owned pointer per that
     * field's own doc, so it needs storage that outlives the channel;
     * this buffer, embedded in ctx, does. Filled once by
     * ab_gp_channel_checkpoint_setup(). */
    char                    checkpoint_channel_name_buf[16];
 
    /* Transport subsystem */
    ab_gp_config_t          config;
    ab_gp_com_t             com;
 
    bool                    stop_requested;
 
    uint32_t                last_accepted_peer_cycle;
    bool                    peer_cycle_seen;
 
    rte_timestamp_ms_t     checkpoint_relaxed_until_ms;
 
    /* Inter-site site role (ADR-040): the link, negotiation, partner supervision, takeover and standby sync are
     * Platform_RTE's rte_site_role service; this channel is its Site Role Client (ab_gp_channel_negotiate.c).
     * is_online mirrors rte_site_role_is_online() (set at start and on every reported change); own_faulted and
     * single_mode are this channel's local facts, handed to the service each cycle. */
    rte_timestamp_ms_t     startup_timestamp_ms;     
    rte_timestamp_ms_t     sibling_startup_timestamp_ms; 
    bool                   have_sibling_startup_timestamp; 
    rte_site_role_t        site_role;
    uint8_t                site_role_tx[RTE_EXAMPLE_SITE_EXTRA_PAYLOAD_SIZE];
    uint8_t                site_role_rx[RTE_EXAMPLE_SITE_EXTRA_PAYLOAD_SIZE];
    char                   site_role_peer_tag[16];
 
    uint32_t                last_relay_rx_cycle;     
    uint32_t                join_window_cycles_left; 
 
    bool                    is_online;
    bool                    own_faulted;

    struct
    {
        ab_gp_train_session_t sessions[RTE_EXAMPLE_MAX_TRAINS];
        ab_gp_db_t            db;
    } neg_peer_extra;
 
 
    ab_gp_sibling_state_t   peer_site_state;       
    uint32_t                xcompare_skew_skips;   
 
    /* --- Built-in AppManager checkpoint rendezvous, jitter-tolerant path
     * (ab_gp_channel_checkpoint.c; RTE_EXAMPLE_AB_CHECKPOINT_LOOKBACK_CYCLES;
     * docs/TIMING_AND_DATA_LOSS_ANALYSIS.md finding 10) ---
     *
     * The most recent CHECKPOINT_REPLY (this side's own arrival echoed
     * back by the peer) and CHECKPOINT_REQUEST (the peer's own arrival)
     * that the per-cycle peer pump (pre_execute's on_peer_frame_received)
     * drained while ab_gp_channel_checkpoint_backend_recv() was NOT
     * blocked. Retained (a REPLY here used to be dropped) so backend_recv
     * can offer them as confirmation candidates: the REPLY carries this
     * side's id and confirms any idle cycle (constant folded signature);
     * the REQUEST carries the peer's id and confirms an active cycle when
     * both channels took the same path. A stale id is still rejected by
     * rte_checkpoint.c's reply_confirms_checkpoint(). */
    bool                    has_cached_checkpoint_reply;
    uint8_t                 cached_checkpoint_reply[sizeof(rte_vital_message_t)];
    bool                    has_cached_checkpoint_request;
    uint8_t                 cached_checkpoint_request[sizeof(rte_vital_message_t)];
 
    /* Cycle number (ctx->cyc_cycle) of the most recent CHECKPOINT_REQUEST
     * or CHECKPOINT_REPLY seen from the peer, by either the pump or
     * backend_recv's own poll. 0 = none seen yet. backend_recv treats
     * "peer exchanged a checkpoint frame within the last
     * RTE_EXAMPLE_AB_CHECKPOINT_LOOKBACK_CYCLES cycles" as this cycle's
     * confirmation when a fresh round trip did not land in-window - see
     * that constant's own doc. */
    uint32_t                last_peer_checkpoint_cycle;
 
    /* The exact rte_vital_message_t bytes backend_send() was last asked
     * to send (this cycle's own arrival, built by rte_channel_checkpoint()
     * for this cycle's checkpoint_id). backend_recv() returns these
     * verbatim to satisfy the lookback path - they verify against the
     * current checkpoint_id by construction. */
    bool                    has_last_sent_checkpoint_arrival;
    uint8_t                 last_sent_checkpoint_arrival[sizeof(rte_vital_message_t)];
 
    rte_watchdog_t         watchdog;
    bool                    single_mode;
    bool                    was_online;
    uint32_t                last_peer_sample_cycle;
 
    rte_timer_storage_t    cycle_timer_storage;
    rte_timer_handle_t     cycle_timer_handle;
    ab_gp_cycle_ticks_t     cycle_ticks;          
    rte_timestamp_ms_t      last_cycle_wall_ms;   
 
    /* Train and Route database subsystems */
    ab_gp_train_session_t   sessions[RTE_EXAMPLE_MAX_TRAINS];
    ab_gp_db_t              db;
 
    /* Checkpoint subsystem */
    void                                *checkpoint_channel_handle;
    rte_channel_t                      checkpoint_vc;
    rte_voter_t                        checkpoint_voter;
    rte_appmanager_checkpoint_config_t checkpoint_cfg;
 
    /* Cross-compare subsystem - RCA/OCORA Phase 2b: no rte_channel_t
     * "sources" needed any more, rte_cross_comparator_execute_buffers()
     * takes local/peer bytes directly (see ab_gp_channel_crosscompare.c). */
    rte_cross_comparator_t xcompare_cmp;
    uint8_t                 xcompare_skip_count[RTE_EXAMPLE_MAX_TRAINS];
    uint8_t                 adopt_pending[RTE_EXAMPLE_MAX_TRAINS]; 
 
    uint32_t                cycle;
 
    /* Per-cycle orchestration scratch */
    uint32_t                cyc_cycle;
    bool                    cyc_have_channel_data;
    bool                    cyc_have_peer_data;
    uint32_t                cyc_peer_cycle;
    ab_gp_train_session_t   cyc_peer_sessions[RTE_EXAMPLE_MAX_TRAINS];
    bool                    cyc_crc_ok;
    bool                    cyc_agree;
 
    uint32_t                cyc_msg_type_due[RTE_EXAMPLE_MAX_TRAINS];
    bool                    cyc_position_reply_due[RTE_EXAMPLE_MAX_TRAINS];
 
    /* Train-link SaF termination (ab_gp_saf_train.h); disabled unless RTE_SAFECOMM_TRAIN_RBC_ID is set. */
    ab_gp_saf_train_t       saf_train;
 
    /* Peer-link control frames (PEER_MSG_KIND_SAF_RB, PEER_MSG_KIND_KM114_DIGEST) that the checkpoint rendezvous read
     * off the shared peer link while waiting for its own frame; pre_execute replays them through the normal peer
     * handler next cycle instead of losing them. */
    uint8_t                 deferred_peer_frames[AB_GP_DEFERRED_PEER_FRAMES][PEER_WIRE_FRAME_SIZE];
    uint8_t                 deferred_peer_count;
 
    /* Stage-then-commit output queue (ADR-034) - see ab_gp_channel_stage.h */
    ab_gp_staged_send_t     staged_sends[AB_GP_MAX_STAGED_SENDS_PER_CYCLE];
    uint32_t                staged_send_count;
} ab_gp_channel_context_t;
 
void ab_gp_channel_sleep_ms(unsigned int ms);
rte_status_t ab_gp_channel_shutdown(void *context);
 
#endif /* RTE_EXAMPLE_AB_GP_CHANNEL_TYPES_H */