VirtualBox

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

Last change on this file since 78976 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif

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