src/mem/packet_queue.hh

   1 /*
   2  * Copyright (c) 2012,2015 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  *          Andreas Hansson
  42  */
  43
  44 #ifndef __MEM_PACKET_QUEUE_HH__
  45 #define __MEM_PACKET_QUEUE_HH__
  46
  47 /**
  48  * @file
  49  * Declaration of a simple PacketQueue that is associated with
  50  * a port on which it attempts to send packets according to the time
  51  * stamp given to them at insertion. The packet queue is responsible
  52  * for the flow control of the port.
  53  */
  54
  55 #include <list>
  56
  57 #include "mem/port.hh"
  58 #include "sim/drain.hh"
  59 #include "sim/eventq_impl.hh"
  60
  61 /**
  62  * A packet queue is a class that holds deferred packets and later
  63  * sends them using the associated slave port or master port.
  64  */
  65 class PacketQueue : public Drainable
  66 {
  67   private:
  68     /** A deferred packet, buffered to transmit later. */
  69     class DeferredPacket {
  70       public:
  71         Tick tick;      ///< The tick when the packet is ready to transmit
  72         PacketPtr pkt;  ///< Pointer to the packet to transmit
  73         DeferredPacket(Tick t, PacketPtr p)
  74             : tick(t), pkt(p)
  75         {}
  76     };
  77
  78     typedef std::list<DeferredPacket> DeferredPacketList;
  79
  80     /** A list of outgoing packets. */
  81     DeferredPacketList transmitList;
  82
  83     /** The manager which is used for the event queue */
  84     EventManager& em;
  85
  86     /** Used to schedule sending of deferred packets. */
  87     void processSendEvent();
  88
  89     /** Event used to call processSendEvent. */
  90     EventFunctionWrapper sendEvent;
  91
  92      /*
  93       * Optionally disable the sanity check
  94       * on the size of the transmitList. The
  95       * sanity check will be enabled by default.
  96       */
  97     bool _disableSanityCheck;
  98
  99   protected:
 100
 101     /** Label to use for print request packets label stack. */
 102     const std::string label;
 103
 104     /** Remember whether we're awaiting a retry. */
 105     bool waitingOnRetry;
 106
 107     /** Check whether we have a packet ready to go on the transmit list. */
 108     bool deferredPacketReady() const
 109     { return !transmitList.empty() && transmitList.front().tick <= curTick(); }
 110
 111     /**
 112      * Attempt to send a packet. Note that a subclass of the
 113      * PacketQueue can override this method and thus change the
 114      * behaviour (as done by the cache for the request queue). The
 115      * default implementation sends the head of the transmit list. The
 116      * caller must guarantee that the list is non-empty and that the
 117      * head packet is scheduled for curTick() (or earlier).
 118      */
 119     virtual void sendDeferredPacket();
 120
 121     /**
 122      * Send a packet using the appropriate method for the specific
 123      * subclass (reuest, response or snoop response).
 124      */
 125     virtual bool sendTiming(PacketPtr pkt) = 0;
 126
 127     /**
 128      * Create a packet queue, linked to an event manager, and a label
 129      * that will be used for functional print request packets.
 130      *
 131      * @param _em Event manager used for scheduling this queue
 132      * @param _label Label to push on the label stack for print request packets
 133      * @param disable_sanity_check Flag used to disable the sanity check
 134      *        on the size of the transmitList. The check is enabled by default.
 135      */
 136     PacketQueue(EventManager& _em, const std::string& _label,
 137                 const std::string& _sendEventName,
 138                 bool disable_sanity_check = false);
 139
 140     /**
 141      * Virtual desctructor since the class may be used as a base class.
 142      */
 143     virtual ~PacketQueue();
 144
 145   public:
 146
 147     /**
 148      * Provide a name to simplify debugging.
 149      *
 150      * @return A complete name, appended to module and port
 151      */
 152     virtual const std::string name() const = 0;
 153
 154     /**
 155      * Get the size of the queue.
 156      */
 157     size_t size() const { return transmitList.size(); }
 158
 159     /**
 160      * Get the next packet ready time.
 161      */
 162     Tick deferredPacketReadyTime() const
 163     { return transmitList.empty() ? MaxTick : transmitList.front().tick; }
 164
 165     /**
 166      * Check if a packets address exists in the queue.
 167      */
 168     bool hasAddr(Addr addr) const;
 169
 170     /** Check the list of buffered packets against the supplied
 171      * functional request. */
 172     bool trySatisfyFunctional(PacketPtr pkt);
 173
 174     /**
 175      * Schedule a send event if we are not already waiting for a
 176      * retry. If the requested time is before an already scheduled
 177      * send event, the event will be rescheduled. If MaxTick is
 178      * passed, no event is scheduled. Instead, if we are idle and
 179      * asked to drain then check and signal drained.
 180      *
 181      * @param when time to schedule an event
 182      */
 183     void schedSendEvent(Tick when);
 184
 185     /**
 186      * Add a packet to the transmit list, and schedule a send event.
 187      *
 188      * @param pkt Packet to send
 189      * @param when Absolute time (in ticks) to send packet
 190      * @param force_order Force insertion order for packets with same address
 191      */
 192     void schedSendTiming(PacketPtr pkt, Tick when, bool force_order = false);
 193
 194     /**
 195      * Retry sending a packet from the queue. Note that this is not
 196      * necessarily the same packet if something has been added with an
 197      * earlier time stamp.
 198      */
 199     void retry();
 200
 201     /**
 202       * This allows a user to explicitly disable the sanity check
 203       * on the size of the transmitList, which is enabled by default.
 204       * Users must use this function to explicitly disable the sanity
 205       * check.
 206       */
 207     void disableSanityCheck() { _disableSanityCheck = true; }
 208
 209     DrainState drain() override;
 210 };
 211
 212 class ReqPacketQueue : public PacketQueue
 213 {
 214
 215   protected:
 216
 217     MasterPort& masterPort;
 218
 219     // Static definition so it can be called when constructing the parent
 220     // without us being completely initialized.
 221     static const std::string name(const MasterPort& masterPort,
 222                                   const std::string& label)
 223     { return masterPort.name() + "-" + label; }
 224
 225   public:
 226
 227     /**
 228      * Create a request packet queue, linked to an event manager, a
 229      * master port, and a label that will be used for functional print
 230      * request packets.
 231      *
 232      * @param _em Event manager used for scheduling this queue
 233      * @param _masterPort Master port used to send the packets
 234      * @param _label Label to push on the label stack for print request packets
 235      */
 236     ReqPacketQueue(EventManager& _em, MasterPort& _masterPort,
 237                    const std::string _label = "ReqPacketQueue");
 238
 239     virtual ~ReqPacketQueue() { }
 240
 241     const std::string name() const
 242     { return name(masterPort, label); }
 243
 244     bool sendTiming(PacketPtr pkt);
 245
 246 };
 247
 248 class SnoopRespPacketQueue : public PacketQueue
 249 {
 250
 251   protected:
 252
 253     MasterPort& masterPort;
 254
 255     // Static definition so it can be called when constructing the parent
 256     // without us being completely initialized.
 257     static const std::string name(const MasterPort& masterPort,
 258                                   const std::string& label)
 259     { return masterPort.name() + "-" + label; }
 260
 261   public:
 262
 263     /**
 264      * Create a snoop response packet queue, linked to an event
 265      * manager, a master port, and a label that will be used for
 266      * functional print request packets.
 267      *
 268      * @param _em Event manager used for scheduling this queue
 269      * @param _masterPort Master port used to send the packets
 270      * @param _label Label to push on the label stack for print request packets
 271      */
 272     SnoopRespPacketQueue(EventManager& _em, MasterPort& _masterPort,
 273                          const std::string _label = "SnoopRespPacketQueue");
 274
 275     virtual ~SnoopRespPacketQueue() { }
 276
 277     const std::string name() const
 278     { return name(masterPort, label); }
 279
 280     bool sendTiming(PacketPtr pkt);
 281
 282 };
 283
 284 class RespPacketQueue : public PacketQueue
 285 {
 286
 287   protected:
 288
 289     SlavePort& slavePort;
 290
 291     // Static definition so it can be called when constructing the parent
 292     // without us being completely initialized.
 293     static const std::string name(const SlavePort& slavePort,
 294                                   const std::string& label)
 295     { return slavePort.name() + "-" + label; }
 296
 297   public:
 298
 299     /**
 300      * Create a response packet queue, linked to an event manager, a
 301      * slave port, and a label that will be used for functional print
 302      * request packets.
 303      *
 304      * @param _em Event manager used for scheduling this queue
 305      * @param _slavePort Slave port used to send the packets
 306      * @param _label Label to push on the label stack for print request packets
 307      */
 308     RespPacketQueue(EventManager& _em, SlavePort& _slavePort,
 309                      const std::string _label = "RespPacketQueue");
 310
 311     virtual ~RespPacketQueue() { }
 312
 313     const std::string name() const
 314     { return name(slavePort, label); }
 315
 316     bool sendTiming(PacketPtr pkt);
 317
 318 };
 319
 320 #endif // __MEM_PACKET_QUEUE_HH__