rte_site_role_policy.h File Reference

Site-role policy: one pure decision function for "should this channel promote, demote or stay?" and the timing predicates of standby sync, takeover and the both-STANDBY tie-break. More...

#include <stdbool.h>
#include <stdint.h>

Include dependency graph for rte_site_role_policy.h:

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

Go to the source code of this file.

Data Structures
struct	rte_site_role_input_t
struct	rte_site_role_decision_t

Macros
#define	RTE_SITE_ROLE_STANDBY_DATA_TIMEOUT_CYCLES   3U
#define	RTE_SITE_ROLE_STANDBY_SYNC_RETRY_CYCLES   10U
#define	RTE_SITE_ROLE_TAKEOVER_CONFIRM_VALID_CYCLES   120U
#define	RTE_SITE_ROLE_BOTH_STANDBY_CYCLES   6U

Enumerations
enum	rte_site_role_action_t {   RTE_SITE_ROLE_ACTION_NONE = 0 , RTE_SITE_ROLE_ACTION_PROMOTE , RTE_SITE_ROLE_ACTION_DEMOTE , RTE_SITE_ROLE_ACTION_RENEGOTIATE ,   RTE_SITE_ROLE_ACTION_ALARM , RTE_SITE_ROLE_ACTION_WAIT }
enum	rte_site_role_reason_t {   RTE_SITE_ROLE_REASON_NONE = 0 , RTE_SITE_ROLE_REASON_BOTH_FAULTED , RTE_SITE_ROLE_REASON_PEER_FAULTED , RTE_SITE_ROLE_REASON_RECOVERED ,   RTE_SITE_ROLE_REASON_DISPATCHER_CONFIRMED , RTE_SITE_ROLE_REASON_BOTH_STANDBY_WEST , RTE_SITE_ROLE_REASON_BOTH_STANDBY_SIBLING , RTE_SITE_ROLE_REASON_YIELD_TO_TAKEOVER ,   RTE_SITE_ROLE_REASON_DUAL_ONLINE , RTE_SITE_ROLE_REASON_WAITING_READY }

Functions
rte_site_role_decision_t	rte_site_role_decide (const rte_site_role_input_t *in)
	Decides this cycle's role action. Rules are evaluated in this order and the first that applies wins:
const char *	rte_site_role_reason_text (rte_site_role_reason_t reason)
const char *	rte_site_role_reason_token (rte_site_role_reason_t reason)
bool	rte_site_role_standby_sync_due (bool sync_enabled, bool is_online, bool link_up, bool healthy, uint32_t cycle, uint32_t last_try)
	Whether ONLINE should attempt the pre-commit standby sync this cycle.
bool	rte_site_role_standby_data_stale (bool sync_enabled, bool is_online, bool have_snapshot, uint32_t cycle, uint32_t last_rx_cycle)
	Whether STANDBY's held snapshot is stale and must be dropped (STANDBY goes cold).
bool	rte_site_role_takeover_allowed (bool is_online, bool own_faulted, bool peer_unresponsive, bool confirmed, uint32_t cycle, uint32_t confirm_cycle)
	Whether a STANDBY channel may promote itself because its counterpart stopped responding. Silence alone never promotes: the dispatcher must have confirmed, within RTE_SITE_ROLE_TAKEOVER_CONFIRM_VALID_CYCLES, that the other site is not ONLINE.
bool	rte_site_role_both_standby_tiebreak (uint32_t both_standby_cycles, bool is_west, bool sibling_online)
	Negotiation tie-break for "both sites STANDBY": a channel whose A/B sibling is already ONLINE joins it at once; otherwise WEST promotes after RTE_SITE_ROLE_BOTH_STANDBY_CYCLES. Both sites compute the same answer from the same link, so this is a negotiation outcome, not a unilateral promotion.

Detailed Description

Site-role policy: one pure decision function for "should this channel promote, demote or stay?" and the timing predicates of standby sync, takeover and the both-STANDBY tie-break.

ADR-040 step 1: the Capella model places site-role negotiation in RTE Redundancy Services; the application keeps a declarative Site Role Client. This header is the pure part of that service, moved unchanged from RBC_GP (ab_gp_site_role, ab_gp_standby_policy). No I/O, no globals: facts come from the caller, the answer is one action per cycle, and the both-STANDBY counter is passed in and returned.

A channel becomes ONLINE only through:

