router.h

/*
 * Copyright (c) 2022-2024 Qualcomm Innovation Center, Inc. All Rights Reserved.
 * Author: GreenSocs 2022
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */
 
#ifndef _GREENSOCS_BASE_COMPONENTS_ROUTER_H
#define _GREENSOCS_BASE_COMPONENTS_ROUTER_H
 
#include <cinttypes>
#include <utility>
#include <vector>
#include <map>
#include <set>           // Required for std::set
#include <limits>        // Required for std::numeric_limits
#include <memory>        // Required for std::shared_ptrs
#include <unordered_map> // Required for std::unordered_map
#include <list>          // Required for std::list
#include <functional>    // Required for std::less
 
/* Theoretically a DMI request can be failed with no ill effects, and to protect against re-entrant code
 * between a DMI invalidate and a DMI request on separate threads, effectively requiring work to be done
 * on the same thread, we make use of this by 'try_lock'ing and failing the DMI. However this has the
 * negative side effect that up-stream models may not get DMI's when they expect them, which at the very
 * least would be a performance hit.
 * Define this as true if you require protection against re-entrant models.
 */
#define THREAD_SAFE_REENTRANT false
#define THREAD_SAFE true
#if defined(THREAD_SAFE) and THREAD_SAFE
#include <mutex>
#include <shared_mutex>
#endif
#include <atomic>
 
#include <cci_configuration>
#include <systemc>
#include <tlm>
#include <scp/report.h>
#include <scp/helpers.h>
#include <cciutils.h>
 
#include <tlm_utils/multi_passthrough_initiator_socket.h>
#include <tlm_utils/multi_passthrough_target_socket.h>
#include <tlm-extensions/pathid_extension.h>
#include <tlm-extensions/underlying-dmi.h>
 
#include <router_if.h>
#include <module_factory_registery.h>
#include <tlm_sockets_buswidth.h>
 
namespace gs {
 
template <typename Key, typename Value>
class AddrMapCacheBase
{
public:
    virtual ~AddrMapCacheBase() = default;
    virtual bool get(const Key& key, Value& value) = 0;
    virtual void put(const Key& key, const Value& value, uint64_t size) = 0;
    virtual void clear() = 0;
 
    // Statistics interface
    virtual uint64_t get_hits() const = 0;
    virtual uint64_t get_misses() const = 0;
    virtual void reset_stats() = 0;
};
 
template <typename Key, typename Value>
class AddrMapNoCache : public AddrMapCacheBase<Key, Value>
{
public:
    bool get(const Key& key, Value& value) override
    {
        (void)key;   // Suppress unused parameter warning
        (void)value; // Suppress unused parameter warning
        return false;
    }
 
    void put(const Key& key, const Value& value, [[maybe_unused]] uint64_t size) override
    {
        (void)key;   // Suppress unused parameter warning
        (void)value; // Suppress unused parameter warning
    }
 
    void clear() override {}
 
    // Statistics interface implementation
    uint64_t get_hits() const override { return 0; }
    uint64_t get_misses() const override { return 0; }
    void reset_stats() override {}
};
 
template <unsigned int BUSWIDTH = DEFAULT_TLM_BUSWIDTH, template <typename, typename> class CacheType = AddrMapNoCache>
class router : public sc_core::sc_module, public gs::router_if<BUSWIDTH>
{
    using TargetSocket = tlm::tlm_base_target_socket_b<BUSWIDTH, tlm::tlm_fw_transport_if<>,
                                                       tlm::tlm_bw_transport_if<>>;
    using InitiatorSocket = tlm::tlm_base_initiator_socket_b<BUSWIDTH, tlm::tlm_fw_transport_if<>,
                                                             tlm::tlm_bw_transport_if<>>;
    using typename gs::router_if<BUSWIDTH>::target_info;
    using initiator_socket_type = typename gs::router<
        BUSWIDTH, CacheType>::template multi_passthrough_initiator_socket_spying<router<BUSWIDTH, CacheType>>;
    using gs::router_if<BUSWIDTH>::bound_targets;
 
