Appendix E — Compile-Time Configuration Reference

All compile-time configuration is provided by the application in openlcb_user_config.h. This file must be placed on the compiler's include path. A template is provided in templates/openlcb_user_config.h.

E.1 Required Buffer Depth Macros

These macros control the static memory allocation for message buffer pools. All must be defined:

Macro	Purpose	Per-Buffer Size	Typical Value
`USER_DEFINED_BASIC_BUFFER_DEPTH`	Number of BASIC message buffers	16 bytes	5-10
`USER_DEFINED_DATAGRAM_BUFFER_DEPTH`	Number of DATAGRAM message buffers	72 bytes	2-5
`USER_DEFINED_SNIP_BUFFER_DEPTH`	Number of SNIP message buffers	256 bytes	1-3
`USER_DEFINED_STREAM_BUFFER_DEPTH`	Number of STREAM message buffers	512 bytes	0-2
`USER_DEFINED_CAN_MSG_BUFFER_DEPTH`	Number of CAN frame buffers (FIFO depth)	~16 bytes	5-20

Buffer Limit

The sum BASIC + DATAGRAM + SNIP + STREAM must not exceed 126 on 8-bit targets. This is enforced at compile time by openlcb_config.h.

E.2 Required Node and Event Macros

Macro	Purpose	Typical Value
`USER_DEFINED_NODE_BUFFER_DEPTH`	Maximum virtual nodes that can be allocated	1-5
`USER_DEFINED_PRODUCER_COUNT`	Max events a node can produce	2-16
`USER_DEFINED_CONSUMER_COUNT`	Max events a node can consume	2-16
`USER_DEFINED_PRODUCER_RANGE_COUNT`	Max producer event ranges (must be >= 1)	1-4
`USER_DEFINED_CONSUMER_RANGE_COUNT`	Max consumer event ranges (must be >= 1)	1-4
`USER_DEFINED_CDI_LENGTH`	CDI XML buffer size in bytes	256-2048
`USER_DEFINED_FDI_LENGTH`	FDI XML buffer size in bytes (train nodes)	1-512

E.3 Required Config Memory Macros

Macro	Purpose
`USER_DEFINED_CONFIG_MEM_USER_NAME_ADDRESS`	Address in config memory for user-assigned node name
`USER_DEFINED_CONFIG_MEM_USER_DESCRIPTION_ADDRESS`	Address in config memory for user description

E.4 Required Train Macros

These must be defined even if train support is not enabled (set to 0 if not needed):

Macro	Purpose	Typical Value
`USER_DEFINED_TRAIN_NODE_COUNT`	Max train nodes that can be allocated	0-8
`USER_DEFINED_MAX_LISTENERS_PER_TRAIN`	Max consist members per train	0-4
`USER_DEFINED_MAX_TRAIN_FUNCTIONS`	DCC functions per train (29 = F0-F28)	0-29

E.5 Feature Flag Macros

Define these to enable optional protocol support. Each flag includes the corresponding protocol handler code and callbacks in the build:

Macro	Enables	Dependencies
`OPENLCB_COMPILE_EVENTS`	Event Transport Protocol (Producer/Consumer)	None
`OPENLCB_COMPILE_DATAGRAMS`	Datagram Protocol	None
`OPENLCB_COMPILE_MEMORY_CONFIGURATION`	Memory Configuration Protocol (read/write/operations)	`DATAGRAMS`
`OPENLCB_COMPILE_FIRMWARE`	Firmware Upgrade Protocol (freeze/unfreeze/write)	`MEMORY_CONFIGURATION`
`OPENLCB_COMPILE_BROADCAST_TIME`	Broadcast Time Protocol	`EVENTS`
`OPENLCB_COMPILE_TRAIN`	Train Control Protocol	None
`OPENLCB_COMPILE_TRAIN_SEARCH`	Train Search Protocol	`EVENTS` + `TRAIN`
`OPENLCB_COMPILE_VERBOSE`	Compile-time summary via `#pragma message`	None

E.6 Feature Dependency Tree

flowchart TD EVT["OPENLCB_COMPILE_EVENTS"] DG["OPENLCB_COMPILE_DATAGRAMS"] MC["OPENLCB_COMPILE_MEMORY_CONFIGURATION"] FW["OPENLCB_COMPILE_FIRMWARE"] BT["OPENLCB_COMPILE_BROADCAST_TIME"] TR["OPENLCB_COMPILE_TRAIN"] TS["OPENLCB_COMPILE_TRAIN_SEARCH"] MC -->|requires| DG FW -->|requires| MC BT -->|requires| EVT TS -->|requires| EVT TS -->|requires| TR style EVT fill:#e8f5e9,stroke:#2e7d32 style DG fill:#e8f5e9,stroke:#2e7d32 style MC fill:#e3f2fd,stroke:#1565c0 style FW fill:#e3f2fd,stroke:#1565c0 style BT fill:#fff3e0,stroke:#e65100 style TR fill:#e8f5e9,stroke:#2e7d32 style TS fill:#fff3e0,stroke:#e65100

If a dependency is not met, compilation fails with a #error directive. For example, enabling OPENLCB_COMPILE_MEMORY_CONFIGURATION without OPENLCB_COMPILE_DATAGRAMS produces:

#error "OPENLCB_COMPILE_MEMORY_CONFIGURATION requires OPENLCB_COMPILE_DATAGRAMS"

E.7 Derived Constants

These constants are computed from the user-defined macros. They should not be overridden directly:

Constant	Formula	Purpose
`LEN_MESSAGE_BUFFER`	BASIC + DATAGRAM + SNIP + STREAM	Total number of message buffers
`ALIAS_MAPPING_BUFFER_DEPTH`	`USER_DEFINED_NODE_BUFFER_DEPTH`	Alias table size (one per node)
`LISTENER_ALIAS_TABLE_DEPTH`	MAX_LISTENERS_PER_TRAIN * TRAIN_NODE_COUNT	Listener alias table size

E.8 No-Features Warning

If no optional features are enabled, the compiler issues a warning:

#if !defined(OPENLCB_COMPILE_EVENTS) && !defined(OPENLCB_COMPILE_DATAGRAMS) && \
    !defined(OPENLCB_COMPILE_TRAIN)
#warning "No optional features enabled. This node will only support SNIP identification."
#endif

Source Reference

Required macros are validated with #error directives in openlcb_types.h and can_types.h. Feature dependency validation and buffer sanity checks are in openlcb_config.h. The verbose compile summary is also in openlcb_config.h.

← Prev: Appendix D — Event ID Encoding Next: Appendix F — Spec Traceability →