port.hh revision 8965
12381SN/A/* 28853Sandreas.hansson@arm.com * Copyright (c) 2011-2012 ARM Limited 38711Sandreas.hansson@arm.com * All rights reserved 48711Sandreas.hansson@arm.com * 58711Sandreas.hansson@arm.com * The license below extends only to copyright in the software and shall 68711Sandreas.hansson@arm.com * not be construed as granting a license to any other intellectual 78711Sandreas.hansson@arm.com * property including but not limited to intellectual property relating 88711Sandreas.hansson@arm.com * to a hardware implementation of the functionality of the software 98711Sandreas.hansson@arm.com * licensed hereunder. You may use the software subject to the license 108711Sandreas.hansson@arm.com * terms below provided that you ensure that this notice is replicated 118711Sandreas.hansson@arm.com * unmodified and in its entirety in all distributions of the software, 128711Sandreas.hansson@arm.com * modified or unmodified, in source code or in binary form. 138711Sandreas.hansson@arm.com * 142381SN/A * Copyright (c) 2002-2005 The Regents of The University of Michigan 152381SN/A * All rights reserved. 162381SN/A * 172381SN/A * Redistribution and use in source and binary forms, with or without 182381SN/A * modification, are permitted provided that the following conditions are 192381SN/A * met: redistributions of source code must retain the above copyright 202381SN/A * notice, this list of conditions and the following disclaimer; 212381SN/A * redistributions in binary form must reproduce the above copyright 222381SN/A * notice, this list of conditions and the following disclaimer in the 232381SN/A * documentation and/or other materials provided with the distribution; 242381SN/A * neither the name of the copyright holders nor the names of its 252381SN/A * contributors may be used to endorse or promote products derived from 262381SN/A * this software without specific prior written permission. 272381SN/A * 282381SN/A * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 292381SN/A * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 302381SN/A * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 312381SN/A * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 322381SN/A * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 332381SN/A * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 342381SN/A * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 352381SN/A * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 362381SN/A * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 372381SN/A * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 382381SN/A * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 392665Ssaidi@eecs.umich.edu * 402665Ssaidi@eecs.umich.edu * Authors: Ron Dreslinski 418853Sandreas.hansson@arm.com * Andreas Hansson 428922Swilliam.wang@arm.com * William Wang 432381SN/A */ 442381SN/A 452381SN/A/** 462381SN/A * @file 478922Swilliam.wang@arm.com * Port Object Declaration. 482381SN/A */ 492381SN/A 502381SN/A#ifndef __MEM_PORT_HH__ 512381SN/A#define __MEM_PORT_HH__ 522381SN/A 532381SN/A#include <list> 542381SN/A 552381SN/A#include "base/range.hh" 562381SN/A#include "mem/packet.hh" 572381SN/A 588922Swilliam.wang@arm.com/** 598922Swilliam.wang@arm.com * This typedef is used to clean up getAddrRanges(). It's declared 602407SN/A * outside the Port object since it's also used by some mem objects. 612407SN/A * Eventually we should move this typedef to wherever Addr is 622407SN/A * defined. 632407SN/A */ 642407SN/A 652407SN/Atypedef std::list<Range<Addr> > AddrRangeList; 662521SN/Atypedef std::list<Range<Addr> >::iterator AddrRangeIter; 672407SN/A 683401Sktlim@umich.educlass MemObject; 693401Sktlim@umich.edu 702381SN/A/** 718922Swilliam.wang@arm.com * Ports are used to interface memory objects to each other. A port is 728922Swilliam.wang@arm.com * either a master or a slave and the connected peer is always of the 738922Swilliam.wang@arm.com * opposite role. 742381SN/A * 758922Swilliam.wang@arm.com * Each port has a name and an owner, and enables three basic types of 768922Swilliam.wang@arm.com * accesses to the peer port: sendFunctional, sendAtomic and 778922Swilliam.wang@arm.com * sendTiming. 782381SN/A */ 798708Sandreas.hansson@arm.comclass Port 802381SN/A{ 818922Swilliam.wang@arm.com 828965Sandreas.hansson@arm.com public: 838965Sandreas.hansson@arm.com 848965Sandreas.hansson@arm.com /** A type name for the port identifier. */ 858965Sandreas.hansson@arm.com typedef int PortId; 868965Sandreas.hansson@arm.com 878965Sandreas.hansson@arm.com /** A symbolic name for the absence of a port id. */ 888965Sandreas.hansson@arm.com static const PortId INVALID_PORT_ID = -1; 898965Sandreas.hansson@arm.com 908922Swilliam.wang@arm.com private: 918922Swilliam.wang@arm.com 928922Swilliam.wang@arm.com /** Descriptive name (for DPRINTF output) */ 938922Swilliam.wang@arm.com std::string portName; 948922Swilliam.wang@arm.com 955476Snate@binkert.org protected: 962640Sstever@eecs.umich.edu 978965Sandreas.hansson@arm.com /** 988965Sandreas.hansson@arm.com * A numeric identifier to distinguish ports in a vector, and set 998965Sandreas.hansson@arm.com * to INVALID_PORT_ID in case this port is not part of a vector. 1008965Sandreas.hansson@arm.com */ 1018965Sandreas.hansson@arm.com const PortId id; 1028965Sandreas.hansson@arm.com 1038922Swilliam.wang@arm.com /** A pointer to the peer port. */ 1048922Swilliam.wang@arm.com Port* peer; 1052661Sstever@eecs.umich.edu 1068922Swilliam.wang@arm.com /** A reference to the MemObject that owns this port. */ 1078922Swilliam.wang@arm.com MemObject& owner; 1088922Swilliam.wang@arm.com 1098922Swilliam.wang@arm.com /** 1108922Swilliam.wang@arm.com * Abstract base class for ports 1118922Swilliam.wang@arm.com * 1128922Swilliam.wang@arm.com * @param _name Port name including the owners name 1138922Swilliam.wang@arm.com * @param _owner The MemObject that is the structural owner of this port 1148965Sandreas.hansson@arm.com * @param _id A port identifier for vector ports 1158922Swilliam.wang@arm.com */ 1168965Sandreas.hansson@arm.com Port(const std::string& _name, MemObject& _owner, PortId _id); 1178922Swilliam.wang@arm.com 1188922Swilliam.wang@arm.com /** 1198922Swilliam.wang@arm.com * Virtual destructor due to inheritance. 1208922Swilliam.wang@arm.com */ 1218922Swilliam.wang@arm.com virtual ~Port(); 1223401Sktlim@umich.edu 1232381SN/A public: 1242640Sstever@eecs.umich.edu 1252640Sstever@eecs.umich.edu /** Return port name (for DPRINTF). */ 1268922Swilliam.wang@arm.com const std::string name() const { return portName; } 1274190Ssaidi@eecs.umich.edu 1288965Sandreas.hansson@arm.com /** Get the port id. */ 1298965Sandreas.hansson@arm.com PortId getId() const { return id; } 1308965Sandreas.hansson@arm.com 1312381SN/A protected: 1322381SN/A 1332406SN/A /** These functions are protected because they should only be 1342406SN/A * called by a peer port, never directly by any outside object. */ 1352406SN/A 1368948Sandreas.hansson@arm.com /** 1378948Sandreas.hansson@arm.com * Receive a timing request or response packet from the peer port. 1388948Sandreas.hansson@arm.com */ 1393349Sbinkertn@umich.edu virtual bool recvTiming(PacketPtr pkt) = 0; 1402381SN/A 1418948Sandreas.hansson@arm.com /** 1428948Sandreas.hansson@arm.com * Receive a timing snoop request or snoop response packet from 1438948Sandreas.hansson@arm.com * the peer port. 1448948Sandreas.hansson@arm.com */ 1458948Sandreas.hansson@arm.com virtual bool recvTimingSnoop(PacketPtr pkt) 1468948Sandreas.hansson@arm.com { 1478948Sandreas.hansson@arm.com panic("%s was not expecting a timing snoop\n", name()); 1488948Sandreas.hansson@arm.com return false; 1498948Sandreas.hansson@arm.com } 1502381SN/A 1518922Swilliam.wang@arm.com /** 1528948Sandreas.hansson@arm.com * Called by a peer port if sendTiming or sendTimingSnoop was 1538948Sandreas.hansson@arm.com * unsuccesful, and had to wait. 1548922Swilliam.wang@arm.com */ 1558922Swilliam.wang@arm.com virtual void recvRetry() = 0; 1562381SN/A 1578711Sandreas.hansson@arm.com public: 1582381SN/A 1598711Sandreas.hansson@arm.com /** 1608948Sandreas.hansson@arm.com * Attempt to send a timing request or response packet to the peer 1618948Sandreas.hansson@arm.com * port by calling its receive function. If the send does not 1628948Sandreas.hansson@arm.com * succeed, as indicated by the return value, then the sender must 1638948Sandreas.hansson@arm.com * wait for a recvRetry at which point it can re-issue a 1648948Sandreas.hansson@arm.com * sendTiming. 1658711Sandreas.hansson@arm.com * 1668922Swilliam.wang@arm.com * @param pkt Packet to send. 1678922Swilliam.wang@arm.com * 1688922Swilliam.wang@arm.com * @return If the send was succesful or not. 1698922Swilliam.wang@arm.com */ 1708922Swilliam.wang@arm.com bool sendTiming(PacketPtr pkt) { return peer->recvTiming(pkt); } 1718711Sandreas.hansson@arm.com 1728711Sandreas.hansson@arm.com /** 1738948Sandreas.hansson@arm.com * Attempt to send a timing snoop request or snoop response packet 1748948Sandreas.hansson@arm.com * to the peer port by calling its receive function. If the send 1758948Sandreas.hansson@arm.com * does not succeed, as indicated by the return value, then the 1768948Sandreas.hansson@arm.com * sender must wait for a recvRetry at which point it can re-issue 1778948Sandreas.hansson@arm.com * a sendTimingSnoop. 1788922Swilliam.wang@arm.com * 1798922Swilliam.wang@arm.com * @param pkt Packet to send. 1808922Swilliam.wang@arm.com * 1818948Sandreas.hansson@arm.com * @return If the send was succesful or not. 1828948Sandreas.hansson@arm.com */ 1838948Sandreas.hansson@arm.com bool sendTimingSnoop(PacketPtr pkt) { return peer->recvTimingSnoop(pkt); } 1848922Swilliam.wang@arm.com 1858922Swilliam.wang@arm.com /** 1868948Sandreas.hansson@arm.com * Send a retry to a peer port that previously attempted a 1878948Sandreas.hansson@arm.com * sendTiming or sendTimingSnoop which was unsuccessful. 1888922Swilliam.wang@arm.com */ 1898948Sandreas.hansson@arm.com void sendRetry() { return peer->recvRetry(); } 1908922Swilliam.wang@arm.com 1918922Swilliam.wang@arm.com}; 1928922Swilliam.wang@arm.com 1938922Swilliam.wang@arm.com/** Forward declaration */ 1948922Swilliam.wang@arm.comclass SlavePort; 1958922Swilliam.wang@arm.com 1968922Swilliam.wang@arm.com/** 1978922Swilliam.wang@arm.com * A MasterPort is a specialisation of a port. In addition to the 1988922Swilliam.wang@arm.com * basic functionality of sending packets to its slave peer, it also 1998922Swilliam.wang@arm.com * has functions specific to a master, e.g. to receive range changes 2008922Swilliam.wang@arm.com * or determine if the port is snooping or not. 2018922Swilliam.wang@arm.com */ 2028922Swilliam.wang@arm.comclass MasterPort : public Port 2038922Swilliam.wang@arm.com{ 2048922Swilliam.wang@arm.com 2058922Swilliam.wang@arm.com private: 2068922Swilliam.wang@arm.com 2078922Swilliam.wang@arm.com SlavePort* _slavePort; 2088922Swilliam.wang@arm.com 2098922Swilliam.wang@arm.com public: 2108922Swilliam.wang@arm.com 2118965Sandreas.hansson@arm.com MasterPort(const std::string& name, MemObject* owner, 2128965Sandreas.hansson@arm.com PortId id = INVALID_PORT_ID); 2138922Swilliam.wang@arm.com virtual ~MasterPort(); 2148922Swilliam.wang@arm.com 2158922Swilliam.wang@arm.com void bind(SlavePort& slave_port); 2168922Swilliam.wang@arm.com SlavePort& getSlavePort() const; 2178922Swilliam.wang@arm.com bool isConnected() const; 2188922Swilliam.wang@arm.com 2198922Swilliam.wang@arm.com /** 2208948Sandreas.hansson@arm.com * Send an atomic request packet, where the data is moved and the 2218948Sandreas.hansson@arm.com * state is updated in zero time, without interleaving with other 2228948Sandreas.hansson@arm.com * memory accesses. 2238948Sandreas.hansson@arm.com * 2248948Sandreas.hansson@arm.com * @param pkt Packet to send. 2258948Sandreas.hansson@arm.com * 2268948Sandreas.hansson@arm.com * @return Estimated latency of access. 2278948Sandreas.hansson@arm.com */ 2288948Sandreas.hansson@arm.com Tick sendAtomic(PacketPtr pkt); 2298948Sandreas.hansson@arm.com 2308948Sandreas.hansson@arm.com /** 2318948Sandreas.hansson@arm.com * Send a functional request packet, where the data is instantly 2328948Sandreas.hansson@arm.com * updated everywhere in the memory system, without affecting the 2338948Sandreas.hansson@arm.com * current state of any block or moving the block. 2348948Sandreas.hansson@arm.com * 2358948Sandreas.hansson@arm.com * @param pkt Packet to send. 2368948Sandreas.hansson@arm.com */ 2378948Sandreas.hansson@arm.com void sendFunctional(PacketPtr pkt); 2388948Sandreas.hansson@arm.com 2398948Sandreas.hansson@arm.com /** 2408948Sandreas.hansson@arm.com * Receive an atomic snoop request packet from the slave port. 2418948Sandreas.hansson@arm.com */ 2428948Sandreas.hansson@arm.com virtual Tick recvAtomicSnoop(PacketPtr pkt) 2438948Sandreas.hansson@arm.com { 2448948Sandreas.hansson@arm.com panic("%s was not expecting an atomic snoop\n", name()); 2458948Sandreas.hansson@arm.com return 0; 2468948Sandreas.hansson@arm.com } 2478948Sandreas.hansson@arm.com 2488948Sandreas.hansson@arm.com /** 2498948Sandreas.hansson@arm.com * Receive a functional snoop request packet from the slave port. 2508948Sandreas.hansson@arm.com */ 2518948Sandreas.hansson@arm.com virtual void recvFunctionalSnoop(PacketPtr pkt) 2528948Sandreas.hansson@arm.com { 2538948Sandreas.hansson@arm.com panic("%s was not expecting a functional snoop\n", name()); 2548948Sandreas.hansson@arm.com } 2558948Sandreas.hansson@arm.com 2568948Sandreas.hansson@arm.com /** 2578922Swilliam.wang@arm.com * Called to receive an address range change from the peer slave 2588922Swilliam.wang@arm.com * port. the default implementation ignored the change and does 2598922Swilliam.wang@arm.com * nothing. Override this function in a derived class if the owner 2608922Swilliam.wang@arm.com * needs to be aware of he laesddress ranges, e.g. in an 2618922Swilliam.wang@arm.com * interconnect component like a bus. 2628922Swilliam.wang@arm.com */ 2638922Swilliam.wang@arm.com virtual void recvRangeChange() { } 2648922Swilliam.wang@arm.com 2658922Swilliam.wang@arm.com /** 2668922Swilliam.wang@arm.com * Determine if this master port is snooping or not. The default 2678711Sandreas.hansson@arm.com * implementation returns false and thus tells the neighbour we 2688922Swilliam.wang@arm.com * are not snooping. Any master port that wants to receive snoop 2698922Swilliam.wang@arm.com * requests (e.g. a cache connected to a bus) has to override this 2708922Swilliam.wang@arm.com * function. 2718711Sandreas.hansson@arm.com * 2728711Sandreas.hansson@arm.com * @return true if the port should be considered a snooper 2738711Sandreas.hansson@arm.com */ 2748922Swilliam.wang@arm.com virtual bool isSnooping() const { return false; } 2752381SN/A 2768711Sandreas.hansson@arm.com /** 2778922Swilliam.wang@arm.com * Called by a peer port in order to determine the block size of 2788922Swilliam.wang@arm.com * the owner of this port. 2798711Sandreas.hansson@arm.com */ 2808922Swilliam.wang@arm.com virtual unsigned deviceBlockSize() const { return 0; } 2812381SN/A 2822381SN/A /** Called by the associated device if it wishes to find out the blocksize 2832381SN/A of the device on attached to the peer port. 2842381SN/A */ 2858922Swilliam.wang@arm.com unsigned peerBlockSize() const; 2862381SN/A 2875314Sstever@gmail.com /** Inject a PrintReq for the given address to print the state of 2885314Sstever@gmail.com * that address throughout the memory system. For debugging. 2895314Sstever@gmail.com */ 2905314Sstever@gmail.com void printAddr(Addr a); 2912381SN/A}; 2922381SN/A 2938922Swilliam.wang@arm.com/** 2948922Swilliam.wang@arm.com * A SlavePort is a specialisation of a port. In addition to the 2958922Swilliam.wang@arm.com * basic functionality of sending packets to its master peer, it also 2968922Swilliam.wang@arm.com * has functions specific to a slave, e.g. to send range changes 2978922Swilliam.wang@arm.com * and get the address ranges that the port responds to. 2988922Swilliam.wang@arm.com */ 2998922Swilliam.wang@arm.comclass SlavePort : public Port 3008922Swilliam.wang@arm.com{ 3018922Swilliam.wang@arm.com 3028922Swilliam.wang@arm.com private: 3038922Swilliam.wang@arm.com 3048922Swilliam.wang@arm.com MasterPort* _masterPort; 3058922Swilliam.wang@arm.com 3068922Swilliam.wang@arm.com public: 3078922Swilliam.wang@arm.com 3088965Sandreas.hansson@arm.com SlavePort(const std::string& name, MemObject* owner, 3098965Sandreas.hansson@arm.com PortId id = INVALID_PORT_ID); 3108922Swilliam.wang@arm.com virtual ~SlavePort(); 3118922Swilliam.wang@arm.com 3128922Swilliam.wang@arm.com void bind(MasterPort& master_port); 3138922Swilliam.wang@arm.com MasterPort& getMasterPort() const; 3148922Swilliam.wang@arm.com bool isConnected() const; 3158922Swilliam.wang@arm.com 3168922Swilliam.wang@arm.com /** 3178948Sandreas.hansson@arm.com * Send an atomic snoop request packet, where the data is moved 3188948Sandreas.hansson@arm.com * and the state is updated in zero time, without interleaving 3198948Sandreas.hansson@arm.com * with other memory accesses. 3208948Sandreas.hansson@arm.com * 3218948Sandreas.hansson@arm.com * @param pkt Snoop packet to send. 3228948Sandreas.hansson@arm.com * 3238948Sandreas.hansson@arm.com * @return Estimated latency of access. 3248948Sandreas.hansson@arm.com */ 3258948Sandreas.hansson@arm.com Tick sendAtomicSnoop(PacketPtr pkt); 3268948Sandreas.hansson@arm.com 3278948Sandreas.hansson@arm.com /** 3288948Sandreas.hansson@arm.com * Send a functional snoop request packet, where the data is 3298948Sandreas.hansson@arm.com * instantly updated everywhere in the memory system, without 3308948Sandreas.hansson@arm.com * affecting the current state of any block or moving the block. 3318948Sandreas.hansson@arm.com * 3328948Sandreas.hansson@arm.com * @param pkt Snoop packet to send. 3338948Sandreas.hansson@arm.com */ 3348948Sandreas.hansson@arm.com void sendFunctionalSnoop(PacketPtr pkt); 3358948Sandreas.hansson@arm.com 3368948Sandreas.hansson@arm.com /** 3378948Sandreas.hansson@arm.com * Receive an atomic request packet from the master port. 3388948Sandreas.hansson@arm.com */ 3398948Sandreas.hansson@arm.com virtual Tick recvAtomic(PacketPtr pkt) = 0; 3408948Sandreas.hansson@arm.com 3418948Sandreas.hansson@arm.com /** 3428948Sandreas.hansson@arm.com * Receive a functional request packet from the master port. 3438948Sandreas.hansson@arm.com */ 3448948Sandreas.hansson@arm.com virtual void recvFunctional(PacketPtr pkt) = 0; 3458948Sandreas.hansson@arm.com 3468948Sandreas.hansson@arm.com /** 3478922Swilliam.wang@arm.com * Called by a peer port in order to determine the block size of 3488922Swilliam.wang@arm.com * the owner of this port. 3498922Swilliam.wang@arm.com */ 3508922Swilliam.wang@arm.com virtual unsigned deviceBlockSize() const { return 0; } 3518922Swilliam.wang@arm.com 3528922Swilliam.wang@arm.com /** Called by the associated device if it wishes to find out the blocksize 3538922Swilliam.wang@arm.com of the device on attached to the peer port. 3548922Swilliam.wang@arm.com */ 3558922Swilliam.wang@arm.com unsigned peerBlockSize() const; 3568922Swilliam.wang@arm.com 3578922Swilliam.wang@arm.com /** 3588922Swilliam.wang@arm.com * Called by the owner to send a range change 3598922Swilliam.wang@arm.com */ 3608922Swilliam.wang@arm.com void sendRangeChange() const { _masterPort->recvRangeChange(); } 3618922Swilliam.wang@arm.com 3628922Swilliam.wang@arm.com /** 3638922Swilliam.wang@arm.com * Get a list of the non-overlapping address ranges the owner is 3648922Swilliam.wang@arm.com * responsible for. All slave ports must override this function 3658922Swilliam.wang@arm.com * and return a populated list with at least one item. 3668922Swilliam.wang@arm.com * 3678922Swilliam.wang@arm.com * @return a list of ranges responded to 3688922Swilliam.wang@arm.com */ 3698922Swilliam.wang@arm.com virtual AddrRangeList getAddrRanges() = 0; 3708922Swilliam.wang@arm.com}; 3718922Swilliam.wang@arm.com 3722381SN/A#endif //__MEM_PORT_HH__ 373