ab_gp_train.c

Go to the documentation of this file.

#include "ab_gp_train.h"
 
#include <stdio.h>
 
#include "rte/utils/buffer/rte_buffer.h"
#include "rte/utils/cast/rte_cast.h"
#include "rte/utils/lifecycle/rte_lifecycle.h"
#include "rte/oal/log/rte_log.h"
#include "rte/oal/memory/rte_mem_util.h"
#include "rte/utils/notify/rte_notify.h"
#include "ab_siteGP.h"
 
#include "../com/ab_gp_channel_payload.h" /* ab_gp_channel_payload_register_collector() - see ab_gp_train_init() below */
#include "../ertms_procedures/ab_gp_ertms_engine.h"
#include "../ertms_procedures/ab_gp_proc_session.h"
 
/* GA notification registry - module-private storage, same "static
 * singleton" convention as ab_gp_channel.c's own g_ab_ctx. See ab_gp_train.h's
 * own "GA notification" doc for why this file fires it (it owns the
 * mutations) and rte_notify.h's own doc (safeAPIFreamwork, ADR-030) for
 * the storage shape/why init/register/dispatch are hand-written. ONE list
 * (was two) - interface-simplification pass, see ab_gp_train.h's own doc. */
RTE_DECLARE_CALLBACK_LIST(ab_gp_train_context_list_t, ab_gp_train_context_notify_fn,
                               AB_GP_TRAIN_MAX_CONTEXT_SUBSCRIBERS);

static bool train_id_in_range(uint8_t train_id);
 
static ab_gp_train_context_list_t g_train_context_subscribers;
 
rte_status_t ab_gp_register_train_context_notify(ab_gp_train_context_notify_fn fn, const void *context)
{
    rte_status_t lifecycle_status;
 
    if (fn == NULL)
    {
        return RTE_STATUS_INVALID_PARAM;
    }
    lifecycle_status = rte_lifecycle_check_setup_allowed();
    if (lifecycle_status != RTE_STATUS_OK)
    {
        return lifecycle_status;
    }
    if (g_train_context_subscribers.count >= (uint32_t)AB_GP_TRAIN_MAX_CONTEXT_SUBSCRIBERS)
    {
        return RTE_STATUS_RESOURCE_EXHAUSTED;
    }
    g_train_context_subscribers.slots[g_train_context_subscribers.count].fn = fn;
    g_train_context_subscribers.slots[g_train_context_subscribers.count].context = (void *)context; /* see
        AB/GP/ma_logic/ab_gp_logic.c's own identical cast for why this is safe */
    g_train_context_subscribers.count++;
    return RTE_STATUS_OK;
}

