memory.h

/*******************************************************************************
 * Copyright 2016, 2018 MINRES Technologies GmbH
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *******************************************************************************/
 
#ifndef _SYSC_MEMORY_H_
#define _SYSC_MEMORY_H_
 
// Needed for the simple_target_socket
#include <nonstd/span.h>
#include <tlm/scc/memory_map_collector.h>
#include <tlm_core/tlm_2/tlm_generic_payload/tlm_gp.h>
#include <util/ities.h>
#ifndef SC_INCLUDE_DYNAMIC_PROCESSES
#define SC_INCLUDE_DYNAMIC_PROCESSES
#endif
 
#include "clock_if_mixins.h"
#include <cci_configuration>
#include <cstdint>
#include <numeric>
#include <scc/mt19937_rng.h>
#include <scc/report.h>
#include <scc/signal_opt_ports.h>
#include <scc/utilities.h>
#include <tlm.h>
#include <tlm/scc/target_mixin.h>
#include <type_traits>
#include <util/range_lut.h>
#include <util/sparse_array.h>
 
namespace scc {
template <bool USE_CYCLES> struct delay_spec_type;
 
template <> struct delay_spec_type<true> {
    using type = unsigned;
    static inline unsigned get_default_val() { return 0; };
    static inline sc_core::sc_time get_effective_value(unsigned cycles, sc_core::sc_time period) { return cycles * period; }
};
 
template <> struct delay_spec_type<false> {
    using type = sc_core::sc_time;
    static inline sc_core::sc_time get_default_val() { return sc_core::SC_ZERO_TIME; };
    static inline sc_core::sc_time get_effective_value(sc_core::sc_time delay, sc_core::sc_time period) { return delay; }
};

template <unsigned long long SIZE, unsigned BUSWIDTH = LT, unsigned PAGE_ADDR_BITS = 24, bool USE_CYCLES = false>
class memory : public sc_core::sc_module {
public:
    using delay_type = typename delay_spec_type<USE_CYCLES>::type;
    using this_class = memory<SIZE, BUSWIDTH, PAGE_ADDR_BITS, USE_CYCLES>;

    tlm::scc::target_mixin<tlm::tlm_target_socket<BUSWIDTH>> target{"ts"};
    memory(const sc_core::sc_module_name& nm);
    static constexpr unsigned long long getPageSize() { return 1 << PAGE_ADDR_BITS; }
    static constexpr unsigned long long getSize() { return SIZE; }
    void set_operation_callback(std::function<int(memory<SIZE, BUSWIDTH>&, tlm::tlm_generic_payload&, sc_core::sc_time& delay)> cb) {
        operation_cb = cb;
    }

    void set_dmi_callback(std::function<bool(memory<SIZE, BUSWIDTH>&, tlm::tlm_generic_payload&, tlm::tlm_dmi&)> cb) { dmi_cb = cb; }
    cci::cci_param<bool> allow_dmi{"allow_dmi", true, "Allow DMI accesses to this memory if set"};
    cci::cci_param<delay_type> rd_resp_delay{"rd_resp_delay", delay_spec_type<USE_CYCLES>::get_default_val()};
    cci::cci_param<delay_type> wr_resp_delay{"wr_resp_delay", delay_spec_type<USE_CYCLES>::get_default_val()};
    void map_host_memory(uint64_t base, uint64_t size, uint8_t* ptr) {
        try {
            host_mem_lut.addEntry(host_map_entry{ptr, base, size}, base, size);
        } catch(std::runtime_error& e) {
            SCCERR(SCMOD) << "Cannot map memory to address=0x" << std::hex << base << " with size=0x" << size << " because: " << e.what();
        }
    }

    void unmap_host_memory(uint64_t base, uint64_t size) {
        if(!host_mem_lut.removeEntry(host_map_entry{nullptr, base, size})) {
            SCCERR(SCMOD) << "Cannot unmap memory at address=0x" << std::hex << base << " with size=0x" << size;
        }
    }
 
protected:
    util::sparse_array<uint8_t, SIZE, PAGE_ADDR_BITS> mem;
    struct host_map_entry {
        uint8_t* ptr;
        uint64_t base;
        uint64_t size;
        bool operator==(host_map_entry const& o) { return base == o.base && size == o.size; }
        bool operator!=(host_map_entry const& o) { return !operator==(o); }
    };
    util::range_lut<host_map_entry> host_mem_lut{host_map_entry{nullptr, 0, 0}};
 
