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