src/sim/global_event.hh

   1 /*
   2  * Copyright (c) 2011-2013 Advanced Micro Devices, Inc.
   3  * Copyright (c) 2013 Mark D. Hill and David A. Wood
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are
   8  * met: redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer;
  10  * redistributions in binary form must reproduce the above copyright
  11  * notice, this list of conditions and the following disclaimer in the
  12  * documentation and/or other materials provided with the distribution;
  13  * neither the name of the copyright holders nor the names of its
  14  * contributors may be used to endorse or promote products derived from
  15  * this software without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28  */
  29
  30 #ifndef __SIM_GLOBAL_EVENT_HH__
  31 #define __SIM_GLOBAL_EVENT_HH__
  32
  33 #include <mutex>
  34 #include <vector>
  35
  36 #include "base/barrier.hh"
  37 #include "sim/eventq.hh"
  38
  39 /**
  40  * @file sim/global_event.hh
  41  * Global events and related declarations.
  42  *
  43  * A global event is an event that occurs across all threads, i.e.,
  44  * globally.  It consists of a set of "local" (regular) Events, one
  45  * per thread/event queue, a barrier object, and common state.  The
  46  * local events are scheduled for the same tick.  The local event
  47  * process() method enters the barrier to wait for other threads; once
  48  * all threads reach that tick (and enter the associated barrier), the
  49  * global event is triggered and its associated activity is performed.
  50  *
  51  * There are two basic global event patterns, GlobalEvent and
  52  * GlobalSyncEvent.  GlobalEvent is the base class for typical global
  53  * events, while GlobalSyncEvent is optimized for global
  54  * synchronization operations.
  55  */
  56
  57 /**
  58  * Common base class for GlobalEvent and GlobalSyncEvent.
  59  */
  60 class BaseGlobalEvent : public EventBase
  61 {
  62   private:
  63       //! Mutex variable for providing exculsive right to schedule global
  64       //! events. This is necessary so that a total order can be maintained
  65       //! amongst the global events. Without ensuring the total order, it is
  66       //! possible that threads execute global events in different orders,
  67       //! which can result in a deadlock.
  68       static std::mutex globalQMutex;
  69
  70   protected:
  71
  72     /// The base class for the local events that will synchronize
  73     /// threads to perform the global event.  This class is abstract,
  74     /// since it derives from the abstract Event class but still does
  75     /// not define the required process() method.
  76     class BarrierEvent : public Event
  77     {
  78       protected:
  79         BaseGlobalEvent *_globalEvent;
  80
  81         BarrierEvent(BaseGlobalEvent *global_event, Priority p, Flags f)
  82             : Event(p, f), _globalEvent(global_event)
  83         {
  84         }
  85
  86         ~BarrierEvent();
  87
  88         friend class BaseGlobalEvent;
  89
  90         bool globalBarrier()
  91         {
  92             // This method will be called from the process() method in
  93             // the local barrier events
  94             // (GlobalSyncEvent::BarrierEvent).  The local event
  95             // queues are always locked when servicing events (calling
  96             // the process() method), which means that it will be
  97             // locked when entering this method. We need to unlock it
  98             // while waiting on the barrier to prevent deadlocks if
  99             // another thread wants to lock the event queue.
 100             EventQueue::ScopedRelease release(curEventQueue());
 101             return _globalEvent->barrier.wait();
 102         }
 103
 104       public:
 105         virtual BaseGlobalEvent *globalEvent() { return _globalEvent; }
 106     };
 107
 108     //! The barrier that all threads wait on before performing the
 109     //! global event.
 110     Barrier barrier;
 111
 112     //! The individual local event instances (one per thread/event queue).
 113     std::vector<BarrierEvent *> barrierEvent;
 114
 115   public:
 116     BaseGlobalEvent(Priority p, Flags f);
 117
 118     virtual ~BaseGlobalEvent();
 119
 120     virtual void process() = 0;
 121
 122     virtual const char *description() const = 0;
 123
 124     void schedule(Tick when);
 125
 126     bool scheduled() const
 127     {
 128         bool sched = false;
 129         for (uint32_t i = 0; i < numMainEventQueues; ++i) {
 130             sched = sched || barrierEvent[i]->scheduled();
 131         }
 132
 133         return sched;
 134     }
 135
 136     Tick when() const
 137     {
 138         assert(numMainEventQueues > 0);
 139         return barrierEvent[0]->when();
 140     }
 141
 142     void deschedule();
 143     void reschedule(Tick when);
 144 };
 145
 146
 147 /**
 148  * Funky intermediate class to support CRTP so that we can have a
 149  * common constructor to create the local events, even though the
 150  * types of the local events are defined in the derived classes.
 151  */
 152 template <class Derived>
 153 class BaseGlobalEventTemplate : public BaseGlobalEvent
 154 {
 155   protected:
 156     BaseGlobalEventTemplate(Priority p, Flags f)
 157         : BaseGlobalEvent(p, f)
 158     {
 159         for (int i = 0; i < numMainEventQueues; ++i)
 160             barrierEvent[i] = new typename Derived::BarrierEvent(this, p, f);
 161     }
 162 };
 163
 164
 165 /**
 166  * The main global event class.  Ordinary global events should derive
 167  * from this class, and define process() to specify the action to be
 168  * taken when the event is reached.  All threads will synchronize at a
 169  * barrier, exactly one of the threads will execute the process()
 170  * method, then the threads will synchronize again so that none of
 171  * them continue until process() is complete.
 172  */
 173 class GlobalEvent : public BaseGlobalEventTemplate<GlobalEvent>
 174 {
 175   public:
 176     typedef BaseGlobalEventTemplate<GlobalEvent> Base;
 177
 178     class BarrierEvent : public Base::BarrierEvent
 179     {
 180       public:
 181         void process();
 182         BarrierEvent(Base *global_event, Priority p, Flags f)
 183             : Base::BarrierEvent(global_event, p, f)
 184         { }
 185     };
 186
 187     GlobalEvent(Priority p, Flags f)
 188         : Base(p, f)
 189     { }
 190
 191     GlobalEvent(Tick when, Priority p, Flags f)
 192         : Base(p, f)
 193     {
 194         schedule(when);
 195     }
 196
 197     virtual void process() = 0;
 198 };
 199
 200 /**
 201  * A special global event that synchronizes all threads and forces
 202  * them to process asynchronously enqueued events.  Useful for
 203  * separating quanta in a quantum-based parallel simulation.
 204  */
 205 class GlobalSyncEvent : public BaseGlobalEventTemplate<GlobalSyncEvent>
 206 {
 207   public:
 208     typedef BaseGlobalEventTemplate<GlobalSyncEvent> Base;
 209
 210     class BarrierEvent : public Base::BarrierEvent
 211     {
 212       public:
 213         void process();
 214         BarrierEvent(Base *global_event, Priority p, Flags f)
 215             : Base::BarrierEvent(global_event, p, f)
 216         { }
 217     };
 218
 219     GlobalSyncEvent(Priority p, Flags f)
 220         : Base(p, f), repeat(0)
 221     { }
 222
 223     GlobalSyncEvent(Tick when, Tick _repeat, Priority p, Flags f)
 224         : Base(p, f), repeat(_repeat)
 225     {
 226         schedule(when);
 227     }
 228
 229     void process();
 230
 231     const char *description() const;
 232
 233     Tick repeat;
 234 };
 235
 236
 237 #endif // __SIM_GLOBAL_EVENT_HH__