static bool build_train_context(const ab_gp_train_session_t sessions[], const ab_gp_db_t *db, uint8_t train_id,
                                 ab_gp_train_context_t *out_ctx)
{
    uint32_t                    i;
    const ab_gp_train_session_t *s;
    const ab_gp_db_train_t      *t;
 
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    s = &sessions[train_id - 1U];
    t = &db->trains[train_id - 1U];
 
    out_ctx->train_id = train_id;
    out_ctx->in_use = s->in_use;
    out_ctx->cycle = s->cycle;
    out_ctx->d_lrbg = s->d_lrbg;
    out_ctx->nid_lrbg = t->last_nid_lrbg;
    out_ctx->v_train = s->v_train;
    out_ctx->m_mode = s->m_mode;
    out_ctx->granted_length = s->granted_length;
    out_ctx->ma_seq = s->ma_seq;
    out_ctx->ma_acked = s->ma_acked;
    out_ctx->has_ma = t->has_ma;
    out_ctx->ma_pending_send = s->ma_pending_send;
    out_ctx->ctc_connected_sent = s->ctc_connected_sent;
    out_ctx->ctc_ma_granted_sent = s->ctc_ma_granted_sent;
    out_ctx->ctc_ma_notify_pending = s->ctc_ma_notify_pending;
    uint32_t count = (t->route_count > (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN)
                     ? (uint32_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN
                     : (uint32_t)t->route_count;
    out_ctx->route_count = (uint8_t)count;
    for (i = 0U; i < count; i++)
    {
        out_ctx->route_ids[i] = t->route_ids[i];
    }
    for (; i < (uint32_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN; i++)
    {
        out_ctx->route_ids[i] = 0U;
    }
    return true;
}

static void notify_train_context(const ab_gp_train_session_t sessions[], const ab_gp_db_t *db, uint8_t train_id,
                                  ab_gp_train_update_type_t update_type)
{
    ab_gp_train_context_t ctx;
    uint32_t              i;
 
    rte_mem_set(&ctx, 0, sizeof(ctx));
    if (!build_train_context(sessions, db, train_id, &ctx))
    {
        return;
    }
    for (i = 0U; i < g_train_context_subscribers.count; i++)
    {
        if (g_train_context_subscribers.slots[i].fn != NULL)
        {
            g_train_context_subscribers.slots[i].fn(g_train_context_subscribers.slots[i].context, &ctx,
                                                       update_type);
        }
    }
}
 
void ab_gp_train_notify_context_changed(const ab_gp_train_session_t sessions[], const ab_gp_db_t *db,
                                         uint8_t train_id, ab_gp_train_update_type_t update_type)
{
    notify_train_context(sessions, db, train_id, update_type);
}
 
bool ab_gp_get_train_context(const ab_gp_train_session_t sessions[], const ab_gp_db_t *db, uint8_t train_id,
                              ab_gp_train_context_t *out_ctx)
{
    return build_train_context(sessions, db, train_id, out_ctx);
}
 
/* --- Train-domain wire codec ------------------------------------------
 * Own copy of the fixed-offset RBC envelope layout (REQ-RBC-001 revised)
 * the old shared rbc_wire.c used to own for every kind - see
 * ab_gp_train.h's own module doc for why this is now duplicated per domain
 * rather than shared. Byte-for-byte identical to ab_ga_il.c's/ab_ga_ctc.c's
 * own copies (same fixed offsets, same non-aliasing "always write every
 * field, zero if not meaningful" convention) - MUST stay that way, and
 * must stay byte-for-byte identical to SimCore's Python mirror
 * (rbc_wire.py) too, since ROUTE_ADD/CTC_* frames never pass through
 * this file at all but still share the same wire layout on other
 * channels. Only handles the kinds that ever flow over Train's own
 * dedicated relay channel (P0/M136/M24_M15/M3/M146) - a kind this file
 * does not recognize is rejected at decode, same as a genuinely
 * corrupted frame (REQ-RBC-002). */
 
#define TRAIN_WIRE_HEADER_SIZE 12U
#define TRAIN_WIRE_CONTENT_SIZE_BASE 24U
#define TRAIN_WIRE_CONTENT_SIZE_M146 (TRAIN_WIRE_CONTENT_SIZE_BASE + 4U)
#define TRAIN_WIRE_CONTENT_SIZE_M136 (TRAIN_WIRE_CONTENT_SIZE_BASE + 4U + 40U)

static uint8_t train_wire_nid_message_for_kind(rbc_msg_kind_t kind)
{
    uint8_t result;
 
    switch (kind)
    {
        case RBC_MSG_M136:
            result = 136U;
            break;
        case RBC_MSG_M3:
            result = 3U;
            break;
        case RBC_MSG_M146:
            result = 146U;
            break;
        case RBC_MSG_P0:
        case RBC_MSG_M24_M15:
        default:
            result = 0U;
            break;
    }
    return result;
}

static uint16_t train_wire_content_size_for_kind(rbc_msg_kind_t kind)
{
    uint16_t result;
 
    switch (kind)
    {
        case RBC_MSG_M146:
            result = (uint16_t)TRAIN_WIRE_CONTENT_SIZE_M146;
            break;
        case RBC_MSG_M136:
            result = (uint16_t)TRAIN_WIRE_CONTENT_SIZE_M136;
            break;
        case RBC_MSG_P0:
        case RBC_MSG_M24_M15:
        case RBC_MSG_M3:
        default:
            result = (uint16_t)TRAIN_WIRE_CONTENT_SIZE_BASE;
            break;
    }
    return result;
}

static void train_wire_encode(uint8_t out[RBC_ENVELOPE_WIRE_SIZE], const rbc_envelope_t *env)
{
    rte_buffer_t buf;
    uint16_t content_size = train_wire_content_size_for_kind(env->kind);
    uint16_t l_message = (uint16_t)(TRAIN_WIRE_HEADER_SIZE + content_size);
 
    rte_mem_set(out, 0, RBC_ENVELOPE_WIRE_SIZE);
    (void)rte_buffer_init(&buf, out, RBC_ENVELOPE_WIRE_SIZE);
    out[0] = (uint8_t)env->kind;
    out[1] = env->train_id;
    out[2] = train_wire_nid_message_for_kind(env->kind);
    out[3] = 0U; /* reserved */
    (void)rte_buffer_set_length(&buf, 4U);
    (void)rte_buffer_write_u16_le(&buf, l_message);      /* offset 4-5 */
    (void)rte_buffer_write_u16_le(&buf, 0U);              /* offset 6-7, reserved */
    (void)rte_buffer_write_u32_le(&buf, env->t_train);    /* offset 8-11 */
    (void)rte_buffer_write_u32_le(&buf, env->cycle);
    (void)rte_buffer_write_u32_le(&buf, env->d_lrbg);
    (void)rte_buffer_write_u32_le(&buf, env->msg_type);
    (void)rte_buffer_write_u32_le(&buf, env->route_len); /* not Train's own field - always 0 here, see this
                                                             * file's own header for why the offset stays */
    (void)rte_buffer_write_u32_le(&buf, env->ma_seq);
    (void)rte_buffer_write_u32_le(&buf, env->ma_length);
    (void)rte_buffer_write_u32_le(&buf, env->t_train_ack);
    (void)rte_buffer_write_u32_le(&buf, env->nid_lrbg);
    (void)rte_buffer_write_u32_le(&buf, env->q_dirlrbg);
    (void)rte_buffer_write_u32_le(&buf, env->q_dlrbg);
    (void)rte_buffer_write_u32_le(&buf, env->l_doubtover);
    (void)rte_buffer_write_u32_le(&buf, env->l_doubtunder);
    (void)rte_buffer_write_u32_le(&buf, env->q_length);
    (void)rte_buffer_write_u32_le(&buf, env->v_train);
    (void)rte_buffer_write_u32_le(&buf, env->q_dirtrain);
    (void)rte_buffer_write_u32_le(&buf, env->m_mode);
    (void)rte_buffer_write_u32_le(&buf, env->m_level);
}

static bool train_wire_decode(const uint8_t in[RBC_ENVELOPE_WIRE_SIZE], rbc_envelope_t *out_env)
{
    rte_buffer_t buf;
    rbc_envelope_t decoded;
    uint16_t l_message;
    uint16_t expected_l_message;
 
    rte_mem_set(&decoded, 0, sizeof(decoded));
    decoded.kind = (rbc_msg_kind_t)in[0];
 
    if (rte_buffer_init(&buf, (uint8_t *)in, RBC_ENVELOPE_WIRE_SIZE) != RTE_STATUS_OK)
    {
        return false;
    }
    (void)rte_buffer_set_length(&buf, RBC_ENVELOPE_WIRE_SIZE);
 
    if (rte_buffer_read_u16_le(&buf, 4U, &l_message) != RTE_STATUS_OK)
    {
        return false;
    }
    expected_l_message = (uint16_t)(TRAIN_WIRE_HEADER_SIZE + train_wire_content_size_for_kind(decoded.kind));
    if (l_message != expected_l_message)
    {
        return false;
    }
    decoded.l_message = l_message;
    decoded.nid_message = in[2];
    decoded.train_id = in[1];
 
    if ((rte_buffer_read_u32_le(&buf, 8U, &decoded.t_train) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 12U, &decoded.cycle) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 16U, &decoded.d_lrbg) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 20U, &decoded.msg_type) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 24U, &decoded.route_len) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 28U, &decoded.ma_seq) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 32U, &decoded.ma_length) != RTE_STATUS_OK))
    {
        return false;
    }
    if ((rte_buffer_read_u32_le(&buf, 36U, &decoded.t_train_ack) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 40U, &decoded.nid_lrbg) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 44U, &decoded.q_dirlrbg) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 48U, &decoded.q_dlrbg) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 52U, &decoded.l_doubtover) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 56U, &decoded.l_doubtunder) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 60U, &decoded.q_length) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 64U, &decoded.v_train) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 68U, &decoded.q_dirtrain) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 72U, &decoded.m_mode) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 76U, &decoded.m_level) != RTE_STATUS_OK))
    {
        return false;
    }
 
    *out_env = decoded;
    return true;
}
/* --- end Train-domain wire codec --------------------------------------- */

