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