    using CacheImpl = CacheType<uint64_t, std::shared_ptr<target_info>>;
    template <typename TargetInfoType>
    class addressMap
    {
    private:
        struct Region {
            uint64_t start;                         
            uint64_t end;                           
            std::shared_ptr<TargetInfoType> target; 
 
            Region(uint64_t s, uint64_t e, std::shared_ptr<TargetInfoType> t): start(s), end(e), target(t) {}
        };
 
        std::map<uint64_t, Region> m_regions;
 
        CacheImpl m_cache;
 
        void split_and_resolve(uint64_t new_start, uint64_t new_end, std::shared_ptr<TargetInfoType> new_target)
        {
            // Step 1: Collect all existing regions that overlap with the new region
            std::vector<Region> overlapping_regions;
            std::vector<uint64_t> keys_to_remove;
 
            // Find overlapping regions using interval overlap test: (a.start < b.end && a.end > b.start)
            for (const auto& [start_addr, region] : m_regions) {
                if (region.start < new_end && region.end > new_start) {
                    overlapping_regions.push_back(region);
                    keys_to_remove.push_back(start_addr);
                }
            }
 
            // Step 2: Remove overlapping regions from the map (they'll be re-added after splitting)
            for (uint64_t key : keys_to_remove) {
                m_regions.erase(key);
            }
 
            // Step 3: Create intervals for all regions that need to be resolved
            struct Interval {
                uint64_t start, end;
                std::shared_ptr<TargetInfoType> target;
                uint32_t priority;
 
                Interval(uint64_t s, uint64_t e, std::shared_ptr<TargetInfoType> t)
                    : start(s), end(e), target(t), priority(t->priority)
                {
                }
            };
 
            std::vector<Interval> intervals;
            intervals.reserve(overlapping_regions.size() + 1); // Optimize allocation
 
            // Add the new region
            intervals.emplace_back(new_start, new_end, new_target);
 
            // Add all overlapping existing regions
            for (const Region& region : overlapping_regions) {
                intervals.emplace_back(region.start, region.end, region.target);
            }
 
            // Step 4: Create sorted list of all boundary points for segmentation
            std::set<uint64_t> boundaries;
            for (const Interval& interval : intervals) {
                boundaries.insert(interval.start);
                boundaries.insert(interval.end);
            }
 
            // Step 5: Process each segment between boundaries and resolve conflicts
            auto boundary_it = boundaries.begin();
            while (boundary_it != boundaries.end()) {
                uint64_t seg_start = *boundary_it;
                ++boundary_it;
                if (boundary_it == boundaries.end()) break;
                uint64_t seg_end = *boundary_it;
 
                // Find the highest priority target for this segment
                std::shared_ptr<TargetInfoType> best_target = nullptr;
                uint32_t best_priority = UINT32_MAX;
 
                for (const Interval& interval : intervals) {
                    // Check if this interval covers the current segment
                    if (interval.start <= seg_start && interval.end >= seg_end) {
                        if (interval.priority < best_priority) {
                            best_priority = interval.priority;
                            best_target = interval.target;
                        }
                    }
                }
 
                // Add the resolved segment to the final map
                if (best_target) {
                    m_regions.emplace(seg_start, Region(seg_start, seg_end, best_target));
                }
            }
 
            // Step 6: Check for completely shadowed regions and issue warnings
            for (const Interval& interval : intervals) {
                // Skip the newly added region (it can't be shadowed by itself)
                if (interval.start == new_start && interval.end == new_end && interval.target == new_target) {
                    continue;
                }
 
                // Check if this interval is completely covered by higher priority regions
                // We do this by checking if any part of this interval "wins" in the final mapping
                bool completely_shadowed = true;
 
                // Look through the final resolved regions to see if any belong to this interval's target
                for (const auto& [seg_start, region] : m_regions) {
                    // Check if this final region overlaps with our interval and belongs to our target
                    if (region.target == interval.target && region.start < interval.end &&
                        region.end > interval.start) {
                        // This interval has at least some part that's not shadowed
                        completely_shadowed = false;
                        break;
                    }
                }
 
                if (completely_shadowed) {
                    std::stringstream ss;
                    ss << "Region '" << interval.target->name << "' (0x" << std::hex << interval.start << "-0x"
                       << (interval.end - 1) << ", priority " << std::dec << interval.priority
                       << ") is completely shadowed by higher priority regions and will never be accessed";
                    SC_REPORT_WARNING("addressMap", ss.str().c_str());
                }
            }
        }
 