static bool train_id_in_range(uint8_t train_id)
{
    if (train_id == 0U)
    {
        return false;
    }
    return rte_cast_bounds_check((size_t)(train_id - 1U), (size_t)RTE_EXAMPLE_MAX_TRAINS) == RTE_STATUS_OK;
}

static bool nid_engine_connected_elsewhere(const ab_gp_db_t *db, uint8_t nid_engine, uint8_t exclude_train_id)
{
    uint8_t i;
 
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_TRAINS; i++)
    {
        uint8_t this_train_id = (uint8_t)(i + 1U);
 
        if ((this_train_id != exclude_train_id) && db->trains[i].connected && (db->trains[i].nid_engine == nid_engine))
        {
            return true;
        }
    }
    return false;
}
 
bool ab_gp_train_add(ab_gp_db_t *db, uint8_t train_id, uint8_t nid_engine)
{
    ab_gp_db_train_t *slot;
 
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    slot = &db->trains[train_id - 1U];
    if (slot->connected)
    {
        return false; /* already connected - ab_gp_train_remove() first to replace it */
    }
    if (nid_engine_connected_elsewhere(db, nid_engine, 0U))
    {
        return false; /* same physical train already connected in a different slot */
    }
 
    rte_mem_set(slot, 0, sizeof(*slot));
    slot->nid_engine = nid_engine;
    slot->connected = true;
    slot->has_ma = false;
    /* No notify_train_context() call here - this function has no
     * sessions[] in scope (db-level connection state only, see this
     * file's own module doc on why route_ids[]/session state are kept
     * separate). Every real caller (ab_gp_train_handle_connect(), itself
     * only reached from apply_envelope()'s P0/M136 cases) already fires
     * AB_TRAIN_REGISTERED right after calling this, where both sessions[]
     * and db are in scope. */
    return true;
}
 
