1/*
2 * Copyright (c) 2011-2015, 2017, 2019 ARM Limited
3 * All rights reserved
4 *
5 * The license below extends only to copyright in the software and shall
6 * not be construed as granting a license to any other intellectual
7 * property including but not limited to intellectual property relating
8 * to a hardware implementation of the functionality of the software
9 * licensed hereunder.  You may use the software subject to the license
10 * terms below provided that you ensure that this notice is replicated
11 * unmodified and in its entirety in all distributions of the software,
12 * modified or unmodified, in source code or in binary form.
13 *
14 * Copyright (c) 2002-2005 The Regents of The University of Michigan
15 * All rights reserved.
16 *
17 * Redistribution and use in source and binary forms, with or without
18 * modification, are permitted provided that the following conditions are
19 * met: redistributions of source code must retain the above copyright
20 * notice, this list of conditions and the following disclaimer;
21 * redistributions in binary form must reproduce the above copyright
22 * notice, this list of conditions and the following disclaimer in the
23 * documentation and/or other materials provided with the distribution;
24 * neither the name of the copyright holders nor the names of its
25 * contributors may be used to endorse or promote products derived from
26 * this software without specific prior written permission.
27 *
28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 *
40 * Authors: Ron Dreslinski
41 *          Ali Saidi
42 *          Andreas Hansson
43 *          William Wang
44 */
45
46/**
47 * @file
48 * Declaration of a coherent crossbar.
49 */
50
51#ifndef __MEM_COHERENT_XBAR_HH__
52#define __MEM_COHERENT_XBAR_HH__
53
54#include <unordered_map>
55#include <unordered_set>
56
57#include "mem/snoop_filter.hh"
58#include "mem/xbar.hh"
59#include "params/CoherentXBar.hh"
60
61/**
62 * A coherent crossbar connects a number of (potentially) snooping
63 * masters and slaves, and routes the request and response packets
64 * based on the address, and also forwards all requests to the
65 * snoopers and deals with the snoop responses.
66 *
67 * The coherent crossbar can be used as a template for modelling QPI,
68 * HyperTransport, ACE and coherent OCP buses, and is typically used
69 * for the L1-to-L2 buses and as the main system interconnect.  @sa
70 * \ref gem5MemorySystem "gem5 Memory System"
71 */
72class CoherentXBar : public BaseXBar
73{
74
75  protected:
76
77    /**
78     * Declare the layers of this crossbar, one vector for requests,
79     * one for responses, and one for snoop responses
80     */
81    std::vector<ReqLayer*> reqLayers;
82    std::vector<RespLayer*> respLayers;
83    std::vector<SnoopRespLayer*> snoopLayers;
84
85    /**
86     * Declaration of the coherent crossbar slave port type, one will
87     * be instantiated for each of the master ports connecting to the
88     * crossbar.
89     */
90    class CoherentXBarSlavePort : public QueuedSlavePort
91    {
92
93      private:
94
95        /** A reference to the crossbar to which this port belongs. */
96        CoherentXBar &xbar;
97
98        /** A normal packet queue used to store responses. */
99        RespPacketQueue queue;
100
101      public:
102
103        CoherentXBarSlavePort(const std::string &_name,
104                             CoherentXBar &_xbar, PortID _id)
105            : QueuedSlavePort(_name, &_xbar, queue, _id), xbar(_xbar),
106              queue(_xbar, *this)
107        { }
108
109      protected:
110
111        bool
112        recvTimingReq(PacketPtr pkt) override
113        {
114            return xbar.recvTimingReq(pkt, id);
115        }
116
117        bool
118        recvTimingSnoopResp(PacketPtr pkt) override
119        {
120            return xbar.recvTimingSnoopResp(pkt, id);
121        }
122
123        Tick
124        recvAtomic(PacketPtr pkt) override
125        {
126            return xbar.recvAtomicBackdoor(pkt, id);
127        }
128
129        Tick
130        recvAtomicBackdoor(PacketPtr pkt, MemBackdoorPtr &backdoor) override
131        {
132            return xbar.recvAtomicBackdoor(pkt, id, &backdoor);
133        }
134
135        void
136        recvFunctional(PacketPtr pkt) override
137        {
138            xbar.recvFunctional(pkt, id);
139        }
140
141        AddrRangeList
142        getAddrRanges() const override
143        {
144            return xbar.getAddrRanges();
145        }
146
147    };
148
149    /**
150     * Declaration of the coherent crossbar master port type, one will be
151     * instantiated for each of the slave interfaces connecting to the
152     * crossbar.
153     */
154    class CoherentXBarMasterPort : public MasterPort
155    {
156      private:
157        /** A reference to the crossbar to which this port belongs. */
158        CoherentXBar &xbar;
159
160      public:
161
162        CoherentXBarMasterPort(const std::string &_name,
163                              CoherentXBar &_xbar, PortID _id)
164            : MasterPort(_name, &_xbar, _id), xbar(_xbar)
165        { }
166
167      protected:
168
169        /**
170         * Determine if this port should be considered a snooper. For
171         * a coherent crossbar master port this is always true.
172         *
173         * @return a boolean that is true if this port is snooping
174         */
175        bool isSnooping() const override { return true; }
176
177        bool
178        recvTimingResp(PacketPtr pkt) override
179        {
180            return xbar.recvTimingResp(pkt, id);
181        }
182
183        void
184        recvTimingSnoopReq(PacketPtr pkt) override
185        {
186            return xbar.recvTimingSnoopReq(pkt, id);
187        }
188
189        Tick
190        recvAtomicSnoop(PacketPtr pkt) override
191        {
192            return xbar.recvAtomicSnoop(pkt, id);
193        }
194
195        void
196        recvFunctionalSnoop(PacketPtr pkt) override
197        {
198            xbar.recvFunctionalSnoop(pkt, id);
199        }
200
201        void recvRangeChange() override { xbar.recvRangeChange(id); }
202        void recvReqRetry() override { xbar.recvReqRetry(id); }
203
204    };
205
206    /**
207     * Internal class to bridge between an incoming snoop response
208     * from a slave port and forwarding it through an outgoing slave
209     * port. It is effectively a dangling master port.
210     */
211    class SnoopRespPort : public MasterPort
212    {
213
214      private:
215
216        /** The port which we mirror internally. */
217        QueuedSlavePort& slavePort;
218
219      public:
220
221        /**
222         * Create a snoop response port that mirrors a given slave port.
223         */
224        SnoopRespPort(QueuedSlavePort& slave_port, CoherentXBar& _xbar) :
225            MasterPort(slave_port.name() + ".snoopRespPort", &_xbar),
226            slavePort(slave_port) { }
227
228        /**
229         * Override the sending of retries and pass them on through
230         * the mirrored slave port.
231         */
232        void
233        sendRetryResp() override
234        {
235            // forward it as a snoop response retry
236            slavePort.sendRetrySnoopResp();
237        }
238
239        void
240        recvReqRetry() override
241        {
242            panic("SnoopRespPort should never see retry");
243        }
244
245        bool
246        recvTimingResp(PacketPtr pkt) override
247        {
248            panic("SnoopRespPort should never see timing response");
249        }
250
251    };
252
253    std::vector<SnoopRespPort*> snoopRespPorts;
254
255    std::vector<QueuedSlavePort*> snoopPorts;
256
257    /**
258     * Store the outstanding requests that we are expecting snoop
259     * responses from so we can determine which snoop responses we
260     * generated and which ones were merely forwarded.
261     */
262    std::unordered_set<RequestPtr> outstandingSnoop;
263
264    /**
265     * Store the outstanding cache maintenance that we are expecting
266     * snoop responses from so we can determine when we received all
267     * snoop responses and if any of the agents satisfied the request.
268     */
269    std::unordered_map<PacketId, PacketPtr> outstandingCMO;
270
271    /**
272     * Keep a pointer to the system to be allow to querying memory system
273     * properties.
274     */
275    System *system;
276
277    /** A snoop filter that tracks cache line residency and can restrict the
278      * broadcast needed for probes.  NULL denotes an absent filter. */
279    SnoopFilter *snoopFilter;
280
281    /** Cycles of snoop response latency.*/
282    const Cycles snoopResponseLatency;
283
284    /** Maximum number of outstading snoops sanity check*/
285    const unsigned int maxOutstandingSnoopCheck;
286
287    /** Maximum routing table size sanity check*/
288    const unsigned int maxRoutingTableSizeCheck;
289
290    /** Is this crossbar the point of coherency? **/
291    const bool pointOfCoherency;
292
293    /** Is this crossbar the point of unification? **/
294    const bool pointOfUnification;
295
296    /**
297     * Upstream caches need this packet until true is returned, so
298     * hold it for deletion until a subsequent call
299     */
300    std::unique_ptr<Packet> pendingDelete;
301
302    bool recvTimingReq(PacketPtr pkt, PortID slave_port_id);
303    bool recvTimingResp(PacketPtr pkt, PortID master_port_id);
304    void recvTimingSnoopReq(PacketPtr pkt, PortID master_port_id);
305    bool recvTimingSnoopResp(PacketPtr pkt, PortID slave_port_id);
306    void recvReqRetry(PortID master_port_id);
307
308    /**
309     * Forward a timing packet to our snoopers, potentially excluding
310     * one of the connected coherent masters to avoid sending a packet
311     * back to where it came from.
312     *
313     * @param pkt Packet to forward
314     * @param exclude_slave_port_id Id of slave port to exclude
315     */
316    void
317    forwardTiming(PacketPtr pkt, PortID exclude_slave_port_id)
318    {
319        forwardTiming(pkt, exclude_slave_port_id, snoopPorts);
320    }
321
322    /**
323     * Forward a timing packet to a selected list of snoopers, potentially
324     * excluding one of the connected coherent masters to avoid sending a packet
325     * back to where it came from.
326     *
327     * @param pkt Packet to forward
328     * @param exclude_slave_port_id Id of slave port to exclude
329     * @param dests Vector of destination ports for the forwarded pkt
330     */
331    void forwardTiming(PacketPtr pkt, PortID exclude_slave_port_id,
332                       const std::vector<QueuedSlavePort*>& dests);
333
334    Tick recvAtomicBackdoor(PacketPtr pkt, PortID slave_port_id,
335                            MemBackdoorPtr *backdoor=nullptr);
336    Tick recvAtomicSnoop(PacketPtr pkt, PortID master_port_id);
337
338    /**
339     * Forward an atomic packet to our snoopers, potentially excluding
340     * one of the connected coherent masters to avoid sending a packet
341     * back to where it came from.
342     *
343     * @param pkt Packet to forward
344     * @param exclude_slave_port_id Id of slave port to exclude
345     *
346     * @return a pair containing the snoop response and snoop latency
347     */
348    std::pair<MemCmd, Tick>
349    forwardAtomic(PacketPtr pkt, PortID exclude_slave_port_id)
350    {
351        return forwardAtomic(pkt, exclude_slave_port_id, InvalidPortID,
352                             snoopPorts);
353    }
354
355    /**
356     * Forward an atomic packet to a selected list of snoopers, potentially
357     * excluding one of the connected coherent masters to avoid sending a packet
358     * back to where it came from.
359     *
360     * @param pkt Packet to forward
361     * @param exclude_slave_port_id Id of slave port to exclude
362     * @param source_master_port_id Id of the master port for snoops from below
363     * @param dests Vector of destination ports for the forwarded pkt
364     *
365     * @return a pair containing the snoop response and snoop latency
366     */
367    std::pair<MemCmd, Tick> forwardAtomic(PacketPtr pkt,
368                                          PortID exclude_slave_port_id,
369                                          PortID source_master_port_id,
370                                          const std::vector<QueuedSlavePort*>&
371                                          dests);
372
373    /** Function called by the port when the crossbar is recieving a Functional
374        transaction.*/
375    void recvFunctional(PacketPtr pkt, PortID slave_port_id);
376
377    /** Function called by the port when the crossbar is recieving a functional
378        snoop transaction.*/
379    void recvFunctionalSnoop(PacketPtr pkt, PortID master_port_id);
380
381    /**
382     * Forward a functional packet to our snoopers, potentially
383     * excluding one of the connected coherent masters to avoid
384     * sending a packet back to where it came from.
385     *
386     * @param pkt Packet to forward
387     * @param exclude_slave_port_id Id of slave port to exclude
388     */
389    void forwardFunctional(PacketPtr pkt, PortID exclude_slave_port_id);
390
391    /**
392     * Determine if the crossbar should sink the packet, as opposed to
393     * forwarding it, or responding.
394     */
395    bool sinkPacket(const PacketPtr pkt) const;
396
397    /**
398     * Determine if the crossbar should forward the packet, as opposed to
399     * responding to it.
400     */
401    bool forwardPacket(const PacketPtr pkt);
402
403    /**
404     * Determine if the packet's destination is the memory below
405     *
406     * The memory below is the destination for a cache mainteance
407     * operation to the Point of Coherence/Unification if this is the
408     * Point of Coherence/Unification.
409     *
410     * @param pkt The processed packet
411     *
412     * @return Whether the memory below is the destination for the packet
413     */
414    bool
415    isDestination(const PacketPtr pkt) const
416    {
417        return (pkt->req->isToPOC() && pointOfCoherency) ||
418            (pkt->req->isToPOU() && pointOfUnification);
419    }
420
421    Stats::Scalar snoops;
422    Stats::Scalar snoopTraffic;
423    Stats::Distribution snoopFanout;
424
425  public:
426
427    virtual void init();
428
429    CoherentXBar(const CoherentXBarParams *p);
430
431    virtual ~CoherentXBar();
432
433    virtual void regStats();
434};
435
436#endif //__MEM_COHERENT_XBAR_HH__
437