THE single door GA (safeAPIRBC2oo2GA, a separate shared-library project) uses to reach GP - GP exports this header (GA reaches it header-only, via RTE_RBC2OO2GP_DIR, same sibling-source posture as common/) so GA's independent build can see every function signature it is allowed to call. More...

#include <stdbool.h>
#include <stdint.h>
#include "rte/app/appmanager/rte_appmanager.h"
#include "rte/utils/status/rte_status.h"
#include "common_config.h"
#include "site_config.h"
#include "ab_siteGA.h"

Include dependency graph for ga_interface.h:

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

Go to the source code of this file.

Data Structures
struct	ab_gp_route_context_t
struct	ab_gp_train_context_t
struct	ab_gp_il_pending_output_t
struct	ab_gp_ctc_pending_output_t

Macros
#define	RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN 4U
#define	AB_GP_DB_T_DEFINED
#define	TRAIN_SESSION_T_DEFINED
#define	AB_GP_DB_ROUTE_IL_STATUS_T_DEFINED
#define	AB_GP_ROUTE_UPDATE_TYPE_T_DEFINED
#define	AB_GP_ROUTE_CONTEXT_T_DEFINED
#define	AB_GP_DB_ROUTE_NOTIFY_FN_DEFINED
#define	AB_GP_TRAIN_UPDATE_TYPE_T_DEFINED
#define	AB_GP_TRAIN_CONTEXT_T_DEFINED
#define	AB_GP_TRAIN_NOTIFY_FN_DEFINED
#define	AB_GP_LOGIC_ROUTE_VALIDATOR_FN_DEFINED
#define	AB_GA_CHECKPOINT_MARK()
	Records a checkpoint mark for this GA call site (ADR-034). GA links rte::appmanager directly now (no more proxying through GP) - this is a thin, GA-side alias for the framework's own RTE_CHECKPOINT_MARK() (rte/app/appmanager/rte_appmanager.h), kept as a distinct name only so a grep for AB_GA_CHECKPOINT_MARK still finds every GA call site the way it always has.

Typedefs
typedef struct ab_gp_db_s	ab_gp_db_t
typedef struct train_session_s	ab_gp_train_session_t
typedef void(*)	ab_gp_train_context_notify_fn(const void context, const ab_gp_train_context_t ctx, ab_gp_train_update_type_t update_type)
typedef bool(*)	ab_gp_logic_route_validator_fn(void *context, uint16_t route_id, uint8_t train_id)

Enumerations
enum	ab_gp_db_route_il_status_t { AB_GP_DB_ROUTE_IL_STATUS_UNKNOWN = 0 , AB_GP_DB_ROUTE_IL_STATUS_FREE , AB_GP_DB_ROUTE_IL_STATUS_RESERVED , AB_GP_DB_ROUTE_IL_STATUS_LOCKED }
enum	ab_gp_route_update_type_t { AB_ROUTE_ADDED , AB_ROUTE_STATUS_CHANGED , AB_ROUTE_CONNECTED , AB_ROUTE_DISCONNECTED }
enum	ab_gp_train_update_type_t { AB_TRAIN_REGISTERED , AB_TRAIN_REMOVED , AB_TRAIN_POSITION , AB_TRAIN_MA_CHANGED , AB_TRAIN_EMERGENCY_REACTION_RAISED }

