src/mem/port.hh

   1 /*
   2  * Copyright (c) 2011-2012,2015,2017 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) 2002-2005 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: Ron Dreslinski
  41  *          Andreas Hansson
  42  *          William Wang
  43  */
  44
  45 /**
  46  * @file
  47  * Port Object Declaration.
  48  */
  49
  50 #ifndef __MEM_PORT_HH__
  51 #define __MEM_PORT_HH__
  52
  53 #include "base/addr_range.hh"
  54 #include "mem/packet.hh"
  55
  56 class MemObject;
  57
  58 /**
  59  * Ports are used to interface memory objects to each other. A port is
  60  * either a master or a slave and the connected peer is always of the
  61  * opposite role. Each port has a name, an owner, and an identifier.
  62  */
  63 class Port
  64 {
  65
  66   private:
  67
  68     /** Descriptive name (for DPRINTF output) */
  69     std::string portName;
  70
  71   protected:
  72
  73     /**
  74      * A numeric identifier to distinguish ports in a vector, and set
  75      * to InvalidPortID in case this port is not part of a vector.
  76      */
  77     const PortID id;
  78
  79     /**
  80      * Abstract base class for ports
  81      *
  82      * @param _name Port name including the owners name
  83      * @param _id A port identifier for vector ports
  84      */
  85     Port(const std::string& _name, PortID _id);
  86
  87     /**
  88      * Virtual destructor due to inheritance.
  89      */
  90     virtual ~Port();
  91
  92   public:
  93
  94     /** Return port name (for DPRINTF). */
  95     const std::string name() const { return portName; }
  96
  97     /** Get the port id. */
  98     PortID getId() const { return id; }
  99
 100 };
 101
 102 /** Forward declaration */
 103 class BaseSlavePort;
 104
 105 /**
 106  * A BaseMasterPort is a protocol-agnostic master port, responsible
 107  * only for the structural connection to a slave port. The final
 108  * master port that inherits from the base class must override the
 109  * bind member function for the specific slave port class.
 110  */
 111 class BaseMasterPort : public Port
 112 {
 113
 114   protected:
 115
 116     BaseSlavePort* _baseSlavePort;
 117
 118     BaseMasterPort(const std::string& name, PortID id=InvalidPortID);
 119     virtual ~BaseMasterPort();
 120
 121   public:
 122
 123     virtual void bind(BaseSlavePort& slave_port) = 0;
 124     virtual void unbind() = 0;
 125     BaseSlavePort& getSlavePort() const;
 126     bool isConnected() const;
 127
 128 };
 129
 130 /**
 131  * A BaseSlavePort is a protocol-agnostic slave port, responsible
 132  * only for the structural connection to a master port.
 133  */
 134 class BaseSlavePort : public Port
 135 {
 136
 137   protected:
 138
 139     BaseMasterPort* _baseMasterPort;
 140
 141     BaseSlavePort(const std::string& name, PortID id=InvalidPortID);
 142     virtual ~BaseSlavePort();
 143
 144   public:
 145
 146     BaseMasterPort& getMasterPort() const;
 147     bool isConnected() const;
 148
 149 };
 150
 151 /** Forward declaration */
 152 class SlavePort;
 153
 154 /**
 155  * A MasterPort is a specialisation of a BaseMasterPort, which
 156  * implements the default protocol for the three different level of
 157  * transport functions. In addition to the basic functionality of
 158  * sending packets, it also has functions to receive range changes or
 159  * determine if the port is snooping or not.
 160  */
 161 class MasterPort : public BaseMasterPort
 162 {
 163
 164     friend class SlavePort;
 165
 166   private:
 167
 168     SlavePort* _slavePort;
 169
 170   protected:
 171
 172     MemObject& owner;
 173
 174   public:
 175
 176     MasterPort(const std::string& name, MemObject* _owner,
 177                PortID id=InvalidPortID);
 178     virtual ~MasterPort();
 179
 180     /**
 181      * Bind this master port to a slave port. This also does the
 182      * mirror action and binds the slave port to the master port.
 183      */
 184     void bind(BaseSlavePort& slave_port);
 185
 186     /**
 187      * Unbind this master port and the associated slave port.
 188      */
 189     void unbind();
 190
 191     /**
 192      * Send an atomic request packet, where the data is moved and the
 193      * state is updated in zero time, without interleaving with other
 194      * memory accesses.
 195      *
 196      * @param pkt Packet to send.
 197      *
 198      * @return Estimated latency of access.
 199      */
 200     Tick sendAtomic(PacketPtr pkt);
 201
 202     /**
 203      * Send a functional request packet, where the data is instantly
 204      * updated everywhere in the memory system, without affecting the
 205      * current state of any block or moving the block.
 206      *
 207      * @param pkt Packet to send.
 208      */
 209     void sendFunctional(PacketPtr pkt);
 210
 211     /**
 212      * Attempt to send a timing request to the slave port by calling
 213      * its corresponding receive function. If the send does not
 214      * succeed, as indicated by the return value, then the sender must
 215      * wait for a recvReqRetry at which point it can re-issue a
 216      * sendTimingReq.
 217      *
 218      * @param pkt Packet to send.
 219      *
 220      * @return If the send was succesful or not.
 221     */
 222     bool sendTimingReq(PacketPtr pkt);
 223
 224     /**
 225      * Check if the slave can handle a timing request.
 226      *
 227      * If the send cannot be handled at the moment, as indicated by
 228      * the return value, then the sender will receive a recvReqRetry
 229      * at which point it can re-issue a sendTimingReq.
 230      *
 231      * @param pkt Packet to send.
 232      *
 233      * @return If the send was succesful or not.
 234      */
 235     bool tryTiming(PacketPtr pkt) const;
 236
 237     /**
 238      * Attempt to send a timing snoop response packet to the slave
 239      * port by calling its corresponding receive function. If the send
 240      * does not succeed, as indicated by the return value, then the
 241      * sender must wait for a recvRetrySnoop at which point it can
 242      * re-issue a sendTimingSnoopResp.
 243      *
 244      * @param pkt Packet to send.
 245      */
 246     bool sendTimingSnoopResp(PacketPtr pkt);
 247
 248     /**
 249      * Send a retry to the slave port that previously attempted a
 250      * sendTimingResp to this master port and failed. Note that this
 251      * is virtual so that the "fake" snoop response port in the
 252      * coherent crossbar can override the behaviour.
 253      */
 254     virtual void sendRetryResp();
 255
 256     /**
 257      * Determine if this master port is snooping or not. The default
 258      * implementation returns false and thus tells the neighbour we
 259      * are not snooping. Any master port that wants to receive snoop
 260      * requests (e.g. a cache connected to a bus) has to override this
 261      * function.
 262      *
 263      * @return true if the port should be considered a snooper
 264      */
 265     virtual bool isSnooping() const { return false; }
 266
 267     /**
 268      * Get the address ranges of the connected slave port.
 269      */
 270     AddrRangeList getAddrRanges() const;
 271
 272     /** Inject a PrintReq for the given address to print the state of
 273      * that address throughout the memory system.  For debugging.
 274      */
 275     void printAddr(Addr a);
 276
 277   protected:
 278
 279     /**
 280      * Receive an atomic snoop request packet from the slave port.
 281      */
 282     virtual Tick recvAtomicSnoop(PacketPtr pkt)
 283     {
 284         panic("%s was not expecting an atomic snoop request\n", name());
 285         return 0;
 286     }
 287
 288     /**
 289      * Receive a functional snoop request packet from the slave port.
 290      */
 291     virtual void recvFunctionalSnoop(PacketPtr pkt)
 292     {
 293         panic("%s was not expecting a functional snoop request\n", name());
 294     }
 295
 296     /**
 297      * Receive a timing response from the slave port.
 298      */
 299     virtual bool recvTimingResp(PacketPtr pkt) = 0;
 300
 301     /**
 302      * Receive a timing snoop request from the slave port.
 303      */
 304     virtual void recvTimingSnoopReq(PacketPtr pkt)
 305     {
 306         panic("%s was not expecting a timing snoop request\n", name());
 307     }
 308
 309     /**
 310      * Called by the slave port if sendTimingReq was called on this
 311      * master port (causing recvTimingReq to be called on the slave
 312      * port) and was unsuccesful.
 313      */
 314     virtual void recvReqRetry() = 0;
 315
 316     /**
 317      * Called by the slave port if sendTimingSnoopResp was called on this
 318      * master port (causing recvTimingSnoopResp to be called on the slave
 319      * port) and was unsuccesful.
 320      */
 321     virtual void recvRetrySnoopResp()
 322     {
 323         panic("%s was not expecting a snoop retry\n", name());
 324     }
 325
 326     /**
 327      * Called to receive an address range change from the peer slave
 328      * port. The default implementation ignores the change and does
 329      * nothing. Override this function in a derived class if the owner
 330      * needs to be aware of the address ranges, e.g. in an
 331      * interconnect component like a bus.
 332      */
 333     virtual void recvRangeChange() { }
 334 };
 335
 336 /**
 337  * A SlavePort is a specialisation of a port. In addition to the
 338  * basic functionality of sending packets to its master peer, it also
 339  * has functions specific to a slave, e.g. to send range changes
 340  * and get the address ranges that the port responds to.
 341  */
 342 class SlavePort : public BaseSlavePort
 343 {
 344
 345     friend class MasterPort;
 346
 347   private:
 348
 349     MasterPort* _masterPort;
 350
 351   protected:
 352
 353     MemObject& owner;
 354
 355   public:
 356
 357     SlavePort(const std::string& name, MemObject* _owner,
 358               PortID id=InvalidPortID);
 359     virtual ~SlavePort();
 360
 361     /**
 362      * Send an atomic snoop request packet, where the data is moved
 363      * and the state is updated in zero time, without interleaving
 364      * with other memory accesses.
 365      *
 366      * @param pkt Snoop packet to send.
 367      *
 368      * @return Estimated latency of access.
 369      */
 370     Tick sendAtomicSnoop(PacketPtr pkt);
 371
 372     /**
 373      * Send a functional snoop request packet, where the data is
 374      * instantly updated everywhere in the memory system, without
 375      * affecting the current state of any block or moving the block.
 376      *
 377      * @param pkt Snoop packet to send.
 378      */
 379     void sendFunctionalSnoop(PacketPtr pkt);
 380
 381     /**
 382      * Attempt to send a timing response to the master port by calling
 383      * its corresponding receive function. If the send does not
 384      * succeed, as indicated by the return value, then the sender must
 385      * wait for a recvRespRetry at which point it can re-issue a
 386      * sendTimingResp.
 387      *
 388      * @param pkt Packet to send.
 389      *
 390      * @return If the send was succesful or not.
 391     */
 392     bool sendTimingResp(PacketPtr pkt);
 393
 394     /**
 395      * Attempt to send a timing snoop request packet to the master port
 396      * by calling its corresponding receive function. Snoop requests
 397      * always succeed and hence no return value is needed.
 398      *
 399      * @param pkt Packet to send.
 400      */
 401     void sendTimingSnoopReq(PacketPtr pkt);
 402
 403     /**
 404      * Send a retry to the master port that previously attempted a
 405      * sendTimingReq to this slave port and failed.
 406      */
 407     void sendRetryReq();
 408
 409     /**
 410      * Send a retry to the master port that previously attempted a
 411      * sendTimingSnoopResp to this slave port and failed.
 412      */
 413     void sendRetrySnoopResp();
 414
 415     /**
 416      * Find out if the peer master port is snooping or not.
 417      *
 418      * @return true if the peer master port is snooping
 419      */
 420     bool isSnooping() const { return _masterPort->isSnooping(); }
 421
 422     /**
 423      * Called by the owner to send a range change
 424      */
 425     void sendRangeChange() const {
 426         if (!_masterPort)
 427             fatal("%s cannot sendRangeChange() without master port", name());
 428         _masterPort->recvRangeChange();
 429     }
 430
 431     /**
 432      * Get a list of the non-overlapping address ranges the owner is
 433      * responsible for. All slave ports must override this function
 434      * and return a populated list with at least one item.
 435      *
 436      * @return a list of ranges responded to
 437      */
 438     virtual AddrRangeList getAddrRanges() const = 0;
 439
 440   protected:
 441
 442     /**
 443      * Called by the master port to unbind. Should never be called
 444      * directly.
 445      */
 446     void unbind();
 447
 448     /**
 449      * Called by the master port to bind. Should never be called
 450      * directly.
 451      */
 452     void bind(MasterPort& master_port);
 453
 454     /**
 455      * Receive an atomic request packet from the master port.
 456      */
 457     virtual Tick recvAtomic(PacketPtr pkt) = 0;
 458
 459     /**
 460      * Receive a functional request packet from the master port.
 461      */
 462     virtual void recvFunctional(PacketPtr pkt) = 0;
 463
 464     /**
 465      * Receive a timing request from the master port.
 466      */
 467     virtual bool recvTimingReq(PacketPtr pkt) = 0;
 468
 469     /**
 470      * Availability request from the master port.
 471      */
 472     virtual bool tryTiming(PacketPtr pkt) {
 473         panic("%s was not expecting a %s\n", name(), __func__);
 474     }
 475
 476     /**
 477      * Receive a timing snoop response from the master port.
 478      */
 479     virtual bool recvTimingSnoopResp(PacketPtr pkt)
 480     {
 481         panic("%s was not expecting a timing snoop response\n", name());
 482     }
 483
 484     /**
 485      * Called by the master port if sendTimingResp was called on this
 486      * slave port (causing recvTimingResp to be called on the master
 487      * port) and was unsuccesful.
 488      */
 489     virtual void recvRespRetry() = 0;
 490
 491 };
 492
 493 #endif //__MEM_PORT_HH__