port.hh revision 2661
12440SN/A/*
22440SN/A * Copyright (c) 2002-2005 The Regents of The University of Michigan
32440SN/A * All rights reserved.
42440SN/A *
52440SN/A * Redistribution and use in source and binary forms, with or without
62440SN/A * modification, are permitted provided that the following conditions are
72440SN/A * met: redistributions of source code must retain the above copyright
82440SN/A * notice, this list of conditions and the following disclaimer;
92440SN/A * redistributions in binary form must reproduce the above copyright
102440SN/A * notice, this list of conditions and the following disclaimer in the
112440SN/A * documentation and/or other materials provided with the distribution;
122440SN/A * neither the name of the copyright holders nor the names of its
132440SN/A * contributors may be used to endorse or promote products derived from
142440SN/A * this software without specific prior written permission.
152440SN/A *
162440SN/A * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
172440SN/A * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
182440SN/A * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
192440SN/A * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
202440SN/A * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
212440SN/A * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
222440SN/A * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
232440SN/A * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
242440SN/A * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
252440SN/A * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
262440SN/A * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
272665Ssaidi@eecs.umich.edu */
282665Ssaidi@eecs.umich.edu
292665Ssaidi@eecs.umich.edu/**
302440SN/A * @file
312440SN/A * Port Object Decleration. Ports are used to interface memory objects to
322440SN/A * each other.  They will always come in pairs, and we refer to the other
332440SN/A * port object as the peer.  These are used to make the design more
342440SN/A * modular so that a specific interface between every type of objcet doesn't
352440SN/A * have to be created.
362972Sgblack@eecs.umich.edu */
376327Sgblack@eecs.umich.edu
382440SN/A#ifndef __MEM_PORT_HH__
395569Snate@binkert.org#define __MEM_PORT_HH__
403120Sgblack@eecs.umich.edu
412440SN/A#include <list>
425569Snate@binkert.org#include <inttypes.h>
435569Snate@binkert.org
445569Snate@binkert.org#include "base/misc.hh"
455569Snate@binkert.org#include "base/range.hh"
465569Snate@binkert.org#include "mem/packet.hh"
475569Snate@binkert.org#include "mem/request.hh"
482440SN/A
495569Snate@binkert.org/** This typedef is used to clean up the parameter list of
505569Snate@binkert.org * getDeviceAddressRanges() and getPeerAddressRanges().  It's declared
514826Ssaidi@eecs.umich.edu * outside the Port object since it's also used by some mem objects.
525569Snate@binkert.org * Eventually we should move this typedef to wherever Addr is
535569Snate@binkert.org * defined.
545569Snate@binkert.org */
555569Snate@binkert.org
565570Snate@binkert.orgtypedef std::list<Range<Addr> > AddrRangeList;
575569Snate@binkert.orgtypedef std::list<Range<Addr> >::iterator AddrRangeIter;
583577Sgblack@eecs.umich.edu
595569Snate@binkert.org/**
605569Snate@binkert.org * Ports are used to interface memory objects to
615569Snate@binkert.org * each other.  They will always come in pairs, and we refer to the other
625569Snate@binkert.org * port object as the peer.  These are used to make the design more
635570Snate@binkert.org * modular so that a specific interface between every type of objcet doesn't
645569Snate@binkert.org * have to be created.
652440SN/A *
665569Snate@binkert.org * Recv accesor functions are being called from the peer interface.
675569Snate@binkert.org * Send accessor functions are being called from the device the port is
685569Snate@binkert.org * associated with, and it will call the peer recv. accessor function.
695569Snate@binkert.org */
705569Snate@binkert.orgclass Port
715569Snate@binkert.org{
722440SN/A  private:
735569Snate@binkert.org
745569Snate@binkert.org    /** Descriptive name (for DPRINTF output) */
755569Snate@binkert.org    const std::string portName;
765569Snate@binkert.org
775569Snate@binkert.org    /** A pointer to the peer port.  Ports always come in pairs, that way they
785569Snate@binkert.org        can use a standardized interface to communicate between different
792440SN/A        memory objects. */
805569Snate@binkert.org    Port *peer;
815569Snate@binkert.org
825569Snate@binkert.org  public:
835569Snate@binkert.org
845569Snate@binkert.org    /**
852440SN/A     * Constructor.
865569Snate@binkert.org     *
875569Snate@binkert.org     * @param _name Port name for DPRINTF output.  Should include name
885569Snate@binkert.org     * of memory system object to which the port belongs.
895569Snate@binkert.org     */
905569Snate@binkert.org    Port(const std::string &_name)
915569Snate@binkert.org        : portName(_name), peer(NULL)
922440SN/A    { }
935569Snate@binkert.org
945569Snate@binkert.org    /** Return port name (for DPRINTF). */
955569Snate@binkert.org    const std::string &name() const { return portName; }
965569Snate@binkert.org
975569Snate@binkert.org    virtual ~Port() {};
982440SN/A
995569Snate@binkert.org    // mey be better to use subclasses & RTTI?
1005569Snate@binkert.org    /** Holds the ports status.  Currently just that a range recomputation needs
1015569Snate@binkert.org     * to be done. */
1025569Snate@binkert.org    enum Status {
1035569Snate@binkert.org        RangeChange
1045569Snate@binkert.org    };
1055569Snate@binkert.org
1062440SN/A    /** Function to set the pointer for the peer port.
1075569Snate@binkert.org        @todo should be called by the configuration stuff (python).
1085569Snate@binkert.org    */
1095569Snate@binkert.org    void setPeer(Port *port);
1105569Snate@binkert.org
1115569Snate@binkert.org    /** Function to set the pointer for the peer port.
1125569Snate@binkert.org        @todo should be called by the configuration stuff (python).
1132440SN/A    */
1145569Snate@binkert.org    Port *getPeer() { return peer; }
1155569Snate@binkert.org
1165569Snate@binkert.org  protected:
1175569Snate@binkert.org
1185569Snate@binkert.org    /** These functions are protected because they should only be
1195569Snate@binkert.org     * called by a peer port, never directly by any outside object. */
1202440SN/A
1215569Snate@binkert.org    /** Called to recive a timing call from the peer port. */
1225569Snate@binkert.org    virtual bool recvTiming(Packet *pkt) = 0;
1235569Snate@binkert.org
1242440SN/A    /** Called to recive a atomic call from the peer port. */
1255569Snate@binkert.org    virtual Tick recvAtomic(Packet *pkt) = 0;
1265569Snate@binkert.org
1275569Snate@binkert.org    /** Called to recive a functional call from the peer port. */
1285569Snate@binkert.org    virtual void recvFunctional(Packet *pkt) = 0;
1292440SN/A
1305569Snate@binkert.org    /** Called to recieve a status change from the peer port. */
1312440SN/A    virtual void recvStatusChange(Status status) = 0;
1325569Snate@binkert.org
1335569Snate@binkert.org    /** Called by a peer port if the send was unsuccesful, and had to
1342440SN/A        wait.  This shouldn't be valid for response paths (IO Devices).
1355569Snate@binkert.org        so it is set to panic if it isn't already defined.
1365569Snate@binkert.org    */
1375569Snate@binkert.org    virtual void recvRetry() { panic("??"); }
1382440SN/A
1395569Snate@binkert.org    /** Called by a peer port in order to determine the block size of the
1405569Snate@binkert.org        device connected to this port.  It sometimes doesn't make sense for
1412440SN/A        this function to be called, a DMA interface doesn't really have a
1425569Snate@binkert.org        block size, so it is defaulted to a panic.
1435569Snate@binkert.org    */
1445569Snate@binkert.org    virtual int deviceBlockSize() { panic("??"); }
1452440SN/A
1465569Snate@binkert.org    /** The peer port is requesting us to reply with a list of the ranges we
1475569Snate@binkert.org        are responsible for.
1485569Snate@binkert.org        @param resp is a list of ranges responded to
1492440SN/A        @param snoop is a list of ranges snooped
1505569Snate@binkert.org    */
1515569Snate@binkert.org    virtual void getDeviceAddressRanges(AddrRangeList &resp,
1525569Snate@binkert.org            AddrRangeList &snoop)
1532440SN/A    { panic("??"); }
1545569Snate@binkert.org
1555569Snate@binkert.org  public:
1565569Snate@binkert.org
1575569Snate@binkert.org    /** Function called by associated memory device (cache, memory, iodevice)
1585569Snate@binkert.org        in order to send a timing request to the port.  Simply calls the peer
1595569Snate@binkert.org        port receive function.
1602440SN/A        @return This function returns if the send was succesful in it's
1612440SN/A        recieve. If it was a failure, then the port will wait for a recvRetry
1626329Sgblack@eecs.umich.edu        at which point it can possibly issue a successful sendTiming.  This is used in
1636329Sgblack@eecs.umich.edu        case a cache has a higher priority request come in while waiting for
1646329Sgblack@eecs.umich.edu        the bus to arbitrate.
1656329Sgblack@eecs.umich.edu    */
1662440SN/A    bool sendTiming(Packet *pkt) { return peer->recvTiming(pkt); }
1672440SN/A
1685569Snate@binkert.org    /** Function called by the associated device to send an atomic access,
169        an access in which the data is moved and the state is updated in one
170        cycle, without interleaving with other memory accesses.
171    */
172    Tick sendAtomic(Packet *pkt)
173        { return peer->recvAtomic(pkt); }
174
175    /** Function called by the associated device to send a functional access,
176        an access in which the data is instantly updated everywhere in the
177        memory system, without affecting the current state of any block or
178        moving the block.
179    */
180    void sendFunctional(Packet *pkt)
181        { return peer->recvFunctional(pkt); }
182
183    /** Called by the associated device to send a status change to the device
184        connected to the peer interface.
185    */
186    void sendStatusChange(Status status) {peer->recvStatusChange(status); }
187
188    /** When a timing access doesn't return a success, some time later the
189        Retry will be sent.
190    */
191    void sendRetry() { return peer->recvRetry(); }
192
193    /** Called by the associated device if it wishes to find out the blocksize
194        of the device on attached to the peer port.
195    */
196    int peerBlockSize() { return peer->deviceBlockSize(); }
197
198    /** Called by the associated device if it wishes to find out the address
199        ranges connected to the peer ports devices.
200    */
201    void getPeerAddressRanges(AddrRangeList &resp, AddrRangeList &snoop)
202    { peer->getDeviceAddressRanges(resp, snoop); }
203
204    /** This function is a wrapper around sendFunctional()
205        that breaks a larger, arbitrarily aligned access into
206        appropriate chunks.  The default implementation can use
207        getBlockSize() to determine the block size and go from there.
208    */
209    virtual void readBlob(Addr addr, uint8_t *p, int size);
210
211    /** This function is a wrapper around sendFunctional()
212        that breaks a larger, arbitrarily aligned access into
213        appropriate chunks.  The default implementation can use
214        getBlockSize() to determine the block size and go from there.
215    */
216    virtual void writeBlob(Addr addr, uint8_t *p, int size);
217
218    /** Fill size bytes starting at addr with byte value val.  This
219        should not need to be virtual, since it can be implemented in
220        terms of writeBlob().  However, it shouldn't be
221        performance-critical either, so it could be if we wanted to.
222    */
223    virtual void memsetBlob(Addr addr, uint8_t val, int size);
224
225  private:
226
227    /** Internal helper function for read/writeBlob().
228     */
229    void blobHelper(Addr addr, uint8_t *p, int size, Packet::Command cmd);
230};
231
232/** A simple functional port that is only meant for one way communication to
233 * physical memory. It is only meant to be used to load data into memory before
234 * the simulation begins.
235 */
236
237class FunctionalPort : public Port
238{
239  public:
240    FunctionalPort(const std::string &_name)
241        : Port(_name)
242    {}
243
244    virtual bool recvTiming(Packet *pkt) { panic("FuncPort is UniDir"); }
245    virtual Tick recvAtomic(Packet *pkt) { panic("FuncPort is UniDir"); }
246    virtual void recvFunctional(Packet *pkt) { panic("FuncPort is UniDir"); }
247    virtual void recvStatusChange(Status status) {}
248
249    template <typename T>
250    inline void write(Addr addr, T d)
251    {
252        writeBlob(addr, (uint8_t*)&d, sizeof(T));
253    }
254
255    template <typename T>
256    inline T read(Addr addr)
257    {
258        T d;
259        readBlob(addr, (uint8_t*)&d, sizeof(T));
260        return d;
261    }
262};
263
264#endif //__MEM_PORT_HH__
265