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