1 /* 2 * QEMU aio implementation 3 * 4 * Copyright IBM, Corp. 2008 5 * 6 * Authors: 7 * Anthony Liguori <aliguori@us.ibm.com> 8 * 9 * This work is licensed under the terms of the GNU GPL, version 2. See 10 * the COPYING file in the top-level directory. 11 * 12 */ 13 14 #ifndef QEMU_AIO_H 15 #define QEMU_AIO_H 16 17 #include "qemu-common.h" 18 #include "qemu/queue.h" 19 #include "qemu/event_notifier.h" 20 #include "qemu/thread.h" 21 22 typedef struct BlockDriverAIOCB BlockDriverAIOCB; 23 typedef void BlockDriverCompletionFunc(void *opaque, int ret); 24 25 typedef struct AIOCBInfo { 26 void (*cancel)(BlockDriverAIOCB *acb); 27 size_t aiocb_size; 28 } AIOCBInfo; 29 30 struct BlockDriverAIOCB { 31 const AIOCBInfo *aiocb_info; 32 BlockDriverState *bs; 33 BlockDriverCompletionFunc *cb; 34 void *opaque; 35 }; 36 37 void *qemu_aio_get(const AIOCBInfo *aiocb_info, BlockDriverState *bs, 38 BlockDriverCompletionFunc *cb, void *opaque); 39 void qemu_aio_release(void *p); 40 41 typedef struct AioHandler AioHandler; 42 typedef void QEMUBHFunc(void *opaque); 43 typedef void IOHandler(void *opaque); 44 45 typedef struct AioContext { 46 GSource source; 47 48 /* The list of registered AIO handlers */ 49 QLIST_HEAD(, AioHandler) aio_handlers; 50 51 /* This is a simple lock used to protect the aio_handlers list. 52 * Specifically, it's used to ensure that no callbacks are removed while 53 * we're walking and dispatching callbacks. 54 */ 55 int walking_handlers; 56 57 /* lock to protect between bh's adders and deleter */ 58 QemuMutex bh_lock; 59 /* Anchor of the list of Bottom Halves belonging to the context */ 60 struct QEMUBH *first_bh; 61 62 /* A simple lock used to protect the first_bh list, and ensure that 63 * no callbacks are removed while we're walking and dispatching callbacks. 64 */ 65 int walking_bh; 66 67 /* Used for aio_notify. */ 68 EventNotifier notifier; 69 70 /* GPollFDs for aio_poll() */ 71 GArray *pollfds; 72 73 /* Thread pool for performing work and receiving completion callbacks */ 74 struct ThreadPool *thread_pool; 75 } AioContext; 76 77 /* Returns 1 if there are still outstanding AIO requests; 0 otherwise */ 78 typedef int (AioFlushEventNotifierHandler)(EventNotifier *e); 79 80 /** 81 * aio_context_new: Allocate a new AioContext. 82 * 83 * AioContext provide a mini event-loop that can be waited on synchronously. 84 * They also provide bottom halves, a service to execute a piece of code 85 * as soon as possible. 86 */ 87 AioContext *aio_context_new(void); 88 89 /** 90 * aio_context_ref: 91 * @ctx: The AioContext to operate on. 92 * 93 * Add a reference to an AioContext. 94 */ 95 void aio_context_ref(AioContext *ctx); 96 97 /** 98 * aio_context_unref: 99 * @ctx: The AioContext to operate on. 100 * 101 * Drop a reference to an AioContext. 102 */ 103 void aio_context_unref(AioContext *ctx); 104 105 /** 106 * aio_bh_new: Allocate a new bottom half structure. 107 * 108 * Bottom halves are lightweight callbacks whose invocation is guaranteed 109 * to be wait-free, thread-safe and signal-safe. The #QEMUBH structure 110 * is opaque and must be allocated prior to its use. 111 */ 112 QEMUBH *aio_bh_new(AioContext *ctx, QEMUBHFunc *cb, void *opaque); 113 114 /** 115 * aio_notify: Force processing of pending events. 116 * 117 * Similar to signaling a condition variable, aio_notify forces 118 * aio_wait to exit, so that the next call will re-examine pending events. 119 * The caller of aio_notify will usually call aio_wait again very soon, 120 * or go through another iteration of the GLib main loop. Hence, aio_notify 121 * also has the side effect of recalculating the sets of file descriptors 122 * that the main loop waits for. 123 * 124 * Calling aio_notify is rarely necessary, because for example scheduling 125 * a bottom half calls it already. 126 */ 127 void aio_notify(AioContext *ctx); 128 129 /** 130 * aio_bh_poll: Poll bottom halves for an AioContext. 131 * 132 * These are internal functions used by the QEMU main loop. 133 * And notice that multiple occurrences of aio_bh_poll cannot 134 * be called concurrently 135 */ 136 int aio_bh_poll(AioContext *ctx); 137 138 /** 139 * qemu_bh_schedule: Schedule a bottom half. 140 * 141 * Scheduling a bottom half interrupts the main loop and causes the 142 * execution of the callback that was passed to qemu_bh_new. 143 * 144 * Bottom halves that are scheduled from a bottom half handler are instantly 145 * invoked. This can create an infinite loop if a bottom half handler 146 * schedules itself. 147 * 148 * @bh: The bottom half to be scheduled. 149 */ 150 void qemu_bh_schedule(QEMUBH *bh); 151 152 /** 153 * qemu_bh_cancel: Cancel execution of a bottom half. 154 * 155 * Canceling execution of a bottom half undoes the effect of calls to 156 * qemu_bh_schedule without freeing its resources yet. While cancellation 157 * itself is also wait-free and thread-safe, it can of course race with the 158 * loop that executes bottom halves unless you are holding the iothread 159 * mutex. This makes it mostly useless if you are not holding the mutex. 160 * 161 * @bh: The bottom half to be canceled. 162 */ 163 void qemu_bh_cancel(QEMUBH *bh); 164 165 /** 166 *qemu_bh_delete: Cancel execution of a bottom half and free its resources. 167 * 168 * Deleting a bottom half frees the memory that was allocated for it by 169 * qemu_bh_new. It also implies canceling the bottom half if it was 170 * scheduled. 171 * This func is async. The bottom half will do the delete action at the finial 172 * end. 173 * 174 * @bh: The bottom half to be deleted. 175 */ 176 void qemu_bh_delete(QEMUBH *bh); 177 178 /* Return whether there are any pending callbacks from the GSource 179 * attached to the AioContext. 180 * 181 * This is used internally in the implementation of the GSource. 182 */ 183 bool aio_pending(AioContext *ctx); 184 185 /* Progress in completing AIO work to occur. This can issue new pending 186 * aio as a result of executing I/O completion or bh callbacks. 187 * 188 * If there is no pending AIO operation or completion (bottom half), 189 * return false. If there are pending AIO operations of bottom halves, 190 * return true. 191 * 192 * If there are no pending bottom halves, but there are pending AIO 193 * operations, it may not be possible to make any progress without 194 * blocking. If @blocking is true, this function will wait until one 195 * or more AIO events have completed, to ensure something has moved 196 * before returning. 197 */ 198 bool aio_poll(AioContext *ctx, bool blocking); 199 200 #ifdef CONFIG_POSIX 201 /* Returns 1 if there are still outstanding AIO requests; 0 otherwise */ 202 typedef int (AioFlushHandler)(void *opaque); 203 204 /* Register a file descriptor and associated callbacks. Behaves very similarly 205 * to qemu_set_fd_handler2. Unlike qemu_set_fd_handler2, these callbacks will 206 * be invoked when using qemu_aio_wait(). 207 * 208 * Code that invokes AIO completion functions should rely on this function 209 * instead of qemu_set_fd_handler[2]. 210 */ 211 void aio_set_fd_handler(AioContext *ctx, 212 int fd, 213 IOHandler *io_read, 214 IOHandler *io_write, 215 AioFlushHandler *io_flush, 216 void *opaque); 217 #endif 218 219 /* Register an event notifier and associated callbacks. Behaves very similarly 220 * to event_notifier_set_handler. Unlike event_notifier_set_handler, these callbacks 221 * will be invoked when using qemu_aio_wait(). 222 * 223 * Code that invokes AIO completion functions should rely on this function 224 * instead of event_notifier_set_handler. 225 */ 226 void aio_set_event_notifier(AioContext *ctx, 227 EventNotifier *notifier, 228 EventNotifierHandler *io_read, 229 AioFlushEventNotifierHandler *io_flush); 230 231 /* Return a GSource that lets the main loop poll the file descriptors attached 232 * to this AioContext. 233 */ 234 GSource *aio_get_g_source(AioContext *ctx); 235 236 /* Return the ThreadPool bound to this AioContext */ 237 struct ThreadPool *aio_get_thread_pool(AioContext *ctx); 238 239 /* Functions to operate on the main QEMU AioContext. */ 240 241 bool qemu_aio_wait(void); 242 void qemu_aio_set_event_notifier(EventNotifier *notifier, 243 EventNotifierHandler *io_read, 244 AioFlushEventNotifierHandler *io_flush); 245 246 #ifdef CONFIG_POSIX 247 void qemu_aio_set_fd_handler(int fd, 248 IOHandler *io_read, 249 IOHandler *io_write, 250 AioFlushHandler *io_flush, 251 void *opaque); 252 #endif 253 254 #endif 255