A/B's own RBC decision logic - today's slice: connect a train's currently-reported route to that train, from the balise (NID_LRBG) it most recently reported in its Position Report. More...

#include <stdbool.h>
#include <stdint.h>
#include "rte/utils/status/rte_status.h"
#include "../db/ab_gp_db.h"

Include dependency graph for ab_gp_logic.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
bool	ab_gp_logic_connect_route_for_train (ab_gp_db_t *db, uint8_t train_id)
	Connects one train's own currently-reported route to it: looks up which route the balise at db->trains[train_id-1].last_nid_lrbg (ab_gp_train_get_last_position(), AB/GP/train/ab_gp_train.h) is placed in (site/'s own static balise table, ab_site.h), asks every registered GA validator whether connecting it to `train_id` is OK (ab_gp_ga_register_init() above - il/'s own validator is also where a not-yet-tracked route gets added, see that function's own doc), and if approved, connects it (AB/GP/db/ab_gp_db.h's own ab_gp_db_route_connect_train(), which fires its OWN registered-subscriber notification on success - this module itself does not notify GA, see this file's own module doc for why). Idempotent: calling this again with the same still-current position is a safe no-op, not a re-connect (already-connected is detected before any validator call, so it does not fire again for an unchanged position).
void	ab_gp_logic_connect_routes_and_trains (ab_gp_db_t *db)
	THE cyclic sweep: calls ab_gp_logic_connect_route_for_train() for every currently-connected train (ab_gp_train_is_connected(), AB/GP/train/ab_gp_train.h). Safe to call every cycle unconditionally, whether or not any train reported a new position this cycle - see this function's own idempotence doc above.

