ab_ga_il.c

Go to the documentation of this file.

#include "ab_ga_il.h"
 
#include <stdio.h>
#include "rte/oal/memory/rte_mem_util.h"
#include "rte/utils/buffer/rte_buffer.h"
#include "rte/utils/cast/rte_cast.h"
#include "rte/oal/log/rte_log.h"
#include "ga_interface.h" /* ab_gp_db_*()/ab_gp_train_*() - bare calls now, see that file's own doc */
#include "ab_ga_il_wire.h"  /* dedicated IL messages 25/26/27 - decode + validation */
#include "ab_ga_route_fsm.h" /* per-route state machine driven by RBC_MSG_IL_ROUTE_CMD */
 
/* Fixed-offset RBC envelope wire sizes for IL domain (REQ-RBC-001) */
#define IL_WIRE_HEADER_SIZE 12U
#define IL_WIRE_CONTENT_SIZE_ROUTE_ADD 24U
#define IL_WIRE_CONTENT_SIZE_ROUTE_IDENTITY (RBC_ENVELOPE_WIRE_SIZE - IL_WIRE_HEADER_SIZE)

typedef struct
{
    uint8_t  train_id;      /* slot id (== nid_engine in this simplified model), 0 = none */
    uint16_t route_id;
    uint32_t start_signal;
    uint32_t end_signal;
    uint32_t route_status;  /* rbc_route_status_t - NO_TRAIN / TRAIN_IN_ROUTE */
    bool     train_has_ma;  /* connected train has an MA reaching into this route */
    uint8_t  fsm_state;     /* ab_ga_route_state_t - the RBC's acknowledged per-route state */
    bool     fsm_is_stub;   /* fsm_state is a not-yet-implemented OS/SH/DEGRADED stub */
} il_pending_route_event_t;
 
static bool route_fsm_state_is_stub(uint8_t s)
{
    return (s == (uint8_t)AB_GA_ROUTE_STATE_OS) || (s == (uint8_t)AB_GA_ROUTE_STATE_SH)
        || (s == (uint8_t)AB_GA_ROUTE_STATE_DEGRADED);
}
 
static il_pending_route_event_t g_pending_route_events[AB_GP_IL_MAX_PENDING_OUTPUTS];
static uint8_t                  g_pending_route_event_count = 0U;

static rbc_il_status_t g_il_status = RBC_IL_STATUS_DOWN;
 
static bool il_wire_decode(const uint8_t in[RBC_ENVELOPE_WIRE_SIZE], rbc_envelope_t *out_env);
static void il_wire_encode(uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t start_signal,
                             uint32_t end_signal, uint32_t route_status);
static bool handle_route_add(ab_gp_db_t *db, const rbc_envelope_t *env, uint32_t cycle, rte_example_site_t site,
                              const char *role_tag);
static bool handle_route_release(ab_gp_db_t *db, const rbc_envelope_t *env, uint32_t cycle, rte_example_site_t site,
                                  const char *role_tag);
static bool handle_route_status_report(const rbc_envelope_t *env, uint32_t cycle, const char *role_tag);
static bool handle_il_route_cmd(ab_gp_db_t *db, const ab_ga_il_route_cmd_t *cmd, uint32_t cycle,
                                 rte_example_site_t site, const char *role_tag);
static bool handle_il_status(const ab_ga_il_status_msg_t *st, uint32_t cycle, const char *role_tag);
static void enqueue_pending_route_event(uint8_t train_id, uint16_t route_id, uint32_t start_signal,
                                          uint32_t end_signal, uint32_t route_status, bool train_has_ma,
                                          uint8_t fsm_state);
/* il_on_route_connected/_disconnected forward decls REMOVED -
 * ab_ga_il_on_route_context_changed() below is now the ONE public
 * function GA's dispatch module calls, not two GP-registered callbacks -
 * see this file's own module doc. */
 
bool ab_ga_il_site_has_route(uint16_t route_id, const ab_site_ga_route_layout_t **out_layout)
{
    size_t i;
 
    if (route_id == 0U)
    {
        return false;
    }
    for (i = 0U; i < ab_site_ga_track_layout_count; i++)
    {
        if (ab_site_ga_track_layout[i].id == route_id)
        {
            if (out_layout != NULL)
            {
                *out_layout = &ab_site_ga_track_layout[i];
            }
            return true;
        }
    }
    return false;
}
 
