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