src/mem/bus.hh

   1 /*
   2  * Copyright (c) 2011 ARM Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Copyright (c) 2002-2005 The Regents of The University of Michigan
  15  * All rights reserved.
  16  *
  17  * Redistribution and use in source and binary forms, with or without
  18  * modification, are permitted provided that the following conditions are
  19  * met: redistributions of source code must retain the above copyright
  20  * notice, this list of conditions and the following disclaimer;
  21  * redistributions in binary form must reproduce the above copyright
  22  * notice, this list of conditions and the following disclaimer in the
  23  * documentation and/or other materials provided with the distribution;
  24  * neither the name of the copyright holders nor the names of its
  25  * contributors may be used to endorse or promote products derived from
  26  * this software without specific prior written permission.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  29  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  30  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  31  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  32  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  33  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  34  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  38  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39  *
  40  * Authors: Ron Dreslinski
  41  *          Ali Saidi
  42  *          Andreas Hansson
  43  *          William Wang
  44  */
  45
  46 /**
  47  * @file
  48  * Declaration of a bus object.
  49  */
  50
  51 #ifndef __MEM_BUS_HH__
  52 #define __MEM_BUS_HH__
  53
  54 #include <list>
  55 #include <set>
  56 #include <string>
  57
  58 #include "base/range.hh"
  59 #include "base/range_map.hh"
  60 #include "base/types.hh"
  61 #include "mem/mem_object.hh"
  62 #include "mem/packet.hh"
  63 #include "mem/port.hh"
  64 #include "params/Bus.hh"
  65 #include "sim/eventq.hh"
  66
  67 class Bus : public MemObject
  68 {
  69     /**
  70      * Declaration of the bus slave port type, one will be
  71      * instantiated for each of the master interfaces connecting to
  72      * the bus.
  73      */
  74     class BusSlavePort : public SlavePort
  75     {
  76       private:
  77         /** A pointer to the bus to which this port belongs. */
  78         Bus *bus;
  79
  80       public:
  81
  82         /** Constructor for the BusSlavePort.*/
  83         BusSlavePort(const std::string &_name, Bus *_bus, Port::PortId _id)
  84             : SlavePort(_name, _bus, _id), bus(_bus)
  85         { }
  86
  87       protected:
  88
  89         /**
  90          * When receiving a timing request, pass it to the bus.
  91          */
  92         virtual bool recvTiming(PacketPtr pkt)
  93         { pkt->setSrc(id); return bus->recvTiming(pkt); }
  94
  95         /**
  96          * When receiving a timing snoop response, pass it to the bus.
  97          */
  98         virtual bool recvTimingSnoop(PacketPtr pkt)
  99         { pkt->setSrc(id); return bus->recvTimingSnoop(pkt); }
 100
 101         /**
 102          * When receiving an atomic request, pass it to the bus.
 103          */
 104         virtual Tick recvAtomic(PacketPtr pkt)
 105         { pkt->setSrc(id); return bus->recvAtomic(pkt); }
 106
 107         /**
 108          * When receiving a functional request, pass it to the bus.
 109          */
 110         virtual void recvFunctional(PacketPtr pkt)
 111         { pkt->setSrc(id); bus->recvFunctional(pkt); }
 112
 113         /**
 114          * When receiving a retry, pass it to the bus.
 115          */
 116         virtual void recvRetry()
 117         { panic("Bus slave ports always succeed and should never retry.\n"); }
 118
 119         // This should return all the 'owned' addresses that are
 120         // downstream from this bus, yes?  That is, the union of all
 121         // the 'owned' address ranges of all the other interfaces on
 122         // this bus...
 123         virtual AddrRangeList getAddrRanges()
 124         { return bus->getAddrRanges(id); }
 125
 126         // Ask the bus to ask everyone on the bus what their block size is and
 127         // take the max of it. This might need to be changed a bit if we ever
 128         // support multiple block sizes.
 129         virtual unsigned deviceBlockSize() const
 130         { return bus->findBlockSize(id); }
 131
 132     };
 133
 134     /**
 135      * Declaration of the bus master port type, one will be
 136      * instantiated for each of the slave interfaces connecting to the
 137      * bus.
 138      */
 139     class BusMasterPort : public MasterPort
 140     {
 141       private:
 142         /** A pointer to the bus to which this port belongs. */
 143         Bus *bus;
 144
 145       public:
 146
 147         /** Constructor for the BusMasterPort.*/
 148         BusMasterPort(const std::string &_name, Bus *_bus, Port::PortId _id)
 149             : MasterPort(_name, _bus, _id), bus(_bus)
 150         { }
 151
 152         /**
 153          * Determine if this port should be considered a snooper. This
 154          * is determined by the bus.
 155          *
 156          * @return a boolean that is true if this port is snooping
 157          */
 158         virtual bool isSnooping() const
 159         { return bus->isSnooping(id); }
 160
 161       protected:
 162
 163         /**
 164          * When receiving a timing response, pass it to the bus.
 165          */
 166         virtual bool recvTiming(PacketPtr pkt)
 167         { pkt->setSrc(id); return bus->recvTiming(pkt); }
 168
 169         /**
 170          * When receiving a timing snoop request, pass it to the bus.
 171          */
 172         virtual bool recvTimingSnoop(PacketPtr pkt)
 173         { pkt->setSrc(id); return bus->recvTimingSnoop(pkt); }
 174
 175         /**
 176          * When receiving an atomic snoop request, pass it to the bus.
 177          */
 178         virtual Tick recvAtomicSnoop(PacketPtr pkt)
 179         { pkt->setSrc(id); return bus->recvAtomicSnoop(pkt); }
 180
 181         /**
 182          * When receiving a functional snoop request, pass it to the bus.
 183          */
 184         virtual void recvFunctionalSnoop(PacketPtr pkt)
 185         { pkt->setSrc(id); bus->recvFunctionalSnoop(pkt); }
 186
 187         /** When reciving a range change from the peer port (at id),
 188             pass it to the bus. */
 189         virtual void recvRangeChange()
 190         { bus->recvRangeChange(id); }
 191
 192         /** When reciving a retry from the peer port (at id),
 193             pass it to the bus. */
 194         virtual void recvRetry()
 195         { bus->recvRetry(id); }
 196
 197         // Ask the bus to ask everyone on the bus what their block size is and
 198         // take the max of it. This might need to be changed a bit if we ever
 199         // support multiple block sizes.
 200         virtual unsigned deviceBlockSize() const
 201         { return bus->findBlockSize(id); }
 202
 203     };
 204
 205     /** the clock speed for the bus */
 206     int clock;
 207     /** cycles of overhead per transaction */
 208     int headerCycles;
 209     /** the width of the bus in bytes */
 210     int width;
 211     /** the next tick at which the bus will be idle */
 212     Tick tickNextIdle;
 213
 214     Event * drainEvent;
 215
 216     typedef range_map<Addr,int>::iterator PortIter;
 217     range_map<Addr, int> portMap;
 218
 219     AddrRangeList defaultRange;
 220
 221     typedef std::vector<BusSlavePort*>::iterator SnoopIter;
 222     std::vector<BusSlavePort*> snoopPorts;
 223
 224     /**
 225      * Store the outstanding requests so we can determine which ones
 226      * we generated and which ones were merely forwarded. This is used
 227      * in the coherent bus when coherency responses come back.
 228      */
 229     std::set<RequestPtr> outstandingReq;
 230
 231     /** Function called by the port when the bus is recieving a Timing
 232       transaction.*/
 233     bool recvTiming(PacketPtr pkt);
 234
 235     /** Function called by the port when the bus is recieving a timing
 236         snoop transaction.*/
 237     bool recvTimingSnoop(PacketPtr pkt);
 238
 239     /**
 240      * Forward a timing packet to our snoopers, potentially excluding
 241      * one of the connected coherent masters to avoid sending a packet
 242      * back to where it came from.
 243      *
 244      * @param pkt Packet to forward
 245      * @param exclude_slave_port_id Id of slave port to exclude
 246      */
 247     void forwardTiming(PacketPtr pkt, Port::PortId exclude_slave_port_id);
 248
 249     /**
 250      * Determine if the bus is to be considered occupied when being
 251      * presented with a packet from a specific port. If so, the port
 252      * in question is also added to the retry list.
 253      *
 254      * @param pkt Incoming packet
 255      * @param port Source port on the bus presenting the packet
 256      *
 257      * @return True if the bus is to be considered occupied
 258      */
 259     bool isOccupied(PacketPtr pkt, Port* port);
 260
 261     /**
 262      * Deal with a destination port accepting a packet by potentially
 263      * removing the source port from the retry list (if retrying) and
 264      * occupying the bus accordingly.
 265      *
 266      * @param busy_time Time to spend as a result of a successful send
 267      */
 268     void succeededTiming(Tick busy_time);
 269
 270     /** Function called by the port when the bus is recieving a Atomic
 271       transaction.*/
 272     Tick recvAtomic(PacketPtr pkt);
 273
 274     /** Function called by the port when the bus is recieving an
 275         atomic snoop transaction.*/
 276     Tick recvAtomicSnoop(PacketPtr pkt);
 277
 278     /**
 279      * Forward an atomic packet to our snoopers, potentially excluding
 280      * one of the connected coherent masters to avoid sending a packet
 281      * back to where it came from.
 282      *
 283      * @param pkt Packet to forward
 284      * @param exclude_slave_port_id Id of slave port to exclude
 285      *
 286      * @return a pair containing the snoop response and snoop latency
 287      */
 288     std::pair<MemCmd, Tick> forwardAtomic(PacketPtr pkt,
 289                                           Port::PortId exclude_slave_port_id);
 290
 291     /** Function called by the port when the bus is recieving a Functional
 292         transaction.*/
 293     void recvFunctional(PacketPtr pkt);
 294
 295     /** Function called by the port when the bus is recieving a functional
 296         snoop transaction.*/
 297     void recvFunctionalSnoop(PacketPtr pkt);
 298
 299     /**
 300      * Forward a functional packet to our snoopers, potentially
 301      * excluding one of the connected coherent masters to avoid
 302      * sending a packet back to where it came from.
 303      *
 304      * @param pkt Packet to forward
 305      * @param exclude_slave_port_id Id of slave port to exclude
 306      */
 307     void forwardFunctional(PacketPtr pkt, Port::PortId exclude_slave_port_id);
 308
 309     /** Timing function called by port when it is once again able to process
 310      * requests. */
 311     void recvRetry(Port::PortId id);
 312
 313     /** Function called by the port when the bus is recieving a range change.*/
 314     void recvRangeChange(Port::PortId id);
 315
 316     /** Find which port connected to this bus (if any) should be given a packet
 317      * with this address.
 318      * @param addr Address to find port for.
 319      * @return id of port that the packet should be sent out of.
 320      */
 321     int findPort(Addr addr);
 322
 323     // Cache for the findPort function storing recently used ports from portMap
 324     struct PortCache {
 325         bool valid;
 326         Port::PortId id;
 327         Addr start;
 328         Addr end;
 329     };
 330
 331     PortCache portCache[3];
 332
 333     // Checks the cache and returns the id of the port that has the requested
 334     // address within its range
 335     inline int checkPortCache(Addr addr) {
 336         if (portCache[0].valid && addr >= portCache[0].start &&
 337             addr < portCache[0].end) {
 338             return portCache[0].id;
 339         }
 340         if (portCache[1].valid && addr >= portCache[1].start &&
 341                    addr < portCache[1].end) {
 342             return portCache[1].id;
 343         }
 344         if (portCache[2].valid && addr >= portCache[2].start &&
 345             addr < portCache[2].end) {
 346             return portCache[2].id;
 347         }
 348
 349         return Port::INVALID_PORT_ID;
 350     }
 351
 352     // Clears the earliest entry of the cache and inserts a new port entry
 353     inline void updatePortCache(short id, Addr start, Addr end) {
 354         portCache[2].valid = portCache[1].valid;
 355         portCache[2].id    = portCache[1].id;
 356         portCache[2].start = portCache[1].start;
 357         portCache[2].end   = portCache[1].end;
 358
 359         portCache[1].valid = portCache[0].valid;
 360         portCache[1].id    = portCache[0].id;
 361         portCache[1].start = portCache[0].start;
 362         portCache[1].end   = portCache[0].end;
 363
 364         portCache[0].valid = true;
 365         portCache[0].id    = id;
 366         portCache[0].start = start;
 367         portCache[0].end   = end;
 368     }
 369
 370     // Clears the cache. Needs to be called in constructor.
 371     inline void clearPortCache() {
 372         portCache[2].valid = false;
 373         portCache[1].valid = false;
 374         portCache[0].valid = false;
 375     }
 376
 377     /**
 378      * Return the address ranges this port is responsible for.
 379      *
 380      * @param id id of the bus port that made the request
 381      *
 382      * @return a list of non-overlapping address ranges
 383      */
 384     AddrRangeList getAddrRanges(Port::PortId id);
 385
 386     /**
 387      * Determine if the bus port is snooping or not.
 388      *
 389      * @param id id of the bus port that made the request
 390      *
 391      * @return a boolean indicating if this port is snooping or not
 392      */
 393     bool isSnooping(Port::PortId id) const;
 394
 395     /** Calculate the timing parameters for the packet.  Updates the
 396      * firstWordTime and finishTime fields of the packet object.
 397      * Returns the tick at which the packet header is completed (which
 398      * will be all that is sent if the target rejects the packet).
 399      */
 400     Tick calcPacketTiming(PacketPtr pkt);
 401
 402     /** Occupy the bus until until */
 403     void occupyBus(Tick until);
 404
 405     /**
 406      * Release the bus after being occupied and return to an idle
 407      * state where we proceed to send a retry to any potential waiting
 408      * port, or drain if asked to do so.
 409      */
 410     void releaseBus();
 411
 412     /**
 413      * Send a retry to the port at the head of the retryList. The
 414      * caller must ensure that the list is not empty.
 415      */
 416     void retryWaiting();
 417
 418     /** Ask everyone on the bus what their size is
 419      * @param id id of the busport that made the request
 420      * @return the max of all the sizes
 421      */
 422     unsigned findBlockSize(Port::PortId id);
 423
 424     // event used to schedule a release of the bus
 425     EventWrapper<Bus, &Bus::releaseBus> busIdleEvent;
 426
 427     bool inRetry;
 428     std::set<Port::PortId> inRecvRangeChange;
 429
 430     /** The master and slave ports of the bus */
 431     std::vector<BusSlavePort*> slavePorts;
 432     std::vector<BusMasterPort*> masterPorts;
 433
 434     /** An array of pointers to ports that retry should be called on because the
 435      * original send failed for whatever reason.*/
 436     std::list<Port*> retryList;
 437
 438     void addToRetryList(Port* port)
 439     {
 440         if (!inRetry) {
 441             // The device wasn't retrying a packet, or wasn't at an
 442             // appropriate time.
 443             retryList.push_back(port);
 444         } else {
 445             if (!retryList.empty() && port == retryList.front()) {
 446                 // The device was retrying a packet. It didn't work,
 447                 // so we'll leave it at the head of the retry list.
 448                 inRetry = false;
 449             } else {
 450                 // We are in retry, but not for this port, put it at
 451                 // the end.
 452                 retryList.push_back(port);
 453             }
 454         }
 455     }
 456
 457     /** Port that handles requests that don't match any of the interfaces.*/
 458     short defaultPortId;
 459
 460     /** If true, use address range provided by default device.  Any
 461        address not handled by another port and not in default device's
 462        range will cause a fatal error.  If false, just send all
 463        addresses not handled by another port to default device. */
 464     bool useDefaultRange;
 465
 466     unsigned defaultBlockSize;
 467     unsigned cachedBlockSize;
 468     bool cachedBlockSizeValid;
 469
 470   public:
 471
 472     /** A function used to return the port associated with this bus object. */
 473     virtual MasterPort& getMasterPort(const std::string& if_name, int idx = -1);
 474     virtual SlavePort& getSlavePort(const std::string& if_name, int idx = -1);
 475
 476     virtual void init();
 477     virtual void startup();
 478
 479     unsigned int drain(Event *de);
 480
 481     Bus(const BusParams *p);
 482 };
 483
 484 #endif //__MEM_BUS_HH__