bool ab_ga_il_site_has_route_by_signals(uint16_t start_signal, uint16_t end_signal,
                                          const ab_site_ga_route_layout_t **out_layout)
{
    size_t i;
 
    for (i = 0U; i < ab_site_ga_track_layout_count; i++)
    {
        if ((ab_site_ga_track_layout[i].start_signal == start_signal)
            && (ab_site_ga_track_layout[i].end_signal == end_signal))
        {
            if (out_layout != NULL)
            {
                *out_layout = &ab_site_ga_track_layout[i];
            }
            return true;
        }
    }
    return false;
}
 
bool ab_ga_il_route_verify(uint16_t route_id, uint16_t start_signal, uint16_t end_signal)
{
    const ab_site_ga_route_layout_t *layout = NULL;
 
    if (!ab_ga_il_site_has_route(route_id, &layout))
    {
        return false;
    }
    return (layout->start_signal == start_signal) && (layout->end_signal == end_signal);
}
 
bool ab_ga_il_route_add(ab_gp_db_t *db, uint16_t route_id, uint16_t start_signal, uint16_t end_signal)
{
    if (!ab_ga_il_route_verify(route_id, start_signal, end_signal))
    {
        return false;
    }
    return ab_gp_db_route_add(db, route_id, start_signal, end_signal);
}
 
bool ab_ga_il_route_remove(ab_gp_db_t *db, uint16_t route_id)
{
    return ab_gp_db_route_remove(db, route_id);
}
 
bool ab_ga_il_route_set_status(ab_gp_db_t *db, uint16_t route_id, ab_gp_db_route_il_status_t status)
{
    return ab_gp_db_route_set_status(db, route_id, status);
}
 
bool ab_ga_il_route_set_type(ab_gp_db_t *db, uint16_t route_id, uint32_t route_type)
{
    return ab_gp_db_route_set_type(db, route_id, route_type);
}
 
bool ab_ga_il_route_assign_train(ab_gp_db_t *db, uint16_t route_id, uint8_t train_id)
{
    return ab_gp_db_route_connect_train(db, route_id, train_id);
}
 
bool ab_ga_il_route_unassign_train(ab_gp_db_t *db, uint16_t route_id)
{
    return ab_gp_db_route_disconnect_train(db, route_id);
}
 
bool ab_ga_il_handle_route_add(ab_gp_db_t *db, uint8_t train_id)
{
    return ab_gp_train_set_has_ma(db, train_id, true);
}
 