    public:
        addressMap() = default;
 
        void add(std::shared_ptr<TargetInfoType> t_info)
        {
            uint64_t start = t_info->address;
            uint64_t end = t_info->address + t_info->size;
 
            split_and_resolve(start, end, t_info);
 
            // Clear cache after map modification to ensure consistency
            m_cache.clear();
        }
 
        std::shared_ptr<TargetInfoType> find(uint64_t address, uint64_t size)
        {
            // Fast path: check LRU cache first
            std::shared_ptr<TargetInfoType> cached_result;
            if (m_cache.get(address, cached_result)) {
                return cached_result;
            }
 
            // Slow path: search the map using upper_bound for O(log n) lookup
            // upper_bound finds the first region with start > address
            auto it = m_regions.upper_bound(address);
            if (it != m_regions.begin()) {
                --it; // Move to the region that might contain our address
 
                // Check if address falls within this region [start, end)
                if (address >= it->second.start && address < it->second.end) {
                    // Cache the result for future lookups
                    m_cache.put(address, it->second.target, size);
                    return it->second.target;
                }
            }
 
            // Address not found - cache the negative result to avoid repeated lookups
            m_cache.put(address, nullptr, size);
            return nullptr;
        }
 
        std::shared_ptr<TargetInfoType> find_region(uint64_t addr, tlm::tlm_dmi& dmi)
        {
            // First try to find a mapped region using the same logic as find()
            auto it = m_regions.upper_bound(addr);
            if (it != m_regions.begin()) {
                --it;
                if (addr >= it->second.start && addr < it->second.end) {
                    // Return the segment boundaries. After split_and_resolve, adjacent
                    // same-target segments are merged, so this segment represents the
                    // full contiguous range owned by this target. We must not use the
                    // original target range as it may span across higher-priority targets.
                    std::shared_ptr<TargetInfoType> target = it->second.target;
                    dmi.set_start_address(it->second.start);
                    dmi.set_end_address(it->second.end - 1); // inclusive end (Region.end is exclusive)
                    return target;
                }
            }
 
            // Address is in a hole - calculate hole boundaries for DMI invalidation
            uint64_t hole_start = 0;
            uint64_t hole_end = std::numeric_limits<uint64_t>::max();
 
            // Find the region immediately before this address
            it = m_regions.upper_bound(addr);
            if (it != m_regions.begin()) {
                --it;
                if (it->second.end <= addr) {
                    hole_start = it->second.end;
                }
            }
 
            // Find the region immediately after this address
            it = m_regions.upper_bound(addr);
            if (it != m_regions.end()) {
                hole_end = it->second.start;
            }
 
            // Set DMI boundaries for the hole
            dmi.set_start_address(hole_start);
            dmi.set_end_address(hole_end == 0 ? 0 : hole_end - 1); // Handle edge case
            return nullptr;
        }
 
        void get_cache_stats(uint64_t& hits, uint64_t& misses) const
        {
            hits = m_cache.get_hits();
            misses = m_cache.get_misses();
        }
 
        void reset_cache_stats() { m_cache.reset_stats(); }
    };
 
    SCP_LOGGER_VECTOR(D);
    SCP_LOGGER(());
    SCP_LOGGER((DMI), "dmi");
 
private:
#if defined(THREAD_SAFE) and THREAD_SAFE
    std::mutex m_dmi_mutex;
#endif
    struct dmi_info {
        std::set<int> initiators; 
        tlm::tlm_dmi dmi;         
        dmi_info(tlm::tlm_dmi& _dmi) { dmi = _dmi; }
    };
    std::map<uint64_t, dmi_info> m_dmi_info_map;
 
