protocol_config_mem_read_handler.h File Reference

Configuration memory read handler. More...

Go to the source code of this file.

Data Structures
struct	interface_protocol_config_mem_read_handler_t
	Callback interface for config memory reads. Datagram ACK and config_memory_read are REQUIRED; SNIP loaders and per-space handlers are optional. More...

Functions
void	ProtocolConfigMemReadHandler_initialize (const interface_protocol_config_mem_read_handler_t *interface_protocol_config_mem_read_handler)
	Stores the callback interface. Call once at startup.
void	ProtocolConfigMemReadHandler_read_space_config_description_info (openlcb_statemachine_info_t *statemachine_info)
	Read from CDI space (0xFF).
void	ProtocolConfigMemReadHandler_read_space_all (openlcb_statemachine_info_t *statemachine_info)
	Read from All space (0xFE).
void	ProtocolConfigMemReadHandler_read_space_config_memory (openlcb_statemachine_info_t *statemachine_info)
	Read from Config space (0xFD).
void	ProtocolConfigMemReadHandler_read_space_acdi_manufacturer (openlcb_statemachine_info_t *statemachine_info)
	Read from ACDI-Mfg space (0xFC).
void	ProtocolConfigMemReadHandler_read_space_acdi_user (openlcb_statemachine_info_t *statemachine_info)
	Read from ACDI-User space (0xFB).
void	ProtocolConfigMemReadHandler_read_space_train_function_definition_info (openlcb_statemachine_info_t *statemachine_info)
	Read from Train FDI space (0xFA).
void	ProtocolConfigMemReadHandler_read_space_train_function_config_memory (openlcb_statemachine_info_t *statemachine_info)
	Read from Train Fn Config space (0xF9).
void	ProtocolConfigMemReadHandler_read_request_config_definition_info (openlcb_statemachine_info_t *statemachine_info, config_mem_read_request_info_t *config_mem_read_request_info)
	Send read request targeting CDI (0xFF) on another node.
void	ProtocolConfigMemReadHandler_read_request_config_mem (openlcb_statemachine_info_t *statemachine_info, config_mem_read_request_info_t *config_mem_read_request_info)
	Send read request targeting Config (0xFD) on another node.
void	ProtocolConfigMemReadHandler_read_request_acdi_manufacturer (openlcb_statemachine_info_t *statemachine_info, config_mem_read_request_info_t *config_mem_read_request_info)
	Send read request targeting ACDI-Mfg (0xFC) on another node.
void	ProtocolConfigMemReadHandler_read_request_acdi_user (openlcb_statemachine_info_t *statemachine_info, config_mem_read_request_info_t *config_mem_read_request_info)
	Send read request targeting ACDI-User (0xFB) on another node.
void	ProtocolConfigMemReadHandler_read_request_train_function_definition_info (openlcb_statemachine_info_t *statemachine_info, config_mem_read_request_info_t *config_mem_read_request_info)
	Send read request targeting Train FDI (0xFA) on another node.
void	ProtocolConfigMemReadHandler_read_request_train_function_config_memory (openlcb_statemachine_info_t *statemachine_info, config_mem_read_request_info_t *config_mem_read_request_info)
	Send read request targeting Train Fn Config (0xF9) on another node.
void	ProtocolConfigMemReadHandler_read_message (openlcb_statemachine_info_t *statemachine_info, uint8_t space, uint8_t return_msg_ok, uint8_t return_msg_fail)
	Generic read message handler. Placeholder.
void	ProtocolConfigMemReadHandler_read_reply_ok_message (openlcb_statemachine_info_t *statemachine_info, uint8_t space)
	Generic read reply OK handler. Placeholder.
void	ProtocolConfigMemReadHandler_read_reply_reject_message (openlcb_statemachine_info_t *statemachine_info, uint8_t space)
	Generic read reply reject handler. Placeholder.

Detailed Description

Configuration memory read handler.

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.

Processes datagram read commands for CDI (0xFF), All (0xFE), Config (0xFD), ACDI-Mfg (0xFC), ACDI-User (0xFB), Train FDI (0xFA), and Train Fn Config (0xF9). Uses a two-phase ACK-then-reply pattern and supports optional per-space handler overrides and delayed replies.

Author

Jim Kueneman

Date

9 Mar 2026

Function Documentation

ProtocolConfigMemReadHandler_initialize()

void ProtocolConfigMemReadHandler_initialize ( const interface_protocol_config_mem_read_handler_t * interface_protocol_config_mem_read_handler )

extern

Stores the callback interface. Call once at startup.

Parameters

interface_protocol_config_mem_read_handler

Pointer to interface_protocol_config_mem_read_handler_t (must remain valid for application lifetime).

* @param interface_protocol_config_mem_read_handler  Populated table.
* 

Warning

Structure must remain valid for application lifetime.

ProtocolConfigMemReadHandler_read_space_config_description_info()

void ProtocolConfigMemReadHandler_read_space_config_description_info ( openlcb_statemachine_info_t * statemachine_info )

extern

Read from CDI space (0xFF).

Parameters

statemachine_info

Pointer to openlcb_statemachine_info_t context.

Read from CDI space (0xFF).

ProtocolConfigMemReadHandler_read_space_all()

void ProtocolConfigMemReadHandler_read_space_all ( openlcb_statemachine_info_t * statemachine_info )

extern

Read from All space (0xFE).

Parameters

statemachine_info

Pointer to openlcb_statemachine_info_t context.

Read from All space (0xFE).

ProtocolConfigMemReadHandler_read_space_config_memory()

void ProtocolConfigMemReadHandler_read_space_config_memory ( openlcb_statemachine_info_t * statemachine_info )

extern

Read from Config space (0xFD).