bool ab_ga_il_apply_envelope(const void *context, ab_gp_train_session_t *sessions, ab_gp_db_t *db,
                              const uint8_t env_bytes[RBC_ENVELOPE_WIRE_SIZE], uint32_t cycle,
                              rte_example_site_t site, const char *role_tag)
{
    rbc_envelope_t   env_storage;
    const rbc_envelope_t *env = &env_storage;
 
    (void)context;  /* unused - matches ab_gp_il_envelope_handler_fn's own signature so this
                      * function can be registered directly, no trampoline needed - see this
                      * file's own header doc */
    (void)sessions; /* unused now - handle_route_add()/handle_route_release() no longer touch
                      * train sessions directly (moved to ab_ga_il_on_route_context_changed(),
                      * see that function's own doc) - kept in this signature only because it's
                      * part of ab_gp_il_envelope_handler_fn's own required shape. */
 
    /* Dedicated IL messages (25/26/27) have their own packed layout, NOT
     * the shared rbc_envelope_t il_wire_decode() understands - route them
     * on the raw kind byte before the legacy decode. */
    switch (env_bytes[0])
    {
        case (uint8_t)RBC_MSG_IL_ROUTE_CMD:
        {
            ab_ga_il_route_cmd_t cmd;
            if (!ab_ga_il_wire_decode_route_cmd(env_bytes, &cmd))
            {
                rte_log_write_event(RTE_LOG_LEVEL_ERROR, site_config_name(site), cycle, "C", role_tag,
                                      "IL_ROUTE_CMD", "malformed or out-of-range", NULL);
                return false;
            }
            return handle_il_route_cmd(db, &cmd, cycle, site, role_tag);
        }
        case (uint8_t)RBC_MSG_IL_STATUS:
        {
            ab_ga_il_status_msg_t st;
            if (!ab_ga_il_wire_decode_status(env_bytes, &st))
            {
                rte_log_write_event(RTE_LOG_LEVEL_ERROR, site_config_name(site), cycle, "C", role_tag,
                                      "IL_STATUS", "malformed or out-of-range", NULL);
                return false;
            }
            return handle_il_status(&st, cycle, role_tag);
        }
        default:
            break; /* fall through to the legacy flat-envelope path */
    }
 
    if (!il_wire_decode(env_bytes, &env_storage))
    {
        RTE_EXAMPLE_LOG("[%s] cycle %u: malformed or unexpected-kind envelope from C (IL 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;
    }
 
    switch (env->kind)
    {
        case RBC_MSG_ROUTE_ADD:
            return handle_route_add(db, env, cycle, site, role_tag);
        case RBC_MSG_ROUTE_RELEASE:
            return handle_route_release(db, env, cycle, site, role_tag);
        case RBC_MSG_ROUTE_STATUS_REPORT:
            return handle_route_status_report(env, cycle, role_tag);
        default:
            RTE_EXAMPLE_LOG("[%s] cycle %u: IL relay envelope kind %d unexpected - dropping\n", role_tag, cycle,
                                 (int)env->kind);
            return false;
    }
}
 
uint8_t ab_ga_il_build_outputs(ab_gp_il_pending_output_t out[AB_GP_IL_MAX_PENDING_OUTPUTS])
{
    uint8_t events = g_pending_route_event_count;
    uint8_t i;
    uint8_t oi = 0U;
 
    for (i = 0U; i < events; i++)
    {
        const il_pending_route_event_t *event = &g_pending_route_events[i];
        const bool train_in_route = (event->route_status == (uint32_t)RBC_ROUTE_STATUS_TRAIN_IN_ROUTE);
        ab_ga_il_route_indication_t ind;
        uint8_t relay_index = (event->train_id > 0U) ? (uint8_t)(event->train_id - 1U) : 0U;
 
        /* Frame 1: legacy TRAIN_POSITION_IN_ROUTE - unchanged wire shape,
         * kept for the existing liveness-first Robot flow. */
        il_wire_encode(out[oi].bytes, event->train_id, event->start_signal, event->end_signal, event->route_status);
        (void)snprintf(out[oi].tag, sizeof(out[oi].tag), "TRAIN_POS_ROUTE"); /* fits tag[16]; the old 18-char label was silently cut */
        out[oi].index = relay_index;
        oi++;
 
        /* Frame 2: RBC_MSG_IL_ROUTE_INDICATION - the richer field set.
         * emergency_in_route / emergency_type are not wired yet (no
         * per-route emergency tracking) - always "none" for now. */
        ind.route_id                   = (int32_t)event->route_id;
        ind.start_signal               = (int32_t)event->start_signal;
        ind.end_signal                 = (int32_t)event->end_signal;
        ind.allocated_train_nid_engine = train_in_route ? (int32_t)event->train_id : -1;
        ind.train_in_route             = train_in_route;
        ind.train_has_ma_in_route      = event->train_has_ma;
        ind.emergency_in_route         = false;
        ind.emergency_type             = RBC_IL_EMERGENCY_TYPE_NONE;
        ind.route_fsm_state            = event->fsm_state;
        ind.route_fsm_is_stub          = event->fsm_is_stub;
        ab_ga_il_wire_encode_route_indication(out[oi].bytes, &ind);
        (void)snprintf(out[oi].tag, sizeof(out[oi].tag), "IL_ROUTE_IND");
        out[oi].index = relay_index;
        oi++;
    }
    return oi;
}
 
void ab_ga_il_confirm_outputs_sent(void)
{
    g_pending_route_event_count = 0U;
}
 
/* ab_ga_il_init() REMOVED - its entire body was two GP registrations,
 * both now owned by ab_ga_dispatch.c's own single subscription (see this
 * file's own module doc and ab_ga_dispatch.h). */

static bool il_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;
    const uint16_t expected_l_message =
        (uint16_t)(IL_WIRE_HEADER_SIZE + IL_WIRE_CONTENT_SIZE_ROUTE_IDENTITY);
    bool is_route_add;
    bool is_route_status_report;
 
    is_route_add = (in[0] == (uint8_t)RBC_MSG_ROUTE_ADD);
    is_route_status_report = (in[0] == (uint8_t)RBC_MSG_ROUTE_STATUS_REPORT);
    if (!is_route_add && !is_route_status_report && (in[0] != (uint8_t)RBC_MSG_ROUTE_RELEASE))
    {
        return false;
    }
    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;
    }
    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, 80U, &decoded.start_signal) != RTE_STATUS_OK)
        || (rte_buffer_read_u32_le(&buf, 84U, &decoded.end_signal) != RTE_STATUS_OK))
    {
        return false;
    }
    if (is_route_status_report)
    {
        /* Same offset TRAIN_POSITION_IN_ROUTE's own il_wire_encode() writes
         * route_status at (92U, after start_signal@80/end_signal@84 and a
         * zero-padding u32 at 88 where ROUTE_ADD's route_type lives instead) -
         * this is IL originating the SAME wire shape in the OTHER direction. */
        if (rte_buffer_read_u32_le(&buf, 92U, &decoded.route_status) != RTE_STATUS_OK)
        {
            return false;
        }
    }
    if (is_route_add)
    {
        if ((rte_buffer_read_u32_le(&buf, 24U, &decoded.route_len) != RTE_STATUS_OK)
            || (rte_buffer_read_u32_le(&buf, 88U, &decoded.route_type) != RTE_STATUS_OK))
        {
            return false;
        }
    }
 
    *out_env = decoded;
    return true;
}