Functions
Route data - existence/mutators (real impl: AB/GP/db/ab_gp_db.c)
Reads go through ab_gp_db_get_route_context() below now (later session, on direct request: "it will be enough if GA can getTrainContext/getRouteContext; setters stay separate since they require validation") - the individual _get_status()/_get_used_in_ma()/ _get_type() getters this used to declare are gone.
bool	ab_gp_db_route_exists (const ab_gp_db_t *db, uint16_t route_id)
bool	ab_gp_db_route_add (ab_gp_db_t *db, uint16_t route_id, uint16_t start_signal, uint16_t end_signal)
	Adds a new route to db->routes[]. New entry starts fully idle: occupied=false, il_status=AB_GP_DB_ROUTE_IL_STATUS_UNKNOWN, used_in_ma=false, train_id=0. Purely mechanical - does NOT verify `route_id/start_signal/end_signal against any` site layout (that stays il/'s own business, ab_ga_il_route_verify(), called before this).
bool	ab_gp_db_route_remove (ab_gp_db_t *db, uint16_t route_id)
	Removes a tracked route from db->routes[], freeing its slot.
bool	ab_gp_db_route_set_status (ab_gp_db_t *db, uint16_t route_id, ab_gp_db_route_il_status_t status)
bool	ab_gp_db_route_set_type (ab_gp_db_t *db, uint16_t route_id, uint32_t route_type)
bool	ab_gp_db_route_set_fsm_state (ab_gp_db_t *db, uint16_t route_id, uint32_t fsm_state)
	Get/set the per-route FSM state (ab_ga_route_state_t, raw uint32_t - GA owns the value space, GP just stores it).
uint32_t	ab_gp_db_route_get_fsm_state (const ab_gp_db_t *db, uint16_t route_id)
bool	ab_gp_db_route_connect_train (ab_gp_db_t *db, uint16_t route_id, uint8_t train_id)
	Connects `route_id` to `train_id:` appends the route to that train's own route_ids[] and marks the route used_in_ma.
bool	ab_gp_db_route_disconnect_train (ab_gp_db_t *db, uint16_t route_id)
	Reverses ab_gp_db_route_connect_train(): clears the route's own used_in_ma/train_id and removes it from its owning train's route_ids[] (compacting the remaining entries down).
Train data (ab_gp_db_t-keyed, not ab_gp_train_session_t) - mutator +
one narrow read (real impl: AB/GP/train/ab_gp_train.c). _get_has_ma()/ab_gp_db_train_get_routes() are gone from this facade the same way every other single-field getter is - now fields on ab_gp_get_train_context() below. _get_last_position() is the one exception, kept: it is GP's own registered route validator (ab_gp_ga_register_init() below, ma_logic_adaptation.c's validate_route_assignment()) that calls it, and that callback only ever receives `db` as its context - no sessions[] is available there to build a full ab_gp_get_train_context() snapshot, so this one genuinely stays a standalone, db-only read.
bool	ab_gp_train_set_has_ma (ab_gp_db_t *db, uint8_t train_id, bool has_ma)
bool	ab_gp_train_get_last_position (const ab_gp_db_t db, uint8_t train_id, uint32_t out_nid_lrbg)
Route data - GA notification + one-shot read (real impl: AB/GP/db/ab_gp_db.c)
ONE subscription covers every route change (added/status-changed/ connected/disconnected) - see AB/GP/db/ab_gp_db.h's own "GA notification" doc for the firing rule, the fail-open/setup-phase- only contract, and why this collapsed from four registrations.
rte_status_t	ab_gp_db_register_route_context_notify (ab_gp_route_context_notify_fn fn, const void *context)
bool	ab_gp_db_get_route_context (const ab_gp_db_t db, uint16_t route_id, ab_gp_route_context_t out_ctx)
	One-shot pull equivalent of the push notification above - the SAME snapshot-building logic (real impl: ab_gp_db.c's own build_route_context(), shared with notify_route_context()), for a caller that just needs `route_id's` current state right now rather than reacting to a change. Replaces the individual ab_gp_db_route_get_status()/_get_used_in_ma()/_get_type() getters GA used to call one field at a time (later session, on direct request). Mutation still goes through the individual setters - this is READ-ONLY, deliberately.
Site geometry - remaining-MA-length computation (real impl:
AB/GP/ertms_procedures/ab_gp_proc_ma.c) - only GP has direct access to the physical segment/balise tables this needs (ab_siteGP.h); GA's own route.length_m alone cannot resolve how far into a route a train already is. Shared with the real ERTMS engine's own identical use (ab_gp_proc_ma_compute()/ _extend()) - implemented once, not duplicated per scheme.
uint32_t	ab_gp_proc_ma_remaining_length_m (const ab_site_ga_route_layout_t *route, uint32_t nid_lrbg, uint32_t d_lrbg_m)
	Computes the Movement Authority length actually REMAINING from a train's own last-KNOWN balise to `route's` end signal - a direct point-to-point distance along `route's` own segment chain from that balise's (`nid_lrbg`) own physical position to the end signal's own physical position, NOT "route->length_m minus however far the balise sits from the route's own START signal" - the two are NOT interchangeable (found live: an earlier version of this function computed the latter and got a real, confirmed-wrong answer - see the .c file's own implementation doc for the concrete counter-example). Measured from the balise, NOT from `nid_lrbg` plus `d_lrbg_m's` own distance past it - on direct instruction: MA length is anchored to the train's last KNOWN, site-data-backed reference point, not a continuously self-reported odometer offset past it (`d_lrbg_m` is accepted for a possible future use but not used in this computation today - see the .c file's own doc). A train connecting to (or being extended into) a route it is already partway through must NOT be granted the route's own full length regardless - found live: both this function's own caller below and the flat scheme's ab_ga_il_on_route_context_changed() (safeAPIRBC2oo2GA) were granting route->length_m unconditionally, regardless of the train's own reported position - a real overrun-risk shape (the train is told it has more track ahead of it than physically remains).
Train session data - mutators only (real impl: AB/GP/train/ab_gp_train.c)
Every read (in_use/d_lrbg/granted_length/ma_seq/ma_pending_send/ ctc_connected_sent/ctc_ma_granted_sent/ctc_ma_notify_pending) is now a field on ab_gp_get_train_context() below - these are the mutators only, since mutation still needs GP's own validation (the same direct instruction this whole consolidation follows).
bool	ab_gp_train_session_add_granted_length (ab_gp_train_session_t *sessions, uint8_t train_id, uint32_t delta)
bool	ab_gp_train_session_set_granted_length (ab_gp_train_session_t *sessions, uint8_t train_id, uint32_t granted_length)
bool	ab_gp_train_session_increment_ma_seq (ab_gp_train_session_t *sessions, uint8_t train_id)
bool	ab_gp_train_session_set_ma_pending_send (ab_gp_train_session_t *sessions, uint8_t train_id, bool pending)
bool	ab_gp_train_session_set_ma_acked (ab_gp_train_session_t *sessions, uint8_t train_id, bool acked)
bool	ab_gp_train_session_set_ctc_connected_sent (ab_gp_train_session_t *sessions, uint8_t train_id, bool sent)
bool	ab_gp_train_session_set_ctc_ma_granted_sent (ab_gp_train_session_t *sessions, uint8_t train_id, bool sent)
bool	ab_gp_train_session_set_ctc_ma_notify_pending (ab_gp_train_session_t *sessions, uint8_t train_id, bool pending)
Train data - GA notification + one-shot read (real impl: AB/GP/train/ab_gp_train.c)
ONE subscription covers every train change (registered/removed/ position/MA-changed/emergency-reaction-raised) - see AB/GP/train/ab_gp_train.h's own "GA notification" doc for the firing rule, the fail-open/setup-phase-only contract, and why this collapsed from two registrations.
rte_status_t	ab_gp_register_train_context_notify (ab_gp_train_context_notify_fn fn, const void *context)
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)
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)
Route<->train connect gate (real impl: AB/GP/ma_logic/ab_gp_logic.c)
See AB/GP/ma_logic/ab_gp_logic.h's own doc for the fail-safe default-deny contract - identical here.
rte_status_t	ab_gp_ga_register_init (ab_gp_logic_route_validator_fn fn, void *context)
The complete, explicit set of functions GP calls into GA with -
the reverse direction, deliberately kept as small as possible (later session, on direct request). Every one of these used to be a bare call GP made to a GA-owned function by name (which needed a matching stub in dummy_ga/dummy_ga.c, GP's own link-time-only stand-in for GA - see that file's own doc); all but ONE were converted to callback registrations instead (GA registers a handler/producer with GP at its own init time, through the SAME ab_ga_ma_adaptation_init() call below, and GP invokes it through the registered pointer - no bare GP->GA symbol reference at all, so dummy_ga needs no stub for any of these). ab_ga_ma_adaptation_init() itself is the one exception kept as a genuine bare call (GP still calls it once per channel, with real per-channel db/site/role_tag context a load-time constructor in GA could not receive) - declared HERE, not in GA's own public header, so GP's call site and dummy_ga's stub both see it through this one facade, the same posture every other declaration in this file already takes.
rte_status_t	ab_ga_ma_adaptation_init (ab_gp_train_session_t sessions, ab_gp_db_t db, rte_example_site_t site, const char *role_tag)
	GA's own single entry point - registers this channel's route- connection validator (ab_gp_ga_register_init() above) and its dispatch module's context-notify/envelope-handler/output- producer registrations (all declared below) with GP. Real impl: AB/ma_logic_adaptation/ab_ga_ma_adaptation.c. Called once from AB/GP/com/ab_gp_channel.c's own ab_gp_channel_ga_setup(), before the setup phase locks.