1. negotiation - startup, the both-STANDBY tie-break, or joining an ONLINE A/B sibling;
2. the counterpart's FAULTED (about-to-reboot) notice;
3. a dispatcher confirmation that the other site is not ONLINE, while the counterpart is silent. Silence alone never promotes.

REQ-SITEROLE-001: rte_site_role_decide() evaluates the rules in the documented order; the first that applies wins. REQ-SITEROLE-002: a promotion is carried out only when the pair is ready (else WAIT). REQ-SITEROLE-003: silence alone never promotes (rte_site_role_takeover_allowed needs a valid confirmation). REQ-SITEROLE-004: a restarted cycle counter makes a takeover confirmation expired and a held snapshot stale.

Definition in file rte_site_role_policy.h.

Macro Definition Documentation

RTE_SITE_ROLE_STANDBY_DATA_TIMEOUT_CYCLES

#define RTE_SITE_ROLE_STANDBY_DATA_TIMEOUT_CYCLES   3U

Cycles STANDBY may go without a valid snapshot before it is treated as cold.

Definition at line 33 of file rte_site_role_policy.h.

RTE_SITE_ROLE_STANDBY_SYNC_RETRY_CYCLES

#define RTE_SITE_ROLE_STANDBY_SYNC_RETRY_CYCLES   10U

While STANDBY is considered not working, ONLINE retries the sync every this many cycles.

Definition at line 36 of file rte_site_role_policy.h.

RTE_SITE_ROLE_TAKEOVER_CONFIRM_VALID_CYCLES

#define RTE_SITE_ROLE_TAKEOVER_CONFIRM_VALID_CYCLES   120U

How long (cycles) a dispatcher takeover confirmation stays valid.

Definition at line 39 of file rte_site_role_policy.h.

RTE_SITE_ROLE_BOTH_STANDBY_CYCLES

#define RTE_SITE_ROLE_BOTH_STANDBY_CYCLES   6U

Consecutive cycles both sites must be STANDBY (counterpart responding, neither ONLINE nor FAULTED) before the tie-break.

Definition at line 42 of file rte_site_role_policy.h.

Enumeration Type Documentation

rte_site_role_action_t

enum rte_site_role_action_t

What the channel should do this cycle.

Enumerator
RTE_SITE_ROLE_ACTION_NONE	stay as is
RTE_SITE_ROLE_ACTION_PROMOTE	become ONLINE
RTE_SITE_ROLE_ACTION_DEMOTE	become STANDBY
RTE_SITE_ROLE_ACTION_RENEGOTIATE	both sites FAULTED: deterministic re-negotiation (WEST wins)
RTE_SITE_ROLE_ACTION_ALARM	a state that is not resolved automatically: report it loudly
RTE_SITE_ROLE_ACTION_WAIT	a promotion is due but not yet allowed: waiting for this channel and its A/B sibling to be ready

Definition at line 45 of file rte_site_role_policy.h.

rte_site_role_reason_t

enum rte_site_role_reason_t

Why (the log line, the status frame and the tests use it).

Enumerator
RTE_SITE_ROLE_REASON_BOTH_FAULTED	own and counterpart FAULTED
RTE_SITE_ROLE_REASON_PEER_FAULTED	counterpart announced FAULTED / reboot
RTE_SITE_ROLE_REASON_RECOVERED	was FAULTED, counterpart healthy ONLINE
RTE_SITE_ROLE_REASON_DISPATCHER_CONFIRMED	silent counterpart, dispatcher confirmed it is not ONLINE
RTE_SITE_ROLE_REASON_BOTH_STANDBY_WEST	negotiation tie-break: both STANDBY, WEST wins
RTE_SITE_ROLE_REASON_BOTH_STANDBY_SIBLING	joined the ONLINE A/B sibling of this site
RTE_SITE_ROLE_REASON_YIELD_TO_TAKEOVER	was cut off while ONLINE, counterpart took over meanwhile
RTE_SITE_ROLE_REASON_DUAL_ONLINE	both ONLINE without a lost-contact history (alarm)
RTE_SITE_ROLE_REASON_WAITING_READY	promotion held back until both A/B channels confirm they are ready

Definition at line 56 of file rte_site_role_policy.h.

Function Documentation

rte_site_role_decide()

rte_site_role_decision_t rte_site_role_decide

(

const rte_site_role_input_t *

in

)

