Handles the automatic logon flow for DCC decoders. More...

#include <Logon.hxx>

Inheritance diagram for dcc::LogonHandler< Module >:

Classes
class	LogonSelect
	Flow that sends out addressed packets that are part of the logon sequences. More...

Public Member Functions
	LogonHandler (Service service, TrackIf track, RailcomHubFlow rcom_hub, Module m)
	Constructor.

void	startup_logon (uint16_t cid, uint8_t session_id)
	Initiates a logon sequence at startup.

PacketType	classify_packet (uintptr_t feedback_key) override
	Determines based on feedback key what the given DCC packet was.

void	process_select_shortinfo (uintptr_t feedback_key, bool error, uint64_t data) override
	Handles a Select ShortInfo feedback message.

void	process_logon_assign (uintptr_t feedback_key, bool error, uint64_t data) override
	Handles a Logon Assign feedback message.

void	process_decoder_id (uintptr_t feedback_key, bool error, uint64_t data) override
	Handles a Decoder ID feedback message.

Public Member Functions inherited from StateFlowBase
void	run () override
	Callback from the executor.

void	notify () override
	Wakeup call arrived.

Service *	service ()
	Return a pointer to the service I am bound to.

Public Member Functions inherited from Executable
void	test_deletion ()

Public Member Functions inherited from QMember
void	init ()
	Initiailize a QMember, in place of a public placement construction.

Private Member Functions
Action	allocate_logon_now ()
	Allocates a buffer and sends a Logon Enable(now) packet.

Action	send_logon_now ()
	Sends a Logon Enable(now) packet.

Action	start_logon_wait ()
	Called when the logon now packet is released.

Action	evaluate_logon ()
	Called when the logon timer expires or is cancelled due to feedback.

Action	allocate_logon_many ()
	Called when we have seen a conflict on a logon enable packet.

Action	send_logon_many ()
	Send out the repeated logon request.

Action	many_logon_wait ()
	Called after the many logon packets' buffer is freed.

void	logon_send_helper (Defs::LogonEnableParam param, unsigned rept)
	Helper function to send out logon enable commands.

Static Private Member Functions
static constexpr bool	is_logon_enable_key (uintptr_t feedback_key)
	Checks if a feedback key is for logon enable.

static constexpr bool	is_select_shortinfo_key (uintptr_t feedback_key)
	Checks if a feedback key is for select shortinfo.

static constexpr bool	is_logon_assign_key (uintptr_t feedback_key)
	Checks if a feedback key is for logon assign.

Private Attributes
dcc::LogonHandler::LogonSelect	this

TrackIf *	trackIf_
	If we need to send packets to the track, we can do it here directly.

Module *	module_
	Storage module.

StateFlowTimer	timer_ {this}
	Helper object for timing.

LogonFeedbackParser	fbParser_
	Helper object for parsing railcom feedback from the railcom hub.

BarrierNotifiable	bn_

long long	lastLogonTime_ {0}
	Timestamp of the last logon packet we sent out.

uint16_t	cid_
	Command station unique ID.

uint8_t	sessionId_
	Session ID of the current session.

uint8_t	hasLogonEnableConflict_: 1
	1 if we got an error (presumably a conflict) in the logon enable feedback.

uint8_t	hasLogonEnableFeedback_: 1
	1 if we got any feedback packet from logon enable.

uint8_t	needShutdown_: 1
	Signals that we need to shut down the flow.

uint8_t	countLogonToSend_ {0}
	Tracks how many logons to send out.

Static Private Attributes
static constexpr uintptr_t	LOGON_ENABLE_KEY
	We send this as feedback key for logon enable packets.

static constexpr uintptr_t	SELECT_SHORTINFO_KEY
	We send this as feedback key for select/get short info packets.

static constexpr uintptr_t	LOGON_ASSIGN_KEY
	We send this as feedback key for logon assign packets.

static constexpr unsigned	LOGON_PERIOD_MSEC = 295
	How often to send logon enable packets.

static constexpr unsigned	MAX_LOCO_ID = 0xfff
	Maximum allowed locomotive ID.

static constexpr uintptr_t	LOCO_ID_MASK = MAX_LOCO_ID
	Mask selecting bits that belong to the locomotive ID.

static constexpr uint64_t	DECODER_ID_MASK = (1ull << 44) - 1
	Mask selecting bits that belong to the decoder ID.