static void il_wire_encode(uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t start_signal,
                             uint32_t end_signal, uint32_t route_status)
{
    rte_buffer_t buf;
    uint16_t l_message = (uint16_t)(IL_WIRE_HEADER_SIZE + IL_WIRE_CONTENT_SIZE_ROUTE_IDENTITY);
 
    rte_mem_set(out, 0, RBC_ENVELOPE_WIRE_SIZE);
    (void)rte_buffer_init(&buf, out, RBC_ENVELOPE_WIRE_SIZE);
    out[0] = (uint8_t)RBC_MSG_TRAIN_POSITION_IN_ROUTE;
    out[1] = train_id;
    out[2] = 0U;
    out[3] = 0U;
    (void)rte_buffer_set_length(&buf, 4U);
    (void)rte_buffer_write_u16_le(&buf, l_message);
    (void)rte_buffer_write_u16_le(&buf, 0U);
    (void)rte_buffer_write_u32_le(&buf, 0U);
    (void)rte_buffer_set_length(&buf, 80U);
    (void)rte_buffer_write_u32_le(&buf, start_signal);
    (void)rte_buffer_write_u32_le(&buf, end_signal);
    (void)rte_buffer_write_u32_le(&buf, 0U);
    (void)rte_buffer_write_u32_le(&buf, route_status);
}

static bool handle_route_add(ab_gp_db_t *db, const rbc_envelope_t *env, uint32_t cycle, rte_example_site_t site,
                              const char *role_tag)
{
    const ab_site_ga_route_layout_t *layout = NULL;
 
    if (!ab_ga_il_site_has_route_by_signals((uint16_t)env->start_signal, (uint16_t)env->end_signal, &layout))
    {
        RTE_EXAMPLE_LOG(
            "[%s] cycle %u: ROUTE_ADD for unknown route (start_signal=%u end_signal=%u) - dropping\n", role_tag,
            cycle, (unsigned int)env->start_signal, (unsigned int)env->end_signal);
        rte_log_write_event(RTE_LOG_LEVEL_ERROR, site_config_name(site), cycle, "IL", role_tag, "ROUTE_ADD",
                              "unknown route", NULL);
        return false;
    }
    if (!ab_gp_db_route_exists(db, layout->id))
    {
        (void)ab_ga_il_route_add(db, layout->id, layout->start_signal, layout->end_signal);
    }
    (void)ab_ga_il_route_set_type(db, layout->id, env->route_type);
 
    RTE_EXAMPLE_LOG("[%s] cycle %u: [ONLINE] route %u tracked (type=%u) - MA grant awaits GP's own "
                         "position-based connect\n",
                         role_tag, cycle, (unsigned int)layout->id, (unsigned int)env->route_type);
    rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), cycle, "IL", role_tag, "ROUTE_ADD", "tracked",
                          NULL);
    return true;
}

