mappable-conf-object.h

Go to the documentation of this file.

// -*- mode: C++; c-file-style: "virtutech-c++" -*-
 
/*
  © 2022 Intel Corporation
 
  This software and the related documents are Intel copyrighted materials, and
  your use of them is governed by the express license under which they were
  provided to you ("License"). Unless the License provides otherwise, you may
  not use, modify, copy, publish, distribute, disclose or transmit this software
  or the related documents without Intel's prior written permission.
 
  This software and the related documents are provided as is, with no express or
  implied warranties, other than those that are expressly stated in the License.
*/
 
#ifndef SIMICS_MAPPABLE_CONF_OBJECT_H
#define SIMICS_MAPPABLE_CONF_OBJECT_H
 
#include <simics/base/log.h>  // SIM_LOG_ERROR
#include <string_view>
#include <string>
#include <stdexcept>
#include <unordered_map>
#include <unordered_set>
#include <set>
#include <tuple>
#include <vector>
#include <functional>  // hash
 
#include "conf-object.h"
#include "iface/map-name-to-interface.h"
#include "iface/register-interface.h"
#include "type/bank-type.h"
 
namespace simics {
 
// Class supports get/set a pointer to IFACE with a string name
template <typename IFACE>
class MapNameToInterfaceObject : public MapNameToInterface<IFACE> {
  public:
    static size_t hash_str(const std::string &name) {
        return std::hash<std::string>{}(name);
    }
 
    // MapNameToInterface<IFACE>
    void set_iface(const std::string &name, IFACE *iface) override {
        if (!iface) {
            throw std::invalid_argument {
                "Cannot set with NULL interface"
            };
        } else if (name.empty()) {
            throw std::invalid_argument {
                "Cannot set with empty name string"
            };
        } else {
            name_to_iface_[hash_str(name)] = iface;
        }
    }
    IFACE *get_iface(const std::string &name) const override {
        auto hashed = hash_str(name);
        if (name_to_iface_.find(hashed) == name_to_iface_.end()) {
            return nullptr;
        }
        return name_to_iface_.at(hashed);
    }
    void erase_iface(const std::string &name) override {
        name_to_iface_.erase(hash_str(name));
    }
 
  private:
    std::unordered_map<size_t, IFACE *> name_to_iface_;
};
 
class BankInterface;
class FieldInterface;
 
// Specialization of template Class MapNameToInterfaceObject
// it supports get/set a pointer to RegisterInterface with a string name
// and tracks all the names currently in use.
template <>
class MapNameToInterfaceObject<RegisterInterface>
    : public MapNameToInterface<RegisterInterface> {
  public:
    static size_t hash_str(const std::string &name) {
        return std::hash<std::string>{}(name);
    }
 
    // MapNameToInterface<RegisterInterface>
    void set_iface(const std::string &name, RegisterInterface *iface) override {
        if (!iface) {
            throw std::invalid_argument {
                "Cannot set with NULL interface"
            };
        } else if (name.empty()) {
            throw std::invalid_argument {
                "Cannot set with empty name string"
            };
        } else {
            name_to_iface_[hash_str(name)] = iface;
            all_registers_.insert(name);
        }
    }
    RegisterInterface *get_iface(const std::string &name) const override {
        return get_iface(hash_str(name));
    }
    void erase_iface(const std::string &name) override {
        name_to_iface_.erase(hash_str(name));
        all_registers_.erase(name);
    }
 
    RegisterInterface *get_iface(size_t name_hash) const {
        if (name_to_iface_.find(name_hash) == name_to_iface_.end()) {
            return nullptr;
        }
        return name_to_iface_.at(name_hash);
    }
 
    std::unordered_set<std::string> all_registers_;
 
  private:
    std::unordered_map<size_t, RegisterInterface *> name_to_iface_;
};
 
/*
 * A class inherited by a model class to support memory mapped I/O
 *
 * It manages a container which associates a unique name to its corresponding
 * operational interface. These 3 object types are supported: bank, register
 * and field.
 */
class MappableConfObject : public ConfObject {
  public:
    explicit MappableConfObject(ConfObjectRef obj) : ConfObject(obj) {}
    virtual ~MappableConfObject() {}
 
