Implementation of the Memory Access Configuration Protocol for OpenLCB. More...

#include <MemoryConfig.hxx>

Inheritance diagram for openlcb::MemoryConfigHandler:

Classes
class	RebootTimer
	Used internally by the factory_reset implementation to reboot the binary asynchronously. More...

Public Member Functions
	MemoryConfigHandler (DatagramService if_dg, Node node, int registry_size)
	node can be nullptr, and then the handler will be registered globally.

	~MemoryConfigHandler ()

Registry *	registry ()

void	send (DefaultDatagramHandler::message_type *message, unsigned priority=UINT_MAX) override
	Overrides the default send method in orderto decide whether the queue the incoming datagram in the server queue or the client queue.

void	set_client (DatagramHandlerFlow *client)
	Registers a second handler to forward all the client interactions, i.e.

void	clear_client (DatagramHandlerFlow *client)
	Unregisters the previously registered second handler.

void	set_stream_handler (DatagramHandlerFlow *stream_handler)
	This will be called by the constructor of the stream handler plugin.

Public Member Functions inherited from openlcb::DefaultDatagramHandler
DatagramService *	dg_service ()

Public Member Functions inherited from StateFlow< MessageType, QueueType >
	StateFlow (Service *service)
	Constructor.

Public Member Functions inherited from TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >
	TypedStateFlow (Service *service)
	Constructor.

virtual	~TypedStateFlow ()
	Destructor.

void	send (MessageType *msg, unsigned priority=UINT_MAX) OVERRIDE
	Sends a message to the state flow for processing.

Public Member Functions inherited from UntypedStateFlow< QueueType >
	UntypedStateFlow (Service *service)
	Constructor.

Public Member Functions inherited from StateFlowWithQueue
void	notify () override
	Wakeup call arrived. Schedules *this on the executor.

bool	is_waiting ()

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

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.

Public Member Functions inherited from LinkedObject< StateFlowWithQueue >
StateFlowWithQueue *	link_next ()

Public Member Functions inherited from FlowInterface< MessageType >
virtual Pool *	pool ()

virtual MessageType *	type_helper ()
	This function is never user in the code, but GDB can use it to infer the correct message types.

MessageType *	alloc ()
	Synchronously allocates a message buffer from the pool of this flow.

void	alloc_async (Executable *target)
	Asynchronously allocates a message buffer from the pool of this flow.

Private Member Functions
Action	entry () OVERRIDE
	Entry into the StateFlow activity.

uint16_t	handle_factory_reset (NodeID target)
	Invokes the openlcb config handler to do a factory reset.

uint16_t	app_handle_factory_reset (NodeID target)
	Weak definition for invoking a factory reset on virtual nodes.

Action	handle_options ()

Action	handle_get_space_info ()

Action	handle_read ()

Action	try_read ()

Action	handle_write ()

Action	try_write ()
	Internal loop performing the writes.

MemorySpace *	get_space ()
	Looks up the memory space for the current datagram.

Private Attributes
Registry	registry_

DatagramHandlerFlow *	client_ {nullptr}
	If there is a memory config client, we will forward response traffic to it.

DatagramHandlerFlow *	streamHandler_ {nullptr}
	If there is a handler for stream requests, we will forward the respective traffic to it.

uint8_t	currentOffset_
	Offset withing the current write/read datagram.

Additional Inherited Members
Public Types inherited from TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >
typedef Base::Action	Action
	Allows using Action without having StateFlowBase:: prefix in front of it.

Public Types inherited from FlowInterface< MessageType >
typedef MessageType	message_type
	Stores the message template type for external reference.

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.

Static Public Member Functions inherited from LinkedObject< StateFlowWithQueue >
static StateFlowWithQueue *	link_head ()

static Atomic *	head_mu ()
	Locks the list for modification (at any entry!).

Static Public Member Functions inherited from FlowInterface< MessageType >
static MessageType *	cast_alloc (QMember *entry)
	Down casts and initializes an asynchronous allocation result to the appropriate flow's buffer type.

Protected Types inherited from openlcb::MemoryConfigHandlerBase
enum	{ DATAGRAM_ID = DatagramDefs::CONFIGURATION }

typedef MemorySpace::address_t	address_t

typedef MemorySpace::errorcode_t	errorcode_t

typedef TypedNodeHandlerMap< Node, MemorySpace >	Registry

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

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

Protected Member Functions inherited from openlcb::MemoryConfigHandlerBase
	MemoryConfigHandlerBase (DatagramService *if_dg)

Action	ok_response_sent () OVERRIDE
	This state is where the handling will end up after a respond_ok call.

Action	cleanup ()

Action	client_allocated ()

Action	send_response_datagram ()

Action	response_flow_complete ()

bool	has_custom_space ()

int	get_space_number ()
	Returns the memory space number, or -1 if the incoming datagram is of incorrect format.

