port.hh

Go to the documentation of this file.

/*
 * Copyright (c) 2011-2012,2015,2017 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.
 */
 
#ifndef __MEM_PORT_HH__
#define __MEM_PORT_HH__
 
#include <memory>
#include <stack>
#include <string>
 
#include "base/addr_range.hh"
#include "mem/packet.hh"
#include "mem/protocol/atomic.hh"
#include "mem/protocol/functional.hh"
#include "mem/protocol/timing.hh"
#include "sim/port.hh"
 
namespace gem5
{
 
class SimObject;
 
class MasterPort;
class SlavePort;
 
class ResponsePort;
 
class TracingExtension : public gem5::Extension<Packet, TracingExtension>
{
 public:
   TracingExtension() = default;
   TracingExtension(const std::stack<std::string>& q) { trace_ = q; }
 
   std::unique_ptr<ExtensionBase> clone() const override
   {
       return std::make_unique<TracingExtension>(trace_);
   }
 
   void
   add(std::string request_port, std::string response_port)
   {
       trace_.push(request_port);
       trace_.push(response_port);
   }
 
   void
   remove()
   {
       trace_.pop();  // Remove the response port name.
       trace_.pop();  // Remove the request port name.
   }
 
   bool empty() { return trace_.empty(); }
   std::stack<std::string>& getTrace() { return trace_; }
 
