port.hh revision 4475
12381SN/A/*
22381SN/A * Copyright (c) 2002-2005 The Regents of The University of Michigan
32381SN/A * All rights reserved.
42381SN/A *
52381SN/A * Redistribution and use in source and binary forms, with or without
62381SN/A * modification, are permitted provided that the following conditions are
72381SN/A * met: redistributions of source code must retain the above copyright
82381SN/A * notice, this list of conditions and the following disclaimer;
92381SN/A * redistributions in binary form must reproduce the above copyright
102381SN/A * notice, this list of conditions and the following disclaimer in the
112381SN/A * documentation and/or other materials provided with the distribution;
122381SN/A * neither the name of the copyright holders nor the names of its
132381SN/A * contributors may be used to endorse or promote products derived from
142381SN/A * this software without specific prior written permission.
152381SN/A *
162381SN/A * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
172381SN/A * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
182381SN/A * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
192381SN/A * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
202381SN/A * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
212381SN/A * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
222381SN/A * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
232381SN/A * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
242381SN/A * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
252381SN/A * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
262381SN/A * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
272665Ssaidi@eecs.umich.edu *
282665Ssaidi@eecs.umich.edu * Authors: Ron Dreslinski
292381SN/A */
302381SN/A
312381SN/A/**
322381SN/A * @file
332982Sstever@eecs.umich.edu * Port Object Declaration. Ports are used to interface memory objects to
342381SN/A * each other.  They will always come in pairs, and we refer to the other
352381SN/A * port object as the peer.  These are used to make the design more
362381SN/A * modular so that a specific interface between every type of objcet doesn't
372381SN/A * have to be created.
382381SN/A */
392381SN/A
402381SN/A#ifndef __MEM_PORT_HH__
412381SN/A#define __MEM_PORT_HH__
422381SN/A
432381SN/A#include <list>
442381SN/A#include <inttypes.h>
452381SN/A
462439SN/A#include "base/misc.hh"
472381SN/A#include "base/range.hh"
482381SN/A#include "mem/packet.hh"
492381SN/A#include "mem/request.hh"
502381SN/A
512407SN/A/** This typedef is used to clean up the parameter list of
522407SN/A * getDeviceAddressRanges() and getPeerAddressRanges().  It's declared
532407SN/A * outside the Port object since it's also used by some mem objects.
542407SN/A * Eventually we should move this typedef to wherever Addr is
552407SN/A * defined.
562407SN/A */
572407SN/A
582407SN/Atypedef std::list<Range<Addr> > AddrRangeList;
592521SN/Atypedef std::list<Range<Addr> >::iterator AddrRangeIter;
602407SN/A
613401Sktlim@umich.educlass MemObject;
623401Sktlim@umich.edu
632381SN/A/**
642381SN/A * Ports are used to interface memory objects to
652381SN/A * each other.  They will always come in pairs, and we refer to the other
662381SN/A * port object as the peer.  These are used to make the design more
672381SN/A * modular so that a specific interface between every type of objcet doesn't
682381SN/A * have to be created.
692381SN/A *
702381SN/A * Recv accesor functions are being called from the peer interface.
712381SN/A * Send accessor functions are being called from the device the port is
722381SN/A * associated with, and it will call the peer recv. accessor function.
732381SN/A */
742381SN/Aclass Port
752381SN/A{
762640Sstever@eecs.umich.edu  private:
772640Sstever@eecs.umich.edu
782640Sstever@eecs.umich.edu    /** Descriptive name (for DPRINTF output) */
792796Sktlim@umich.edu    mutable std::string portName;
802640Sstever@eecs.umich.edu
812661Sstever@eecs.umich.edu    /** A pointer to the peer port.  Ports always come in pairs, that way they
822661Sstever@eecs.umich.edu        can use a standardized interface to communicate between different
832661Sstever@eecs.umich.edu        memory objects. */
842661Sstever@eecs.umich.edu    Port *peer;
852661Sstever@eecs.umich.edu
863401Sktlim@umich.edu    /** A pointer to the MemObject that owns this port. This may not be set. */
873401Sktlim@umich.edu    MemObject *owner;
883401Sktlim@umich.edu
892381SN/A  public:
902381SN/A
912796Sktlim@umich.edu    Port()
923401Sktlim@umich.edu        : peer(NULL), owner(NULL)
932796Sktlim@umich.edu    { }
942796Sktlim@umich.edu
952640Sstever@eecs.umich.edu    /**
962640Sstever@eecs.umich.edu     * Constructor.
972640Sstever@eecs.umich.edu     *
982640Sstever@eecs.umich.edu     * @param _name Port name for DPRINTF output.  Should include name
992640Sstever@eecs.umich.edu     * of memory system object to which the port belongs.
1003401Sktlim@umich.edu     * @param _owner Pointer to the MemObject that owns this port.
1013401Sktlim@umich.edu     * Will not necessarily be set.
1022640Sstever@eecs.umich.edu     */
1033401Sktlim@umich.edu    Port(const std::string &_name, MemObject *_owner = NULL)
1043401Sktlim@umich.edu        : portName(_name), peer(NULL), owner(_owner)
1052640Sstever@eecs.umich.edu    { }
1062640Sstever@eecs.umich.edu
1072640Sstever@eecs.umich.edu    /** Return port name (for DPRINTF). */
1082640Sstever@eecs.umich.edu    const std::string &name() const { return portName; }
1092640Sstever@eecs.umich.edu
1102474SN/A    virtual ~Port() {};
1112640Sstever@eecs.umich.edu
1122381SN/A    // mey be better to use subclasses & RTTI?
1132657Ssaidi@eecs.umich.edu    /** Holds the ports status.  Currently just that a range recomputation needs
1142657Ssaidi@eecs.umich.edu     * to be done. */
1152381SN/A    enum Status {
1163173Srdreslin@umich.edu        RangeChange
1172381SN/A    };
1182381SN/A
1192796Sktlim@umich.edu    void setName(const std::string &name)
1202796Sktlim@umich.edu    { portName = name; }
1212796Sktlim@umich.edu
1223401Sktlim@umich.edu    /** Function to set the pointer for the peer port. */
1234192Sktlim@umich.edu    virtual void setPeer(Port *port);
1242381SN/A
1253401Sktlim@umich.edu    /** Function to get the pointer to the peer port. */
1262409SN/A    Port *getPeer() { return peer; }
1272408SN/A
1283401Sktlim@umich.edu    /** Function to set the owner of this port. */
1293401Sktlim@umich.edu    void setOwner(MemObject *_owner) { owner = _owner; }
1303401Sktlim@umich.edu
1313401Sktlim@umich.edu    /** Function to return the owner of this port. */
1323401Sktlim@umich.edu    MemObject *getOwner() { return owner; }
1333401Sktlim@umich.edu
1344190Ssaidi@eecs.umich.edu    /** Inform the peer port to delete itself and notify it's owner about it's
1354190Ssaidi@eecs.umich.edu     * demise. */
1364190Ssaidi@eecs.umich.edu    void removeConn();
1374190Ssaidi@eecs.umich.edu
1384190Ssaidi@eecs.umich.edu
1392381SN/A  protected:
1402381SN/A
1412406SN/A    /** These functions are protected because they should only be
1422406SN/A     * called by a peer port, never directly by any outside object. */
1432406SN/A
1442381SN/A    /** Called to recive a timing call from the peer port. */
1453349Sbinkertn@umich.edu    virtual bool recvTiming(PacketPtr pkt) = 0;
1462381SN/A
1472381SN/A    /** Called to recive a atomic call from the peer port. */
1483349Sbinkertn@umich.edu    virtual Tick recvAtomic(PacketPtr pkt) = 0;
1492381SN/A
1502381SN/A    /** Called to recive a functional call from the peer port. */
1513349Sbinkertn@umich.edu    virtual void recvFunctional(PacketPtr pkt) = 0;
1522381SN/A
1532381SN/A    /** Called to recieve a status change from the peer port. */
1542381SN/A    virtual void recvStatusChange(Status status) = 0;
1552381SN/A
1562381SN/A    /** Called by a peer port if the send was unsuccesful, and had to
1572381SN/A        wait.  This shouldn't be valid for response paths (IO Devices).
1582381SN/A        so it is set to panic if it isn't already defined.
1592381SN/A    */
1602657Ssaidi@eecs.umich.edu    virtual void recvRetry() { panic("??"); }
1612381SN/A
1622381SN/A    /** Called by a peer port in order to determine the block size of the
1632381SN/A        device connected to this port.  It sometimes doesn't make sense for
1644432Ssaidi@eecs.umich.edu        this function to be called, so it just returns 0. Anytthing that is
1654432Ssaidi@eecs.umich.edu        concerned with the size should just ignore that.
1662381SN/A    */
1674432Ssaidi@eecs.umich.edu    virtual int deviceBlockSize() { return 0; }
1682381SN/A
1692381SN/A    /** The peer port is requesting us to reply with a list of the ranges we
1702381SN/A        are responsible for.
1712521SN/A        @param resp is a list of ranges responded to
1722521SN/A        @param snoop is a list of ranges snooped
1732381SN/A    */
1742521SN/A    virtual void getDeviceAddressRanges(AddrRangeList &resp,
1754475Sstever@eecs.umich.edu                                        bool &snoop)
1762407SN/A    { panic("??"); }
1772381SN/A
1782381SN/A  public:
1792381SN/A
1802381SN/A    /** Function called by associated memory device (cache, memory, iodevice)
1812381SN/A        in order to send a timing request to the port.  Simply calls the peer
1822381SN/A        port receive function.
1832381SN/A        @return This function returns if the send was succesful in it's
1842381SN/A        recieve. If it was a failure, then the port will wait for a recvRetry
1852657Ssaidi@eecs.umich.edu        at which point it can possibly issue a successful sendTiming.  This is used in
1862381SN/A        case a cache has a higher priority request come in while waiting for
1872381SN/A        the bus to arbitrate.
1882381SN/A    */
1893349Sbinkertn@umich.edu    bool sendTiming(PacketPtr pkt) { return peer->recvTiming(pkt); }
1902381SN/A
1912662Sstever@eecs.umich.edu    /** Function called by the associated device to send an atomic
1922662Sstever@eecs.umich.edu     *   access, an access in which the data is moved and the state is
1932662Sstever@eecs.umich.edu     *   updated in one cycle, without interleaving with other memory
1942662Sstever@eecs.umich.edu     *   accesses.  Returns estimated latency of access.
1952662Sstever@eecs.umich.edu     */
1963349Sbinkertn@umich.edu    Tick sendAtomic(PacketPtr pkt)
1972381SN/A        { return peer->recvAtomic(pkt); }
1982381SN/A
1992381SN/A    /** Function called by the associated device to send a functional access,
2002381SN/A        an access in which the data is instantly updated everywhere in the
2012520SN/A        memory system, without affecting the current state of any block or
2022520SN/A        moving the block.
2032381SN/A    */
2043349Sbinkertn@umich.edu    void sendFunctional(PacketPtr pkt)
2052381SN/A        { return peer->recvFunctional(pkt); }
2062381SN/A
2072381SN/A    /** Called by the associated device to send a status change to the device
2082381SN/A        connected to the peer interface.
2092381SN/A    */
2102381SN/A    void sendStatusChange(Status status) {peer->recvStatusChange(status); }
2112381SN/A
2122381SN/A    /** When a timing access doesn't return a success, some time later the
2132381SN/A        Retry will be sent.
2142381SN/A    */
2152657Ssaidi@eecs.umich.edu    void sendRetry() { return peer->recvRetry(); }
2162381SN/A
2172381SN/A    /** Called by the associated device if it wishes to find out the blocksize
2182381SN/A        of the device on attached to the peer port.
2192381SN/A    */
2202406SN/A    int peerBlockSize() { return peer->deviceBlockSize(); }
2212381SN/A
2222381SN/A    /** Called by the associated device if it wishes to find out the address
2232381SN/A        ranges connected to the peer ports devices.
2242381SN/A    */
2254475Sstever@eecs.umich.edu    void getPeerAddressRanges(AddrRangeList &resp, bool &snoop)
2262521SN/A    { peer->getDeviceAddressRanges(resp, snoop); }
2272381SN/A
2282461SN/A    /** This function is a wrapper around sendFunctional()
2292461SN/A        that breaks a larger, arbitrarily aligned access into
2302461SN/A        appropriate chunks.  The default implementation can use
2312461SN/A        getBlockSize() to determine the block size and go from there.
2322461SN/A    */
2332519SN/A    virtual void readBlob(Addr addr, uint8_t *p, int size);
2342381SN/A
2352381SN/A    /** This function is a wrapper around sendFunctional()
2362381SN/A        that breaks a larger, arbitrarily aligned access into
2372381SN/A        appropriate chunks.  The default implementation can use
2382381SN/A        getBlockSize() to determine the block size and go from there.
2392381SN/A    */
2402519SN/A    virtual void writeBlob(Addr addr, uint8_t *p, int size);
2412381SN/A
2422381SN/A    /** Fill size bytes starting at addr with byte value val.  This
2432381SN/A        should not need to be virtual, since it can be implemented in
2442461SN/A        terms of writeBlob().  However, it shouldn't be
2452381SN/A        performance-critical either, so it could be if we wanted to.
2462381SN/A    */
2472519SN/A    virtual void memsetBlob(Addr addr, uint8_t val, int size);
2482405SN/A
2492405SN/A  private:
2502405SN/A
2512405SN/A    /** Internal helper function for read/writeBlob().
2522405SN/A     */
2534022Sstever@eecs.umich.edu    void blobHelper(Addr addr, uint8_t *p, int size, MemCmd cmd);
2542381SN/A};
2552381SN/A
2562520SN/A/** A simple functional port that is only meant for one way communication to
2572520SN/A * physical memory. It is only meant to be used to load data into memory before
2582520SN/A * the simulation begins.
2592520SN/A */
2602520SN/A
2612520SN/Aclass FunctionalPort : public Port
2622520SN/A{
2632520SN/A  public:
2643401Sktlim@umich.edu    FunctionalPort(const std::string &_name, MemObject *_owner = NULL)
2653401Sktlim@umich.edu        : Port(_name, _owner)
2662640Sstever@eecs.umich.edu    {}
2672640Sstever@eecs.umich.edu
2683091Sstever@eecs.umich.edu  protected:
2693918Ssaidi@eecs.umich.edu    virtual bool recvTiming(PacketPtr pkt) { panic("FuncPort is UniDir");
2703918Ssaidi@eecs.umich.edu        M5_DUMMY_RETURN }
2713918Ssaidi@eecs.umich.edu    virtual Tick recvAtomic(PacketPtr pkt) { panic("FuncPort is UniDir");
2723918Ssaidi@eecs.umich.edu        M5_DUMMY_RETURN }
2733349Sbinkertn@umich.edu    virtual void recvFunctional(PacketPtr pkt) { panic("FuncPort is UniDir"); }
2742590SN/A    virtual void recvStatusChange(Status status) {}
2752521SN/A
2763091Sstever@eecs.umich.edu  public:
2772684Ssaidi@eecs.umich.edu    /** a write function that also does an endian conversion. */
2782684Ssaidi@eecs.umich.edu    template <typename T>
2792684Ssaidi@eecs.umich.edu    inline void writeHtoG(Addr addr, T d);
2802684Ssaidi@eecs.umich.edu
2812684Ssaidi@eecs.umich.edu    /** a read function that also does an endian conversion. */
2822684Ssaidi@eecs.umich.edu    template <typename T>
2832684Ssaidi@eecs.umich.edu    inline T readGtoH(Addr addr);
2842684Ssaidi@eecs.umich.edu
2852521SN/A    template <typename T>
2862521SN/A    inline void write(Addr addr, T d)
2872521SN/A    {
2882521SN/A        writeBlob(addr, (uint8_t*)&d, sizeof(T));
2892521SN/A    }
2902521SN/A
2912521SN/A    template <typename T>
2922521SN/A    inline T read(Addr addr)
2932521SN/A    {
2942521SN/A        T d;
2952521SN/A        readBlob(addr, (uint8_t*)&d, sizeof(T));
2962521SN/A        return d;
2972521SN/A    }
2982520SN/A};
2992520SN/A
3002381SN/A#endif //__MEM_PORT_HH__
301