Shunting gate (real impl: AB/GP/ma_logic/ab_gp_logic.c)
GA's veto over a Msg 130 Request for Shunting (Subset-026 5.6). Same default-deny, setup-phase-only contract as the route gate above.
#define	AB_GP_LOGIC_SHUNTING_VALIDATOR_FN_DEFINED
typedef bool(*)	ab_gp_logic_shunting_validator_fn(void *context, uint8_t train_id)
rte_status_t	ab_gp_ga_register_shunting_validator (ab_gp_logic_shunting_validator_fn fn, void *context)

IL envelope handling - GA registers, GP dispatches through it
(real impl: AB/GP/main/pre_execute.c's own registry, AB/il/ab_ga_il.c's own handler). Replaces the old bare ab_ga_il_apply_envelope() call - "pure GA" now, on direct request: GP no longer names this function at all, it only ever invokes whatever GA registered.
#define	AB_GP_IL_ENVELOPE_HANDLER_FN_DEFINED
typedef bool(*)	ab_gp_il_envelope_handler_fn(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)
rte_status_t	ab_gp_register_il_envelope_handler (ab_gp_il_envelope_handler_fn fn, const void *context)

IL/CTC pending-output draining - GA registers a producer, GP
drains it every cycle (real impl: AB/GP/main/post_execute.c's own registries, AB/il/ab_ga_il.c's/AB/ctc/ab_ga_ctc.c's own producers). Replaces the old bare ab_ga_il_build_outputs()/ab_ga_ctc_build_outputs() calls - GP names neither, it only invokes whatever GA registered. GP owns the pending-output slot SHAPE (below) rather than GA, for the same reason it owns ab_gp_route_context_t/ab_gp_train_context_t - the consumer's own struct, not the producer's.
#define	AB_GP_IL_PENDING_OUTPUT_T_DEFINED
#define	AB_GP_IL_MAX_PENDING_OUTPUTS (RTE_EXAMPLE_MAX_ROUTES * 2U)
#define	AB_GP_IL_OUTPUT_PRODUCER_FN_DEFINED
#define	AB_GP_CTC_PENDING_OUTPUT_T_DEFINED
#define	AB_GP_CTC_MAX_PENDING_OUTPUTS ((uint8_t)(RTE_EXAMPLE_MAX_TRAINS * 3U))
#define	AB_GP_CTC_OUTPUT_PRODUCER_FN_DEFINED
typedef uint8_t(*)	ab_gp_il_output_producer_fn(const void *context, ab_gp_il_pending_output_t out[AB_GP_IL_MAX_PENDING_OUTPUTS])
typedef void(*)	ab_gp_il_output_confirm_fn(const void *context)
typedef uint8_t(*)	ab_gp_ctc_output_producer_fn(const void *context, ab_gp_ctc_pending_output_t out[AB_GP_CTC_MAX_PENDING_OUTPUTS])
typedef void(*)	ab_gp_ctc_output_confirm_fn(const void *context)
rte_status_t	ab_gp_register_il_output_producer (ab_gp_il_output_producer_fn fn, ab_gp_il_output_confirm_fn confirm_fn, const void *context)
rte_status_t	ab_gp_register_ctc_output_producer (ab_gp_ctc_output_producer_fn fn, ab_gp_ctc_output_confirm_fn confirm_fn, const void *context)

Detailed Description

THE single door GA (safeAPIRBC2oo2GA, a separate shared-library project) uses to reach GP - GP exports this header (GA reaches it header-only, via RTE_RBC2OO2GP_DIR, same sibling-source posture as common/) so GA's independent build can see every function signature it is allowed to call.

Later session: back to plain extern declarations + bare calls, replacing the function-pointer-struct handoff this header used to describe (ab_gp_ga_interface_t, populated once by ab_gp_ga_interface_populate() and handed to GA at its own init call - removed). That struct existed to solve one problem: GP-exe / GA-.so couldn't link both directions at once with ordinary symbol resolution. Per direct instruction, GP itself became a shared library too (librte_gp, see CMakeLists.txt's own doc and src/application/AB/GP/main/launcher_main.c) specifically so this problem has a different fix: GA's own build now links against a real, if empty, DUMMY librte_gp stub (safeAPIRBC2oo2GA/dummy_gp/, same install_name/SONAME as this project's real one) purely to satisfy the linker at GA's build time (Mach-O refuses an unresolved symbol in a dylib even where ELF would tolerate it) - at actual process load time the REAL librte_gp (this project's own build output, co-located with GA's own .so in dist/<platform>/lib/) is what's actually present on disk and is what the OS dynamic linker resolves these symbols against, ordinary symbol resolution, no proxy struct. See safeAPIRBC2oo2GA/CLAUDE.md's own "GP<->GA boundary" section for the full design and the load-bearing deploy-time requirement this trades in (the real librte_gp must be what actually ships - a safety-process note, not a blocker).