    // Set the object interface by a name.
    template <typename IFACE>
    void set_iface(const std::string &name, IFACE *iface) {
        if (finalized()) {
            SIM_LOG_ERROR(obj(), 0,
                          "Cannot set interface for %s when ConfObject"
                          " has been finalized", name.c_str());
            return;
        }
 
        auto current_iface = get_iface<IFACE>(name);
        if (current_iface && current_iface != iface) {
            if (is_bank_initialized(name)) {
                SIM_LOG_INFO(4, obj(), 0,
                             "Interface for %s ignored since bank"
                             " has been initialized", name.c_str());
                return;
            }
            // TODO(xiuliang): Logs when interface is overridden
        }
 
        try {
            std::get<MapNameToInterfaceObject<IFACE>>(
                    objects_).set_iface(name, iface);
        } catch (std::exception &e) {
            SIM_LOG_ERROR(obj(), 0, "%s", e.what());
        }
    }
 
    /* Get the object interface by a name.
     *
     * User should check if the return pointer is nullptr before use.
     */
    template <typename IFACE>
    IFACE *get_iface(const std::string &name) const {
        return std::get<MapNameToInterfaceObject<IFACE>>(
                objects_).get_iface(name);
    }
 
    RegisterInterface *get_iface(size_t name_hash) const {
        return std::get<MapNameToInterfaceObject<RegisterInterface>>(
                objects_).get_iface(name_hash);
    }
 
    // Erase the object interface by name.
    template <typename IFACE>
    void erase_iface(const std::string &name) {
        std::get<MapNameToInterfaceObject<IFACE>>(objects_).erase_iface(name);
    }
 
    // Whether to represent the bits in big endian, i.e, whether the bit
    // number 0 refers to the most significant bit.
    virtual bool big_endian_bitorder() {
        return false;
    }
 
    // @return all registers' names currently in use
    const std::unordered_set<std::string> &all_registers() const {
        return std::get<MapNameToInterfaceObject<
                            RegisterInterface>>(objects_).all_registers_;
    }
 
    std::vector<size_t> register_dimensions(const std::string &name) {
        auto reg_name = name.substr(name.rfind('.') + 1);
        auto num_dims = std::count(reg_name.cbegin(), reg_name.cend(), '[');
        if (num_dims == 0) {
            return {};
        }
        std::vector<size_t> dims(num_dims);
 
        auto all_regs = all_registers();
        auto base_name = name.substr(0, name.rfind('.') + 1) + \
            reg_name.substr(0, reg_name.find('['));
        for (int dim_index = 0; dim_index < num_dims; ++dim_index) {
            auto prefix = base_name;
            for (int prefix_index = 0; prefix_index < dim_index;
                 ++prefix_index) {
                prefix.append("[0]");
            }
            std::string postfix;
            for (int postfix_index = dim_index + 1; postfix_index < num_dims;
                 ++postfix_index) {
                postfix.append("[0]");
            }
            size_t s = 0;
 
            while (true) {
                std::string check_name = prefix + '[' + std::to_string(s) + \
                    ']' + postfix;
                if (all_regs.find(check_name) != all_regs.end()) {
                    ++s;
                } else {
                    break;
                }
            }
            dims[dim_index] = s;
        }
        return dims;
    }
 
    void set_bank_as_initialized(const std::string &name) {
        initialized_banks_.insert(name);
    }
 
    // Return the pointer to bank memory by a name
    bank_memory_t *get_bank_memory(std::string_view name_of_memory) {
        return &allocated_bank_memories_[name_of_memory.data()];
    }
 
  private:
    bool is_bank_initialized(const std::string &name) {
        const auto &bank_name = name.substr(0, name.find('.'));
        return initialized_banks_.find(bank_name) != initialized_banks_.end();
    }
 
    // @internal tracks the name to interface associations
    std::tuple<MapNameToInterfaceObject<BankInterface>,
               MapNameToInterfaceObject<RegisterInterface>,
               MapNameToInterfaceObject<FieldInterface>> objects_;
 
    // The name of initialized banks
    std::unordered_set<std::string> initialized_banks_;
 
    /*
     * The allocated_bank_memories_ maps a string key to a
     * value of type bank_memory_t.
     *
     * This structure groups bytes memory for all banks, can be used
     * to efficiently store and access byte-level data using the name
     * and byte offset as keys.
     *
     * By default, each bank uses its bank name as the key to get the
     * bank memory. For SharedMemoryBank, multiple banks can share the
     * same bank memory by using the same key. The key can be any unique
     * string.
     */
    std::unordered_map<std::string,
                       bank_memory_t> allocated_bank_memories_;
};
 
}  // namespace simics
 
#endif