Friends
class	LogonSelect

Additional Inherited Members
Static Public Member Functions inherited from StateFlowBase
template<class T , typename... Args>
static void	invoke_subflow_and_ignore_result (FlowInterface< Buffer< T > > *target_flow, Args &&... args)
	Calls a helper flow to perform some actions.

Protected Types inherited from StateFlowBase
typedef Action(StateFlowBase::*	Callback) ()
	State Flow callback prototype.

Protected Member Functions inherited from StateFlowBase
	StateFlowBase (Service *service)
	Constructor.

	~StateFlowBase ()
	Destructor.

void	reset_flow (Callback c)
	Resets the flow to the specified state.

bool	is_state (Callback c)

bool	is_terminated ()

void	start_flow (Callback c)
	Resets the flow to the specified state and starts it.

Action	again ()
	Call the current state again via call_immediately.

Action	exit ()
	Terminate current StateFlow activity.

Action	delete_this ()
	Terminates the flow and deletes *this.

Action	set_terminated ()
	Sets the flow to terminated state.

Action	call_immediately (Callback c)
	Imediately call the next state upon return.

Action	wait ()
	Wait for an asynchronous call.

Action	wait_and_call (Callback c)
	Wait for resource to become available before proceeding to next state.

template<class T >
Action	allocate_and_call (FlowInterface< Buffer< T > > target_flow, Callback c, Pool pool=nullptr)
	Allocates a buffer from a pool and proceed to the next state when allocation is successful.

Action	allocate_and_call (Callback c, QAsync *queue)
	Allocates an entry from an asynchronous queue, and transitions to a state once the allocation is complete.

template<class T >
Buffer< T > *	full_allocation_result (FlowInterface< Buffer< T > > *target_flow)
	Takes the result of the asynchronous allocation without resetting the object.

template<class T >
T *	full_allocation_result (TypedQAsync< T > *queue)
	Takes the result of the asynchronous allocation without resetting the object.

template<class T >
void	cast_allocation_result (T **member)
	Takes the result of the asynchronous allocation without resetting the object.

template<class T >
Buffer< T > *	get_allocation_result (FlowInterface< Buffer< T > > *target_flow)
	Takes the result of the asynchronous allocation.

Action	yield_and_call (Callback c)
	Place the current flow to the back of the executor, and transition to a new state after we get the CPU again.

Action	yield ()
	Place the current flow to the back of the executor, and re-try the current state after we get the CPU again.

Action	sleep_and_call (::Timer *timer, long long timeout_nsec, Callback c)
	Suspends execution of this control flow for a specified time.

template<class T , typename... Args>
Action	invoke_subflow_and_wait (FlowInterface< Buffer< T > > *target_flow, Callback c, Args &&... args)
	Calls a helper flow to perform some actions.

