1 /***************************************************************************** 2 3 Licensed to Accellera Systems Initiative Inc. (Accellera) under one or 4 more contributor license agreements. See the NOTICE file distributed 5 with this work for additional information regarding copyright ownership. 6 Accellera licenses this file to you under the Apache License, Version 2.0 7 (the "License"); you may not use this file except in compliance with the 8 License. You may obtain a copy of the License at 9 10 http://www.apache.org/licenses/LICENSE-2.0 11 12 Unless required by applicable law or agreed to in writing, software 13 distributed under the License is distributed on an "AS IS" BASIS, 14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 15 implied. See the License for the specific language governing 16 permissions and limitations under the License. 17 18 *****************************************************************************/ 19 20 #ifndef __TLM_FW_BW_IFS_H__ 21 #define __TLM_FW_BW_IFS_H__ 22 23 #include <systemc> 24 #include "tlm_core/tlm_2/tlm_generic_payload/tlm_generic_payload.h" 25 #include "tlm_core/tlm_2/tlm_2_interfaces/tlm_dmi.h" 26 27 namespace tlm { 28 29 enum tlm_sync_enum { TLM_ACCEPTED, TLM_UPDATED, TLM_COMPLETED }; 30 31 //////////////////////////////////////////////////////////////////////////// 32 // Basic interfaces 33 //////////////////////////////////////////////////////////////////////////// 34 template <typename TRANS = tlm_generic_payload, 35 typename PHASE = tlm_phase> 36 class tlm_fw_nonblocking_transport_if : public virtual sc_core::sc_interface { 37 public: 38 virtual tlm_sync_enum nb_transport_fw(TRANS& trans, 39 PHASE& phase, 40 sc_core::sc_time& t) = 0; 41 }; 42 43 template <typename TRANS = tlm_generic_payload, 44 typename PHASE = tlm_phase> 45 class tlm_bw_nonblocking_transport_if : public virtual sc_core::sc_interface { 46 public: 47 virtual tlm_sync_enum nb_transport_bw(TRANS& trans, 48 PHASE& phase, 49 sc_core::sc_time& t) = 0; 50 }; 51 52 template <typename TRANS = tlm_generic_payload> 53 class tlm_blocking_transport_if : public virtual sc_core::sc_interface { 54 public: 55 virtual void b_transport(TRANS& trans, 56 sc_core::sc_time& t) = 0; 57 }; 58 59 ////////////////////////////////////////////////////////////////////////// 60 // DMI interfaces for getting and invalidating DMI pointers: 61 ////////////////////////////////////////////////////////////////////////// 62 63 // The semantics of the forward interface are as follows: 64 // 65 // - An initiator that wants to get direct access to a target's memory region 66 // can call the get_direct_mem_ptr method with the 'trans' parameter set to 67 // the address that it wants to gain access to. It sets the trans.m_command 68 // to specify if the initiator intended use (read or write) 69 // to the target's DMI region. The initiator is responsible for calling the 70 // method with a freshly initialized tlm_dmi object either by using a newly 71 // constructed object, or by calling an existing object's init() method. 72 // - Although a reference to a complete 'TRANS' type is passed to the get_ 73 // direct_mem_ptr call, only the address command, and extension fields are of 74 // interest in most cases. 75 // - Read and write ranges are not necessarily identical. If they are, a target 76 // can specify that the range is valid for all accesses with the tlm_data 77 // m_type attribute in the. 78 // - The interconnect, if any, needs to decode the address and forward the 79 // call to the corresponding target. It needs to handle the address exactly 80 // as the target would expect on a transaction call, e.g. mask the address 81 // according to the target's address width. 82 // - If the target supports DMI access for the given address, it sets the 83 // data fields in the DMI struct and returns true. 84 // - If a target does not support DMI access it needs to return false. 85 // The target can either set the correct address range in the DMI struct 86 // to indicate the memory region where DMI is disallowed, or it can specify 87 // the complete address range if it doesn't know it's memory range. In this 88 // case the interconnect is responsible for clipping the address range to 89 // the correct range that the target serves. 90 // - The interconnect must always translate the addresses to the initiator's 91 // address space. This must be the inverse operation of what the 92 // interconnect needed to do when forwarding the call. In case the 93 // component wants to change any member of the tlm_dmi object, e.g. for 94 // its own latency to the target's latency, it must only do so *after* the 95 // target has been called. The target is always allowed to overwrite all 96 // values in the tlm_dmi object. 97 // - In case the slave returned with an invalid region the bus/interconnect 98 // must fill in the complete address region for the particular slave in the 99 // DMI data structure. 100 // 101 // DMI hint optimization: 102 // 103 // Initiators may use the DMI hint in the tlm_generic_payload to avoid 104 // unnecessary DMI attempts. The recommended sequence of interface 105 // method calls would be: 106 // 107 // - The initiator first tries to check if it has a valid DMI region for the 108 // address that it wants to access next. 109 // - If not, it performs a normal transaction. 110 // - If the DMI hint in this transaction is true, the initiator can try and 111 // get the DMI region. 112 // 113 // Note that the DMI hint optimization is completely optional and every 114 // initiator model is free to ignore the DMI hint. However, a target is 115 // required to set the DMI hint to true if a DMI request on the given address 116 // with the given transaction type (read or write) would have succeeded. 117 118 template <typename TRANS = tlm_generic_payload> 119 class tlm_fw_direct_mem_if : public virtual sc_core::sc_interface 120 { 121 public: 122 virtual bool get_direct_mem_ptr(TRANS& trans, 123 tlm_dmi& dmi_data) = 0; 124 }; 125 126 // The semantics of the backwards call is as follows: 127 // 128 // - An interconnect component or a target is required to invalidate all 129 // affected DMI regions whenever any change in the regions take place. 130 // The exact rule is that a component must invalidate all those DMI regions 131 // that it already reported, if it would answer the same DMI request 132 // with any member of the tlm_dmi data structure set differently. 133 // - An interconnect component must forward the invalidate_direct_mem_ptr call 134 // to all initiators that could potentially have a DMI pointer to the region 135 // specified in the method arguments. A safe implementation is to call 136 // every attached initiator. 137 // - An interconnect component must transform the address region of an 138 // incoming invalidate_direct_mem_ptr to the corresponding address space 139 // for the initiators. Basically, this is the same address transformation 140 // that the interconnect does on the DMI ranges on the forward direction. 141 // - Each initiator must check if it has a pointer to the given region and 142 // throw this away. It is recommended that the initiator throws away all DMI 143 // regions that have any overlap with the given regions, but this is not a 144 // hard requirement. 145 // 146 // - A full DMI pointer invalidation, e.g. for a bus remap can be signaled 147 // by setting the range: 0x0 - 0xffffffffffffffffull = (sc_dt::uint64)-1 148 // - An initiator must throw away all DMI pointers in this case. 149 // 150 // - Under no circumstances a model is allowed to call the get_direct_mem_ptr 151 // from within the invalidate_direct_mem_ptr method, directly or indirectly. 152 // 153 class tlm_bw_direct_mem_if : public virtual sc_core::sc_interface 154 { 155 public: 156 virtual void invalidate_direct_mem_ptr(sc_dt::uint64 start_range, 157 sc_dt::uint64 end_range) = 0; 158 }; 159 160 ///////////////////////////////////////////////////////////////////// 161 // debug interface for memory access 162 ///////////////////////////////////////////////////////////////////// 163 // 164 // This interface can be used to gain access to a targets memory or registers 165 // in a non-intrusive manner. No side effects, waits or event notifications 166 // must happen in the course of the method. 167 // 168 // Semantics: 169 // - The initiator calls the transport_dbg method with transaction 'trans' as 170 // argument. The commonly used parts of trans for debug are: 171 // . address: The start address that it wants to peek or poke. 172 // . length: The number of bytes that it requests to read or write. 173 // . command: Indicates a read or write access. 174 // . data: A pointer to the initiator-allocated data buffer, which must 175 // be at least num_bytes large. The data is always organized in 176 // the endianness of the machine. 177 // . extensions: Any extension that could affect the transaction. 178 // - The interconnect, if any, will decode the address and forward the call to 179 // the appropriate target. 180 // - The target must return the number of successfully transmitted bytes, where 181 // this number must be <= num_bytes. Thus, a target can safely return 0 if it 182 // does not support debug transactions. 183 // 184 template <typename TRANS = tlm_generic_payload> 185 class tlm_transport_dbg_if : public virtual sc_core::sc_interface 186 { 187 public: 188 // The return value of defines the number of bytes successfully 189 // transferred. 190 virtual unsigned int transport_dbg(TRANS& trans) = 0; 191 }; 192 193 //////////////////////////////////////////////////////////////////////////// 194 // Combined interfaces 195 //////////////////////////////////////////////////////////////////////////// 196 197 struct tlm_base_protocol_types 198 { 199 typedef tlm_generic_payload tlm_payload_type; 200 typedef tlm_phase tlm_phase_type; 201 }; 202 203 // The forward interface: 204 template <typename TYPES = tlm_base_protocol_types> 205 class tlm_fw_transport_if 206 : public virtual tlm_fw_nonblocking_transport_if<typename TYPES::tlm_payload_type, 207 typename TYPES::tlm_phase_type> 208 , public virtual tlm_blocking_transport_if<typename TYPES::tlm_payload_type> 209 , public virtual tlm_fw_direct_mem_if<typename TYPES::tlm_payload_type> 210 , public virtual tlm_transport_dbg_if<typename TYPES::tlm_payload_type> 211 { 212 public: 213 typedef TYPES protocol_types; 214 }; 215 216 // The backward interface: 217 template <typename TYPES = tlm_base_protocol_types> 218 class tlm_bw_transport_if 219 : public virtual tlm_bw_nonblocking_transport_if<typename TYPES::tlm_payload_type, 220 typename TYPES::tlm_phase_type> 221 , public virtual tlm_bw_direct_mem_if 222 { 223 public: 224 typedef TYPES protocol_types; 225 }; 226 227 } // namespace tlm 228 229 #endif /* __TLM_FW_BW_IFS_H__ */ 230