int	get_read_length ()
	Returns the read/write length from byte 6 or 7 of the incoming datagram, or -1 if the incoming datagram is of incorrect format.

int	get_write_length ()

address_t	get_address ()
	Returns the address from the incoming datagram.

void	set_address_and_space ()
	Copies the address and memory space information from the incoming datagram to the outgoing datagram payload.

void	set_address (address_t address)
	Sets the address in the response payload buffer.

uint8_t *	out_bytes ()

const uint8_t *	in_bytes ()

Protected Member Functions inherited from openlcb::DefaultDatagramHandler
	DefaultDatagramHandler (DatagramService *if_datagram)

Action	respond_ok (uint8_t flags)
	Sends a DATAGRAM_OK response to the datagram originator node.

void	inline_respond_ok (uint8_t flags)
	Sends a DATAGRAM_OK response to the datagram originator node.

Action	respond_reject (uint16_t error_code)
	Sends a DATAGRAM_REJECT response to the datagram originator node.

size_t	size ()

const uint8_t *	payload ()

Protected Member Functions inherited from TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >
void	release () OVERRIDE
	Unrefs the current buffer.

void	return_buffer ()
	For state flows that are operated using invoke_subflow_and_wait this is a way to hand back the buffer to the caller.

MessageType *	message ()

MessageType *	transfer_message ()
	Releases ownership of the current message.

Protected Member Functions inherited from UntypedStateFlow< QueueType >
void	send (BufferBase *msg, unsigned priority=UINT_MAX)
	Sends a message to the state flow for processing.

QMember *	queue_next (unsigned *priority) OVERRIDE
	Takes the front entry in the queue.

bool	queue_empty () OVERRIDE

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

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

Action	exit ()
	Terminates the processing of this flow.

Action	release_and_exit ()
	Terminates the processing of the current message.

BufferBase *	message ()

BufferBase *	transfer_message ()
	Releases ownership of the current message.

void	reset_message (BufferBase *message, unsigned priority)
	Sets the current message being processed.

unsigned	priority ()

void	set_priority (unsigned priority)
	Overrides the current priority.

void	start_flow_at_init (Callback c)
	Call this from the constructor of the child class to do some work before the main queue processing loop begins.

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 Member Functions inherited from Atomic
void	lock ()

void	unlock ()

Protected Member Functions inherited from LinkedObject< StateFlowWithQueue >
StateFlowWithQueue *	link_this ()

	LinkedObject ()
	Constructor. Puts *this on the linked list.

	~LinkedObject ()
	Constructor. Removes *this from the linked list.

StateFlowWithQueue *	link_next ()

Static Protected Member Functions inherited from LinkedObject< StateFlowWithQueue >
static StateFlowWithQueue *	link_head ()

static Atomic *	head_mu ()
	Locks the list for modification (at any entry!).

Protected Attributes inherited from openlcb::MemoryConfigHandlerBase
DatagramPayload	response_

DatagramClient *	responseFlow_

BarrierNotifiable	b_

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

Protected Attributes inherited from LinkedObject< StateFlowWithQueue >
StateFlowWithQueue *	link_
	Linked list pointer.

Static Protected Attributes inherited from LinkedObject< StateFlowWithQueue >
static StateFlowWithQueue *	head_
	Beginning of the list.

Detailed Description

Implementation of the Memory Access Configuration Protocol for OpenLCB.

Usage: Create an instance of this object either for the specific virtual node, or for an entire interface. Create your memory spaces using various children of the class MemorySpace. Register the memory spaces using registry().

Definition at line 539 of file MemoryConfig.hxx.

Constructor & Destructor Documentation

◆ MemoryConfigHandler()

openlcb::MemoryConfigHandler::MemoryConfigHandler	(	DatagramService *	if_dg,
		Node *	node,
		int	registry_size
	)

inline

node can be nullptr, and then the handler will be registered globally.

Definition at line 543 of file MemoryConfig.hxx.

◆ ~MemoryConfigHandler()

openlcb::MemoryConfigHandler::~MemoryConfigHandler ( )

inline

@TODO(balazs.racz): unregister *this!

Definition at line 550 of file MemoryConfig.hxx.

Member Function Documentation

◆ app_handle_factory_reset()

uint16_t openlcb::MemoryConfigHandler::app_handle_factory_reset ( NodeID target )

private

Weak definition for invoking a factory reset on virtual nodes.

The default implementation does nothing and return an unimplemented error. Applications that use virtual nodes and need to support factory reset should reimplement this function.

Parameters

target the node ID for which factory reset was invoked.

Returns: openlcb error code, 0 on success

Definition at line 79 of file MemoryConfig.cxx.

◆ clear_client()

void openlcb::MemoryConfigHandler::clear_client ( DatagramHandlerFlow * client )

inline

Unregisters the previously registered second handler.

Definition at line 606 of file MemoryConfig.hxx.

◆ entry()