bool ab_gp_train_remove(ab_gp_db_t *db, uint8_t train_id)
{
    ab_gp_db_train_t *slot;
 
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    slot = &db->trains[train_id - 1U];
    if (!slot->connected)
    {
        return false;
    }
    if (slot->route_count > 0U)
    {
        return false; /* still has routes allocated - ab_ga_il_route_unassign_train() each one first */
    }
 
    rte_mem_set(slot, 0, sizeof(*slot));
    return true;
}
 
ab_gp_db_train_t *ab_gp_train_find(ab_gp_db_t *db, uint8_t train_id)
{
    if (!train_id_in_range(train_id))
    {
        return NULL;
    }
    if (!db->trains[train_id - 1U].connected)
    {
        return NULL;
    }
    return &db->trains[train_id - 1U];
}
 
bool ab_gp_train_find_by_nid_engine(const ab_gp_db_t *db, uint8_t nid_engine, uint8_t *out_train_id)
{
    uint8_t i;
 
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_TRAINS; i++)
    {
        if (db->trains[i].connected && (db->trains[i].nid_engine == nid_engine))
        {
            if (out_train_id != NULL)
            {
                *out_train_id = (uint8_t)(i + 1U);
            }
            return true;
        }
    }
    return false;
}
 
bool ab_gp_train_is_connected(const ab_gp_db_t *db, uint8_t train_id)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    return db->trains[train_id - 1U].connected;
}
 
bool ab_gp_train_get_nid_engine(const ab_gp_db_t *db, uint8_t train_id, uint8_t *out_nid_engine)
{
    if (!ab_gp_train_is_connected(db, train_id))
    {
        return false;
    }
    *out_nid_engine = db->trains[train_id - 1U].nid_engine;
    return true;
}
 
bool ab_gp_train_get_route_count(const ab_gp_db_t *db, uint8_t train_id, uint8_t *out_route_count)
{
    if (!ab_gp_train_is_connected(db, train_id))
    {
        return false;
    }
    *out_route_count = db->trains[train_id - 1U].route_count;
    return true;
}
 
bool ab_gp_train_set_nid_engine(ab_gp_db_t *db, uint8_t train_id, uint8_t nid_engine)
{
    if (!ab_gp_train_is_connected(db, train_id))
    {
        return false;
    }
    if (nid_engine_connected_elsewhere(db, nid_engine, train_id))
    {
        return false;
    }
    db->trains[train_id - 1U].nid_engine = nid_engine;
    return true;
}
 
bool ab_gp_train_set_has_ma(ab_gp_db_t *db, uint8_t train_id, bool has_ma)
{
    if (!ab_gp_train_is_connected(db, train_id))
    {
        return false;
    }
    db->trains[train_id - 1U].has_ma = has_ma;
    /* No notify_train_context() call here (this function has no
     * sessions[] in scope - db-level state only) - a route-grant/release
     * is a multi-step sequence (granted_length/ma_seq/has_ma all change
     * together, see AB/GA/il/ab_ga_il.c's own handle_route_add()/
     * handle_route_release()), so the caller explicitly fires
     * AB_TRAIN_MA_CHANGED once, after every field is updated, via
     * ab_gp_train_notify_context_changed() (ga_interface.h) - firing
     * from each individual setter here would either fire with a
     * half-updated context or fire multiple times for one logical
     * change. */
    return true;
}
 
bool ab_gp_train_get_last_position(const ab_gp_db_t *db, uint8_t train_id, uint32_t *out_nid_lrbg)
{
    if (!ab_gp_train_is_connected(db, train_id))
    {
        return false;
    }
    *out_nid_lrbg = db->trains[train_id - 1U].last_nid_lrbg;
    return true;
}
 
bool ab_gp_train_set_last_position(ab_gp_db_t *db, uint8_t train_id, uint32_t nid_lrbg)
{
    if (!ab_gp_train_is_connected(db, train_id))
    {
        return false;
    }
    db->trains[train_id - 1U].last_nid_lrbg = nid_lrbg;
    return true;
}
 
bool ab_gp_train_handle_connect(ab_gp_db_t *db, uint8_t train_id)
{
    return ab_gp_train_add(db, train_id, train_id);
}
 
bool ab_gp_train_handle_position_report(ab_gp_db_t *db, uint8_t train_id, uint32_t nid_lrbg)
{
    if (!ab_gp_train_is_connected(db, train_id))
    {
        (void)ab_gp_train_handle_connect(db, train_id);
    }
    if (nid_lrbg == 0U)
    {
        return true; /* nothing new to record - not an error */
    }
    return ab_gp_train_set_last_position(db, train_id, nid_lrbg);
}
 
