113521Sgabeblack@google.com/***************************************************************************** 213521Sgabeblack@google.com 313521Sgabeblack@google.com Licensed to Accellera Systems Initiative Inc. (Accellera) under one or 413521Sgabeblack@google.com more contributor license agreements. See the NOTICE file distributed 513521Sgabeblack@google.com with this work for additional information regarding copyright ownership. 613521Sgabeblack@google.com Accellera licenses this file to you under the Apache License, Version 2.0 713521Sgabeblack@google.com (the "License"); you may not use this file except in compliance with the 813521Sgabeblack@google.com License. You may obtain a copy of the License at 913521Sgabeblack@google.com 1013521Sgabeblack@google.com http://www.apache.org/licenses/LICENSE-2.0 1113521Sgabeblack@google.com 1213521Sgabeblack@google.com Unless required by applicable law or agreed to in writing, software 1313521Sgabeblack@google.com distributed under the License is distributed on an "AS IS" BASIS, 1413521Sgabeblack@google.com WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 1513521Sgabeblack@google.com implied. See the License for the specific language governing 1613521Sgabeblack@google.com permissions and limitations under the License. 1713521Sgabeblack@google.com 1813521Sgabeblack@google.com *****************************************************************************/ 1913521Sgabeblack@google.com 2013521Sgabeblack@google.com#ifndef __SYSTEMC_EXT_TLM_CORE_2_INTERFACES_FW_BW_IFS_HH__ 2113521Sgabeblack@google.com#define __SYSTEMC_EXT_TLM_CORE_2_INTERFACES_FW_BW_IFS_HH__ 2213521Sgabeblack@google.com 2313586Sgabeblack@google.com#include "../../../core/sc_interface.hh" 2413586Sgabeblack@google.com#include "../../../core/sc_time.hh" 2513586Sgabeblack@google.com#include "../generic_payload/generic_payload.hh" 2613586Sgabeblack@google.com#include "dmi.hh" 2713521Sgabeblack@google.com 2813521Sgabeblack@google.comnamespace tlm 2913521Sgabeblack@google.com{ 3013521Sgabeblack@google.com 3113521Sgabeblack@google.comenum tlm_sync_enum { TLM_ACCEPTED, TLM_UPDATED, TLM_COMPLETED }; 3213521Sgabeblack@google.com 3313521Sgabeblack@google.com//////////////////////////////////////////////////////////////////////////// 3413521Sgabeblack@google.com// Basic interfaces 3513521Sgabeblack@google.com//////////////////////////////////////////////////////////////////////////// 3613521Sgabeblack@google.comtemplate <typename TRANS=tlm_generic_payload, typename PHASE=tlm_phase> 3713521Sgabeblack@google.comclass tlm_fw_nonblocking_transport_if : public virtual sc_core::sc_interface 3813521Sgabeblack@google.com{ 3913521Sgabeblack@google.com public: 4013521Sgabeblack@google.com virtual tlm_sync_enum nb_transport_fw(TRANS &trans, PHASE &phase, 4113521Sgabeblack@google.com sc_core::sc_time& t) = 0; 4213521Sgabeblack@google.com}; 4313521Sgabeblack@google.com 4413521Sgabeblack@google.comtemplate <typename TRANS=tlm_generic_payload, typename PHASE=tlm_phase> 4513521Sgabeblack@google.comclass tlm_bw_nonblocking_transport_if : public virtual sc_core::sc_interface 4613521Sgabeblack@google.com{ 4713521Sgabeblack@google.com public: 4813521Sgabeblack@google.com virtual tlm_sync_enum nb_transport_bw(TRANS &trans, PHASE &phase, 4913521Sgabeblack@google.com sc_core::sc_time &t) = 0; 5013521Sgabeblack@google.com}; 5113521Sgabeblack@google.com 5213521Sgabeblack@google.comtemplate <typename TRANS=tlm_generic_payload> 5313521Sgabeblack@google.comclass tlm_blocking_transport_if : public virtual sc_core::sc_interface 5413521Sgabeblack@google.com{ 5513521Sgabeblack@google.com public: 5613521Sgabeblack@google.com virtual void b_transport(TRANS &trans, sc_core::sc_time &t) = 0; 5713521Sgabeblack@google.com}; 5813521Sgabeblack@google.com 5913521Sgabeblack@google.com////////////////////////////////////////////////////////////////////////// 6013521Sgabeblack@google.com// DMI interfaces for getting and invalidating DMI pointers: 6113521Sgabeblack@google.com////////////////////////////////////////////////////////////////////////// 6213521Sgabeblack@google.com 6313521Sgabeblack@google.com// The semantics of the forward interface are as follows: 6413521Sgabeblack@google.com// 6513521Sgabeblack@google.com// - An initiator that wants to get direct access to a target's memory region 6613521Sgabeblack@google.com// can call the get_direct_mem_ptr method with the 'trans' parameter set to 6713521Sgabeblack@google.com// the address that it wants to gain access to. It sets the trans.m_command 6813521Sgabeblack@google.com// to specify if the initiator intended use (read or write) 6913521Sgabeblack@google.com// to the target's DMI region. The initiator is responsible for calling the 7013521Sgabeblack@google.com// method with a freshly initialized tlm_dmi object either by using a newly 7113521Sgabeblack@google.com// constructed object, or by calling an existing object's init() method. 7213521Sgabeblack@google.com// - Although a reference to a complete 'TRANS' type is passed to the get_ 7313521Sgabeblack@google.com// direct_mem_ptr call, only the address command, and extension fields are of 7413521Sgabeblack@google.com// interest in most cases. 7513521Sgabeblack@google.com// - Read and write ranges are not necessarily identical. If they are, a target 7613521Sgabeblack@google.com// can specify that the range is valid for all accesses with the tlm_data 7713521Sgabeblack@google.com// m_type attribute in the. 7813521Sgabeblack@google.com// - The interconnect, if any, needs to decode the address and forward the 7913521Sgabeblack@google.com// call to the corresponding target. It needs to handle the address exactly 8013521Sgabeblack@google.com// as the target would expect on a transaction call, e.g. mask the address 8113521Sgabeblack@google.com// according to the target's address width. 8213521Sgabeblack@google.com// - If the target supports DMI access for the given address, it sets the 8313521Sgabeblack@google.com// data fields in the DMI struct and returns true. 8413521Sgabeblack@google.com// - If a target does not support DMI access it needs to return false. 8513521Sgabeblack@google.com// The target can either set the correct address range in the DMI struct 8613521Sgabeblack@google.com// to indicate the memory region where DMI is disallowed, or it can specify 8713521Sgabeblack@google.com// the complete address range if it doesn't know it's memory range. In this 8813521Sgabeblack@google.com// case the interconnect is responsible for clipping the address range to 8913521Sgabeblack@google.com// the correct range that the target serves. 9013521Sgabeblack@google.com// - The interconnect must always translate the addresses to the initiator's 9113521Sgabeblack@google.com// address space. This must be the inverse operation of what the 9213521Sgabeblack@google.com// interconnect needed to do when forwarding the call. In case the 9313521Sgabeblack@google.com// component wants to change any member of the tlm_dmi object, e.g. for 9413521Sgabeblack@google.com// its own latency to the target's latency, it must only do so *after* the 9513521Sgabeblack@google.com// target has been called. The target is always allowed to overwrite all 9613521Sgabeblack@google.com// values in the tlm_dmi object. 9713521Sgabeblack@google.com// - In case the slave returned with an invalid region the bus/interconnect 9813521Sgabeblack@google.com// must fill in the complete address region for the particular slave in the 9913521Sgabeblack@google.com// DMI data structure. 10013521Sgabeblack@google.com// 10113521Sgabeblack@google.com// DMI hint optimization: 10213521Sgabeblack@google.com// 10313521Sgabeblack@google.com// Initiators may use the DMI hint in the tlm_generic_payload to avoid 10413521Sgabeblack@google.com// unnecessary DMI attempts. The recommended sequence of interface 10513521Sgabeblack@google.com// method calls would be: 10613521Sgabeblack@google.com// 10713521Sgabeblack@google.com// - The initiator first tries to check if it has a valid DMI region for the 10813521Sgabeblack@google.com// address that it wants to access next. 10913521Sgabeblack@google.com// - If not, it performs a normal transaction. 11013521Sgabeblack@google.com// - If the DMI hint in this transaction is true, the initiator can try and 11113521Sgabeblack@google.com// get the DMI region. 11213521Sgabeblack@google.com// 11313521Sgabeblack@google.com// Note that the DMI hint optimization is completely optional and every 11413521Sgabeblack@google.com// initiator model is free to ignore the DMI hint. However, a target is 11513521Sgabeblack@google.com// required to set the DMI hint to true if a DMI request on the given address 11613521Sgabeblack@google.com// with the given transaction type (read or write) would have succeeded. 11713521Sgabeblack@google.com 11813521Sgabeblack@google.comtemplate <typename TRANS=tlm_generic_payload> 11913521Sgabeblack@google.comclass tlm_fw_direct_mem_if : public virtual sc_core::sc_interface 12013521Sgabeblack@google.com{ 12113521Sgabeblack@google.com public: 12213521Sgabeblack@google.com virtual bool get_direct_mem_ptr(TRANS &trans, tlm_dmi &dmi_data) = 0; 12313521Sgabeblack@google.com}; 12413521Sgabeblack@google.com 12513521Sgabeblack@google.com// The semantics of the backwards call is as follows: 12613521Sgabeblack@google.com// 12713521Sgabeblack@google.com// - An interconnect component or a target is required to invalidate all 12813521Sgabeblack@google.com// affected DMI regions whenever any change in the regions take place. 12913521Sgabeblack@google.com// The exact rule is that a component must invalidate all those DMI regions 13013521Sgabeblack@google.com// that it already reported, if it would answer the same DMI request 13113521Sgabeblack@google.com// with any member of the tlm_dmi data structure set differently. 13213521Sgabeblack@google.com// - An interconnect component must forward the invalidate_direct_mem_ptr call 13313521Sgabeblack@google.com// to all initiators that could potentially have a DMI pointer to the region 13413521Sgabeblack@google.com// specified in the method arguments. A safe implementation is to call 13513521Sgabeblack@google.com// every attached initiator. 13613521Sgabeblack@google.com// - An interconnect component must transform the address region of an 13713521Sgabeblack@google.com// incoming invalidate_direct_mem_ptr to the corresponding address space 13813521Sgabeblack@google.com// for the initiators. Basically, this is the same address transformation 13913521Sgabeblack@google.com// that the interconnect does on the DMI ranges on the forward direction. 14013521Sgabeblack@google.com// - Each initiator must check if it has a pointer to the given region and 14113521Sgabeblack@google.com// throw this away. It is recommended that the initiator throws away all DMI 14213521Sgabeblack@google.com// regions that have any overlap with the given regions, but this is not a 14313521Sgabeblack@google.com// hard requirement. 14413521Sgabeblack@google.com// 14513521Sgabeblack@google.com// - A full DMI pointer invalidation, e.g. for a bus remap can be signaled 14613521Sgabeblack@google.com// by setting the range: 0x0 - 0xffffffffffffffffull = (sc_dt::uint64)-1 14713521Sgabeblack@google.com// - An initiator must throw away all DMI pointers in this case. 14813521Sgabeblack@google.com// 14913521Sgabeblack@google.com// - Under no circumstances a model is allowed to call the get_direct_mem_ptr 15013521Sgabeblack@google.com// from within the invalidate_direct_mem_ptr method, directly or indirectly. 15113521Sgabeblack@google.com// 15213521Sgabeblack@google.comclass tlm_bw_direct_mem_if : public virtual sc_core::sc_interface 15313521Sgabeblack@google.com{ 15413521Sgabeblack@google.com public: 15513521Sgabeblack@google.com virtual void invalidate_direct_mem_ptr(sc_dt::uint64 start_range, 15613521Sgabeblack@google.com sc_dt::uint64 end_range) = 0; 15713521Sgabeblack@google.com}; 15813521Sgabeblack@google.com 15913521Sgabeblack@google.com///////////////////////////////////////////////////////////////////// 16013521Sgabeblack@google.com// debug interface for memory access 16113521Sgabeblack@google.com///////////////////////////////////////////////////////////////////// 16213521Sgabeblack@google.com// 16313521Sgabeblack@google.com// This interface can be used to gain access to a targets memory or registers 16413521Sgabeblack@google.com// in a non-intrusive manner. No side effects, waits or event notifications 16513521Sgabeblack@google.com// must happen in the course of the method. 16613521Sgabeblack@google.com// 16713521Sgabeblack@google.com// Semantics: 16813521Sgabeblack@google.com// - The initiator calls the transport_dbg method with transaction 'trans' as 16913521Sgabeblack@google.com// argument. The commonly used parts of trans for debug are: 17013521Sgabeblack@google.com// . address: The start address that it wants to peek or poke. 17113521Sgabeblack@google.com// . length: The number of bytes that it requests to read or write. 17213521Sgabeblack@google.com// . command: Indicates a read or write access. 17313521Sgabeblack@google.com// . data: A pointer to the initiator-allocated data buffer, which must 17413521Sgabeblack@google.com// be at least num_bytes large. The data is always organized in 17513521Sgabeblack@google.com// the endianness of the machine. 17613521Sgabeblack@google.com// . extensions: Any extension that could affect the transaction. 17713521Sgabeblack@google.com// - The interconnect, if any, will decode the address and forward the call to 17813521Sgabeblack@google.com// the appropriate target. 17913521Sgabeblack@google.com// - The target must return the number of successfully transmitted bytes, where 18013521Sgabeblack@google.com// this number must be <= num_bytes. Thus, a target can safely return 0 if it 18113521Sgabeblack@google.com// does not support debug transactions. 18213521Sgabeblack@google.com// 18313521Sgabeblack@google.comtemplate <typename TRANS=tlm_generic_payload> 18413521Sgabeblack@google.comclass tlm_transport_dbg_if : public virtual sc_core::sc_interface 18513521Sgabeblack@google.com{ 18613521Sgabeblack@google.com public: 18713521Sgabeblack@google.com // The return value of defines the number of bytes successfully 18813521Sgabeblack@google.com // transferred. 18913521Sgabeblack@google.com virtual unsigned int transport_dbg(TRANS &trans) = 0; 19013521Sgabeblack@google.com}; 19113521Sgabeblack@google.com 19213521Sgabeblack@google.com//////////////////////////////////////////////////////////////////////////// 19313521Sgabeblack@google.com// Combined interfaces 19413521Sgabeblack@google.com//////////////////////////////////////////////////////////////////////////// 19513521Sgabeblack@google.com 19613521Sgabeblack@google.comstruct tlm_base_protocol_types 19713521Sgabeblack@google.com{ 19813521Sgabeblack@google.com typedef tlm_generic_payload tlm_payload_type; 19913521Sgabeblack@google.com typedef tlm_phase tlm_phase_type; 20013521Sgabeblack@google.com}; 20113521Sgabeblack@google.com 20213521Sgabeblack@google.com// The forward interface: 20313521Sgabeblack@google.comtemplate <typename TYPES=tlm_base_protocol_types> 20413521Sgabeblack@google.comclass tlm_fw_transport_if : 20513521Sgabeblack@google.com public virtual tlm_fw_nonblocking_transport_if< 20613521Sgabeblack@google.com typename TYPES::tlm_payload_type, typename TYPES::tlm_phase_type>, 20713521Sgabeblack@google.com public virtual tlm_blocking_transport_if<typename TYPES::tlm_payload_type>, 20813521Sgabeblack@google.com public virtual tlm_fw_direct_mem_if<typename TYPES::tlm_payload_type>, 20913521Sgabeblack@google.com public virtual tlm_transport_dbg_if<typename TYPES::tlm_payload_type> 21013521Sgabeblack@google.com{}; 21113521Sgabeblack@google.com 21213521Sgabeblack@google.com// The backward interface: 21313521Sgabeblack@google.comtemplate <typename TYPES=tlm_base_protocol_types> 21413521Sgabeblack@google.comclass tlm_bw_transport_if : 21513521Sgabeblack@google.com public virtual tlm_bw_nonblocking_transport_if< 21613521Sgabeblack@google.com typename TYPES::tlm_payload_type, typename TYPES::tlm_phase_type>, 21713521Sgabeblack@google.com public virtual tlm_bw_direct_mem_if 21813521Sgabeblack@google.com{}; 21913521Sgabeblack@google.com 22013521Sgabeblack@google.com} // namespace tlm 22113521Sgabeblack@google.com 22213521Sgabeblack@google.com#endif /* __SYSTEMC_EXT_TLM_CORE_2_INTERFACES_FW_BW_IFS_HH__ */ 223