sim/common/sim-events.h

   1 /* The common simulator framework for GDB, the GNU Debugger.
   2
   3    Copyright 2002-2014 Free Software Foundation, Inc.
   4
   5    Contributed by Andrew Cagney and Red Hat.
   6
   7    This file is part of GDB.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  21
  22
  23 #ifndef SIM_EVENTS_H
  24 #define SIM_EVENTS_H
  25
  26
  27 /* Notes:
  28
  29    When scheduling an event, the a delta of zero/one refers to the
  30    timeline as follows:
  31
  32    epoch   0|1              1|2              2|3              3|
  33    **queue**|--insn--|*queue*|--insn--|*queue*|--insn--|*queue*|
  34      |   ^               ^        |       ^                ^
  35      `- +0 ------------ +1 --..   `----- +0 ------------- +1 --..
  36
  37    When the queue is initialized, the time is set to zero with a
  38    number of initialization events scheduled.  Consequently, as also
  39    illustrated above, the event queue should be processed before the
  40    first instruction.  That instruction being executed during tick 1.
  41
  42    The simulator main loop may take a form similar to:
  43
  44        if (halt-/restart-setjmp)
  45          {
  46
  47            .... // Determine who should go next
  48            last-cpu-nr = get-last-cpu-nr (sd);
  49            next-cpu-nr = get-next-cpu-nr (sd);
  50            events-were-last? = (last-cpu-nr >= nr-cpus);
  51            events-were-next? = (next-cpu-nr >= nr-cpus);
  52
  53            .... // process any outstanding events
  54            sim_events_preprocess (sd, events-were-last?, events-were-next?);
  55            if (events-were-next)
  56              next-cpu-nr = 0;
  57
  58            .... // prime main loop
  59
  60            while (1)
  61              {
  62                 .... // model one insn of next-cpu-nr .. nr-cpus
  63                 if (sim_events_tick (sd))
  64                   sim_events_process (sd);
  65                 next-cpu-nr = 0
  66              }
  67          }
  68
  69    NB.  In the above pseudo code it is assumed that any cpu-nr >=
  70    nr-cpus is a marker for the event queue. */
  71
  72
  73 typedef void sim_event_handler(SIM_DESC sd, void *data);
  74
  75 typedef struct _sim_event sim_event;
  76
  77 typedef struct _sim_events sim_events;
  78 struct _sim_events {
  79   int nr_ticks_to_process;
  80   sim_event *queue;
  81   sim_event *watchpoints;
  82   sim_event *watchedpoints;
  83   sim_event *free_list;
  84   /* flag additional work needed */
  85   volatile int work_pending;
  86   /* the asynchronous event queue */
  87 #ifndef MAX_NR_SIGNAL_SIM_EVENTS
  88 #define MAX_NR_SIGNAL_SIM_EVENTS 2
  89 #endif
  90   sim_event *held;
  91   volatile int nr_held;
  92   /* timekeeping */
  93   unsigned long elapsed_wallclock;
  94   SIM_ELAPSED_TIME resume_wallclock;
  95   signed64 time_of_event;
  96   signed64 time_from_event;
  97   int trace;
  98 };
  99
 100
 101
 102 /* Install the "events" module.  */
 103
 104 extern SIM_RC sim_events_install (SIM_DESC sd);
 105
 106
 107 /* Schedule an event DELTA_TIME ticks into the future */
 108
 109 extern sim_event *sim_events_schedule
 110 (SIM_DESC sd,
 111  signed64 delta_time,
 112  sim_event_handler *handler,
 113  void *data);
 114
 115 extern sim_event *sim_events_schedule_tracef
 116 (SIM_DESC sd,
 117  signed64 delta_time,
 118  sim_event_handler *handler,
 119  void *data,
 120  const char *fmt,
 121  ...) __attribute__ ((format (printf, 5, 6)));
 122
 123 extern sim_event *sim_events_schedule_vtracef
 124 (SIM_DESC sd,
 125  signed64 delta_time,
 126  sim_event_handler *handler,
 127  void *data,
 128  const char *fmt,
 129  va_list ap);
 130
 131
 132 extern void sim_events_schedule_after_signal
 133 (SIM_DESC sd,
 134  signed64 delta_time,
 135  sim_event_handler *handler,
 136  void *data);
 137
 138 /* NB: signal level events can't have trace strings as malloc isn't
 139    available */
 140
 141
 142
 143 /* Schedule an event milli-seconds from NOW.  The exact interpretation
 144    of wallclock is host dependant. */
 145
 146 extern sim_event *sim_events_watch_clock
 147 (SIM_DESC sd,
 148  unsigned delta_ms_time,
 149  sim_event_handler *handler,
 150  void *data);
 151
 152
 153 /* Schedule an event when the test (IS_WITHIN == (VAL >= LB && VAL <=
 154    UB)) of the NR_BYTES value at HOST_ADDR with BYTE_ORDER endian is
 155    true.
 156
 157    HOST_ADDR: pointer into the host address space.
 158    BYTE_ORDER: 0 - host endian; BIG_ENDIAN; LITTLE_ENDIAN */
 159
 160 extern sim_event *sim_events_watch_sim
 161 (SIM_DESC sd,
 162  void *host_addr,
 163  int nr_bytes,
 164  int byte_order,
 165  int is_within,
 166  unsigned64 lb,
 167  unsigned64 ub,
 168  sim_event_handler *handler,
 169  void *data);
 170
 171
 172 /* Schedule an event when the test (IS_WITHIN == (VAL >= LB && VAL <=
 173    UB)) of the NR_BYTES value at CORE_ADDR in BYTE_ORDER endian is
 174    true.
 175
 176    CORE_ADDR/MAP: pointer into the target address space.
 177    BYTE_ORDER: 0 - current target endian; BIG_ENDIAN; LITTLE_ENDIAN */
 178
 179 extern sim_event *sim_events_watch_core
 180 (SIM_DESC sd,
 181  address_word core_addr,
 182  unsigned map,
 183  int nr_bytes,
 184  int byte_order,
 185  int is_within,
 186  unsigned64 lb,
 187  unsigned64 ub,
 188  sim_event_handler *handler,
 189  void *data);
 190
 191 /* Deschedule the specified event */
 192
 193 extern void sim_events_deschedule
 194 (SIM_DESC sd,
 195  sim_event *event_to_remove);
 196
 197
 198 /* Prepare for main simulator loop.  Ensure that the next thing to do
 199    is not event processing.
 200
 201    If the simulator halted part way through event processing then both
 202    EVENTS_WERE_LAST and EVENTS_WERE_NEXT shall be true.
 203
 204    If the simulator halted after processing the last cpu, then only
 205    EVENTS_WERE_NEXT shall be true. */
 206
 207 INLINE_SIM_EVENTS\
 208 (void) sim_events_preprocess
 209 (SIM_DESC sd,
 210  int events_were_last,
 211  int events_were_next);
 212
 213
 214 /* Progress time.
 215
 216    Separated into two parts so that the main loop can save its context
 217    before the event queue is processed.  When sim_events_tick*()
 218    returns true, any simulation context should be saved and
 219    sim_events_process() called.
 220
 221    SIM_EVENTS_TICK advances the clock by 1 cycle.
 222
 223    SIM_EVENTS_TICKN advances the clock by N cycles (1..MAXINT). */
 224
 225 INLINE_SIM_EVENTS\
 226 (int) sim_events_tick
 227 (SIM_DESC sd);
 228
 229 INLINE_SIM_EVENTS\
 230 (int) sim_events_tickn
 231 (SIM_DESC sd,
 232  int n);
 233
 234 INLINE_SIM_EVENTS\
 235 (void) sim_events_process
 236 (SIM_DESC sd);
 237
 238
 239 /* Advance the clock by an additional SLIP cycles at the next call to
 240    sim_events_tick*().  For multiple calls, the effect is
 241    accumulative. */
 242
 243 INLINE_SIM_EVENTS\
 244 (void) sim_events_slip
 245 (SIM_DESC sd,
 246  int slip);
 247
 248
 249 /* Progress time such that an event shall occur upon the next call to
 250    sim_events tick */
 251
 252 #if 0
 253 INLINE_SIM_EVENTS\
 254 (void) sim_events_timewarp
 255 (SIM_DESC sd);
 256 #endif
 257
 258
 259 /* local concept of elapsed target time */
 260
 261 INLINE_SIM_EVENTS\
 262 (signed64) sim_events_time
 263 (SIM_DESC sd);
 264
 265
 266 /* local concept of elapsed host time (milliseconds) */
 267
 268 INLINE_SIM_EVENTS\
 269 (unsigned long) sim_events_elapsed_time
 270 (SIM_DESC sd);
 271
 272 /* Returns the time that remains before the event is raised. */
 273 INLINE_SIM_EVENTS\
 274 (signed64) sim_events_remain_time
 275 (SIM_DESC sd, sim_event *event);
 276
 277
 278 #endif