ab_ga_ctc.h File Reference

A/B's own outbound messages to CtcRBCSim. Two layers, same split as AB/GP/train/ab_gp_train.h's own "Outbound envelope building" doc: More...

#include <stdint.h>
#include "safeapi/utils/status/sapi_status.h"
#include "rbc_wire_types.h"
#include "ga_interface.h"
#include <stdbool.h>

Include dependency graph for ab_ga_ctc.h:

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

Go to the source code of this file.

Functions
void	ab_ga_ctc_on_route_context_changed (const ab_gp_route_context_t *ctx, ab_gp_route_update_type_t update_type)
	GA's single dispatch module (safeAPIRBC2oo2GA/src/AB/main/ ab_ga_dispatch.c) is the ONLY thing that registers with GP now (interface-simplification pass) - it owns the ONE route-context subscription and fans AB_ROUTE_CONNECTED here (the only kind CTC ever logged - see this file's own module doc). CTC has no route validator of its own - it never has veto authority over a route<->train connection, only observes the fact once made.
void	ab_ga_ctc_on_train_context_changed (const ab_gp_train_context_t *ctx, ab_gp_train_update_type_t update_type)
	GA's dispatch module fans every train-context change here - stores the received snapshot and marks this train as needing a fresh CTC_TRAIN_INFO next cycle (drained by ab_ga_ctc_build_outputs() below). Replaces the old per-cycle poll+diff scan against GP's own session getters entirely - interface-simplification pass, see this file's own module doc.
void	ab_ga_ctc_build_connected (uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t d_lrbg)
	Builds and wire-encodes the outbound CTC_CONNECTED indication for train_id (kind=RBC_MSG_CTC_CONNECTED) directly into out - sent once, the first time a train's session becomes known (GP's own ctc_connected_sent latch, read/written via ga_interface.h). Wire-encoding is this module's own (ctc_wire_encode(), ab_ga_ctc.c, file-static) - the old shared rbc_wire_encode() is retired.
void	ab_ga_ctc_build_ma_granted (uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t ma_seq, uint32_t ma_length)
	Builds and wire-encodes the outbound CTC_MA_GRANTED indication for train_id (kind=RBC_MSG_CTC_MA_GRANTED) directly into out - sent the first time a route is granted for this train (GP's own ctc_ma_granted_sent latch); every grant after that is ab_ga_ctc_build_ma_extended() instead. Same contract as ab_ga_ctc_build_connected() above.
void	ab_ga_ctc_build_ma_extended (uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t ma_seq, uint32_t ma_length)
	Builds and wire-encodes the outbound CTC_MA_EXTENDED indication for train_id (kind=RBC_MSG_CTC_MA_EXTENDED) directly into out - see ab_ga_ctc_build_ma_granted()'s own doc for the granted/extended split. Same contract as ab_ga_ctc_build_connected() above.
void	ab_ga_ctc_build_train_info (uint8_t out[RBC_ENVELOPE_WIRE_SIZE], uint8_t train_id, uint32_t d_lrbg, uint32_t ma_seq, uint32_t granted_length, bool ma_granted, uint16_t front_signal, uint32_t dist_to_front_signal, uint16_t target_signal, uint32_t nid_lrbg, uint32_t v_train, uint32_t m_mode)
	Builds and wire-encodes a severity-leveled operational alarm (kind=RBC_MSG_CTC_ALARM) directly into out - see that kind's own doc in rbc_wire_types.h. Unlike ab_ga_ctc_build_connected()/_ma_granted()/_ma_extended() above, this is not part of the per-cycle ab_ga_ctc_build_outputs() pipeline - see ga_interface.h/AB/GP/main/ab_gp_ga_hooks.h's own ab_gp_build_ctc_alarm() instead: raising an alarm moved to be GP's own API entirely (later session, on direct request) - it's GP's own decision to raise one, not something that needs a GA round trip, so this module no longer owns it.
uint8_t	ab_ga_ctc_build_outputs (ab_gp_train_session_t *sessions, ab_gp_db_t *db, ab_gp_ctc_pending_output_t out[AB_GP_CTC_MAX_PENDING_OUTPUTS])
	Decides which trains need a CTC indication THIS cycle and builds all of them - see this file's own module doc above for the two-layer split this sits on top of. Mutates sessions in place (ctc_connected_sent/ctc_ma_granted_sent - GP's own sticky latches, written via ga_interface.h's own setters) but does NOT clear ma_pending_send - see AB/GP/train/ab_gp_train.h's ab_gp_train_build_outputs()'s own doc for why the coordinator (com/'s ab_gp_channel_forward_to_c_if_needed()), not either domain, clears that shared flag. Does not send anything itself - ab_gp_channel_forward_to_c_if_needed() owns actually sending each built entry (ab_gp_channel_send_envelope_to_c()).

Detailed Description

A/B's own outbound messages to CtcRBCSim. Two layers, same split as AB/GP/train/ab_gp_train.h's own "Outbound envelope building" doc:

• ab_ga_ctc_build_connected()/_build_ma_granted()/_build_ma_extended() below: given a caller-decided WHAT, build and wire-encode ONE envelope (this module's own ctc_wire_encode(), ab_ga_ctc.c
  • the old shared rbc_wire_encode() is retired). No I/O, no gating.
• ab_ga_ctc_build_outputs() below THAT: given sessions (GP's own ctc_connected_sent/ctc_ma_granted_sent latches and ma_pending_send, read/written through ga_interface.h's own getters/setters - this module never sees ab_gp_train_session_t's own field layout), decides WHICH trains need a CTC indication this cycle and builds all of them, updating the two latches in place. com/'s ab_gp_channel_forward_to_c_if_needed() only decides the higher-level "send to C at all this cycle" gate (should_forward_to_c, ab_gp_channel.c's own concern) and then asks this module (and AB/GP/train/ab_gp_train.h) to build their own outputs and sends whatever came back over ab_gp_channel_io.c's own relay channels.

Today CTC is receive-only (see CTCRBCSim/src/ctc/ctc_sim.py) - observing train-connected/MA-granted/MA-extended indications, exactly the three kinds built here. There is no inbound wire kind yet for CTC to SEND a command to A/B (e.g. a future "stop train" instruction) - rbc_msg_kind_t (rbc_wire_types.h) has no such kind, so there is nothing for com/'s ab_gp_channel.c to decode or forward here yet; its existing default case (ab_gp_channel_apply_inbound_envelope()) already logs and drops any CTC_* kind arriving C->AB as unexpected, which remains correct until a real inbound CTC kind exists to dispatch on.

Definition in file ab_ga_ctc.h.

Function Documentation

ab_ga_ctc_build_connected()

void ab_ga_ctc_build_connected	(	uint8_t	out[RBC_ENVELOPE_WIRE_SIZE],
		uint8_t	train_id,
		uint32_t	d_lrbg )

Builds and wire-encodes the outbound CTC_CONNECTED indication for train_id (kind=RBC_MSG_CTC_CONNECTED) directly into out - sent once, the first time a train's session becomes known (GP's own ctc_connected_sent latch, read/written via ga_interface.h). Wire-encoding is this module's own (ctc_wire_encode(), ab_ga_ctc.c, file-static) - the old shared rbc_wire_encode() is retired.

Parameters

out	Destination, exactly RBC_ENVELOPE_WIRE_SIZE bytes. Must not be NULL.

Global functions

Definition at line 92 of file ab_ga_ctc.c.

ab_ga_ctc_build_ma_extended()

void ab_ga_ctc_build_ma_extended	(	uint8_t	out[RBC_ENVELOPE_WIRE_SIZE],
		uint8_t	train_id,
		uint32_t	ma_seq,
		uint32_t	ma_length )

Builds and wire-encodes the outbound CTC_MA_EXTENDED indication for train_id (kind=RBC_MSG_CTC_MA_EXTENDED) directly into out - see ab_ga_ctc_build_ma_granted()'s own doc for the granted/extended split. Same contract as ab_ga_ctc_build_connected() above.

Definition at line 116 of file ab_ga_ctc.c.

ab_ga_ctc_build_ma_granted()

void ab_ga_ctc_build_ma_granted	(	uint8_t	out[RBC_ENVELOPE_WIRE_SIZE],
		uint8_t	train_id,
		uint32_t	ma_seq,
		uint32_t	ma_length )

Builds and wire-encodes the outbound CTC_MA_GRANTED indication for train_id (kind=RBC_MSG_CTC_MA_GRANTED) directly into out - sent the first time a route is granted for this train (GP's own ctc_ma_granted_sent latch); every grant after that is ab_ga_ctc_build_ma_extended() instead. Same contract as ab_ga_ctc_build_connected() above.

Definition at line 103 of file ab_ga_ctc.c.

ab_ga_ctc_build_outputs()

uint8_t ab_ga_ctc_build_outputs	(	ab_gp_train_session_t *	sessions,
		ab_gp_db_t *	db,
		ab_gp_ctc_pending_output_t	out[AB_GP_CTC_MAX_PENDING_OUTPUTS] )

Decides which trains need a CTC indication THIS cycle and builds all of them - see this file's own module doc above for the two-layer split this sits on top of. Mutates sessions in place (ctc_connected_sent/ctc_ma_granted_sent - GP's own sticky latches, written via ga_interface.h's own setters) but does NOT clear ma_pending_send - see AB/GP/train/ab_gp_train.h's ab_gp_train_build_outputs()'s own doc for why the coordinator (com/'s ab_gp_channel_forward_to_c_if_needed()), not either domain, clears that shared flag. Does not send anything itself - ab_gp_channel_forward_to_c_if_needed() owns actually sending each built entry (ab_gp_channel_send_envelope_to_c()).

The pending-output element type/capacity this module fills (ab_gp_ctc_pending_output_t/AB_GP_CTC_MAX_PENDING_OUTPUTS) are GP-owned now, declared in ga_interface.h - the "consumer owns the shape" posture ab_gp_route_context_t/ab_gp_train_context_t already take (see that header's own doc).

Parameters

sessions	GP's own ab_gp_train_session_t table (opaque to this module) (SAFEAPI_EXAMPLE_MAX_TRAINS entries) - mutated in place via ga_interface.h's own setters.
db	GP's own route/train database (opaque to this module) needed to compute CTC_TRAIN_INFO's front/target signal via ab_gp_db_train_get_routes() (ga_interface.h) and ab_siteGA.h's own static route table. Every other output built here needs no db access, hence this parameter being new rather than always present.
out	Destination array, AB_GP_CTC_MAX_PENDING_OUTPUTS entries. Must not be NULL.

Returns

the number of entries actually filled in out (0..AB_GP_CTC_MAX_PENDING_OUTPUTS).

Definition at line 169 of file ab_ga_ctc.c.

ab_ga_ctc_build_train_info()

void ab_ga_ctc_build_train_info	(	uint8_t	out[RBC_ENVELOPE_WIRE_SIZE],
		uint8_t	train_id,
		uint32_t	d_lrbg,
		uint32_t	ma_seq,
		uint32_t	granted_length,
		bool	ma_granted,
		uint16_t	front_signal,
		uint32_t	dist_to_front_signal,
		uint16_t	target_signal,
		uint32_t	nid_lrbg,
		uint32_t	v_train,
		uint32_t	m_mode )

Builds and wire-encodes a severity-leveled operational alarm (kind=RBC_MSG_CTC_ALARM) directly into out - see that kind's own doc in rbc_wire_types.h. Unlike ab_ga_ctc_build_connected()/_ma_granted()/_ma_extended() above, this is not part of the per-cycle ab_ga_ctc_build_outputs() pipeline - see ga_interface.h/AB/GP/main/ab_gp_ga_hooks.h's own ab_gp_build_ctc_alarm() instead: raising an alarm moved to be GP's own API entirely (later session, on direct request) - it's GP's own decision to raise one, not something that needs a GA round trip, so this module no longer owns it.

Builds and wire-encodes the outbound CTC_TRAIN_INFO indication for train_id (kind=RBC_MSG_CTC_TRAIN_INFO) directly into out - see that kind's own doc in rbc_wire_types.h for the generic-field-reuse layout. Pure encode, no computation and no gating - front_signal/dist_to_front_signal/ target_signal are caller-computed (ab_ga_ctc_build_outputs() below owns that, via its own file-static route-chain walk).

Parameters

d_lrbg	Train's current reported position.
ma_seq	This train's real MA sequence number.
granted_length	Cumulative MA length granted, meters - used only to derive the signed MA offset (d_lrbg - granted_length) stored in the wire's ma_length slot.
ma_granted	True if this train currently has any MA (ma_status wire field).
front_signal	Earliest not-yet-reached held-route boundary's end_signal, 0 if none.
dist_to_front_signal	Distance to that boundary, meters.
target_signal	end_signal of the last held route (the far end of the current MA), 0 if none.
nid_lrbg	This train's own last relevant balise group id (d_lrbg is relative to this) - appended after ma_length, not a reused generic slot - see ctc_wire_encode()'s own doc for why.
v_train	Last reported train speed (M136's own v_train), appended the same way.
m_mode	Last reported ETCS mode (M136's own m_mode), appended the same way.
out	Destination, exactly RBC_ENVELOPE_WIRE_SIZE bytes. Must not be NULL.

Definition at line 132 of file ab_ga_ctc.c.

ab_ga_ctc_on_route_context_changed()

void ab_ga_ctc_on_route_context_changed	(	const ab_gp_route_context_t *	ctx,
		ab_gp_route_update_type_t	update_type )

GA's single dispatch module (safeAPIRBC2oo2GA/src/AB/main/ ab_ga_dispatch.c) is the ONLY thing that registers with GP now (interface-simplification pass) - it owns the ONE route-context subscription and fans AB_ROUTE_CONNECTED here (the only kind CTC ever logged - see this file's own module doc). CTC has no route validator of its own - it never has veto authority over a route<->train connection, only observes the fact once made.

Definition at line 264 of file ab_ga_ctc.c.

ab_ga_ctc_on_train_context_changed()

void ab_ga_ctc_on_train_context_changed	(	const ab_gp_train_context_t *	ctx,
		ab_gp_train_update_type_t	update_type )

GA's dispatch module fans every train-context change here - stores the received snapshot and marks this train as needing a fresh CTC_TRAIN_INFO next cycle (drained by ab_ga_ctc_build_outputs() below). Replaces the old per-cycle poll+diff scan against GP's own session getters entirely - interface-simplification pass, see this file's own module doc.

Definition at line 278 of file ab_ga_ctc.c.