    dmi_info* in_dmi_cache(tlm::tlm_dmi& dmi)
    {
        auto it = m_dmi_info_map.find(dmi.get_start_address());
        if (it != m_dmi_info_map.end()) {
            if (it->second.dmi.get_end_address() != dmi.get_end_address()) {
                // Defensive guard: unreachable in normal operation. The only caller
                // (record_dmi) detects differing end addresses and calls
                // invalidate_direct_mem_ptr_ts to erase the old entry before reaching here.
                std::stringstream ss;
                ss << "Can't handle that: DMI overlap with differing end address (0x" << std::hex
                   << it->second.dmi.get_end_address() << " vs 0x" << dmi.get_end_address() << ")";
                SC_REPORT_ERROR("DMI", ss.str().c_str());
            }
            return &(it->second);
        }
        auto insit = m_dmi_info_map.emplace(dmi.get_start_address(), dmi_info(dmi));
        return &(insit.first->second);
    }
 
    void record_dmi(int id, tlm::tlm_dmi& dmi)
    {
        auto it = m_dmi_info_map.find(dmi.get_start_address());
        if (it != m_dmi_info_map.end()) {
            if (it->second.dmi.get_end_address() != dmi.get_end_address()) {
                SCP_WARN((DMI)) << "A new DMI overlaps with an old one, invalidating the old one";
                invalidate_direct_mem_ptr_ts(0, dmi.get_start_address(),
                                             dmi.get_end_address()); // id will be ignored
            }
        }
 
        dmi_info* dinfo = in_dmi_cache(dmi);
        dinfo->initiators.insert(id);
    }
 
    void register_boundto(std::string s) override
    {
        s = gs::router_if<BUSWIDTH>::nameFromSocket(s);
        // Create a shared_ptr for the new target_info
        std::shared_ptr<target_info> ti_ptr = std::make_shared<target_info>();
        ti_ptr->name = s;
        ti_ptr->index = bound_targets.size(); // Current size will be its index
        SCP_LOGGER_VECTOR_PUSH_BACK(D, ti_ptr->name);
        SCP_DEBUG((D[ti_ptr->index])) << "Connecting : " << ti_ptr->name;
        ti_ptr->chained = false;
        std::string tmp = name();
        int i;
        for (i = 0; i < tmp.length(); i++)
            if (s[i] != tmp[i]) break;
        ti_ptr->shortname = s.substr(i);
        bound_targets.push_back(ti_ptr); // Add shared_ptr to bound_targets
    }
 
    std::string txn_tostring(const target_info* ti, tlm::tlm_generic_payload& trans)
    {
        std::stringstream info;
        const char* cmd = "UNKOWN";
        switch (trans.get_command()) {
        case tlm::TLM_IGNORE_COMMAND:
            info << "IGNORE ";
            break;
        case tlm::TLM_WRITE_COMMAND:
            info << "WRITE ";
            break;
        case tlm::TLM_READ_COMMAND:
            info << "READ ";
            break;
        }
 
        info << " address:"
             << "0x" << std::hex << trans.get_address();
        info << " len:" << trans.get_data_length();
        unsigned char* ptr = trans.get_data_ptr();
        if ((trans.get_command() == tlm::TLM_READ_COMMAND && trans.get_response_status() == tlm::TLM_OK_RESPONSE) ||
            (trans.get_command() == tlm::TLM_WRITE_COMMAND &&
             trans.get_response_status() == tlm::TLM_INCOMPLETE_RESPONSE)) {
            info << " data:0x";
            for (int i = trans.get_data_length(); i; i--) {
                info << std::setw(2) << std::setfill('0') << std::hex << (unsigned int)(ptr[i - 1]);
            }
        }
        info << " " << trans.get_response_string() << " ";
        for (int i = 0; i < tlm::max_num_extensions(); i++) {
            if (trans.get_extension(i)) {
                info << " extn:" << i;
            }
        }
        return info.str();
    }
 
public:
    initiator_socket_type initiator_socket;
    tlm_utils::multi_passthrough_target_socket<router<BUSWIDTH, CacheType>, BUSWIDTH> target_socket;
    cci::cci_broker_handle m_broker;
 
private:
    std::vector<std::shared_ptr<target_info>> alias_targets;
    addressMap<target_info> m_address_map;
    std::vector<std::shared_ptr<target_info>> id_targets;
 
