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     EventWrapper<PacketQueue, &PacketQueue::processSendEvent> 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                 bool disable_sanity_check = false);
 138
 139     /**
 140      * Virtual desctructor since the class may be used as a base class.
 141      */
 142     virtual ~PacketQueue();
 143
 144   public:
 145
 146     /**
 147      * Provide a name to simplify debugging.
 148      *
 149      * @return A complete name, appended to module and port
 150      */
 151     virtual const std::string name() const = 0;
 152
 153     /**
 154      * Get the size of the queue.
 155      */
 156     size_t size() const { return transmitList.size(); }
 157
 158     /**
 159      * Get the next packet ready time.
 160      */
 161     Tick deferredPacketReadyTime() const
 162     { return transmitList.empty() ? MaxTick : transmitList.front().tick; }
 163
 164     /**
 165      * Check if a packets address exists in the queue.
 166      */
 167     bool hasAddr(Addr addr) const;
 168
 169     /** Check the list of buffered packets against the supplied
 170      * functional request. */
 171     bool checkFunctional(PacketPtr pkt);
 172
 173     /**
 174      * Schedule a send event if we are not already waiting for a
 175      * retry. If the requested time is before an already scheduled
 176      * send event, the event will be rescheduled. If MaxTick is
 177      * passed, no event is scheduled. Instead, if we are idle and
 178      * asked to drain then check and signal drained.
 179      *
 180      * @param when time to schedule an event
 181      */
 182     void schedSendEvent(Tick when);
 183
 184     /**
 185      * Add a packet to the transmit list, and schedule a send event.
 186      *
 187      * @param pkt Packet to send
 188      * @param when Absolute time (in ticks) to send packet
 189      * @param force_order Force insertion order for packets with same address
 190      */
 191     void schedSendTiming(PacketPtr pkt, Tick when, bool force_order = false);
 192
 193     /**
 194      * Retry sending a packet from the queue. Note that this is not
 195      * necessarily the same packet if something has been added with an
 196      * earlier time stamp.
 197      */
 198     void retry();
 199
 200     /**
 201       * This allows a user to explicitly disable the sanity check
 202       * on the size of the transmitList, which is enabled by default.
 203       * Users must use this function to explicitly disable the sanity
 204       * check.
 205       */
 206     void disableSanityCheck() { _disableSanityCheck = true; }
 207
 208     DrainState drain() override;
 209 };
 210
 211 class ReqPacketQueue : public PacketQueue
 212 {
 213
 214   protected:
 215
 216     MasterPort& masterPort;
 217
 218   public:
 219
 220     /**
 221      * Create a request packet queue, linked to an event manager, a
 222      * master port, and a label that will be used for functional print
 223      * request packets.
 224      *
 225      * @param _em Event manager used for scheduling this queue
 226      * @param _masterPort Master port used to send the packets
 227      * @param _label Label to push on the label stack for print request packets
 228      */
 229     ReqPacketQueue(EventManager& _em, MasterPort& _masterPort,
 230                    const std::string _label = "ReqPacketQueue");
 231
 232     virtual ~ReqPacketQueue() { }
 233
 234     const std::string name() const
 235     { return masterPort.name() + "-" + label; }
 236
 237     bool sendTiming(PacketPtr pkt);
 238
 239 };
 240
 241 class SnoopRespPacketQueue : public PacketQueue
 242 {
 243
 244   protected:
 245
 246     MasterPort& masterPort;
 247
 248   public:
 249
 250     /**
 251      * Create a snoop response packet queue, linked to an event
 252      * manager, a master port, and a label that will be used for
 253      * functional print request packets.
 254      *
 255      * @param _em Event manager used for scheduling this queue
 256      * @param _masterPort Master port used to send the packets
 257      * @param _label Label to push on the label stack for print request packets
 258      */
 259     SnoopRespPacketQueue(EventManager& _em, MasterPort& _masterPort,
 260                          const std::string _label = "SnoopRespPacketQueue");
 261
 262     virtual ~SnoopRespPacketQueue() { }
 263
 264     const std::string name() const
 265     { return masterPort.name() + "-" + label; }
 266
 267     bool sendTiming(PacketPtr pkt);
 268
 269 };
 270
 271 class RespPacketQueue : public PacketQueue
 272 {
 273
 274   protected:
 275
 276     SlavePort& slavePort;
 277
 278   public:
 279
 280     /**
 281      * Create a response packet queue, linked to an event manager, a
 282      * slave port, and a label that will be used for functional print
 283      * request packets.
 284      *
 285      * @param _em Event manager used for scheduling this queue
 286      * @param _slavePort Slave port used to send the packets
 287      * @param _label Label to push on the label stack for print request packets
 288      */
 289     RespPacketQueue(EventManager& _em, SlavePort& _slavePort,
 290                      const std::string _label = "RespPacketQueue");
 291
 292     virtual ~RespPacketQueue() { }
 293
 294     const std::string name() const
 295     { return slavePort.name() + "-" + label; }
 296
 297     bool sendTiming(PacketPtr pkt);
 298
 299 };
 300
 301 #endif // __MEM_PACKET_QUEUE_HH__