static bool handle_route_release(ab_gp_db_t *db, const rbc_envelope_t *env, uint32_t cycle,
                                  rte_example_site_t site, const char *role_tag)
{
    const ab_site_ga_route_layout_t *layout = NULL;
    ab_gp_route_context_t rctx;
 
    if (!ab_ga_il_site_has_route_by_signals((uint16_t)env->start_signal, (uint16_t)env->end_signal, &layout))
    {
        RTE_EXAMPLE_LOG(
            "[%s] cycle %u: ROUTE_RELEASE for unknown route (start_signal=%u end_signal=%u) - dropping\n", role_tag,
            cycle, (unsigned int)env->start_signal, (unsigned int)env->end_signal);
        rte_log_write_event(RTE_LOG_LEVEL_ERROR, site_config_name(site), cycle, "IL", role_tag, "ROUTE_RELEASE",
                              "unknown route", NULL);
        return false;
    }
    if (!ab_gp_db_route_exists(db, layout->id))
    {
        RTE_EXAMPLE_LOG("[%s] cycle %u: ROUTE_RELEASE for route %u - not tracked, acknowledging noTrain\n", role_tag,
                             cycle, (unsigned int)layout->id);
        /* No train is genuinely known for an untracked route - 0, not
         * env->train_id (see this function's own doc). */
        enqueue_pending_route_event(0U, layout->id, layout->start_signal, layout->end_signal, (uint32_t)RBC_ROUTE_STATUS_NO_TRAIN, false, (uint8_t)AB_GA_ROUTE_STATE_NO_ROUTE);
        return true;
    }
    /* used_in_ma read now via ab_gp_db_get_route_context() - the
     * individual _get_used_in_ma() getter this used to call is gone
     * (later session, on direct request). */
    (void)ab_gp_db_get_route_context(db, layout->id, &rctx);
    if (rctx.used_in_ma)
    {
        /* Fires AB_ROUTE_DISCONNECTED synchronously (GP's own
         * ab_gp_db_route_disconnect_train(), notify_route_context()) -
         * ab_ga_il_on_route_context_changed() does the MA shrink/zero AND
         * its own enqueue_pending_route_event(), using the route's own
         * real (pre-clear) train_id - nothing further needed here. */
        (void)ab_ga_il_route_unassign_train(db, layout->id);
    }
    else
    {
        enqueue_pending_route_event(0U, layout->id, layout->start_signal, layout->end_signal, (uint32_t)RBC_ROUTE_STATUS_NO_TRAIN, false, (uint8_t)AB_GA_ROUTE_STATE_NO_ROUTE);
    }
    (void)ab_ga_il_route_remove(db, layout->id);
    /* Distinct from "released" below (train association dropped): this
     * marks the DB entry itself gone (ab_ga_il_route_remove(), just
     * above) - on direct request, "removing" is its own logged fact,
     * not folded silently into the release line. */
    RTE_EXAMPLE_LOG("[%s] cycle %u: route %u removed from DB\n", role_tag, cycle, (unsigned int)layout->id);
    rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), cycle, "IL", role_tag, "ROUTE_REMOVED",
                          "removed", NULL);
 
    RTE_EXAMPLE_LOG("[%s] cycle %u: route %u released\n", role_tag, cycle, (unsigned int)layout->id);
    rte_log_write_event(RTE_LOG_LEVEL_INFO, site_config_name(site), cycle, "IL", role_tag, "ROUTE_RELEASE",
                          "released", NULL);
    return true;
}

static bool handle_route_status_report(const rbc_envelope_t *env, uint32_t cycle, const char *role_tag)
{
    bool known = ab_ga_il_site_has_route_by_signals((uint16_t)env->start_signal, (uint16_t)env->end_signal, NULL);
 
    RTE_EXAMPLE_LOG(
        "[%s] cycle %u: ROUTE_STATUS_REPORT start_signal=%u end_signal=%u route_status=%u (route %s)\n", role_tag,
        cycle, (unsigned int)env->start_signal, (unsigned int)env->end_signal, (unsigned int)env->route_status,
        known ? "known" : "UNKNOWN to this site's own layout");
    return true;
}