void ab_gp_train_build_position_answer(uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t cycle,
                                     uint32_t d_lrbg, uint32_t msg_type)
{
    rbc_envelope_t env;
 
    rte_mem_set(&env, 0, sizeof(env));
    env.kind = RBC_MSG_M24_M15;
    env.train_id = train_id;
    env.cycle = cycle;
    env.d_lrbg = d_lrbg;
    env.msg_type = msg_type;
    train_wire_encode(out, &env);
}
 
void ab_gp_train_build_movement_authority(uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t ma_seq,
                                        uint32_t ma_length)
{
    rbc_envelope_t env;
 
    rte_mem_set(&env, 0, sizeof(env));
    env.kind = RBC_MSG_M3;
    env.train_id = train_id;
    env.ma_seq = ma_seq;
    env.ma_length = ma_length;
    train_wire_encode(out, &env);
}

static void handle_envelope_p0(ab_gp_train_session_t *session, ab_gp_train_session_t sessions[], ab_gp_db_t *db,
                               const rbc_envelope_t *env, uint32_t cycle, rte_example_site_t site,
                               const char *role_tag)
{
    if (!session->in_use)
    {
        rte_mem_set(session, 0, sizeof(*session));
        session->in_use = true;
        session->train_id = env->train_id;
        /* Idempotent: ab_gp_train_add() itself is safe to call on an
         * already-connected slot - see its own doc. */
        (void)ab_gp_train_handle_connect(db, env->train_id);
        notify_train_context(sessions, db, env->train_id, AB_TRAIN_REGISTERED);
        RTE_EXAMPLE_LOG("[%s] cycle %u: [ONLINE] train %u connected (P0)\n", role_tag, cycle,
                             (unsigned int)env->train_id);
        rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), cycle, "Train", role_tag, "P0",
                              "connected", NULL);
    }
    else
    {
        /* DEBUG instrumentation (left in place, gated by
         * RTE_RBC_LOG_LEVEL=DEBUG) - a redundant P0 for an
         * already-connected train is a deliberate no-op (this
         * branch), NOT a session reset - see the sibling branch
         * above for the actual reset path. Logged so a
         * "did a reconnect wipe my MA" investigation can rule
         * this specific mechanism in or out from the log alone,
         * rather than re-deriving it by reading this file again. */
        rte_log_write_event(RTE_LOG_LEVEL_DEBUG, site_config_name(site), cycle, "Train", role_tag, "P0",
                              "redundant P0 for already-connected train - no-op, session untouched", NULL);
    }
}

static bool handle_envelope_m136(ab_gp_train_session_t *session, ab_gp_train_session_t sessions[], ab_gp_db_t *db,
                                 const rbc_envelope_t *env, uint32_t cycle, rte_example_site_t site,
                                 const char *role_tag, uint8_t idx, uint32_t cyc_msg_type_due[],
                                 bool cyc_position_reply_due[])
{
    uint32_t local_msg_type;
 
    if (!session->in_use)
    {
        /* Tolerate M136 arriving before/without a P0 - simple
         * first pass, lenient rather than dropping real position
         * data over a missed handshake. */
        rte_mem_set(session, 0, sizeof(*session));
        session->in_use = true;
        session->train_id = env->train_id;
        (void)ab_gp_train_handle_connect(db, env->train_id);
        notify_train_context(sessions, db, env->train_id, AB_TRAIN_REGISTERED);
    }
    /* REQ-RBC-001 (revised): records env->nid_lrbg (the real Packet 0
     * field this function's own M24/M15 decision below does not use)
     * for AB/logic's own cyclic route-connect sweep to consume - see
     * ab_gp_train_handle_position_report()'s own doc. */
    (void)ab_gp_train_handle_position_report(db, env->train_id, env->nid_lrbg);
    session->cycle = env->cycle;
    session->d_lrbg = env->d_lrbg;
    /* v_train/m_mode: on direct request, persisted now so
     * RBC_MSG_CTC_TRAIN_INFO can carry them (see that struct's
     * own doc, ab_gp_train.h) - M136 always carried these on the
     * wire, they were simply never stored anywhere before. */
    session->v_train = env->v_train;
    session->m_mode = env->m_mode;
    notify_train_context(sessions, db, env->train_id, AB_TRAIN_POSITION);
    /* Every M136 gets a plain M24 ack, unconditionally - the old
     * D_LRBG-threshold decision (below RTE_EXAMPLE_DLRBG_THRESHOLD
     * -> M24, at/above it -> M15) is retired on direct request: M15
     * was never a real Subset-026 Conditional Emergency Stop trigger
     * here, just this simulated ack picking a different message
     * kind on its own, with no operational meaning behind the
     * switch. M24 stays the position-report answer for every
     * M136 UNLESS this train has some other message actually due
     * this cycle instead - ab_gp_train_build_outputs() below already
     * sends M3 (Movement Authority) as an ADDITIONAL output when
     * session->ma_pending_send is set, alongside this M24, so that
     * case needs no special-casing here. */
    local_msg_type = RTE_EXAMPLE_MSG_M24;
    cyc_msg_type_due[idx] = local_msg_type;
    cyc_position_reply_due[idx] = true;
    session->position_reply_pending = true;
    session->position_reply_msg_type = local_msg_type;
    {
        const ab_site_balise_t *bal = ab_site_get_balise(env->nid_lrbg);
        const char *bal_name = (bal != NULL) ? bal->name : "UNKNOWN_BG";
 
        RTE_EXAMPLE_LOG("[%s] cycle %u: [ONLINE] train %u M136 NID_LRBG=%u (%s) D_LRBG=%u (its cycle %u) -> M%u\n", role_tag,
                             cycle, (unsigned int)env->train_id, (unsigned int)env->nid_lrbg, bal_name, env->d_lrbg, env->cycle, local_msg_type);
        {
            char extra[96];
            char type_buf[8];
 
            (void)snprintf(extra, sizeof(extra), "train_id=%u nid_lrbg=%u (%s) d_lrbg=%u", (unsigned int)env->train_id,
                            (unsigned int)env->nid_lrbg, bal_name, env->d_lrbg);
            (void)snprintf(type_buf, sizeof(type_buf), "M%u", local_msg_type);
            rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), cycle, "Train", role_tag, type_buf,
                                  "decision", extra);
        }
    }
    return true;
}

