TLM-2.0: include/tlm/tlm_h/tlm_2_interfaces/tlm_fw_bw_ifs.h Source File

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

# include/tlm/tlm_h/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_generic_payload/tlm_generic_payload.h"
    00023 #include "tlm_h/tlm_2_interfaces/tlm_dmi.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__ */