alias_mappings.h File Reference

Fixed-size buffer mapping 12-bit CAN aliases to 48-bit OpenLCB Node IDs. More...

Go to the source code of this file.

Functions
void	AliasMappings_initialize (void)
	Initializes the alias mapping buffer, clearing all entries and flags.
alias_mapping_info_t *	AliasMappings_get_alias_mapping_info (void)
	Returns a pointer to the internal alias mapping info structure.
void	AliasMappings_set_has_duplicate_alias_flag (void)
	Signals the main loop that an incoming message used one of our reserved aliases.
void	AliasMappings_clear_has_duplicate_alias_flag (void)
	Clears the duplicate alias flag after the conflict has been resolved.
alias_mapping_t *	AliasMappings_register (uint16_t alias, node_id_t node_id)
	Registers a CAN alias / Node ID pair in the buffer.
void	AliasMappings_unregister (uint16_t alias)
	Removes the entry matching the given alias from the buffer.
alias_mapping_t *	AliasMappings_find_mapping_by_alias (uint16_t alias)
	Finds the mapping entry for the given alias.
alias_mapping_t *	AliasMappings_find_mapping_by_node_id (node_id_t node_id)
	Finds the mapping entry for the given Node ID.
void	AliasMappings_flush (void)
	Clears all alias mappings and resets all flags.

Detailed Description

Fixed-size buffer mapping 12-bit CAN aliases to 48-bit OpenLCB Node IDs.

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.

Supports bidirectional lookup (by alias or by Node ID), duplicate alias detection, and permission tracking. Used during node login, message routing, and alias conflict resolution. Must be initialized before any node operations.

Author

Jim Kueneman

Date

4 Mar 2026

Function Documentation

AliasMappings_initialize()

void AliasMappings_initialize ( void )

extern

Initializes the alias mapping buffer, clearing all entries and flags.

Warning

Calling during active operation loses all existing mappings and will cause communication failures.

See also

AliasMappings_flush - Runtime equivalent

AliasMappings_get_alias_mapping_info()

alias_mapping_info_t * AliasMappings_get_alias_mapping_info ( void )

extern

Returns a pointer to the internal alias mapping info structure.

Intended for diagnostics and testing. Prefer the specific API functions for normal use — direct modification can break internal consistency.

Returns

Pointer to the alias_mapping_info_t structure (never NULL).

See also

AliasMappings_set_has_duplicate_alias_flag

AliasMappings_clear_has_duplicate_alias_flag

Returns

Pointer to the alias_mapping_info_t structure (never NULL).

AliasMappings_set_has_duplicate_alias_flag()

void AliasMappings_set_has_duplicate_alias_flag ( void )

extern

Signals the main loop that an incoming message used one of our reserved aliases.

Sets the has_duplicate_alias flag. The main state machine must detect this flag and restart alias allocation with a new alias. Setting this flag does NOT automatically trigger reallocation.

Attention

The main loop must clear this flag after resolving the conflict.

See also

AliasMappings_clear_has_duplicate_alias_flag

Signals the main loop that an incoming message used one of our reserved aliases.

AliasMappings_clear_has_duplicate_alias_flag()

void AliasMappings_clear_has_duplicate_alias_flag ( void )

extern

Clears the duplicate alias flag after the conflict has been resolved.

Clears the duplicate alias flag after the conflict has been resolved.

AliasMappings_register()

alias_mapping_t * AliasMappings_register ( uint16_t alias, node_id_t node_id )

extern

Registers a CAN alias / Node ID pair in the buffer.

Searches for an empty slot or an existing entry with the same Node ID. If the Node ID already exists its alias is updated (correct behavior during conflict recovery). Returns NULL if the buffer is full or either parameter is outside its valid range.

Use cases:

• Storing a newly allocated alias during node login
• Updating an alias after conflict resolution
• Recording remote node aliases learned from AMD frames

Parameters

alias	12-bit CAN alias (valid range: 0x001–0xFFF).
node_id	48-bit OpenLCB node_id_t (valid range: 0x000000000001–0xFFFFFFFFFFFF).

Returns

Pointer to the registered alias_mapping_t entry, or NULL on failure.

Warning

Returns NULL when the buffer is full — caller MUST check before use.

Out-of-range alias or node_id values return NULL.

