00001 /***************************************************************************** 00002 00003 The following code is derived, directly or indirectly, from the SystemC 00004 source code Copyright (c) 1996-2008 by all Contributors. 00005 All Rights reserved. 00006 00007 The contents of this file are subject to the restrictions and limitations 00008 set forth in the SystemC Open Source License Version 3.0 (the "License"); 00009 You may not use this file except in compliance with such restrictions and 00010 limitations. You may obtain instructions on how to receive a copy of the 00011 License at http://www.systemc.org/. Software distributed by Contributors 00012 under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF 00013 ANY KIND, either express or implied. See the License for the specific 00014 language governing rights and limitations under the License. 00015 00016 *****************************************************************************/ 00017 00018 #ifndef __TLM_FW_BW_IFS_H__ 00019 #define __TLM_FW_BW_IFS_H__ 00020 00021 #include <systemc> 00022 #include "tlm_h/tlm_trans/tlm_generic_payload/tlm_generic_payload.h" 00023 #include "tlm_h/tlm_trans/tlm_generic_payload/tlm_phase.h" 00024 00025 namespace tlm { 00026 00027 enum tlm_sync_enum { TLM_ACCEPTED, TLM_UPDATED, TLM_COMPLETED }; 00028 00030 // Basic interfaces 00032 template <typename TRANS = tlm_generic_payload, 00033 typename PHASE = tlm_phase> 00034 class tlm_fw_nonblocking_transport_if : public virtual sc_core::sc_interface { 00035 public: 00036 virtual tlm_sync_enum nb_transport_fw(TRANS& trans, 00037 PHASE& phase, 00038 sc_core::sc_time& t) = 0; 00039 }; 00040 00041 template <typename TRANS = tlm_generic_payload, 00042 typename PHASE = tlm_phase> 00043 class tlm_bw_nonblocking_transport_if : public virtual sc_core::sc_interface { 00044 public: 00045 virtual tlm_sync_enum nb_transport_bw(TRANS& trans, 00046 PHASE& phase, 00047 sc_core::sc_time& t) = 0; 00048 }; 00049 00050 template <typename TRANS = tlm_generic_payload> 00051 class tlm_blocking_transport_if : public virtual sc_core::sc_interface { 00052 public: 00053 virtual void b_transport(TRANS& trans, 00054 sc_core::sc_time& t) = 0; 00055 }; 00056 00058 // DMI interfaces for getting and invalidating DMI pointers: 00060 00061 // The semantics of the forward interface are as follows: 00062 // 00063 // - An initiator that wants to get direct access to a target's memory region 00064 // can call the get_direct_mem_ptr method with the 'trans' parameter set to 00065 // the address that it wants to gain access to. It sets the trans.m_command 00066 // to specify if the initiator intended use (read or write) 00067 // to the target's DMI region. The initiator is responsible for calling the 00068 // method with a freshly initialized tlm_dmi object either by using a newly 00069 // constructed object, or by calling an existing object's init() method. 00070 // - Although a reference to a complete 'TRANS' type is passed to the get_ 00071 // direct_mem_ptr call, only the address command, and extension fields are of 00072 // interest in most cases. 00073 // - Read and write ranges are not necessarily identical. If they are, a target 00074 // can specify that the range is valid for all accesses with the tlm_data 00075 // m_type attribute in the. 00076 // - The interconnect, if any, needs to decode the address and forward the 00077 // call to the corresponding target. It needs to handle the address exactly 00078 // as the target would expect on a transaction call, e.g. mask the address 00079 // according to the target's address width. 00080 // - If the target supports DMI access for the given address, it sets the 00081 // data fields in the DMI struct and returns true. 00082 // - If a target does not support DMI access it needs to return false. 00083 // The target can either set the correct address range in the DMI struct 00084 // to indicate the memory region where DMI is disallowed, or it can specify 00085 // the complete address range if it doesn't know it's memory range. In this 00086 // case the interconnect is responsible for clipping the address range to 00087 // the correct range that the target serves. 00088 // - The interconnect must always translate the addresses to the initiator's 00089 // address space. This must be the inverse operation of what the 00090 // interconnect needed to do when forwarding the call. In case the 00091 // component wants to change any member of the tlm_dmi object, e.g. for 00092 // its own latency to the target's latency, it must only do so *after* the 00093 // target has been called. The target is always allowed to overwrite all 00094 // values in the tlm_dmi object. 00095 // - In case the slave returned with an invalid region the bus/interconnect 00096 // must fill in the complete address region for the particular slave in the 00097 // DMI data structure. 00098 // 00099 // DMI hint optimization: 00100 // 00101 // Initiators may use the DMI hint in the tlm_generic_payload to avoid 00102 // unnecessary DMI attempts. The recommended sequence of interface 00103 // method calls would be: 00104 // 00105 // - The initiator first tries to check if it has a valid DMI region for the 00106 // address that it wants to access next. 00107 // - If not, it performs a normal transaction. 00108 // - If the DMI hint in this transaction is true, the initiator can try and 00109 // get the DMI region. 00110 // 00111 // Note that the DMI hint optimization is completely optional and every 00112 // initiator model is free to ignore the DMI hint. However, a target is 00113 // required to set the DMI hint to true if a DMI request on the given address 00114 // with the given transaction type (read or write) would have succeeded. 00115 00116 template <typename TRANS = tlm_generic_payload> 00117 class tlm_fw_direct_mem_if : public virtual sc_core::sc_interface 00118 { 00119 public: 00120 virtual bool get_direct_mem_ptr(TRANS& trans, 00121 tlm_dmi& dmi_data) = 0; 00122 }; 00123 00124 // The semantics of the backwards call is as follows: 00125 // 00126 // - An interconnect component or a target is required to invalidate all 00127 // affected DMI regions whenever any change in the regions take place. 00128 // The exact rule is that a component must invalidate all those DMI regions 00129 // that it already reported, if it would answer the same DMI request 00130 // with any member of the tlm_dmi data structure set differently. 00131 // - An interconnect component must forward the invalidate_direct_mem_ptr call 00132 // to all initiators that could potentially have a DMI pointer to the region 00133 // specified in the method arguments. A safe implementation is to call 00134 // every attached initiator. 00135 // - An interconnect component must transform the address region of an 00136 // incoming invalidate_direct_mem_ptr to the corresponding address space 00137 // for the initiators. Basically, this is the same address transformation 00138 // that the interconnect does on the DMI ranges on the forward direction. 00139 // - Each initiator must check if it has a pointer to the given region and 00140 // throw this away. It is recommended that the initiator throws away all DMI 00141 // regions that have any overlap with the given regions, but this is not a 00142 // hard requirement. 00143 // 00144 // - A full DMI pointer invalidation, e.g. for a bus remap can be signaled 00145 // by setting the range: 0x0 - 0xffffffffffffffffull = (sc_dt::uint64)-1 00146 // - An initiator must throw away all DMI pointers in this case. 00147 // 00148 // - Under no circumstances a model is allowed to call the get_direct_mem_ptr 00149 // from within the invalidate_direct_mem_ptr method, directly or indirectly. 00150 // 00151 class tlm_bw_direct_mem_if : public virtual sc_core::sc_interface 00152 { 00153 public: 00154 virtual void invalidate_direct_mem_ptr(sc_dt::uint64 start_range, 00155 sc_dt::uint64 end_range) = 0; 00156 }; 00157 00159 // debug interface for memory access 00161 // 00162 // This interface can be used to gain access to a targets memory or registers 00163 // in a non-intrusive manner. No side effects, waits or event notifications 00164 // must happen in the course of the method. 00165 // 00166 // Semantics: 00167 // - The initiator calls the transport_dbg method with transaction 'trans' as 00168 // argument. The commonly used parts of trans for debug are: 00169 // . address: The start address that it wants to peek or poke. 00170 // . length: The number of bytes that it requests to read or write. 00171 // . command: Indicates a read or write access. 00172 // . data: A pointer to the initiator-allocated data buffer, which must 00173 // be at least num_bytes large. The data is always organized in 00174 // the endianness of the machine. 00175 // . extensions: Any extension that could affect the transaction. 00176 // - The interconnect, if any, will decode the address and forward the call to 00177 // the appropriate target. 00178 // - The target must return the number of successfully transmitted bytes, where 00179 // this number must be <= num_bytes. Thus, a target can safely return 0 if it 00180 // does not support debug transactions. 00181 // 00182 template <typename TRANS = tlm_generic_payload> 00183 class tlm_transport_dbg_if : public virtual sc_core::sc_interface 00184 { 00185 public: 00186 // The return value of defines the number of bytes successfully 00187 // transferred. 00188 virtual unsigned int transport_dbg(TRANS& trans) = 0; 00189 }; 00190 00192 // Combined interfaces 00194 00195 struct tlm_base_protocol_types 00196 { 00197 typedef tlm_generic_payload tlm_payload_type; 00198 typedef tlm_phase tlm_phase_type; 00199 }; 00200 00201 // The forward interface: 00202 template <typename TYPES = tlm_base_protocol_types> 00203 class tlm_fw_transport_if 00204 : public virtual tlm_fw_nonblocking_transport_if<typename TYPES::tlm_payload_type, 00205 typename TYPES::tlm_phase_type> 00206 , public virtual tlm_blocking_transport_if<typename TYPES::tlm_payload_type> 00207 , public virtual tlm_fw_direct_mem_if<typename TYPES::tlm_payload_type> 00208 , public virtual tlm_transport_dbg_if<typename TYPES::tlm_payload_type> 00209 {}; 00210 00211 // The backward interface: 00212 template <typename TYPES = tlm_base_protocol_types> 00213 class tlm_bw_transport_if 00214 : public virtual tlm_bw_nonblocking_transport_if<typename TYPES::tlm_payload_type, 00215 typename TYPES::tlm_phase_type> 00216 , public virtual tlm_bw_direct_mem_if 00217 {}; 00218 00219 } // namespace tlm 00220 00221 #endif /* __TLM_FW_BW_IFS_H__ */