ab_gp_db.c

Go to the documentation of this file.

#include "ab_gp_db.h"
 
#include "rte/utils/buffer/rte_buffer.h"
#include "rte/oal/memory/rte_mem_util.h"
#include "rte/utils/lifecycle/rte_lifecycle.h"
#include "rte/utils/notify/rte_notify.h"
 
 
/* GA notification registries - module-private storage, same "static
 * singleton" convention as ab_gp_channel.c's own g_ab_ctx. See ab_gp_db.h's
 * own "GA notification" doc for why this file fires them (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. */
RTE_DECLARE_CALLBACK_LIST(ab_gp_db_route_context_list_t, ab_gp_route_context_notify_fn,
                               AB_GP_DB_MAX_ROUTE_CONTEXT_SUBSCRIBERS);
 
static ab_gp_db_route_context_list_t g_route_context_subscribers;
 
rte_status_t ab_gp_db_register_route_context_notify(ab_gp_route_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_route_context_subscribers.count >= (uint32_t)AB_GP_DB_MAX_ROUTE_CONTEXT_SUBSCRIBERS)
    {
        return RTE_STATUS_RESOURCE_EXHAUSTED;
    }
    g_route_context_subscribers.slots[g_route_context_subscribers.count].fn = fn;
    g_route_context_subscribers.slots[g_route_context_subscribers.count].context = (void *)context; /* see
        AB/GP/ma_logic/ab_gp_logic.c's own identical cast for why this is safe - const enters, const-typed
        fn() is all that's ever done with it */
    g_route_context_subscribers.count++;
    return RTE_STATUS_OK;
}

static void build_route_context(const ab_gp_db_t *db, int route_idx, uint8_t train_id, ab_gp_route_context_t *out_ctx)
{
    const ab_gp_db_route_t *route = &db->routes[route_idx];
 
    out_ctx->id = route->id;
    out_ctx->start_signal = route->start_signal;
    out_ctx->end_signal = route->end_signal;
    out_ctx->il_status = route->il_status;
    out_ctx->route_type = route->route_type;
    out_ctx->used_in_ma = route->used_in_ma;
    out_ctx->train_id = train_id;
}

static void notify_route_context(const ab_gp_db_t *db, int route_idx, uint8_t train_id,
                                  ab_gp_route_update_type_t update_type)
{
    ab_gp_route_context_t ctx;
    uint32_t               i;
 
    build_route_context(db, route_idx, train_id, &ctx);
 
    for (i = 0U; i < g_route_context_subscribers.count; i++)
    {
        if (g_route_context_subscribers.slots[i].fn != NULL)
        {
            g_route_context_subscribers.slots[i].fn(g_route_context_subscribers.slots[i].context, &ctx,
                                                       update_type);
        }
    }
}

static int find_route_index(const ab_gp_db_t *db, uint16_t route_id)
{
    uint32_t i;
 
    if (db == NULL || route_id == 0U)
    {
        return -1;
    }
 
    for (i = 0U; i < (uint32_t)RTE_EXAMPLE_MAX_ROUTES; i++)
    {
        if (db->routes[i].id == route_id)
        {
            return (int)i;
        }
    }
    return -1;
}

static int find_free_route_slot(const ab_gp_db_t *db)
{
    uint32_t i;
 
    if (db == NULL)
    {
        return -1;
    }
 
    for (i = 0U; i < (uint32_t)RTE_EXAMPLE_MAX_ROUTES; i++)
    {
        if (db->routes[i].id == 0U)
        {
            return (int)i;
        }
    }
    return -1;
}
 