static bool handle_il_route_cmd(ab_gp_db_t *db, const ab_ga_il_route_cmd_t *cmd, uint32_t cycle,
                                 rte_example_site_t site, const char *role_tag)
{
    uint16_t route_id;
    bool     want_route;
    ab_ga_route_fsm_result_t fsm;
 
    /* Need a concrete route identity to track/step. int32 -1 (or an
     * out-of-uint16 value) => no specific route => accepted but no-op. */
    if ((cmd->route_id < 0) || (cmd->route_id > (int32_t)UINT16_MAX))
    {
        RTE_LOG_WRITE_EVENT_F(RTE_LOG_LEVEL_WARNING, site_config_name(site), cycle, "IL", role_tag,
                               "IL_ROUTE_CMD",
                               "no route_id (=%d) - command ignored (route_type=%d route_status=%d release=%d)",
                               (int)cmd->route_id, (int)cmd->route_type, (int)cmd->route_status,
                               cmd->release_route_request ? 1 : 0);
        return true;
    }
    route_id = (uint16_t)cmd->route_id;
 
    want_route = (!cmd->release_route_request) && (cmd->route_type == RBC_IL_ROUTE_TYPE_LOCKED);
 
    if (want_route)
    {
        /* Track the route if the site knows it and it is not tracked yet.
         * start/end signals are optional in the command (-1); when both
         * are given, verify + add through the same site-checked path
         * ROUTE_ADD uses; otherwise, if the route is already tracked,
         * leave it. */
        if (!ab_gp_db_route_exists(db, route_id))
        {
            const ab_site_ga_route_layout_t *layout = NULL;
 
            if ((cmd->start_signal >= 0) && (cmd->end_signal >= 0)
                && ab_ga_il_site_has_route_by_signals((uint16_t)cmd->start_signal,
                                                       (uint16_t)cmd->end_signal, &layout)
                && (layout->id == route_id))
            {
                (void)ab_ga_il_route_add(db, route_id, layout->start_signal, layout->end_signal);
            }
            else if (ab_ga_il_site_has_route(route_id, &layout))
            {
                (void)ab_ga_il_route_add(db, route_id, layout->start_signal, layout->end_signal);
            }
            else
            {
                RTE_LOG_WRITE_EVENT_F(RTE_LOG_LEVEL_ERROR, site_config_name(site), cycle, "IL", role_tag,
                                       "IL_ROUTE_CMD",
                                       "route %u (start_signal=%d end_signal=%d) unknown to this site's layout - rejecting",
                                       (unsigned int)route_id, (int)cmd->start_signal, (int)cmd->end_signal);
                return false;
            }
        }
    }
 
    fsm = ab_ga_route_fsm_step(db, route_id, cmd, cycle, role_tag);
 
    if ((!want_route) && ab_gp_db_route_exists(db, route_id))
    {
        /* Release / NO_ROUTE: untrack. Any connected train is
         * disconnected through GP's own path (fires
         * ab_ga_il_on_route_context_changed()'s AB_ROUTE_DISCONNECTED,
         * which does the MA shrink AND its own indication) - same as
         * handle_route_release(). */
        (void)ab_ga_il_route_remove(db, route_id);
    }
 
    /* Acknowledge EVERY route command with a fresh RBC_MSG_IL_ROUTE_INDICATION
     * reflecting the RBC's resulting per-route view - so IL gets feedback
     * even for a command that connects no train (the connect/disconnect
     * hook only fires when a train is actually involved). Route identity
     * always comes from the static site layout, never the (optional)
     * wire fields. */
    {
        const ab_site_ga_route_layout_t *layout = NULL;
 
        if (ab_ga_il_site_has_route(route_id, &layout))
        {
            uint8_t alloc_train = 0U;
            bool    has_ma = false;
            uint32_t rstatus;
 
            if (ab_gp_db_route_exists(db, route_id))
            {
                ab_gp_route_context_t rctx;
                if (ab_gp_db_get_route_context(db, route_id, &rctx))
                {
                    alloc_train = rctx.train_id;
                    has_ma = rctx.used_in_ma;
                }
            }
            rstatus = (alloc_train != 0U) ? (uint32_t)RBC_ROUTE_STATUS_TRAIN_IN_ROUTE
                                          : (uint32_t)RBC_ROUTE_STATUS_NO_TRAIN;
            enqueue_pending_route_event(alloc_train, route_id, layout->start_signal,
                                         layout->end_signal, rstatus, has_ma, (uint8_t)fsm.to);
        }
    }
 
    return true;
}

static bool handle_il_status(const ab_ga_il_status_msg_t *st, uint32_t cycle, const char *role_tag)
{
    g_il_status = st->il_status;
 
    if ((st->il_status == RBC_IL_STATUS_DOWN) || (st->il_status == RBC_IL_STATUS_RESTARTING))
    {
        RTE_EXAMPLE_LOG("[%s] cycle %u: IL_STATUS=%s - route state trust HOLD not implemented yet (stub)\n",
                             role_tag, cycle,
                             (st->il_status == RBC_IL_STATUS_DOWN) ? "DOWN" : "RESTARTING");
    }
    else
    {
        RTE_EXAMPLE_LOG("[%s] cycle %u: IL_STATUS=UP\n", role_tag, cycle);
    }
    return true;
}

