Mechanical route<->train connect/disconnect - see ab_gp_db.h's own "Mechanical route<->train connect/disconnect" doc for why this logic lives here rather than in il/. More...

#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"

Include dependency graph for ab_gp_db.c:

Functions
	RTE_DECLARE_CALLBACK_LIST (ab_gp_db_route_context_list_t, ab_gp_route_context_notify_fn, AB_GP_DB_MAX_ROUTE_CONTEXT_SUBSCRIBERS)
rte_status_t	ab_gp_db_register_route_context_notify (ab_gp_route_context_notify_fn fn, const void *context)
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)
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)
static int	find_route_index (const ab_gp_db_t *db, uint16_t route_id)
static int	find_free_route_slot (const ab_gp_db_t *db)
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).
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_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.
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)
uint8_t	ab_gp_db_route_get_count (const ab_gp_db_t *db)
	Returns total number of active routes currently in the GP database.
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)
	Retrieves route snapshot by table index for GA/GP route list synchronization.
bool	ab_gp_db_train_is_connected (const ab_gp_db_t *db, uint8_t train_id)
	Checks if a train has an active connection session in the DB.
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)
	Retrieves routes currently allocated to a train.
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)
	Encodes the full route and train database into a deterministic wire format.
rte_status_t	ab_gp_db_decode (ab_gp_db_t db, const uint8_t in_bytes, uint32_t in_size)
	Decodes the full route and train database from a deterministic wire format.

Variables
static ab_gp_db_route_context_list_t	g_route_context_subscribers

Detailed Description

Mechanical route<->train connect/disconnect - see ab_gp_db.h's own "Mechanical route<->train connect/disconnect" doc for why this logic lives here rather than in il/.

Definition in file ab_gp_db.c.

Function Documentation

◆ RTE_DECLARE_CALLBACK_LIST()

RTE_DECLARE_CALLBACK_LIST	(	ab_gp_db_route_context_list_t	,
		ab_gp_route_context_notify_fn	,
		AB_GP_DB_MAX_ROUTE_CONTEXT_SUBSCRIBERS	)

◆ 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.

◆ build_route_context()

void build_route_context	(	const ab_gp_db_t *	db,
		int	route_idx,
		uint8_t	train_id,
		ab_gp_route_context_t *	out_ctx )

static

Builds this route's own current-state snapshot - shared by notify_route_context() (push) and the public ab_gp_db_get_route_context() (pull) below - one builder, two ways to reach it (later session, on direct request). route_idx must already be a valid db->routes[] index (every caller resolves it via find_route_index() first). train_id is the caller's OWN explicit value, not re-derived from db->routes[route_idx].train_id - the disconnect call site in particular already clears that field before notifying (same capture-before-clear discipline the old notify_route_disconnected() relied on - a real subscriber, il_on_route_disconnected(), needs the train that WAS connected, which reading the live (already-cleared) struct here would lose); the pull path (ab_gp_db_get_route_context()) just passes the route's own live train_id through instead, since there is no clear-before-read race there.

Definition at line 65 of file ab_gp_db.c.

◆ notify_route_context()

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 )

static

Fires this route's own current-state snapshot (build_route_context() above) to every subscriber - the ONE notify path every route mutation below now goes through (was four separate notify_route_*() helpers, one per old notify type - collapsed on direct request, see this file's own module doc).

Definition at line 83 of file ab_gp_db.c.

◆ find_route_index()

int find_route_index	(	const ab_gp_db_t *	db,
		uint16_t	route_id )

static

Returns: index of db->routes[] holding route_id, or -1 if not found. -1, not 0, means "not found" here (0 is a valid array index) - route_id itself is what uses 0 as its own "unused" sentinel (see this struct's own doc). The ONE place left that walks db->routes[] directly - every getter/setter below goes through this, and nothing outside this file ever does (GA/il's own former copy of this exact helper is gone now that il/'s route_add()/_remove()/_set_status() are thin wrappers here instead of touching db->routes[] itself).

Definition at line 110 of file ab_gp_db.c.

◆ find_free_route_slot()

int find_free_route_slot ( const ab_gp_db_t * db )

static

Returns: index of the first unused (id == 0) db->routes[] slot, or -1 if the table is full.

Definition at line 131 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_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_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_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_get_count()

uint8_t ab_gp_db_route_get_count ( const ab_gp_db_t * db )

Returns total number of active routes currently in the GP database.

Definition at line 375 of file ab_gp_db.c.

◆ ab_gp_db_route_get_by_index()

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 )

Retrieves route snapshot by table index for GA/GP route list synchronization.

Definition at line 395 of file ab_gp_db.c.

◆ ab_gp_db_train_is_connected()

bool ab_gp_db_train_is_connected	(	const ab_gp_db_t *	db,
		uint8_t	train_id )

Checks if a train has an active connection session in the DB.

Definition at line 435 of file ab_gp_db.c.

◆ ab_gp_db_train_get_routes()

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 )

Retrieves routes currently allocated to a train.

Definition at line 444 of file ab_gp_db.c.

◆ ab_gp_db_encode()

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 )

Encodes the full route and train database into a deterministic wire format.

Parameters

db	Database to encode.
out_bytes	Destination buffer.
out_capacity	Size of destination buffer (must be at least RTE_EXAMPLE_DB_WIRE_SIZE).
out_written	Bytes written.

Returns: RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM or RTE_STATUS_BUFFER_TOO_SMALL on error.

Definition at line 474 of file ab_gp_db.c.

◆ ab_gp_db_decode()

rte_status_t ab_gp_db_decode	(	ab_gp_db_t *	db,
		const uint8_t *	in_bytes,
		uint32_t	in_size )

Decodes the full route and train database from a deterministic wire format.

Parameters

db	Destination database to populate.
in_bytes	Buffer containing wire format.
in_size	Size of buffer (must be at least RTE_EXAMPLE_DB_WIRE_SIZE).

Returns: RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM or RTE_STATUS_BUFFER_TOO_SMALL on error.

Definition at line 557 of file ab_gp_db.c.

Variable Documentation

◆ g_route_context_subscribers

ab_gp_db_route_context_list_t g_route_context_subscribers

static

Definition at line 23 of file ab_gp_db.c.

Functions

Variables

Detailed Description

Function Documentation

◆ RTE_DECLARE_CALLBACK_LIST()

◆ ab_gp_db_register_route_context_notify()

◆ build_route_context()

◆ notify_route_context()

◆ find_route_index()

◆ find_free_route_slot()

◆ ab_gp_db_route_connect_train()

◆ ab_gp_db_route_disconnect_train()

◆ ab_gp_db_route_exists()

◆ ab_gp_db_route_add()

◆ ab_gp_db_route_remove()

◆ ab_gp_db_route_set_status()

◆ ab_gp_db_get_route_context()

◆ ab_gp_db_route_set_type()

◆ ab_gp_db_route_set_fsm_state()

◆ ab_gp_db_route_get_fsm_state()

◆ ab_gp_db_route_get_count()

◆ ab_gp_db_route_get_by_index()

◆ ab_gp_db_train_is_connected()

◆ ab_gp_db_train_get_routes()

◆ ab_gp_db_encode()

◆ ab_gp_db_decode()

Variable Documentation

◆ g_route_context_subscribers