src/mem/port.hh - testing/jenkins-gem5-prod - Git at Google

 /*
  * Copyright (c) 2011-2012 ARM Limited
  * All rights reserved
  *
  * The license below extends only to copyright in the software and shall
  * not be construed as granting a license to any other intellectual
  * property including but not limited to intellectual property relating
  * to a hardware implementation of the functionality of the software
  * licensed hereunder.  You may use the software subject to the license
  * terms below provided that you ensure that this notice is replicated
  * unmodified and in its entirety in all distributions of the software,
  * modified or unmodified, in source code or in binary form.
  *
  * Copyright (c) 2002-2005 The Regents of The University of Michigan
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met: redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer;
  * redistributions in binary form must reproduce the above copyright
  * notice, this list of conditions and the following disclaimer in the
  * documentation and/or other materials provided with the distribution;
  * neither the name of the copyright holders nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  * Authors: Ron Dreslinski
  *          Andreas Hansson
  *          William Wang
  */

 /**
  * @file
  * Port Object Declaration.
  */

 #ifndef __MEM_PORT_HH__
 #define __MEM_PORT_HH__

 #include <list>

 #include "base/range.hh"
 #include "mem/packet.hh"

 /**
  * This typedef is used to clean up getAddrRanges(). It's declared
  * outside the Port object since it's also used by some mem objects.
  * Eventually we should move this typedef to wherever Addr is
  * defined.
  */

 typedef std::list<Range<Addr> > AddrRangeList;
 typedef std::list<Range<Addr> >::iterator AddrRangeIter;

 class MemObject;

 /**
  * Ports are used to interface memory objects to each other. A port is
  * either a master or a slave and the connected peer is always of the
  * opposite role.
  *
  * Each port has a name and an owner, and enables three basic types of
  * accesses to the peer port: sendFunctional, sendAtomic and
  * sendTiming.
  */
 class Port
 {

   private:

     /** Descriptive name (for DPRINTF output) */
     std::string portName;

   protected:

     /** A pointer to the peer port.  */
     Port* peer;

     /** A reference to the MemObject that owns this port. */
     MemObject& owner;

     /**
      * Abstract base class for ports
      *
      * @param _name Port name including the owners name
      * @param _owner The MemObject that is the structural owner of this port
      */
     Port(const std::string& _name, MemObject& _owner);

     /**
      * Virtual destructor due to inheritance.
      */
     virtual ~Port();

   public:

     /** Return port name (for DPRINTF). */
     const std::string name() const { return portName; }

   protected:

     /** These functions are protected because they should only be
      * called by a peer port, never directly by any outside object. */

     /** Called to recive a timing call from the peer port. */
     virtual bool recvTiming(PacketPtr pkt) = 0;

     /** Called to recive a atomic call from the peer port. */
     virtual Tick recvAtomic(PacketPtr pkt) = 0;

     /** Called to recive a functional call from the peer port. */
     virtual void recvFunctional(PacketPtr pkt) = 0;

     /**
      * Called by a peer port if sendTiming was unsuccesful, and had to
      * wait.
      */
     virtual void recvRetry() = 0;

   public:

     /**
      * Attempt to send a timing packet to the peer port by calling its
      * receive function. If the send does not succeed, as indicated by
      * the return value, then the sender must wait for a recvRetry at
      * which point it can re-issue a sendTiming.
      *
      * @param pkt Packet to send.
      *
      * @return If the send was succesful or not.
     */
     bool sendTiming(PacketPtr pkt) { return peer->recvTiming(pkt); }

     /**
      * Send a retry to a peer port that previously attempted a sendTiming
      * which was unsuccessful.
      */
     void sendRetry() { return peer->recvRetry(); }

     /**
      * Send an atomic packet, where the data is moved and the state
      * is updated in zero time, without interleaving with other
      * memory accesses.
      *
      * @param pkt Packet to send.
      *
      * @return Estimated latency of access.
      */
     Tick sendAtomic(PacketPtr pkt) { return peer->recvAtomic(pkt); }

     /**
      * Send a functional packet, where the data is instantly updated
      * everywhere in the memory system, without affecting the current
      * state of any block or moving the block.
      *
      * @param pkt Packet to send.
      */
     void sendFunctional(PacketPtr pkt) { return peer->recvFunctional(pkt); }

 };

 /** Forward declaration */
 class SlavePort;

 /**
  * A MasterPort is a specialisation of a port. In addition to the
  * basic functionality of sending packets to its slave peer, it also
  * has functions specific to a master, e.g. to receive range changes
  * or determine if the port is snooping or not.
  */
 class MasterPort : public Port
 {

   private:

     SlavePort* _slavePort;

   public:

     MasterPort(const std::string& name, MemObject* owner);
     virtual ~MasterPort();

     void bind(SlavePort& slave_port);
     SlavePort& getSlavePort() const;
     bool isConnected() const;

     /**
      * Called to receive an address range change from the peer slave
      * port. the default implementation ignored the change and does
      * nothing. Override this function in a derived class if the owner
      * needs to be aware of he laesddress ranges, e.g. in an
      * interconnect component like a bus.
      */
     virtual void recvRangeChange() { }

     /**
      * Determine if this master port is snooping or not. The default
      * implementation returns false and thus tells the neighbour we
      * are not snooping. Any master port that wants to receive snoop
      * requests (e.g. a cache connected to a bus) has to override this
      * function.
      *
      * @return true if the port should be considered a snooper
      */
     virtual bool isSnooping() const { return false; }

     /**
      * Called by a peer port in order to determine the block size of
      * the owner of this port.
      */
     virtual unsigned deviceBlockSize() const { return 0; }

     /** Called by the associated device if it wishes to find out the blocksize
         of the device on attached to the peer port.
     */
     unsigned peerBlockSize() const;

     /** Inject a PrintReq for the given address to print the state of
      * that address throughout the memory system.  For debugging.
      */
     void printAddr(Addr a);
 };

 /**
  * A SlavePort is a specialisation of a port. In addition to the
  * basic functionality of sending packets to its master peer, it also
  * has functions specific to a slave, e.g. to send range changes
  * and get the address ranges that the port responds to.
  */
 class SlavePort : public Port
 {

   private:

     MasterPort* _masterPort;

   public:

     SlavePort(const std::string& name, MemObject* owner);
     virtual ~SlavePort();

     void bind(MasterPort& master_port);
     MasterPort& getMasterPort() const;
     bool isConnected() const;

     /**
      * Called by a peer port in order to determine the block size of
      * the owner of this port.
      */
     virtual unsigned deviceBlockSize() const { return 0; }

     /** Called by the associated device if it wishes to find out the blocksize
         of the device on attached to the peer port.
     */
     unsigned peerBlockSize() const;

     /**
      * Called by the owner to send a range change
      */
     void sendRangeChange() const { _masterPort->recvRangeChange(); }

     /**
      * Get a list of the non-overlapping address ranges the owner is
      * responsible for. All slave ports must override this function
      * and return a populated list with at least one item.
      *
      * @return a list of ranges responded to
      */
     virtual AddrRangeList getAddrRanges() = 0;
 };

 #endif //__MEM_PORT_HH__
	/*
	* Copyright (c) 2011-2012 ARM Limited
	* All rights reserved
	*
	* The license below extends only to copyright in the software and shall
	* not be construed as granting a license to any other intellectual
	* property including but not limited to intellectual property relating
	* to a hardware implementation of the functionality of the software
	* licensed hereunder. You may use the software subject to the license
	* terms below provided that you ensure that this notice is replicated
	* unmodified and in its entirety in all distributions of the software,
	* modified or unmodified, in source code or in binary form.
	*
	* Copyright (c) 2002-2005 The Regents of The University of Michigan
	* All rights reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions are
	* met: redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer;
	* redistributions in binary form must reproduce the above copyright
	* notice, this list of conditions and the following disclaimer in the
	* documentation and/or other materials provided with the distribution;
	* neither the name of the copyright holders nor the names of its
	* contributors may be used to endorse or promote products derived from
	* this software without specific prior written permission.
	*
	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
	* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
	* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
	* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	*
	* Authors: Ron Dreslinski
	* Andreas Hansson
	* William Wang
	*/

	/**
	* @file
	* Port Object Declaration.
	*/

	#ifndef __MEM_PORT_HH__
	#define __MEM_PORT_HH__

	#include <list>

	#include "base/range.hh"
	#include "mem/packet.hh"

	/**
	* This typedef is used to clean up getAddrRanges(). It's declared
	* outside the Port object since it's also used by some mem objects.
	* Eventually we should move this typedef to wherever Addr is
	* defined.
	*/

	typedef std::list<Range<Addr> > AddrRangeList;
	typedef std::list<Range<Addr> >::iterator AddrRangeIter;

	class MemObject;

	/**
	* Ports are used to interface memory objects to each other. A port is
	* either a master or a slave and the connected peer is always of the
	* opposite role.
	*
	* Each port has a name and an owner, and enables three basic types of
	* accesses to the peer port: sendFunctional, sendAtomic and
	* sendTiming.
	*/
	class Port
	{

	private:

	/** Descriptive name (for DPRINTF output) */
	std::string portName;

	protected:

	/** A pointer to the peer port. */
	Port* peer;

	/** A reference to the MemObject that owns this port. */
	MemObject& owner;

	/**
	* Abstract base class for ports
	*
	* @param _name Port name including the owners name
	* @param _owner The MemObject that is the structural owner of this port
	*/
	Port(const std::string& _name, MemObject& _owner);

	/**
	* Virtual destructor due to inheritance.
	*/
	virtual ~Port();

	public:

	/** Return port name (for DPRINTF). */
	const std::string name() const { return portName; }

	protected:

	/** These functions are protected because they should only be
	* called by a peer port, never directly by any outside object. */

	/** Called to recive a timing call from the peer port. */
	virtual bool recvTiming(PacketPtr pkt) = 0;

	/** Called to recive a atomic call from the peer port. */
	virtual Tick recvAtomic(PacketPtr pkt) = 0;

	/** Called to recive a functional call from the peer port. */
	virtual void recvFunctional(PacketPtr pkt) = 0;

	/**
	* Called by a peer port if sendTiming was unsuccesful, and had to
	* wait.
	*/
	virtual void recvRetry() = 0;

	public:

	/**
	* Attempt to send a timing packet to the peer port by calling its
	* receive function. If the send does not succeed, as indicated by
	* the return value, then the sender must wait for a recvRetry at
	* which point it can re-issue a sendTiming.
	*
	* @param pkt Packet to send.
	*
	* @return If the send was succesful or not.
	*/
	bool sendTiming(PacketPtr pkt) { return peer->recvTiming(pkt); }

	/**
	* Send a retry to a peer port that previously attempted a sendTiming
	* which was unsuccessful.
	*/
	void sendRetry() { return peer->recvRetry(); }

	/**
	* Send an atomic packet, where the data is moved and the state
	* is updated in zero time, without interleaving with other
	* memory accesses.
	*
	* @param pkt Packet to send.
	*
	* @return Estimated latency of access.
	*/
	Tick sendAtomic(PacketPtr pkt) { return peer->recvAtomic(pkt); }

	/**
	* Send a functional packet, where the data is instantly updated
	* everywhere in the memory system, without affecting the current
	* state of any block or moving the block.
	*
	* @param pkt Packet to send.
	*/
	void sendFunctional(PacketPtr pkt) { return peer->recvFunctional(pkt); }

	};

	/** Forward declaration */
	class SlavePort;

	/**
	* A MasterPort is a specialisation of a port. In addition to the
	* basic functionality of sending packets to its slave peer, it also
	* has functions specific to a master, e.g. to receive range changes
	* or determine if the port is snooping or not.
	*/
	class MasterPort : public Port
	{

	private:

	SlavePort* _slavePort;

	public:

	MasterPort(const std::string& name, MemObject* owner);
	virtual ~MasterPort();

	void bind(SlavePort& slave_port);
	SlavePort& getSlavePort() const;
	bool isConnected() const;

	/**
	* Called to receive an address range change from the peer slave
	* port. the default implementation ignored the change and does
	* nothing. Override this function in a derived class if the owner
	* needs to be aware of he laesddress ranges, e.g. in an
	* interconnect component like a bus.
	*/
	virtual void recvRangeChange() { }

	/**
	* Determine if this master port is snooping or not. The default
	* implementation returns false and thus tells the neighbour we
	* are not snooping. Any master port that wants to receive snoop
	* requests (e.g. a cache connected to a bus) has to override this
	* function.
	*
	* @return true if the port should be considered a snooper
	*/
	virtual bool isSnooping() const { return false; }

	/**
	* Called by a peer port in order to determine the block size of
	* the owner of this port.
	*/
	virtual unsigned deviceBlockSize() const { return 0; }

	/** Called by the associated device if it wishes to find out the blocksize
	of the device on attached to the peer port.
	*/
	unsigned peerBlockSize() const;

	/** Inject a PrintReq for the given address to print the state of
	* that address throughout the memory system. For debugging.
	*/
	void printAddr(Addr a);
	};

	/**
	* A SlavePort is a specialisation of a port. In addition to the
	* basic functionality of sending packets to its master peer, it also
	* has functions specific to a slave, e.g. to send range changes
	* and get the address ranges that the port responds to.
	*/
	class SlavePort : public Port
	{

	private:

	MasterPort* _masterPort;

	public:

	SlavePort(const std::string& name, MemObject* owner);
	virtual ~SlavePort();

	void bind(MasterPort& master_port);
	MasterPort& getMasterPort() const;
	bool isConnected() const;

	/**
	* Called by a peer port in order to determine the block size of
	* the owner of this port.
	*/
	virtual unsigned deviceBlockSize() const { return 0; }

	/** Called by the associated device if it wishes to find out the blocksize
	of the device on attached to the peer port.
	*/
	unsigned peerBlockSize() const;

	/**
	* Called by the owner to send a range change
	*/
	void sendRangeChange() const { _masterPort->recvRangeChange(); }

	/**
	* Get a list of the non-overlapping address ranges the owner is
	* responsible for. All slave ports must override this function
	* and return a populated list with at least one item.
	*
	* @return a list of ranges responded to
	*/
	virtual AddrRangeList getAddrRanges() = 0;
	};

	#endif //__MEM_PORT_HH__