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
28namespace tlm
29{
30
31enum tlm_sync_enum { TLM_ACCEPTED, TLM_UPDATED, TLM_COMPLETED };
32
33////////////////////////////////////////////////////////////////////////////
34// Basic interfaces
35////////////////////////////////////////////////////////////////////////////
36template <typename TRANS=tlm_generic_payload, typename PHASE=tlm_phase>
37class 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
44template <typename TRANS=tlm_generic_payload, typename PHASE=tlm_phase>
45class 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
52template <typename TRANS=tlm_generic_payload>
53class 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
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
118template <typename TRANS=tlm_generic_payload>
119class 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//
152class 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
159/////////////////////////////////////////////////////////////////////
160// debug interface for memory access
161/////////////////////////////////////////////////////////////////////
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//
183template <typename TRANS=tlm_generic_payload>
184class 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
192////////////////////////////////////////////////////////////////////////////
193// Combined interfaces
194////////////////////////////////////////////////////////////////////////////
195
196struct tlm_base_protocol_types
197{
198    typedef tlm_generic_payload tlm_payload_type;
199    typedef tlm_phase tlm_phase_type;
200};
201
202// The forward interface:
203template <typename TYPES=tlm_base_protocol_types>
204class tlm_fw_transport_if :
205    public virtual tlm_fw_nonblocking_transport_if<
206        typename TYPES::tlm_payload_type, typename TYPES::tlm_phase_type>,
207    public virtual tlm_blocking_transport_if<typename TYPES::tlm_payload_type>,
208    public virtual tlm_fw_direct_mem_if<typename TYPES::tlm_payload_type>,
209    public virtual tlm_transport_dbg_if<typename TYPES::tlm_payload_type>
210{};
211
212// The backward interface:
213template <typename TYPES=tlm_base_protocol_types>
214class tlm_bw_transport_if :
215    public virtual tlm_bw_nonblocking_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__ */
223