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     /** all contigous ranges seen by this bus */
 236     AddrRangeList busRanges;
 237
 238     AddrRange defaultRange;
 239
 240     /**
 241      * Function called by the port when the bus is recieving a range change.
 242      *
 243      * @param master_port_id id of the port that received the change
 244      */
 245     void recvRangeChange(PortID master_port_id);
 246
 247     /** Find which port connected to this bus (if any) should be given a packet
 248      * with this address.
 249      * @param addr Address to find port for.
 250      * @return id of port that the packet should be sent out of.
 251      */
 252     PortID findPort(Addr addr);
 253
 254     // Cache for the findPort function storing recently used ports from portMap
 255     struct PortCache {
 256         bool valid;
 257         PortID id;
 258         AddrRange range;
 259     };
 260
 261     PortCache portCache[3];
 262
 263     // Checks the cache and returns the id of the port that has the requested
 264     // address within its range
 265     inline PortID checkPortCache(Addr addr) const {
 266         if (portCache[0].valid && portCache[0].range.contains(addr)) {
 267             return portCache[0].id;
 268         }
 269         if (portCache[1].valid && portCache[1].range.contains(addr)) {
 270             return portCache[1].id;
 271         }
 272         if (portCache[2].valid && portCache[2].range.contains(addr)) {
 273             return portCache[2].id;
 274         }
 275
 276         return InvalidPortID;
 277     }
 278
 279     // Clears the earliest entry of the cache and inserts a new port entry
 280     inline void updatePortCache(short id, const AddrRange& range) {
 281         portCache[2].valid = portCache[1].valid;
 282         portCache[2].id    = portCache[1].id;
 283         portCache[2].range = portCache[1].range;
 284
 285         portCache[1].valid = portCache[0].valid;
 286         portCache[1].id    = portCache[0].id;
 287         portCache[1].range = portCache[0].range;
 288
 289         portCache[0].valid = true;
 290         portCache[0].id    = id;
 291         portCache[0].range = range;
 292     }
 293
 294     // Clears the cache. Needs to be called in constructor.
 295     inline void clearPortCache() {
 296         portCache[2].valid = false;
 297         portCache[1].valid = false;
 298         portCache[0].valid = false;
 299     }
 300
 301     /**
 302      * Return the address ranges the bus is responsible for.
 303      *
 304      * @return a list of non-overlapping address ranges
 305      */
 306     AddrRangeList getAddrRanges() const;
 307
 308     /**
 309      * Calculate the timing parameters for the packet. Updates the
 310      * busFirstWordDelay and busLastWordDelay fields of the packet
 311      * object with the relative number of ticks required to transmit
 312      * the header and the first word, and the last word, respectively.
 313      */
 314     void calcPacketTiming(PacketPtr pkt);
 315
 316     /**
 317      * Ask everyone on the bus what their size is and determine the
 318      * bus size as either the maximum, or if no device specifies a
 319      * block size return the default.
 320      *
 321      * @return the max of all the sizes or the default if none is set
 322      */
 323     unsigned deviceBlockSize() const;
 324
 325     /**
 326      * Remember for each of the master ports of the bus if we got an
 327      * address range from the connected slave. For convenience, also
 328      * keep track of if we got ranges from all the slave modules or
 329      * not.
 330      */
 331     std::vector<bool> gotAddrRanges;
 332     bool gotAllAddrRanges;
 333
 334     /** The master and slave ports of the bus */
 335     std::vector<SlavePort*> slavePorts;
 336     std::vector<MasterPort*> masterPorts;
 337
 338     /** Convenience typedefs. */
 339     typedef std::vector<SlavePort*>::iterator SlavePortIter;
 340     typedef std::vector<MasterPort*>::iterator MasterPortIter;
 341     typedef std::vector<SlavePort*>::const_iterator SlavePortConstIter;
 342     typedef std::vector<MasterPort*>::const_iterator MasterPortConstIter;
 343
 344     /** Port that handles requests that don't match any of the interfaces.*/
 345     PortID defaultPortID;
 346
 347     /** If true, use address range provided by default device.  Any
 348        address not handled by another port and not in default device's
 349        range will cause a fatal error.  If false, just send all
 350        addresses not handled by another port to default device. */
 351     const bool useDefaultRange;
 352
 353     uint32_t blockSize;
 354
 355     BaseBus(const BaseBusParams *p);
 356
 357     virtual ~BaseBus();
 358
 359   public:
 360
 361     virtual void init();
 362
 363     /** A function used to return the port associated with this bus object. */
 364     BaseMasterPort& getMasterPort(const std::string& if_name,
 365                                   PortID idx = InvalidPortID);
 366     BaseSlavePort& getSlavePort(const std::string& if_name,
 367                                 PortID idx = InvalidPortID);
 368
 369     virtual unsigned int drain(DrainManager *dm) = 0;
 370
 371 };
 372
 373 #endif //__MEM_BUS_HH__