port.hh revision 9178:6a0ff1770e6e
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 65typedef std::list<Range<Addr> > AddrRangeList; 66typedef std::list<Range<Addr> >::iterator AddrRangeIter; 67typedef std::list<Range<Addr> >::const_iterator AddrRangeConstIter; 68 69class 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 */ 76class 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 */ 120class 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 */ 128class 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 /** 144 * Bind this master port to a slave port. This also does the 145 * mirror action and binds the slave port to the master port. 146 */ 147 void bind(SlavePort& slave_port); 148 149 /** 150 * Unbind this master port and the associated slave port. 151 */ 152 void unbind(); 153 154 SlavePort& getSlavePort() const; 155 bool isConnected() const; 156 157 /** 158 * Send an atomic request packet, where the data is moved and the 159 * state is updated in zero time, without interleaving with other 160 * memory accesses. 161 * 162 * @param pkt Packet to send. 163 * 164 * @return Estimated latency of access. 165 */ 166 Tick sendAtomic(PacketPtr pkt); 167 168 /** 169 * Send a functional request packet, where the data is instantly 170 * updated everywhere in the memory system, without affecting the 171 * current state of any block or moving the block. 172 * 173 * @param pkt Packet to send. 174 */ 175 void sendFunctional(PacketPtr pkt); 176 177 /** 178 * Attempt to send a timing request to the slave port by calling 179 * its corresponding receive function. If the send does not 180 * succeed, as indicated by the return value, then the sender must 181 * wait for a recvRetry at which point it can re-issue a 182 * sendTimingReq. 183 * 184 * @param pkt Packet to send. 185 * 186 * @return If the send was succesful or not. 187 */ 188 bool sendTimingReq(PacketPtr pkt); 189 190 /** 191 * Attempt to send a timing snoop response packet to the slave 192 * port by calling its corresponding receive function. If the send 193 * does not succeed, as indicated by the return value, then the 194 * sender must wait for a recvRetry at which point it can re-issue 195 * a sendTimingSnoopResp. 196 * 197 * @param pkt Packet to send. 198 */ 199 bool sendTimingSnoopResp(PacketPtr pkt); 200 201 /** 202 * Send a retry to the slave port that previously attempted a 203 * sendTimingResp to this master port and failed. 204 */ 205 void sendRetry(); 206 207 /** 208 * Determine if this master port is snooping or not. The default 209 * implementation returns false and thus tells the neighbour we 210 * are not snooping. Any master port that wants to receive snoop 211 * requests (e.g. a cache connected to a bus) has to override this 212 * function. 213 * 214 * @return true if the port should be considered a snooper 215 */ 216 virtual bool isSnooping() const { return false; } 217 218 /** 219 * Called by a peer port in order to determine the block size of 220 * the owner of this port. 221 */ 222 virtual unsigned deviceBlockSize() const { return 0; } 223 224 /** Called by the associated device if it wishes to find out the blocksize 225 of the device on attached to the peer port. 226 */ 227 unsigned peerBlockSize() const; 228 229 /** 230 * Get the address ranges of the connected slave port. 231 */ 232 AddrRangeList getAddrRanges() const; 233 234 /** Inject a PrintReq for the given address to print the state of 235 * that address throughout the memory system. For debugging. 236 */ 237 void printAddr(Addr a); 238 239 protected: 240 241 /** 242 * Receive an atomic snoop request packet from the slave port. 243 */ 244 virtual Tick recvAtomicSnoop(PacketPtr pkt) 245 { 246 panic("%s was not expecting an atomic snoop request\n", name()); 247 return 0; 248 } 249 250 /** 251 * Receive a functional snoop request packet from the slave port. 252 */ 253 virtual void recvFunctionalSnoop(PacketPtr pkt) 254 { 255 panic("%s was not expecting a functional snoop request\n", name()); 256 } 257 258 /** 259 * Receive a timing response from the slave port. 260 */ 261 virtual bool recvTimingResp(PacketPtr pkt) = 0; 262 263 /** 264 * Receive a timing snoop request from the slave port. 265 */ 266 virtual void recvTimingSnoopReq(PacketPtr pkt) 267 { 268 panic("%s was not expecting a timing snoop request\n", name()); 269 } 270 271 /** 272 * Called by the slave port if sendTimingReq or 273 * sendTimingSnoopResp was called on this master port (causing 274 * recvTimingReq and recvTimingSnoopResp to be called on the 275 * slave port) and was unsuccesful. 276 */ 277 virtual void recvRetry() = 0; 278 279 /** 280 * Called to receive an address range change from the peer slave 281 * port. the default implementation ignored the change and does 282 * nothing. Override this function in a derived class if the owner 283 * needs to be aware of he laesddress ranges, e.g. in an 284 * interconnect component like a bus. 285 */ 286 virtual void recvRangeChange() { } 287}; 288 289/** 290 * A SlavePort is a specialisation of a port. In addition to the 291 * basic functionality of sending packets to its master peer, it also 292 * has functions specific to a slave, e.g. to send range changes 293 * and get the address ranges that the port responds to. 294 */ 295class SlavePort : public Port 296{ 297 298 friend class MasterPort; 299 300 private: 301 302 MasterPort* _masterPort; 303 304 public: 305 306 SlavePort(const std::string& name, MemObject* owner, 307 PortID id = InvalidPortID); 308 virtual ~SlavePort(); 309 310 MasterPort& getMasterPort() const; 311 bool isConnected() const; 312 313 /** 314 * Send an atomic snoop request packet, where the data is moved 315 * and the state is updated in zero time, without interleaving 316 * with other memory accesses. 317 * 318 * @param pkt Snoop packet to send. 319 * 320 * @return Estimated latency of access. 321 */ 322 Tick sendAtomicSnoop(PacketPtr pkt); 323 324 /** 325 * Send a functional snoop request packet, where the data is 326 * instantly updated everywhere in the memory system, without 327 * affecting the current state of any block or moving the block. 328 * 329 * @param pkt Snoop packet to send. 330 */ 331 void sendFunctionalSnoop(PacketPtr pkt); 332 333 /** 334 * Attempt to send a timing response to the master port by calling 335 * its corresponding receive function. If the send does not 336 * succeed, as indicated by the return value, then the sender must 337 * wait for a recvRetry at which point it can re-issue a 338 * sendTimingResp. 339 * 340 * @param pkt Packet to send. 341 * 342 * @return If the send was succesful or not. 343 */ 344 bool sendTimingResp(PacketPtr pkt); 345 346 /** 347 * Attempt to send a timing snoop request packet to the master port 348 * by calling its corresponding receive function. Snoop requests 349 * always succeed and hence no return value is needed. 350 * 351 * @param pkt Packet to send. 352 */ 353 void sendTimingSnoopReq(PacketPtr pkt); 354 355 /** 356 * Send a retry to the master port that previously attempted a 357 * sendTimingReq or sendTimingSnoopResp to this slave port and 358 * failed. 359 */ 360 void sendRetry(); 361 362 /** 363 * Called by a peer port in order to determine the block size of 364 * the owner of this port. 365 */ 366 virtual unsigned deviceBlockSize() const { return 0; } 367 368 /** Called by the associated device if it wishes to find out the blocksize 369 of the device on attached to the peer port. 370 */ 371 unsigned peerBlockSize() const; 372 373 /** 374 * Find out if the peer master port is snooping or not. 375 * 376 * @return true if the peer master port is snooping 377 */ 378 bool isSnooping() const { return _masterPort->isSnooping(); } 379 380 /** 381 * Called by the owner to send a range change 382 */ 383 void sendRangeChange() const { _masterPort->recvRangeChange(); } 384 385 /** 386 * Get a list of the non-overlapping address ranges the owner is 387 * responsible for. All slave ports must override this function 388 * and return a populated list with at least one item. 389 * 390 * @return a list of ranges responded to 391 */ 392 virtual AddrRangeList getAddrRanges() const = 0; 393 394 protected: 395 396 /** 397 * Called by the master port to unbind. Should never be called 398 * directly. 399 */ 400 void unbind(); 401 402 /** 403 * Called by the master port to bind. Should never be called 404 * directly. 405 */ 406 void bind(MasterPort& master_port); 407 408 /** 409 * Receive an atomic request packet from the master port. 410 */ 411 virtual Tick recvAtomic(PacketPtr pkt) = 0; 412 413 /** 414 * Receive a functional request packet from the master port. 415 */ 416 virtual void recvFunctional(PacketPtr pkt) = 0; 417 418 /** 419 * Receive a timing request from the master port. 420 */ 421 virtual bool recvTimingReq(PacketPtr pkt) = 0; 422 423 /** 424 * Receive a timing snoop response from the master port. 425 */ 426 virtual bool recvTimingSnoopResp(PacketPtr pkt) 427 { 428 panic("%s was not expecting a timing snoop response\n", name()); 429 } 430 431 /** 432 * Called by the master port if sendTimingResp was called on this 433 * slave port (causing recvTimingResp to be called on the master 434 * port) and was unsuccesful. 435 */ 436 virtual void recvRetry() = 0; 437 438}; 439 440#endif //__MEM_PORT_HH__ 441