src/mem/port.hh

   1 /*
   2  * Copyright (c) 2011-2012 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 recvRetry 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      * Attempt to send a timing snoop response packet to the slave
 228      * port by calling its corresponding receive function. If the send
 229      * does not succeed, as indicated by the return value, then the
 230      * sender must wait for a recvRetry at which point it can re-issue
 231      * a sendTimingSnoopResp.
 232      *
 233      * @param pkt Packet to send.
 234      */
 235     bool sendTimingSnoopResp(PacketPtr pkt);
 236
 237     /**
 238      * Send a retry to the slave port that previously attempted a
 239      * sendTimingResp to this master port and failed.
 240      */
 241     virtual void sendRetry();
 242
 243     /**
 244      * Determine if this master port is snooping or not. The default
 245      * implementation returns false and thus tells the neighbour we
 246      * are not snooping. Any master port that wants to receive snoop
 247      * requests (e.g. a cache connected to a bus) has to override this
 248      * function.
 249      *
 250      * @return true if the port should be considered a snooper
 251      */
 252     virtual bool isSnooping() const { return false; }
 253
 254     /**
 255      * Get the address ranges of the connected slave port.
 256      */
 257     AddrRangeList getAddrRanges() const;
 258
 259     /** Inject a PrintReq for the given address to print the state of
 260      * that address throughout the memory system.  For debugging.
 261      */
 262     void printAddr(Addr a);
 263
 264   protected:
 265
 266     /**
 267      * Receive an atomic snoop request packet from the slave port.
 268      */
 269     virtual Tick recvAtomicSnoop(PacketPtr pkt)
 270     {
 271         panic("%s was not expecting an atomic snoop request\n", name());
 272         return 0;
 273     }
 274
 275     /**
 276      * Receive a functional snoop request packet from the slave port.
 277      */
 278     virtual void recvFunctionalSnoop(PacketPtr pkt)
 279     {
 280         panic("%s was not expecting a functional snoop request\n", name());
 281     }
 282
 283     /**
 284      * Receive a timing response from the slave port.
 285      */
 286     virtual bool recvTimingResp(PacketPtr pkt) = 0;
 287
 288     /**
 289      * Receive a timing snoop request from the slave port.
 290      */
 291     virtual void recvTimingSnoopReq(PacketPtr pkt)
 292     {
 293         panic("%s was not expecting a timing snoop request\n", name());
 294     }
 295
 296     /**
 297      * Called by the slave port if sendTimingReq or
 298      * sendTimingSnoopResp was called on this master port (causing
 299      * recvTimingReq and recvTimingSnoopResp to be called on the
 300      * slave port) and was unsuccesful.
 301      */
 302     virtual void recvRetry() = 0;
 303
 304     /**
 305      * Called to receive an address range change from the peer slave
 306      * port. The default implementation ignores the change and does
 307      * nothing. Override this function in a derived class if the owner
 308      * needs to be aware of the address ranges, e.g. in an
 309      * interconnect component like a bus.
 310      */
 311     virtual void recvRangeChange() { }
 312 };
 313
 314 /**
 315  * A SlavePort is a specialisation of a port. In addition to the
 316  * basic functionality of sending packets to its master peer, it also
 317  * has functions specific to a slave, e.g. to send range changes
 318  * and get the address ranges that the port responds to.
 319  */
 320 class SlavePort : public BaseSlavePort
 321 {
 322
 323     friend class MasterPort;
 324
 325   private:
 326
 327     MasterPort* _masterPort;
 328
 329   public:
 330
 331     SlavePort(const std::string& name, MemObject* owner,
 332               PortID id = InvalidPortID);
 333     virtual ~SlavePort();
 334
 335     /**
 336      * Send an atomic snoop request packet, where the data is moved
 337      * and the state is updated in zero time, without interleaving
 338      * with other memory accesses.
 339      *
 340      * @param pkt Snoop packet to send.
 341      *
 342      * @return Estimated latency of access.
 343      */
 344     Tick sendAtomicSnoop(PacketPtr pkt);
 345
 346     /**
 347      * Send a functional snoop request packet, where the data is
 348      * instantly updated everywhere in the memory system, without
 349      * affecting the current state of any block or moving the block.
 350      *
 351      * @param pkt Snoop packet to send.
 352      */
 353     void sendFunctionalSnoop(PacketPtr pkt);
 354
 355     /**
 356      * Attempt to send a timing response to the master port by calling
 357      * its corresponding receive function. If the send does not
 358      * succeed, as indicated by the return value, then the sender must
 359      * wait for a recvRetry at which point it can re-issue a
 360      * sendTimingResp.
 361      *
 362      * @param pkt Packet to send.
 363      *
 364      * @return If the send was succesful or not.
 365     */
 366     bool sendTimingResp(PacketPtr pkt);
 367
 368     /**
 369      * Attempt to send a timing snoop request packet to the master port
 370      * by calling its corresponding receive function. Snoop requests
 371      * always succeed and hence no return value is needed.
 372      *
 373      * @param pkt Packet to send.
 374      */
 375     void sendTimingSnoopReq(PacketPtr pkt);
 376
 377     /**
 378      * Send a retry to the master port that previously attempted a
 379      * sendTimingReq or sendTimingSnoopResp to this slave port and
 380      * failed.
 381      */
 382     void sendRetry();
 383
 384     /**
 385      * Find out if the peer master port is snooping or not.
 386      *
 387      * @return true if the peer master port is snooping
 388      */
 389     bool isSnooping() const { return _masterPort->isSnooping(); }
 390
 391     /**
 392      * Called by the owner to send a range change
 393      */
 394     void sendRangeChange() const {
 395         if (!_masterPort)
 396             fatal("%s cannot sendRangeChange() without master port", name());
 397         _masterPort->recvRangeChange();
 398     }
 399
 400     /**
 401      * Get a list of the non-overlapping address ranges the owner is
 402      * responsible for. All slave ports must override this function
 403      * and return a populated list with at least one item.
 404      *
 405      * @return a list of ranges responded to
 406      */
 407     virtual AddrRangeList getAddrRanges() const = 0;
 408
 409   protected:
 410
 411     /**
 412      * Called by the master port to unbind. Should never be called
 413      * directly.
 414      */
 415     void unbind();
 416
 417     /**
 418      * Called by the master port to bind. Should never be called
 419      * directly.
 420      */
 421     void bind(MasterPort& master_port);
 422
 423     /**
 424      * Receive an atomic request packet from the master port.
 425      */
 426     virtual Tick recvAtomic(PacketPtr pkt) = 0;
 427
 428     /**
 429      * Receive a functional request packet from the master port.
 430      */
 431     virtual void recvFunctional(PacketPtr pkt) = 0;
 432
 433     /**
 434      * Receive a timing request from the master port.
 435      */
 436     virtual bool recvTimingReq(PacketPtr pkt) = 0;
 437
 438     /**
 439      * Receive a timing snoop response from the master port.
 440      */
 441     virtual bool recvTimingSnoopResp(PacketPtr pkt)
 442     {
 443         panic("%s was not expecting a timing snoop response\n", name());
 444     }
 445
 446     /**
 447      * Called by the master port if sendTimingResp was called on this
 448      * slave port (causing recvTimingResp to be called on the master
 449      * port) and was unsuccesful.
 450      */
 451     virtual void recvRetry() = 0;
 452
 453 };
 454
 455 #endif //__MEM_PORT_HH__