bridge.hh revision 8949 
1/*
2 * Copyright (c) 2011-2012 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) 2006 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: Ali Saidi
41 *          Steve Reinhardt
42 *          Andreas Hansson
43 */
44
45/**
46 * @file
47 * Declaration of a memory-mapped bus bridge that connects a master
48 * and a slave through a request and response queue.
49 */
50
51#ifndef __MEM_BRIDGE_HH__
52#define __MEM_BRIDGE_HH__
53
54#include <list>
55#include <queue>
56#include <string>
57
58#include "base/fast_alloc.hh"
59#include "base/types.hh"
60#include "mem/mem_object.hh"
61#include "mem/packet.hh"
62#include "mem/port.hh"
63#include "params/Bridge.hh"
64#include "sim/eventq.hh"
65
66/**
67 * A bridge is used to interface two different busses (or in general a
68 * memory-mapped master and slave), with buffering for requests and
69 * responses. The bridge has a fixed delay for packets passing through
70 * it and responds to a fixed set of address ranges.
71 *
72 * The bridge comprises a slave port and a master port, that buffer
73 * outgoing responses and requests respectively. Buffer space is
74 * reserved when a request arrives, also reserving response space
75 * before forwarding the request. An incoming request is always
76 * accepted (recvTiming returns true), but is potentially NACKed if
77 * there is no request space or response space.
78 */
79class Bridge : public MemObject
80{
81  protected:
82
83    /**
84     * A packet buffer stores packets along with their sender state
85     * and scheduled time for transmission.
86     */
87    class PacketBuffer : public Packet::SenderState, public FastAlloc {
88
89      public:
90        Tick ready;
91        PacketPtr pkt;
92        bool nackedHere;
93        Packet::SenderState *origSenderState;
94        Packet::NodeID origSrc;
95        bool expectResponse;
96
97        PacketBuffer(PacketPtr _pkt, Tick t, bool nack = false)
98            : ready(t), pkt(_pkt), nackedHere(nack),
99              origSenderState(_pkt->senderState),
100              origSrc(nack ? _pkt->getDest() : _pkt->getSrc() ),
101              expectResponse(_pkt->needsResponse() && !nack)
102
103        {
104            if (!pkt->isResponse() && !nack)
105                pkt->senderState = this;
106        }
107
108        void fixResponse(PacketPtr pkt)
109        {
110            assert(pkt->senderState == this);
111            pkt->setDest(origSrc);
112            pkt->senderState = origSenderState;
113        }
114    };
115
116    // Forward declaration to allow the slave port to have a pointer
117    class BridgeMasterPort;
118
119    /**
120     * The port on the side that receives requests and sends
121     * responses. The slave port has a set of address ranges that it
122     * is responsible for. The slave port also has a buffer for the
123     * responses not yet sent.
124     */
125    class BridgeSlavePort : public SlavePort
126    {
127
128      private:
129
130        /** A pointer to the bridge to which this port belongs. */
131        Bridge *bridge;
132
133        /**
134         * Master port on the other side of the bridge
135         * (connected to the other bus).
136         */
137        BridgeMasterPort& masterPort;
138
139        /** Minimum request delay though this bridge. */
140        Tick delay;
141
142        /** Min delay to respond with a nack. */
143        Tick nackDelay;
144
145        /** Address ranges to pass through the bridge */
146        AddrRangeList ranges;
147
148        /**
149         * Response packet queue. Response packets are held in this
150         * queue for a specified delay to model the processing delay
151         * of the bridge.
152         */
153        std::list<PacketBuffer*> responseQueue;
154
155        /** Counter to track the outstanding responses. */
156        unsigned int outstandingResponses;
157
158        /** If we're waiting for a retry to happen. */
159        bool inRetry;
160
161        /** Max queue size for reserved responses. */
162        unsigned int respQueueLimit;
163
164        /**
165         * Is this side blocked from accepting new response packets.
166         *
167         * @return true if the reserved space has reached the set limit
168         */
169        bool respQueueFull();
170
171        /**
172         * Turn the request packet into a NACK response and put it in
173         * the response queue and schedule its transmission.
174         *
175         * @param pkt the request packet to NACK
176         */
177        void nackRequest(PacketPtr pkt);
178
179        /**
180         * Handle send event, scheduled when the packet at the head of
181         * the response queue is ready to transmit (for timing
182         * accesses only).
183         */
184        void trySend();
185
186        /**
187         * Private class for scheduling sending of responses from the
188         * response queue.
189         */
190        class SendEvent : public Event
191        {
192            BridgeSlavePort& port;
193
194          public:
195            SendEvent(BridgeSlavePort& p) : port(p) {}
196            virtual void process() { port.trySend(); }
197            virtual const char *description() const { return "bridge send"; }
198        };
199
200        /** Send event for the response queue. */
201        SendEvent sendEvent;
202
203      public:
204
205        /**
206         * Constructor for the BridgeSlavePort.
207         *
208         * @param _name the port name including the owner
209         * @param _bridge the structural owner
210         * @param _masterPort the master port on the other side of the bridge
211         * @param _delay the delay from seeing a response to sending it
212         * @param _nack_delay the delay from a NACK to sending the response
213         * @param _resp_limit the size of the response queue
214         * @param _ranges a number of address ranges to forward
215         */
216        BridgeSlavePort(const std::string &_name, Bridge *_bridge,
217                        BridgeMasterPort& _masterPort, int _delay,
218                        int _nack_delay, int _resp_limit,
219                        std::vector<Range<Addr> > _ranges);
220
221        /**
222         * Queue a response packet to be sent out later and also schedule
223         * a send if necessary.
224         *
225         * @param pkt a response to send out after a delay
226         */
227        void queueForSendTiming(PacketPtr pkt);
228
229      protected:
230
231        /** When receiving a timing request from the peer port,
232            pass it to the bridge. */
233        virtual bool recvTiming(PacketPtr pkt);
234
235        /** When receiving a retry request from the peer port,
236            pass it to the bridge. */
237        virtual void recvRetry();
238
239        /** When receiving a Atomic requestfrom the peer port,
240            pass it to the bridge. */
241        virtual Tick recvAtomic(PacketPtr pkt);
242
243        /** When receiving a Functional request from the peer port,
244            pass it to the bridge. */
245        virtual void recvFunctional(PacketPtr pkt);
246
247        /** When receiving a address range request the peer port,
248            pass it to the bridge. */
249        virtual AddrRangeList getAddrRanges();
250    };
251
252
253    /**
254     * Port on the side that forwards requests and receives
255     * responses. The master port has a buffer for the requests not
256     * yet sent.
257     */
258    class BridgeMasterPort : public MasterPort
259    {
260
261      private:
262
263        /** A pointer to the bridge to which this port belongs. */
264        Bridge* bridge;
265
266        /**
267         * Pointer to the slave port on the other side of the bridge
268         * (connected to the other bus).
269         */
270        BridgeSlavePort& slavePort;
271
272        /** Minimum delay though this bridge. */
273        Tick delay;
274
275        /**
276         * Request packet queue. Request packets are held in this
277         * queue for a specified delay to model the processing delay
278         * of the bridge.
279         */
280        std::list<PacketBuffer*> requestQueue;
281
282        /** If we're waiting for a retry to happen. */
283        bool inRetry;
284
285        /** Max queue size for request packets */
286        unsigned int reqQueueLimit;
287
288        /**
289         * Handle send event, scheduled when the packet at the head of
290         * the outbound queue is ready to transmit (for timing
291         * accesses only).
292         */
293        void trySend();
294
295        /**
296         * Private class for scheduling sending of requests from the
297         * request queue.
298         */
299        class SendEvent : public Event
300        {
301            BridgeMasterPort& port;
302
303          public:
304            SendEvent(BridgeMasterPort& p) : port(p) {}
305            virtual void process() { port.trySend(); }
306            virtual const char *description() const { return "bridge send"; }
307        };
308
309        /** Send event for the request queue. */
310        SendEvent sendEvent;
311
312      public:
313
314        /**
315         * Constructor for the BridgeMasterPort.
316         *
317         * @param _name the port name including the owner
318         * @param _bridge the structural owner
319         * @param _slavePort the slave port on the other side of the bridge
320         * @param _delay the delay from seeing a request to sending it
321         * @param _req_limit the size of the request queue
322         */
323        BridgeMasterPort(const std::string &_name, Bridge *_bridge,
324                         BridgeSlavePort& _slavePort, int _delay,
325                         int _req_limit);
326
327        /**
328         * Is this side blocked from accepting new request packets.
329         *
330         * @return true if the occupied space has reached the set limit
331         */
332        bool reqQueueFull();
333
334        /**
335         * Queue a request packet to be sent out later and also schedule
336         * a send if necessary.
337         *
338         * @param pkt a request to send out after a delay
339         */
340        void queueForSendTiming(PacketPtr pkt);
341
342        /**
343         * Check a functional request against the packets in our
344         * request queue.
345         *
346         * @param pkt packet to check against
347         *
348         * @return true if we find a match
349         */
350        bool checkFunctional(PacketPtr pkt);
351
352      protected:
353
354        /** When receiving a timing request from the peer port,
355            pass it to the bridge. */
356        virtual bool recvTiming(PacketPtr pkt);
357
358        /** When receiving a retry request from the peer port,
359            pass it to the bridge. */
360        virtual void recvRetry();
361    };
362
363    /** Slave port of the bridge. */
364    BridgeSlavePort slavePort;
365
366    /** Master port of the bridge. */
367    BridgeMasterPort masterPort;
368
369    /** If this bridge should acknowledge writes. */
370    bool ackWrites;
371
372  public:
373    typedef BridgeParams Params;
374
375  protected:
376    Params *_params;
377
378  public:
379    const Params *params() const { return _params; }
380
381    virtual MasterPort& getMasterPort(const std::string& if_name,
382                                      int idx = -1);
383    virtual SlavePort& getSlavePort(const std::string& if_name, int idx = -1);
384
385    virtual void init();
386
387    Bridge(Params *p);
388};
389
390#endif //__MEM_BUS_HH__
391