bridge.hh revision 8713:2f1a3e335255 
1/*
2 * Copyright (c) 2011 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        short 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 Port
126    {
127
128      private:
129
130        /** A pointer to the bridge to which this port belongs. */
131        Bridge *bridge;
132
133        /**
134         * Pointer to the 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        /**
248         * When receiving a range change on the slave side do nothing.
249         */
250        virtual void recvRangeChange();
251
252        /** When receiving a address range request the peer port,
253            pass it to the bridge. */
254        virtual AddrRangeList getAddrRanges();
255    };
256
257
258    /**
259     * Port on the side that forwards requests and receives
260     * responses. The master port has a buffer for the requests not
261     * yet sent.
262     */
263    class BridgeMasterPort : public Port
264    {
265
266      private:
267
268        /** A pointer to the bridge to which this port belongs. */
269        Bridge* bridge;
270
271        /**
272         * Pointer to the slave port on the other side of the bridge
273         * (connected to the other bus).
274         */
275        BridgeSlavePort* slavePort;
276
277        /** Minimum delay though this bridge. */
278        Tick delay;
279
280        /**
281         * Request packet queue. Request packets are held in this
282         * queue for a specified delay to model the processing delay
283         * of the bridge.
284         */
285        std::list<PacketBuffer*> requestQueue;
286
287        /** If we're waiting for a retry to happen. */
288        bool inRetry;
289
290        /** Max queue size for request packets */
291        unsigned int reqQueueLimit;
292
293        /**
294         * Handle send event, scheduled when the packet at the head of
295         * the outbound queue is ready to transmit (for timing
296         * accesses only).
297         */
298        void trySend();
299
300        /**
301         * Private class for scheduling sending of requests from the
302         * request queue.
303         */
304        class SendEvent : public Event
305        {
306            BridgeMasterPort *port;
307
308          public:
309            SendEvent(BridgeMasterPort *p) : port(p) {}
310            virtual void process() { port->trySend(); }
311            virtual const char *description() const { return "bridge send"; }
312        };
313
314        /** Send event for the request queue. */
315        SendEvent sendEvent;
316
317      public:
318
319        /**
320         * Constructor for the BridgeMasterPort.
321         *
322         * @param _name the port name including the owner
323         * @param _bridge the structural owner
324         * @param _slavePort the slave port on the other side of the bridge
325         * @param _delay the delay from seeing a request to sending it
326         * @param _req_limit the size of the request queue
327         */
328        BridgeMasterPort(const std::string &_name, Bridge *_bridge,
329                         BridgeSlavePort* _slavePort, int _delay,
330                         int _req_limit);
331
332        /**
333         * Is this side blocked from accepting new request packets.
334         *
335         * @return true if the occupied space has reached the set limit
336         */
337        bool reqQueueFull();
338
339        /**
340         * Queue a request packet to be sent out later and also schedule
341         * a send if necessary.
342         *
343         * @param pkt a request to send out after a delay
344         */
345        void queueForSendTiming(PacketPtr pkt);
346
347        /**
348         * Check a functional request against the packets in our
349         * request queue.
350         *
351         * @param pkt packet to check against
352         *
353         * @return true if we find a match
354         */
355        bool checkFunctional(PacketPtr pkt);
356
357      protected:
358
359        /** When receiving a timing request from the peer port,
360            pass it to the bridge. */
361        virtual bool recvTiming(PacketPtr pkt);
362
363        /** When receiving a retry request from the peer port,
364            pass it to the bridge. */
365        virtual void recvRetry();
366
367        /** When receiving a Atomic requestfrom the peer port,
368            pass it to the bridge. */
369        virtual Tick recvAtomic(PacketPtr pkt);
370
371        /** When receiving a Functional request from the peer port,
372            pass it to the bridge. */
373        virtual void recvFunctional(PacketPtr pkt);
374
375        /**
376         * When receiving a range change, pass it through the bridge.
377         */
378        virtual void recvRangeChange();
379    };
380
381    /** Slave port of the bridge. */
382    BridgeSlavePort slavePort;
383
384    /** Master port of the bridge. */
385    BridgeMasterPort masterPort;
386
387    /** If this bridge should acknowledge writes. */
388    bool ackWrites;
389
390  public:
391    typedef BridgeParams Params;
392
393  protected:
394    Params *_params;
395
396  public:
397    const Params *params() const { return _params; }
398
399    /** A function used to return the port associated with this bus object. */
400    virtual Port *getPort(const std::string &if_name, int idx = -1);
401
402    virtual void init();
403
404    Bridge(Params *p);
405};
406
407#endif //__MEM_BUS_HH__
408