static void enqueue_pending_route_event(uint8_t train_id, uint16_t route_id, uint32_t start_signal,
                                          uint32_t end_signal, uint32_t route_status, bool train_has_ma,
                                          uint8_t fsm_state)
{
    uint8_t i;
    /* Each queued event yields TWO output frames (legacy + indication),
     * so the effective ceiling is half the array. */
    const uint8_t max_events = (uint8_t)(AB_GP_IL_MAX_PENDING_OUTPUTS / 2U);
 
    for (i = 0U; i < g_pending_route_event_count; i++)
    {
        if ((g_pending_route_events[i].route_id == route_id) &&
            (g_pending_route_events[i].train_id == train_id) &&
            (g_pending_route_events[i].route_status == route_status) &&
            (g_pending_route_events[i].fsm_state == fsm_state))
        {
            return; /* already queued this exact route view this cycle */
        }
    }
    if (g_pending_route_event_count >= max_events)
    {
        RTE_EXAMPLE_LOG("IL: pending route-indication queue full - dropping event for train %u\n",
                             (unsigned int)train_id);
        return;
    }
    g_pending_route_events[g_pending_route_event_count].train_id = train_id;
    g_pending_route_events[g_pending_route_event_count].route_id = route_id;
    g_pending_route_events[g_pending_route_event_count].start_signal = start_signal;
    g_pending_route_events[g_pending_route_event_count].end_signal = end_signal;
    g_pending_route_events[g_pending_route_event_count].route_status = route_status;
    g_pending_route_events[g_pending_route_event_count].train_has_ma = train_has_ma;
    g_pending_route_events[g_pending_route_event_count].fsm_state = fsm_state;
    g_pending_route_events[g_pending_route_event_count].fsm_is_stub = route_fsm_state_is_stub(fsm_state);
    g_pending_route_event_count++;
}

extern char *g_ga_role_tag;

