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#ifndef __SYSTEMC_EXT_TLM_UTILS_MULTI_PASSTHROUGH_INITIATOR_SOCKET_H__
20#define __SYSTEMC_EXT_TLM_UTILS_MULTI_PASSTHROUGH_INITIATOR_SOCKET_H__
21
22#include "tlm_utils/multi_socket_bases.h"
23
24namespace tlm_utils
25{
26
27/*
28This class implements a trivial multi initiator socket.
29The triviality refers to the fact that the socket does not
30do blocking to non-blocking or non-blocking to blocking conversions.
31
32It allows to connect multiple targets to this socket.
33The user has to register callbacks for the bw interface methods
34he likes to use. The callbacks are basically equal to the bw interface
35methods but carry an additional integer that indicates to which
36index of this socket the calling target is connected.
37*/
38template <typename MODULE, unsigned int BUSWIDTH=32,
39          typename TYPES=tlm::tlm_base_protocol_types, unsigned int N=0,
40          sc_core::sc_port_policy POL=sc_core::SC_ONE_OR_MORE_BOUND>
41class multi_passthrough_initiator_socket :
42    public multi_init_base< BUSWIDTH, TYPES, N, POL>
43{
44  public:
45
46    //typedefs
47    //  tlm 2.0 types for nb_transport
48    typedef typename TYPES::tlm_payload_type transaction_type;
49    typedef typename TYPES::tlm_phase_type phase_type;
50    typedef tlm::tlm_sync_enum sync_enum_type;
51
52    //  typedefs to keep the fn ptr notations short
53    typedef sync_enum_type (MODULE::*nb_cb)(
54            int, transaction_type &, phase_type &, sc_core::sc_time &);
55    typedef void (MODULE::*dmi_cb)(int, sc_dt::uint64, sc_dt::uint64);
56
57    typedef multi_init_base<BUSWIDTH, TYPES, N, POL> base_type;
58
59    typedef typename base_type::base_target_socket_type
60        base_target_socket_type;
61
62    static const char *
63    default_name()
64    {
65        return sc_core::sc_gen_unique_name(
66                "multi_passthrough_initiator_socket");
67    }
68
69    explicit multi_passthrough_initiator_socket(
70            const char *name=default_name()) :
71        base_type(name), m_hierarch_bind(nullptr), m_beoe_disabled(false),
72        m_dummy(this, 42)
73    {}
74
75    ~multi_passthrough_initiator_socket()
76    {
77        // Clean up everything allocated by 'new'.
78        for (unsigned int i = 0; i < m_binders.size(); i++)
79            delete m_binders[i];
80    }
81
82    // Register callback for nb transport of bw interface.
83    void
84    register_nb_transport_bw(MODULE *mod, sync_enum_type (MODULE::*cb)(
85                int, transaction_type &, phase_type &, sc_core::sc_time &))
86    {
87        // Warn if there already is a callback.
88        if (m_nb_f.is_valid()) {
89            display_warning("NBTransport_bw callback already registered.");
90            return;
91        }
92
93        // Set the functor.
94        m_nb_f.set_function(mod, cb);
95    }
96
97    // Register callback for dmi function of bw interface.
98    void
99    register_invalidate_direct_mem_ptr(MODULE *mod, void (MODULE::*cb)(
100                int, sc_dt::uint64, sc_dt::uint64))
101    {
102        // Warn if there already is a callback.
103        if (m_dmi_f.is_valid()) {
104            display_warning("InvalidateDMI callback already registered.");
105            return;
106        }
107
108        // Set the functor.
109        m_dmi_f.set_function(mod, cb);
110    }
111
112    // Override virtual functions of the tlm_initiator_socket:
113    // this function is called whenever an sc_port (as part of a target socket)
114    // wants to bind to the export of the underlying tlm_initiator_socket.
115    // At this time a callback binder is created an returned to the sc_port
116    // of the target socket, so that it binds to the callback binder.
117    virtual tlm::tlm_bw_transport_if<TYPES> &
118    get_base_interface()
119    {
120        m_binders.push_back(
121                new callback_binder_bw<TYPES>(this, m_binders.size()));
122        return *m_binders[m_binders.size() - 1];
123    }
124
125    // Const overload not allowed for multi-sockets.
126    virtual const tlm::tlm_bw_transport_if<TYPES> &
127    get_base_interface() const
128    {
129        display_error("'get_base_interface()'"
130                " const not allowed for multi-sockets.");
131        return base_type::get_base_interface();
132    }
133
134    // Override virtual functions of the tlm_initiator_socket:
135    // This function is called whenever an sc_export (as part of a initiator
136    // socket) wants to bind to the export of the underlying
137    // tlm_initiator_socket, i.e. a hierarchical bind takes place.
138    virtual sc_core::sc_export<tlm::tlm_bw_transport_if<TYPES>> &
139    get_base_export()
140    {
141        if (!m_beoe_disabled) { // We are not bound hierarchically.
142            // So we bind the dummy to avoid a SystemC error.
143            base_type::m_export.bind(m_dummy);
144        }
145        // and then return our own export so that the hierarchical
146        // binding is set up properly.
147        return base_type::get_base_export();
148    }
149
150    virtual const sc_core::sc_export<tlm::tlm_bw_transport_if<TYPES>> &
151    get_base_export() const
152    {
153        return base_type::get_base_export();
154    }
155
156    // Bind against a target socket.
157    virtual void
158    bind(base_target_socket_type &s)
159    {
160        // Error if this socket is already bound hierarchically.
161        if (m_hierarch_bind) {
162            display_error("Already hierarchically bound.");
163            return;
164        }
165
166        // Satisfy systemC, leads to a call to get_base_interface().
167        base_type::bind(s);
168
169        // Try to cast the target socket into a fw interface.
170        sc_core::sc_export<tlm::tlm_fw_transport_if<TYPES>> *p_ex_s =
171            dynamic_cast<sc_core::sc_export<
172                tlm::tlm_fw_transport_if<TYPES>> *>(&s);
173        if (!p_ex_s) {
174            display_error("Multi socket not bound to tlm_socket.");
175            return;
176        }
177
178        // Try a cast into a multi sockets.
179        multi_to_multi_bind_base<TYPES> *test =
180            dynamic_cast<multi_to_multi_bind_base<TYPES> *>(p_ex_s);
181        if (test) {
182            // Did we just do a multi-multi bind??
183            // If that is the case the multi target socket must have just
184            // created a callback binder which we want to get from it.
185            // Moreover, we also just created one, which we will pass to it.
186            m_sockets.push_back(test->get_last_binder(
187                        m_binders[m_binders.size() - 1]));
188        } else { // If not just bind normally,
189            sc_core::sc_export<tlm::tlm_fw_transport_if<TYPES>> &ex_s =
190                *p_ex_s;
191            // Store the interface we are bound against.
192            m_sockets.push_back(&((tlm::tlm_fw_transport_if<TYPES> &)ex_s));
193        }
194    }
195
196    // Operator notation for direct bind.
197    void operator() (base_target_socket_type &s) { bind(s); }
198
199    // SystemC standard callback before end of elaboration.
200    void
201    before_end_of_elaboration()
202    {
203        // If our export hasn't been bound yet (due to a hierarch binding)
204        // we bind it now to avoid a SystemC error. We must do that because it
205        // is legal not to register a callback on this socket as the user
206        // might only use b_transport.
207        if (!base_type::m_export.get_interface()) {
208            base_type::m_export.bind(m_dummy);
209        }
210
211        // 'break' here if the socket was told not to do callback binding.
212        if (m_beoe_disabled)
213            return;
214
215        // Get the callback binders of the top of the hierachical bind chain.
216        // NOTE: this could be the same socket if there is no hierachical bind.
217        std::vector<callback_binder_bw<TYPES> *> &binders =
218            get_hierarch_bind()->get_binders();
219
220        // Get the interfaces bound to the top of the hierachical bind chain.
221        // NOTE: this could be the same socket if there is no hierachical bind.
222        m_used_sockets = get_hierarch_bind()->get_sockets();
223
224        // Register the callbacks of this socket with the callback binders
225        // we just got from the top of the hierachical bind chain.
226        for (unsigned int i = 0; i < binders.size(); i++) {
227            binders[i]->set_callbacks(m_nb_f, m_dmi_f);
228        }
229    }
230
231    //
232    // Bind multi initiator socket to multi initiator socket (hierarchical
233    // bind).
234    //
235    virtual void
236    bind(base_type& s)
237    {
238        if (m_binders.size()) {
239            // A multi socket is either bound hierarchically or directly.
240            display_error("Socket already directly bound.");
241            return;
242        }
243        if (m_hierarch_bind) {
244            display_warning("Socket already bound hierarchically. "
245                    "Bind attempt ignored.");
246            return;
247        }
248
249        // Remember to which socket we are hierarchically bound and disable it,
250        // so that it won't try to register callbacks itself.
251        s.disable_cb_bind();
252        m_hierarch_bind = &s;
253        base_type::bind(s); // Satisfy SystemC.
254    }
255
256    // Operator notation for hierarchical bind.
257    void operator() (base_type &s) { bind(s); }
258
259    // Get access to sub port.
260    tlm::tlm_fw_transport_if<TYPES> *
261    operator [] (int i)
262    {
263        return m_used_sockets[i];
264    }
265
266    // Get the number of bound targets.
267    // NOTE: This is only valid at end of elaboration!
268    unsigned int size() { return get_hierarch_bind()->get_sockets().size(); }
269
270  protected:
271    using base_type::display_warning;
272    using base_type::display_error;
273
274    // Implementation of base class interface.
275    base_type *
276    get_hierarch_bind()
277    {
278        if (m_hierarch_bind)
279            return m_hierarch_bind->get_hierarch_bind();
280        else
281            return this;
282    }
283    void disable_cb_bind() { m_beoe_disabled = true; }
284    std::vector<callback_binder_bw<TYPES> *> &
285    get_binders()
286    {
287        return m_binders;
288    }
289    std::vector<tlm::tlm_fw_transport_if<TYPES> *> &
290    get_sockets()
291    {
292        return m_sockets;
293    }
294    // Vector of connected sockets.
295    std::vector<tlm::tlm_fw_transport_if<TYPES> *> m_sockets;
296    std::vector<tlm::tlm_fw_transport_if<TYPES> *> m_used_sockets;
297    // Vector of binders that convert untagged interface into tagged interface.
298    std::vector<callback_binder_bw<TYPES> *> m_binders;
299
300    base_type *m_hierarch_bind; // Pointer to hierarchical bound multi port.
301    // bool that remembers whether this socket shall bind callbacks or not.
302    bool m_beoe_disabled;
303    // A callback binder that is bound to the underlying export
304    // in case there was no real bind.
305    callback_binder_bw<TYPES> m_dummy;
306
307    //callbacks as functors
308    // (allows to pass the callback to another socket that does not know the
309    // type of the module that owns the callbacks).
310    typename callback_binder_bw<TYPES>::nb_func_type m_nb_f;
311    typename callback_binder_bw<TYPES>::dmi_func_type m_dmi_f;
312};
313
314template <typename MODULE, unsigned int BUSWIDTH=32,
315          typename TYPES=tlm::tlm_base_protocol_types, unsigned int N=0>
316class multi_passthrough_initiator_socket_optional :
317    public multi_passthrough_initiator_socket<
318        MODULE, BUSWIDTH, TYPES, N, sc_core::SC_ZERO_OR_MORE_BOUND>
319{
320    typedef multi_passthrough_initiator_socket<
321        MODULE, BUSWIDTH, TYPES, N, sc_core::SC_ZERO_OR_MORE_BOUND> socket_b;
322  public:
323    multi_passthrough_initiator_socket_optional() : socket_b() {}
324    explicit multi_passthrough_initiator_socket_optional(const char *name) :
325        socket_b(name)
326    {}
327};
328
329} // namespace tlm_utils
330
331#endif /* __SYSTEMC_EXT_TLM_UTILS_MULTI_PASSTHROUGH_INITIATOR_SOCKET_H__ */
332