numa: add -numa node,memdev= option
[qemu.git] / include / block / aio.h
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/typedefs.h"
18 #include "qemu-common.h"
19 #include "qemu/queue.h"
20 #include "qemu/event_notifier.h"
21 #include "qemu/thread.h"
22 #include "qemu/rfifolock.h"
23 #include "qemu/timer.h"
24
25 typedef struct BlockDriverAIOCB BlockDriverAIOCB;
26 typedef void BlockDriverCompletionFunc(void *opaque, int ret);
27
28 typedef struct AIOCBInfo {
29 void (*cancel)(BlockDriverAIOCB *acb);
30 size_t aiocb_size;
31 } AIOCBInfo;
32
33 struct BlockDriverAIOCB {
34 const AIOCBInfo *aiocb_info;
35 BlockDriverState *bs;
36 BlockDriverCompletionFunc *cb;
37 void *opaque;
38 };
39
40 void *qemu_aio_get(const AIOCBInfo *aiocb_info, BlockDriverState *bs,
41 BlockDriverCompletionFunc *cb, void *opaque);
42 void qemu_aio_release(void *p);
43
44 typedef struct AioHandler AioHandler;
45 typedef void QEMUBHFunc(void *opaque);
46 typedef void IOHandler(void *opaque);
47
48 struct AioContext {
49 GSource source;
50
51 /* Protects all fields from multi-threaded access */
52 RFifoLock lock;
53
54 /* The list of registered AIO handlers */
55 QLIST_HEAD(, AioHandler) aio_handlers;
56
57 /* This is a simple lock used to protect the aio_handlers list.
58 * Specifically, it's used to ensure that no callbacks are removed while
59 * we're walking and dispatching callbacks.
60 */
61 int walking_handlers;
62
63 /* lock to protect between bh's adders and deleter */
64 QemuMutex bh_lock;
65 /* Anchor of the list of Bottom Halves belonging to the context */
66 struct QEMUBH *first_bh;
67
68 /* A simple lock used to protect the first_bh list, and ensure that
69 * no callbacks are removed while we're walking and dispatching callbacks.
70 */
71 int walking_bh;
72
73 /* Used for aio_notify. */
74 EventNotifier notifier;
75
76 /* GPollFDs for aio_poll() */
77 GArray *pollfds;
78
79 /* Thread pool for performing work and receiving completion callbacks */
80 struct ThreadPool *thread_pool;
81
82 /* TimerLists for calling timers - one per clock type */
83 QEMUTimerListGroup tlg;
84 };
85
86 /**
87 * aio_context_new: Allocate a new AioContext.
88 *
89 * AioContext provide a mini event-loop that can be waited on synchronously.
90 * They also provide bottom halves, a service to execute a piece of code
91 * as soon as possible.
92 */
93 AioContext *aio_context_new(void);
94
95 /**
96 * aio_context_ref:
97 * @ctx: The AioContext to operate on.
98 *
99 * Add a reference to an AioContext.
100 */
101 void aio_context_ref(AioContext *ctx);
102
103 /**
104 * aio_context_unref:
105 * @ctx: The AioContext to operate on.
106 *
107 * Drop a reference to an AioContext.
108 */
109 void aio_context_unref(AioContext *ctx);
110
111 /* Take ownership of the AioContext. If the AioContext will be shared between
112 * threads, a thread must have ownership when calling aio_poll().
113 *
114 * Note that multiple threads calling aio_poll() means timers, BHs, and
115 * callbacks may be invoked from a different thread than they were registered
116 * from. Therefore, code must use AioContext acquire/release or use
117 * fine-grained synchronization to protect shared state if other threads will
118 * be accessing it simultaneously.
119 */
120 void aio_context_acquire(AioContext *ctx);
121
122 /* Relinquish ownership of the AioContext. */
123 void aio_context_release(AioContext *ctx);
124
125 /**
126 * aio_bh_new: Allocate a new bottom half structure.
127 *
128 * Bottom halves are lightweight callbacks whose invocation is guaranteed
129 * to be wait-free, thread-safe and signal-safe. The #QEMUBH structure
130 * is opaque and must be allocated prior to its use.
131 */
132 QEMUBH *aio_bh_new(AioContext *ctx, QEMUBHFunc *cb, void *opaque);
133
134 /**
135 * aio_notify: Force processing of pending events.
136 *
137 * Similar to signaling a condition variable, aio_notify forces
138 * aio_wait to exit, so that the next call will re-examine pending events.
139 * The caller of aio_notify will usually call aio_wait again very soon,
140 * or go through another iteration of the GLib main loop. Hence, aio_notify
141 * also has the side effect of recalculating the sets of file descriptors
142 * that the main loop waits for.
143 *
144 * Calling aio_notify is rarely necessary, because for example scheduling
145 * a bottom half calls it already.
146 */
147 void aio_notify(AioContext *ctx);
148
149 /**
150 * aio_bh_poll: Poll bottom halves for an AioContext.
151 *
152 * These are internal functions used by the QEMU main loop.
153 * And notice that multiple occurrences of aio_bh_poll cannot
154 * be called concurrently
155 */
156 int aio_bh_poll(AioContext *ctx);
157
158 /**
159 * qemu_bh_schedule: Schedule a bottom half.
160 *
161 * Scheduling a bottom half interrupts the main loop and causes the
162 * execution of the callback that was passed to qemu_bh_new.
163 *
164 * Bottom halves that are scheduled from a bottom half handler are instantly
165 * invoked. This can create an infinite loop if a bottom half handler
166 * schedules itself.
167 *
168 * @bh: The bottom half to be scheduled.
169 */
170 void qemu_bh_schedule(QEMUBH *bh);
171
172 /**
173 * qemu_bh_cancel: Cancel execution of a bottom half.
174 *
175 * Canceling execution of a bottom half undoes the effect of calls to
176 * qemu_bh_schedule without freeing its resources yet. While cancellation
177 * itself is also wait-free and thread-safe, it can of course race with the
178 * loop that executes bottom halves unless you are holding the iothread
179 * mutex. This makes it mostly useless if you are not holding the mutex.
180 *
181 * @bh: The bottom half to be canceled.
182 */
183 void qemu_bh_cancel(QEMUBH *bh);
184
185 /**
186 *qemu_bh_delete: Cancel execution of a bottom half and free its resources.
187 *
188 * Deleting a bottom half frees the memory that was allocated for it by
189 * qemu_bh_new. It also implies canceling the bottom half if it was
190 * scheduled.
191 * This func is async. The bottom half will do the delete action at the finial
192 * end.
193 *
194 * @bh: The bottom half to be deleted.
195 */
196 void qemu_bh_delete(QEMUBH *bh);
197
198 /* Return whether there are any pending callbacks from the GSource
199 * attached to the AioContext.
200 *
201 * This is used internally in the implementation of the GSource.
202 */
203 bool aio_pending(AioContext *ctx);
204
205 /* Progress in completing AIO work to occur. This can issue new pending
206 * aio as a result of executing I/O completion or bh callbacks.
207 *
208 * If there is no pending AIO operation or completion (bottom half),
209 * return false. If there are pending AIO operations of bottom halves,
210 * return true.
211 *
212 * If there are no pending bottom halves, but there are pending AIO
213 * operations, it may not be possible to make any progress without
214 * blocking. If @blocking is true, this function will wait until one
215 * or more AIO events have completed, to ensure something has moved
216 * before returning.
217 */
218 bool aio_poll(AioContext *ctx, bool blocking);
219
220 #ifdef CONFIG_POSIX
221 /* Register a file descriptor and associated callbacks. Behaves very similarly
222 * to qemu_set_fd_handler2. Unlike qemu_set_fd_handler2, these callbacks will
223 * be invoked when using qemu_aio_wait().
224 *
225 * Code that invokes AIO completion functions should rely on this function
226 * instead of qemu_set_fd_handler[2].
227 */
228 void aio_set_fd_handler(AioContext *ctx,
229 int fd,
230 IOHandler *io_read,
231 IOHandler *io_write,
232 void *opaque);
233 #endif
234
235 /* Register an event notifier and associated callbacks. Behaves very similarly
236 * to event_notifier_set_handler. Unlike event_notifier_set_handler, these callbacks
237 * will be invoked when using qemu_aio_wait().
238 *
239 * Code that invokes AIO completion functions should rely on this function
240 * instead of event_notifier_set_handler.
241 */
242 void aio_set_event_notifier(AioContext *ctx,
243 EventNotifier *notifier,
244 EventNotifierHandler *io_read);
245
246 /* Return a GSource that lets the main loop poll the file descriptors attached
247 * to this AioContext.
248 */
249 GSource *aio_get_g_source(AioContext *ctx);
250
251 /* Return the ThreadPool bound to this AioContext */
252 struct ThreadPool *aio_get_thread_pool(AioContext *ctx);
253
254 /* Functions to operate on the main QEMU AioContext. */
255
256 bool qemu_aio_wait(void);
257 void qemu_aio_set_event_notifier(EventNotifier *notifier,
258 EventNotifierHandler *io_read);
259
260 #ifdef CONFIG_POSIX
261 void qemu_aio_set_fd_handler(int fd,
262 IOHandler *io_read,
263 IOHandler *io_write,
264 void *opaque);
265 #endif
266
267 /**
268 * aio_timer_new:
269 * @ctx: the aio context
270 * @type: the clock type
271 * @scale: the scale
272 * @cb: the callback to call on timer expiry
273 * @opaque: the opaque pointer to pass to the callback
274 *
275 * Allocate a new timer attached to the context @ctx.
276 * The function is responsible for memory allocation.
277 *
278 * The preferred interface is aio_timer_init. Use that
279 * unless you really need dynamic memory allocation.
280 *
281 * Returns: a pointer to the new timer
282 */
283 static inline QEMUTimer *aio_timer_new(AioContext *ctx, QEMUClockType type,
284 int scale,
285 QEMUTimerCB *cb, void *opaque)
286 {
287 return timer_new_tl(ctx->tlg.tl[type], scale, cb, opaque);
288 }
289
290 /**
291 * aio_timer_init:
292 * @ctx: the aio context
293 * @ts: the timer
294 * @type: the clock type
295 * @scale: the scale
296 * @cb: the callback to call on timer expiry
297 * @opaque: the opaque pointer to pass to the callback
298 *
299 * Initialise a new timer attached to the context @ctx.
300 * The caller is responsible for memory allocation.
301 */
302 static inline void aio_timer_init(AioContext *ctx,
303 QEMUTimer *ts, QEMUClockType type,
304 int scale,
305 QEMUTimerCB *cb, void *opaque)
306 {
307 timer_init(ts, ctx->tlg.tl[type], scale, cb, opaque);
308 }
309
310 #endif