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 <list>
  54
  55 #include "base/range.hh"
  56 #include "mem/packet.hh"
  57
  58 /**
  59  * This typedef is used to clean up getAddrRanges(). It's declared
  60  * outside the Port object since it's also used by some mem objects.
  61  * Eventually we should move this typedef to wherever Addr is
  62  * defined.
  63  */
  64
  65 typedef std::list<Range<Addr> > AddrRangeList;
  66 typedef std::list<Range<Addr> >::iterator AddrRangeIter;
  67
  68 class MemObject;
  69
  70 /**
  71  * Ports are used to interface memory objects to each other. A port is
  72  * either a master or a slave and the connected peer is always of the
  73  * opposite role. Each port has a name, an owner, and an identifier.
  74  */
  75 class Port
  76 {
  77
  78   private:
  79
  80     /** Descriptive name (for DPRINTF output) */
  81     std::string portName;
  82
  83   protected:
  84
  85     /**
  86      * A numeric identifier to distinguish ports in a vector, and set
  87      * to InvalidPortID in case this port is not part of a vector.
  88      */
  89     const PortID id;
  90
  91     /** A reference to the MemObject that owns this port. */
  92     MemObject& owner;
  93
  94     /**
  95      * Abstract base class for ports
  96      *
  97      * @param _name Port name including the owners name
  98      * @param _owner The MemObject that is the structural owner of this port
  99      * @param _id A port identifier for vector ports
 100      */
 101     Port(const std::string& _name, MemObject& _owner, PortID _id);
 102
 103     /**
 104      * Virtual destructor due to inheritance.
 105      */
 106     virtual ~Port();
 107
 108   public:
 109
 110     /** Return port name (for DPRINTF). */
 111     const std::string name() const { return portName; }
 112
 113     /** Get the port id. */
 114     PortID getId() const { return id; }
 115
 116 };
 117
 118 /** Forward declaration */
 119 class SlavePort;
 120
 121 /**
 122  * A MasterPort is a specialisation of a port. In addition to the
 123  * basic functionality of sending packets to its slave peer, it also
 124  * has functions specific to a master, e.g. to receive range changes
 125  * or determine if the port is snooping or not.
 126  */
 127 class MasterPort : public Port
 128 {
 129
 130     friend class SlavePort;
 131
 132   private:
 133
 134     SlavePort* _slavePort;
 135
 136   public:
 137
 138     MasterPort(const std::string& name, MemObject* owner,
 139                PortID id = InvalidPortID);
 140     virtual ~MasterPort();
 141
 142     void bind(SlavePort& slave_port);
 143     SlavePort& getSlavePort() const;
 144     bool isConnected() const;
 145
 146     /**
 147      * Send an atomic request packet, where the data is moved and the
 148      * state is updated in zero time, without interleaving with other
 149      * memory accesses.
 150      *
 151      * @param pkt Packet to send.
 152      *
 153      * @return Estimated latency of access.
 154      */
 155     Tick sendAtomic(PacketPtr pkt);
 156
 157     /**
 158      * Send a functional request packet, where the data is instantly
 159      * updated everywhere in the memory system, without affecting the
 160      * current state of any block or moving the block.
 161      *
 162      * @param pkt Packet to send.
 163      */
 164     void sendFunctional(PacketPtr pkt);
 165
 166     /**
 167      * Attempt to send a timing request to the slave port by calling
 168      * its corresponding receive function. If the send does not
 169      * succeed, as indicated by the return value, then the sender must
 170      * wait for a recvRetry at which point it can re-issue a
 171      * sendTimingReq.
 172      *
 173      * @param pkt Packet to send.
 174      *
 175      * @return If the send was succesful or not.
 176     */
 177     bool sendTimingReq(PacketPtr pkt);
 178
 179     /**
 180      * Attempt to send a timing snoop response packet to the slave
 181      * port by calling its corresponding receive function. If the send
 182      * does not succeed, as indicated by the return value, then the
 183      * sender must wait for a recvRetry at which point it can re-issue
 184      * a sendTimingSnoopResp.
 185      *
 186      * @param pkt Packet to send.
 187      */
 188     bool sendTimingSnoopResp(PacketPtr pkt);
 189
 190     /**
 191      * Send a retry to the slave port that previously attempted a
 192      * sendTimingResp to this master port and failed.
 193      */
 194     void sendRetry();
 195
 196     /**
 197      * Determine if this master port is snooping or not. The default
 198      * implementation returns false and thus tells the neighbour we
 199      * are not snooping. Any master port that wants to receive snoop
 200      * requests (e.g. a cache connected to a bus) has to override this
 201      * function.
 202      *
 203      * @return true if the port should be considered a snooper
 204      */
 205     virtual bool isSnooping() const { return false; }
 206
 207     /**
 208      * Called by a peer port in order to determine the block size of
 209      * the owner of this port.
 210      */
 211     virtual unsigned deviceBlockSize() const { return 0; }
 212
 213     /** Called by the associated device if it wishes to find out the blocksize
 214         of the device on attached to the peer port.
 215     */
 216     unsigned peerBlockSize() const;
 217
 218     /** Inject a PrintReq for the given address to print the state of
 219      * that address throughout the memory system.  For debugging.
 220      */
 221     void printAddr(Addr a);
 222
 223   protected:
 224
 225     /**
 226      * Receive an atomic snoop request packet from the slave port.
 227      */
 228     virtual Tick recvAtomicSnoop(PacketPtr pkt)
 229     {
 230         panic("%s was not expecting an atomic snoop request\n", name());
 231         return 0;
 232     }
 233
 234     /**
 235      * Receive a functional snoop request packet from the slave port.
 236      */
 237     virtual void recvFunctionalSnoop(PacketPtr pkt)
 238     {
 239         panic("%s was not expecting a functional snoop request\n", name());
 240     }
 241
 242     /**
 243      * Receive a timing response from the slave port.
 244      */
 245     virtual bool recvTimingResp(PacketPtr pkt) = 0;
 246
 247     /**
 248      * Receive a timing snoop request from the slave port.
 249      */
 250     virtual void recvTimingSnoopReq(PacketPtr pkt)
 251     {
 252         panic("%s was not expecting a timing snoop request\n", name());
 253     }
 254
 255     /**
 256      * Called by the slave port if sendTimingReq or
 257      * sendTimingSnoopResp was called on this master port (causing
 258      * recvTimingReq and recvTimingSnoopResp to be called on the
 259      * slave port) and was unsuccesful.
 260      */
 261     virtual void recvRetry() = 0;
 262
 263     /**
 264      * Called to receive an address range change from the peer slave
 265      * port. the default implementation ignored the change and does
 266      * nothing. Override this function in a derived class if the owner
 267      * needs to be aware of he laesddress ranges, e.g. in an
 268      * interconnect component like a bus.
 269      */
 270     virtual void recvRangeChange() { }
 271 };
 272
 273 /**
 274  * A SlavePort is a specialisation of a port. In addition to the
 275  * basic functionality of sending packets to its master peer, it also
 276  * has functions specific to a slave, e.g. to send range changes
 277  * and get the address ranges that the port responds to.
 278  */
 279 class SlavePort : public Port
 280 {
 281
 282     friend class MasterPort;
 283
 284   private:
 285
 286     MasterPort* _masterPort;
 287
 288   public:
 289
 290     SlavePort(const std::string& name, MemObject* owner,
 291               PortID id = InvalidPortID);
 292     virtual ~SlavePort();
 293
 294     void bind(MasterPort& master_port);
 295     MasterPort& getMasterPort() const;
 296     bool isConnected() const;
 297
 298     /**
 299      * Send an atomic snoop request packet, where the data is moved
 300      * and the state is updated in zero time, without interleaving
 301      * with other memory accesses.
 302      *
 303      * @param pkt Snoop packet to send.
 304      *
 305      * @return Estimated latency of access.
 306      */
 307     Tick sendAtomicSnoop(PacketPtr pkt);
 308
 309     /**
 310      * Send a functional snoop request packet, where the data is
 311      * instantly updated everywhere in the memory system, without
 312      * affecting the current state of any block or moving the block.
 313      *
 314      * @param pkt Snoop packet to send.
 315      */
 316     void sendFunctionalSnoop(PacketPtr pkt);
 317
 318     /**
 319      * Attempt to send a timing response to the master port by calling
 320      * its corresponding receive function. If the send does not
 321      * succeed, as indicated by the return value, then the sender must
 322      * wait for a recvRetry at which point it can re-issue a
 323      * sendTimingResp.
 324      *
 325      * @param pkt Packet to send.
 326      *
 327      * @return If the send was succesful or not.
 328     */
 329     bool sendTimingResp(PacketPtr pkt);
 330
 331     /**
 332      * Attempt to send a timing snoop request packet to the master port
 333      * by calling its corresponding receive function. Snoop requests
 334      * always succeed and hence no return value is needed.
 335      *
 336      * @param pkt Packet to send.
 337      */
 338     void sendTimingSnoopReq(PacketPtr pkt);
 339
 340     /**
 341      * Send a retry to the master port that previously attempted a
 342      * sendTimingReq or sendTimingSnoopResp to this slave port and
 343      * failed.
 344      */
 345     void sendRetry();
 346
 347     /**
 348      * Called by a peer port in order to determine the block size of
 349      * the owner of this port.
 350      */
 351     virtual unsigned deviceBlockSize() const { return 0; }
 352
 353     /** Called by the associated device if it wishes to find out the blocksize
 354         of the device on attached to the peer port.
 355     */
 356     unsigned peerBlockSize() const;
 357
 358     /**
 359      * Find out if the peer master port is snooping or not.
 360      *
 361      * @return true if the peer master port is snooping
 362      */
 363     bool isSnooping() const { return _masterPort->isSnooping(); }
 364
 365     /**
 366      * Called by the owner to send a range change
 367      */
 368     void sendRangeChange() const { _masterPort->recvRangeChange(); }
 369
 370     /**
 371      * Get a list of the non-overlapping address ranges the owner is
 372      * responsible for. All slave ports must override this function
 373      * and return a populated list with at least one item.
 374      *
 375      * @return a list of ranges responded to
 376      */
 377     virtual AddrRangeList getAddrRanges() = 0;
 378
 379   protected:
 380
 381     /**
 382      * Receive an atomic request packet from the master port.
 383      */
 384     virtual Tick recvAtomic(PacketPtr pkt) = 0;
 385
 386     /**
 387      * Receive a functional request packet from the master port.
 388      */
 389     virtual void recvFunctional(PacketPtr pkt) = 0;
 390
 391     /**
 392      * Receive a timing request from the master port.
 393      */
 394     virtual bool recvTimingReq(PacketPtr pkt) = 0;
 395
 396     /**
 397      * Receive a timing snoop response from the master port.
 398      */
 399     virtual bool recvTimingSnoopResp(PacketPtr pkt)
 400     {
 401         panic("%s was not expecting a timing snoop response\n", name());
 402     }
 403
 404     /**
 405      * Called by the master port if sendTimingResp was called on this
 406      * slave port (causing recvTimingResp to be called on the master
 407      * port) and was unsuccesful.
 408      */
 409     virtual void recvRetry() = 0;
 410
 411 };
 412
 413 #endif //__MEM_PORT_HH__