src/mem/bus.hh

   1 /*
   2  * Copyright (c) 2011-2013 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 an abstract bus base class.
  49  */
  50
  51 #ifndef __MEM_BUS_HH__
  52 #define __MEM_BUS_HH__
  53
  54 #include <deque>
  55
  56 #include "base/addr_range_map.hh"
  57 #include "base/types.hh"
  58 #include "mem/mem_object.hh"
  59 #include "params/BaseBus.hh"
  60 #include "sim/stats.hh"
  61
  62 /**
  63  * The base bus contains the common elements of the non-coherent and
  64  * coherent bus. It is an abstract class that does not have any of the
  65  * functionality relating to the actual reception and transmission of
  66  * packets, as this is left for the subclasses.
  67  *
  68  * The BaseBus is responsible for the basic flow control (busy or
  69  * not), the administration of retries, and the address decoding.
  70  */
  71 class BaseBus : public MemObject
  72 {
  73
  74   protected:
  75
  76     /**
  77      * A bus layer is an internal bus structure with its own flow
  78      * control and arbitration. Hence, a single-layer bus mimics a
  79      * traditional off-chip tri-state bus (like PCI), where only one
  80      * set of wires are shared. For on-chip buses, a good starting
  81      * point is to have three layers, for requests, responses, and
  82      * snoop responses respectively (snoop requests are instantaneous
  83      * and do not need any flow control or arbitration). This case is
  84      * similar to AHB and some OCP configurations.
  85      *
  86      * As a further extensions beyond the three-layer bus, a future
  87      * multi-layer bus has with one layer per connected slave port
  88      * provides a full or partial crossbar, like AXI, OCP, PCIe etc.
  89      *
  90      * The template parameter, PortClass, indicates the destination
  91      * port type for the bus. The retry list holds either master ports
  92      * or slave ports, depending on the direction of the layer. Thus,
  93      * a request layer has a retry list containing slave ports,
  94      * whereas a response layer holds master ports.
  95      */
  96     template <typename PortClass>
  97     class Layer : public Drainable
  98     {
  99
 100       public:
 101
 102         /**
 103          * Create a bus layer and give it a name. The bus layer uses
 104          * the bus an event manager.
 105          *
 106          * @param _bus the bus this layer belongs to
 107          * @param _name the layer's name
 108          * @param num_dest_ports number of destination ports
 109          */
 110         Layer(BaseBus& _bus, const std::string& _name, uint16_t num_dest_ports);
 111
 112         /**
 113          * Drain according to the normal semantics, so that the bus
 114          * can tell the layer to drain, and pass an event to signal
 115          * back when drained.
 116          *
 117          * @param de drain event to call once drained
 118          *
 119          * @return 1 if busy or waiting to retry, or 0 if idle
 120          */
 121         unsigned int drain(DrainManager *dm);
 122
 123         /**
 124          * Get the bus layer's name
 125          */
 126         const std::string name() const { return bus.name() + _name; }
 127
 128
 129         /**
 130          * Determine if the bus layer accepts a packet from a specific
 131          * port. If not, the port in question is also added to the
 132          * retry list. In either case the state of the layer is
 133          * updated accordingly. To ignore checking the destination
 134          * port (used by snoops), pass InvalidPortID.
 135          *
 136          * @param port Source port presenting the packet
 137          * @param dest_port_id Destination port id
 138          *
 139          * @return True if the bus layer accepts the packet
 140          */
 141         bool tryTiming(PortClass* port, PortID dest_port_id);
 142
 143         /**
 144          * Deal with a destination port accepting a packet by potentially
 145          * removing the source port from the retry list (if retrying) and
 146          * occupying the bus layer accordingly.
 147          *
 148          * @param busy_time Time to spend as a result of a successful send
 149          */
 150         void succeededTiming(Tick busy_time);
 151
 152         /**
 153          * Deal with a destination port not accepting a packet by
 154          * potentially adding the source port to the retry list (if
 155          * not already at the front) and occupying the bus layer
 156          * accordingly.
 157          *
 158          * @param src_port Source port
 159          * @param dest_port_id Destination port id
 160          * @param busy_time Time to spend as a result of a failed send
 161          */
 162         void failedTiming(PortClass* src_port, PortID dest_port_id,
 163                           Tick busy_time);
 164
 165         /** Occupy the bus layer until until */
 166         void occupyLayer(Tick until);
 167
 168         /**
 169          * Send a retry to the port at the head of waitingForLayer. The
 170          * caller must ensure that the list is not empty.
 171          */
 172         void retryWaiting();
 173
 174         /**
 175          * Handle a retry from a neighbouring module. This wraps
 176          * retryWaiting by verifying that there are ports waiting
 177          * before calling retryWaiting.
 178          *
 179          * @param port_id Id of the port that received the retry
 180          */
 181         void recvRetry(PortID port_id);
 182
 183         /**
 184          * Register stats for the layer
 185          */
 186         void regStats();
 187
 188       private:
 189
 190         /** The bus this layer is a part of. */
 191         BaseBus& bus;
 192
 193         /** A name for this layer. */
 194         std::string _name;
 195
 196         /**
 197          * We declare an enum to track the state of the bus layer. The
 198          * starting point is an idle state where the bus layer is
 199          * waiting for a packet to arrive. Upon arrival, the bus layer
 200          * transitions to the busy state, where it remains either
 201          * until the packet transfer is done, or the header time is
 202          * spent. Once the bus layer leaves the busy state, it can
 203          * either go back to idle, if no packets have arrived while it
 204          * was busy, or the bus layer goes on to retry the first port
 205          * in waitingForLayer. A similar transition takes place from
 206          * idle to retry if the bus layer receives a retry from one of
 207          * its connected ports. The retry state lasts until the port
 208          * in questions calls sendTiming and returns control to the
 209          * bus layer, or goes to a busy state if the port does not
 210          * immediately react to the retry by calling sendTiming.
 211          */
 212         enum State { IDLE, BUSY, RETRY };
 213
 214         /** track the state of the bus layer */
 215         State state;
 216
 217         /** manager to signal when drained */
 218         DrainManager *drainManager;
 219
 220         /**
 221          * A deque of ports that retry should be called on because
 222          * the original send was delayed due to a busy layer.
 223          */
 224         std::deque<PortClass*> waitingForLayer;
 225
 226         /**
 227          * Port that we are currently in the process of telling to
 228          * retry a previously failed attempt to perform a timing
 229          * transaction. This is a valid port when in the retry state,
 230          * and NULL when in busy or idle.
 231          */
 232         PortClass* retryingPort;
 233
 234         /**
 235          * A vector that tracks who is waiting for the retry when
 236          * receiving it from a peer. The vector indices are port ids
 237          * of the outgoing ports for the specific layer. The values
 238          * are the incoming ports that tried to forward something to
 239          * the outgoing port, but was told to wait and is now waiting
 240          * for a retry. If no port is waiting NULL is stored on the
 241          * location in question.
 242          */
 243         std::vector<PortClass*> waitingForPeer;
 244
 245         /**
 246          * Release the bus layer after being occupied and return to an
 247          * idle state where we proceed to send a retry to any
 248          * potential waiting port, or drain if asked to do so.
 249          */
 250         void releaseLayer();
 251
 252         /** event used to schedule a release of the layer */
 253         EventWrapper<Layer, &Layer::releaseLayer> releaseEvent;
 254
 255         /**
 256          * Stats for occupancy and utilization. These stats capture
 257          * the time the bus spends in the busy state and are thus only
 258          * relevant when the memory system is in timing mode.
 259          */
 260         Stats::Scalar occupancy;
 261         Stats::Formula utilization;
 262
 263     };
 264
 265     /** cycles of overhead per transaction */
 266     const Cycles headerCycles;
 267     /** the width of the bus in bytes */
 268     const uint32_t width;
 269
 270     typedef AddrRangeMap<PortID>::iterator PortMapIter;
 271     typedef AddrRangeMap<PortID>::const_iterator PortMapConstIter;
 272     AddrRangeMap<PortID> portMap;
 273
 274     /** all contigous ranges seen by this bus */
 275     AddrRangeList busRanges;
 276
 277     AddrRange defaultRange;
 278
 279     /**
 280      * Function called by the port when the bus is recieving a range change.
 281      *
 282      * @param master_port_id id of the port that received the change
 283      */
 284     void recvRangeChange(PortID master_port_id);
 285
 286     /** Find which port connected to this bus (if any) should be given a packet
 287      * with this address.
 288      * @param addr Address to find port for.
 289      * @return id of port that the packet should be sent out of.
 290      */
 291     PortID findPort(Addr addr);
 292
 293     // Cache for the findPort function storing recently used ports from portMap
 294     struct PortCache {
 295         bool valid;
 296         PortID id;
 297         AddrRange range;
 298     };
 299
 300     PortCache portCache[3];
 301
 302     // Checks the cache and returns the id of the port that has the requested
 303     // address within its range
 304     inline PortID checkPortCache(Addr addr) const {
 305         if (portCache[0].valid && portCache[0].range.contains(addr)) {
 306             return portCache[0].id;
 307         }
 308         if (portCache[1].valid && portCache[1].range.contains(addr)) {
 309             return portCache[1].id;
 310         }
 311         if (portCache[2].valid && portCache[2].range.contains(addr)) {
 312             return portCache[2].id;
 313         }
 314
 315         return InvalidPortID;
 316     }
 317
 318     // Clears the earliest entry of the cache and inserts a new port entry
 319     inline void updatePortCache(short id, const AddrRange& range) {
 320         portCache[2].valid = portCache[1].valid;
 321         portCache[2].id    = portCache[1].id;
 322         portCache[2].range = portCache[1].range;
 323
 324         portCache[1].valid = portCache[0].valid;
 325         portCache[1].id    = portCache[0].id;
 326         portCache[1].range = portCache[0].range;
 327
 328         portCache[0].valid = true;
 329         portCache[0].id    = id;
 330         portCache[0].range = range;
 331     }
 332
 333     // Clears the cache. Needs to be called in constructor.
 334     inline void clearPortCache() {
 335         portCache[2].valid = false;
 336         portCache[1].valid = false;
 337         portCache[0].valid = false;
 338     }
 339
 340     /**
 341      * Return the address ranges the bus is responsible for.
 342      *
 343      * @return a list of non-overlapping address ranges
 344      */
 345     AddrRangeList getAddrRanges() const;
 346
 347     /**
 348      * Calculate the timing parameters for the packet. Updates the
 349      * busFirstWordDelay and busLastWordDelay fields of the packet
 350      * object with the relative number of ticks required to transmit
 351      * the header and the first word, and the last word, respectively.
 352      */
 353     void calcPacketTiming(PacketPtr pkt);
 354
 355     /**
 356      * Ask everyone on the bus what their size is and determine the
 357      * bus size as either the maximum, or if no device specifies a
 358      * block size return the default.
 359      *
 360      * @return the max of all the sizes or the default if none is set
 361      */
 362     unsigned deviceBlockSize() const;
 363
 364     /**
 365      * Remember for each of the master ports of the bus if we got an
 366      * address range from the connected slave. For convenience, also
 367      * keep track of if we got ranges from all the slave modules or
 368      * not.
 369      */
 370     std::vector<bool> gotAddrRanges;
 371     bool gotAllAddrRanges;
 372
 373     /** The master and slave ports of the bus */
 374     std::vector<SlavePort*> slavePorts;
 375     std::vector<MasterPort*> masterPorts;
 376
 377     /** Convenience typedefs. */
 378     typedef std::vector<SlavePort*>::iterator SlavePortIter;
 379     typedef std::vector<MasterPort*>::iterator MasterPortIter;
 380     typedef std::vector<SlavePort*>::const_iterator SlavePortConstIter;
 381     typedef std::vector<MasterPort*>::const_iterator MasterPortConstIter;
 382
 383     /** Port that handles requests that don't match any of the interfaces.*/
 384     PortID defaultPortID;
 385
 386     /** If true, use address range provided by default device.  Any
 387        address not handled by another port and not in default device's
 388        range will cause a fatal error.  If false, just send all
 389        addresses not handled by another port to default device. */
 390     const bool useDefaultRange;
 391
 392     uint32_t blockSize;
 393
 394     BaseBus(const BaseBusParams *p);
 395
 396     virtual ~BaseBus();
 397
 398     /**
 399      * Stats for transaction distribution and data passing through the
 400      * bus. The transaction distribution is globally counting
 401      * different types of commands. The packet count and total packet
 402      * size are two-dimensional vectors that are indexed by the bus
 403      * slave port and master port id (thus the neighbouring master and
 404      * neighbouring slave), summing up both directions (request and
 405      * response).
 406      */
 407     Stats::Formula throughput;
 408     Stats::Vector transDist;
 409     Stats::Vector2d pktCount;
 410     Stats::Vector2d totPktSize;
 411
 412   public:
 413
 414     virtual void init();
 415
 416     /** A function used to return the port associated with this bus object. */
 417     BaseMasterPort& getMasterPort(const std::string& if_name,
 418                                   PortID idx = InvalidPortID);
 419     BaseSlavePort& getSlavePort(const std::string& if_name,
 420                                 PortID idx = InvalidPortID);
 421
 422     virtual unsigned int drain(DrainManager *dm) = 0;
 423
 424     virtual void regStats();
 425
 426 };
 427
 428 #endif //__MEM_BUS_HH__