VirtualBox

source: vbox/trunk/include/iprt/ioqueue.h@ 103224

Last change on this file since 103224 was 99739, checked in by vboxsync, 17 months ago

*: doxygen corrections (mostly about removing @returns from functions returning void).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.3 KB
Line 
1/** @file
2 * IPRT Generic I/O queue API.
3 */
4
5/*
6 * Copyright (C) 2019-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_ioqueue_h
37#define IPRT_INCLUDED_ioqueue_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/types.h>
43#include <iprt/sg.h>
44
45RT_C_DECLS_BEGIN
46
47/** @defgroup grp_rt_ioqueue IPRT generic I/O queue API
48 * @ingroup grp_rt
49 *
50 * This API models a generic I/O queue which can be attached to different providers
51 * for different types of handles.
52 *
53 * @{
54 */
55
56
57/**
58 * I/O queue request operations.
59 */
60typedef enum RTIOQUEUEOP
61{
62 /** The usual invalid option. */
63 RTIOQUEUEOP_INVALID = 0,
64 /** Read request. */
65 RTIOQUEUEOP_READ,
66 /** Write request. */
67 RTIOQUEUEOP_WRITE,
68 /** Synchronize (i.e. flush) request. */
69 RTIOQUEUEOP_SYNC,
70 /** Usual 32bit hack. */
71 RTIOQUEUEOP_32BIT_HACK = 0x7fffffff
72} RTIOQUEUEOP;
73/** Pointer to a I/O queue operation code. */
74typedef RTIOQUEUEOP *PRTIOQUEUEOP;
75
76/** I/O queue provider (processes requests put into the I/O queue) handle. */
77typedef struct RTIOQUEUEPROVINT *RTIOQUEUEPROV;
78/** I/O queue handle. */
79typedef struct RTIOQUEUEINT *RTIOQUEUE;
80/** Pointer to an I/O queue handle. */
81typedef RTIOQUEUE *PRTIOQUEUE;
82/** NIL I/O queue handle value. */
83#define NIL_RTIOQUEUE ((RTIOQUEUE)0)
84
85
86/**
87 * I/O queue completion event.
88 */
89typedef struct RTIOQUEUECEVT
90{
91 /** The user data passed when preparing the request. */
92 void *pvUser;
93 /** The IPRT status code for this request. */
94 int rcReq;
95 /** Transferred data size if applicaple by the request. */
96 size_t cbXfered;
97} RTIOQUEUECEVT;
98/** Pointer to a I/O queue completion event. */
99typedef RTIOQUEUECEVT *PRTIOQUEUECEVT;
100/** Pointer to a const I/O queue completion event. */
101typedef const RTIOQUEUECEVT *PCRTIOQUEUECEVT;
102
103
104/**
105 * I/O queue provider virtual method table.
106 */
107typedef struct RTIOQUEUEPROVVTABLE
108{
109 /** The structure version (RTIOQUEUEPROVVTABLE_VERSION). */
110 uint32_t uVersion;
111 /** Provider ID. */
112 const char *pszId;
113 /** Size of provider specific data for an I/O queue instance. */
114 size_t cbIoQueueProv;
115 /** The handle type the provider is able to process. */
116 RTHANDLETYPE enmHnd;
117 /** Additional flags for exposing supported features or quirks to the user. */
118 uint32_t fFlags;
119
120 /**
121 * Returns whether the provider is supported on the calling host system.
122 *
123 * @returns Flag whether the provider is supported.
124 */
125 DECLCALLBACKMEMBER(bool, pfnIsSupported,(void));
126
127 /**
128 * Initializes the provider specific parts of the given I/O queue.
129 *
130 * @returns IPRT status code.
131 * @param hIoQueueProv The I/O queue provider instance to initialize.
132 * @param fFlags Flags for the queue.
133 * @param cSqEntries Number of entries for the submission queue.
134 * @param cCqEntries Number of entries for the completion queue.
135 */
136 DECLCALLBACKMEMBER(int, pfnQueueInit,(RTIOQUEUEPROV hIoQueueProv, uint32_t fFlags, uint32_t cSqEntries, uint32_t cCqEntries));
137
138 /**
139 * Destroys the provider specific parts of the I/O queue and frees all
140 * associated resources.
141 *
142 * @param hIoQueueProv The I/O queue provider instance to destroy.
143 */
144 DECLCALLBACKMEMBER(void, pfnQueueDestroy,(RTIOQUEUEPROV hIoQueueProv));
145
146 /**
147 * Registers the given handle for use with the I/O queue instance.
148 * The generic code already checked for the correct handle type and that the
149 * handle wasn't registered already by tracking all registered handles.
150 *
151 * @returns IPRT status code.
152 * @param hIoQueueProv The I/O queue provider instance.
153 * @param pHandle The handle to register.
154 */
155 DECLCALLBACKMEMBER(int, pfnHandleRegister,(RTIOQUEUEPROV hIoQueueProv, PCRTHANDLE pHandle));
156
157 /**
158 * Deregisters the given handle for use with the I/O queue instance.
159 * The generic code already checked for the correct handle type and that the
160 * handle was registered previously.
161 *
162 * @returns IPRT status code.
163 * @param hIoQueueProv The I/O queue provider instance.
164 * @param pHandle The handle to deregister.
165 */
166 DECLCALLBACKMEMBER(int, pfnHandleDeregister,(RTIOQUEUEPROV hIoQueueProv, PCRTHANDLE pHandle));
167
168 /**
169 * Prepares a request for the given I/O queue.
170 *
171 * @returns IPRT status code.
172 * @param hIoQueueProv The I/O queue provider instance.
173 * @param pHandle The handle the request is for.
174 * @param enmOp The operation to perform.
175 * @param off Start offset (if applicable, not all handles support/require it and will ignore it).
176 * @param pvBuf Buffer to use for read/write operations (sync ignores this).
177 * @param cbBuf Size of the buffer in bytes.
178 * @param fReqFlags Additional flags for the request.
179 * @param pvUser Opaque user data which is passed back in the completion event.
180 */
181 DECLCALLBACKMEMBER(int, pfnReqPrepare,(RTIOQUEUEPROV hIoQueueProv, PCRTHANDLE pHandle, RTIOQUEUEOP enmOp,
182 uint64_t off, void *pvBuf, size_t cbBuf, uint32_t fReqFlags, void *pvUser));
183
184 /**
185 * Prepares a request for the given I/O queue.
186 *
187 * @returns IPRT status code.
188 * @param hIoQueueProv The I/O queue provider instance.
189 * @param pHandle The handle the request is for.
190 * @param enmOp The operation to perform.
191 * @param off Start offset (if applicable, not all handles support/require it and will ignore it).
192 * @param pSgBuf The S/G buufer to use for read/write operations (sync ignores this).
193 * @param cbSg Number of bytes to transfer from the S/G buffer.
194 * @param fReqFlags Additional flags for the request.
195 * @param pvUser Opaque user data which is passed back in the completion event.
196 */
197 DECLCALLBACKMEMBER(int, pfnReqPrepareSg,(RTIOQUEUEPROV hIoQueueProv, PCRTHANDLE pHandle, RTIOQUEUEOP enmOp,
198 uint64_t off, PCRTSGBUF pSgBuf, size_t cbSg, uint32_t fReqFlags, void *pvUser));
199
200 /**
201 * Commits all prepared requests to the consumer for processing.
202 *
203 * @returns IPRT status code.
204 * @param hIoQueueProv The I/O queue provider instance.
205 * @param pcReqsCommitted Where to store the number of requests actually committed.
206 */
207 DECLCALLBACKMEMBER(int, pfnCommit,(RTIOQUEUEPROV hIoQueueProv, uint32_t *pcReqsCommitted));
208
209 /**
210 * Waits for completion events from the given I/O queue.
211 *
212 * @returns IPRT status code.
213 * @retval VERR_IOQUEUE_EMPTY if there is nothing to wait for.
214 * @param hIoQueueProv The I/O queue provider instance.
215 * @param paCEvt Pointer to the array of completion event entries to fill.
216 * @param cCEvt Size of the completion event entry array.
217 * @param cMinWait Minimum number of completion events to wait for before returning.
218 * @param pcCEvt Where to store the number of completion events on success.
219 * @param fFlags Additional flags controlling the wait behavior.
220 */
221 DECLCALLBACKMEMBER(int, pfnEvtWait,(RTIOQUEUEPROV hIoQueueProv, PRTIOQUEUECEVT paCEvt, uint32_t cCEvt,
222 uint32_t cMinWait, uint32_t *pcCEvt, uint32_t fFlags));
223
224 /**
225 * Wakes up the thread waiting in RTIOQUEUEPROVVTABLE::pfnEvtWait().
226 *
227 * @returns IPRT status code.
228 * @param hIoQueueProv The I/O queue provider instance.
229 */
230 DECLCALLBACKMEMBER(int, pfnEvtWaitWakeup,(RTIOQUEUEPROV hIoQueueProv));
231
232 /** Marks the end of the structure (RTIOQUEUEPROVVTABLE_VERSION). */
233 uintptr_t uEndMarker;
234} RTIOQUEUEPROVVTABLE;
235/** Pointer to an I/O queue provider vtable. */
236typedef RTIOQUEUEPROVVTABLE *PRTIOQUEUEPROVVTABLE;
237/** Pointer to a const I/O queue provider vtable. */
238typedef RTIOQUEUEPROVVTABLE const *PCRTIOQUEUEPROVVTABLE;
239
240/** The RTIOQUEUEPROVVTABLE structure version. */
241#define RTIOQUEUEPROVVTABLE_VERSION RT_MAKE_U32_FROM_U8(0xff,0xf,1,0)
242
243/** @name RTIOQUEUEPROVVTABLE::fFlags
244 * @{ */
245/** Provider supports S/G lists. */
246#define RTIOQUEUEPROVVTABLE_F_SG RT_BIT_32(0)
247/** Mask of the valid I/O stream feature flags. */
248#define RTIOQUEUEPROVVTABLE_F_VALID_MASK UINT32_C(0x00000001)
249/** @} */
250
251
252/**
253 * Tries to return the best I/O queue provider for the given handle type on the called
254 * host system.
255 *
256 * @returns Pointer to the I/O queue provider handle table or NULL if no suitable
257 * provider was found for the given handle type.
258 * @param enmHnd The handle type to look for a provider.
259 */
260RTDECL(PCRTIOQUEUEPROVVTABLE) RTIoQueueProviderGetBestForHndType(RTHANDLETYPE enmHnd);
261
262
263/**
264 * Returns the I/O queue provider with the given ID.
265 *
266 * @returns Pointer to the I/O queue provider handle table or NULL if no provider with
267 * the given ID was found.
268 * @param pszId The ID to look for.
269 */
270RTDECL(PCRTIOQUEUEPROVVTABLE) RTIoQueueProviderGetById(const char *pszId);
271
272
273/**
274 * Creates a new I/O queue with the given consumer.
275 *
276 * @returns IPRT status code.
277 * @param phIoQueue Where to store the handle to the I/O queue on success.
278 * @param pProvVTable The I/O queue provider vtable which will process the requests.
279 * @param fFlags Flags for the queue (MBZ for now).
280 * @param cSqEntries Number of entries for the submission queue.
281 * @param cCqEntries Number of entries for the completion queue.
282 *
283 * @note The number of submission and completion queue entries serve only as a hint to the
284 * provider implementation. It may decide to align the number to a smaller or greater
285 * size.
286 */
287RTDECL(int) RTIoQueueCreate(PRTIOQUEUE phIoQueue, PCRTIOQUEUEPROVVTABLE pProvVTable,
288 uint32_t fFlags, uint32_t cSqEntries, uint32_t cCqEntries);
289
290
291/**
292 * Destroys the given I/O queue.
293 *
294 * @returns IPRT status code.
295 * @retval VERR_IOQUEUE_BUSY if the I/O queue is still processing requests.
296 * @param hIoQueue The I/O queue handle to destroy.
297 */
298RTDECL(int) RTIoQueueDestroy(RTIOQUEUE hIoQueue);
299
300
301/**
302 * Registers the given handle for use with the I/O queue.
303 *
304 * @returns IPRT status code.
305 * @retval VERR_ALREADY_EXISTS if the handle was already registered.
306 * @retval VERR_NOT_SUPPORTED if the handle type is not supported by the consumer
307 * for the given I/O queue.
308 * @param hIoQueue The I/O queue handle.
309 * @param pHandle The handle to register.
310 */
311RTDECL(int) RTIoQueueHandleRegister(RTIOQUEUE hIoQueue, PCRTHANDLE pHandle);
312
313
314/**
315 * Deregisters the given handle from the given I/O queue.
316 *
317 * @returns IPRT status code.
318 * @retval VERR_IOQUEUE_HANDLE_NOT_REGISTERED if the handle wasn't registered by a call to RTIoQueueHandleRegister().
319 * @param hIoQueue The I/O queue handle.
320 * @param pHandle The handle to deregister.
321 */
322RTDECL(int) RTIoQueueHandleDeregister(RTIOQUEUE hIoQueue, PCRTHANDLE pHandle);
323
324
325/**
326 * Prepares a request for the given I/O queue.
327 *
328 * @returns IPRT status code.
329 * @retval VERR_IOQUEUE_FULL if the I/O queue can't accept the new request because the submission queue is full.
330 * @retval VERR_IOQUEUE_HANDLE_NOT_REGISTERED if the handle wasn't registered for use with RTIoQueueHandleRegister() yet.
331 * @param hIoQueue The I/O queue handle.
332 * @param pHandle The handle the request is for.
333 * @param enmOp The operation to perform.
334 * @param off Start offset (if applicable, not all handles support/require it and will ignore it).
335 * @param pvBuf Buffer to use for read/write operations (sync ignores this).
336 * @param cbBuf Size of the buffer in bytes.
337 * @param fReqFlags Additional flags for the request.
338 * @param pvUser Opaque user data which is passed back in the completion event.
339 */
340RTDECL(int) RTIoQueueRequestPrepare(RTIOQUEUE hIoQueue, PCRTHANDLE pHandle, RTIOQUEUEOP enmOp,
341 uint64_t off, void *pvBuf, size_t cbBuf, uint32_t fReqFlags,
342 void *pvUser);
343
344
345/**
346 * Prepares a request for the given I/O queue - S/G buffer variant.
347 *
348 * @returns IPRT status code.
349 * @retval VERR_IOQUEUE_FULL if the I/O queue can't accept the new request because the submission queue is full.
350 * @retval VERR_IOQUEUE_HANDLE_NOT_REGISTERED if the handle wasn't registered for use with RTIoQueueHandleRegister() yet.
351 * @param hIoQueue The I/O queue handle.
352 * @param pHandle The handle the request is for.
353 * @param enmOp The operation to perform.
354 * @param off Start offset (if applicable, not all handles support/require it and will ignore it).
355 * @param pSgBuf The S/G buufer to use for read/write operations (sync ignores this).
356 * @param cbSg Number of bytes to transfer from the S/G buffer.
357 * @param fReqFlags Additional flags for the request.
358 * @param pvUser Opaque user data which is passed back in the completion event.
359 */
360RTDECL(int) RTIoQueueRequestPrepareSg(RTIOQUEUE hIoQueue, PCRTHANDLE pHandle, RTIOQUEUEOP enmOp,
361 uint64_t off, PCRTSGBUF pSgBuf, size_t cbSg, uint32_t fReqFlags,
362 void *pvUser);
363
364
365/**
366 * Commits all prepared requests to the consumer for processing.
367 *
368 * @returns IPRT status code.
369 * @retval VERR_IOQUEUE_EMPTY if there is nothing to commit.
370 * @param hIoQueue The I/O queue handle.
371 */
372RTDECL(int) RTIoQueueCommit(RTIOQUEUE hIoQueue);
373
374
375/**
376 * Waits for completion events from the given I/O queue.
377 *
378 * @returns IPRT status code.
379 * @retval VERR_IOQUEUE_EMPTY if there is nothing to wait for.
380 * @param hIoQueue The I/O queue handle.
381 * @param paCEvt Pointer to the array of completion event entries to fill.
382 * @param cCEvt Size of the completion event entry array.
383 * @param cMinWait Minimum number of completion events to wait for before returning.
384 * @param pcCEvt Where to store the number of completion events on success.
385 * @param fFlags Additional flags controlling the wait behavior.
386 */
387RTDECL(int) RTIoQueueEvtWait(RTIOQUEUE hIoQueue, PRTIOQUEUECEVT paCEvt, uint32_t cCEvt, uint32_t cMinWait,
388 uint32_t *pcCEvt, uint32_t fFlags);
389
390
391/**
392 * Wakes up the thread waiting in RTIoQueueEvtWait().
393 *
394 * @returns IPRT status code.
395 * @param hIoQueue The I/O queue handle to wake up.
396 */
397RTDECL(int) RTIoQueueEvtWaitWakeup(RTIOQUEUE hIoQueue);
398
399/** @} */
400
401RT_C_DECLS_END
402
403#endif /* !IPRT_INCLUDED_ioqueue_h */
404
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette