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