gem5  v21.1.0.2
fw_bw_ifs.hh
Go to the documentation of this file.
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 __SYSTEMC_EXT_TLM_CORE_2_INTERFACES_FW_BW_IFS_HH__
21 #define __SYSTEMC_EXT_TLM_CORE_2_INTERFACES_FW_BW_IFS_HH__
22 
23 #include "../../../core/sc_interface.hh"
24 #include "../../../core/sc_time.hh"
25 #include "../generic_payload/generic_payload.hh"
26 #include "dmi.hh"
27 
28 namespace tlm
29 {
30 
32 
34 // Basic interfaces
36 template <typename TRANS=tlm_generic_payload, typename PHASE=tlm_phase>
37 class tlm_fw_nonblocking_transport_if : public virtual sc_core::sc_interface
38 {
39  public:
40  virtual tlm_sync_enum nb_transport_fw(TRANS &trans, PHASE &phase,
41  sc_core::sc_time& t) = 0;
42 };
43 
44 template <typename TRANS=tlm_generic_payload, typename PHASE=tlm_phase>
45 class tlm_bw_nonblocking_transport_if : public virtual sc_core::sc_interface
46 {
47  public:
48  virtual tlm_sync_enum nb_transport_bw(TRANS &trans, 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 {
55  public:
56  virtual void b_transport(TRANS &trans, sc_core::sc_time &t) = 0;
57 };
58 
60 // DMI interfaces for getting and invalidating DMI pointers:
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, tlm_dmi &dmi_data) = 0;
123 };
124 
125 // The semantics of the backwards call is as follows:
126 //
127 // - An interconnect component or a target is required to invalidate all
128 // affected DMI regions whenever any change in the regions take place.
129 // The exact rule is that a component must invalidate all those DMI regions
130 // that it already reported, if it would answer the same DMI request
131 // with any member of the tlm_dmi data structure set differently.
132 // - An interconnect component must forward the invalidate_direct_mem_ptr call
133 // to all initiators that could potentially have a DMI pointer to the region
134 // specified in the method arguments. A safe implementation is to call
135 // every attached initiator.
136 // - An interconnect component must transform the address region of an
137 // incoming invalidate_direct_mem_ptr to the corresponding address space
138 // for the initiators. Basically, this is the same address transformation
139 // that the interconnect does on the DMI ranges on the forward direction.
140 // - Each initiator must check if it has a pointer to the given region and
141 // throw this away. It is recommended that the initiator throws away all DMI
142 // regions that have any overlap with the given regions, but this is not a
143 // hard requirement.
144 //
145 // - A full DMI pointer invalidation, e.g. for a bus remap can be signaled
146 // by setting the range: 0x0 - 0xffffffffffffffffull = (sc_dt::uint64)-1
147 // - An initiator must throw away all DMI pointers in this case.
148 //
149 // - Under no circumstances a model is allowed to call the get_direct_mem_ptr
150 // from within the invalidate_direct_mem_ptr method, directly or indirectly.
151 //
152 class tlm_bw_direct_mem_if : public virtual sc_core::sc_interface
153 {
154  public:
155  virtual void invalidate_direct_mem_ptr(sc_dt::uint64 start_range,
156  sc_dt::uint64 end_range) = 0;
157 };
158 
160 // debug interface for memory access
162 //
163 // This interface can be used to gain access to a targets memory or registers
164 // in a non-intrusive manner. No side effects, waits or event notifications
165 // must happen in the course of the method.
166 //
167 // Semantics:
168 // - The initiator calls the transport_dbg method with transaction 'trans' as
169 // argument. The commonly used parts of trans for debug are:
170 // . address: The start address that it wants to peek or poke.
171 // . length: The number of bytes that it requests to read or write.
172 // . command: Indicates a read or write access.
173 // . data: A pointer to the initiator-allocated data buffer, which must
174 // be at least num_bytes large. The data is always organized in
175 // the endianness of the machine.
176 // . extensions: Any extension that could affect the transaction.
177 // - The interconnect, if any, will decode the address and forward the call to
178 // the appropriate target.
179 // - The target must return the number of successfully transmitted bytes, where
180 // this number must be <= num_bytes. Thus, a target can safely return 0 if it
181 // does not support debug transactions.
182 //
183 template <typename TRANS=tlm_generic_payload>
184 class tlm_transport_dbg_if : public virtual sc_core::sc_interface
185 {
186  public:
187  // The return value of defines the number of bytes successfully
188  // transferred.
189  virtual unsigned int transport_dbg(TRANS &trans) = 0;
190 };
191 
193 // Combined interfaces
195 
197 {
198  typedef tlm_generic_payload tlm_payload_type;
199  typedef tlm_phase tlm_phase_type;
200 };
201 
202 // The forward interface:
203 template <typename TYPES=tlm_base_protocol_types>
204 class tlm_fw_transport_if :
205  public virtual tlm_fw_nonblocking_transport_if<
206  typename TYPES::tlm_payload_type, typename TYPES::tlm_phase_type>,
210 {};
211 
212 // The backward interface:
213 template <typename TYPES=tlm_base_protocol_types>
214 class tlm_bw_transport_if :
216  typename TYPES::tlm_payload_type, typename TYPES::tlm_phase_type>,
217  public virtual tlm_bw_direct_mem_if
218 {};
219 
220 } // namespace tlm
221 
222 #endif /* __SYSTEMC_EXT_TLM_CORE_2_INTERFACES_FW_BW_IFS_HH__ */
tlm::tlm_bw_transport_if
Definition: fw_bw_ifs.hh:231
tlm::tlm_bw_direct_mem_if
Definition: fw_bw_ifs.hh:169
tlm::tlm_phase
Definition: phase.hh:47
tlm::TLM_COMPLETED
@ TLM_COMPLETED
Definition: fw_bw_ifs.hh:65
tlm::tlm_dmi
Definition: dmi.hh:46
tlm::TLM_UPDATED
@ TLM_UPDATED
Definition: fw_bw_ifs.hh:65
sc_core::sc_interface
Definition: sc_interface.hh:37
tlm::tlm_fw_transport_if
Definition: fw_bw_ifs.hh:221
sc_dt::uint64
uint64_t uint64
Definition: sc_nbdefs.hh:206
sc_core::sc_time
Definition: sc_time.hh:49
gem5::ArmISA::t
Bitfield< 5 > t
Definition: misc_types.hh:70
tlm
Definition: analysis_fifo.hh:27
tlm::tlm_transport_dbg_if
Definition: fw_bw_ifs.hh:201
tlm::tlm_generic_payload
Definition: gp.hh:133
tlm::tlm_base_protocol_types
Definition: fw_bw_ifs.hh:213
tlm::tlm_bw_nonblocking_transport_if
Definition: fw_bw_ifs.hh:62
tlm::tlm_sync_enum
tlm_sync_enum
Definition: fw_bw_ifs.hh:48
tlm::tlm_blocking_transport_if
Definition: fw_bw_ifs.hh:70
tlm::tlm_fw_direct_mem_if
Definition: fw_bw_ifs.hh:136
dmi.hh
tlm::tlm_fw_nonblocking_transport_if
Definition: fw_bw_ifs.hh:54
tlm::TLM_ACCEPTED
@ TLM_ACCEPTED
Definition: fw_bw_ifs.hh:65

Generated on Tue Sep 21 2021 12:25:56 for gem5 by doxygen 1.8.17