1 /*
2 * QEMU System Emulator
3 *
4 * Copyright (c) 2003-2008 Fabrice Bellard
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24
25 #ifndef QEMU_MAIN_LOOP_H
26 #define QEMU_MAIN_LOOP_H
27
28 #include "block/aio.h"
29 #include "qom/object.h"
30 #include "system/event-loop-base.h"
31
32 #define SIG_IPI SIGUSR1
33
34 #define TYPE_MAIN_LOOP "main-loop"
35 OBJECT_DECLARE_TYPE(MainLoop, MainLoopClass, MAIN_LOOP)
36
37 struct MainLoop {
38 EventLoopBase parent_obj;
39 };
40 typedef struct MainLoop MainLoop;
41
42 /**
43 * qemu_init_main_loop: Set up the process so that it can run the main loop.
44 *
45 * This includes setting up signal handlers. It should be called before
46 * any other threads are created. In addition, threads other than the
47 * main one should block signals that are trapped by the main loop.
48 * For simplicity, you can consider these signals to be safe: SIGUSR1,
49 * SIGUSR2, thread signals (SIGFPE, SIGILL, SIGSEGV, SIGBUS) and real-time
50 * signals if available. Remember that Windows in practice does not have
51 * signals, though.
52 *
53 * In the case of QEMU tools, this will also start/initialize timers.
54 */
55 int qemu_init_main_loop(Error **errp);
56
57 /**
58 * main_loop_wait: Run one iteration of the main loop.
59 *
60 * If @nonblocking is true, poll for events, otherwise suspend until
61 * one actually occurs. The main loop usually consists of a loop that
62 * repeatedly calls main_loop_wait(false).
63 *
64 * Main loop services include file descriptor callbacks, bottom halves
65 * and timers (defined in qemu/timer.h). Bottom halves are similar to timers
66 * that execute immediately, but have a lower overhead and scheduling them
67 * is wait-free, thread-safe and signal-safe.
68 *
69 * It is sometimes useful to put a whole program in a coroutine. In this
70 * case, the coroutine actually should be started from within the main loop,
71 * so that the main loop can run whenever the coroutine yields. To do this,
72 * you can use a bottom half to enter the coroutine as soon as the main loop
73 * starts:
74 *
75 * void enter_co_bh(void *opaque) {
76 * QEMUCoroutine *co = opaque;
77 * qemu_coroutine_enter(co);
78 * }
79 *
80 * ...
81 * QEMUCoroutine *co = qemu_coroutine_create(coroutine_entry, NULL);
82 * QEMUBH *start_bh = qemu_bh_new(enter_co_bh, co);
83 * qemu_bh_schedule(start_bh);
84 * while (...) {
85 * main_loop_wait(false);
86 * }
87 *
88 * (In the future we may provide a wrapper for this).
89 *
90 * @nonblocking: Whether the caller should block until an event occurs.
91 */
92 void main_loop_wait(int nonblocking);
93
94 /**
95 * qemu_get_aio_context: Return the main loop's AioContext
96 */
97 AioContext *qemu_get_aio_context(void);
98
99 /**
100 * qemu_notify_event: Force processing of pending events.
101 *
102 * Similar to signaling a condition variable, qemu_notify_event forces
103 * main_loop_wait to look at pending events and exit. The caller of
104 * main_loop_wait will usually call it again very soon, so qemu_notify_event
105 * also has the side effect of recalculating the sets of file descriptors
106 * that the main loop waits for.
107 *
108 * Calling qemu_notify_event is rarely necessary, because main loop
109 * services (bottom halves and timers) call it themselves.
110 */
111 void qemu_notify_event(void);
112
113 #ifdef _WIN32
114 /* return TRUE if no sleep should be done afterwards */
115 typedef int PollingFunc(void *opaque);
116
117 /**
118 * qemu_add_polling_cb: Register a Windows-specific polling callback
119 *
120 * Currently, under Windows some events are polled rather than waited for.
121 * Polling callbacks do not ensure that @func is called timely, because
122 * the main loop might wait for an arbitrarily long time. If possible,
123 * you should instead create a separate thread that does a blocking poll
124 * and set a Win32 event object. The event can then be passed to
125 * qemu_add_wait_object.
126 *
127 * Polling callbacks really have nothing Windows specific in them, but
128 * as they are a hack and are currently not necessary under POSIX systems,
129 * they are only available when QEMU is running under Windows.
130 *
131 * @func: The function that does the polling, and returns 1 to force
132 * immediate completion of main_loop_wait.
133 * @opaque: A pointer-size value that is passed to @func.
134 */
135 int qemu_add_polling_cb(PollingFunc *func, void *opaque);
136
137 /**
138 * qemu_del_polling_cb: Unregister a Windows-specific polling callback
139 *
140 * This function removes a callback that was registered with
141 * qemu_add_polling_cb.
142 *
143 * @func: The function that was passed to qemu_add_polling_cb.
144 * @opaque: A pointer-size value that was passed to qemu_add_polling_cb.
145 */
146 void qemu_del_polling_cb(PollingFunc *func, void *opaque);
147
148 /* Wait objects handling */
149 typedef void WaitObjectFunc(void *opaque);
150
151 /**
152 * qemu_add_wait_object: Register a callback for a Windows handle
153 *
154 * Under Windows, the iohandler mechanism can only be used with sockets.
155 * QEMU must use the WaitForMultipleObjects API to wait on other handles.
156 * This function registers a #HANDLE with QEMU, so that it will be included
157 * in the main loop's calls to WaitForMultipleObjects. When the handle
158 * is in a signaled state, QEMU will call @func.
159 *
160 * If the same HANDLE is added twice, this function returns -1.
161 *
162 * @handle: The Windows handle to be observed.
163 * @func: A function to be called when @handle is in a signaled state.
164 * @opaque: A pointer-size value that is passed to @func.
165 */
166 int qemu_add_wait_object(HANDLE handle, WaitObjectFunc *func, void *opaque);
167
168 /**
169 * qemu_del_wait_object: Unregister a callback for a Windows handle
170 *
171 * This function removes a callback that was registered with
172 * qemu_add_wait_object.
173 *
174 * @func: The function that was passed to qemu_add_wait_object.
175 * @opaque: A pointer-size value that was passed to qemu_add_wait_object.
176 */
177 void qemu_del_wait_object(HANDLE handle, WaitObjectFunc *func, void *opaque);
178 #endif
179
180 /* async I/O support */
181
182 typedef void IOReadHandler(void *opaque, const uint8_t *buf, int size);
183
184 /**
185 * IOCanReadHandler: Return the number of bytes that #IOReadHandler can accept
186 *
187 * This function reports how many bytes #IOReadHandler is prepared to accept.
188 * #IOReadHandler may be invoked with up to this number of bytes. If this
189 * function returns 0 then #IOReadHandler is not invoked.
190 *
191 * This function is typically called from an event loop. If the number of
192 * bytes changes outside the event loop (e.g. because a vcpu thread drained the
193 * buffer), then it is necessary to kick the event loop so that this function
194 * is called again. aio_notify() or qemu_notify_event() can be used to kick
195 * the event loop.
196 */
197 typedef int IOCanReadHandler(void *opaque);
198
199 /**
200 * qemu_set_fd_handler: Register a file descriptor with the main loop
201 *
202 * This function tells the main loop to wake up whenever one of the
203 * following conditions is true:
204 *
205 * 1) if @fd_write is not %NULL, when the file descriptor is writable;
206 *
207 * 2) if @fd_read is not %NULL, when the file descriptor is readable.
208 *
209 * The callbacks that are set up by qemu_set_fd_handler are level-triggered.
210 * If @fd_read does not read from @fd, or @fd_write does not write to @fd
211 * until its buffers are full, they will be called again on the next
212 * iteration.
213 *
214 * @fd: The file descriptor to be observed. Under Windows it must be
215 * a #SOCKET.
216 *
217 * @fd_read: A level-triggered callback that is fired if @fd is readable
218 * at the beginning of a main loop iteration, or if it becomes readable
219 * during one.
220 *
221 * @fd_write: A level-triggered callback that is fired when @fd is writable
222 * at the beginning of a main loop iteration, or if it becomes writable
223 * during one.
224 *
225 * @opaque: A pointer-sized value that is passed to @fd_read and @fd_write.
226 */
227 void qemu_set_fd_handler(int fd,
228 IOHandler *fd_read,
229 IOHandler *fd_write,
230 void *opaque);
231
232
233 /**
234 * event_notifier_set_handler: Register an EventNotifier with the main loop
235 *
236 * This function tells the main loop to wake up whenever the
237 * #EventNotifier was set.
238 *
239 * @e: The #EventNotifier to be observed.
240 *
241 * @handler: A level-triggered callback that is fired when @e
242 * has been set. @e is passed to it as a parameter.
243 */
244 void event_notifier_set_handler(EventNotifier *e,
245 EventNotifierHandler *handler);
246
247 GSource *iohandler_get_g_source(void);
248 AioContext *iohandler_get_aio_context(void);
249
250 /**
251 * rust_bql_mock_lock:
252 *
253 * Called from Rust doctests to make bql_lock() return true.
254 * Do not touch.
255 */
256 void rust_bql_mock_lock(void);
257
258 /**
259 * bql_locked: Return lock status of the Big QEMU Lock (BQL)
260 *
261 * The Big QEMU Lock (BQL) is the coarsest lock in QEMU, and as such it
262 * must always be taken outside other locks. This function helps
263 * functions take different paths depending on whether the current
264 * thread is running within the BQL.
265 *
266 * This function should never be used in the block layer, because
267 * unit tests, block layer tools and qemu-storage-daemon do not
268 * have a BQL.
269 * Please instead refer to qemu_in_main_thread().
270 */
271 bool bql_locked(void);
272
273 /**
274 * bql_block: Allow/deny releasing the BQL
275 *
276 * The Big QEMU Lock (BQL) is used to provide interior mutability to
277 * Rust code, but this only works if other threads cannot run while
278 * the Rust code has an active borrow. This is because C code in
279 * other threads could come in and mutate data under the Rust code's
280 * feet.
281 *
282 * @increase: Whether to increase or decrease the blocking counter.
283 * Releasing the BQL while the counter is nonzero triggers
284 * an assertion failure.
285 */
286 void bql_block_unlock(bool increase);
287
288 /**
289 * qemu_in_main_thread: return whether it's possible to safely access
290 * the global state of the block layer.
291 *
292 * Global state of the block layer is not accessible from I/O threads
293 * or worker threads; only from threads that "own" the default
294 * AioContext that qemu_get_aio_context() returns. For tests, block
295 * layer tools and qemu-storage-daemon there is a designated thread that
296 * runs the event loop for qemu_get_aio_context(), and that is the
297 * main thread.
298 *
299 * For emulators, however, any thread that holds the BQL can act
300 * as the block layer main thread; this will be any of the actual
301 * main thread, the vCPU threads or the RCU thread.
302 *
303 * For clarity, do not use this function outside the block layer.
304 */
305 bool qemu_in_main_thread(void);
306
307 /*
308 * Mark and check that the function is part of the Global State API.
309 * Please refer to include/block/block-global-state.h for more
310 * information about GS API.
311 */
312 #define GLOBAL_STATE_CODE() \
313 do { \
314 assert(qemu_in_main_thread()); \
315 } while (0)
316
317 /*
318 * Mark and check that the function is part of the I/O API.
319 * Please refer to include/block/block-io.h for more
320 * information about IO API.
321 */
322 #define IO_CODE() \
323 do { \
324 /* nop */ \
325 } while (0)
326
327 /*
328 * Mark and check that the function is part of the "I/O OR GS" API.
329 * Please refer to include/block/block-io.h for more
330 * information about "IO or GS" API.
331 */
332 #define IO_OR_GS_CODE() \
333 do { \
334 /* nop */ \
335 } while (0)
336
337 /**
338 * bql_lock: Lock the Big QEMU Lock (BQL).
339 *
340 * This function locks the Big QEMU Lock (BQL). The lock is taken by
341 * main() in vl.c and always taken except while waiting on
342 * external events (such as with select). The lock should be taken
343 * by threads other than the main loop thread when calling
344 * qemu_bh_new(), qemu_set_fd_handler() and basically all other
345 * functions documented in this file.
346 *
347 * NOTE: tools currently are single-threaded and bql_lock
348 * is a no-op there.
349 */
350 #define bql_lock() bql_lock_impl(__FILE__, __LINE__)
351 void bql_lock_impl(const char *file, int line);
352
353 /**
354 * bql_unlock: Unlock the Big QEMU Lock (BQL).
355 *
356 * This function unlocks the Big QEMU Lock. The lock is taken by
357 * main() in vl.c and always taken except while waiting on
358 * external events (such as with select). The lock should be unlocked
359 * as soon as possible by threads other than the main loop thread,
360 * because it prevents the main loop from processing callbacks,
361 * including timers and bottom halves.
362 *
363 * NOTE: tools currently are single-threaded and bql_unlock
364 * is a no-op there.
365 */
366 void bql_unlock(void);
367
368 /**
369 * BQL_LOCK_GUARD
370 *
371 * Wrap a block of code in a conditional bql_{lock,unlock}.
372 */
373 typedef struct BQLLockAuto BQLLockAuto;
374
bql_auto_lock(const char * file,int line)375 static inline BQLLockAuto *bql_auto_lock(const char *file, int line)
376 {
377 if (bql_locked()) {
378 return NULL;
379 }
380 bql_lock_impl(file, line);
381 /* Anything non-NULL causes the cleanup function to be called */
382 return (BQLLockAuto *)(uintptr_t)1;
383 }
384
bql_auto_unlock(BQLLockAuto * l)385 static inline void bql_auto_unlock(BQLLockAuto *l)
386 {
387 bql_unlock();
388 }
389
390 G_DEFINE_AUTOPTR_CLEANUP_FUNC(BQLLockAuto, bql_auto_unlock)
391
392 #define BQL_LOCK_GUARD() \
393 g_autoptr(BQLLockAuto) _bql_lock_auto __attribute__((unused)) \
394 = bql_auto_lock(__FILE__, __LINE__)
395
396 /*
397 * qemu_cond_wait_bql: Wait on condition for the Big QEMU Lock (BQL)
398 *
399 * This function atomically releases the Big QEMU Lock (BQL) and causes
400 * the calling thread to block on the condition.
401 */
402 void qemu_cond_wait_bql(QemuCond *cond);
403
404 /*
405 * qemu_cond_timedwait_bql: like the previous, but with timeout
406 */
407 void qemu_cond_timedwait_bql(QemuCond *cond, int ms);
408
409 /* internal interfaces */
410
411 #define qemu_bh_new_guarded(cb, opaque, guard) \
412 qemu_bh_new_full((cb), (opaque), (stringify(cb)), guard)
413 #define qemu_bh_new(cb, opaque) \
414 qemu_bh_new_full((cb), (opaque), (stringify(cb)), NULL)
415 QEMUBH *qemu_bh_new_full(QEMUBHFunc *cb, void *opaque, const char *name,
416 MemReentrancyGuard *reentrancy_guard);
417 void qemu_bh_schedule_idle(QEMUBH *bh);
418
419 enum {
420 MAIN_LOOP_POLL_FILL,
421 MAIN_LOOP_POLL_ERR,
422 MAIN_LOOP_POLL_OK,
423 };
424
425 typedef struct MainLoopPoll {
426 int state;
427 uint32_t timeout;
428 GArray *pollfds;
429 } MainLoopPoll;
430
431 void main_loop_poll_add_notifier(Notifier *notify);
432 void main_loop_poll_remove_notifier(Notifier *notify);
433
434 #endif
435