    std::vector<PathIDExtension*> m_pathIDPool;
#if defined(THREAD_SAFE) and THREAD_SAFE
    std::mutex m_pool_mutex;
#endif
 
    void stamp_txn(int id, tlm::tlm_generic_payload& txn)
    {
        PathIDExtension* ext = nullptr;
        txn.get_extension(ext);
        if (ext == nullptr) {
#if defined(THREAD_SAFE) and THREAD_SAFE
            std::lock_guard<std::mutex> l(m_pool_mutex);
#endif
            if (m_pathIDPool.size() == 0) {
                ext = new PathIDExtension();
            } else {
                ext = m_pathIDPool.back();
                m_pathIDPool.pop_back();
            }
            txn.set_extension(ext);
        }
        ext->push_back(id);
    }
 
    void unstamp_txn(int id, tlm::tlm_generic_payload& txn)
    {
        PathIDExtension* ext;
        txn.get_extension(ext);
        assert(ext);
        assert(ext->back() == id);
        ext->pop_back();
        if (ext->size() == 0) {
#if defined(THREAD_SAFE) and THREAD_SAFE
            std::lock_guard<std::mutex> l(m_pool_mutex);
#endif
            txn.clear_extension(ext);
            m_pathIDPool.push_back(ext);
        }
    }
 
    void b_transport(int id, tlm::tlm_generic_payload& trans, sc_core::sc_time& delay)
    {
        sc_dt::uint64 addr = trans.get_address();
        auto ti = decode_address(trans);
        if (!ti) {
            SCP_WARN(())("Attempt to access unknown register at offset 0x{:x}", addr);
            trans.set_response_status(tlm::TLM_ADDRESS_ERROR_RESPONSE);
            return;
        }
 
        stamp_txn(id, trans);
        if (!ti->chained) {
            SCP_TRACE((D[ti->index]), ti->name) << "Start b_transport :" << txn_tostring(ti.get(), trans);
        }
        if (trans.get_response_status() >= tlm::TLM_INCOMPLETE_RESPONSE) {
            if (ti->use_offset) trans.set_address(addr - ti->address);
 
            initiator_socket[ti->index]->b_transport(trans, delay);
 
            if (ti->use_offset) trans.set_address(addr);
        }
        if (!ti->chained) {
            SCP_TRACE((D[ti->index]), ti->name) << "Completed b_transport :" << txn_tostring(ti.get(), trans);
        }
        unstamp_txn(id, trans);
    }
 
    unsigned int transport_dbg(int id, tlm::tlm_generic_payload& trans)
    {
        // Ensure router is initialized (thread-safe)
        lazy_initialize();
 
        sc_dt::uint64 addr = trans.get_address();
        auto ti = decode_address(trans);
        if (!ti) {
            trans.set_response_status(tlm::TLM_ADDRESS_ERROR_RESPONSE);
            return 0;
        }
 
        if (ti->use_offset) trans.set_address(addr - ti->address);
        SCP_TRACE((D[ti->index]), ti->name) << "calling dbg_transport : " << scp::scp_txn_tostring(trans);
        unsigned int ret = initiator_socket[ti->index]->transport_dbg(trans);
        if (ti->use_offset) trans.set_address(addr);
        return ret;
    }
 