Parameters

statemachine_info

Pointer to openlcb_statemachine_info_t context.

Read from Config space (0xFD).

ProtocolConfigMemReadHandler_read_space_acdi_manufacturer()

void ProtocolConfigMemReadHandler_read_space_acdi_manufacturer ( openlcb_statemachine_info_t * statemachine_info )

extern

Read from ACDI-Mfg space (0xFC).

Parameters

statemachine_info

Pointer to openlcb_statemachine_info_t context.

Read from ACDI-Mfg space (0xFC).

ProtocolConfigMemReadHandler_read_space_acdi_user()

void ProtocolConfigMemReadHandler_read_space_acdi_user ( openlcb_statemachine_info_t * statemachine_info )

extern

Read from ACDI-User space (0xFB).

Parameters

statemachine_info

Pointer to openlcb_statemachine_info_t context.

Read from ACDI-User space (0xFB).

ProtocolConfigMemReadHandler_read_space_train_function_definition_info()

void ProtocolConfigMemReadHandler_read_space_train_function_definition_info ( openlcb_statemachine_info_t * statemachine_info )

extern

Read from Train FDI space (0xFA).

Parameters

statemachine_info

Pointer to openlcb_statemachine_info_t context.

Read from Train FDI space (0xFA).

ProtocolConfigMemReadHandler_read_space_train_function_config_memory()

void ProtocolConfigMemReadHandler_read_space_train_function_config_memory ( openlcb_statemachine_info_t * statemachine_info )

extern

Read from Train Fn Config space (0xF9).

Parameters

statemachine_info

Pointer to openlcb_statemachine_info_t context.

Read from Train Fn Config space (0xF9).

ProtocolConfigMemReadHandler_read_request_config_definition_info()

void ProtocolConfigMemReadHandler_read_request_config_definition_info ( openlcb_statemachine_info_t * statemachine_info, config_mem_read_request_info_t * config_mem_read_request_info )

extern

Send read request targeting CDI (0xFF) on another node.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
config_mem_read_request_info	Pointer to config_mem_read_request_info_t request.

Send read request targeting CDI (0xFF) on another node.

ProtocolConfigMemReadHandler_read_request_config_mem()

void ProtocolConfigMemReadHandler_read_request_config_mem ( openlcb_statemachine_info_t * statemachine_info, config_mem_read_request_info_t * config_mem_read_request_info )

extern

Send read request targeting Config (0xFD) on another node.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
config_mem_read_request_info	Pointer to config_mem_read_request_info_t request.

Send read request targeting Config (0xFD) on another node.

Partial reads (fewer bytes than requested) return TRANSFER_ERROR.

ProtocolConfigMemReadHandler_read_request_acdi_manufacturer()

void ProtocolConfigMemReadHandler_read_request_acdi_manufacturer ( openlcb_statemachine_info_t * statemachine_info, config_mem_read_request_info_t * config_mem_read_request_info )

extern

Send read request targeting ACDI-Mfg (0xFC) on another node.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
config_mem_read_request_info	Pointer to config_mem_read_request_info_t request.

Send read request targeting ACDI-Mfg (0xFC) on another node.

ProtocolConfigMemReadHandler_read_request_acdi_user()

void ProtocolConfigMemReadHandler_read_request_acdi_user ( openlcb_statemachine_info_t * statemachine_info, config_mem_read_request_info_t * config_mem_read_request_info )

extern

Send read request targeting ACDI-User (0xFB) on another node.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
config_mem_read_request_info	Pointer to config_mem_read_request_info_t request.

Send read request targeting ACDI-User (0xFB) on another node.

ProtocolConfigMemReadHandler_read_request_train_function_definition_info()

void ProtocolConfigMemReadHandler_read_request_train_function_definition_info ( openlcb_statemachine_info_t * statemachine_info, config_mem_read_request_info_t * config_mem_read_request_info )

extern

Send read request targeting Train FDI (0xFA) on another node.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
config_mem_read_request_info	Pointer to config_mem_read_request_info_t request.

Send read request targeting Train FDI (0xFA) on another node.

ProtocolConfigMemReadHandler_read_request_train_function_config_memory()

void ProtocolConfigMemReadHandler_read_request_train_function_config_memory ( openlcb_statemachine_info_t * statemachine_info, config_mem_read_request_info_t * config_mem_read_request_info )

extern

Send read request targeting Train Fn Config (0xF9) on another node.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
config_mem_read_request_info	Pointer to config_mem_read_request_info_t request.

Send read request targeting Train Fn Config (0xF9) on another node.

Each 16-bit function value occupies 2 bytes big-endian: address/2 = fn_index, address%2 selects high/low byte.

ProtocolConfigMemReadHandler_read_message()

void ProtocolConfigMemReadHandler_read_message ( openlcb_statemachine_info_t * statemachine_info, uint8_t space, uint8_t return_msg_ok, uint8_t return_msg_fail )

extern

Generic read message handler. Placeholder.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
space	Address space number.
return_msg_ok	MTI for success reply.
return_msg_fail	MTI for failure reply.

ProtocolConfigMemReadHandler_read_reply_ok_message()

void ProtocolConfigMemReadHandler_read_reply_ok_message ( openlcb_statemachine_info_t * statemachine_info, uint8_t space )

extern

Generic read reply OK handler. Placeholder.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
space	Address space number.

ProtocolConfigMemReadHandler_read_reply_reject_message()

void ProtocolConfigMemReadHandler_read_reply_reject_message ( openlcb_statemachine_info_t * statemachine_info, uint8_t space )

extern

Generic read reply reject handler. Placeholder.

Parameters

statemachine_info	Pointer to openlcb_statemachine_info_t context.
space	Address space number.