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 #include <set>
  56
  57 #include "base/addr_range_map.hh"
  58 #include "base/types.hh"
  59 #include "mem/mem_object.hh"
  60 #include "params/BaseBus.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          */
 109         Layer(BaseBus& _bus, const std::string& _name);
 110
 111         /**
 112          * Drain according to the normal semantics, so that the bus
 113          * can tell the layer to drain, and pass an event to signal
 114          * back when drained.
 115          *
 116          * @param de drain event to call once drained
 117          *
 118          * @return 1 if busy or waiting to retry, or 0 if idle
 119          */
 120         unsigned int drain(DrainManager *dm);
 121
 122         /**
 123          * Get the bus layer's name
 124          */
 125         const std::string name() const { return bus.name() + _name; }
 126
 127
 128         /**
 129          * Determine if the bus layer accepts a packet from a specific
 130          * port. If not, the port in question is also added to the
 131          * retry list. In either case the state of the layer is updated
 132          * accordingly.
 133          *
 134          * @param port Source port resenting the packet
 135          *
 136          * @return True if the bus layer accepts the packet
 137          */
 138         bool tryTiming(PortClass* port);
 139
 140         /**
 141          * Deal with a destination port accepting a packet by potentially
 142          * removing the source port from the retry list (if retrying) and
 143          * occupying the bus layer accordingly.
 144          *
 145          * @param busy_time Time to spend as a result of a successful send
 146          */
 147         void succeededTiming(Tick busy_time);
 148
 149         /**
 150          * Deal with a destination port not accepting a packet by
 151          * potentially adding the source port to the retry list (if
 152          * not already at the front) and occupying the bus layer
 153          * accordingly.
 154          *
 155          * @param busy_time Time to spend as a result of a failed send
 156          */
 157         void failedTiming(PortClass* port, Tick busy_time);
 158
 159         /** Occupy the bus layer until until */
 160         void occupyLayer(Tick until);
 161
 162         /**
 163          * Send a retry to the port at the head of the retryList. The
 164          * caller must ensure that the list is not empty.
 165          */
 166         void retryWaiting();
 167
 168         /**
 169          * Handler a retry from a neighbouring module. Eventually this
 170          * should be all encapsulated in the bus. This wraps
 171          * retryWaiting by verifying that there are ports waiting
 172          * before calling retryWaiting.
 173          */
 174         void recvRetry();
 175
 176       private:
 177
 178         /** The bus this layer is a part of. */
 179         BaseBus& bus;
 180
 181         /** A name for this layer. */
 182         std::string _name;
 183
 184         /**
 185          * We declare an enum to track the state of the bus layer. The
 186          * starting point is an idle state where the bus layer is
 187          * waiting for a packet to arrive. Upon arrival, the bus layer
 188          * transitions to the busy state, where it remains either
 189          * until the packet transfer is done, or the header time is
 190          * spent. Once the bus layer leaves the busy state, it can
 191          * either go back to idle, if no packets have arrived while it
 192          * was busy, or the bus layer goes on to retry the first port
 193          * on the retryList. A similar transition takes place from
 194          * idle to retry if the bus layer receives a retry from one of
 195          * its connected ports. The retry state lasts until the port
 196          * in questions calls sendTiming and returns control to the
 197          * bus layer, or goes to a busy state if the port does not
 198          * immediately react to the retry by calling sendTiming.
 199          */
 200         enum State { IDLE, BUSY, RETRY };
 201
 202         /** track the state of the bus layer */
 203         State state;
 204
 205         /** manager to signal when drained */
 206         DrainManager *drainManager;
 207
 208         /**
 209          * An array of ports that retry should be called
 210          * on because the original send failed for whatever reason.
 211          */
 212         std::deque<PortClass*> retryList;
 213
 214         /**
 215          * Release the bus layer after being occupied and return to an
 216          * idle state where we proceed to send a retry to any
 217          * potential waiting port, or drain if asked to do so.
 218          */
 219         void releaseLayer();
 220
 221         /** event used to schedule a release of the layer */
 222         EventWrapper<Layer, &Layer::releaseLayer> releaseEvent;
 223
 224     };
 225
 226     /** cycles of overhead per transaction */
 227     const Cycles headerCycles;
 228     /** the width of the bus in bytes */
 229     const uint32_t width;
 230
 231     typedef AddrRangeMap<PortID>::iterator PortMapIter;
 232     typedef AddrRangeMap<PortID>::const_iterator PortMapConstIter;
 233     AddrRangeMap<PortID> portMap;
 234
 235     AddrRange defaultRange;
 236
 237     /**
 238      * Function called by the port when the bus is recieving a range change.
 239      *
 240      * @param master_port_id id of the port that received the change
 241      */
 242     void recvRangeChange(PortID master_port_id);
 243
 244     /** Find which port connected to this bus (if any) should be given a packet
 245      * with this address.
 246      * @param addr Address to find port for.
 247      * @return id of port that the packet should be sent out of.
 248      */
 249     PortID findPort(Addr addr);
 250
 251     // Cache for the findPort function storing recently used ports from portMap
 252     struct PortCache {
 253         bool valid;
 254         PortID id;
 255         AddrRange range;
 256     };
 257
 258     PortCache portCache[3];
 259
 260     // Checks the cache and returns the id of the port that has the requested
 261     // address within its range
 262     inline PortID checkPortCache(Addr addr) const {
 263         if (portCache[0].valid && portCache[0].range.contains(addr)) {
 264             return portCache[0].id;
 265         }
 266         if (portCache[1].valid && portCache[1].range.contains(addr)) {
 267             return portCache[1].id;
 268         }
 269         if (portCache[2].valid && portCache[2].range.contains(addr)) {
 270             return portCache[2].id;
 271         }
 272
 273         return InvalidPortID;
 274     }
 275
 276     // Clears the earliest entry of the cache and inserts a new port entry
 277     inline void updatePortCache(short id, const AddrRange& range) {
 278         portCache[2].valid = portCache[1].valid;
 279         portCache[2].id    = portCache[1].id;
 280         portCache[2].range = portCache[1].range;
 281
 282         portCache[1].valid = portCache[0].valid;
 283         portCache[1].id    = portCache[0].id;
 284         portCache[1].range = portCache[0].range;
 285
 286         portCache[0].valid = true;
 287         portCache[0].id    = id;
 288         portCache[0].range = range;
 289     }
 290
 291     // Clears the cache. Needs to be called in constructor.
 292     inline void clearPortCache() {
 293         portCache[2].valid = false;
 294         portCache[1].valid = false;
 295         portCache[0].valid = false;
 296     }
 297
 298     /**
 299      * Return the address ranges the bus is responsible for.
 300      *
 301      * @return a list of non-overlapping address ranges
 302      */
 303     AddrRangeList getAddrRanges() const;
 304
 305     /**
 306      * Calculate the timing parameters for the packet. Updates the
 307      * busFirstWordDelay and busLastWordDelay fields of the packet
 308      * object with the relative number of ticks required to transmit
 309      * the header and the first word, and the last word, respectively.
 310      */
 311     void calcPacketTiming(PacketPtr pkt);
 312
 313     /**
 314      * Ask everyone on the bus what their size is and determine the
 315      * bus size as either the maximum, or if no device specifies a
 316      * block size return the default.
 317      *
 318      * @return the max of all the sizes or the default if none is set
 319      */
 320     unsigned deviceBlockSize() const;
 321
 322     /**
 323      * Remember for each of the master ports of the bus if we got an
 324      * address range from the connected slave. For convenience, also
 325      * keep track of if we got ranges from all the slave modules or
 326      * not.
 327      */
 328     std::vector<bool> gotAddrRanges;
 329     bool gotAllAddrRanges;
 330
 331     /** The master and slave ports of the bus */
 332     std::vector<SlavePort*> slavePorts;
 333     std::vector<MasterPort*> masterPorts;
 334
 335     /** Convenience typedefs. */
 336     typedef std::vector<SlavePort*>::iterator SlavePortIter;
 337     typedef std::vector<MasterPort*>::iterator MasterPortIter;
 338     typedef std::vector<SlavePort*>::const_iterator SlavePortConstIter;
 339     typedef std::vector<MasterPort*>::const_iterator MasterPortConstIter;
 340
 341     /** Port that handles requests that don't match any of the interfaces.*/
 342     PortID defaultPortID;
 343
 344     /** If true, use address range provided by default device.  Any
 345        address not handled by another port and not in default device's
 346        range will cause a fatal error.  If false, just send all
 347        addresses not handled by another port to default device. */
 348     const bool useDefaultRange;
 349
 350     uint32_t blockSize;
 351
 352     BaseBus(const BaseBusParams *p);
 353
 354     virtual ~BaseBus();
 355
 356   public:
 357
 358     virtual void init();
 359
 360     /** A function used to return the port associated with this bus object. */
 361     BaseMasterPort& getMasterPort(const std::string& if_name,
 362                                   PortID idx = InvalidPortID);
 363     BaseSlavePort& getSlavePort(const std::string& if_name,
 364                                 PortID idx = InvalidPortID);
 365
 366     virtual unsigned int drain(DrainManager *dm) = 0;
 367
 368 };
 369
 370 #endif //__MEM_BUS_HH__