protocol_config_mem_operations_handler.c File Reference

Memory-config operations dispatcher implementation. More...

Functions
void	ProtocolConfigMemOperationsHandler_initialize (const interface_protocol_config_mem_operations_handler_t *interface_protocol_config_mem_operations_handler)
	Stores the callback interface. Call once at startup.
void	ProtocolConfigMemOperationsHandler_request_options_cmd (openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info)
	Build a Get Configuration Options reply datagram.
void	ProtocolConfigMemOperationsHandler_request_get_address_space_info (openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info)
	Build a Get Address Space Info reply (present or not-present).
void	ProtocolConfigMemOperationsHandler_request_reserve_lock (openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info)
	Handle Lock/Reserve command: grant, release, or report current holder.
void	ProtocolConfigMemOperationsHandler_options_cmd (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Get Configuration Options command to two-phase handler.
void	ProtocolConfigMemOperationsHandler_options_reply (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Get Configuration Options reply to two-phase handler.
void	ProtocolConfigMemOperationsHandler_get_address_space_info (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Get Address Space Info command to two-phase handler.
void	ProtocolConfigMemOperationsHandler_get_address_space_info_reply_not_present (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Address Space Info Not Present reply to two-phase handler.
void	ProtocolConfigMemOperationsHandler_get_address_space_info_reply_present (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Address Space Info Present reply to two-phase handler.
void	ProtocolConfigMemOperationsHandler_reserve_lock (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Lock/Reserve command to two-phase handler.
void	ProtocolConfigMemOperationsHandler_reserve_lock_reply (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Lock/Reserve reply to two-phase handler.
void	ProtocolConfigMemOperationsHandler_get_unique_id (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Get Unique ID command to two-phase handler.
void	ProtocolConfigMemOperationsHandler_get_unique_id_reply (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Get Unique ID reply to two-phase handler.
void	ProtocolConfigMemOperationsHandler_unfreeze (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Unfreeze command to two-phase handler.
void	ProtocolConfigMemOperationsHandler_freeze (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Freeze command to two-phase handler.
void	ProtocolConfigMemOperationsHandler_update_complete (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Update Complete command to two-phase handler.
void	ProtocolConfigMemOperationsHandler_reset_reboot (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Reset/Reboot command.
void	ProtocolConfigMemOperationsHandler_factory_reset (openlcb_statemachine_info_t *statemachine_info)
	Dispatch Factory Reset command to two-phase handler.

Detailed Description

Memory-config operations dispatcher implementation.

Copyright

Copyright (c) 2024, Jim Kueneman All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Two-phase ACK-then-execute handling for options, address-space info, lock, freeze, reset, and factory-reset sub-commands. Routes each operation to registered callbacks and sends appropriate replies.

Author

Jim Kueneman

Date

9 Mar 2026

See also

protocol_config_mem_operations_handler.h

MemoryConfigurationS.pdf

Function Documentation

ProtocolConfigMemOperationsHandler_initialize()

void ProtocolConfigMemOperationsHandler_initialize

(

const interface_protocol_config_mem_operations_handler_t *

interface_protocol_config_mem_operations_handler

)

Stores the callback interface. Call once at startup.

* @param interface_protocol_config_mem_operations_handler  Populated table.
* 

Warning

Structure must remain valid for application lifetime.

ProtocolConfigMemOperationsHandler_request_options_cmd()

void ProtocolConfigMemOperationsHandler_request_options_cmd	(	openlcb_statemachine_info_t *	statemachine_info,
		config_mem_operations_request_info_t *	config_mem_operations_request_info )

Build a Get Configuration Options reply datagram.

Build outgoing Get Configuration Options command datagram.

Algorithm:

1. Load header, write OPTIONS_REPLY + command flags + write flags + high/low space bounds + optional description string
2. Mark outgoing message valid

* @param statemachine_info                   Context.
* @param config_mem_operations_request_info   Request info.
* 

ProtocolConfigMemOperationsHandler_request_get_address_space_info()

void ProtocolConfigMemOperationsHandler_request_get_address_space_info	(	openlcb_statemachine_info_t *	statemachine_info,
		config_mem_operations_request_info_t *	config_mem_operations_request_info )

Build a Get Address Space Info reply (present or not-present).

Build outgoing Get Address Space Info command datagram.

Algorithm:

1. If space exists and is present: reply with highest address, flags, optional low address, optional description
2. Otherwise: reply NOT_PRESENT with padded 8-byte payload

* @param statemachine_info                   Context.
* @param config_mem_operations_request_info   Carries space_info pointer.
* 

ProtocolConfigMemOperationsHandler_request_reserve_lock()

void ProtocolConfigMemOperationsHandler_request_reserve_lock	(	openlcb_statemachine_info_t *	statemachine_info,
		config_mem_operations_request_info_t *	config_mem_operations_request_info )

Handle Lock/Reserve command: grant, release, or report current holder.

Build outgoing Lock/Reserve command datagram.

Algorithm:

1. Extract requester Node ID from payload
2. If unlocked: grant to requester
3. If locked and ID == 0: release (standard release)
4. If locked and ID == current owner: release (owner self-release per MemoryConfigurationS §4.11)
5. Otherwise: deny — reply with current owner Node ID

* @param statemachine_info                   Context.
* @param config_mem_operations_request_info   Request info.
* 

ProtocolConfigMemOperationsHandler_options_cmd()

void ProtocolConfigMemOperationsHandler_options_cmd

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Get Configuration Options command to two-phase handler.

Handle incoming Get Configuration Options command.

ProtocolConfigMemOperationsHandler_options_reply()

void ProtocolConfigMemOperationsHandler_options_reply

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Get Configuration Options reply to two-phase handler.

Handle incoming Get Configuration Options reply.

ProtocolConfigMemOperationsHandler_get_address_space_info()

void ProtocolConfigMemOperationsHandler_get_address_space_info

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Get Address Space Info command to two-phase handler.

Handle incoming Get Address Space Info command.

ProtocolConfigMemOperationsHandler_get_address_space_info_reply_not_present()

void ProtocolConfigMemOperationsHandler_get_address_space_info_reply_not_present

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Address Space Info Not Present reply to two-phase handler.

Handle incoming Address Space Info Not Present reply.

ProtocolConfigMemOperationsHandler_get_address_space_info_reply_present()

void ProtocolConfigMemOperationsHandler_get_address_space_info_reply_present

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Address Space Info Present reply to two-phase handler.

Handle incoming Address Space Info Present reply.

ProtocolConfigMemOperationsHandler_reserve_lock()

void ProtocolConfigMemOperationsHandler_reserve_lock

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Lock/Reserve command to two-phase handler.

Handle incoming Lock/Reserve command.

ProtocolConfigMemOperationsHandler_reserve_lock_reply()

void ProtocolConfigMemOperationsHandler_reserve_lock_reply

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Lock/Reserve reply to two-phase handler.

Handle incoming Lock/Reserve reply.

ProtocolConfigMemOperationsHandler_get_unique_id()

void ProtocolConfigMemOperationsHandler_get_unique_id

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Get Unique ID command to two-phase handler.

Handle incoming Get Unique ID command.

ProtocolConfigMemOperationsHandler_get_unique_id_reply()

void ProtocolConfigMemOperationsHandler_get_unique_id_reply

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Get Unique ID reply to two-phase handler.

Handle incoming Get Unique ID reply.

ProtocolConfigMemOperationsHandler_unfreeze()

void ProtocolConfigMemOperationsHandler_unfreeze

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Unfreeze command to two-phase handler.

Handle incoming Unfreeze command.

ProtocolConfigMemOperationsHandler_freeze()

void ProtocolConfigMemOperationsHandler_freeze

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Freeze command to two-phase handler.

Handle incoming Freeze command.

ProtocolConfigMemOperationsHandler_update_complete()

void ProtocolConfigMemOperationsHandler_update_complete

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Update Complete command to two-phase handler.

Handle incoming Update Complete command.

ProtocolConfigMemOperationsHandler_reset_reboot()

void ProtocolConfigMemOperationsHandler_reset_reboot

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Reset/Reboot command.

Handle incoming Reset/Reboot command.

Per MemoryConfigurationS Section 4.24, the Reset/Reboot command is only [0x20, 0xA9] with no Node ID in the payload. Unlike Factory Reset (0xAA, Section 4.25) which requires a Node ID as a safety guard, Reset/Reboot applies unconditionally to the addressed node.

Per Section 4.24: "The receiving node may acknowledge this command with a Node Initialization Complete instead of a Datagram Received OK response." We skip the datagram ACK — the Initialization Complete from the reboot serves as acknowledgment.

ProtocolConfigMemOperationsHandler_factory_reset()

void ProtocolConfigMemOperationsHandler_factory_reset

(

openlcb_statemachine_info_t *

statemachine_info

)

Dispatch Factory Reset command to two-phase handler.

Handle incoming Factory Reset command (destructive).

Per MemoryConfigurationS Section 4.25, the Reinitialize/Factory Reset command includes a 6-byte Node ID (bytes 2-7) as a safety guard. The target Node ID must match or the command is silently ignored.