GA registration - the callback interface il/ builds against
(AB/GA/il/ab_ga_il.c's ab_ga_il_init())
#define	AB_GP_LOGIC_ROUTE_VALIDATOR_FN_DEFINED
	A registered GA module's own veto over a proposed route<->train connection - see ab_gp_ga_register_init()'s own doc.
#define	AB_GP_LOGIC_MAX_ROUTE_VALIDATORS 2U
rte_status_t	ab_gp_ga_register_init (ab_gp_logic_route_validator_fn fn, void *context)
	Registers a GA veto over every future proposed route<->train connection (ab_gp_logic_connect_route_for_train() below calls every currently-registered validator - ALL must approve, and approval requires at least one registered validator: zero registered validators means every connection is refused, fail-safe default-deny - see rte_notify.h's own doc, safeAPIFreamwork, for why). Setup-phase only, same convention as every framework constructor (rte_lifecycle_check_setup_allowed()) - called today only from AB/GA/ma_logic_adaptation/'s own ab_ga_ma_logic_adaptation_init() (GA's own single entry point - see that module's own doc), itself called once from ab_gp_channel_ga_setup() (AB/GP/com/ab_gp_channel.c) before rte_appmanager locks the setup phase.

Shunting gate (Subset-026 5.6, Msg 130) - GA veto over SH authorisation
#define	AB_GP_LOGIC_SHUNTING_VALIDATOR_FN_DEFINED
#define	AB_GP_LOGIC_MAX_SHUNTING_VALIDATORS 2U
rte_status_t	ab_gp_ga_register_shunting_validator (ab_gp_logic_shunting_validator_fn fn, void *context)
	Registers a GA veto over Shunting authorisation. Same contract as ab_gp_ga_register_init(): setup phase only, and zero registered validators means every request is refused (fail-safe default-deny).
bool	ab_gp_logic_shunting_allowed (uint8_t train_id)
	Asks every registered shunting validator about `train_id`.

Detailed Description

A/B's own RBC decision logic - today's slice: connect a train's currently-reported route to that train, from the balise (NID_LRBG) it most recently reported in its Position Report.

GA/GP split: this module is "GP" - the mechanical orchestrator that finds a candidate route for a train (site/'s own static balise table, genuinely this module's own site-geometry lookup) and, if approved, connects it (AB/GP/db/ab_gp_db.h's own ab_gp_db_route_connect_train()). It does not decide on its own whether that PRELIMINARY connection is ALLOWED, nor does it #include il/'s header to ask. Instead it asks its own registered "GA" validator(s) (ab_gp_ga_register_init() below - il/'s own ab_ga_il_init() registers itself, AB/GA/il/ab_ga_il.c) via callback - the ONE hook this module owns. Built on safeAPIFreamwork's include/rte/notify/rte_notify.h (RTE_DECLARE_CALLBACK_LIST, ADR-030) for the fixed-capacity registered-callback storage shape; the actual init/register/dispatch functions below are this module's own hand-written code against that shape (see rte_notify.h's own doc for why they aren't macro-generated).

This module does NOT itself notify GA once a connection is made - that notification (AB_DB's own ab_gp_db_register_route_connected_notify(), AB/GP/db/ab_gp_db.h) fires from db/ instead, since db/ is the module that actually performs the connect (ab_gp_db_route_connect_train()) - same "whichever GP module performs a mutation is the one that fires the matching notify" rule this file's design follows (train/ fires its own two hooks for the same reason, AB/GP/train/ab_gp_train.h). This module's own validator gate stays here specifically because it runs BEFORE any mutation happens at all - asking is this module's job, not the mutator's.

Deliberately not unified with the real MA-granting path (granted_length/ma_pending_send, driven entirely by the external IL sim's live ROUTE_ADD wire message, AB/GA/il/ab_ga_il.c's own ab_ga_il_apply_envelope()) - this module's own position-inferred route-connect sweep and that wire-driven path remain two separate, independently-verifiable flows. db/'s route-connected notify is an additive/observability seam for il/ and ctc/, not a second trigger for a real Movement Authority.

Built on db/ (runtime Train/Route state + the mechanical connect/disconnect primitives above), site/ (static track layout + balise placement) and train/ (train find/get/set) - il/ is reached only through the callback interface above, never a direct #include. com/ is the only one of those it does NOT touch directly

com/ populates db/'s train state (train_id, last_nid_lrbg) as real position reports arrive off the wire; this module only ever reads that already-populated state, never wire bytes.

ab_gp_logic_connect_routes_and_trains() is THIS module's own cyclic entry point - see its own doc for how it is wired into rte_appmanager (com/ab_gp_channel.c's already-registered execute() hook calls it once per cycle, ahead of the actual AGREE/DISAGREE decision - this framework's appmanager has no separate "register an arbitrary periodic callback" mechanism of its own, only the fixed init/pre_execute/execute/post_execute/shutdown hooks, and execute() is specifically its mandatory per-cycle DECISION LOGIC slot - see rte_appmanager.h and AB/GP/com/ab_gp_channel.c's own ab_gp_channel_connect_routes_and_trains() doc).

Definition in file ab_gp_logic.h.

Macro Definition Documentation

◆ AB_GP_LOGIC_ROUTE_VALIDATOR_FN_DEFINED

#define AB_GP_LOGIC_ROUTE_VALIDATOR_FN_DEFINED

A registered GA module's own veto over a proposed route<->train connection - see ab_gp_ga_register_init()'s own doc.

Parameters

context	Whatever `context` was passed to ab_gp_ga_register_init() - this module never dereferences it itself.
route_id	Candidate route (site/'s own static track layout identity, AB/SA/site/ab_site.h).
train_id	1..RTE_EXAMPLE_MAX_TRAINS.

Returns: true if this validator approves the connection; false to veto it. il/'s own registered validator (AB/GA/il/ab_ga_il.c) is also where the route gets added to db/'s tracked set if this is the first time it's been seen (a validator may have real, GA-owned side effects on approval - the reason this stays a validate step, not a pure predicate).

Definition at line 98 of file ab_gp_logic.h.

◆ AB_GP_LOGIC_MAX_ROUTE_VALIDATORS

#define AB_GP_LOGIC_MAX_ROUTE_VALIDATORS 2U

Worst case one train↔route connect decision realistically needs today (il/'s own validator; headroom for one more GA module to gain veto say later without another signature/capacity change).

Definition at line 105 of file ab_gp_logic.h.

◆ AB_GP_LOGIC_SHUNTING_VALIDATOR_FN_DEFINED

#define AB_GP_LOGIC_SHUNTING_VALIDATOR_FN_DEFINED

Definition at line 173 of file ab_gp_logic.h.

◆ AB_GP_LOGIC_MAX_SHUNTING_VALIDATORS

#define AB_GP_LOGIC_MAX_SHUNTING_VALIDATORS 2U

One GA validator today (ma_logic_adaptation/), one slot of headroom.

Definition at line 181 of file ab_gp_logic.h.

Function Documentation

◆ ab_gp_ga_register_init()

rte_status_t ab_gp_ga_register_init	(	ab_gp_logic_route_validator_fn	fn,
		void *	context )

Registers a GA veto over every future proposed route<->train connection (ab_gp_logic_connect_route_for_train() below calls every currently-registered validator - ALL must approve, and approval requires at least one registered validator: zero registered validators means every connection is refused, fail-safe default-deny - see rte_notify.h's own doc, safeAPIFreamwork, for why). Setup-phase only, same convention as every framework constructor (rte_lifecycle_check_setup_allowed()) - called today only from AB/GA/ma_logic_adaptation/'s own ab_ga_ma_logic_adaptation_init() (GA's own single entry point - see that module's own doc), itself called once from ab_gp_channel_ga_setup() (AB/GP/com/ab_gp_channel.c) before rte_appmanager locks the setup phase.

Parameters

fn	Validator to register. Must not be NULL.
context	Passed back to `fn` verbatim on every call - see ab_gp_logic_route_validator_fn's own doc.

Returns: RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM if fn is NULL; RTE_STATUS_INVALID_STATE if the setup phase is already locked; RTE_STATUS_RESOURCE_EXHAUSTED if AB_GP_LOGIC_MAX_ROUTE_VALIDATORS are already registered.

Global functions

Definition at line 46 of file ab_gp_logic.c.

◆ ab_gp_logic_connect_route_for_train()

bool ab_gp_logic_connect_route_for_train	(	ab_gp_db_t *	db,
		uint8_t	train_id )

Connects one train's own currently-reported route to it: looks up which route the balise at db->trains[train_id-1].last_nid_lrbg (ab_gp_train_get_last_position(), AB/GP/train/ab_gp_train.h) is placed in (site/'s own static balise table, ab_site.h), asks every registered GA validator whether connecting it to train_id is OK (ab_gp_ga_register_init() above - il/'s own validator is also where a not-yet-tracked route gets added, see that function's own doc), and if approved, connects it (AB/GP/db/ab_gp_db.h's own ab_gp_db_route_connect_train(), which fires its OWN registered-subscriber notification on success - this module itself does not notify GA, see this file's own module doc for why). Idempotent: calling this again with the same still-current position is a safe no-op, not a re-connect (already-connected is detected before any validator call, so it does not fire again for an unchanged position).

Returns: false if train_id is not a currently-connected train, it has not reported a position yet (last_nid_lrbg == 0), the reported NID_LRBG is not a balise this site's own layout knows about, no GA validator approved the connection (this includes the route already being assigned to a DIFFERENT train - never silently reassigned), or the actual connect itself failed. true if the route is now connected to this train (whether this call just did that, or it already was).

Definition at line 120 of file ab_gp_logic.c.

◆ ab_gp_logic_connect_routes_and_trains()

void ab_gp_logic_connect_routes_and_trains ( ab_gp_db_t * db )

THE cyclic sweep: calls ab_gp_logic_connect_route_for_train() for every currently-connected train (ab_gp_train_is_connected(), AB/GP/train/ab_gp_train.h). Safe to call every cycle unconditionally, whether or not any train reported a new position this cycle - see this function's own idempotence doc above.

Definition at line 219 of file ab_gp_logic.c.

◆ ab_gp_ga_register_shunting_validator()

rte_status_t ab_gp_ga_register_shunting_validator	(	ab_gp_logic_shunting_validator_fn	fn,
		void *	context )

Registers a GA veto over Shunting authorisation. Same contract as ab_gp_ga_register_init(): setup phase only, and zero registered validators means every request is refused (fail-safe default-deny).

Returns: RTE_STATUS_OK; RTE_STATUS_INVALID_PARAM if fn is NULL; the rte_lifecycle_check_setup_allowed() status once setup is locked; RTE_STATUS_RESOURCE_EXHAUSTED when AB_GP_LOGIC_MAX_SHUNTING_VALIDATORS are already registered.

Definition at line 69 of file ab_gp_logic.c.

◆ ab_gp_logic_shunting_allowed()

bool ab_gp_logic_shunting_allowed ( uint8_t train_id )

Asks every registered shunting validator about train_id.

Returns: true only if at least one validator is registered and all approve.

Definition at line 92 of file ab_gp_logic.c.

Functions

GA registration - the callback interface il/ builds against

Shunting gate (Subset-026 5.6, Msg 130) - GA veto over SH authorisation