    bool get_direct_mem_ptr(int id, tlm::tlm_generic_payload& trans, tlm::tlm_dmi& dmi_data)
    {
        // Ensure router is initialized (thread-safe)
        lazy_initialize();
 
        sc_dt::uint64 addr = trans.get_address();
 
        tlm::tlm_dmi dmi_data_hole;
        auto ti = m_address_map.find_region(addr, dmi_data_hole);
 
        UnderlyingDMITlmExtension* u_dmi;
        trans.get_extension(u_dmi);
        if (u_dmi) {
            SCP_DEBUG(())
            ("DMI info 0x{:x} 0x{:x} {}", dmi_data_hole.get_start_address(), dmi_data_hole.get_end_address(),
             (ti ? "mapped" : "nomap"));
            u_dmi->add_dmi(this, dmi_data_hole, (ti ? gs::tlm_dmi_ex::dmi_mapped : gs::tlm_dmi_ex::dmi_nomap));
        }
 
        if (!ti) {
            return false;
        }
#if defined(THREAD_SAFE_REENTRANT) and THREAD_SAFE_REENTRANT
        if (!m_dmi_mutex.try_lock()) { // if we're busy invalidating, dont grant DMI's
            return false;
        }
#else
        m_dmi_mutex.lock();
#endif
 
        if (ti->use_offset) trans.set_address(addr - ti->address);
        SCP_TRACE((D[ti->index]), ti->name) << "calling get_direct_mem_ptr : " << scp::scp_txn_tostring(trans);
        bool status = initiator_socket[ti->index]->get_direct_mem_ptr(trans, dmi_data);
        if (ti->use_offset) trans.set_address(addr);
        if (status) {
            if (ti->use_offset) {
                assert(dmi_data.get_start_address() < ti->size);
                dmi_data.set_start_address(ti->address + dmi_data.get_start_address());
                dmi_data.set_end_address(ti->address + dmi_data.get_end_address());
            }
            /* ensure we dont overspill the 'hole' we have in the address map */
            if (dmi_data.get_start_address() < dmi_data_hole.get_start_address()) {
                dmi_data.set_dmi_ptr(dmi_data.get_dmi_ptr() +
                                     (dmi_data_hole.get_start_address() - dmi_data.get_start_address()));
                dmi_data.set_start_address(dmi_data_hole.get_start_address());
            }
            if (dmi_data.get_end_address() > dmi_data_hole.get_end_address()) {
                dmi_data.set_end_address(dmi_data_hole.get_end_address());
            }
            record_dmi(id, dmi_data);
        }
        SCP_DEBUG(())
        ("Providing DMI (status {:x}) {:x} - {:x}", status, dmi_data.get_start_address(), dmi_data.get_end_address());
#if defined(THREAD_SAFE) and THREAD_SAFE
        m_dmi_mutex.unlock();
#endif
        return status;
    }
 
    void invalidate_direct_mem_ptr(int id, sc_dt::uint64 start, sc_dt::uint64 end)
    {
        if (id_targets[id]->use_offset) {
            start = id_targets[id]->address + start;
            end = id_targets[id]->address + end;
        }
#if defined(THREAD_SAFE) and THREAD_SAFE
        std::lock_guard<std::mutex> lock(m_dmi_mutex);
#endif
        invalidate_direct_mem_ptr_ts(id, start, end);
    }
 
    void invalidate_direct_mem_ptr_ts(int id, sc_dt::uint64 start, sc_dt::uint64 end)
    {
        auto it = m_dmi_info_map.upper_bound(start);
 
        if (it != m_dmi_info_map.begin()) {
            /*
             * Start with the preceding region, as it may already cross the
             * range we must invalidate.
             */
            it--;
        }
        std::set<int> initiators;
 
        while (it != m_dmi_info_map.end()) {
            tlm::tlm_dmi& r = it->second.dmi;
 
            if (r.get_start_address() > end) {
                /* We've got out of the invalidation range */
                break;
            }
 
            if (r.get_end_address() < start) {
                /* We are not in yet */
                it++;
                continue;
            }
            for (auto t : it->second.initiators) {
                SCP_TRACE((DMI)) << "Queueing initiator " << t << " for invalidation, its bounds are [0x" << std::hex
                                 << it->second.dmi.get_start_address() << " - 0x" << it->second.dmi.get_end_address()
                                 << "]";
                initiators.insert(t);
            }
            it = m_dmi_info_map.erase(it);
        }
        for (auto t : initiators) {
            SCP_INFO((DMI)) << "Invalidating initiator " << t << " [0x" << std::hex << start << " - 0x" << end << "]";
            target_socket[t]->invalidate_direct_mem_ptr(start, end);
        }
    }
 
protected:
    std::shared_ptr<target_info> decode_address(tlm::tlm_generic_payload& trans) override
    {
        lazy_initialize();
 
        sc_dt::uint64 addr = trans.get_address();
        return m_address_map.find(addr, trans.get_data_length());
    }
 