An existing Node ID entry will have its alias silently replaced.

See also

AliasMappings_unregister

AliasMappings_find_mapping_by_alias

AliasMappings_find_mapping_by_node_id

Algorithm:

1. Validate alias is in range 0x001–0xFFF, return NULL if not
2. Validate node_id is in range 0x000000000001–0xFFFFFFFFFFFF, return NULL if not
3. Iterate through all ALIAS_MAPPING_BUFFER_DEPTH entries
4. On first empty slot (alias == 0) or matching Node ID: store alias and node_id, return pointer to that entry
5. If no slot found, return NULL (buffer full)

Use cases:

• Storing a newly allocated alias during node login
• Updating an alias after conflict resolution
• Recording remote node aliases learned from AMD frames

* @param alias    12-bit CAN alias (valid range: 0x001–0xFFF).
* @param node_id  48-bit OpenLCB Node ID (valid range: 0x000000000001–0xFFFFFFFFFFFF).
* 

Returns

Pointer to the registered alias_mapping_t entry, or NULL on failure.

Warning

Returns NULL when the buffer is full — caller MUST check before use.

Out-of-range alias or node_id values return NULL.

An existing Node ID entry will have its alias silently replaced.

See also

AliasMappings_unregister

AliasMappings_find_mapping_by_alias

AliasMappings_find_mapping_by_node_id

AliasMappings_unregister()

void AliasMappings_unregister ( uint16_t alias )

extern

Removes the entry matching the given alias from the buffer.

Safe to call with an alias that does not exist — no error is raised. All fields in the matching slot are cleared so it can be reused.

Parameters

alias

12-bit CAN alias to remove.

Attention

Pointers previously returned for this entry become invalid after removal.

See also

AliasMappings_register

AliasMappings_flush

Algorithm:

1. Iterate through all ALIAS_MAPPING_BUFFER_DEPTH entries
2. On matching alias: clear all four fields and break
3. If no match found, return without action

* @param alias  12-bit CAN alias to remove.
* 

See also

AliasMappings_register

AliasMappings_flush

AliasMappings_find_mapping_by_alias()

alias_mapping_t * AliasMappings_find_mapping_by_alias ( uint16_t alias )

extern

Finds the mapping entry for the given alias.

Parameters

alias

12-bit CAN alias to search for.

Returns

Pointer to the matching alias_mapping_t entry, or NULL if not found.

Warning

NULL is returned when not found — caller MUST check before use.

See also

AliasMappings_find_mapping_by_node_id

Algorithm:

1. Validate alias is in range 0x001–0xFFF, return NULL if not
2. Iterate through all entries; return pointer on first match
3. Return NULL if no match found

* @param alias  12-bit CAN alias to search for.
* 

Returns

Pointer to the matching alias_mapping_t entry, or NULL if not found.

Warning

NULL is returned when not found — caller MUST check before use.

See also

AliasMappings_find_mapping_by_node_id

AliasMappings_find_mapping_by_node_id()

alias_mapping_t * AliasMappings_find_mapping_by_node_id ( node_id_t node_id )

extern

Finds the mapping entry for the given Node ID.

Parameters

node_id

48-bit OpenLCB node_id_t to search for.

Returns

Pointer to the matching alias_mapping_t entry, or NULL if not found.

Warning

NULL is returned when not found — caller MUST check before use.

See also

AliasMappings_find_mapping_by_alias

Algorithm:

1. Validate node_id is in range 0x000000000001–0xFFFFFFFFFFFF, return NULL if not
2. Iterate through all entries; return pointer on first match
3. Return NULL if no match found

* @param node_id  48-bit OpenLCB Node ID to search for.
* 

Returns

Pointer to the matching alias_mapping_t entry, or NULL if not found.

Warning

NULL is returned when not found — caller MUST check before use.

See also

AliasMappings_find_mapping_by_alias

AliasMappings_flush()

void AliasMappings_flush ( void )

extern

Clears all alias mappings and resets all flags.

Functionally identical to AliasMappings_initialize() but intended for runtime use (system reset, test teardown). Use initialize() at startup.

Warning

Invalidates ALL pointers previously returned by register or find functions.

All nodes lose their CAN bus identity and must re-login.

See also

AliasMappings_initialize

AliasMappings_unregister

Clears all alias mappings and resets all flags.