Chapter 19 — Alias Mapping: Global Table

On a CAN bus, every OpenLCB node is identified by a 48-bit Node ID, but CAN 2.0B frames only provide 12 bits for source addressing. The alias mapping table bridges this gap by maintaining a registry of 12-bit CAN alias to 48-bit Node ID pairs. This chapter covers the global alias mapping table implemented in alias_mappings.h and alias_mappings.c.

19.1 The alias_mapping_t Structure

Each entry in the alias mapping table is an alias_mapping_t:

typedef struct alias_mapping_struct {
    node_id_t node_id;        // Permanent 48-bit Node ID
    uint16_t alias;           // Temporary 12-bit CAN alias (0x001-0xFFF)
    uint8_t is_duplicate : 1; // Set by ISR when another node claims this alias
    uint8_t is_permitted : 1; // Set after successful login (AMD transmitted)
} alias_mapping_t;

19.2 The alias_mapping_info_t Container

All mapping entries are held in a single static container:

typedef struct alias_mapping_info_struct {
    alias_mapping_t list[ALIAS_MAPPING_BUFFER_DEPTH]; // All registered mappings
    bool has_duplicate_alias;                          // Fast-check flag
} alias_mapping_info_t;

The ALIAS_MAPPING_BUFFER_DEPTH macro defaults to USER_DEFINED_NODE_BUFFER_DEPTH, so there is one slot per virtual node. The has_duplicate_alias flag is a fast-check optimization: when set, at least one entry has is_duplicate set, and the main loop should scan the list to find and resolve the conflict.

19.3 API Functions

19.4 Registration and Lookup

The register function enforces one alias per Node ID. If a Node ID is already registered, calling AliasMappings_register() with a new alias silently replaces the old alias. This is the correct behavior during conflict recovery, where a node must adopt a new alias.

// Registration algorithm:
// 1. Validate alias is in range 0x001-0xFFF
// 2. Validate node_id is in range 0x000000000001-0xFFFFFFFFFFFF
// 3. Scan all ALIAS_MAPPING_BUFFER_DEPTH entries
// 4. On first empty slot (alias==0) or matching Node ID: store and return
// 5. If no slot found: return NULL (buffer full)

19.5 Duplicate Alias Detection

Duplicate detection follows a two-phase pattern dictated by the ISR/main-loop architecture:

19.6 Alias Lifecycle

An alias transitions through several states during its lifetime on the CAN bus:

19.7 Thread Safety

The alias mapping table is shared between the CAN RX interrupt (which sets is_duplicate and has_duplicate_alias) and the main loop (which reads and clears these flags, registers and unregisters entries). This makes it one of the critical shared data structures described in Chapter 6.

The lock_shared_resources() / unlock_shared_resources() mechanism must protect accesses from the main loop when the ISR might modify the same data. On bare-metal platforms, this typically means disabling CAN RX interrupts during main-loop table operations.

19.8 Source Files