  private:
   std::stack<std::string> trace_;
};
 
class RequestPort: public Port, public AtomicRequestProtocol,
    public TimingRequestProtocol, public FunctionalRequestProtocol
{
    friend class ResponsePort;
 
  private:
    ResponsePort *_responsePort;
 
  protected:
    SimObject &owner;
 
  public:
    [[deprecated("RequestPort ownership is deprecated. "
                 "Owner should now be registered in derived classes.")]]
    RequestPort(const std::string& name, SimObject* _owner,
                PortID id=InvalidPortID);
 
    RequestPort(const std::string& name, PortID id=InvalidPortID);
 
    virtual ~RequestPort();
 
    void bind(Port &peer) override;
 
    void unbind() override;
 
    virtual bool isSnooping() const { return false; }
 
    AddrRangeList getAddrRanges() const;
 
    void printAddr(Addr a);
 
  public:
    /* The atomic protocol. */
 
    Tick sendAtomic(PacketPtr pkt);
 
    Tick sendAtomicBackdoor(PacketPtr pkt, MemBackdoorPtr &backdoor);
 
  public:
    /* The functional protocol. */
 
    void sendFunctional(PacketPtr pkt) const;
 
    void sendMemBackdoorReq(const MemBackdoorReq &req,
            MemBackdoorPtr &backdoor);
 
  public:
    /* The timing protocol. */
 
    bool sendTimingReq(PacketPtr pkt);
 
    bool tryTiming(PacketPtr pkt) const;
 
    bool sendTimingSnoopResp(PacketPtr pkt);
 
    virtual void sendRetryResp();
 
  protected:
    virtual void recvRangeChange() { }
 
    Tick
    recvAtomicSnoop(PacketPtr pkt) override
    {
        panic("%s was not expecting an atomic snoop request\n", name());
        return 0;
    }
 
    void
    recvFunctionalSnoop(PacketPtr pkt) override
    {
        panic("%s was not expecting a functional snoop request\n", name());
    }
 
    void
    recvTimingSnoopReq(PacketPtr pkt) override
    {
        panic("%s was not expecting a timing snoop request.\n", name());
    }
 
    void
    recvRetrySnoopResp() override
    {
        panic("%s was not expecting a snoop retry.\n", name());
    }
 
  private:
    void addTrace(PacketPtr pkt) const;
    void removeTrace(PacketPtr pkt) const;
};
 
class [[deprecated]] MasterPort : public RequestPort
{
  public:
    using RequestPort::RequestPort;
};
 
class ResponsePort : public Port, public AtomicResponseProtocol,
    public TimingResponseProtocol, public FunctionalResponseProtocol
{
    friend class RequestPort;
 
  private:
    RequestPort* _requestPort;
 
    bool defaultBackdoorWarned;
 
  protected:
    SimObject& owner;
 
  public:
    [[deprecated("ResponsePort ownership is deprecated. "
                 "Owner should now be registered in derived classes.")]]
    ResponsePort(const std::string& name, SimObject* _owner,
                 PortID id=InvalidPortID);
 
    ResponsePort(const std::string& name, PortID id=InvalidPortID);
 
    virtual ~ResponsePort();
 
    bool isSnooping() const { return _requestPort->isSnooping(); }
 
    void sendRangeChange() const { _requestPort->recvRangeChange(); }
 
    virtual AddrRangeList getAddrRanges() const = 0;
 
    void unbind() override {}
    void bind(Port &peer) override {}
 
  public:
    /* The atomic protocol. */
 
    Tick
    sendAtomicSnoop(PacketPtr pkt)
    {
        try {
            return AtomicResponseProtocol::sendSnoop(_requestPort, pkt);
        } catch (UnboundPortException) {
            reportUnbound();
        }
    }
 
  public:
    /* The functional protocol. */
 
    void
    sendFunctionalSnoop(PacketPtr pkt) const
    {
        try {
            FunctionalResponseProtocol::sendSnoop(_requestPort, pkt);
        } catch (UnboundPortException) {
            reportUnbound();
        }
    }
 
  public:
    /* The timing protocol. */
 
    bool
    sendTimingResp(PacketPtr pkt)
    {
        try {
            _requestPort->removeTrace(pkt);
            bool succ = TimingResponseProtocol::sendResp(_requestPort, pkt);
            if (!succ)
                _requestPort->addTrace(pkt);
            return succ;
        } catch (UnboundPortException) {
            reportUnbound();
        }
    }
 
    void
    sendTimingSnoopReq(PacketPtr pkt)
    {
        try {
            TimingResponseProtocol::sendSnoopReq(_requestPort, pkt);
        } catch (UnboundPortException) {
            reportUnbound();
        }
    }
 
    void
    sendRetryReq()
    {
        try {
            TimingResponseProtocol::sendRetryReq(_requestPort);
        } catch (UnboundPortException) {
            reportUnbound();
        }
    }
 
    void
    sendRetrySnoopResp()
    {
        try {
            TimingResponseProtocol::sendRetrySnoopResp(_requestPort);
        } catch (UnboundPortException) {
            reportUnbound();
        }
    }
 
  protected:
    void responderUnbind();
 
    void responderBind(RequestPort& request_port);
 
    Tick recvAtomicBackdoor(PacketPtr pkt, MemBackdoorPtr &backdoor) override;
    void recvMemBackdoorReq(const MemBackdoorReq &req,
            MemBackdoorPtr &backdoor) override;
 
    bool
    tryTiming(PacketPtr pkt) override
    {
        panic("%s was not expecting a %s\n", name(), __func__);
    }
 
    bool
    recvTimingSnoopResp(PacketPtr pkt) override
    {
        panic("%s was not expecting a timing snoop response\n", name());
    }
};
 
class [[deprecated]] SlavePort : public ResponsePort
{
  public:
    using ResponsePort::ResponsePort;
};
 
inline Tick
RequestPort::sendAtomic(PacketPtr pkt)
{
    try {
        addTrace(pkt);
        Tick tick = AtomicRequestProtocol::send(_responsePort, pkt);
        removeTrace(pkt);
        return tick;
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
inline Tick
RequestPort::sendAtomicBackdoor(PacketPtr pkt, MemBackdoorPtr &backdoor)
{
    try {
        addTrace(pkt);
        Tick tick = AtomicRequestProtocol::sendBackdoor(_responsePort,
                                                        pkt, backdoor);
        removeTrace(pkt);
        return tick;
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
inline void
RequestPort::sendFunctional(PacketPtr pkt) const
{
    try {
        addTrace(pkt);
        FunctionalRequestProtocol::send(_responsePort, pkt);
        removeTrace(pkt);
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
inline void
RequestPort::sendMemBackdoorReq(const MemBackdoorReq &req,
        MemBackdoorPtr &backdoor)
{
    try {
        return FunctionalRequestProtocol::sendMemBackdoorReq(
                _responsePort, req, backdoor);
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
inline bool
RequestPort::sendTimingReq(PacketPtr pkt)
{
    try {
        addTrace(pkt);
        bool succ = TimingRequestProtocol::sendReq(_responsePort, pkt);
        if (!succ)
            removeTrace(pkt);
        return succ;
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
inline bool
RequestPort::tryTiming(PacketPtr pkt) const
{
    try {
        return TimingRequestProtocol::trySend(_responsePort, pkt);
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
inline bool
RequestPort::sendTimingSnoopResp(PacketPtr pkt)
{
    try {
        return TimingRequestProtocol::sendSnoopResp(_responsePort, pkt);
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
inline void
RequestPort::sendRetryResp()
{
    try {
        TimingRequestProtocol::sendRetryResp(_responsePort);
    } catch (UnboundPortException) {
        reportUnbound();
    }
}
 
} // namespace gem5
 
#endif //__MEM_PORT_HH__