C:/ESLX/projects/TLMWG/tlm2/include/tlm/tlm_h/tlm_trans/tlm_2_interfaces/tlm_fw_bw_ifs.h

Go to the documentation of this file.
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__ */

Generated on Thu Jun 5 17:43:03 2008 for TLM 2 by  doxygen 1.5.3