OpenLcbCLib 1.0 Alpha
OpenSource C Library to create OpenLcb/Lcc Nodes
Loading...
Searching...
No Matches
Data Structures | Functions
protocol_config_mem_operations_handler.h File Reference

Configuration memory operations dispatcher. More...

Go to the source code of this file.

Data Structures

struct  interface_protocol_config_mem_operations_handler_t
 Callback interface for memory-config operations. 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_options_cmd (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Get Configuration Options command.
 
void ProtocolConfigMemOperationsHandler_options_reply (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Get Configuration Options reply.
 
void ProtocolConfigMemOperationsHandler_get_address_space_info (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Get Address Space Info command.
 
void ProtocolConfigMemOperationsHandler_get_address_space_info_reply_not_present (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Address Space Info Not Present reply.
 
void ProtocolConfigMemOperationsHandler_get_address_space_info_reply_present (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Address Space Info Present reply.
 
void ProtocolConfigMemOperationsHandler_reserve_lock (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Lock/Reserve command.
 
void ProtocolConfigMemOperationsHandler_reserve_lock_reply (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Lock/Reserve reply.
 
void ProtocolConfigMemOperationsHandler_get_unique_id (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Get Unique ID command.
 
void ProtocolConfigMemOperationsHandler_get_unique_id_reply (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Get Unique ID reply.
 
void ProtocolConfigMemOperationsHandler_unfreeze (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Unfreeze command.
 
void ProtocolConfigMemOperationsHandler_freeze (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Freeze command.
 
void ProtocolConfigMemOperationsHandler_update_complete (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Update Complete command.
 
void ProtocolConfigMemOperationsHandler_reset_reboot (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Reset/Reboot command.
 
void ProtocolConfigMemOperationsHandler_factory_reset (openlcb_statemachine_info_t *statemachine_info)
 Handle incoming Factory Reset command (destructive).
 
void ProtocolConfigMemOperationsHandler_request_options_cmd (openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info)
 Build outgoing Get Configuration Options command 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 outgoing Get Address Space Info command datagram.
 
void ProtocolConfigMemOperationsHandler_request_reserve_lock (openlcb_statemachine_info_t *statemachine_info, config_mem_operations_request_info_t *config_mem_operations_request_info)
 Build outgoing Lock/Reserve command datagram.
 

Detailed Description

Configuration memory operations dispatcher.

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.

Routes memory-config datagram sub-commands (options, address-space info, lock, freeze, reset, factory-reset) to registered callbacks. Uses a two-phase ACK-then-execute pattern and supports optional per-command handler overrides.

Author
Jim Kueneman
Date
9 Mar 2026
See also
MemoryConfigurationS.pdf

Function Documentation

◆ ProtocolConfigMemOperationsHandler_initialize()

void ProtocolConfigMemOperationsHandler_initialize ( const interface_protocol_config_mem_operations_handler_t * interface_protocol_config_mem_operations_handler)
extern

Stores the callback interface. Call once at startup.

Parameters
interface_protocol_config_mem_operations_handlerPointer to interface_protocol_config_mem_operations_handler_t (must remain valid for application lifetime).
* @param interface_protocol_config_mem_operations_handler  Populated table.
*
Warning
Structure must remain valid for application lifetime.

◆ ProtocolConfigMemOperationsHandler_options_cmd()

void ProtocolConfigMemOperationsHandler_options_cmd ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Get Configuration Options command.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Get Configuration Options command.

◆ ProtocolConfigMemOperationsHandler_options_reply()

void ProtocolConfigMemOperationsHandler_options_reply ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Get Configuration Options reply.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Get Configuration Options reply.

◆ ProtocolConfigMemOperationsHandler_get_address_space_info()

void ProtocolConfigMemOperationsHandler_get_address_space_info ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Get Address Space Info command.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

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)
extern

Handle incoming Address Space Info Not Present reply.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

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)
extern

Handle incoming Address Space Info Present reply.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Address Space Info Present reply.

◆ ProtocolConfigMemOperationsHandler_reserve_lock()

void ProtocolConfigMemOperationsHandler_reserve_lock ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Lock/Reserve command.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Lock/Reserve command.

◆ ProtocolConfigMemOperationsHandler_reserve_lock_reply()

void ProtocolConfigMemOperationsHandler_reserve_lock_reply ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Lock/Reserve reply.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Lock/Reserve reply.

◆ ProtocolConfigMemOperationsHandler_get_unique_id()

void ProtocolConfigMemOperationsHandler_get_unique_id ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Get Unique ID command.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Get Unique ID command.

◆ ProtocolConfigMemOperationsHandler_get_unique_id_reply()

void ProtocolConfigMemOperationsHandler_get_unique_id_reply ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Get Unique ID reply.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Get Unique ID reply.

◆ ProtocolConfigMemOperationsHandler_unfreeze()

void ProtocolConfigMemOperationsHandler_unfreeze ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Unfreeze command.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Unfreeze command.

◆ ProtocolConfigMemOperationsHandler_freeze()

void ProtocolConfigMemOperationsHandler_freeze ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Freeze command.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Freeze command.

◆ ProtocolConfigMemOperationsHandler_update_complete()

void ProtocolConfigMemOperationsHandler_update_complete ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Update Complete command.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

Handle incoming Update Complete command.

◆ ProtocolConfigMemOperationsHandler_reset_reboot()

void ProtocolConfigMemOperationsHandler_reset_reboot ( openlcb_statemachine_info_t * statemachine_info)
extern

Handle incoming Reset/Reboot command.

Per MemoryConfigurationS Section 4.24, the node acknowledges with Initialization Complete instead of Datagram Received OK.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

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)
extern

Handle incoming Factory Reset command (destructive).

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.

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.

◆ 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 )
extern

Build outgoing Get Configuration Options command datagram.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.
config_mem_operations_request_infoPointer to config_mem_operations_request_info_t request.

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 )
extern

Build outgoing Get Address Space Info command datagram.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.
config_mem_operations_request_infoPointer to config_mem_operations_request_info_t request.

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 )
extern

Build outgoing Lock/Reserve command datagram.

Parameters
statemachine_infoPointer to openlcb_statemachine_info_t context.
config_mem_operations_request_infoPointer to config_mem_operations_request_info_t request.

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.
*

Copyright (c) 2026 Jim Kueneman all rights reserved. See the License