hierarchical-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_HIERARCHICAL_OBJECT_H
#define SIMICS_HIERARCHICAL_OBJECT_H
 
#include <simics/base/log.h>  // SIM_LOG_XXX
#include <fmt/fmt/format.h>
#include <string_view>
#include <string>
#include <stdexcept>
#include <algorithm>  // count
#include <utility>  // swap
 
#include "conf-object.h"  // ConfObjectRef
#include "mappable-conf-object.h"
#include "log.h"
#include "iface/hierarchical-object-interface.h"
 
namespace simics {
 
// TODO(xiuliang): Where to find the register name at compile time?
// #define SIMICS_REGISTER(R)
//     RegisterInterface* get##R##() { return lookup_register(#R); }
 
// The hierarchy separator between bank, register and field names
constexpr static const char &SEPARATOR = '.';
 
// Base class for Bank/Register/Field class
// coverity[rule_of_five_violation:FALSE]
class HierarchicalObject : public HierarchicalObjectInterface {
  public:
    // @param name unique hierarchical name of a bank/register/field
    HierarchicalObject(MappableConfObject *dev_obj,
                       const std::string &name)
        : dev_obj_(dev_obj),
          hierarchical_name_(name) {
        if (dev_obj == nullptr) {
            throw std::invalid_argument {
                "HierarchicalObject cannot be constructed from a NULL dev_obj"
            };
        }
        init();
    }
    HierarchicalObject(MappableConfObject *dev_obj,
                       const std::string &name,
                       FieldInterface *iface)
        : HierarchicalObject(dev_obj, name) {
        init_iface(iface);
    }
    HierarchicalObject(MappableConfObject *dev_obj,
                       const std::string &name,
                       RegisterInterface *iface)
        : HierarchicalObject(dev_obj, name) {
        init_iface(iface);
    }
    HierarchicalObject(MappableConfObject *dev_obj,
                       const std::string &name,
                       BankInterface *iface)
        : HierarchicalObject(dev_obj, name) {
        init_iface(iface);
    }
 
    virtual ~HierarchicalObject() {
        auto *obj = bank_obj_ref_.object();
        if (obj) {
            if (SIM_object_is_configured(obj)) {
                if (!SIM_marked_for_deletion(obj)) {
                    SIM_LOG_CRITICAL(obj, 0,
                                     "Hierarchical object can't be deleted"
                                     " during the simulation");
                }
            }
        }
    }
 
    // No duplication
    HierarchicalObject(const HierarchicalObject&) = delete;
    HierarchicalObject& operator=(const HierarchicalObject&) = delete;
 
    HierarchicalObject(HierarchicalObject &&rhs) noexcept
        : dev_obj_(rhs.dev_obj_),
        hierarchical_name_(std::move(rhs.hierarchical_name_)),
        desc_(std::move(rhs.desc_)),
        bank_obj_ref_(rhs.bank_obj_ref_),
        level_(rhs.level_) {}
    HierarchicalObject& operator=(HierarchicalObject&& rhs) noexcept {
        // check for self-assignment
        if (this == &rhs)
            return *this;
 
        HierarchicalObject temp(std::move(rhs));
        std::swap(dev_obj_, temp.dev_obj_);
        std::swap(hierarchical_name_, temp.hierarchical_name_);
        std::swap(desc_, temp.desc_);
        std::swap(bank_obj_ref_, temp.bank_obj_ref_);
        std::swap(level_, temp.level_);
        return *this;
    }
 
    void init_iface(BankInterface *iface) {
        if (level_ != Level::BANK) {
            std::string err = "Bank name (" + hierarchical_name_ \
                + ") does not match the bank level (bankA)";
            SIM_LOG_CRITICAL_STR(bank_obj_ref(), 0, err);
            throw std::invalid_argument { err };
        }
        dev_obj_->set_iface<BankInterface>(hierarchical_name_, iface);
    }
 
