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