port.hh revision 9087:b5a084a6159b
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 /** 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 */ 279class 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 * Called by the owner to send a range change 360 */ 361 void sendRangeChange() const { _masterPort->recvRangeChange(); } 362 363 /** 364 * Get a list of the non-overlapping address ranges the owner is 365 * responsible for. All slave ports must override this function 366 * and return a populated list with at least one item. 367 * 368 * @return a list of ranges responded to 369 */ 370 virtual AddrRangeList getAddrRanges() = 0; 371 372 protected: 373 374 /** 375 * Receive an atomic request packet from the master port. 376 */ 377 virtual Tick recvAtomic(PacketPtr pkt) = 0; 378 379 /** 380 * Receive a functional request packet from the master port. 381 */ 382 virtual void recvFunctional(PacketPtr pkt) = 0; 383 384 /** 385 * Receive a timing request from the master port. 386 */ 387 virtual bool recvTimingReq(PacketPtr pkt) = 0; 388 389 /** 390 * Receive a timing snoop response from the master port. 391 */ 392 virtual bool recvTimingSnoopResp(PacketPtr pkt) 393 { 394 panic("%s was not expecting a timing snoop response\n", name()); 395 } 396 397 /** 398 * Called by the master port if sendTimingResp was called on this 399 * slave port (causing recvTimingResp to be called on the master 400 * port) and was unsuccesful. 401 */ 402 virtual void recvRetry() = 0; 403 404}; 405 406#endif //__MEM_PORT_HH__ 407