bool ab_gp_db_route_connect_train(ab_gp_db_t *db, uint16_t route_id, uint8_t train_id)
{
    int             route_idx;
    ab_gp_db_train_t  *train;
    uint8_t         k;
 
    if (db == NULL || route_id == 0U)
    {
        return false;
    }
    route_idx = find_route_index(db, route_id);
    if (route_idx < 0)
    {
        return false;
    }
    /* REQ-RBC-005: an out-of-range train_id returns false to the caller before it indexes db->trains[]. */
    if ((train_id == 0U) || (train_id > (uint8_t)RTE_EXAMPLE_MAX_TRAINS))
    {
        return false;
    }
    if (db->routes[route_idx].used_in_ma)
    {
        return false; /* already assigned - disconnect first, never silently reassigned */
    }
 
    train = &db->trains[train_id - 1U];
    if (train->route_count >= (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN)
    {
        return false; /* this train's own route_ids[] table full */
    }
    for (k = 0U; k < train->route_count; k++)
    {
        if (train->route_ids[k] == route_id)
        {
            return false; /* already allocated to this same train */
        }
    }
 
    train->route_ids[train->route_count] = route_id;
    train->route_count++;
 
    db->routes[route_idx].used_in_ma = true;
    db->routes[route_idx].train_id = train_id;
    notify_route_context(db, route_idx, train_id, AB_ROUTE_CONNECTED);
    return true;
}
 
bool ab_gp_db_route_disconnect_train(ab_gp_db_t *db, uint16_t route_id)
{
    int             route_idx;
    ab_gp_db_train_t  *train;
    uint8_t         disconnected_train_id;
    uint8_t         k;
 
    if (db == NULL || route_id == 0U)
    {
        return false;
    }
    route_idx = find_route_index(db, route_id);
    if (route_idx < 0)
    {
        return false;
    }
    if (!db->routes[route_idx].used_in_ma)
    {
        return false; /* nothing to disconnect */
    }
 
    disconnected_train_id = db->routes[route_idx].train_id; /* captured before it's cleared below - see
                                                                notify_route_context()'s own doc */
    db->routes[route_idx].used_in_ma = false;
    db->routes[route_idx].train_id = 0U;
 
    /* REQ-RBC-005: the train_id read back from the route is range-checked before it indexes db->trains[]; an
     * out-of-range value skips the per-train route list cleanup (the route itself is still released). */
    if ((disconnected_train_id >= 1U) && (disconnected_train_id <= (uint8_t)RTE_EXAMPLE_MAX_TRAINS))
    {
        train = &db->trains[disconnected_train_id - 1U];
        if (train->route_count > (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN)
        {
            train->route_count = (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN;
        }
        for (k = 0U; k < train->route_count; k++)
        {
            if (train->route_ids[k] == route_id)
            {
                uint8_t shift;
 
                for (shift = k; (uint8_t)(shift + 1U) < train->route_count; shift++)
                {
                    train->route_ids[shift] = train->route_ids[shift + 1U];
                }
                train->route_ids[train->route_count - 1U] = 0U;
                train->route_count--;
                break;
            }
        }
    }
 
    notify_route_context(db, route_idx, disconnected_train_id, AB_ROUTE_DISCONNECTED);
    return true;
}
 
bool ab_gp_db_route_exists(const ab_gp_db_t *db, uint16_t route_id)
{
    return find_route_index(db, route_id) >= 0;
}
 
bool ab_gp_db_route_add(ab_gp_db_t *db, uint16_t route_id, uint16_t start_signal, uint16_t end_signal)
{
    int slot;
 
    if (find_route_index(db, route_id) >= 0)
    {
        return false; /* already tracked - ab_gp_db_route_remove() first to replace it */
    }
    slot = find_free_route_slot(db);
    if (slot < 0)
    {
        return false; /* db->routes[] (RTE_EXAMPLE_MAX_ROUTES) full */
    }
 
    db->routes[slot].id = route_id;
    db->routes[slot].start_signal = start_signal;
    db->routes[slot].end_signal = end_signal;
    db->routes[slot].occupied = false;
    db->routes[slot].il_status = AB_GP_DB_ROUTE_IL_STATUS_UNKNOWN;
    db->routes[slot].route_type = 0U; /* RBC_ROUTE_TYPE_FS - rbc_wire_types.h */
    db->routes[slot].route_fsm_state = 0U; /* AB_GA_ROUTE_STATE_NO_ROUTE - must be
                                             * reset here: this slot may be a reused
                                             * one whose route_fsm_state still holds
                                             * the PREVIOUS route's last state, which
                                             * ab_ga_route_fsm_step() would then read
                                             * as its "from" and the IL_ROUTE_INDICATION
                                             * would report on a freshly-added route. */
    db->routes[slot].used_in_ma = false;
    db->routes[slot].train_id = 0U;
    notify_route_context(db, slot, 0U, AB_ROUTE_ADDED);
    return true;
}
 
bool ab_gp_db_route_remove(ab_gp_db_t *db, uint16_t route_id)
{
    int idx = find_route_index(db, route_id);
 
    if (idx < 0)
    {
        return false;
    }
    if (db->routes[idx].used_in_ma)
    {
        return false; /* still backing a train's MA - ab_gp_db_route_disconnect_train() first */
    }
    rte_mem_set(&db->routes[idx], 0, sizeof(db->routes[idx])); /* id becomes 0 again -> slot free */
    return true;
}
 
/* ab_gp_db_route_get_status()/_get_used_in_ma()/_get_type() - REMOVED,
 * see ab_gp_db.h's own comment at their old declaration. */
 
bool ab_gp_db_route_set_status(ab_gp_db_t *db, uint16_t route_id, ab_gp_db_route_il_status_t status)
{
    int idx = find_route_index(db, route_id);
 
    if (idx < 0)
    {
        return false;
    }
    db->routes[idx].il_status = status;
    notify_route_context(db, idx, db->routes[idx].train_id, AB_ROUTE_STATUS_CHANGED);
    return true;
}
 
bool ab_gp_db_get_route_context(const ab_gp_db_t *db, uint16_t route_id, ab_gp_route_context_t *out_ctx)
{
    int idx = find_route_index(db, route_id);
 
    if (idx < 0)
    {
        return false;
    }
    build_route_context(db, idx, db->routes[idx].train_id, out_ctx);
    return true;
}
 
bool ab_gp_db_route_set_type(ab_gp_db_t *db, uint16_t route_id, uint32_t route_type)
{
    int idx = find_route_index(db, route_id);
 
    if (idx < 0)
    {
        return false;
    }
    db->routes[idx].route_type = route_type;
    return true;
}
 
bool ab_gp_db_route_set_fsm_state(ab_gp_db_t *db, uint16_t route_id, uint32_t fsm_state)
{
    int idx = find_route_index(db, route_id);
 
    if (idx < 0)
    {
        return false;
    }
    db->routes[idx].route_fsm_state = fsm_state;
    return true;
}
 
uint32_t ab_gp_db_route_get_fsm_state(const ab_gp_db_t *db, uint16_t route_id)
{
    int idx;
 
    if (db == NULL)
    {
        return 0U;
    }
    idx = find_route_index(db, route_id);
    if (idx < 0)
    {
        return 0U;
    }
    return db->routes[idx].route_fsm_state;
}
 
uint8_t ab_gp_db_route_get_count(const ab_gp_db_t *db)
{
    uint8_t count = 0U;
    uint8_t i;
 
    if (db == NULL)
    {
        return 0U;
    }
 
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_ROUTES; i++)
    {
        if (db->routes[i].id != 0U)
        {
            count++;
        }
    }
    return count;
}
 
bool ab_gp_db_route_get_by_index(const ab_gp_db_t *db, uint8_t index, uint16_t *out_route_id,
                                 uint16_t *out_start_signal, uint16_t *out_end_signal,
                                 uint8_t *out_train_id, bool *out_used_in_ma)
{
    if (db == NULL || index >= (uint8_t)RTE_EXAMPLE_MAX_ROUTES)
    {
        return false;
    }
 
    if (db->routes[index].id == 0U)
    {
        return false;
    }
 
    if (out_route_id != NULL)
    {
        *out_route_id = db->routes[index].id;
    }
    if (out_start_signal != NULL)
    {
        *out_start_signal = db->routes[index].start_signal;
    }
    if (out_end_signal != NULL)
    {
        *out_end_signal = db->routes[index].end_signal;
    }
    if (out_train_id != NULL)
    {
        *out_train_id = db->routes[index].train_id;
    }
    if (out_used_in_ma != NULL)
    {
        *out_used_in_ma = db->routes[index].used_in_ma;
    }
    return true;
}
 
/* REQ-RBC-005: ab_gp_db_train_is_connected() and _get_routes() below each check
 * 1 <= train_id <= RTE_EXAMPLE_MAX_TRAINS before it indexes db->trains[], and otherwise return false to the caller;
 * neither of them logs. */
bool ab_gp_db_train_is_connected(const ab_gp_db_t *db, uint8_t train_id)
{
    if (db == NULL || train_id < 1U || train_id > (uint8_t)RTE_EXAMPLE_MAX_TRAINS)
    {
        return false;
    }
    return db->trains[train_id - 1U].connected;
}
 
bool ab_gp_db_train_get_routes(const ab_gp_db_t *db, uint8_t train_id,
                               uint16_t out_routes[RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN],
                               uint8_t *out_count)
{
    uint8_t i;
 
    if (db == NULL || train_id < 1U || train_id > (uint8_t)RTE_EXAMPLE_MAX_TRAINS ||
        out_routes == NULL || out_count == NULL)
    {
        return false;
    }
 
    uint8_t count = db->trains[train_id - 1U].route_count;
 
    if (count > (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN)
    {
        count = (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN;
    }
    *out_count = count;
    for (i = 0U; i < count; i++)
    {
        out_routes[i] = db->trains[train_id - 1U].route_ids[i];
    }
    for (; i < (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN; i++)
    {
        out_routes[i] = 0U;
    }
    return true;
}
 
rte_status_t ab_gp_db_encode(const ab_gp_db_t *db, uint8_t *out_bytes, uint32_t out_capacity, uint32_t *out_written)
{
    size_t offset = 0U;
    uint8_t i;
 
    if (db == NULL || out_bytes == NULL || out_capacity < (uint32_t)RTE_EXAMPLE_DB_WIRE_SIZE)
    {
        return RTE_STATUS_INVALID_PARAM;
    }
 
    rte_mem_set(out_bytes, 0, (size_t)RTE_EXAMPLE_DB_WIRE_SIZE);
 
    /* 1. Encode routes (RTE_EXAMPLE_MAX_ROUTES) */
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_ROUTES; i++)
    {
        const ab_gp_db_route_t *r = &db->routes[i];
 
        out_bytes[offset] = (uint8_t)(r->id & 0xFFU);
        out_bytes[offset + 1U] = (uint8_t)((r->id >> 8) & 0xFFU);
        offset += 2U;
 
        out_bytes[offset] = (uint8_t)(r->start_signal & 0xFFU);
        out_bytes[offset + 1U] = (uint8_t)((r->start_signal >> 8) & 0xFFU);
        offset += 2U;
 
        out_bytes[offset] = (uint8_t)(r->end_signal & 0xFFU);
        out_bytes[offset + 1U] = (uint8_t)((r->end_signal >> 8) & 0xFFU);
        offset += 2U;
 
        out_bytes[offset] = (uint8_t)(r->route_type & 0xFFU);
        out_bytes[offset + 1U] = (uint8_t)((r->route_type >> 8) & 0xFFU);
        offset += 2U;
 
        out_bytes[offset] = r->occupied ? 1U : 0U;
        offset++;
        out_bytes[offset] = (uint8_t)r->il_status;
        offset++;
        out_bytes[offset] = r->used_in_ma ? 1U : 0U;
        offset++;
        out_bytes[offset] = r->train_id;
        offset++;
    }
 
    /* 2. Encode trains (RTE_EXAMPLE_MAX_TRAINS) */
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_TRAINS; i++)
    {
        const ab_gp_db_train_t *t = &db->trains[i];
        uint8_t rc = (t->route_count > (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN)
                     ? (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN : t->route_count;
        uint32_t j;
 
        out_bytes[offset] = t->nid_engine;
        offset++;
        out_bytes[offset] = t->connected ? 1U : 0U;
        offset++;
        out_bytes[offset] = t->has_ma ? 1U : 0U;
        offset++;
        out_bytes[offset] = rc;
        offset++;
 
        for (j = 0U; j < 4U; j++)
        {
            uint16_t rid = (j < (uint32_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN) ? t->route_ids[j] : 0U;
            out_bytes[offset] = (uint8_t)(rid & 0xFFU);
            out_bytes[offset + 1U] = (uint8_t)((rid >> 8) & 0xFFU);
            offset += 2U;
        }
 
        out_bytes[offset] = (uint8_t)(t->last_nid_lrbg & 0xFFU);
        out_bytes[offset + 1U] = (uint8_t)((t->last_nid_lrbg >> 8) & 0xFFU);
        out_bytes[offset + 2U] = (uint8_t)((t->last_nid_lrbg >> 16) & 0xFFU);
        out_bytes[offset + 3U] = (uint8_t)((t->last_nid_lrbg >> 24) & 0xFFU);
        offset += 4U;
    }
 
    if (out_written != NULL)
    {
        *out_written = (uint32_t)offset;
    }
 
    return RTE_STATUS_OK;
}
 
rte_status_t ab_gp_db_decode(ab_gp_db_t *db, const uint8_t *in_bytes, uint32_t in_size)
{
    rte_buffer_t buf;
    rte_status_t status;
    size_t offset = 0U;
    uint8_t i;
 
    if (db == NULL || in_bytes == NULL || in_size < (uint32_t)RTE_EXAMPLE_DB_WIRE_SIZE)
    {
        return RTE_STATUS_INVALID_PARAM;
    }
 
    status = rte_buffer_init(&buf, (void *)in_bytes, (size_t)in_size);
    if (status != RTE_STATUS_OK)
    {
        return status;
    }
    status = rte_buffer_set_length(&buf, (size_t)in_size);
    if (status != RTE_STATUS_OK)
    {
        return status;
    }
 
    rte_mem_set(db, 0, sizeof(ab_gp_db_t));
 
    /* 1. Decode routes (RTE_EXAMPLE_MAX_ROUTES) */
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_ROUTES; i++)
    {
        ab_gp_db_route_t *r = &db->routes[i];
        uint16_t u16_val = 0U;
 
        (void)rte_buffer_read_u16_le(&buf, offset, &r->id);
        offset += 2U;
        (void)rte_buffer_read_u16_le(&buf, offset, &r->start_signal);
        offset += 2U;
        (void)rte_buffer_read_u16_le(&buf, offset, &r->end_signal);
        offset += 2U;
        (void)rte_buffer_read_u16_le(&buf, offset, &u16_val);
        r->route_type = (uint32_t)u16_val;
        offset += 2U;
 
        r->occupied = (in_bytes[offset] != 0U);
        offset++;
        r->il_status = (ab_gp_db_route_il_status_t)in_bytes[offset];
        offset++;
        r->used_in_ma = (in_bytes[offset] != 0U);
        offset++;
        r->train_id = in_bytes[offset];
        offset++;
    }
 
    /* 2. Decode trains (RTE_EXAMPLE_MAX_TRAINS) */
    for (i = 0U; i < (uint8_t)RTE_EXAMPLE_MAX_TRAINS; i++)
    {
        ab_gp_db_train_t *t = &db->trains[i];
 
        t->nid_engine = in_bytes[offset];
        offset++;
        t->connected = (in_bytes[offset] != 0U);
        offset++;
        t->has_ma = (in_bytes[offset] != 0U);
        offset++;
        if (in_bytes[offset] > (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN)
        {
            t->route_count = (uint8_t)RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN;
        }
        else
        {
            t->route_count = in_bytes[offset];
        }
        offset++;
 
        (void)rte_buffer_read_u16_le(&buf, offset, &t->route_ids[0]);
        offset += 2U;
        (void)rte_buffer_read_u16_le(&buf, offset, &t->route_ids[1]);
        offset += 2U;
        (void)rte_buffer_read_u16_le(&buf, offset, &t->route_ids[2]);
        offset += 2U;
        (void)rte_buffer_read_u16_le(&buf, offset, &t->route_ids[3]);
        offset += 2U;
 
        (void)rte_buffer_read_u32_le(&buf, offset, &t->last_nid_lrbg);
        offset += 4U;
    }
 
    return RTE_STATUS_OK;
}