static void handle_envelope_m146(ab_gp_train_session_t *session, const rbc_envelope_t *env, uint32_t cycle,
                                 rte_example_site_t site, const char *role_tag)
{
    if (session->in_use && (env->ma_seq == session->ma_seq))
    {
        session->ma_acked = true;
        rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), cycle, "Train", role_tag, "M146",
                              "MA acked", NULL);
    }
}

static void handle_envelope_disconnect(ab_gp_train_session_t *session, ab_gp_train_session_t sessions[],
                                       ab_gp_db_t *db, const rbc_envelope_t *env, uint32_t cycle,
                                       rte_example_site_t site, const char *role_tag)
{
    if (session->in_use)
    {
        uint16_t held_routes[RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN];
        uint8_t  held_count = 0U;
        uint8_t  r;
 
        /* Release every route this train currently holds BEFORE
         * removing it - ab_gp_train_remove() itself refuses to
         * remove a train still holding routes (see its own doc),
         * a deliberate safety guard this disconnect path must
         * satisfy the same way any other route release would,
         * not bypass. */
        (void)ab_gp_db_train_get_routes(db, env->train_id, held_routes, &held_count);
        for (r = 0U; r < held_count; r++)
        {
            if (held_routes[r] != 0U)
            {
                (void)ab_gp_db_route_disconnect_train(db, held_routes[r]);
            }
        }
        (void)ab_gp_train_remove(db, env->train_id);
        {
            ab_gp_ertms_train_context_t *ertms_ctx = ab_gp_ertms_engine_get_train_context(env->train_id);
            if (ertms_ctx != NULL)
            {
                (void)ab_gp_proc_session_handle_termination(ertms_ctx, db);
            }
        }
        rte_mem_set(session, 0, sizeof(*session));
        notify_train_context(sessions, db, env->train_id, AB_TRAIN_REMOVED);
        RTE_EXAMPLE_LOG(
            "[%s] cycle %u: [ONLINE] train %u disconnected (released %u route(s))\n", role_tag, cycle,
            (unsigned int)env->train_id, (unsigned int)held_count);
        rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), cycle, "Train", role_tag,
                              "DISCONNECT", "removed", NULL);
    }
}
 
