bank-interface.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_IFACE_BANK_INTERFACE_H
#define SIMICS_IFACE_BANK_INTERFACE_H
 
#include <simics/base/memory.h>  // exception_type_t
#include <string_view>
#include <utility>
#include <cstdint>
#include <string>
#include <map>
#include <vector>
 
#include "../type/register-type.h"
 
struct transaction;
typedef struct transaction transaction_t;
 
namespace simics {
 
enum class ByteOrder {
    BE, LE,
};
 
class MappableConfObject;
class RegisterInterface;
class BankIssueCallbacksInterface;
 
/*
 * An interface implemented by a Simics bank
 */
class BankInterface {
  public:
    virtual ~BankInterface() = default;
 
    // @return the bank name without level delimiter
    virtual std::string_view name() const = 0;
 
    // @return the device object holds the bank
    virtual MappableConfObject *dev_obj() const = 0;
 
    // @return the description of the object
    virtual const std::string &description() const = 0;
 
    // Set description for the bank
    virtual void set_description(std::string_view desc) = 0;
 
    // Parse register name and add register(s) to the bank
    virtual void add_register(const register_t &reg) = 0;
 
    // Add a register to the bank
    virtual void add_register(std::string_view name, std::string_view desc,
                              Offset offset, ByteSize number_of_bytes,
                              InitValue init_value,
                              const std::vector<field_t> &fields) = 0;
 
    // @return the number of registers on the bank
    virtual unsigned number_of_registers() const = 0;
 
    /*
     * @return register offset and interface with an index into a
     * sorted registers by their offsets on the bank. {0, nullptr}
     * is returned for an outbound access.
     */
    virtual std::pair<size_t, RegisterInterface *> register_at_index(
            unsigned index) const = 0;
 
    // @return all mapped registers on the bank ordered by offset
    virtual const std::map<size_t, RegisterInterface *> &
    mapped_registers() const = 0;
 
    // Set the callback issuer
    virtual void set_callbacks(BankIssueCallbacksInterface *callbacks) = 0;
 
    // @return the bank's byte endianness
    virtual ByteOrder get_byte_order() const = 0;
 
    /*
     * Set the byte pattern returned in a miss read (read from an offset
     * where no registers are mapped)
     */
    virtual void set_miss_pattern(uint8_t miss_pattern) = 0;
 
    /*
     * Entry point for a memory access from the transaction interface.
     * The function extracts necessary information from t, calls appropriate
     * access methods(read or write), and updates the t parameter
     * accordingly.
     * @param offset is relative to the bank
     * @return Sim_PE_No_Exception if the access succeeded, and
     * SIM_PE_IO_Not_Taken otherwise.
     */
    virtual exception_type_t transaction_access(transaction_t *t,
                                                uint64_t offset) = 0;
};
 
}  // namespace simics
 
#endif