VirtualBox

source: vbox/trunk/include/VBox/vmm/pdmblkcache.h@ 76398

Last change on this file since 76398 was 69107, checked in by vboxsync, 7 years ago

include/VBox/: (C) year

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.0 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Block cache.
3 */
4
5/*
6 * Copyright (C) 2007-2017 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___VBox_vmm_pdmblkcache_h
27#define ___VBox_vmm_pdmblkcache_h
28
29#include <VBox/types.h>
30#include <VBox/err.h>
31#include <iprt/assert.h>
32#include <iprt/sg.h>
33
34
35RT_C_DECLS_BEGIN
36
37/** @defgroup grp_pdm_blk_cache The PDM Block Cache API
38 * @ingroup grp_pdm
39 * @{
40 */
41
42/** Pointer to a PDM block cache. */
43typedef struct PDMBLKCACHE *PPDMBLKCACHE;
44/** Pointer to a PDM block cache pointer. */
45typedef PPDMBLKCACHE *PPPDMBLKCACHE;
46
47/** I/O transfer handle. */
48typedef struct PDMBLKCACHEIOXFER *PPDMBLKCACHEIOXFER;
49
50/**
51 * Block cache I/O request transfer direction.
52 */
53typedef enum PDMBLKCACHEXFERDIR
54{
55 /** Read */
56 PDMBLKCACHEXFERDIR_READ = 0,
57 /** Write */
58 PDMBLKCACHEXFERDIR_WRITE,
59 /** Flush */
60 PDMBLKCACHEXFERDIR_FLUSH,
61 /** Discard */
62 PDMBLKCACHEXFERDIR_DISCARD
63} PDMBLKCACHEXFERDIR;
64
65/**
66 * Completion callback for drivers.
67 *
68 * @param pDrvIns The driver instance.
69 * @param pvUser User argument given during request initiation.
70 * @param rc The status code of the completed request.
71 */
72typedef DECLCALLBACK(void) FNPDMBLKCACHEXFERCOMPLETEDRV(PPDMDRVINS pDrvIns, void *pvUser, int rc);
73/** Pointer to a FNPDMBLKCACHEXFERCOMPLETEDRV(). */
74typedef FNPDMBLKCACHEXFERCOMPLETEDRV *PFNPDMBLKCACHEXFERCOMPLETEDRV;
75
76/**
77 * I/O enqueue callback for drivers.
78 *
79 * @param pDrvIns The driver instance.
80 * @param enmXferDir Transfer direction.
81 * @param off Transfer offset.
82 * @param cbXfer Transfer size.
83 * @param pSgBuf Scather / gather buffer for the transfer.
84 * @param hIoXfer I/O transfer handle to ping on completion.
85 */
86typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEDRV(PPDMDRVINS pDrvIns, PDMBLKCACHEXFERDIR enmXferDir,
87 uint64_t off, size_t cbXfer, PCRTSGBUF pSgBuf, PPDMBLKCACHEIOXFER hIoXfer);
88/** Pointer to a FNPDMBLKCACHEXFERENQUEUEDRV(). */
89typedef FNPDMBLKCACHEXFERENQUEUEDRV *PFNPDMBLKCACHEXFERENQUEUEDRV;
90
91/**
92 * Discard enqueue callback for drivers.
93 *
94 * @param pDrvIns The driver instance.
95 * @param paRanges Ranges to discard.
96 * @param cRanges Number of range entries.
97 * @param hIoXfer I/O handle to return on completion.
98 */
99typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEDISCARDDRV(PPDMDRVINS pDrvIns, PCRTRANGE paRanges, unsigned cRanges,
100 PPDMBLKCACHEIOXFER hIoXfer);
101/** Pointer to a FNPDMBLKCACHEXFERENQUEUEDISCARDDRV(). */
102typedef FNPDMBLKCACHEXFERENQUEUEDISCARDDRV *PFNPDMBLKCACHEXFERENQUEUEDISCARDDRV;
103
104/**
105 * Completion callback for devices.
106 *
107 * @param pDrvIns The device instance.
108 * @param pvUser User argument given during request initiation.
109 * @param rc The status code of the completed request.
110 */
111typedef DECLCALLBACK(void) FNPDMBLKCACHEXFERCOMPLETEDEV(PPDMDEVINS pDevIns, void *pvUser, int rc);
112/** Pointer to a FNPDMBLKCACHEXFERCOMPLETEDEV(). */
113typedef FNPDMBLKCACHEXFERCOMPLETEDEV *PFNPDMBLKCACHEXFERCOMPLETEDEV;
114
115/**
116 * I/O enqueue callback for devices.
117 *
118 * @param pDevIns The device instance.
119 * @param enmXferDir Transfer direction.
120 * @param off Transfer offset.
121 * @param cbXfer Transfer size.
122 * @param pSgBuf Scather / gather buffer for the transfer.
123 * @param hIoXfer I/O transfer handle to ping on completion.
124 */
125typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEDEV(PPDMDEVINS pDevIns, PDMBLKCACHEXFERDIR enmXferDir,
126 uint64_t off, size_t cbXfer, PCRTSGBUF pSgBuf, PPDMBLKCACHEIOXFER hIoXfer);
127/** Pointer to a FNPDMBLKCACHEXFERENQUEUEDEV(). */
128typedef FNPDMBLKCACHEXFERENQUEUEDEV *PFNPDMBLKCACHEXFERENQUEUEDEV;
129
130/**
131 * Discard enqueue callback for devices.
132 *
133 * @param pDrvIns The driver instance.
134 * @param paRanges Ranges to discard.
135 * @param cRanges Number of range entries.
136 * @param hIoXfer I/O handle to return on completion.
137 */
138typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEDISCARDDEV(PPDMDEVINS pDevIns, PCRTRANGE paRanges, unsigned cRanges,
139 PPDMBLKCACHEIOXFER hIoXfer);
140/** Pointer to a FNPDMBLKCACHEXFERENQUEUEDISCARDDEV(). */
141typedef FNPDMBLKCACHEXFERENQUEUEDISCARDDEV *PFNPDMBLKCACHEXFERENQUEUEDISCARDDEV;
142
143/**
144 * Completion callback for drivers.
145 *
146 * @param pDrvIns The driver instance.
147 * @param pvUser User argument given during request initiation.
148 * @param rc The status code of the completed request.
149 */
150typedef DECLCALLBACK(void) FNPDMBLKCACHEXFERCOMPLETEINT(void *pvUserInt, void *pvUser, int rc);
151/** Pointer to a FNPDMBLKCACHEXFERCOMPLETEINT(). */
152typedef FNPDMBLKCACHEXFERCOMPLETEINT *PFNPDMBLKCACHEXFERCOMPLETEINT;
153
154/**
155 * I/O enqueue callback for drivers.
156 *
157 * @param pDrvIns The driver instance.
158 * @param enmXferDir Transfer direction.
159 * @param off Transfer offset.
160 * @param cbXfer Transfer size.
161 * @param pSgBuf Scather / gather buffer for the transfer.
162 * @param hIoXfer I/O transfer handle to ping on completion.
163 */
164typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEINT(void *pvUser, PDMBLKCACHEXFERDIR enmXferDir,
165 uint64_t off, size_t cbXfer, PCRTSGBUF pSgBuf, PPDMBLKCACHEIOXFER hIoXfer);
166/** Pointer to a FNPDMBLKCACHEXFERENQUEUEINT(). */
167typedef FNPDMBLKCACHEXFERENQUEUEINT *PFNPDMBLKCACHEXFERENQUEUEINT;
168
169/**
170 * Discard enqueue callback for VMM internal users.
171 *
172 * @param pDrvIns The driver instance.
173 * @param paRanges Ranges to discard.
174 * @param cRanges Number of range entries.
175 * @param hIoXfer I/O handle to return on completion.
176 */
177typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEDISCARDINT(void *pvUser, PCRTRANGE paRanges, unsigned cRanges,
178 PPDMBLKCACHEIOXFER hIoXfer);
179/** Pointer to a FNPDMBLKCACHEXFERENQUEUEDISCARDINT(). */
180typedef FNPDMBLKCACHEXFERENQUEUEDISCARDINT *PFNPDMBLKCACHEXFERENQUEUEDISCARDINT;
181
182/**
183 * Completion callback for USB.
184 *
185 * @param pDrvIns The driver instance.
186 * @param pvUser User argument given during request initiation.
187 * @param rc The status code of the completed request.
188 */
189typedef DECLCALLBACK(void) FNPDMBLKCACHEXFERCOMPLETEUSB(PPDMUSBINS pUsbIns, void *pvUser, int rc);
190/** Pointer to a FNPDMBLKCACHEXFERCOMPLETEUSB(). */
191typedef FNPDMBLKCACHEXFERCOMPLETEUSB *PFNPDMBLKCACHEXFERCOMPLETEUSB;
192
193/**
194 * I/O enqueue callback for drivers.
195 *
196 * @param pDrvIns The driver instance.
197 * @param enmXferDir Transfer direction.
198 * @param off Transfer offset.
199 * @param cbXfer Transfer size.
200 * @param pSgBuf Scather / gather buffer for the transfer.
201 * @param hIoXfer I/O transfer handle to ping on completion.
202 */
203typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEUSB(PPDMUSBINS pUsbIns, PDMBLKCACHEXFERDIR enmXferDir,
204 uint64_t off, size_t cbXfer, PCRTSGBUF pSgBuf, PPDMBLKCACHEIOXFER hIoXfer);
205/** Pointer to a FNPDMBLKCACHEXFERENQUEUEUSB(). */
206typedef FNPDMBLKCACHEXFERENQUEUEUSB *PFNPDMBLKCACHEXFERENQUEUEUSB;
207
208/**
209 * Discard enqueue callback for USB devices.
210 *
211 * @param pUsbIns The USB device instance.
212 * @param paRanges Ranges to discard.
213 * @param cRanges Number of range entries.
214 * @param hIoXfer I/O handle to return on completion.
215 */
216typedef DECLCALLBACK(int) FNPDMBLKCACHEXFERENQUEUEDISCARDUSB(PPDMUSBINS pUsbIns, PCRTRANGE paRanges, unsigned cRanges,
217 PPDMBLKCACHEIOXFER hIoXfer);
218/** Pointer to a FNPDMBLKCACHEXFERENQUEUEDISCARDUSB(). */
219typedef FNPDMBLKCACHEXFERENQUEUEDISCARDUSB *PFNPDMBLKCACHEXFERENQUEUEDISCARDUSB;
220
221/**
222 * Create a block cache user for a driver instance.
223 *
224 * @returns VBox status code.
225 * @param pVM The cross context VM structure.
226 * @param pDrvIns The driver instance.
227 * @param ppBlkCache Where to store the handle to the block cache.
228 * @param pfnXferComplete The I/O transfer complete callback.
229 * @param pfnXferEnqueue The I/O request enqueue callback.
230 * @param pfnXferEnqueueDiscard The discard request enqueue callback.
231 * @param pcszId Unique ID used to identify the user.
232 */
233VMMR3DECL(int) PDMR3BlkCacheRetainDriver(PVM pVM, PPDMDRVINS pDrvIns, PPPDMBLKCACHE ppBlkCache,
234 PFNPDMBLKCACHEXFERCOMPLETEDRV pfnXferComplete,
235 PFNPDMBLKCACHEXFERENQUEUEDRV pfnXferEnqueue,
236 PFNPDMBLKCACHEXFERENQUEUEDISCARDDRV pfnXferEnqueueDiscard,
237 const char *pcszId);
238
239/**
240 * Create a block cache user for a device instance.
241 *
242 * @returns VBox status code.
243 * @param pVM The cross context VM structure.
244 * @param pDevIns The device instance.
245 * @param ppBlkCache Where to store the handle to the block cache.
246 * @param pfnXferComplete The I/O transfer complete callback.
247 * @param pfnXferEnqueue The I/O request enqueue callback.
248 * @param pfnXferEnqueueDiscard The discard request enqueue callback.
249 * @param pcszId Unique ID used to identify the user.
250 */
251VMMR3DECL(int) PDMR3BlkCacheRetainDevice(PVM pVM, PPDMDEVINS pDevIns, PPPDMBLKCACHE ppBlkCache,
252 PFNPDMBLKCACHEXFERCOMPLETEDEV pfnXferComplete,
253 PFNPDMBLKCACHEXFERENQUEUEDEV pfnXferEnqueue,
254 PFNPDMBLKCACHEXFERENQUEUEDISCARDDEV pfnXferEnqueueDiscard,
255 const char *pcszId);
256
257/**
258 * Create a block cache user for a USB instance.
259 *
260 * @returns VBox status code.
261 * @param pVM The cross context VM structure.
262 * @param pUsbIns The USB device instance.
263 * @param ppBlkCache Where to store the handle to the block cache.
264 * @param pfnXferComplete The I/O transfer complete callback.
265 * @param pfnXferEnqueue The I/O request enqueue callback.
266 * @param pfnXferEnqueueDiscard The discard request enqueue callback.
267 * @param pcszId Unique ID used to identify the user.
268 */
269VMMR3DECL(int) PDMR3BlkCacheRetainUsb(PVM pVM, PPDMUSBINS pUsbIns, PPPDMBLKCACHE ppBlkCache,
270 PFNPDMBLKCACHEXFERCOMPLETEUSB pfnXferComplete,
271 PFNPDMBLKCACHEXFERENQUEUEUSB pfnXferEnqueue,
272 PFNPDMBLKCACHEXFERENQUEUEDISCARDUSB pfnXferEnqueueDiscard,
273 const char *pcszId);
274
275/**
276 * Create a block cache user for internal use by VMM.
277 *
278 * @returns VBox status code.
279 * @param pVM The cross context VM structure.
280 * @param pvUser Opaque user data.
281 * @param ppBlkCache Where to store the handle to the block cache.
282 * @param pfnXferComplete The I/O transfer complete callback.
283 * @param pfnXferEnqueue The I/O request enqueue callback.
284 * @param pfnXferEnqueueDiscard The discard request enqueue callback.
285 * @param pcszId Unique ID used to identify the user.
286 */
287VMMR3DECL(int) PDMR3BlkCacheRetainInt(PVM pVM, void *pvUser, PPPDMBLKCACHE ppBlkCache,
288 PFNPDMBLKCACHEXFERCOMPLETEINT pfnXferComplete,
289 PFNPDMBLKCACHEXFERENQUEUEINT pfnXferEnqueue,
290 PFNPDMBLKCACHEXFERENQUEUEDISCARDINT pfnXferEnqueueDiscard,
291 const char *pcszId);
292
293/**
294 * Releases a block cache handle.
295 *
296 * @returns nothing.
297 * @param pBlkCache Block cache handle.
298 */
299VMMR3DECL(void) PDMR3BlkCacheRelease(PPDMBLKCACHE pBlkCache);
300
301/**
302 * Releases all block cache handles for a device instance.
303 *
304 * @returns nothing.
305 * @param pVM The cross context VM structure.
306 * @param pDevIns The device instance.
307 */
308VMMR3DECL(void) PDMR3BlkCacheReleaseDevice(PVM pVM, PPDMDEVINS pDevIns);
309
310/**
311 * Releases all block cache handles for a driver instance.
312 *
313 * @returns nothing.
314 * @param pVM The cross context VM structure.
315 * @param pDrvIns The driver instance.
316 */
317VMMR3DECL(void) PDMR3BlkCacheReleaseDriver(PVM pVM, PPDMDRVINS pDrvIns);
318
319/**
320 * Releases all block cache handles for a USB device instance.
321 *
322 * @returns nothing.
323 * @param pVM The cross context VM structure.
324 * @param pUsbIns The USB device instance.
325 */
326VMMR3DECL(void) PDMR3BlkCacheReleaseUsb(PVM pVM, PPDMUSBINS pUsbIns);
327
328/**
329 * Creates a read task on the given endpoint.
330 *
331 * @returns VBox status code.
332 * @param pBlkCache The cache instance.
333 * @param off Where to start reading from.
334 * @param pSgBuf Scatter gather buffer store the data in.
335 * @param cbRead The overall number of bytes to read.
336 * @param pvUser Opaque user data returned in the completion callback
337 * upon completion of the read.
338 */
339VMMR3DECL(int) PDMR3BlkCacheRead(PPDMBLKCACHE pBlkCache, uint64_t off, PCRTSGBUF pSgBuf, size_t cbRead, void *pvUser);
340
341/**
342 * Creates a write task on the given endpoint.
343 *
344 * @returns VBox status code.
345 * @param pBlkCache The cache instance.
346 * @param off Where to start writing at.
347 * @param pSgBuf Scatter gather buffer gather the data from.
348 * @param cbWrite The overall number of bytes to write.
349 * @param pvUser Opaque user data returned in the completion callback
350 * upon completion of the task.
351 */
352VMMR3DECL(int) PDMR3BlkCacheWrite(PPDMBLKCACHE pBlkCache, uint64_t off, PCRTSGBUF pSgBuf, size_t cbWrite, void *pvUser);
353
354/**
355 * Creates a flush task on the given endpoint.
356 *
357 * @returns VBox status code.
358 * @param pBlkCache The cache instance.
359 * @param pvUser Opaque user data returned in the completion callback
360 * upon completion of the task.
361 */
362VMMR3DECL(int) PDMR3BlkCacheFlush(PPDMBLKCACHE pBlkCache, void *pvUser);
363
364/**
365 * Discards the given ranges from the cache.
366 *
367 * @returns VBox status code.
368 * @param pBlkCache The cache instance.
369 * @param paRanges Array of ranges to discard.
370 * @param cRanges Number of ranges in the array.
371 * @param pvUser Opaque user data returned in the completion callback
372 * upon completion of the task.
373 */
374VMMR3DECL(int) PDMR3BlkCacheDiscard(PPDMBLKCACHE pBlkCache, PCRTRANGE paRanges, unsigned cRanges, void *pvUser);
375
376/**
377 * Notify the cache of a complete I/O transfer.
378 *
379 * @returns nothing.
380 * @param pBlkCache The cache instance.
381 * @param hIoXfer The I/O transfer handle which completed.
382 * @param rcIoXfer The status code of the completed request.
383 */
384VMMR3DECL(void) PDMR3BlkCacheIoXferComplete(PPDMBLKCACHE pBlkCache, PPDMBLKCACHEIOXFER hIoXfer, int rcIoXfer);
385
386/**
387 * Suspends the block cache.
388 *
389 * The cache waits until all I/O transfers completed and stops to enqueue new
390 * requests after the call returned but will not accept reads, write or flushes
391 * either.
392 *
393 * @returns VBox status code.
394 * @param pBlkCache The cache instance.
395 */
396VMMR3DECL(int) PDMR3BlkCacheSuspend(PPDMBLKCACHE pBlkCache);
397
398/**
399 * Resumes operation of the block cache.
400 *
401 * @returns VBox status code.
402 * @param pBlkCache The cache instance.
403 */
404VMMR3DECL(int) PDMR3BlkCacheResume(PPDMBLKCACHE pBlkCache);
405
406/**
407 * Clears the block cache and removes all entries.
408 *
409 * The cache waits until all I/O transfers completed.
410 *
411 * @returns VBox status code.
412 * @param pBlkCache The cache instance.
413 */
414VMMR3DECL(int) PDMR3BlkCacheClear(PPDMBLKCACHE pBlkCache);
415
416/** @} */
417
418RT_C_DECLS_END
419
420#endif
421
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