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 1 27 28 #include "block/aio.h" 29 30 #define SIG_IPI SIGUSR1 31 32 /** 33 * qemu_init_main_loop: Set up the process so that it can run the main loop. 34 * 35 * This includes setting up signal handlers. It should be called before 36 * any other threads are created. In addition, threads other than the 37 * main one should block signals that are trapped by the main loop. 38 * For simplicity, you can consider these signals to be safe: SIGUSR1, 39 * SIGUSR2, thread signals (SIGFPE, SIGILL, SIGSEGV, SIGBUS) and real-time 40 * signals if available. Remember that Windows in practice does not have 41 * signals, though. 42 * 43 * In the case of QEMU tools, this will also start/initialize timers. 44 */ 45 int qemu_init_main_loop(Error **errp); 46 47 /** 48 * main_loop_wait: Run one iteration of the main loop. 49 * 50 * If @nonblocking is true, poll for events, otherwise suspend until 51 * one actually occurs. The main loop usually consists of a loop that 52 * repeatedly calls main_loop_wait(false). 53 * 54 * Main loop services include file descriptor callbacks, bottom halves 55 * and timers (defined in qemu-timer.h). Bottom halves are similar to timers 56 * that execute immediately, but have a lower overhead and scheduling them 57 * is wait-free, thread-safe and signal-safe. 58 * 59 * It is sometimes useful to put a whole program in a coroutine. In this 60 * case, the coroutine actually should be started from within the main loop, 61 * so that the main loop can run whenever the coroutine yields. To do this, 62 * you can use a bottom half to enter the coroutine as soon as the main loop 63 * starts: 64 * 65 * void enter_co_bh(void *opaque) { 66 * QEMUCoroutine *co = opaque; 67 * qemu_coroutine_enter(co, NULL); 68 * } 69 * 70 * ... 71 * QEMUCoroutine *co = qemu_coroutine_create(coroutine_entry); 72 * QEMUBH *start_bh = qemu_bh_new(enter_co_bh, co); 73 * qemu_bh_schedule(start_bh); 74 * while (...) { 75 * main_loop_wait(false); 76 * } 77 * 78 * (In the future we may provide a wrapper for this). 79 * 80 * @nonblocking: Whether the caller should block until an event occurs. 81 */ 82 int main_loop_wait(int nonblocking); 83 84 /** 85 * qemu_get_aio_context: Return the main loop's AioContext 86 */ 87 AioContext *qemu_get_aio_context(void); 88 89 /** 90 * qemu_notify_event: Force processing of pending events. 91 * 92 * Similar to signaling a condition variable, qemu_notify_event forces 93 * main_loop_wait to look at pending events and exit. The caller of 94 * main_loop_wait will usually call it again very soon, so qemu_notify_event 95 * also has the side effect of recalculating the sets of file descriptors 96 * that the main loop waits for. 97 * 98 * Calling qemu_notify_event is rarely necessary, because main loop 99 * services (bottom halves and timers) call it themselves. 100 */ 101 void qemu_notify_event(void); 102 103 #ifdef _WIN32 104 /* return TRUE if no sleep should be done afterwards */ 105 typedef int PollingFunc(void *opaque); 106 107 /** 108 * qemu_add_polling_cb: Register a Windows-specific polling callback 109 * 110 * Currently, under Windows some events are polled rather than waited for. 111 * Polling callbacks do not ensure that @func is called timely, because 112 * the main loop might wait for an arbitrarily long time. If possible, 113 * you should instead create a separate thread that does a blocking poll 114 * and set a Win32 event object. The event can then be passed to 115 * qemu_add_wait_object. 116 * 117 * Polling callbacks really have nothing Windows specific in them, but 118 * as they are a hack and are currently not necessary under POSIX systems, 119 * they are only available when QEMU is running under Windows. 120 * 121 * @func: The function that does the polling, and returns 1 to force 122 * immediate completion of main_loop_wait. 123 * @opaque: A pointer-size value that is passed to @func. 124 */ 125 int qemu_add_polling_cb(PollingFunc *func, void *opaque); 126 127 /** 128 * qemu_del_polling_cb: Unregister a Windows-specific polling callback 129 * 130 * This function removes a callback that was registered with 131 * qemu_add_polling_cb. 132 * 133 * @func: The function that was passed to qemu_add_polling_cb. 134 * @opaque: A pointer-size value that was passed to qemu_add_polling_cb. 135 */ 136 void qemu_del_polling_cb(PollingFunc *func, void *opaque); 137 138 /* Wait objects handling */ 139 typedef void WaitObjectFunc(void *opaque); 140 141 /** 142 * qemu_add_wait_object: Register a callback for a Windows handle 143 * 144 * Under Windows, the iohandler mechanism can only be used with sockets. 145 * QEMU must use the WaitForMultipleObjects API to wait on other handles. 146 * This function registers a #HANDLE with QEMU, so that it will be included 147 * in the main loop's calls to WaitForMultipleObjects. When the handle 148 * is in a signaled state, QEMU will call @func. 149 * 150 * @handle: The Windows handle to be observed. 151 * @func: A function to be called when @handle is in a signaled state. 152 * @opaque: A pointer-size value that is passed to @func. 153 */ 154 int qemu_add_wait_object(HANDLE handle, WaitObjectFunc *func, void *opaque); 155 156 /** 157 * qemu_del_wait_object: Unregister a callback for a Windows handle 158 * 159 * This function removes a callback that was registered with 160 * qemu_add_wait_object. 161 * 162 * @func: The function that was passed to qemu_add_wait_object. 163 * @opaque: A pointer-size value that was passed to qemu_add_wait_object. 164 */ 165 void qemu_del_wait_object(HANDLE handle, WaitObjectFunc *func, void *opaque); 166 #endif 167 168 /* async I/O support */ 169 170 typedef void IOReadHandler(void *opaque, const uint8_t *buf, int size); 171 typedef int IOCanReadHandler(void *opaque); 172 173 /** 174 * qemu_set_fd_handler: Register a file descriptor with the main loop 175 * 176 * This function tells the main loop to wake up whenever one of the 177 * following conditions is true: 178 * 179 * 1) if @fd_write is not %NULL, when the file descriptor is writable; 180 * 181 * 2) if @fd_read is not %NULL, when the file descriptor is readable. 182 * 183 * The callbacks that are set up by qemu_set_fd_handler are level-triggered. 184 * If @fd_read does not read from @fd, or @fd_write does not write to @fd 185 * until its buffers are full, they will be called again on the next 186 * iteration. 187 * 188 * @fd: The file descriptor to be observed. Under Windows it must be 189 * a #SOCKET. 190 * 191 * @fd_read: A level-triggered callback that is fired if @fd is readable 192 * at the beginning of a main loop iteration, or if it becomes readable 193 * during one. 194 * 195 * @fd_write: A level-triggered callback that is fired when @fd is writable 196 * at the beginning of a main loop iteration, or if it becomes writable 197 * during one. 198 * 199 * @opaque: A pointer-sized value that is passed to @fd_read and @fd_write. 200 */ 201 void qemu_set_fd_handler(int fd, 202 IOHandler *fd_read, 203 IOHandler *fd_write, 204 void *opaque); 205 206 GSource *iohandler_get_g_source(void); 207 #ifdef CONFIG_POSIX 208 /** 209 * qemu_add_child_watch: Register a child process for reaping. 210 * 211 * Under POSIX systems, a parent process must read the exit status of 212 * its child processes using waitpid, or the operating system will not 213 * free some of the resources attached to that process. 214 * 215 * This function directs the QEMU main loop to observe a child process 216 * and call waitpid as soon as it exits; the watch is then removed 217 * automatically. It is useful whenever QEMU forks a child process 218 * but will find out about its termination by other means such as a 219 * "broken pipe". 220 * 221 * @pid: The pid that QEMU should observe. 222 */ 223 int qemu_add_child_watch(pid_t pid); 224 #endif 225 226 /** 227 * qemu_mutex_iothread_locked: Return lock status of the main loop mutex. 228 * 229 * The main loop mutex is the coarsest lock in QEMU, and as such it 230 * must always be taken outside other locks. This function helps 231 * functions take different paths depending on whether the current 232 * thread is running within the main loop mutex. 233 */ 234 bool qemu_mutex_iothread_locked(void); 235 236 /** 237 * qemu_mutex_lock_iothread: Lock the main loop mutex. 238 * 239 * This function locks the main loop mutex. The mutex is taken by 240 * qemu_init_main_loop and always taken except while waiting on 241 * external events (such as with select). The mutex should be taken 242 * by threads other than the main loop thread when calling 243 * qemu_bh_new(), qemu_set_fd_handler() and basically all other 244 * functions documented in this file. 245 * 246 * NOTE: tools currently are single-threaded and qemu_mutex_lock_iothread 247 * is a no-op there. 248 */ 249 void qemu_mutex_lock_iothread(void); 250 251 /** 252 * qemu_mutex_unlock_iothread: Unlock the main loop mutex. 253 * 254 * This function unlocks the main loop mutex. The mutex is taken by 255 * qemu_init_main_loop and always taken except while waiting on 256 * external events (such as with select). The mutex should be unlocked 257 * as soon as possible by threads other than the main loop thread, 258 * because it prevents the main loop from processing callbacks, 259 * including timers and bottom halves. 260 * 261 * NOTE: tools currently are single-threaded and qemu_mutex_unlock_iothread 262 * is a no-op there. 263 */ 264 void qemu_mutex_unlock_iothread(void); 265 266 /* internal interfaces */ 267 268 void qemu_fd_register(int fd); 269 270 QEMUBH *qemu_bh_new(QEMUBHFunc *cb, void *opaque); 271 void qemu_bh_schedule_idle(QEMUBH *bh); 272 273 #endif 274