bool ab_gp_train_apply_envelope(ab_gp_train_session_t sessions[], ab_gp_db_t *db,
                              const uint8_t env_bytes[RBC_ENVELOPE_WIRE_SIZE], uint32_t cycle, bool is_role_a,
                              rte_example_site_t site, const char *role_tag, uint32_t cyc_msg_type_due[],
                              bool cyc_position_reply_due[])
{
    uint8_t           idx;
    ab_gp_train_session_t  *session;
    bool              have_channel_data = false;
    rbc_envelope_t    env_storage;
    const rbc_envelope_t *env = &env_storage;
 
    /* is_role_a was the M24/M15 single-channel fault-injection hook
     * (role A only inverted its decision at D_LRBG=101) - retired with
     * the M24/M15 decision itself. Kept in this public signature as a
     * natural future role-asymmetry hook. */
    (void)is_role_a;
 
    if (!train_wire_decode(env_bytes, &env_storage))
    {
        RTE_EXAMPLE_LOG("[%s] cycle %u: malformed envelope from C (Train relay)\n", role_tag, cycle);
        rte_log_write_event(RTE_LOG_LEVEL_ERROR, site_config_name(site), cycle, "C", role_tag, "ENVELOPE",
                              "malformed", NULL);
        return false;
    }
    if (!train_id_in_range(env->train_id))
    {
        RTE_EXAMPLE_LOG("[%s] cycle %u: Train relay envelope kind %d has out-of-range train_id=%u - dropping\n",
                             role_tag, cycle, (int)env->kind, (unsigned int)env->train_id);
        return false;
    }
    /* ADR-036: routing is by env->train_id - the Train relay is one
     * multiplexed link now, there is no per-train channel to cross-check
     * against. */
    idx = (uint8_t)(env->train_id - 1U);
    session = &sessions[idx];
 
    switch (env->kind)
    {
        case RBC_MSG_P0:
            handle_envelope_p0(session, sessions, db, env, cycle, site, role_tag);
            break;
        case RBC_MSG_M136:
            have_channel_data = handle_envelope_m136(session, sessions, db, env, cycle, site, role_tag, idx,
                                                     cyc_msg_type_due, cyc_position_reply_due);
            break;
        case RBC_MSG_M146:
            handle_envelope_m146(session, env, cycle, site, role_tag);
            break;
        case RBC_MSG_TRAIN_DISCONNECT:
            handle_envelope_disconnect(session, sessions, db, env, cycle, site, role_tag);
            break;
        default:
            RTE_EXAMPLE_LOG(
                "[%s] cycle %u: unexpected envelope kind %d on the Train relay channel - dropping\n", role_tag,
                cycle, (int)env->kind);
            break;
    }
    return have_channel_data;
}
 
uint8_t ab_gp_train_build_outputs(const ab_gp_train_session_t sessions[], const uint32_t cyc_msg_type_due[],
                                const bool cyc_position_reply_due[],
                                ab_gp_train_pending_output_t out[AB_GP_TRAIN_MAX_PENDING_OUTPUTS])
{
    uint8_t count = 0U;
    uint8_t i;
 
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_TRAINS; i++)
    {
        const ab_gp_train_session_t *session = &sessions[i];
        uint8_t                train_id = (uint8_t)(i + 1U);
 
        if (cyc_position_reply_due[i] || session->position_reply_pending)
        {
            uint32_t reply_type = cyc_position_reply_due[i] ? cyc_msg_type_due[i] : session->position_reply_msg_type;
            if (reply_type == 0U)
            {
                reply_type = RTE_EXAMPLE_MSG_M24;
            }
            (void)snprintf(out[count].tag, sizeof(out[count].tag), "M%u", (unsigned int)(reply_type & 0xFFU)); /* message ids fit one byte: at most 3 digits */
            out[count].index = i;
            ab_gp_train_build_position_answer(out[count].bytes, train_id, session->cycle, session->d_lrbg,
                                            reply_type);
            count++;
        }
        if (session->ma_pending_send)
        {
            rte_mem_copy(out[count].tag, "M3", 3U);
            out[count].index = i;
            ab_gp_train_build_movement_authority(out[count].bytes, train_id, session->ma_seq, session->granted_length);
            count++;
        }
    }
    return count;
}
 
/* ab_gp_train_session_get_in_use()/_get_d_lrbg()/_get_granted_length() -
 * REMOVED, see ab_gp_train.h's own comment at their old declaration. */
 
bool ab_gp_train_session_add_granted_length(ab_gp_train_session_t sessions[], uint8_t train_id, uint32_t delta)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].granted_length += delta;
    return true;
}
 
bool ab_gp_train_session_set_granted_length(ab_gp_train_session_t sessions[], uint8_t train_id, uint32_t granted_length)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].granted_length = granted_length;
    return true;
}
 
/* ab_gp_train_session_get_ma_seq() - REMOVED, same reasoning. */
 
bool ab_gp_train_session_increment_ma_seq(ab_gp_train_session_t sessions[], uint8_t train_id)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].ma_seq++;
    return true;
}
 
/* ab_gp_train_session_get_ma_pending_send() - REMOVED, same reasoning. */
 
bool ab_gp_train_session_set_ma_pending_send(ab_gp_train_session_t sessions[], uint8_t train_id, bool pending)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].ma_pending_send = pending;
    return true;
}
 
bool ab_gp_train_session_set_ma_acked(ab_gp_train_session_t sessions[], uint8_t train_id, bool acked)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].ma_acked = acked;
    return true;
}
 
/* ab_gp_train_session_get_ctc_connected_sent() - REMOVED (dead: zero
 * GP-internal callers and zero GA callers even before this pass). */
 
bool ab_gp_train_session_set_ctc_connected_sent(ab_gp_train_session_t sessions[], uint8_t train_id, bool sent)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].ctc_connected_sent = sent;
    return true;
}
 