    void set_clock_period(sc_core::sc_time period) { clk_period = period; }
    sc_core::sc_time clk_period;
 
public:
    int handle_operation(tlm::tlm_generic_payload& trans, sc_core::sc_time& delay);
    bool handle_dmi(tlm::tlm_generic_payload& gp, tlm::tlm_dmi& dmi_data);
    std::function<int(this_class&, tlm::tlm_generic_payload&, sc_core::sc_time& delay)> operation_cb;
    std::function<bool(this_class&, tlm::tlm_generic_payload&, tlm::tlm_dmi&)> dmi_cb;
};
 
template <unsigned long long SIZE, unsigned BUSWIDTH = LT, unsigned PAGE_ADDR_BITS = 24>
using memory_tl = tickless_clock<memory<SIZE, BUSWIDTH, PAGE_ADDR_BITS, false>>;
template <unsigned long long SIZE, unsigned BUSWIDTH = LT, unsigned PAGE_ADDR_BITS = 24>
using memory_tc = ticking_clock<memory<SIZE, BUSWIDTH, PAGE_ADDR_BITS, true>>;
 
template <unsigned long long SIZE, unsigned BUSWIDTH = LT>
int handle_operation(memory<SIZE, BUSWIDTH>&, tlm::tlm_generic_payload&, sc_core::sc_time& delay);
 
struct host_mem_map_extension : public tlm::tlm_extension<host_mem_map_extension> {
    tlm_extension_base* clone() const override { return nullptr; }
    void copy_from(tlm_extension_base const& ext) override {}
    host_mem_map_extension(uint8_t* data, size_t size)
    : range(data, data + size) {}
    host_mem_map_extension(size_t size)
    : range(nullptr, size) {}
    host_mem_map_extension() = default;
    ~host_mem_map_extension() {}
    nonstd::span<uint8_t> range;
};

template <unsigned long long SIZE, unsigned BUSWIDTH, unsigned PAGE_ADDR_BITS, bool USE_CYCLES>
memory<SIZE, BUSWIDTH, PAGE_ADDR_BITS, USE_CYCLES>::memory(const sc_core::sc_module_name& nm)
: sc_module(nm) {
    // Register callback for incoming b_transport interface method call
    target.register_b_transport([this](tlm::tlm_generic_payload& gp, sc_core::sc_time& delay) -> void {
        operation_cb ? operation_cb(*this, gp, delay) : handle_operation(gp, delay);
    });
    target.register_transport_dbg([this](tlm::tlm_generic_payload& gp) -> unsigned {
        if(gp.get_command() == tlm::TLM_IGNORE_COMMAND)
            if(auto ext = gp.get_extension<tlm::scc::memory_map_extension>()) {
                ext->node.name = name();
                return 0;
            }
        sc_core::sc_time z = sc_core::SC_ZERO_TIME;
        if(auto ext = gp.get_extension<host_mem_map_extension>()) {
            if(ext->range.data())
                map_host_memory(gp.get_address(), ext->range.size(), ext->range.data());
            else
                unmap_host_memory(gp.get_address(), ext->range.size());
            if(gp.get_command() == tlm::TLM_IGNORE_COMMAND)
                return 0;
        }
        return operation_cb ? operation_cb(*this, gp, z) : handle_operation(gp, z);
    });
    target.register_get_direct_mem_ptr([this](tlm::tlm_generic_payload& gp, tlm::tlm_dmi& dmi_data) -> bool {
        return dmi_cb ? dmi_cb(*this, gp, dmi_data) : handle_dmi(gp, dmi_data);
    });
}
 
template <unsigned long long SIZE, unsigned BUSWIDTH, unsigned PAGE_ADDR_BITS, bool USE_CYCLES>
int memory<SIZE, BUSWIDTH, PAGE_ADDR_BITS, USE_CYCLES>::handle_operation(tlm::tlm_generic_payload& trans, sc_core::sc_time& delay) {
    uint64_t adr = trans.get_address();
    uint8_t* ptr = trans.get_data_ptr();
    unsigned len = trans.get_data_length();
    uint8_t* byt = trans.get_byte_enable_ptr();
    unsigned wid = trans.get_streaming_width();
    // check address range and check for unsupported features,
    //   i.e. byte enables, streaming, and bursts
    // Can ignore DMI hint and extensions
    if(adr + len > ::sc_dt::uint64(SIZE)) {
        SC_REPORT_ERROR("TLM-2", "generic payload transaction exceeeds memory size");
        trans.set_response_status(tlm::TLM_ADDRESS_ERROR_RESPONSE);
        return 0;
    }
    if(wid < len) {
        SCCERR(SCMOD) << "Streaming width: " << wid << ", data length: " << len;
        SC_REPORT_ERROR("TLM-2", "generic payload transaction not supported");
        trans.set_response_status(tlm::TLM_GENERIC_ERROR_RESPONSE);
        return 0;
    }
    auto scattered =
        byt ? std::accumulate(byt, byt + trans.get_byte_enable_length(), 0xff, [](uint8_t a, uint8_t b) { return a & b; }) != 0xff : false;
    tlm::tlm_command cmd = trans.get_command();
    SCCTRACE(SCMOD) << (cmd == tlm::TLM_READ_COMMAND ? "read" : "write") << " access to addr 0x" << std::hex << adr;
    trans.set_dmi_allowed(allow_dmi.get_value());
    trans.set_response_status(tlm::TLM_OK_RESPONSE);
    auto hm_entry = host_mem_lut.getEntry(adr);
    if(cmd == tlm::TLM_READ_COMMAND) {
        delay += delay_spec_type<USE_CYCLES>::get_effective_value(rd_resp_delay, clk_period);
        if(hm_entry.ptr) {
            auto hm_start_offs = adr - hm_entry.base;
            auto hm_end_offs = hm_start_offs + len;
            auto hm_ptr = hm_entry.ptr + hm_start_offs;
            if(hm_end_offs < hm_entry.size) {
                std::copy(hm_ptr, hm_ptr + len, ptr);
            } else {
                auto transfer_length = hm_end_offs - hm_start_offs;
                std::copy(hm_ptr, hm_ptr + transfer_length, ptr);
                for(size_t i = transfer_length; i < len; i++)
                    ptr[i] = scc::MT19937::uniform() % 256;
            }
        } else {
            if(mem.is_allocated(adr)) {
                const auto& p = mem(adr / mem.page_size);
                auto offs = adr & mem.page_addr_mask;
                if((offs + len) > mem.page_size) {
                    auto first_part = mem.page_size - offs;
                    std::copy(p.data() + offs, p.data() + offs + first_part, ptr);
                    const auto& p2 = mem((adr / mem.page_size) + 1);
                    auto second_part = len - first_part;
                    std::copy(p2.data(), p2.data() + second_part, ptr + first_part);
                } else {
                    std::copy(p.data() + offs, p.data() + offs + len, ptr);
                }
            } else {
                // no allocated page so return randomized data
                for(size_t i = 0; i < len; i++)
                    ptr[i] = scc::MT19937::uniform() % 256;
            }
        }
    } else if(cmd == tlm::TLM_WRITE_COMMAND) {
        delay += delay_spec_type<USE_CYCLES>::get_effective_value(clk_period, wr_resp_delay);
        if(UNLIKELY(hm_entry.ptr)) {
            auto hm_start_offs = adr - hm_entry.base;
            auto hm_end_offs = adr + len - hm_entry.base;
            auto hm_ptr = hm_entry.ptr + hm_start_offs;
            auto transfer_length = hm_end_offs < hm_entry.size ? len : hm_end_offs - hm_start_offs;
            if(scattered) {
                for(size_t i = 0; i < transfer_length; ++i)
                    if(byt[i] == 0xff)
                        *(hm_ptr + i) = *(ptr + i);
            } else
                std::copy(ptr, ptr + transfer_length, hm_ptr);
        } else {
            auto& p = mem(adr / mem.page_size);
            auto offs = adr & mem.page_addr_mask;
            if(UNLIKELY((offs + len) > mem.page_size)) { // we cross a page of the memory
                auto first_part = mem.page_size - offs;
                if(scattered) {
                    for(size_t i = 0; i < first_part; ++i)
                        if(byt[i] == 0xff)
                            *(p.data() + offs + i) = *(ptr + i);
                } else
                    std::copy(ptr, ptr + first_part, p.data() + offs);
                auto& p2 = mem((adr / mem.page_size) + 1);
                if(scattered) {
                    for(size_t i = 0, j = first_part; j < len; ++i, ++j)
                        if(byt[j] == 0xff)
                            *(p2.data() + i) = *(ptr + j);
                } else
                    std::copy(ptr + first_part, ptr + len, p2.data());
            } else { // we stay within a page of the memory
                if(scattered) {
                    for(size_t i = 0; i < len; ++i)
                        if(byt[i] == 0xff)
                            *(p.data() + offs + i) = *(ptr + i);
                } else
                    std::copy(ptr, ptr + len, p.data() + offs);
            }
        }
    }
    return len;
}
 
template <unsigned long long SIZE, unsigned BUSWIDTH, unsigned PAGE_ADDR_BITS, bool USE_CYCLES>
inline bool memory<SIZE, BUSWIDTH, PAGE_ADDR_BITS, USE_CYCLES>::handle_dmi(tlm::tlm_generic_payload& gp, tlm::tlm_dmi& dmi_data) {
    if(allow_dmi.get_value()) {
        auto hm_entry = host_mem_lut.getEntry(gp.get_address());
        if(hm_entry.ptr) {
            dmi_data.set_start_address(hm_entry.base);
            dmi_data.set_end_address(hm_entry.base + hm_entry.size - 1);
            dmi_data.set_dmi_ptr(hm_entry.ptr);
        } else {
            auto& p = mem(gp.get_address() / mem.page_size);
            auto start_address = gp.get_address() & ~mem.page_addr_mask;
            auto end_address = std::min<uint64_t>(start_address + mem.page_size, SIZE);
            dmi_data.set_start_address(start_address);
            dmi_data.set_end_address(end_address - 1);
            dmi_data.set_dmi_ptr(p.data());
        }
        dmi_data.set_granted_access(tlm::tlm_dmi::DMI_ACCESS_READ_WRITE);
        dmi_data.set_read_latency(delay_spec_type<USE_CYCLES>::get_effective_value(clk_period, rd_resp_delay));
        dmi_data.set_write_latency(delay_spec_type<USE_CYCLES>::get_effective_value(clk_period, wr_resp_delay));
    }
    return allow_dmi.get_value();
}
 
} // namespace scc
 
#endif /* _SYSC_MEMORY_H_ */