xref: /openbmc/qemu/include/qemu/main-loop.h (revision 7c754c78)
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 "sysemu/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  * bql_locked: Return lock status of the Big QEMU Lock (BQL)
252  *
253  * The Big QEMU Lock (BQL) 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 BQL.
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().
262  */
263 bool bql_locked(void);
264 
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 
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  */
289 #define GLOBAL_STATE_CODE()                                         \
290     do {                                                            \
291         assert(qemu_in_main_thread());                              \
292     } while (0)
293 
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  */
299 #define IO_CODE()                                                   \
300     do {                                                            \
301         /* nop */                                                   \
302     } while (0)
303 
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  */
309 #define IO_OR_GS_CODE()                                             \
310     do {                                                            \
311         /* nop */                                                   \
312     } while (0)
313 
314 /**
315  * bql_lock: Lock the Big QEMU Lock (BQL).
316  *
317  * This function locks the Big QEMU Lock (BQL).  The lock is taken by
318  * main() in vl.c and always taken except while waiting on
319  * external events (such as with select).  The lock 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.
323  *
324  * NOTE: tools currently are single-threaded and bql_lock
325  * is a no-op there.
326  */
327 #define bql_lock() bql_lock_impl(__FILE__, __LINE__)
328 void bql_lock_impl(const char *file, int line);
329 
330 /**
331  * bql_unlock: Unlock the Big QEMU Lock (BQL).
332  *
333  * This function unlocks the Big QEMU Lock.  The lock is taken by
334  * main() in vl.c and always taken except while waiting on
335  * external events (such as with select).  The lock should be unlocked
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.
339  *
340  * NOTE: tools currently are single-threaded and bql_unlock
341  * is a no-op there.
342  */
343 void bql_unlock(void);
344 
345 /**
346  * BQL_LOCK_GUARD
347  *
348  * Wrap a block of code in a conditional bql_{lock,unlock}.
349  */
350 typedef struct BQLLockAuto BQLLockAuto;
351 
bql_auto_lock(const char * file,int line)352 static inline BQLLockAuto *bql_auto_lock(const char *file, int line)
353 {
354     if (bql_locked()) {
355         return NULL;
356     }
357     bql_lock_impl(file, line);
358     /* Anything non-NULL causes the cleanup function to be called */
359     return (BQLLockAuto *)(uintptr_t)1;
360 }
361 
bql_auto_unlock(BQLLockAuto * l)362 static inline void bql_auto_unlock(BQLLockAuto *l)
363 {
364     bql_unlock();
365 }
366 
367 G_DEFINE_AUTOPTR_CLEANUP_FUNC(BQLLockAuto, bql_auto_unlock)
368 
369 #define BQL_LOCK_GUARD() \
370     g_autoptr(BQLLockAuto) _bql_lock_auto __attribute__((unused)) \
371         = bql_auto_lock(__FILE__, __LINE__)
372 
373 /*
374  * qemu_cond_wait_bql: Wait on condition for the Big QEMU Lock (BQL)
375  *
376  * This function atomically releases the Big QEMU Lock (BQL) and causes
377  * the calling thread to block on the condition.
378  */
379 void qemu_cond_wait_bql(QemuCond *cond);
380 
381 /*
382  * qemu_cond_timedwait_bql: like the previous, but with timeout
383  */
384 void qemu_cond_timedwait_bql(QemuCond *cond, int ms);
385 
386 /* internal interfaces */
387 
388 #define qemu_bh_new_guarded(cb, opaque, guard) \
389     qemu_bh_new_full((cb), (opaque), (stringify(cb)), guard)
390 #define qemu_bh_new(cb, opaque) \
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);
394 void qemu_bh_schedule_idle(QEMUBH *bh);
395 
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 
411 #endif
412