bank-port.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_BANK_PORT_H
#define SIMICS_BANK_PORT_H
 
#include <simics/base/attr-value.h>
#include <simics/base/notifier.h>  // SIM_register_notifier
#include <simics/simulator-api.h>  // SIM_hap_XXX
#include <simics/c++/model-iface/transaction.h>
#include <simics/c++/model-iface/register-view.h>
#include <simics/c++/model-iface/register-view-read-only.h>
#include <string>
#include <memory>
#include <type_traits>  // is_base_of
#include <exception>
 
#include "conf-object.h"
#include "port.h"
#include "bank.h"
#include "bank-instrumentation-subscribe-connection.h"
#include "mappable-conf-object.h"
#include "iface/bank-port-interface.h"
#include "iface/bank-interface.h"
#include "iface/register-interface.h"
#include "type/bank-type.h"
 
namespace simics {
 
/*
 * The class for bank port objects
 *
 * In Simics, each port object contains exactly one bank, the name of the
 * bank is determined by the CTOR parameter o. The instance of this class
 * must have a valid bank interface to direct the received Simics interface
 * calls.
 *
 * @param template parameter TParent must set to the class of the
 * parent device
 */
template <typename TParent>
// coverity[rule_of_three_violation:FALSE]
class BankPort : public Port<TParent>,
                 public BankPortInterface,
                 public BankInstrumentationSubscribeConnection,
                 public iface::RegisterViewInterface,
                 public iface::RegisterViewReadOnlyInterface,
                 public iface::TransactionInterface {
    static_assert(
            std::is_base_of<MappableConfObject, TParent>::value,
            "BankPort requires the parent class be a MappableConfObject");
 
  public:
    /*
     * Used by the "by code" option to set a bank on the port
     * By this option, the bank is created as a class member variable of
     * the user defined bank port class. Thus no need to initialize the
     * bank_iface here.
     */
    explicit BankPort(ConfObjectRef o)
        : Port<TParent>(o),
          bank_name_(bank_name_from_port_obj(o)) {
        dev_obj()->set_bank_as_initialized(bank_name_);
        SIM_hap_add_callback_obj(
                "Core_Conf_Object_Created", o.object(), 0,
                reinterpret_cast<obj_hap_func_t>(object_created), nullptr);
    }
 
    /*
     * Used by the "by data" option to set a bank on the port
     * By this option, bank is created and initialized here.
     */
    BankPort(ConfObjectRef o, const bank_t *bank)
        : BankPort(o) {
        if (bank == nullptr) {
            throw std::invalid_argument("Bank pointer cannot be nullptr");
        }
        set_bank(*bank);
    }
 
    // non-copyable
    BankPort(const BankPort &) = delete;
    BankPort &operator=(const BankPort &) = delete;
 
    virtual ~BankPort() {
        SIM_hap_delete_callback_obj(
                "Core_Conf_Object_Created", Port<TParent>::obj().object(),
                reinterpret_cast<obj_hap_func_t>(object_created), nullptr);
    }
 
    // BankPortInterface
    std::string_view bank_name() const override {
        return bank_name_;
    }
 
    const BankInterface *bank_iface() const override {
        return bank_iface_;
    }
 
    MappableConfObject *dev_obj() const override {
        return Port<TParent>::parent();
    };
 
    bool validate_bank_iface() const override {
#if __cplusplus >= 202002L || (defined(_MSVC_LANG) && _MSVC_LANG >= 202002L)
        if (bank_iface_ == nullptr) { [[unlikely]]
#else
        if (bank_iface_ == nullptr) {
#endif
            SIM_LOG_ERROR(Port<TParent>::obj(), 0,
                          "BankPort should have one bank");
            return false;
        }
        return true;
    }
 
    void set_bank(const bank_t &bank) override {
        if (bank_iface_) {
            SIM_LOG_ERROR(Port<TParent>::obj(), 0,
                          "bank iface can only be set once");
            return;
        }
 
        bank_iface_ = dev_obj()->template get_iface<BankInterface>(bank_name_);
        if (bank_iface_) {
            SIM_LOG_INFO(3, Port<TParent>::obj(), 0,
                         "Used user defined bank for %s",
                         bank_name_.c_str());
        } else {
            allocated_bank_.reset(new Bank(dev_obj(), bank_name_));
            bank_iface_ = allocated_bank_.get();
            SIM_LOG_INFO(3, Port<TParent>::obj(), 0,
                         "Created a new default bank for %s",
                         bank_name_.c_str());
        }
        auto &[name, desc, registers] = bank;
        bank_iface_->set_description(desc);
        bank_iface_->set_callbacks(this);
        for (auto &reg : registers) {
            bank_iface_->add_register(reg);
        }
    }
 
    // iface::TransactionInterface
    exception_type_t issue(transaction_t *t, uint64 addr) override {
        if (!validate_bank_iface()) {
            return Sim_PE_IO_Not_Taken;
        }
        return bank_iface_->transaction_access(t, addr);
    }
 
    // iface::RegisterViewInterface
    const char *description() override {
        if (!validate_bank_iface()) {
            return nullptr;
        }
        return bank_iface_->description().data();
    }
    bool big_endian_bitorder() override {
        return Port<TParent>::parent()->big_endian_bitorder();
    }
    unsigned number_of_registers() override {
        if (!validate_bank_iface()) {
            return 0;
        }
        return bank_iface_->number_of_registers();
    } 
    attr_value_t register_info(unsigned reg) override {
        if (!validate_bank_iface()) {
            return SIM_make_attr_nil();
        }
        auto[reg_offset, reg_iface] = bank_iface_->register_at_index(reg);
        if (reg_iface) {
            return register_info(reg_offset,
                                 bank_iface_->get_byte_order(),
                                 reg_iface);
        }
        return SIM_make_attr_nil();
    }
    uint64 get_register_value(unsigned reg) override {
        if (!validate_bank_iface()) {
            return 0;
        }
        auto[reg_offset, reg_iface] = bank_iface_->register_at_index(reg);
        return reg_iface ? reg_iface->get() : 0;
    }
    void set_register_value(unsigned reg, uint64 val) override {
        if (validate_bank_iface()) {
            auto[reg_offset, reg_iface] = bank_iface_->register_at_index(reg);
            if (reg_iface) {
                reg_iface->set(val);
            }
        }
    }
 
    // iface::RegisterViewReadOnlyInterface
    bool is_read_only(unsigned reg) override {
        if (!validate_bank_iface()) {
            return false;
        }
        auto[reg_offset, reg_iface] = bank_iface_->register_at_index(reg);
        return reg_iface ? reg_iface->is_read_only() : false;
    }
 
  private:
    // Function get called when the object is created and finalized
    static void object_created(lang_void *, conf_object_t *obj) {
        get_interface<BankPortInterface>(obj)->validate_bank_iface();
    }
 
    static std::string_view bank_name_from_port_obj(ConfObjectRef port_obj) {
        std::string_view port_name = port_obj.name();
        if (port_name.find(bank_name_keyword) == std::string::npos) {
            throw std::invalid_argument(
                    "Invalid bank port name (" + port_obj.name() + ")");
        }
        return port_name.substr(port_name.rfind(bank_name_keyword) + \
                                bank_name_keyword.size());
    }
 
    static attr_value_t register_info(size_t address, ByteOrder bo,
                                      const RegisterInterface *i) {
        attr_value_t info = SIM_alloc_attr_list(6);
        SIM_attr_list_set_item(&info, 0,
                               SIM_make_attr_string(i->name().data()));
        SIM_attr_list_set_item(&info, 1,
                               SIM_make_attr_string(i->description().c_str()));
        SIM_attr_list_set_item(&info, 2,
                               SIM_make_attr_uint64(i->number_of_bytes()));
        SIM_attr_list_set_item(&info, 3, SIM_make_attr_uint64(address));
 
        auto fields_info = i->fields_info();
        // The forth attr in info is a list fields
        attr_value_t fields = SIM_alloc_attr_list(fields_info.size());
        unsigned index = 0;
        for (const auto &[name, desc, offset, width] : fields_info) {
            // Each attr in fields is another list field_info
            attr_value_t field_info = SIM_alloc_attr_list(4);
            SIM_attr_list_set_item(&field_info, 0,
                                   SIM_make_attr_string(name.data()));
            SIM_attr_list_set_item(&field_info, 1,
                                   SIM_make_attr_string(desc.data()));
            SIM_attr_list_set_item(&field_info, 2,
                                   SIM_make_attr_uint64(offset));
            SIM_attr_list_set_item(&field_info, 3,
                                   SIM_make_attr_uint64(offset + width - 1));
            SIM_attr_list_set_item(&fields, index++, field_info);
        }
        SIM_attr_list_set_item(&info, 4, fields);
        SIM_attr_list_set_item(&info, 5,
                               SIM_make_attr_boolean(bo == ByteOrder::BE));
        return info;
    }
 
    // A keyword exists in the name of all bank ports
    static constexpr std::string_view bank_name_keyword {".bank."};
    // Points to the actual bank interface
    BankInterface *bank_iface_ { nullptr };
    // Name of the bank
    std::string bank_name_;
    // @internal: record the heap allocated Bank
    std::unique_ptr<BankInterface> allocated_bank_;
};
 
template <typename TBankPort> ConfClassPtr
make_bank_port(const std::string &name, const std::string &desc) {
    auto port = simics::make_class<TBankPort>(name, "", desc);
    port->add(simics::iface::TransactionInterface::Info());
    port->add(simics::iface::RegisterViewInterface::Info());
    port->add(simics::iface::RegisterViewReadOnlyInterface::Info());
    port->add(simics::iface::BankInstrumentationSubscribeInterface::Info());
    port->add(simics::iface::InstrumentationOrderInterface::Info());
    port->add(simics::LogGroups{"Register_Read", "Register_Write"});
    SIM_register_notifier(*port, Sim_Notify_Bank_Register_Value_Change,
                          NULL /* default description works well */);
    return port;
}
 
template <typename TBankPort, typename TArg> ConfClassPtr
make_bank_port(const std::string &name, const std::string &desc, TArg *arg) {
    auto port = simics::make_class<TBankPort>(name, "", desc, arg);
    port->add(simics::iface::TransactionInterface::Info());
    port->add(simics::iface::RegisterViewInterface::Info());
    port->add(simics::iface::RegisterViewReadOnlyInterface::Info());
    port->add(simics::iface::BankInstrumentationSubscribeInterface::Info());
    port->add(simics::iface::InstrumentationOrderInterface::Info());
    port->add(simics::LogGroups{"Register_Read", "Register_Write"});
    SIM_register_notifier(*port, Sim_Notify_Bank_Register_Value_Change,
                          NULL /* default description works well */);
    return port;
}
 
/*
 *  Register the bank as port object, pass the pointer to the registers as
 *  the class data.
 */
template <typename TParent>
void create_hierarchy_from_register_data(ConfClass *cls, const bank_t &bank) {
    const auto &[name, desc, registers] = bank;
    cls->add(make_bank_port<BankPort<TParent>, const bank_t>(
                     cls->name() + SEPARATOR + std::string(name.base_name()),
                     desc.data(), &bank),
             std::string("bank.") + name.data());
}
 
template <typename TParent>
void create_hierarchy_from_register_data(
        ConfClass *cls, std::initializer_list<bank_t> register_data) {
    for (auto &bank : register_data) {
        create_hierarchy_from_register_data<TParent>(cls, bank);
    }
}
 
}  // namespace simics
 
#endif