/* ab_gp_train_session_get_ctc_ma_granted_sent() - REMOVED, same reasoning. */
 
bool ab_gp_train_session_set_ctc_ma_granted_sent(ab_gp_train_session_t sessions[], uint8_t train_id, bool sent)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].ctc_ma_granted_sent = sent;
    return true;
}
 
/* ab_gp_train_session_{get,set}_ctc_train_info_sent / _last_ctc_train_info /
 * _get_v_train_m_mode REMOVED (interface-simplification pass) - see
 * ab_gp_train_session_t's own comment at their old field location,
 * ab_gp_train.h. */
 
/* ab_gp_train_session_get_ctc_ma_notify_pending() - REMOVED, same reasoning. */
 
bool ab_gp_train_session_set_ctc_ma_notify_pending(ab_gp_train_session_t sessions[], uint8_t train_id, bool pending)
{
    if (!train_id_in_range(train_id))
    {
        return false;
    }
    sessions[train_id - 1U].ctc_ma_notify_pending = pending;
    return true;
}

static void train_sessions_collector_encode(void *context, const void *items, uint8_t *out)
{
    const ab_gp_train_session_t *sessions = (const ab_gp_train_session_t *)items;
    uint8_t                i;
 
    (void)context;
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_TRAINS; i++)
    {
        uint8_t                *slot = &out[(uint32_t)i * RTE_EXAMPLE_TRAIN_SESSION_WIRE_SIZE];
        const ab_gp_train_session_t *session = &sessions[i];
        rte_buffer_t           buf;
 
        (void)rte_buffer_init(&buf, slot, RTE_EXAMPLE_TRAIN_SESSION_WIRE_SIZE);
        slot[0] = session->in_use ? 1U : 0U;
        slot[1] = session->train_id;
        (void)rte_buffer_set_length(&buf, 2U);
        (void)rte_buffer_write_u32_le(&buf, session->cycle);
        (void)rte_buffer_write_u32_le(&buf, session->d_lrbg);
        (void)rte_buffer_write_u32_le(&buf, session->granted_length);
        (void)rte_buffer_write_u32_le(&buf, session->ma_seq);
        slot[18] = session->ma_acked ? 1U : 0U;
    }
}

static void train_sessions_collector_decode(void *context, const uint8_t *in, void *out_items)
{
    ab_gp_train_session_t *out_sessions = (ab_gp_train_session_t *)out_items;
    uint8_t           i;
 
    (void)context;
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_TRAINS; i++)
    {
        const uint8_t    *slot = &in[(uint32_t)i * RTE_EXAMPLE_TRAIN_SESSION_WIRE_SIZE];
        ab_gp_train_session_t *out_session = &out_sessions[i];
        rte_buffer_t     buf;
        uint32_t          cycle = 0U;
        uint32_t          d_lrbg = 0U;
        uint32_t          granted_length = 0U;
        uint32_t          ma_seq = 0U;
 
        rte_mem_set(out_session, 0, sizeof(*out_session));
        if (rte_buffer_init(&buf, (uint8_t *)slot, RTE_EXAMPLE_TRAIN_SESSION_WIRE_SIZE) != RTE_STATUS_OK)
        {
            continue;
        }
        (void)rte_buffer_set_length(&buf, RTE_EXAMPLE_TRAIN_SESSION_WIRE_SIZE);
        if ((rte_buffer_read_u32_le(&buf, 2U, &cycle) != RTE_STATUS_OK)
            || (rte_buffer_read_u32_le(&buf, 6U, &d_lrbg) != RTE_STATUS_OK)
            || (rte_buffer_read_u32_le(&buf, 10U, &granted_length) != RTE_STATUS_OK)
            || (rte_buffer_read_u32_le(&buf, 14U, &ma_seq) != RTE_STATUS_OK))
        {
            continue;
        }
        out_session->in_use = (slot[0] != 0U);
        out_session->train_id = slot[1];
        out_session->cycle = cycle;
        out_session->d_lrbg = d_lrbg;
        out_session->granted_length = granted_length;
        out_session->ma_seq = ma_seq;
        out_session->ma_acked = (slot[18] != 0U);
        out_session->ma_pending_send = false; /* not on the wire - see ab_gp_train_session_t's own doc */
    }
}
 
static ab_gp_channel_payload_collector_id_t g_train_payload_collector_id;
 
rte_status_t ab_gp_train_init(void)
{
    return ab_gp_channel_payload_register_collector(
        (uint32_t)RTE_EXAMPLE_MAX_TRAINS * RTE_EXAMPLE_TRAIN_SESSION_WIRE_SIZE, train_sessions_collector_encode,
        train_sessions_collector_decode, NULL, &g_train_payload_collector_id);
}
 
uint32_t ab_gp_train_payload_collector_id(void)
{
    return g_train_payload_collector_id;
}