Two things this header does NOT expose, by design (unchanged from before the split):

ab_gp_db_t/ab_gp_train_session_t are forward-declared here as INCOMPLETE types (struct ab_gp_db_s/struct train_session_s, tagged for exactly this reason in AB/GP/db/ab_gp_db.h/AB/GP/train/ab_gp_train.h) - GA can hold and pass ab_gp_db_t */ab_gp_train_session_t * pointers, but the C compiler itself refuses to compile a db->field or sessions[i].field expression inside GA's own translation units, since GA never sees either struct's body. GA reads/writes fields only through the functions declared below - real, compiler- enforced encapsulation, not just a documented convention.
GP's own com/ (transport), main/ (composition root), ma_logic/'s own cyclic sweep internals: GA has no business with any of these and none of it is re-declared here.

Every declaration below is copied verbatim (identical signature) from its real, implementing function - AB/GP/db/ab_gp_db.c/.h, AB/GP/train/ab_gp_train.c/.h, AB/GP/ma_logic/ab_gp_logic.c/.h - which already declare these same functions for GP's own internal callers; this header re-declares (never redefines) the subset GA is allowed to call, so a stray extra GP-internal function never becomes reachable from GA just because it happens to sit in the same source file.

AB/SA/site/ab_site.h (now safeAPIRBC2oo2SA's own public header) and common/'s own headers (rbc_wire_types.h, site_config.h) are NOT routed through here - they are not "another GP part" - GA #includes those directly (SA the same way GP does; common/ stays GP-internal since it has GP-specific config GA doesn't need beyond the one constant below).

Every type/typedef re-declared below is wrapped in its own #ifndef ..._DEFINED guard, matched by an IDENTICAL guard around the real definition in its own owning header (AB/GP/db/ab_gp_db.h, AB/GP/train/ab_gp_train.h, AB/GP/ma_logic/ab_gp_logic.h). This is what makes it safe for the SAME translation unit to include both this facade AND a real GP header - com/'s ab_gp_channel.c does exactly that (it needs the full, non-opaque types for its own ctx->db/ctx->sessions[] storage).

Definition in file ga_interface.h.

Macro Definition Documentation

◆ RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN

#define RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN 4U

Definition at line 92 of file ga_interface.h.

◆ AB_GP_DB_T_DEFINED

#define AB_GP_DB_T_DEFINED

Opaque to GA - see this file's own header doc. Real definition: AB/GP/db/ab_gp_db.h.

Definition at line 98 of file ga_interface.h.

◆ TRAIN_SESSION_T_DEFINED

#define TRAIN_SESSION_T_DEFINED

Opaque to GA - see this file's own header doc. Real definition: AB/GP/train/ab_gp_train.h.

Definition at line 105 of file ga_interface.h.

◆ AB_GP_DB_ROUTE_IL_STATUS_T_DEFINED

#define AB_GP_DB_ROUTE_IL_STATUS_T_DEFINED

Not a struct - a closed set of named integers carries no layout to hide, so this is the one GP-owned type GA sees in full. Real definition: AB/GP/db/ab_gp_db.h.

Definition at line 113 of file ga_interface.h.

◆ AB_GP_ROUTE_UPDATE_TYPE_T_DEFINED

#define AB_GP_ROUTE_UPDATE_TYPE_T_DEFINED

Real definitions: AB/GP/db/ab_gp_db.h - see that header's own doc for why this is ONE notification (was four) and what each ab_gp_route_update_type_t value means.

Definition at line 127 of file ga_interface.h.

◆ AB_GP_ROUTE_CONTEXT_T_DEFINED

#define AB_GP_ROUTE_CONTEXT_T_DEFINED

Definition at line 138 of file ga_interface.h.

◆ AB_GP_DB_ROUTE_NOTIFY_FN_DEFINED

#define AB_GP_DB_ROUTE_NOTIFY_FN_DEFINED

Definition at line 152 of file ga_interface.h.

◆ AB_GP_TRAIN_UPDATE_TYPE_T_DEFINED

#define AB_GP_TRAIN_UPDATE_TYPE_T_DEFINED

Real definitions: AB/GP/train/ab_gp_train.h - see that header's own doc for why this is ONE notification (was two) and what each ab_gp_train_update_type_t value means.

Definition at line 161 of file ga_interface.h.

◆ AB_GP_TRAIN_CONTEXT_T_DEFINED

#define AB_GP_TRAIN_CONTEXT_T_DEFINED

Definition at line 173 of file ga_interface.h.

◆ AB_GP_TRAIN_NOTIFY_FN_DEFINED

#define AB_GP_TRAIN_NOTIFY_FN_DEFINED

Definition at line 199 of file ga_interface.h.

◆ AB_GP_LOGIC_ROUTE_VALIDATOR_FN_DEFINED

#define AB_GP_LOGIC_ROUTE_VALIDATOR_FN_DEFINED

Definition at line 205 of file ga_interface.h.

◆ AB_GP_LOGIC_SHUNTING_VALIDATOR_FN_DEFINED

#define AB_GP_LOGIC_SHUNTING_VALIDATOR_FN_DEFINED

Definition at line 326 of file ga_interface.h.

◆ AB_GP_IL_ENVELOPE_HANDLER_FN_DEFINED

#define AB_GP_IL_ENVELOPE_HANDLER_FN_DEFINED

Definition at line 392 of file ga_interface.h.

◆ AB_GP_IL_PENDING_OUTPUT_T_DEFINED

#define AB_GP_IL_PENDING_OUTPUT_T_DEFINED

Definition at line 415 of file ga_interface.h.

◆ AB_GP_IL_MAX_PENDING_OUTPUTS

#define AB_GP_IL_MAX_PENDING_OUTPUTS (RTE_EXAMPLE_MAX_ROUTES * 2U)

Definition at line 428 of file ga_interface.h.

◆ AB_GP_IL_OUTPUT_PRODUCER_FN_DEFINED

#define AB_GP_IL_OUTPUT_PRODUCER_FN_DEFINED

Definition at line 431 of file ga_interface.h.

◆ AB_GP_CTC_PENDING_OUTPUT_T_DEFINED

#define AB_GP_CTC_PENDING_OUTPUT_T_DEFINED

Definition at line 454 of file ga_interface.h.

◆ AB_GP_CTC_MAX_PENDING_OUTPUTS

#define AB_GP_CTC_MAX_PENDING_OUTPUTS ((uint8_t)(RTE_EXAMPLE_MAX_TRAINS * 3U))

Definition at line 462 of file ga_interface.h.

◆ AB_GP_CTC_OUTPUT_PRODUCER_FN_DEFINED

#define AB_GP_CTC_OUTPUT_PRODUCER_FN_DEFINED

Definition at line 465 of file ga_interface.h.

◆ AB_GA_CHECKPOINT_MARK

#define AB_GA_CHECKPOINT_MARK ( )

Value:

RTE_CHECKPOINT_MARK()

Records a checkpoint mark for this GA call site (ADR-034). GA links rte::appmanager directly now (no more proxying through GP) - this is a thin, GA-side alias for the framework's own RTE_CHECKPOINT_MARK() (rte/app/appmanager/rte_appmanager.h), kept as a distinct name only so a grep for AB_GA_CHECKPOINT_MARK still finds every GA call site the way it always has.

Definition at line 487 of file ga_interface.h.

Typedef Documentation

◆ ab_gp_db_t

typedef struct ab_gp_db_s ab_gp_db_t

Definition at line 99 of file ga_interface.h.

◆ ab_gp_train_session_t

typedef struct train_session_s ab_gp_train_session_t

Definition at line 106 of file ga_interface.h.

◆ ab_gp_train_context_notify_fn

typedef void(*) ab_gp_train_context_notify_fn(const void *context, const ab_gp_train_context_t *ctx, ab_gp_train_update_type_t update_type)

Definition at line 200 of file ga_interface.h.

◆ ab_gp_logic_route_validator_fn

typedef bool(*) ab_gp_logic_route_validator_fn(void *context, uint16_t route_id, uint8_t train_id)

Definition at line 206 of file ga_interface.h.

◆ ab_gp_logic_shunting_validator_fn

typedef bool(*) ab_gp_logic_shunting_validator_fn(void *context, uint8_t train_id)

Returns: true if GA allows train_id to enter Shunting mode now. Must be a pure function of replicated state (db, sessions), so channels A and B reach the same answer.

Definition at line 327 of file ga_interface.h.

◆ ab_gp_il_envelope_handler_fn

typedef bool(*) ab_gp_il_envelope_handler_fn(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)

Definition at line 393 of file ga_interface.h.

◆ ab_gp_il_output_producer_fn

typedef uint8_t(*) ab_gp_il_output_producer_fn(const void *context, ab_gp_il_pending_output_t out[AB_GP_IL_MAX_PENDING_OUTPUTS])

Definition at line 432 of file ga_interface.h.

◆ ab_gp_il_output_confirm_fn

typedef void(*) ab_gp_il_output_confirm_fn(const void *context)

Called ONLY on the cycle post_execute.c actually forwards the outputs fn just built to C (should_forward_to_c true) - never on a cycle where they were built but discarded (cross-compare hasn't AGREED on this brand-new decision yet - see post_execute.c's own doc on why that lags by at least one cycle). fn itself must NOT clear its own pending-output state as a side effect of building - only this confirms the build was genuinely consumed, so an unforwarded cycle's pending state survives and gets rebuilt+retried next cycle instead of being silently lost. Real bug this fixes: ab_gp_train.c's own ma_pending_send/etc. had exactly this problem (fixed directly, no confirm callback needed there - those flags live in GP's own ctx->sessions, reachable from post_execute.c already); IL's/CTC's own pending-output queues are GA-private statics GP cannot reach directly, hence this callback.

Definition at line 448 of file ga_interface.h.

◆ ab_gp_ctc_output_producer_fn

typedef uint8_t(*) ab_gp_ctc_output_producer_fn(const void *context, ab_gp_ctc_pending_output_t out[AB_GP_CTC_MAX_PENDING_OUTPUTS])

Definition at line 466 of file ga_interface.h.

◆ ab_gp_ctc_output_confirm_fn

typedef void(*) ab_gp_ctc_output_confirm_fn(const void *context)

Same contract as ab_gp_il_output_confirm_fn above - called only once this cycle's built CTC outputs are actually forwarded to C.

Definition at line 470 of file ga_interface.h.

Enumeration Type Documentation

◆ ab_gp_db_route_il_status_t

enum ab_gp_db_route_il_status_t

Enumerator
AB_GP_DB_ROUTE_IL_STATUS_UNKNOWN
AB_GP_DB_ROUTE_IL_STATUS_FREE
AB_GP_DB_ROUTE_IL_STATUS_RESERVED
AB_GP_DB_ROUTE_IL_STATUS_LOCKED

Definition at line 114 of file ga_interface.h.

◆ ab_gp_route_update_type_t

enum ab_gp_route_update_type_t

Enumerator
AB_ROUTE_ADDED
AB_ROUTE_STATUS_CHANGED
AB_ROUTE_CONNECTED
AB_ROUTE_DISCONNECTED

Definition at line 128 of file ga_interface.h.

◆ ab_gp_train_update_type_t

enum ab_gp_train_update_type_t

Enumerator
AB_TRAIN_REGISTERED
AB_TRAIN_REMOVED
AB_TRAIN_POSITION
AB_TRAIN_MA_CHANGED
AB_TRAIN_EMERGENCY_REACTION_RAISED

Definition at line 162 of file ga_interface.h.

Function Documentation

◆ ab_gp_db_route_exists()

bool ab_gp_db_route_exists	(	const ab_gp_db_t *	db,
		uint16_t	route_id )

Returns: true if route_id is already tracked in db->routes[].

Definition at line 253 of file ab_gp_db.c.

◆ ab_gp_db_route_add()

bool ab_gp_db_route_add	(	ab_gp_db_t *	db,
		uint16_t	route_id,
		uint16_t	start_signal,
		uint16_t	end_signal )

Adds a new route to db->routes[]. New entry starts fully idle: occupied=false, il_status=AB_GP_DB_ROUTE_IL_STATUS_UNKNOWN, used_in_ma=false, train_id=0. Purely mechanical - does NOT verify route_id/start_signal/end_signal against any site layout (that stays il/'s own business, ab_ga_il_route_verify(), called before this).

Returns: false if route_id is already tracked (call ab_gp_db_route_remove() first to replace it), or db->routes[] (RTE_EXAMPLE_MAX_ROUTES) is full.

Definition at line 258 of file ab_gp_db.c.

◆ ab_gp_db_route_remove()

bool ab_gp_db_route_remove	(	ab_gp_db_t *	db,
		uint16_t	route_id )

Removes a tracked route from db->routes[], freeing its slot.

Returns: false if route_id is not tracked, or it is still used_in_ma (ab_gp_db_route_disconnect_train() first - a route actively backing a train's Movement Authority is never silently dropped).

Definition at line 291 of file ab_gp_db.c.

◆ ab_gp_db_route_set_status()

bool ab_gp_db_route_set_status	(	ab_gp_db_t *	db,
		uint16_t	route_id,
		ab_gp_db_route_il_status_t	status )

Returns: false if route_id is not tracked; otherwise true with the field updated. Does not touch occupied (a separate, non-IL-sourced concept - see ab_gp_db_route_t's own doc).

Definition at line 310 of file ab_gp_db.c.

◆ ab_gp_db_route_set_type()

bool ab_gp_db_route_set_type	(	ab_gp_db_t *	db,
		uint16_t	route_id,
		uint32_t	route_type )

Returns: false if route_id is not tracked; otherwise true with the field updated (rbc_route_type_t value, raw uint32_t) - IL's latest report always wins, no notify (route_type is not observed by anything yet - unlike il_status, which already has GA subscribers).

Definition at line 335 of file ab_gp_db.c.

◆ ab_gp_db_route_set_fsm_state()

bool ab_gp_db_route_set_fsm_state	(	ab_gp_db_t *	db,
		uint16_t	route_id,
		uint32_t	fsm_state )

Get/set the per-route FSM state (ab_ga_route_state_t, raw uint32_t - GA owns the value space, GP just stores it).

Returns: set: false if route_id is not tracked, else true. get: the stored value, or AB_GA_ROUTE_STATE_NO_ROUTE (0) for an unknown route.

Definition at line 347 of file ab_gp_db.c.

◆ ab_gp_db_route_get_fsm_state()

uint32_t ab_gp_db_route_get_fsm_state	(	const ab_gp_db_t *	db,
		uint16_t	route_id )

Definition at line 359 of file ab_gp_db.c.

◆ ab_gp_db_route_connect_train()

bool ab_gp_db_route_connect_train	(	ab_gp_db_t *	db,
		uint16_t	route_id,
		uint8_t	train_id )

Connects route_id to train_id: appends the route to that train's own route_ids[] and marks the route used_in_ma.

Parameters

db	AB's own Train/Route database. Must not be NULL.
route_id	Must already be tracked (db->routes[], e.g. via ab_gp_db_route_add() - this function does not add it).
train_id	1..RTE_EXAMPLE_MAX_TRAINS.

Returns: false if route_id is not tracked, train_id is out of range, the route is already used_in_ma (disconnect first, never silently reassigned), it is already in that same train's route_ids[], or that train's route_ids[] (RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN) is full. true once connected.

Definition at line 150 of file ab_gp_db.c.

◆ ab_gp_db_route_disconnect_train()

bool ab_gp_db_route_disconnect_train	(	ab_gp_db_t *	db,
		uint16_t	route_id )

Reverses ab_gp_db_route_connect_train(): clears the route's own used_in_ma/train_id and removes it from its owning train's route_ids[] (compacting the remaining entries down).

Returns: false if route_id is not tracked, or it is not currently used_in_ma (nothing to disconnect).

Definition at line 197 of file ab_gp_db.c.

◆ ab_gp_train_set_has_ma()

bool ab_gp_train_set_has_ma	(	ab_gp_db_t *	db,
		uint8_t	train_id,
		bool	has_ma )

Definition at line 502 of file ab_gp_train.c.

◆ ab_gp_train_get_last_position()

bool ab_gp_train_get_last_position	(	const ab_gp_db_t *	db,
		uint8_t	train_id,
		uint32_t *	out_nid_lrbg )

Definition at line 522 of file ab_gp_train.c.

◆ ab_gp_db_register_route_context_notify()

rte_status_t ab_gp_db_register_route_context_notify	(	ab_gp_route_context_notify_fn	fn,
		const void *	context )

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_DB_MAX_ROUTE_CONTEXT_SUBSCRIBERS are already registered.

Definition at line 25 of file ab_gp_db.c.

◆ ab_gp_db_get_route_context()

bool ab_gp_db_get_route_context	(	const ab_gp_db_t *	db,
		uint16_t	route_id,
		ab_gp_route_context_t *	out_ctx )

One-shot pull equivalent of the push notification above - the SAME snapshot-building logic (real impl: ab_gp_db.c's own build_route_context(), shared with notify_route_context()), for a caller that just needs route_id's current state right now rather than reacting to a change. Replaces the individual ab_gp_db_route_get_status()/_get_used_in_ma()/_get_type() getters GA used to call one field at a time (later session, on direct request). Mutation still goes through the individual setters - this is READ-ONLY, deliberately.

Returns: false if route_id is not tracked; otherwise true with *out_ctx fully populated.

Definition at line 323 of file ab_gp_db.c.

◆ ab_gp_proc_ma_remaining_length_m()

uint32_t ab_gp_proc_ma_remaining_length_m	(	const ab_site_ga_route_layout_t *	route,
		uint32_t	nid_lrbg,
		uint32_t	d_lrbg_m )

Computes the Movement Authority length actually REMAINING from a train's own last-KNOWN balise to route's end signal - a direct point-to-point distance along route's own segment chain from that balise's (nid_lrbg) own physical position to the end signal's own physical position, NOT "route->length_m minus however far the balise sits from the route's own START signal" - the two are NOT interchangeable (found live: an earlier version of this function computed the latter and got a real, confirmed-wrong answer - see the .c file's own implementation doc for the concrete counter-example). Measured from the balise, NOT from nid_lrbg plus d_lrbg_m's own distance past it - on direct instruction: MA length is anchored to the train's last KNOWN, site-data-backed reference point, not a continuously self-reported odometer offset past it (d_lrbg_m is accepted for a possible future use but not used in this computation today - see the .c file's own doc). A train connecting to (or being extended into) a route it is already partway through must NOT be granted the route's own full length regardless - found live: both this function's own caller below and the flat scheme's ab_ga_il_on_route_context_changed() (safeAPIRBC2oo2GA) were granting route->length_m unconditionally, regardless of the train's own reported position - a real overrun-risk shape (the train is told it has more track ahead of it than physically remains).

Falls back to the FULL route->length_m (the previously unconditional behavior) if nid_lrbg cannot be resolved to a balise on route's own segment chain at all (e.g. no position report yet, or the reported balise belongs to a different route/segment entirely) - never guesses past what site data can actually support; this is also the correct fallback for a genuine forward extension (the additional route's own balises legitimately do not include the train's current one yet).

Implemented once, here, since only GP has direct access to the physical segment/balise tables (ab_siteGP.h, ab_site_get_segment()/ab_site_get_balise()) this computation needs - GA's own ab_site_ga_route_layout_t alone (length_m, opaque segment_ids[]) cannot do it. Exposed to GA via ga_interface.h for the flat scheme's own identical use.

Parameters

route	The route being granted/extended - GA's own ab_site_ga_route_layout_t.
nid_lrbg	Train's own last-reported NID_LRBG (M136/flat scheme position report alike) - the balise this computation is anchored to.
d_lrbg_m	Train's own last-reported D_LRBG (distance past `nid_lrbg`, meters) - accepted but NOT used in this computation, see this function's own doc above.

Returns: Remaining MA length in meters - never more than route->length_m, never negative (clamped to 0 if the train's own reported position is already past the route's own end).

Definition at line 53 of file ab_gp_proc_ma.c.

◆ ab_gp_train_session_add_granted_length()

bool ab_gp_train_session_add_granted_length	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id,
		uint32_t	delta )

◆ ab_gp_train_session_set_granted_length()

bool ab_gp_train_session_set_granted_length	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id,
		uint32_t	granted_length )

◆ ab_gp_train_session_increment_ma_seq()

bool ab_gp_train_session_increment_ma_seq	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id )

◆ ab_gp_train_session_set_ma_pending_send()

bool ab_gp_train_session_set_ma_pending_send	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id,
		bool	pending )

◆ ab_gp_train_session_set_ma_acked()

bool ab_gp_train_session_set_ma_acked	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id,
		bool	acked )

◆ ab_gp_train_session_set_ctc_connected_sent()

bool ab_gp_train_session_set_ctc_connected_sent	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id,
		bool	sent )

