]>
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 | 250 | /** |
195801d7 | 251 | * bql_locked: Return lock status of the Big QEMU Lock (BQL) |
afbe7053 | 252 | * |
195801d7 | 253 | * The Big QEMU Lock (BQL) is the coarsest lock in QEMU, and as such it |
afbe7053 PB |
254 | * must always be taken outside other locks. This function helps |
255 | * functions take different paths depending on whether the current | |
195801d7 | 256 | * thread is running within the BQL. |
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 | 262 | */ |
195801d7 | 263 | bool bql_locked(void); |
afbe7053 | 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 | 314 | /** |
195801d7 | 315 | * bql_lock: Lock the Big QEMU Lock (BQL). |
d3b12f5d | 316 | * |
195801d7 | 317 | * This function locks the Big QEMU Lock (BQL). The lock is taken by |
11717bc9 | 318 | * main() in vl.c and always taken except while waiting on |
195801d7 | 319 | * external events (such as with select). The lock should be taken |
d3b12f5d PB |
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 | 323 | * |
195801d7 | 324 | * NOTE: tools currently are single-threaded and bql_lock |
cbcfa041 | 325 | * is a no-op there. |
d3b12f5d | 326 | */ |
195801d7 SH |
327 | #define bql_lock() bql_lock_impl(__FILE__, __LINE__) |
328 | void bql_lock_impl(const char *file, int line); | |
d3b12f5d PB |
329 | |
330 | /** | |
195801d7 | 331 | * bql_unlock: Unlock the Big QEMU Lock (BQL). |
d3b12f5d | 332 | * |
195801d7 | 333 | * This function unlocks the Big QEMU Lock. The lock is taken by |
11717bc9 | 334 | * main() in vl.c and always taken except while waiting on |
195801d7 | 335 | * external events (such as with select). The lock should be unlocked |
d3b12f5d PB |
336 | * as soon as possible by threads other than the main loop thread, |
337 | * because it prevents the main loop from processing callbacks, | |
338 | * including timers and bottom halves. | |
cbcfa041 | 339 | * |
195801d7 | 340 | * NOTE: tools currently are single-threaded and bql_unlock |
cbcfa041 | 341 | * is a no-op there. |
d3b12f5d | 342 | */ |
195801d7 | 343 | void bql_unlock(void); |
d3b12f5d | 344 | |
0aa5d47a | 345 | /** |
32ead8e6 | 346 | * BQL_LOCK_GUARD |
0aa5d47a | 347 | * |
195801d7 | 348 | * Wrap a block of code in a conditional bql_{lock,unlock}. |
0aa5d47a | 349 | */ |
32ead8e6 | 350 | typedef struct BQLLockAuto BQLLockAuto; |
0aa5d47a | 351 | |
32ead8e6 | 352 | static inline BQLLockAuto *bql_auto_lock(const char *file, int line) |
0aa5d47a | 353 | { |
195801d7 | 354 | if (bql_locked()) { |
0aa5d47a RH |
355 | return NULL; |
356 | } | |
195801d7 | 357 | bql_lock_impl(file, line); |
0aa5d47a | 358 | /* Anything non-NULL causes the cleanup function to be called */ |
32ead8e6 | 359 | return (BQLLockAuto *)(uintptr_t)1; |
0aa5d47a RH |
360 | } |
361 | ||
32ead8e6 | 362 | static inline void bql_auto_unlock(BQLLockAuto *l) |
0aa5d47a | 363 | { |
195801d7 | 364 | bql_unlock(); |
0aa5d47a RH |
365 | } |
366 | ||
32ead8e6 | 367 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(BQLLockAuto, bql_auto_unlock) |
0aa5d47a | 368 | |
32ead8e6 SH |
369 | #define BQL_LOCK_GUARD() \ |
370 | g_autoptr(BQLLockAuto) _bql_lock_auto __attribute__((unused)) \ | |
371 | = bql_auto_lock(__FILE__, __LINE__) | |
0aa5d47a | 372 | |
19e067e0 | 373 | /* |
7c754c78 | 374 | * qemu_cond_wait_bql: Wait on condition for the Big QEMU Lock (BQL) |
19e067e0 | 375 | * |
7c754c78 | 376 | * This function atomically releases the Big QEMU Lock (BQL) and causes |
19e067e0 AP |
377 | * the calling thread to block on the condition. |
378 | */ | |
7c754c78 | 379 | void qemu_cond_wait_bql(QemuCond *cond); |
19e067e0 | 380 | |
b0c3cf94 | 381 | /* |
7c754c78 | 382 | * qemu_cond_timedwait_bql: like the previous, but with timeout |
b0c3cf94 | 383 | */ |
7c754c78 | 384 | void qemu_cond_timedwait_bql(QemuCond *cond, int ms); |
b0c3cf94 | 385 | |
44a9b356 PB |
386 | /* internal interfaces */ |
387 | ||
9c86c97f AB |
388 | #define qemu_bh_new_guarded(cb, opaque, guard) \ |
389 | qemu_bh_new_full((cb), (opaque), (stringify(cb)), guard) | |
0f08586c | 390 | #define qemu_bh_new(cb, opaque) \ |
9c86c97f AB |
391 | qemu_bh_new_full((cb), (opaque), (stringify(cb)), NULL) |
392 | QEMUBH *qemu_bh_new_full(QEMUBHFunc *cb, void *opaque, const char *name, | |
393 | MemReentrancyGuard *reentrancy_guard); | |
44a9b356 | 394 | void qemu_bh_schedule_idle(QEMUBH *bh); |
44a9b356 | 395 | |
1ab67b98 MAL |
396 | enum { |
397 | MAIN_LOOP_POLL_FILL, | |
398 | MAIN_LOOP_POLL_ERR, | |
399 | MAIN_LOOP_POLL_OK, | |
400 | }; | |
401 | ||
402 | typedef struct MainLoopPoll { | |
403 | int state; | |
404 | uint32_t timeout; | |
405 | GArray *pollfds; | |
406 | } MainLoopPoll; | |
407 | ||
408 | void main_loop_poll_add_notifier(Notifier *notify); | |
409 | void main_loop_poll_remove_notifier(Notifier *notify); | |
410 | ||
44a9b356 | 411 | #endif |