    void init_iface(RegisterInterface *iface) {
        if (level_ != Level::REGISTER) {
            std::string err = "Register name (" + hierarchical_name_ \
                + ") does not match the register level (bankA.registerB)";
            SIM_LOG_CRITICAL_STR(bank_obj_ref(), 0, err);
            throw std::invalid_argument { err };
        }
        dev_obj_->set_iface<RegisterInterface>(hierarchical_name_, iface);
    }
 
    void init_iface(FieldInterface *iface) {
        if (level_ != Level::FIELD) {
            std::string err = "Field name (" + hierarchical_name_ \
                + ") does not match the field level (bankA.registerB.fieldC)";
            SIM_LOG_CRITICAL_STR(bank_obj_ref(), 0, err);
            throw std::invalid_argument { err };
        }
        dev_obj_->set_iface<FieldInterface>(hierarchical_name_, iface);
    }
 
    const std::string &hierarchical_name() const override {
        return hierarchical_name_;
    }
 
    std::string_view name() const override {
        if (hierarchy_level() == Level::BANK) {
            return hierarchical_name();
        } else {
            return {hierarchical_name().data()                  \
                    + hierarchical_name().rfind(SEPARATOR) + 1};
        }
    }
 
    const std::string &description() const override {
        return desc_;
    }
 
    void set_description(std::string_view desc) override {
        desc_ = desc;
    }
 
    Level hierarchy_level() const override {
        return level_;
    }
 
    std::string_view bank_name() const override {
        if (hierarchy_level() == Level::BANK) {
            return name();
        } else {
            return {hierarchical_name().data(),
                    hierarchical_name().find(SEPARATOR)};
        }
    }
 
    MappableConfObject *dev_obj() const override {
        return dev_obj_;
    }
 
    ConfObjectRef bank_obj_ref() const override {
        return bank_obj_ref_;
    }
 
    template<typename T> T *dev_ptr() {
        static_assert(std::is_base_of<MappableConfObject, T>::value,
                      "T needs be a MappableConfObject");
        return dynamic_cast<T *>(dev_obj());
    }
 
    std::string_view parent_name() const override {
        if (hierarchy_level() == Level::BANK) {
            return {};
        } else {
            return {hierarchical_name().data(),
                    hierarchical_name().rfind(SEPARATOR)};
        }
    }
 
    FieldInterface *lookup_field(const std::string &name) const override {
        FieldInterface *field_interface = nullptr;
        if (!dev_obj_->finalized()) {
            SIM_LOG_ERROR(dev_obj_->obj(), 0,
                          "Look up field should be called after finalize"
                          " phase");
            return field_interface;
        }
        if (!is_valid_hierarchical_name(name)) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Invalid field name: {}", name));
            return field_interface;
        }
 
        int field_name_level = level_of_hierarchical_name(name);
        if (field_name_level == 0) {
            // With field name only like "f2"
            if (level_ == Level::REGISTER) {
                 field_interface = dev_obj_->get_iface<FieldInterface>(
                        hierarchical_name_ + SEPARATOR + name);
            } else if (level_ == Level::FIELD) {
                field_interface = dev_obj_->get_iface<FieldInterface>(
                        hierarchical_name_.substr(0, hierarchical_name_.rfind(
                                                          SEPARATOR)) \
                        + SEPARATOR + name);
            } else {
                SIM_LOG_ERROR(dev_obj_->obj(), 0,
                              "Unable to lookup a field with field name only"
                              " in a bank");
            }
        } else if (field_name_level == 1) {
            // With field name only like "r1.f2"
            field_interface = dev_obj_->get_iface<FieldInterface>(
                    std::string(bank_name()).append(1, SEPARATOR).append(name));
        } else {
            field_interface = dev_obj_->get_iface<FieldInterface>(name);
        }
 
