src/mem/packet_queue.hh

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