sim-events.h revision 1.1.1.6 
1/* The common simulator framework for GDB, the GNU Debugger.
2
3   Copyright 2002-2016 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
73typedef void sim_event_handler(SIM_DESC sd, void *data);
74
75typedef struct _sim_event sim_event;
76
77typedef struct _sim_events sim_events;
78struct _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};
98
99
100
101/* Install the "events" module.  */
102
103extern SIM_RC sim_events_install (SIM_DESC sd);
104
105
106/* Schedule an event DELTA_TIME ticks into the future */
107
108extern sim_event *sim_events_schedule
109(SIM_DESC sd,
110 signed64 delta_time,
111 sim_event_handler *handler,
112 void *data);
113
114extern sim_event *sim_events_schedule_tracef
115(SIM_DESC sd,
116 signed64 delta_time,
117 sim_event_handler *handler,
118 void *data,
119 const char *fmt,
120 ...) __attribute__ ((format (printf, 5, 6)));
121
122extern sim_event *sim_events_schedule_vtracef
123(SIM_DESC sd,
124 signed64 delta_time,
125 sim_event_handler *handler,
126 void *data,
127 const char *fmt,
128 va_list ap);
129
130
131extern void sim_events_schedule_after_signal
132(SIM_DESC sd,
133 signed64 delta_time,
134 sim_event_handler *handler,
135 void *data);
136
137/* NB: signal level events can't have trace strings as malloc isn't
138   available */
139
140
141
142/* Schedule an event milli-seconds from NOW.  The exact interpretation
143   of wallclock is host dependant. */
144
145extern sim_event *sim_events_watch_clock
146(SIM_DESC sd,
147 unsigned delta_ms_time,
148 sim_event_handler *handler,
149 void *data);
150
151
152/* Schedule an event when the test (IS_WITHIN == (VAL >= LB && VAL <=
153   UB)) of the NR_BYTES value at HOST_ADDR with BYTE_ORDER endian is
154   true.
155
156   HOST_ADDR: pointer into the host address space.
157   BYTE_ORDER: BFD_ENDIAN_UNKNOWN - host endian; BFD_ENDIAN_BIG;
158	       BFD_ENDIAN_LITTLE.  */
159
160extern 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: BFD_ENDIAN_UNKNOWN - host endian; BFD_ENDIAN_BIG;
178	       BFD_ENDIAN_LITTLE.  */
179
180extern sim_event *sim_events_watch_core
181(SIM_DESC sd,
182 address_word core_addr,
183 unsigned map,
184 int nr_bytes,
185 int byte_order,
186 int is_within,
187 unsigned64 lb,
188 unsigned64 ub,
189 sim_event_handler *handler,
190 void *data);
191
192/* Deschedule the specified event */
193
194extern void sim_events_deschedule
195(SIM_DESC sd,
196 sim_event *event_to_remove);
197
198
199/* Prepare for main simulator loop.  Ensure that the next thing to do
200   is not event processing.
201
202   If the simulator halted part way through event processing then both
203   EVENTS_WERE_LAST and EVENTS_WERE_NEXT shall be true.
204
205   If the simulator halted after processing the last cpu, then only
206   EVENTS_WERE_NEXT shall be true. */
207
208INLINE_SIM_EVENTS\
209(void) sim_events_preprocess
210(SIM_DESC sd,
211 int events_were_last,
212 int events_were_next);
213
214
215/* Progress time.
216
217   Separated into two parts so that the main loop can save its context
218   before the event queue is processed.  When sim_events_tick*()
219   returns true, any simulation context should be saved and
220   sim_events_process() called.
221
222   SIM_EVENTS_TICK advances the clock by 1 cycle.
223
224   SIM_EVENTS_TICKN advances the clock by N cycles (1..MAXINT). */
225
226INLINE_SIM_EVENTS\
227(int) sim_events_tick
228(SIM_DESC sd);
229
230INLINE_SIM_EVENTS\
231(int) sim_events_tickn
232(SIM_DESC sd,
233 int n);
234
235INLINE_SIM_EVENTS\
236(void) sim_events_process
237(SIM_DESC sd);
238
239
240/* Advance the clock by an additional SLIP cycles at the next call to
241   sim_events_tick*().  For multiple calls, the effect is
242   accumulative. */
243
244INLINE_SIM_EVENTS\
245(void) sim_events_slip
246(SIM_DESC sd,
247 int slip);
248
249
250/* Progress time such that an event shall occur upon the next call to
251   sim_events tick */
252
253#if 0
254INLINE_SIM_EVENTS\
255(void) sim_events_timewarp
256(SIM_DESC sd);
257#endif
258
259
260/* local concept of elapsed target time */
261
262INLINE_SIM_EVENTS\
263(signed64) sim_events_time
264(SIM_DESC sd);
265
266
267/* local concept of elapsed host time (milliseconds) */
268
269INLINE_SIM_EVENTS\
270(unsigned long) sim_events_elapsed_time
271(SIM_DESC sd);
272
273/* Returns the time that remains before the event is raised. */
274INLINE_SIM_EVENTS\
275(signed64) sim_events_remain_time
276(SIM_DESC sd, sim_event *event);
277
278
279#endif
280