Action openlcb::MemoryConfigHandler::entry ( )

inlineprivatevirtual

Entry into the StateFlow activity.

Pure virtual which must be defined by derived class.

Returns: function pointer to next state

Implements TypedStateFlow< MessageType, UntypedStateFlow< QueueType > >.

Definition at line 618 of file MemoryConfig.hxx.

◆ get_space()

MemorySpace * openlcb::MemoryConfigHandler::get_space ( )

inlineprivate

Looks up the memory space for the current datagram.

Returns NULL if no space was registered (for neither the current node, nor global).

Definition at line 1042 of file MemoryConfig.hxx.

◆ handle_factory_reset()

uint16_t openlcb::MemoryConfigHandler::handle_factory_reset ( NodeID target )

private

Invokes the openlcb config handler to do a factory reset.

Starts a timer to reboot the device after a little time.

Parameters

target the node ID for which factory reset was invoked.

Returns: openlcb error code, 0 on success

Definition at line 84 of file MemoryConfig.cxx.

◆ handle_get_space_info()

Action openlcb::MemoryConfigHandler::handle_get_space_info ( )

inlineprivate

Definition at line 832 of file MemoryConfig.hxx.

◆ handle_options()

Action openlcb::MemoryConfigHandler::handle_options ( )

inlineprivate

Definition at line 778 of file MemoryConfig.hxx.

◆ handle_read()

Action openlcb::MemoryConfigHandler::handle_read ( )

inlineprivate

Definition at line 872 of file MemoryConfig.hxx.

◆ handle_write()

Action openlcb::MemoryConfigHandler::handle_write ( )

inlineprivate

Definition at line 957 of file MemoryConfig.hxx.

◆ registry()

Registry * openlcb::MemoryConfigHandler::registry ( )

inline

Definition at line 555 of file MemoryConfig.hxx.

◆ send()

void openlcb::MemoryConfigHandler::send	(	DefaultDatagramHandler::message_type *	message,
		unsigned	priority = `UINT_MAX`
	)

inlineoverridevirtual

Overrides the default send method in orderto decide whether the queue the incoming datagram in the server queue or the client queue.

Implements FlowInterface< MessageType >.

Definition at line 562 of file MemoryConfig.hxx.

◆ set_client()

void openlcb::MemoryConfigHandler::set_client ( DatagramHandlerFlow * client )

inline

Registers a second handler to forward all the client interactions, i.e.

everythingthat comes back with the RESPONSE bit set.

Definition at line 600 of file MemoryConfig.hxx.

◆ set_stream_handler()

void openlcb::MemoryConfigHandler::set_stream_handler ( DatagramHandlerFlow * stream_handler )

inline

This will be called by the constructor of the stream handler plugin.

Definition at line 612 of file MemoryConfig.hxx.

◆ try_read()

Action openlcb::MemoryConfigHandler::try_read ( )

inlineprivate

Definition at line 901 of file MemoryConfig.hxx.

◆ try_write()

Action openlcb::MemoryConfigHandler::try_write ( )

inlineprivate

Internal loop performing the writes.

This state will be invoked multiple times if the writes are asynchronous. The OK datagram response has been already sent. Eventually when all writes are completed, the ok_response_sent state will be invoked. This is correct even if there is an error; the error will be returned in the response datagram.

Definition at line 988 of file MemoryConfig.hxx.

Member Data Documentation

◆ client_

DatagramHandlerFlow* openlcb::MemoryConfigHandler::client_ {nullptr}

private

If there is a memory config client, we will forward response traffic to it.

Definition at line 1072 of file MemoryConfig.hxx.

◆ currentOffset_

uint8_t openlcb::MemoryConfigHandler::currentOffset_

private

Offset withing the current write/read datagram.

This does not include the offset from the incoming datagram.

Definition at line 1079 of file MemoryConfig.hxx.

◆ registry_

Registry openlcb::MemoryConfigHandler::registry_

private

Todo:: (balazs.racz) implement lock/unlock.

Definition at line 1069 of file MemoryConfig.hxx.

◆ streamHandler_

DatagramHandlerFlow* openlcb::MemoryConfigHandler::streamHandler_ {nullptr}

private

If there is a handler for stream requests, we will forward the respective traffic to it.

Definition at line 1075 of file MemoryConfig.hxx.

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

Classes

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MemoryConfigHandler()

◆ ~MemoryConfigHandler()

Member Function Documentation

◆ app_handle_factory_reset()

◆ clear_client()

◆ entry()

◆ get_space()

◆ handle_factory_reset()

◆ handle_get_space_info()

◆ handle_options()

◆ handle_read()

◆ handle_write()

◆ registry()

◆ send()

◆ set_client()

◆ set_stream_handler()

◆ try_read()

◆ try_write()

Member Data Documentation

◆ client_

◆ currentOffset_

◆ registry_

◆ streamHandler_