◆ ab_gp_train_session_set_ctc_ma_granted_sent()

bool ab_gp_train_session_set_ctc_ma_granted_sent	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id,
		bool	sent )

◆ ab_gp_train_session_set_ctc_ma_notify_pending()

bool ab_gp_train_session_set_ctc_ma_notify_pending	(	ab_gp_train_session_t *	sessions,
		uint8_t	train_id,
		bool	pending )

◆ ab_gp_register_train_context_notify()

rte_status_t ab_gp_register_train_context_notify	(	ab_gp_train_context_notify_fn	fn,
		const void *	context )

Definition at line 39 of file ab_gp_train.c.

◆ ab_gp_get_train_context()

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 )

◆ ab_gp_train_notify_context_changed()

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 )

Explicit multi-step-change trigger - see ab_gp_train_notify_context_changed()'s own doc, ab_gp_train.h.

◆ ab_gp_ga_register_init()

rte_status_t ab_gp_ga_register_init	(	ab_gp_logic_route_validator_fn	fn,
		void *	context )

Global functions

Definition at line 46 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 )

Definition at line 69 of file ab_gp_logic.c.

◆ ab_ga_ma_adaptation_init()

rte_status_t ab_ga_ma_adaptation_init	(	ab_gp_train_session_t *	sessions,
		ab_gp_db_t *	db,
		rte_example_site_t	site,
		const char *	role_tag )