    virtual void before_end_of_elaboration() override
    {
        if (!lazy_init) lazy_initialize();
    }
 
private:
    std::atomic<bool> m_initialized{ false };
#if defined(THREAD_SAFE) and THREAD_SAFE
    std::mutex m_init_mutex;
#endif
    std::list<std::string> get_matching_children(cci::cci_broker_handle broker, const std::string& prefix,
                                                 const std::vector<cci_name_value_pair>& list)
    {
        size_t prefix_len = prefix.length() + 1; // +1 for the dot separator
        std::list<std::string> children;
        for (const auto& p : list) {
            if (p.first.find(prefix) == 0) {
                // Extract the child name after the prefix
                std::string child = p.first.substr(prefix_len, p.first.find(".", prefix_len) - prefix_len);
                children.push_back(child);
            }
        }
        children.sort();
        children.unique();
        return children;
    }
 
    void lazy_initialize() override
    {
        // Fast path: check if already initialized (lock-free)
        if (m_initialized.load(std::memory_order_acquire)) {
            return;
        }
 
#if defined(THREAD_SAFE) and THREAD_SAFE
        // Slow path: acquire lock and initialize
        std::lock_guard<std::mutex> lock(m_init_mutex);
#endif
 
        // Double-check: another thread may have initialized while we waited
        if (m_initialized.load(std::memory_order_relaxed)) {
            return;
        }
 
        // Perform initialization
        // Get filtered range and convert to vector to materialize the results
        auto all_alias_range = m_broker.get_unconsumed_preset_values([](const std::pair<std::string, cci_value>& iv) {
            return iv.first.find(".aliases.") != std::string::npos;
        });
        std::vector<cci_name_value_pair> all_alias(all_alias_range.begin(), all_alias_range.end());
 
        for (auto& ti_ptr : bound_targets) {
            std::string name = ti_ptr->name;
            std::string src;
            if (gs::cci_get<std::string>(m_broker, ti_ptr->name + ".0", src)) {
                // deal with an alias
                if (m_broker.has_preset_value(ti_ptr->name + ".address") &&
                    m_broker.get_preset_cci_value(ti_ptr->name + ".address").is_number()) {
                    SCP_WARN((D[ti_ptr->index]), ti_ptr->name)
                    ("The configuration alias provided ({}) will be ignored as a valid address is also provided.", src);
                } else {
                    if (src[0] == '&') src = (src.erase(0, 1)) + ".target_socket";
                    if (!m_broker.has_preset_value(src + ".address")) {
                        std::stringstream ss;
                        ss << "The configuration alias provided (" << src << ") can not be found.";
                        SC_REPORT_ERROR("router", ss.str().c_str());
                    }
                    name = src;
                }
            }
 
            // Update the target_info object pointed to by ti_ptr
            ti_ptr->address = gs::cci_get<uint64_t>(m_broker, name + ".address");
            ti_ptr->size = gs::cci_get<uint64_t>(m_broker, name + ".size");
            ti_ptr->use_offset = gs::cci_get_d<bool>(m_broker, name + ".relative_addresses", true);
            ti_ptr->chained = gs::cci_get_d<bool>(m_broker, name + ".chained", false);
            ti_ptr->priority = gs::cci_get_d<uint32_t>(m_broker, name + ".priority", 0);
 
            SCP_INFO((D[ti_ptr->index]), ti_ptr->name)
                << "Address map " << ti_ptr->name << " at address "
                << "0x" << std::hex << ti_ptr->address << " size "
                << "0x" << std::hex << ti_ptr->size << (ti_ptr->use_offset ? " (with relative address) " : " ")
                << "priority : " << ti_ptr->priority;
            if (ti_ptr->chained) SCP_DEBUG(())("{} is chained so debug will be suppressed", ti_ptr->name);
 
            // Add the shared_ptr to the address map
            m_address_map.add(ti_ptr);
            for (std::string n : get_matching_children(m_broker, (ti_ptr->name + ".aliases"), all_alias)) {
                std::string alias_name = ti_ptr->name + ".aliases." + n;
                uint64_t address = gs::cci_get<uint64_t>(m_broker, alias_name + ".address");
                uint64_t size = gs::cci_get<uint64_t>(m_broker, alias_name + ".size");
                SCP_INFO((D[ti_ptr->index]), ti_ptr->name)("Adding alias {} {:#x} (size: {})", alias_name, address,
                                                           size);
 
                // Create a new shared_ptr for the alias, copying from the current ti_ptr state
                std::shared_ptr<target_info> alias_ti_ptr = std::make_shared<target_info>(*ti_ptr);
                alias_ti_ptr->address = address;
                alias_ti_ptr->size = size;
                alias_ti_ptr->name = alias_name;
                alias_targets.push_back(alias_ti_ptr); // Store shared_ptr in alias_targets
 
                // Add aliases to the address map
                m_address_map.add(alias_ti_ptr);
            }
            id_targets.push_back(ti_ptr); // Store shared_ptr in id_targets
        }
 
        // Mark as initialized (release semantics ensures all writes are visible)
        m_initialized.store(true, std::memory_order_release);
    }
 