        if (!field_interface) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Lookup field failed: {}", name));
        }
        return field_interface;
    }
 
    RegisterInterface *lookup_register(const std::string &name) const override {
        RegisterInterface *register_interface = nullptr;
        if (!dev_obj_->finalized()) {
            SIM_LOG_ERROR(dev_obj_->obj(), 0,
                          "Look up register should be called after finalize"
                          " phase");
            return register_interface;
        }
        if (!is_valid_hierarchical_name(name)) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Invalid register name: {}", name));
            return register_interface;
        }
 
        int register_name_level = level_of_hierarchical_name(name);
        if (register_name_level > static_cast<int>(Level::REGISTER)) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Invalid register name: {}", name));
        } else {
            register_interface = dev_obj_->get_iface<RegisterInterface>(
                    std::string(bank_name()).append(1, SEPARATOR).append(name));
        }
 
        if (!register_interface) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Lookup register failed: {}", name));
        }
        return register_interface;
    }
 
    BankInterface *lookup_bank(const std::string &name) const override {
        BankInterface *bank_interface = nullptr;
        if (!dev_obj_->finalized()) {
            SIM_LOG_ERROR(dev_obj_->obj(), 0,
                          "Look up bank should be called after finalize phase");
            return bank_interface;
        }
        if (!is_valid_hierarchical_name(name)) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Invalid bank name: {}", name));
            return bank_interface;
        }
 
        int bank_name_level = level_of_hierarchical_name(name);
        if (bank_name_level > static_cast<int>(Level::BANK)) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Invalid bank name: {}", name));
        } else {
            bank_interface = dev_obj_->get_iface<BankInterface>(name);
        }
 
        if (!bank_interface) {
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0,
                              fmt::format("Lookup bank failed: {}", name));
        }
        return bank_interface;
    }
 
    static bool is_valid_hierarchical_name(std::string_view name) {
        // The allowed characters in the hierarchical object's name
        static const char *allowed_characters {
            "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ[]._"
        };
 
        if (name.empty()) {
            return false;
        }
        if (isdigit(name[0]) || name[0] == '['
            || name[0] == ']' || name[0] == '_') {
            return false;
        }
        if (name.find_first_not_of(allowed_characters) != std::string::npos) {
            return false;
        }
        if (std::count(name.cbegin(), name.cend(), SEPARATOR) > 2) {
            return false;
        }
        if (name.find(std::string(2, SEPARATOR)) != std::string::npos) {
            return false;
        }
        if (name.find(SEPARATOR) == 0
            || name.rfind(SEPARATOR) == name.length() - 1) {
            return false;
        }
        return true;
    }
 
    static int level_of_hierarchical_name(std::string_view name) {
        assert(!name.empty());
        assert(is_valid_hierarchical_name(name));
 
        return std::count(name.cbegin(), name.cend(), SEPARATOR);
    }
 
    static const uint64_t Register_Read {1};
    static const uint64_t Register_Write {2};
 
  private:
    void init() {
        if (!is_valid_hierarchical_name(hierarchical_name_)) {
            std::string err = "Cannot set with invalid name string: " \
                + hierarchical_name_;
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0, err);
            throw std::invalid_argument { err };
        }
 
        level_ = static_cast<Level>(
                level_of_hierarchical_name(hierarchical_name_));
 
        std::string bank_name {hierarchical_name_};
        if (level_ != Level::BANK) {
            auto pos_first_separator = hierarchical_name_.find(SEPARATOR);
            assert(pos_first_separator != std::string::npos);
            bank_name = hierarchical_name_.substr(0, pos_first_separator);
        }
 
        bank_obj_ref_ = SIM_object_descendant(
                dev_obj_->obj(), ("bank." + bank_name).c_str());
        if (bank_obj_ref_.object() == nullptr) {
            std::string err = fmt::format("{}.bank.{} does not exist",
                                          dev_obj_->obj().name(),
                                          bank_name);
            SIM_LOG_ERROR_STR(dev_obj_->obj(), 0, err);
            throw std::invalid_argument { err };
        }
    }
 
    MappableConfObject *dev_obj_;
    std::string hierarchical_name_;
    std::string desc_;
    ConfObjectRef bank_obj_ref_;
    Level level_;
};
 
}  // namespace simics
 
#endif