src/mem/bus.hh

   1 /*
   2  * Copyright (c) 2011-2012 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 <list>
  55 #include <set>
  56
  57 #include "base/range.hh"
  58 #include "base/range_map.hh"
  59 #include "base/types.hh"
  60 #include "mem/mem_object.hh"
  61 #include "params/BaseBus.hh"
  62
  63 /**
  64  * The base bus contains the common elements of the non-coherent and
  65  * coherent bus. It is an abstract class that does not have any of the
  66  * functionality relating to the actual reception and transmission of
  67  * packets, as this is left for the subclasses.
  68  *
  69  * The BaseBus is responsible for the basic flow control (busy or
  70  * not), the administration of retries, and the address decoding.
  71  */
  72 class BaseBus : public MemObject
  73 {
  74
  75   protected:
  76
  77     /**
  78      * A bus layer is an internal bus structure with its own flow
  79      * control and arbitration. Hence, a single-layer bus mimics a
  80      * traditional off-chip tri-state bus (like PCI), where only one
  81      * set of wires are shared. For on-chip buses, a good starting
  82      * point is to have three layers, for requests, responses, and
  83      * snoop responses respectively (snoop requests are instantaneous
  84      * and do not need any flow control or arbitration). This case is
  85      * similar to AHB and some OCP configurations.
  86      *
  87      * As a further extensions beyond the three-layer bus, a future
  88      * multi-layer bus has with one layer per connected slave port
  89      * provides a full or partial crossbar, like AXI, OCP, PCIe etc.
  90      *
  91      * The template parameter, PortClass, indicates the destination
  92      * port type for the bus. The retry list holds either master ports
  93      * or slave ports, depending on the direction of the layer. Thus,
  94      * a request layer has a retry list containing slave ports,
  95      * whereas a response layer holds master ports.
  96      */
  97     template <typename PortClass>
  98     class Layer
  99     {
 100
 101       public:
 102
 103         /**
 104          * Create a bus layer and give it a name. The bus layer uses
 105          * the bus an event manager.
 106          *
 107          * @param _bus the bus this layer belongs to
 108          * @param _name the layer's name
 109          * @param _clock clock period in ticks
 110          */
 111         Layer(BaseBus& _bus, const std::string& _name, Tick _clock);
 112
 113         /**
 114          * Drain according to the normal semantics, so that the bus
 115          * can tell the layer to drain, and pass an event to signal
 116          * back when drained.
 117          *
 118          * @param de drain event to call once drained
 119          *
 120          * @return 1 if busy or waiting to retry, or 0 if idle
 121          */
 122         unsigned int drain(Event *de);
 123
 124         /**
 125          * Get the bus layer's name
 126          */
 127         const std::string name() const { return bus.name() + _name; }
 128
 129
 130         /**
 131          * Determine if the bus layer accepts a packet from a specific
 132          * port. If not, the port in question is also added to the
 133          * retry list. In either case the state of the layer is updated
 134          * accordingly.
 135          *
 136          * @param port Source port resenting the packet
 137          *
 138          * @return True if the bus layer accepts the packet
 139          */
 140         bool tryTiming(PortClass* port);
 141
 142         /**
 143          * Deal with a destination port accepting a packet by potentially
 144          * removing the source port from the retry list (if retrying) and
 145          * occupying the bus layer accordingly.
 146          *
 147          * @param busy_time Time to spend as a result of a successful send
 148          */
 149         void succeededTiming(Tick busy_time);
 150
 151         /**
 152          * Deal with a destination port not accepting a packet by
 153          * potentially adding the source port to the retry list (if
 154          * not already at the front) and occupying the bus layer
 155          * accordingly.
 156          *
 157          * @param busy_time Time to spend as a result of a failed send
 158          */
 159         void failedTiming(PortClass* port, Tick busy_time);
 160
 161         /** Occupy the bus layer until until */
 162         void occupyLayer(Tick until);
 163
 164         /**
 165          * Send a retry to the port at the head of the retryList. The
 166          * caller must ensure that the list is not empty.
 167          */
 168         void retryWaiting();
 169
 170         /**
 171          * Handler a retry from a neighbouring module. Eventually this
 172          * should be all encapsulated in the bus. This wraps
 173          * retryWaiting by verifying that there are ports waiting
 174          * before calling retryWaiting.
 175          */
 176         void recvRetry();
 177
 178       private:
 179
 180         /** The bus this layer is a part of. */
 181         BaseBus& bus;
 182
 183         /** A name for this layer. */
 184         std::string _name;
 185
 186         /**
 187          * We declare an enum to track the state of the bus layer. The
 188          * starting point is an idle state where the bus layer is
 189          * waiting for a packet to arrive. Upon arrival, the bus layer
 190          * transitions to the busy state, where it remains either
 191          * until the packet transfer is done, or the header time is
 192          * spent. Once the bus layer leaves the busy state, it can
 193          * either go back to idle, if no packets have arrived while it
 194          * was busy, or the bus layer goes on to retry the first port
 195          * on the retryList. A similar transition takes place from
 196          * idle to retry if the bus layer receives a retry from one of
 197          * its connected ports. The retry state lasts until the port
 198          * in questions calls sendTiming and returns control to the
 199          * bus layer, or goes to a busy state if the port does not
 200          * immediately react to the retry by calling sendTiming.
 201          */
 202         enum State { IDLE, BUSY, RETRY };
 203
 204         /** track the state of the bus layer */
 205         State state;
 206
 207         /** the clock speed for the bus layer */
 208         Tick clock;
 209
 210         /** event for signalling when drained */
 211         Event * drainEvent;
 212
 213         /**
 214          * An array of ports that retry should be called
 215          * on because the original send failed for whatever reason.
 216          */
 217         std::list<PortClass*> retryList;
 218
 219         /**
 220          * Release the bus layer after being occupied and return to an
 221          * idle state where we proceed to send a retry to any
 222          * potential waiting port, or drain if asked to do so.
 223          */
 224         void releaseLayer();
 225
 226         /** event used to schedule a release of the layer */
 227         EventWrapper<Layer, &Layer::releaseLayer> releaseEvent;
 228
 229     };
 230
 231     /** cycles of overhead per transaction */
 232     int headerCycles;
 233     /** the width of the bus in bytes */
 234     int width;
 235
 236     typedef range_map<Addr, PortID>::iterator PortMapIter;
 237     typedef range_map<Addr, PortID>::const_iterator PortMapConstIter;
 238     range_map<Addr, PortID> portMap;
 239
 240     AddrRangeList defaultRange;
 241
 242     /**
 243      * Function called by the port when the bus is recieving a range change.
 244      *
 245      * @param master_port_id id of the port that received the change
 246      */
 247     void recvRangeChange(PortID master_port_id);
 248
 249     /** Find which port connected to this bus (if any) should be given a packet
 250      * with this address.
 251      * @param addr Address to find port for.
 252      * @return id of port that the packet should be sent out of.
 253      */
 254     PortID findPort(Addr addr);
 255
 256     // Cache for the findPort function storing recently used ports from portMap
 257     struct PortCache {
 258         bool valid;
 259         PortID id;
 260         Addr start;
 261         Addr end;
 262     };
 263
 264     PortCache portCache[3];
 265
 266     // Checks the cache and returns the id of the port that has the requested
 267     // address within its range
 268     inline PortID checkPortCache(Addr addr) {
 269         if (portCache[0].valid && addr >= portCache[0].start &&
 270             addr < portCache[0].end) {
 271             return portCache[0].id;
 272         }
 273         if (portCache[1].valid && addr >= portCache[1].start &&
 274                    addr < portCache[1].end) {
 275             return portCache[1].id;
 276         }
 277         if (portCache[2].valid && addr >= portCache[2].start &&
 278             addr < portCache[2].end) {
 279             return portCache[2].id;
 280         }
 281
 282         return InvalidPortID;
 283     }
 284
 285     // Clears the earliest entry of the cache and inserts a new port entry
 286     inline void updatePortCache(short id, Addr start, Addr end) {
 287         portCache[2].valid = portCache[1].valid;
 288         portCache[2].id    = portCache[1].id;
 289         portCache[2].start = portCache[1].start;
 290         portCache[2].end   = portCache[1].end;
 291
 292         portCache[1].valid = portCache[0].valid;
 293         portCache[1].id    = portCache[0].id;
 294         portCache[1].start = portCache[0].start;
 295         portCache[1].end   = portCache[0].end;
 296
 297         portCache[0].valid = true;
 298         portCache[0].id    = id;
 299         portCache[0].start = start;
 300         portCache[0].end   = end;
 301     }
 302
 303     // Clears the cache. Needs to be called in constructor.
 304     inline void clearPortCache() {
 305         portCache[2].valid = false;
 306         portCache[1].valid = false;
 307         portCache[0].valid = false;
 308     }
 309
 310     /**
 311      * Return the address ranges the bus is responsible for.
 312      *
 313      * @return a list of non-overlapping address ranges
 314      */
 315     AddrRangeList getAddrRanges() const;
 316
 317     /** Calculate the timing parameters for the packet.  Updates the
 318      * firstWordTime and finishTime fields of the packet object.
 319      * Returns the tick at which the packet header is completed (which
 320      * will be all that is sent if the target rejects the packet).
 321      */
 322     Tick calcPacketTiming(PacketPtr pkt);
 323
 324     /**
 325      * Ask everyone on the bus what their size is
 326      *
 327      * @return the max of all the sizes
 328      */
 329     unsigned findBlockSize();
 330
 331     std::set<PortID> inRecvRangeChange;
 332
 333     /** The master and slave ports of the bus */
 334     std::vector<SlavePort*> slavePorts;
 335     std::vector<MasterPort*> masterPorts;
 336
 337     /** Convenience typedefs. */
 338     typedef std::vector<SlavePort*>::iterator SlavePortIter;
 339     typedef std::vector<MasterPort*>::iterator MasterPortIter;
 340     typedef std::vector<SlavePort*>::const_iterator SlavePortConstIter;
 341     typedef std::vector<MasterPort*>::const_iterator MasterPortConstIter;
 342
 343     /** Port that handles requests that don't match any of the interfaces.*/
 344     PortID defaultPortID;
 345
 346     /** If true, use address range provided by default device.  Any
 347        address not handled by another port and not in default device's
 348        range will cause a fatal error.  If false, just send all
 349        addresses not handled by another port to default device. */
 350     bool useDefaultRange;
 351
 352     unsigned defaultBlockSize;
 353     unsigned cachedBlockSize;
 354     bool cachedBlockSizeValid;
 355
 356     BaseBus(const BaseBusParams *p);
 357
 358     virtual ~BaseBus();
 359
 360   public:
 361
 362     /** A function used to return the port associated with this bus object. */
 363     virtual MasterPort& getMasterPort(const std::string& if_name, int idx = -1);
 364     virtual SlavePort& getSlavePort(const std::string& if_name, int idx = -1);
 365
 366     virtual unsigned int drain(Event *de) = 0;
 367
 368 };
 369
 370 #endif //__MEM_BUS_HH__