void ab_ga_il_on_route_context_changed(ab_gp_train_session_t *sessions, ab_gp_db_t *db,
                                        const ab_gp_route_context_t *ctx, ab_gp_route_update_type_t update_type)
{
    const ab_site_ga_route_layout_t *layout = NULL;
    uint32_t                         route_status;
 
    if ((ctx == NULL) || (ctx->id == 0U))
    {
        return;
    }
    if ((update_type != AB_ROUTE_CONNECTED) && (update_type != AB_ROUTE_DISCONNECTED))
    {
        return; /* IL only cares about connect/disconnect - added/status-changed are ignored here */
    }
    route_status = (update_type == AB_ROUTE_CONNECTED) ? (uint32_t)RBC_ROUTE_STATUS_TRAIN_IN_ROUTE
                                                         : (uint32_t)RBC_ROUTE_STATUS_NO_TRAIN;
    RTE_EXAMPLE_LOG("[%s] IL notified: route %u %s train %u\n", g_ga_role_tag, (unsigned int)ctx->id,
                         (update_type == AB_ROUTE_CONNECTED) ? "connected to" : "disconnected from",
                         (unsigned int)ctx->train_id);
    if (!ab_ga_il_site_has_route(ctx->id, &layout))
    {
        return; /* shouldn't happen - ctx->id came from GP's own tracked route table */
    }
    enqueue_pending_route_event(ctx->train_id, ctx->id, layout->start_signal, layout->end_signal, route_status, (update_type == AB_ROUTE_CONNECTED), (uint8_t)ab_gp_db_route_get_fsm_state(db, ctx->id));
 
    if ((sessions == NULL) || (db == NULL) || (ctx->train_id == 0U))
    {
        return; /* no train association to grant/shrink MA for (e.g. connected==false already handled above) */
    }
 
    /* Movement Authority grant/shrink - moved HERE from the old
     * ROUTE_ADD/ROUTE_RELEASE-direct paths (this file's own
     * handle_route_add()/handle_route_release()), on direct request -
     * see this function's own header doc, ab_ga_il.h, for the full
     * reasoning. Fires only once GP's own position-based connect gate
     * has actually connected/disconnected this route to/from a train -
     * ctx->train_id is GP's own real, tracked association, never
     * anything IL supplied on the wire, and layout->length_m is this
     * route's own known length, resolved by ctx->id - never a
     * wire-supplied length either. */
    if (update_type == AB_ROUTE_CONNECTED)
    {
        /* Remaining length from the train's own last-reported position
         * to this route's own end signal - NOT the route's own full
         * length unconditionally (a real bug, found live: a train
         * connecting to a route already partway in was granted the
         * whole route, telling it there is more track ahead than
         * physically remains). Same correction as the real ERTMS
         * engine's own ab_gp_proc_ma_compute()/_extend() - see
         * ab_gp_proc_ma_remaining_length_m()'s own doc, ga_interface.h,
         * for the fallback behavior when the train's position can't be
         * resolved against this route at all. */
        /* The MA is measured from the train's LRBG (Subset-026): total = distance(LRBG -> this route's end signal)
         * minus the overlap, from chainage (ab_gp_proc_ma_remaining_length_m()). It is the WHOLE authority up to
         * this route's end, not an amount to add on top of the routes already granted, so it replaces the granted
         * length (the old one was relative to an earlier LRBG). If the train's position cannot be
         * read at all, fall back to adding the route's authored length. */
        ab_gp_train_context_t tctx_pos;
 
        if (ab_gp_get_train_context(sessions, db, ctx->train_id, &tctx_pos))
        {
            uint32_t total_m = ab_gp_proc_ma_remaining_length_m(layout, tctx_pos.nid_lrbg, tctx_pos.d_lrbg);
 
            total_m = (total_m > RTE_EXAMPLE_MA_OVERLAP_M) ? (total_m - RTE_EXAMPLE_MA_OVERLAP_M) : 0U;
            (void)ab_gp_train_session_set_granted_length(sessions, ctx->train_id, total_m);
        }
        else
        {
            (void)ab_gp_train_session_add_granted_length(sessions, ctx->train_id, layout->length_m);
        }
        (void)ab_gp_train_session_increment_ma_seq(sessions, ctx->train_id);
        /* ADR-034: this is the decision to grant a Movement Authority -
         * see handle_route_add()'s own former identical call for why. */
        AB_GA_CHECKPOINT_MARK();
        (void)ab_gp_train_session_set_ma_pending_send(sessions, ctx->train_id, true);
        (void)ab_gp_train_session_set_ma_acked(sessions, ctx->train_id, false);
        (void)ab_ga_il_handle_route_add(db, ctx->train_id);
    }
    else /* AB_ROUTE_DISCONNECTED */
    {
        /* route_count already reflects this disconnect - GP's own
         * ab_gp_db_route_disconnect_train() updates db->trains[].route_count/
         * route_ids[] before firing this notification. */
        ab_gp_train_context_t tctx;
 
        (void)ab_gp_get_train_context(sessions, db, ctx->train_id, &tctx);
        if (tctx.route_count == 0U)
        {
            rte_log_write_event(RTE_LOG_LEVEL_DEBUG, "-", 0U, "IL", g_ga_role_tag, "ROUTE_DISCONNECT_ZEROED_MA",
                                  "no routes remain for this train - granted_length reset to 0", NULL);
            (void)ab_gp_train_session_set_granted_length(sessions, ctx->train_id, 0U);
            (void)ab_gp_train_session_set_ctc_ma_granted_sent(sessions, ctx->train_id, false);
        }
        else
        {
            /* The remaining authority ends at the last route the train still holds: re-derive it from the LRBG
             * (distance to that route's end signal minus the overlap), never below what the train already
             * passed and never above what it held. */
            const ab_site_ga_route_layout_t *last = ab_site_ga_get_route(tctx.route_ids[tctx.route_count - 1U]);
 
            if (last != NULL)
            {
                uint32_t total_m = ab_gp_proc_ma_remaining_length_m(last, tctx.nid_lrbg, tctx.d_lrbg);
 
                total_m = (total_m > RTE_EXAMPLE_MA_OVERLAP_M) ? (total_m - RTE_EXAMPLE_MA_OVERLAP_M) : 0U;
                if (total_m < tctx.granted_length)
                {
                    rte_log_write_event(RTE_LOG_LEVEL_DEBUG, "-", 0U, "IL", g_ga_role_tag,
                                          "ROUTE_DISCONNECT_SHRUNK_MA",
                                          "granted_length re-derived from the last remaining route", NULL);
                    (void)ab_gp_train_session_set_granted_length(sessions, ctx->train_id, total_m);
                }
            }
        }
    }
    /* Explicit trigger, on direct request - same "fire once, after every
     * field is settled" rule this call has always followed - see
     * ab_gp_train_notify_context_changed()'s own doc, ab_gp_train.h. */
    ab_gp_train_notify_context_changed(sessions, db, ctx->train_id, AB_TRAIN_MA_CHANGED);
}