GA's own single entry point - registers this channel's route- connection validator (ab_gp_ga_register_init() above) and its dispatch module's context-notify/envelope-handler/output- producer registrations (all declared below) with GP. Real impl: AB/ma_logic_adaptation/ab_ga_ma_adaptation.c. Called once from AB/GP/com/ab_gp_channel.c's own ab_gp_channel_ga_setup(), before the setup phase locks.

Parameters

sessions	This channel's own Train session table (opaque to GA) - retained by address (module-static, one GA instance per process/channel) for the CTC output producer/IL envelope handler this call registers. Must outlive the whole process, same lifetime requirement as `db` below.
db	This channel's own Train/Route database (opaque to GA) - retained by address as every registered handler/validator's own context. Must outlive every future call GP makes through anything GA registers here - i.e. must be long-lived storage (ab_gp_channel_context_t's own ctx->db).
site	This channel's own site - used in this function's own setup-failure log line.
role_tag	This channel's own "A/WEST" etc. tag.

Returns: RTE_STATUS_OK on success; the first failing registration's own status otherwise.

◆ ab_gp_register_il_envelope_handler()

rte_status_t ab_gp_register_il_envelope_handler	(	ab_gp_il_envelope_handler_fn	fn,
		const void *	context )

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 the one slot is already taken (one handler per channel, same as ab_gp_ga_register_init()).

Definition at line 28 of file ab_gp_ga_hooks.c.

◆ ab_gp_register_il_output_producer()

rte_status_t ab_gp_register_il_output_producer	(	ab_gp_il_output_producer_fn	fn,
		ab_gp_il_output_confirm_fn	confirm_fn,
		const void *	context )

Definition at line 76 of file ab_gp_ga_hooks.c.

◆ ab_gp_register_ctc_output_producer()

rte_status_t ab_gp_register_ctc_output_producer	(	ab_gp_ctc_output_producer_fn	fn,
		ab_gp_ctc_output_confirm_fn	confirm_fn,
		const void *	context )

Definition at line 126 of file ab_gp_ga_hooks.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Shunting gate (real impl: AB/GP/ma_logic/ab_gp_logic.c)

IL envelope handling - GA registers, GP dispatches through it

IL/CTC pending-output draining - GA registers a producer, GP

Detailed Description

Macro Definition Documentation

◆ RTE_EXAMPLE_MAX_ROUTES_PER_TRAIN

◆ AB_GP_DB_T_DEFINED

◆ TRAIN_SESSION_T_DEFINED

◆ AB_GP_DB_ROUTE_IL_STATUS_T_DEFINED

◆ AB_GP_ROUTE_UPDATE_TYPE_T_DEFINED

◆ AB_GP_ROUTE_CONTEXT_T_DEFINED

◆ AB_GP_DB_ROUTE_NOTIFY_FN_DEFINED

◆ AB_GP_TRAIN_UPDATE_TYPE_T_DEFINED

◆ AB_GP_TRAIN_CONTEXT_T_DEFINED

◆ AB_GP_TRAIN_NOTIFY_FN_DEFINED

◆ AB_GP_LOGIC_ROUTE_VALIDATOR_FN_DEFINED

◆ AB_GP_LOGIC_SHUNTING_VALIDATOR_FN_DEFINED

◆ AB_GP_IL_ENVELOPE_HANDLER_FN_DEFINED

◆ AB_GP_IL_PENDING_OUTPUT_T_DEFINED

◆ AB_GP_IL_MAX_PENDING_OUTPUTS

◆ AB_GP_IL_OUTPUT_PRODUCER_FN_DEFINED

◆ AB_GP_CTC_PENDING_OUTPUT_T_DEFINED

◆ AB_GP_CTC_MAX_PENDING_OUTPUTS

◆ AB_GP_CTC_OUTPUT_PRODUCER_FN_DEFINED

◆ AB_GA_CHECKPOINT_MARK

Typedef Documentation

◆ ab_gp_db_t

◆ ab_gp_train_session_t

◆ ab_gp_train_context_notify_fn

◆ ab_gp_logic_route_validator_fn

◆ ab_gp_logic_shunting_validator_fn

◆ ab_gp_il_envelope_handler_fn

◆ ab_gp_il_output_producer_fn

◆ ab_gp_il_output_confirm_fn

◆ ab_gp_ctc_output_producer_fn

◆ ab_gp_ctc_output_confirm_fn

Enumeration Type Documentation

◆ ab_gp_db_route_il_status_t

◆ ab_gp_route_update_type_t

◆ ab_gp_train_update_type_t

Function Documentation

◆ ab_gp_db_route_exists()

◆ ab_gp_db_route_add()

◆ ab_gp_db_route_remove()

◆ ab_gp_db_route_set_status()

◆ ab_gp_db_route_set_type()

◆ ab_gp_db_route_set_fsm_state()

◆ ab_gp_db_route_get_fsm_state()

◆ ab_gp_db_route_connect_train()

◆ ab_gp_db_route_disconnect_train()

◆ ab_gp_train_set_has_ma()

◆ ab_gp_train_get_last_position()

◆ ab_gp_db_register_route_context_notify()

◆ ab_gp_db_get_route_context()

◆ ab_gp_proc_ma_remaining_length_m()

◆ ab_gp_train_session_add_granted_length()

◆ ab_gp_train_session_set_granted_length()

◆ ab_gp_train_session_increment_ma_seq()

◆ ab_gp_train_session_set_ma_pending_send()

◆ ab_gp_train_session_set_ma_acked()

◆ ab_gp_train_session_set_ctc_connected_sent()

◆ ab_gp_train_session_set_ctc_ma_granted_sent()

◆ ab_gp_train_session_set_ctc_ma_notify_pending()

◆ ab_gp_register_train_context_notify()

◆ ab_gp_get_train_context()

◆ ab_gp_train_notify_context_changed()

◆ ab_gp_ga_register_init()

◆ ab_gp_ga_register_shunting_validator()

◆ ab_ga_ma_adaptation_init()

◆ ab_gp_register_il_envelope_handler()

◆ ab_gp_register_il_output_producer()

◆ ab_gp_register_ctc_output_producer()