    cci::cci_param<bool> lazy_init;
 
public:
    explicit router(const sc_core::sc_module_name& nm, cci::cci_broker_handle broker = cci::cci_get_broker())
        : sc_core::sc_module(nm)
        , initiator_socket("initiator_socket", [&](std::string s) -> void { register_boundto(s); })
        , target_socket("target_socket")
        , m_address_map()
        , m_broker(broker)
        , lazy_init("lazy_init", false, "Initialize the router lazily (eg. during simulation rather than BEOL)")
    {
        SCP_DEBUG(()) << "router constructed";
 
        target_socket.register_b_transport(this, &router<BUSWIDTH, CacheType>::b_transport);
        target_socket.register_transport_dbg(this, &router<BUSWIDTH, CacheType>::transport_dbg);
        target_socket.register_get_direct_mem_ptr(this, &router<BUSWIDTH, CacheType>::get_direct_mem_ptr);
        initiator_socket.register_invalidate_direct_mem_ptr(this,
                                                            &router<BUSWIDTH, CacheType>::invalidate_direct_mem_ptr);
        SCP_DEBUG((DMI)) << "router Initializing DMI SCP reporting";
    }
 
    router() = delete;
 
    router(const router&) = delete;
 
public:
    ~router() { m_pathIDPool.clear(); }
 
    void add_target(TargetSocket& t, const uint64_t address, uint64_t size, bool masked = true,
                    unsigned int priority = 0)
    {
        std::string s = gs::router_if<BUSWIDTH>::nameFromSocket(t.get_base_export().name());
        if (!m_broker.has_preset_value(s + ".address")) {
            m_broker.set_preset_cci_value(s + ".address", cci::cci_value(address));
        }
        if (!m_broker.has_preset_value(s + ".size")) {
            m_broker.set_preset_cci_value(s + ".size", cci::cci_value(size));
        }
        if (!m_broker.has_preset_value(s + ".relative_addresses")) {
            m_broker.set_preset_cci_value(s + ".relative_addresses", cci::cci_value(masked));
        }
        if (!m_broker.has_preset_value(s + ".priority")) {
            SCP_DEBUG(())("Setting prio to {}", priority);
            m_broker.set_preset_cci_value(s + ".priority", cci::cci_value(priority));
        }
        initiator_socket.bind(t);
    }
 
    virtual void add_initiator(InitiatorSocket& i)
    {
        // hand bind the port/exports as we are using base classes
        (i.get_base_port())(target_socket.get_base_interface());
        (target_socket.get_base_port())(i.get_base_interface());
    }
 
    void get_cache_stats(uint64_t& hits, uint64_t& misses) const { m_address_map.get_cache_stats(hits, misses); }
 
    void reset_cache_stats() { m_address_map.reset_cache_stats(); }
};
} // namespace gs
 
extern "C" void module_register();
#endif