Decides this cycle's role action. Rules are evaluated in this order and the first that applies wins:

1. own FAULTED and counterpart FAULTED: RENEGOTIATE.
2. this channel is STANDBY, healthy, counterpart FAULTED: PROMOTE (PEER_FAULTED).
3. own FAULTED, counterpart healthy and holding an ONLINE snapshot: DEMOTE (RECOVERED).
4. STANDBY, counterpart silent, dispatcher confirmation valid: PROMOTE (DISPATCHER_CONFIRMED).
5. ONLINE and the counterpart, answering within 2 cycles, is ONLINE too: DEMOTE (YIELD_TO_TAKEOVER) if this channel was cut off while ONLINE, otherwise ALARM (DUAL_ONLINE).
6. STANDBY, link up, counterpart answering within 2 cycles and not ONLINE for RTE_SITE_ROLE_BOTH_STANDBY_CYCLES cycles (or 1 cycle when the A/B sibling is already ONLINE): PROMOTE (BOTH_STANDBY_WEST / _SIBLING).
7. STANDBY, A/B sibling ONLINE, own link view unusable and counterpart not verifiably ONLINE: follow the sibling after 2 cycles, PROMOTE (BOTH_STANDBY_SIBLING).

A promotion is only carried out when this channel is ready AND its A/B sibling is ONLINE already, or confirms it is ready, or cannot be reached (single channel). Otherwise the answer is WAIT.

Parameters

in	facts; must not be NULL

Returns

the decision; both_standby_cycles must be stored by the caller

Definition at line 20 of file rte_site_role_policy.c.

rte_site_role_reason_text()

const char * rte_site_role_reason_text

(

rte_site_role_reason_t

reason

)

Returns

a short text for a reason, for logs.

Definition at line 101 of file rte_site_role_policy.c.

rte_site_role_reason_token()

const char * rte_site_role_reason_token

(

rte_site_role_reason_t

reason

)

Returns

a one-word token (no spaces) for a reason, for the status frame.

Definition at line 141 of file rte_site_role_policy.c.

rte_site_role_standby_sync_due()

bool rte_site_role_standby_sync_due	(	bool	sync_enabled,
		bool	is_online,
		bool	link_up,
		bool	healthy,
		uint32_t	cycle,
		uint32_t	last_try )

Whether ONLINE should attempt the pre-commit standby sync this cycle.

Parameters

sync_enabled	true when standby_mode is warm or hot
is_online	this channel is ONLINE
link_up	the inter-site link is open
healthy	STANDBY answered the last sync
cycle	current cycle number
last_try	cycle of the last sync attempt made while unhealthy

Returns

true if a sync should be sent now

Definition at line 181 of file rte_site_role_policy.c.

rte_site_role_standby_data_stale()

bool rte_site_role_standby_data_stale	(	bool	sync_enabled,
		bool	is_online,
		bool	have_snapshot,
		uint32_t	cycle,
		uint32_t	last_rx_cycle )

Whether STANDBY's held snapshot is stale and must be dropped (STANDBY goes cold).

Returns

true if the snapshot has been silent for more than RTE_SITE_ROLE_STANDBY_DATA_TIMEOUT_CYCLES, or the cycle counter restarted since it arrived

Definition at line 202 of file rte_site_role_policy.c.

rte_site_role_takeover_allowed()

bool rte_site_role_takeover_allowed	(	bool	is_online,
		bool	own_faulted,
		bool	peer_unresponsive,
		bool	confirmed,
		uint32_t	cycle,
		uint32_t	confirm_cycle )

Whether a STANDBY channel may promote itself because its counterpart stopped responding. Silence alone never promotes: the dispatcher must have confirmed, within RTE_SITE_ROLE_TAKEOVER_CONFIRM_VALID_CYCLES, that the other site is not ONLINE.

Definition at line 216 of file rte_site_role_policy.c.

rte_site_role_both_standby_tiebreak()

bool rte_site_role_both_standby_tiebreak	(	uint32_t	both_standby_cycles,
		bool	is_west,
		bool	sibling_online )

Negotiation tie-break for "both sites STANDBY": a channel whose A/B sibling is already ONLINE joins it at once; otherwise WEST promotes after RTE_SITE_ROLE_BOTH_STANDBY_CYCLES. Both sites compute the same answer from the same link, so this is a negotiation outcome, not a unilateral promotion.

Definition at line 229 of file rte_site_role_policy.c.