Action	read_repeated (StateFlowSelectHelper helper, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Blocks until size bytes are read and then invokes the next state.

Action	read_single (StateFlowSelectHelper helper, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Attempts to read at most size_t bytes, and blocks the caller until at least one byte is read.

Action	read_nonblocking (StateFlowSelectHelper helper, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Attempts to read at most size bytes, and then invokes the next state, even if only zero bytes are available right now.

Action	read_repeated_with_timeout (StateFlowTimedSelectHelper helper, long long timeout_nsec, int fd, void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Blocks until size bytes are read, or a timeout expires.

Action	internal_try_read ()
	Implementation state that gets repeatedly called upon every wakeup and tries to make progress on reading.

Action	write_repeated (StateFlowSelectHelper helper, int fd, const void buf, size_t size, Callback c, unsigned priority=Selectable::MAX_PRIO)
	Writes some data into a file descriptor, repeating the operation as necessary until all bytes are written.

Action	internal_try_write ()
	Implementation state that gets repeatedly called upon every wakeup and tries to make progress on writing.

Protected Member Functions inherited from QMember
	QMember ()
	Constructor.

	~QMember ()
	Destructor.

Protected Attributes inherited from QMember
QMember *	next
	pointer to the next member in the queue

Private Types inherited from dcc::LogonFeedbackCallbacks
enum	PacketType { UNKNOWN = 0 , GET_DATA_START , GET_DATA_CONT , LOGON_ENABLE , SELECT_SHORTINFO , LOGON_ASSIGN , MISC_254 }

Detailed Description

template<class Module>
class dcc::LogonHandler< Module >

Handles the automatic logon flow for DCC decoders.

Definition at line 120 of file Logon.hxx.

Constructor & Destructor Documentation

◆ LogonHandler()

template<class Module >

dcc::LogonHandler< Module >::LogonHandler	(	Service *	service,
		TrackIf *	track,
		RailcomHubFlow *	rcom_hub,
		Module *	m
	)

inline

Constructor.

Parameters

service	points to the executor to use.
track	pointer to the track interface to send DCC packets to.
rcom_hub	will register to this railcom hub to get feedback.
m	the module for the storage and CS interface

Definition at line 129 of file Logon.hxx.

Member Function Documentation

◆ allocate_logon_many()

template<class Module >

Action dcc::LogonHandler< Module >::allocate_logon_many ( )

inlineprivate

Called when we have seen a conflict on a logon enable packet.

Allocates a buffer to send out many logon packets.

Definition at line 385 of file Logon.hxx.

◆ allocate_logon_now()

template<class Module >

Action dcc::LogonHandler< Module >::allocate_logon_now ( )

inlineprivate

Allocates a buffer and sends a Logon Enable(now) packet.

Definition at line 328 of file Logon.hxx.

◆ classify_packet()

template<class Module >

PacketType dcc::LogonHandler< Module >::classify_packet ( uintptr_t feedback_key )

inlineoverridevirtual

Determines based on feedback key what the given DCC packet was.

Parameters

feedback_key from the railcom packet.

Returns: the packet classification wrt the logon feature.

Implements dcc::LogonFeedbackCallbacks.

Definition at line 163 of file Logon.hxx.

◆ evaluate_logon()

template<class Module >

Action dcc::LogonHandler< Module >::evaluate_logon ( )

inlineprivate

Called when the logon timer expires or is cancelled due to feedback.

Definition at line 358 of file Logon.hxx.

◆ is_logon_assign_key()

template<class Module >

static constexpr bool dcc::LogonHandler< Module >::is_logon_assign_key ( uintptr_t feedback_key )

inlinestaticconstexprprivate

Checks if a feedback key is for logon assign.

Parameters

feedback_key the key

Returns: true if this is for a logon assign

Definition at line 644 of file Logon.hxx.

◆ is_logon_enable_key()

template<class Module >

static constexpr bool dcc::LogonHandler< Module >::is_logon_enable_key ( uintptr_t feedback_key )

inlinestaticconstexprprivate

Checks if a feedback key is for logon enable.

Parameters

feedback_key the key

Returns: true if this is for a logon enable

Definition at line 619 of file Logon.hxx.

◆ is_select_shortinfo_key()

template<class Module >

static constexpr bool dcc::LogonHandler< Module >::is_select_shortinfo_key ( uintptr_t feedback_key )

inlinestaticconstexprprivate

Checks if a feedback key is for select shortinfo.

Parameters

feedback_key the key

Returns: true if this is for a select short info

Definition at line 632 of file Logon.hxx.

◆ logon_send_helper()

template<class Module >

void dcc::LogonHandler< Module >::logon_send_helper	(	Defs::LogonEnableParam	param,
		unsigned	rept
	)

inlineprivate

Helper function to send out logon enable commands.

Requirement: a buffer is allocated before calling.

Parameters

param	option of which logon enable command to send out.
rept	0-3 for how many repeats to send out (N-1, so it means 1-4 repeats).

Definition at line 419 of file Logon.hxx.

◆ many_logon_wait()

template<class Module >

Action dcc::LogonHandler< Module >::many_logon_wait ( )

inlineprivate

Called after the many logon packets' buffer is freed.

@TODO we should really evaluate whether we've seen conflicts coming back.

Definition at line 398 of file Logon.hxx.

◆ process_decoder_id()

template<class Module >

void dcc::LogonHandler< Module >::process_decoder_id	(	uintptr_t	feedback_key,
		bool	error,
		uint64_t	data
	)

inlineoverridevirtual

Handles a Decoder ID feedback message.

Parameters

feedback_key	refers to the packet it came from.
error	true if there was a transmission error or the data came in incorrect format.
data	48 bits of payload. The low 44 bits of this is a decoder ID.

Implements dcc::LogonFeedbackCallbacks.

Definition at line 293 of file Logon.hxx.

◆ process_logon_assign()

template<class Module >

void dcc::LogonHandler< Module >::process_logon_assign	(	uintptr_t	feedback_key,
		bool	error,
		uint64_t	data
	)

inlineoverridevirtual

Handles a Logon Assign feedback message.

Parameters

feedback_key	refers to the packet it came from.
error	true if there was a transmission error or the data came in incorrect format.
data	48 bits of payload.

Implements dcc::LogonFeedbackCallbacks.

Definition at line 243 of file Logon.hxx.

◆ process_select_shortinfo()

template<class Module >

void dcc::LogonHandler< Module >::process_select_shortinfo	(	uintptr_t	feedback_key,
		bool	error,
		uint64_t	data
	)

inlineoverridevirtual

Handles a Select ShortInfo feedback message.

Parameters

feedback_key	refers to the packet it came from.
error	true if there was a transmission error or the data came in incorrect format.
data	48 bits of payload.

Implements dcc::LogonFeedbackCallbacks.

Definition at line 189 of file Logon.hxx.

◆ send_logon_many()

template<class Module >

Action dcc::LogonHandler< Module >::send_logon_many ( )

inlineprivate

Send out the repeated logon request.

Definition at line 391 of file Logon.hxx.

◆ send_logon_now()

template<class Module >

Action dcc::LogonHandler< Module >::send_logon_now ( )

inlineprivate

Sends a Logon Enable(now) packet.

Definition at line 334 of file Logon.hxx.

◆ start_logon_wait()

template<class Module >

Action dcc::LogonHandler< Module >::start_logon_wait ( )

inlineprivate

Called when the logon now packet is released.

This means the packet is enqueued in the device driver, but not necessarily that it is on the track yet.

Computes the next time that we need to send out a logon packet, and starts a sleep.

Definition at line 346 of file Logon.hxx.

◆ startup_logon()

template<class Module >

void dcc::LogonHandler< Module >::startup_logon	(	uint16_t	cid,
		uint8_t	session_id
	)

inline

Initiates a logon sequence at startup.

Definition at line 142 of file Logon.hxx.

Friends And Related Symbol Documentation

◆ LogonSelect

template<class Module >

friend class LogonSelect

friend

Definition at line 436 of file Logon.hxx.

Member Data Documentation

◆ bn_

template<class Module >

BarrierNotifiable dcc::LogonHandler< Module >::bn_

private

Definition at line 672 of file Logon.hxx.

◆ cid_

template<class Module >

uint16_t dcc::LogonHandler< Module >::cid_

private

Command station unique ID.

Definition at line 678 of file Logon.hxx.

◆ countLogonToSend_

template<class Module >

uint8_t dcc::LogonHandler< Module >::countLogonToSend_ {0}

private

Tracks how many logons to send out.

Definition at line 691 of file Logon.hxx.

◆ DECODER_ID_MASK

template<class Module >

constexpr uint64_t dcc::LogonHandler< Module >::DECODER_ID_MASK = (1ull << 44) - 1

staticconstexprprivate

Mask selecting bits that belong to the decoder ID.

Definition at line 658 of file Logon.hxx.

◆ fbParser_

template<class Module >

LogonFeedbackParser dcc::LogonHandler< Module >::fbParser_

private

Helper object for parsing railcom feedback from the railcom hub.

Definition at line 670 of file Logon.hxx.

◆ hasLogonEnableConflict_

template<class Module >

uint8_t dcc::LogonHandler< Module >::hasLogonEnableConflict_

private

1 if we got an error (presumably a conflict) in the logon enable feedback.

Definition at line 684 of file Logon.hxx.

◆ hasLogonEnableFeedback_

template<class Module >

uint8_t dcc::LogonHandler< Module >::hasLogonEnableFeedback_

private

1 if we got any feedback packet from logon enable.

Definition at line 686 of file Logon.hxx.

◆ lastLogonTime_

template<class Module >

long long dcc::LogonHandler< Module >::lastLogonTime_ {0}

private

Timestamp of the last logon packet we sent out.

Definition at line 675 of file Logon.hxx.

◆ LOCO_ID_MASK

template<class Module >

constexpr uintptr_t dcc::LogonHandler< Module >::LOCO_ID_MASK = MAX_LOCO_ID

staticconstexprprivate

Mask selecting bits that belong to the locomotive ID.

Definition at line 655 of file Logon.hxx.

◆ LOGON_ASSIGN_KEY

template<class Module >

constexpr uintptr_t dcc::LogonHandler< Module >::LOGON_ASSIGN_KEY

staticconstexprprivate

Initial value:

=

uint32_t((Defs::ADDRESS_LOGON << 24) | (Defs::DCC_LOGON_ASSIGN << 16))

We send this as feedback key for logon assign packets.

Definition at line 638 of file Logon.hxx.

◆ LOGON_ENABLE_KEY

template<class Module >

constexpr uintptr_t dcc::LogonHandler< Module >::LOGON_ENABLE_KEY

staticconstexprprivate

Initial value:

=

uint32_t((Defs::ADDRESS_LOGON << 24) | (Defs::DCC_LOGON_ENABLE << 16))

We send this as feedback key for logon enable packets.

Definition at line 613 of file Logon.hxx.

◆ LOGON_PERIOD_MSEC

template<class Module >

constexpr unsigned dcc::LogonHandler< Module >::LOGON_PERIOD_MSEC = 295

staticconstexprprivate

How often to send logon enable packets.

Definition at line 650 of file Logon.hxx.

◆ MAX_LOCO_ID

template<class Module >

constexpr unsigned dcc::LogonHandler< Module >::MAX_LOCO_ID = 0xfff

staticconstexprprivate

Maximum allowed locomotive ID.

Definition at line 653 of file Logon.hxx.

◆ module_

template<class Module >

Module* dcc::LogonHandler< Module >::module_

private

Storage module.

Definition at line 664 of file Logon.hxx.

◆ needShutdown_

template<class Module >

uint8_t dcc::LogonHandler< Module >::needShutdown_

private

Signals that we need to shut down the flow.

Definition at line 688 of file Logon.hxx.

◆ SELECT_SHORTINFO_KEY

template<class Module >

constexpr uintptr_t dcc::LogonHandler< Module >::SELECT_SHORTINFO_KEY

staticconstexprprivate

Initial value:

=
        uint32_t((Defs::ADDRESS_LOGON << 24) | (Defs::DCC_SELECT << 16) |
            (Defs::CMD_READ_SHORT_INFO << 12))

We send this as feedback key for select/get short info packets.

Definition at line 625 of file Logon.hxx.

◆ sessionId_

template<class Module >

uint8_t dcc::LogonHandler< Module >::sessionId_

private

Session ID of the current session.

Definition at line 680 of file Logon.hxx.

◆ timer_

template<class Module >

StateFlowTimer dcc::LogonHandler< Module >::timer_ {this}

private

Helper object for timing.

Definition at line 667 of file Logon.hxx.

◆ trackIf_

template<class Module >

TrackIf* dcc::LogonHandler< Module >::trackIf_

private

If we need to send packets to the track, we can do it here directly.

Definition at line 661 of file Logon.hxx.

The documentation for this class was generated from the following file:

Logon.hxx

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ LogonHandler()

Member Function Documentation

◆ allocate_logon_many()

◆ allocate_logon_now()

◆ classify_packet()

◆ evaluate_logon()

◆ is_logon_assign_key()

◆ is_logon_enable_key()

◆ is_select_shortinfo_key()

◆ logon_send_helper()

◆ many_logon_wait()

◆ process_decoder_id()

◆ process_logon_assign()

◆ process_select_shortinfo()

◆ send_logon_many()

◆ send_logon_now()

◆ start_logon_wait()

◆ startup_logon()

Friends And Related Symbol Documentation

◆ LogonSelect

Member Data Documentation

◆ bn_

◆ cid_

◆ countLogonToSend_

◆ DECODER_ID_MASK

◆ fbParser_

◆ hasLogonEnableConflict_

◆ hasLogonEnableFeedback_

◆ lastLogonTime_

◆ LOCO_ID_MASK

◆ LOGON_ASSIGN_KEY

◆ LOGON_ENABLE_KEY

◆ LOGON_PERIOD_MSEC

◆ MAX_LOCO_ID

◆ module_

◆ needShutdown_

◆ SELECT_SHORTINFO_KEY

◆ sessionId_

◆ timer_

◆ trackIf_