]>
Commit | Line | Data |
---|---|---|
44a9b356 PB |
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 | |
175de524 | 26 | #define QEMU_MAIN_LOOP_H |
44a9b356 | 27 | |
737e150e | 28 | #include "block/aio.h" |
70ac26b9 NSJ |
29 | #include "qom/object.h" |
30 | #include "sysemu/event-loop-base.h" | |
f627aab1 | 31 | |
44a9b356 | 32 | #define SIG_IPI SIGUSR1 |
44a9b356 | 33 | |
70ac26b9 NSJ |
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 | ||
44a9b356 PB |
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. | |
d34e8f6e MR |
52 | * |
53 | * In the case of QEMU tools, this will also start/initialize timers. | |
44a9b356 | 54 | */ |
2f78e491 | 55 | int qemu_init_main_loop(Error **errp); |
44a9b356 PB |
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 | |
a275e934 | 65 | * and timers (defined in qemu/timer.h). Bottom halves are similar to timers |
44a9b356 PB |
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; | |
0b8b8753 | 77 | * qemu_coroutine_enter(co); |
44a9b356 PB |
78 | * } |
79 | * | |
80 | * ... | |
0b8b8753 | 81 | * QEMUCoroutine *co = qemu_coroutine_create(coroutine_entry, NULL); |
44a9b356 PB |
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 | */ | |
de5f852f | 92 | void main_loop_wait(int nonblocking); |
44a9b356 | 93 | |
5f3aa1ff SH |
94 | /** |
95 | * qemu_get_aio_context: Return the main loop's AioContext | |
96 | */ | |
97 | AioContext *qemu_get_aio_context(void); | |
98 | ||
44a9b356 PB |
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 | |
6484e422 | 109 | * services (bottom halves and timers) call it themselves. |
44a9b356 PB |
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 | |
07f35073 | 128 | * as they are a hack and are currently not necessary under POSIX systems, |
44a9b356 PB |
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 | * | |
d393b0a1 BM |
160 | * If the same HANDLE is added twice, this function returns -1. |
161 | * | |
44a9b356 PB |
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); | |
d29a8a1b SH |
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 | */ | |
44a9b356 | 197 | typedef int IOCanReadHandler(void *opaque); |
44a9b356 | 198 | |
44a9b356 PB |
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 | */ | |
f4d248bd FZ |
227 | void qemu_set_fd_handler(int fd, |
228 | IOHandler *fd_read, | |
229 | IOHandler *fd_write, | |
230 | void *opaque); | |
44a9b356 | 231 | |
d6da1e9e PB |
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 | ||
f3926945 | 247 | GSource *iohandler_get_g_source(void); |
bcd82a96 | 248 | AioContext *iohandler_get_aio_context(void); |
44a9b356 | 249 | |
afbe7053 PB |
250 | /** |
251 | * qemu_mutex_iothread_locked: Return lock status of the main loop mutex. | |
252 | * | |
253 | * The main loop mutex is the coarsest lock in QEMU, and as such it | |
254 | * must always be taken outside other locks. This function helps | |
255 | * functions take different paths depending on whether the current | |
256 | * thread is running within the main loop mutex. | |
6538692e EGE |
257 | * |
258 | * This function should never be used in the block layer, because | |
259 | * unit tests, block layer tools and qemu-storage-daemon do not | |
260 | * have a BQL. | |
261 | * Please instead refer to qemu_in_main_thread(). | |
afbe7053 PB |
262 | */ |
263 | bool qemu_mutex_iothread_locked(void); | |
264 | ||
6538692e EGE |
265 | /** |
266 | * qemu_in_main_thread: return whether it's possible to safely access | |
267 | * the global state of the block layer. | |
268 | * | |
269 | * Global state of the block layer is not accessible from I/O threads | |
270 | * or worker threads; only from threads that "own" the default | |
271 | * AioContext that qemu_get_aio_context() returns. For tests, block | |
272 | * layer tools and qemu-storage-daemon there is a designated thread that | |
273 | * runs the event loop for qemu_get_aio_context(), and that is the | |
274 | * main thread. | |
275 | * | |
276 | * For emulators, however, any thread that holds the BQL can act | |
277 | * as the block layer main thread; this will be any of the actual | |
278 | * main thread, the vCPU threads or the RCU thread. | |
279 | * | |
280 | * For clarity, do not use this function outside the block layer. | |
281 | */ | |
282 | bool qemu_in_main_thread(void); | |
283 | ||
21b1d974 EGE |
284 | /* |
285 | * Mark and check that the function is part of the Global State API. | |
286 | * Please refer to include/block/block-global-state.h for more | |
287 | * information about GS API. | |
288 | */ | |
ac7798f2 EGE |
289 | #define GLOBAL_STATE_CODE() \ |
290 | do { \ | |
ccfaf783 | 291 | assert(qemu_in_main_thread()); \ |
ac7798f2 EGE |
292 | } while (0) |
293 | ||
21b1d974 EGE |
294 | /* |
295 | * Mark and check that the function is part of the I/O API. | |
296 | * Please refer to include/block/block-io.h for more | |
297 | * information about IO API. | |
298 | */ | |
ac7798f2 EGE |
299 | #define IO_CODE() \ |
300 | do { \ | |
301 | /* nop */ \ | |
302 | } while (0) | |
303 | ||
21b1d974 EGE |
304 | /* |
305 | * Mark and check that the function is part of the "I/O OR GS" API. | |
306 | * Please refer to include/block/block-io.h for more | |
307 | * information about "IO or GS" API. | |
308 | */ | |
ac7798f2 EGE |
309 | #define IO_OR_GS_CODE() \ |
310 | do { \ | |
311 | /* nop */ \ | |
312 | } while (0) | |
313 | ||
d3b12f5d PB |
314 | /** |
315 | * qemu_mutex_lock_iothread: Lock the main loop mutex. | |
316 | * | |
317 | * This function locks the main loop mutex. The mutex is taken by | |
11717bc9 | 318 | * main() in vl.c and always taken except while waiting on |
d3b12f5d PB |
319 | * external events (such as with select). The mutex should be taken |
320 | * by threads other than the main loop thread when calling | |
321 | * qemu_bh_new(), qemu_set_fd_handler() and basically all other | |
322 | * functions documented in this file. | |
cbcfa041 PB |
323 | * |
324 | * NOTE: tools currently are single-threaded and qemu_mutex_lock_iothread | |
325 | * is a no-op there. | |
d3b12f5d | 326 | */ |
cb764d06 EC |
327 | #define qemu_mutex_lock_iothread() \ |
328 | qemu_mutex_lock_iothread_impl(__FILE__, __LINE__) | |
329 | void qemu_mutex_lock_iothread_impl(const char *file, int line); | |
d3b12f5d PB |
330 | |
331 | /** | |
332 | * qemu_mutex_unlock_iothread: Unlock the main loop mutex. | |
333 | * | |
334 | * This function unlocks the main loop mutex. The mutex is taken by | |
11717bc9 | 335 | * main() in vl.c and always taken except while waiting on |
d3b12f5d PB |
336 | * external events (such as with select). The mutex should be unlocked |
337 | * as soon as possible by threads other than the main loop thread, | |
338 | * because it prevents the main loop from processing callbacks, | |
339 | * including timers and bottom halves. | |
cbcfa041 PB |
340 | * |
341 | * NOTE: tools currently are single-threaded and qemu_mutex_unlock_iothread | |
342 | * is a no-op there. | |
d3b12f5d PB |
343 | */ |
344 | void qemu_mutex_unlock_iothread(void); | |
345 | ||
0aa5d47a RH |
346 | /** |
347 | * QEMU_IOTHREAD_LOCK_GUARD | |
348 | * | |
349 | * Wrap a block of code in a conditional qemu_mutex_{lock,unlock}_iothread. | |
350 | */ | |
351 | typedef struct IOThreadLockAuto IOThreadLockAuto; | |
352 | ||
353 | static inline IOThreadLockAuto *qemu_iothread_auto_lock(const char *file, | |
354 | int line) | |
355 | { | |
356 | if (qemu_mutex_iothread_locked()) { | |
357 | return NULL; | |
358 | } | |
359 | qemu_mutex_lock_iothread_impl(file, line); | |
360 | /* Anything non-NULL causes the cleanup function to be called */ | |
361 | return (IOThreadLockAuto *)(uintptr_t)1; | |
362 | } | |
363 | ||
364 | static inline void qemu_iothread_auto_unlock(IOThreadLockAuto *l) | |
365 | { | |
366 | qemu_mutex_unlock_iothread(); | |
367 | } | |
368 | ||
369 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(IOThreadLockAuto, qemu_iothread_auto_unlock) | |
370 | ||
371 | #define QEMU_IOTHREAD_LOCK_GUARD() \ | |
372 | g_autoptr(IOThreadLockAuto) _iothread_lock_auto __attribute__((unused)) \ | |
373 | = qemu_iothread_auto_lock(__FILE__, __LINE__) | |
374 | ||
19e067e0 AP |
375 | /* |
376 | * qemu_cond_wait_iothread: Wait on condition for the main loop mutex | |
377 | * | |
378 | * This function atomically releases the main loop mutex and causes | |
379 | * the calling thread to block on the condition. | |
380 | */ | |
381 | void qemu_cond_wait_iothread(QemuCond *cond); | |
382 | ||
b0c3cf94 CF |
383 | /* |
384 | * qemu_cond_timedwait_iothread: like the previous, but with timeout | |
385 | */ | |
386 | void qemu_cond_timedwait_iothread(QemuCond *cond, int ms); | |
387 | ||
44a9b356 PB |
388 | /* internal interfaces */ |
389 | ||
9c86c97f AB |
390 | #define qemu_bh_new_guarded(cb, opaque, guard) \ |
391 | qemu_bh_new_full((cb), (opaque), (stringify(cb)), guard) | |
0f08586c | 392 | #define qemu_bh_new(cb, opaque) \ |
9c86c97f AB |
393 | qemu_bh_new_full((cb), (opaque), (stringify(cb)), NULL) |
394 | QEMUBH *qemu_bh_new_full(QEMUBHFunc *cb, void *opaque, const char *name, | |
395 | MemReentrancyGuard *reentrancy_guard); | |
44a9b356 | 396 | void qemu_bh_schedule_idle(QEMUBH *bh); |
44a9b356 | 397 | |
1ab67b98 MAL |
398 | enum { |
399 | MAIN_LOOP_POLL_FILL, | |
400 | MAIN_LOOP_POLL_ERR, | |
401 | MAIN_LOOP_POLL_OK, | |
402 | }; | |
403 | ||
404 | typedef struct MainLoopPoll { | |
405 | int state; | |
406 | uint32_t timeout; | |
407 | GArray *pollfds; | |
408 | } MainLoopPoll; | |
409 | ||
410 | void main_loop_poll_add_notifier(Notifier *notify); | |
411 | void main_loop_poll_remove_notifier(Notifier *notify); | |
412 | ||
44a9b356 | 413 | #endif |