sim/eventq.hh

   1 /*
   2  * Copyright (c) 2003 The Regents of The University of Michigan
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are
   7  * met: redistributions of source code must retain the above copyright
   8  * notice, this list of conditions and the following disclaimer;
   9  * redistributions in binary form must reproduce the above copyright
  10  * notice, this list of conditions and the following disclaimer in the
  11  * documentation and/or other materials provided with the distribution;
  12  * neither the name of the copyright holders nor the names of its
  13  * contributors may be used to endorse or promote products derived from
  14  * this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  20  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  26  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /* @file
  30  * EventQueue interfaces
  31  */
  32
  33 #ifndef __EVENTQ_HH__
  34 #define __EVENTQ_HH__
  35
  36 #include <assert.h>
  37
  38 #include <algorithm>
  39 #include <map>
  40 #include <string>
  41 #include <vector>
  42
  43 #include "sim/host.hh"  // for Tick
  44
  45 #include "base/fast_alloc.hh"
  46 #include "sim/serialize.hh"
  47 #include "base/trace.hh"
  48
  49 class EventQueue;       // forward declaration
  50
  51 /*
  52  * An item on an event queue.  The action caused by a given
  53  * event is specified by deriving a subclass and overriding the
  54  * process() member function.
  55  */
  56 class Event : public Serializeable, public FastAlloc
  57 {
  58     friend class EventQueue;
  59
  60   private:
  61     /// queue to which this event belongs (though it may or may not be
  62     /// scheduled on this queue yet)
  63     EventQueue *queue;
  64
  65     Event *next;
  66
  67     Tick _when; //!< timestamp when event should be processed
  68     int _priority;      //!< event priority
  69     char _flags;
  70
  71   protected:
  72     enum Flags {
  73         None = 0x0,
  74         Squashed = 0x1,
  75         Scheduled = 0x2,
  76         AutoDelete = 0x4,
  77         AutoSerialize = 0x8
  78     };
  79
  80     bool getFlags(Flags f) const { return (_flags & f) == f; }
  81     void setFlags(Flags f) { _flags |= f; }
  82     void clearFlags(Flags f) { _flags &= ~f; }
  83
  84   protected:
  85     EventQueue *theQueue() const { return queue; }
  86
  87 #if TRACING_ON
  88     Tick when_created;  //!< Keep track of creation time For debugging
  89     Tick when_scheduled;        //!< Keep track of creation time For debugging
  90
  91     virtual void trace(const char *action);     //!< trace event activity
  92 #else
  93     void trace(const char *) {}
  94 #endif
  95
  96     unsigned annotated_value;
  97
  98   public:
  99
 100     /*
 101      * Event constructor
 102      * @param queue that the event gets scheduled on
 103      */
 104     Event(EventQueue *q, int p = 0)
 105         : queue(q), next(NULL), _priority(p), _flags(None),
 106 #if TRACING_ON
 107           when_created(curTick), when_scheduled(0),
 108 #endif
 109           annotated_value(0)
 110     {
 111     }
 112
 113     ~Event() {}
 114
 115     virtual std::string name() const {
 116         return csprintf("Event_%x", (uintptr_t)this);
 117     }
 118
 119     /// Determine if the current event is scheduled
 120     bool scheduled() const { return getFlags(Scheduled); }
 121
 122     /// Schedule the event with the current priority or default priority
 123     void schedule(Tick t);
 124
 125     /// Schedule the event with a specific priority
 126     void schedule(Tick t, int priority);
 127
 128     /// Reschedule the event with the current priority
 129     void reschedule(Tick t);
 130
 131     /// Reschedule the event with a specific priority
 132     void reschedule(Tick t, int priority);
 133
 134     /// Remove the event from the current schedule
 135     void deschedule();
 136
 137     /// Return a C string describing the event.  This string should
 138     /// *not* be dynamically allocated; just a const char array
 139     /// describing the event class.
 140     virtual const char *description();
 141
 142     /// Dump the current event data
 143     void dump();
 144
 145     /*
 146      * This member function is invoked when the event is processed
 147      * (occurs).  There is no default implementation; each subclass
 148      * must provide its own implementation.  The event is not
 149      * automatically deleted after it is processed (to allow for
 150      * statically allocated event objects).
 151      *
 152      * If the AutoDestroy flag is set, the object is deleted once it
 153      * is processed.
 154      */
 155     virtual void process() = 0;
 156
 157     void annotate(unsigned value) { annotated_value = value; };
 158     unsigned annotation() { return annotated_value; }
 159
 160     /// Squash the current event
 161     void squash() { setFlags(Squashed); }
 162
 163     /// Check whether the event is squashed
 164     bool squashed() { return getFlags(Squashed); }
 165
 166     /// Get the time that the event is scheduled
 167     Tick when() const { return _when; }
 168
 169     /// Get the event priority
 170     int priority() const { return _priority; }
 171
 172     struct priority_compare :
 173     public std::binary_function<Event *, Event *, bool>
 174     {
 175         bool operator()(const Event *l, const Event *r) const {
 176             return l->when() >= r->when() || l->priority() >= r->priority();
 177         }
 178     };
 179
 180     virtual void serialize(std::ostream &os);
 181     virtual void unserialize(Checkpoint *cp, const std::string &section);
 182 };
 183
 184 template <class T, void (T::* F)()>
 185 void
 186 DelayFunction(Tick when, T *object)
 187 {
 188     class DelayEvent : public Event
 189     {
 190       private:
 191         T *object;
 192
 193       public:
 194         DelayEvent(Tick when, T *o)
 195             : Event(&mainEventQueue), object(o)
 196             { setFlags(AutoDestroy); schedule(when); }
 197         void process() { (object->*F)(); }
 198         const char *description() { return "delay"; }
 199     };
 200
 201     new DelayEvent(when, object);
 202 }
 203
 204 /*
 205  * Queue of events sorted in time order
 206  */
 207 class EventQueue : public Serializeable
 208 {
 209   protected:
 210     std::string objName;
 211
 212   private:
 213     Event *head;
 214
 215     void insert(Event *event);
 216     void remove(Event *event);
 217
 218   public:
 219
 220     // constructor
 221     EventQueue(const std::string &n)
 222         : objName(n), head(NULL)
 223     {}
 224
 225     virtual std::string name() const { return objName; }
 226
 227     // schedule the given event on this queue
 228     void schedule(Event *ev);
 229     void deschedule(Event *ev);
 230     void reschedule(Event *ev);
 231
 232     Tick nextTick() { return head->when(); }
 233     void serviceOne();
 234
 235     // process all events up to the given timestamp.  we inline a
 236     // quick test to see if there are any events to process; if so,
 237     // call the internal out-of-line version to process them all.
 238     void serviceEvents(Tick when) {
 239         while (!empty()) {
 240             if (nextTick() > when)
 241                 break;
 242
 243             assert(head->when() >= when && "event scheduled in the past");
 244             serviceOne();
 245         }
 246     }
 247
 248     // default: process all events up to 'now' (curTick)
 249     void serviceEvents() { serviceEvents(curTick); }
 250
 251     // return true if no events are queued
 252     bool empty() { return head == NULL; }
 253
 254     void dump();
 255
 256     Tick nextEventTime() { return empty() ? curTick : head->when(); }
 257
 258     virtual void serialize(std::ostream &os);
 259     virtual void unserialize(Checkpoint *cp, const std::string &section);
 260 };
 261
 262
 263 //////////////////////
 264 //
 265 // inline functions
 266 //
 267 // can't put these inside declaration due to circular dependence
 268 // between Event and EventQueue classes.
 269 //
 270 //////////////////////
 271
 272 // schedule at specified time (place on event queue specified via
 273 // constructor)
 274 inline void
 275 Event::schedule(Tick t)
 276 {
 277     assert(!scheduled());
 278     setFlags(Scheduled);
 279 #if TRACING_ON
 280     when_scheduled = curTick;
 281 #endif
 282     _when = t;
 283     queue->schedule(this);
 284 }
 285
 286 inline void
 287 Event::schedule(Tick t, int p)
 288 {
 289     _priority = p;
 290     schedule(t);
 291 }
 292
 293 inline void
 294 Event::deschedule()
 295 {
 296     assert(scheduled());
 297
 298     clearFlags(Squashed);
 299     clearFlags(Scheduled);
 300     queue->deschedule(this);
 301 }
 302
 303 inline void
 304 Event::reschedule(Tick t)
 305 {
 306     assert(scheduled());
 307     clearFlags(Squashed);
 308
 309 #if TRACING_ON
 310     when_scheduled = curTick;
 311 #endif
 312     _when = t;
 313     queue->reschedule(this);
 314 }
 315
 316 inline void
 317 Event::reschedule(Tick t, int p)
 318 {
 319     _priority = p;
 320     reschedule(t);
 321 }
 322
 323 inline void
 324 EventQueue::schedule(Event *event)
 325 {
 326     insert(event);
 327     if (DTRACE(Event))
 328         event->trace("scheduled");
 329 }
 330
 331 inline void
 332 EventQueue::deschedule(Event *event)
 333 {
 334     remove(event);
 335     if (DTRACE(Event))
 336         event->trace("descheduled");
 337 }
 338
 339 inline void
 340 EventQueue::reschedule(Event *event)
 341 {
 342     remove(event);
 343     insert(event);
 344     if (DTRACE(Event))
 345         event->trace("rescheduled");
 346 }
 347
 348
 349 //////////////////////
 350 //
 351 // Main Event Queue
 352 //
 353 // Events on this queue are processed at the *beginning* of each
 354 // cycle, before the pipeline simulation is performed.
 355 //
 356 // defined in eventq.cc
 357 //
 358 //////////////////////
 359 extern EventQueue mainEventQueue;
 360
 361 #endif // __EVENTQ_HH__