VirtualBox

source: vbox/trunk/include/VBox/vd.h@ 103224

Last change on this file since 103224 was 100078, checked in by vboxsync, 16 months ago

Main/src-server and Storage: Immutable media handling flexibility added bugref:5995

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 76.8 KB
Line 
1/** @file
2 * VBox HDD Container API.
3 */
4
5/*
6 * Copyright (C) 2006-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 VBOX_INCLUDED_vd_h
37#define VBOX_INCLUDED_vd_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/assert.h>
43#include <iprt/string.h>
44#include <iprt/mem.h>
45#include <iprt/file.h>
46#include <iprt/net.h>
47#include <iprt/sg.h>
48#include <iprt/vfs.h>
49#include <VBox/cdefs.h>
50#include <VBox/types.h>
51#include <VBox/vdmedia.h>
52#include <VBox/vd-ifs.h>
53
54RT_C_DECLS_BEGIN
55
56#ifdef IN_RING0
57# error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
58#endif
59
60/** @defgroup grp_vd Virtual Disk Container
61 * @{
62 */
63
64/** Current VMDK image version. */
65#define VMDK_IMAGE_VERSION (0x0001)
66
67/** Current VDI image major version. */
68#define VDI_IMAGE_VERSION_MAJOR (0x0001)
69/** Current VDI image minor version. */
70#define VDI_IMAGE_VERSION_MINOR (0x0001)
71/** Current VDI image version. */
72#define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) | VDI_IMAGE_VERSION_MINOR)
73
74/** Get VDI major version from combined version. */
75#define VDI_GET_VERSION_MAJOR(uVer) ((uVer) >> 16)
76/** Get VDI minor version from combined version. */
77#define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
78
79/** Placeholder for specifying the last opened image. */
80#define VD_LAST_IMAGE 0xffffffffU
81
82/** Placeholder for VDCopyEx to indicate that the image content is unknown. */
83#define VD_IMAGE_CONTENT_UNKNOWN 0xffffffffU
84
85/** @name VBox HDD container image flags
86 * Same values as MediumVariant API enum.
87 * @{
88 */
89/** No flags. */
90#define VD_IMAGE_FLAGS_NONE (0)
91/** Fixed image. */
92#define VD_IMAGE_FLAGS_FIXED (0x10000)
93/** Diff image. Mutually exclusive with fixed image. */
94#define VD_IMAGE_FLAGS_DIFF (0x20000)
95/** VMDK: Split image into 2GB extents. */
96#define VD_VMDK_IMAGE_FLAGS_SPLIT_2G (0x0001)
97/** VMDK: Raw disk image (giving access to a number of host partitions). */
98#define VD_VMDK_IMAGE_FLAGS_RAWDISK (0x0002)
99/** VMDK: stream optimized image, read only. */
100#define VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED (0x0004)
101/** VMDK: ESX variant, use in addition to other flags. */
102#define VD_VMDK_IMAGE_FLAGS_ESX (0x0008)
103/** VDI: Fill new blocks with zeroes while expanding image file. Only valid
104 * for newly created images, never set for opened existing images. */
105#define VD_VDI_IMAGE_FLAGS_ZERO_EXPAND (0x0100)
106
107/** Mask of valid image flags for VMDK. */
108#define VD_VMDK_IMAGE_FLAGS_MASK ( VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE \
109 | VD_VMDK_IMAGE_FLAGS_SPLIT_2G | VD_VMDK_IMAGE_FLAGS_RAWDISK \
110 | VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED | VD_VMDK_IMAGE_FLAGS_ESX)
111
112/** Mask of valid image flags for VDI. */
113#define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE | VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
114
115/** Mask of all valid image flags for all formats. */
116#define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK | VD_VDI_IMAGE_FLAGS_MASK)
117
118/** Default image flags. */
119#define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
120/** @} */
121
122/** @name VD image repair flags
123 * @{
124 */
125/** Don't repair the image but check what needs to be done. */
126#define VD_REPAIR_DRY_RUN RT_BIT_32(0)
127
128/** Mask of all valid repair flags. */
129#define VD_REPAIR_FLAGS_MASK (VD_REPAIR_DRY_RUN)
130/** @} */
131
132/** @name VD image VFS file flags
133 * @{
134 */
135/** Destroy the VD disk container when the VFS file is released. */
136#define VD_VFSFILE_DESTROY_ON_RELEASE RT_BIT_32(0)
137
138/** Mask of all valid repair flags. */
139#define VD_VFSFILE_FLAGS_MASK (VD_VFSFILE_DESTROY_ON_RELEASE)
140/** @} */
141
142/** @name VDISKRAW_XXX - VBox raw disk or partition flags
143 * @{
144 */
145/** No special treatment. */
146#define VDISKRAW_NORMAL 0
147/** Whether this is a raw disk (where the partition information is ignored) or
148 * not. Valid only in the raw disk descriptor. */
149#define VDISKRAW_DISK RT_BIT(0)
150/** Open the corresponding raw disk or partition for reading only, no matter
151 * how the image is created or opened. */
152#define VDISKRAW_READONLY RT_BIT(1)
153/** @} */
154
155/**
156 * Auxiliary type for describing partitions on raw disks.
157 *
158 * The entries must be in ascending order (as far as uStart is concerned), and
159 * must not overlap. Note that this does not correspond 1:1 to partitions, it is
160 * describing the general meaning of contiguous areas on the disk.
161 */
162typedef struct VDISKRAWPARTDESC
163{
164 /** Device to use for this partition/data area. Can be the disk device if
165 * the offset field is set appropriately. If this is NULL, then this
166 * partition will not be accessible to the guest. The size of the data area
167 * must still be set correctly. */
168 char *pszRawDevice;
169 /** Pointer to the partitioning info. NULL means this is a regular data
170 * area on disk, non-NULL denotes data which should be copied to the
171 * partition data overlay. */
172 void *pvPartitionData;
173 /** Offset where the data starts in this device. */
174 uint64_t offStartInDevice;
175 /** Offset where the data starts in the disk. */
176 uint64_t offStartInVDisk;
177 /** Size of the data area. */
178 uint64_t cbData;
179 /** Flags for special treatment, see VDISKRAW_XXX. */
180 uint32_t uFlags;
181} VDISKRAWPARTDESC, *PVDISKRAWPARTDESC;
182
183/**
184 * Auxiliary data structure for difference between GPT and MBR disks.
185 */
186typedef enum VDISKPARTTYPE
187{
188 VDISKPARTTYPE_MBR = 0,
189 VDISKPARTTYPE_GPT
190} VDISKPARTTYPE;
191
192/**
193 * Auxiliary data structure for creating raw disks.
194 */
195typedef struct VDISKRAW
196{
197 /** Signature for structure. Must be 'R', 'A', 'W', '\\0'. Actually a trick
198 * to make logging of the comment string produce sensible results. */
199 char szSignature[4];
200 /** Flags for special treatment, see VDISKRAW_XXX. */
201 uint32_t uFlags;
202 /** Filename for the raw disk. Ignored for partitioned raw disks.
203 * For Linux e.g. /dev/sda, and for Windows e.g. //./PhysicalDisk0. */
204 char *pszRawDisk;
205 /** Partitioning type of the disk */
206 VDISKPARTTYPE enmPartitioningType;
207 /** Number of entries in the partition descriptor array. */
208 uint32_t cPartDescs;
209 /** Pointer to the partition descriptor array. */
210 PVDISKRAWPARTDESC pPartDescs;
211} VDISKRAW, *PVDISKRAW;
212
213
214/** @name VBox HDD container image open mode flags
215 * @{
216 */
217/** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
218#define VD_OPEN_FLAGS_NORMAL 0
219/** Open image in read-only mode with sharing access with others. */
220#define VD_OPEN_FLAGS_READONLY RT_BIT(0)
221/** Honor zero block writes instead of ignoring them whenever possible.
222 * This is not supported by all formats. It is silently ignored in this case. */
223#define VD_OPEN_FLAGS_HONOR_ZEROES RT_BIT(1)
224/** Honor writes of the same data instead of ignoring whenever possible.
225 * This is handled generically, and is only meaningful for differential image
226 * formats. It is silently ignored otherwise. */
227#define VD_OPEN_FLAGS_HONOR_SAME RT_BIT(2)
228/** Do not perform the base/diff image check on open. This does NOT imply
229 * opening the image as readonly (would break e.g. adding UUIDs to VMDK files
230 * created by other products). Images opened with this flag should only be
231 * used for querying information, and nothing else. */
232#define VD_OPEN_FLAGS_INFO RT_BIT(3)
233/** Open image for asynchronous access. Only available if VD_CAP_ASYNC_IO is
234 * set. VDOpen fails with VERR_NOT_SUPPORTED if this operation is not supported for
235 * this kind of image. */
236#define VD_OPEN_FLAGS_ASYNC_IO RT_BIT(4)
237/** Allow sharing of the image for writable images. May be ignored if the
238 * format backend doesn't support this type of concurrent access. */
239#define VD_OPEN_FLAGS_SHAREABLE RT_BIT(5)
240/** Ask the backend to switch to sequential accesses if possible. Opening
241 * will not fail if it cannot do this, the flag will be simply ignored. */
242#define VD_OPEN_FLAGS_SEQUENTIAL RT_BIT(6)
243/** Allow the discard operation if supported. Only available if VD_CAP_DISCARD
244 * is set. VDOpen fails with VERR_VD_DISCARD_NOT_SUPPORTED if discarding is not
245 * supported. */
246#define VD_OPEN_FLAGS_DISCARD RT_BIT(7)
247/** Ignore all flush requests to workaround certain filesystems which are slow
248 * when writing a lot of cached data to the medium.
249 * Use with extreme care as a host crash can result in completely corrupted and
250 * unusable images.
251 */
252#define VD_OPEN_FLAGS_IGNORE_FLUSH RT_BIT(8)
253/**
254 * Return VINF_VD_NEW_ZEROED_BLOCK for reads from unallocated blocks.
255 * The caller who uses the flag has to make sure that the read doesn't cross
256 * a block boundary. Because the block size can differ between images reading one
257 * sector at a time is the safest solution.
258 */
259#define VD_OPEN_FLAGS_INFORM_ABOUT_ZERO_BLOCKS RT_BIT(9)
260/**
261 * Don't do unnecessary consistency checks when opening the image.
262 * Only valid when the image is opened in readonly because inconsistencies
263 * can lead to corrupted images in read-write mode.
264 */
265#define VD_OPEN_FLAGS_SKIP_CONSISTENCY_CHECKS RT_BIT(10)
266/** Mask of valid flags. */
267#define VD_OPEN_FLAGS_MASK (VD_OPEN_FLAGS_NORMAL | VD_OPEN_FLAGS_READONLY | VD_OPEN_FLAGS_HONOR_ZEROES | VD_OPEN_FLAGS_HONOR_SAME | VD_OPEN_FLAGS_INFO | VD_OPEN_FLAGS_ASYNC_IO | VD_OPEN_FLAGS_SHAREABLE | VD_OPEN_FLAGS_SEQUENTIAL | VD_OPEN_FLAGS_DISCARD | VD_OPEN_FLAGS_IGNORE_FLUSH | VD_OPEN_FLAGS_INFORM_ABOUT_ZERO_BLOCKS | VD_OPEN_FLAGS_SKIP_CONSISTENCY_CHECKS)
268/** @}*/
269
270/** @name VBox HDD container filter flags
271 * @{
272 */
273/** The filter is applied during writes. */
274#define VD_FILTER_FLAGS_WRITE RT_BIT(0)
275/** The filter is applied during reads. */
276#define VD_FILTER_FLAGS_READ RT_BIT(1)
277/** Open the filter in info mode. */
278#define VD_FILTER_FLAGS_INFO RT_BIT(2)
279/** Default set of filter flags. */
280#define VD_FILTER_FLAGS_DEFAULT (VD_FILTER_FLAGS_WRITE | VD_FILTER_FLAGS_READ)
281/** Mask of valid flags. */
282#define VD_FILTER_FLAGS_MASK (VD_FILTER_FLAGS_WRITE | VD_FILTER_FLAGS_READ | VD_FILTER_FLAGS_INFO)
283/** @} */
284
285/**
286 * Helper functions to handle open flags.
287 */
288
289/**
290 * Translate VD_OPEN_FLAGS_* to RTFile open flags.
291 *
292 * @return RTFile open flags.
293 * @param fOpenFlags VD_OPEN_FLAGS_* open flags.
294 * @param fCreate Flag that the file should be created.
295 */
296DECLINLINE(uint32_t) VDOpenFlagsToFileOpenFlags(unsigned fOpenFlags, bool fCreate)
297{
298 uint32_t fOpen;
299 AssertMsg(!(fOpenFlags & VD_OPEN_FLAGS_READONLY) || !fCreate, ("Image can't be opened readonly while being created\n"));
300
301 if (fOpenFlags & VD_OPEN_FLAGS_READONLY)
302 fOpen = RTFILE_O_READ | RTFILE_O_DENY_NONE;
303 else
304 {
305 fOpen = RTFILE_O_READWRITE;
306
307 if (fOpenFlags & VD_OPEN_FLAGS_SHAREABLE)
308 fOpen |= RTFILE_O_DENY_NONE;
309 else
310 fOpen |= RTFILE_O_DENY_WRITE;
311 }
312
313 if (!fCreate)
314 fOpen |= RTFILE_O_OPEN;
315 else
316 fOpen |= RTFILE_O_CREATE | RTFILE_O_NOT_CONTENT_INDEXED;
317
318 return fOpen;
319}
320
321
322/** @name VBox HDD container backend capability flags
323 * @{
324 */
325/** Supports UUIDs as expected by VirtualBox code. */
326#define VD_CAP_UUID RT_BIT(0)
327/** Supports creating fixed size images, allocating all space instantly. */
328#define VD_CAP_CREATE_FIXED RT_BIT(1)
329/** Supports creating dynamically growing images, allocating space on demand. */
330#define VD_CAP_CREATE_DYNAMIC RT_BIT(2)
331/** Supports creating images split in chunks of a bit less than 2GBytes. */
332#define VD_CAP_CREATE_SPLIT_2G RT_BIT(3)
333/** Supports being used as differencing image format backend. */
334#define VD_CAP_DIFF RT_BIT(4)
335/** Supports asynchronous I/O operations for at least some configurations. */
336#define VD_CAP_ASYNC RT_BIT(5)
337/** The backend operates on files. The caller needs to know to handle the
338 * location appropriately. */
339#define VD_CAP_FILE RT_BIT(6)
340/** The backend uses the config interface. The caller needs to know how to
341 * provide the mandatory configuration parts this way. */
342#define VD_CAP_CONFIG RT_BIT(7)
343/** The backend uses the network stack interface. The caller has to provide
344 * the appropriate interface. */
345#define VD_CAP_TCPNET RT_BIT(8)
346/** The backend supports VFS (virtual filesystem) functionality since it uses
347 * VDINTERFACEIO exclusively for all file operations. */
348#define VD_CAP_VFS RT_BIT(9)
349/** The backend supports the discard operation. */
350#define VD_CAP_DISCARD RT_BIT(10)
351/** This is a frequently used backend. */
352#define VD_CAP_PREFERRED RT_BIT(11)
353/** @}*/
354
355/** @name Configuration interface key handling flags.
356 * @{
357 */
358/** Mandatory config key. Not providing a value for this key will cause
359 * the backend to fail. */
360#define VD_CFGKEY_MANDATORY RT_BIT(0)
361/** Expert config key. Not showing it by default in the GUI is is probably
362 * a good idea, as the average user won't understand it easily. */
363#define VD_CFGKEY_EXPERT RT_BIT(1)
364/** Key only need at media creation, not to be retained in registry.
365 * Should not be exposed in the GUI */
366#define VD_CFGKEY_CREATEONLY RT_BIT(2)
367/** @}*/
368
369
370/**
371 * Configuration value type for configuration information interface.
372 */
373typedef enum VDCFGVALUETYPE
374{
375 /** Integer value. */
376 VDCFGVALUETYPE_INTEGER = 1,
377 /** String value. */
378 VDCFGVALUETYPE_STRING,
379 /** Bytestring value. */
380 VDCFGVALUETYPE_BYTES
381} VDCFGVALUETYPE;
382
383
384/**
385 * Structure describing configuration keys required/supported by a backend
386 * through the config interface.
387 */
388typedef struct VDCONFIGINFO
389{
390 /** Key name of the configuration. */
391 const char *pszKey;
392 /** Pointer to default value (descriptor). NULL if no useful default value
393 * can be specified. */
394 const char *pszDefaultValue;
395 /** Value type for this key. */
396 VDCFGVALUETYPE enmValueType;
397 /** Key handling flags (a combination of VD_CFGKEY_* flags). */
398 uint64_t uKeyFlags;
399} VDCONFIGINFO;
400
401/** Pointer to structure describing configuration keys. */
402typedef VDCONFIGINFO *PVDCONFIGINFO;
403
404/** Pointer to const structure describing configuration keys. */
405typedef const VDCONFIGINFO *PCVDCONFIGINFO;
406
407/**
408 * Structure describing a file extension.
409 */
410typedef struct VDFILEEXTENSION
411{
412 /** Pointer to the NULL-terminated string containing the extension. */
413 const char *pszExtension;
414 /** The device type the extension supports. */
415 VDTYPE enmType;
416} VDFILEEXTENSION;
417
418/** Pointer to a structure describing a file extension. */
419typedef VDFILEEXTENSION *PVDFILEEXTENSION;
420
421/** Pointer to a const structure describing a file extension. */
422typedef const VDFILEEXTENSION *PCVDFILEEXTENSION;
423
424/**
425 * Data structure for returning a list of backend capabilities.
426 */
427typedef struct VDBACKENDINFO
428{
429 /** Name of the backend. Must be unique even with case insensitive comparison. */
430 const char *pszBackend;
431 /** Capabilities of the backend (a combination of the VD_CAP_* flags). */
432 uint64_t uBackendCaps;
433 /** Pointer to a NULL-terminated array of strings, containing the supported
434 * file extensions. Note that some backends do not work on files, so this
435 * pointer may just contain NULL. */
436 PCVDFILEEXTENSION paFileExtensions;
437 /** Pointer to an array of structs describing each supported config key.
438 * Terminated by a NULL config key. Note that some backends do not support
439 * the configuration interface, so this pointer may just contain NULL.
440 * Mandatory if the backend sets VD_CAP_CONFIG. */
441 PCVDCONFIGINFO paConfigInfo;
442 /** Returns a human readable hard disk location string given a
443 * set of hard disk configuration keys. The returned string is an
444 * equivalent of the full file path for image-based hard disks.
445 * Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
446 DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
447 /** Returns a human readable hard disk name string given a
448 * set of hard disk configuration keys. The returned string is an
449 * equivalent of the file name part in the full file path for
450 * image-based hard disks. Mandatory for backends with no
451 * VD_CAP_FILE and NULL otherwise. */
452 DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
453} VDBACKENDINFO, *PVDBACKENDINFO;
454
455/**
456 * Data structure for returning a list of filter capabilities.
457 */
458typedef struct VDFILTERINFO
459{
460 /** Name of the filter. Must be unique even with case insensitive comparison. */
461 const char *pszFilter;
462 /** Pointer to an array of structs describing each supported config key.
463 * Terminated by a NULL config key. Note that some filters do not support
464 * the configuration interface, so this pointer may just contain NULL. */
465 PCVDCONFIGINFO paConfigInfo;
466} VDFILTERINFO, *PVDFILTERINFO;
467
468
469/**
470 * Request completion callback for the async read/write API.
471 */
472typedef DECLCALLBACKTYPE(void, FNVDASYNCTRANSFERCOMPLETE,(void *pvUser1, void *pvUser2, int rcReq));
473/** Pointer to a transfer compelte callback. */
474typedef FNVDASYNCTRANSFERCOMPLETE *PFNVDASYNCTRANSFERCOMPLETE;
475
476/**
477 * VD Container main structure.
478 */
479/* Forward declaration, VDISK structure is visible only inside VD module. */
480struct VDISK;
481typedef struct VDISK VDISK;
482typedef VDISK *PVDISK;
483
484/**
485 * Initializes HDD backends.
486 *
487 * @returns VBox status code.
488 */
489VBOXDDU_DECL(int) VDInit(void);
490
491/**
492 * Destroys loaded HDD backends.
493 *
494 * @returns VBox status code.
495 */
496VBOXDDU_DECL(int) VDShutdown(void);
497
498/**
499 * Loads a single plugin given by filename.
500 *
501 * @returns VBox status code.
502 * @param pszFilename The plugin filename to load.
503 */
504VBOXDDU_DECL(int) VDPluginLoadFromFilename(const char *pszFilename);
505
506/**
507 * Load all plugins from a given path.
508 *
509 * @returns VBox statuse code.
510 * @param pszPath The path to load plugins from.
511 */
512VBOXDDU_DECL(int) VDPluginLoadFromPath(const char *pszPath);
513
514/**
515 * Unloads a single plugin given by filename.
516 *
517 * @returns VBox status code.
518 * @param pszFilename The plugin filename to unload.
519 */
520VBOXDDU_DECL(int) VDPluginUnloadFromFilename(const char *pszFilename);
521
522/**
523 * Unload all plugins from a given path.
524 *
525 * @returns VBox statuse code.
526 * @param pszPath The path to unload plugins from.
527 */
528VBOXDDU_DECL(int) VDPluginUnloadFromPath(const char *pszPath);
529
530/**
531 * Lists all HDD backends and their capabilities in a caller-provided buffer.
532 *
533 * @return VBox status code.
534 * VERR_BUFFER_OVERFLOW if not enough space is passed.
535 * @param cEntriesAlloc Number of list entries available.
536 * @param pEntries Pointer to array for the entries.
537 * @param pcEntriesUsed Number of entries returned.
538 */
539VBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
540 unsigned *pcEntriesUsed);
541
542/**
543 * Lists the capabilities of a backend identified by its name.
544 *
545 * @return VBox status code.
546 * @param pszBackend The backend name (case insensitive).
547 * @param pEntry Pointer to an entry.
548 */
549VBOXDDU_DECL(int) VDBackendInfoOne(const char *pszBackend, PVDBACKENDINFO pEntry);
550
551/**
552 * Lists all filters and their capabilities in a caller-provided buffer.
553 *
554 * @return VBox status code.
555 * VERR_BUFFER_OVERFLOW if not enough space is passed.
556 * @param cEntriesAlloc Number of list entries available.
557 * @param pEntries Pointer to array for the entries.
558 * @param pcEntriesUsed Number of entries returned.
559 */
560VBOXDDU_DECL(int) VDFilterInfo(unsigned cEntriesAlloc, PVDFILTERINFO pEntries,
561 unsigned *pcEntriesUsed);
562
563/**
564 * Lists the capabilities of a filter identified by its name.
565 *
566 * @return VBox status code.
567 * @param pszFilter The filter name (case insensitive).
568 * @param pEntry Pointer to an entry.
569 */
570VBOXDDU_DECL(int) VDFilterInfoOne(const char *pszFilter, PVDFILTERINFO pEntry);
571
572/**
573 * Allocates and initializes an empty HDD container.
574 * No image files are opened.
575 *
576 * @return VBox status code.
577 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
578 * @param enmType Type of the image container.
579 * @param ppDisk Where to store the reference to HDD container.
580 */
581VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfsDisk, VDTYPE enmType, PVDISK *ppDisk);
582
583/**
584 * Destroys HDD container.
585 * If container has opened image files they will be closed.
586 *
587 * @return VBox status code.
588 * @param pDisk Pointer to HDD container.
589 */
590VBOXDDU_DECL(int) VDDestroy(PVDISK pDisk);
591
592/**
593 * Try to get the backend name which can use this image.
594 *
595 * @return VBox status code.
596 * VINF_SUCCESS if a plugin was found.
597 * ppszFormat contains the string which can be used as backend name.
598 * VERR_NOT_SUPPORTED if no backend was found.
599 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
600 * @param pVDIfsImage Pointer to the per-image VD interface list.
601 * @param pszFilename Name of the image file for which the backend is queried.
602 * @param enmDesiredType The desired image type, VDTYPE_INVALID if anything goes.
603 * @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
604 * The returned pointer must be freed using RTStrFree().
605 * @param penmType Where to store the type of the image.
606 */
607VBOXDDU_DECL(int) VDGetFormat(PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
608 const char *pszFilename, VDTYPE enmDesiredType,
609 char **ppszFormat, VDTYPE *penmType);
610
611/**
612 * Opens an image file.
613 *
614 * The first opened image file in HDD container must have a base image type,
615 * others (next opened images) must be differencing or undo images.
616 * Linkage is checked for differencing image to be consistent with the previously opened image.
617 * When another differencing image is opened and the last image was opened in read/write access
618 * mode, then the last image is reopened in read-only with deny write sharing mode. This allows
619 * other processes to use images in read-only mode too.
620 *
621 * Note that the image is opened in read-only mode if a read/write open is not possible.
622 * Use VDIsReadOnly to check open mode.
623 *
624 * @return VBox status code.
625 * @param pDisk Pointer to HDD container.
626 * @param pszBackend Name of the image file backend to use (case insensitive).
627 * @param pszFilename Name of the image file to open.
628 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
629 * @param pVDIfsImage Pointer to the per-image VD interface list.
630 */
631VBOXDDU_DECL(int) VDOpen(PVDISK pDisk, const char *pszBackend,
632 const char *pszFilename, unsigned uOpenFlags,
633 PVDINTERFACE pVDIfsImage);
634
635/**
636 * Opens a cache image.
637 *
638 * @return VBox status code.
639 * @param pDisk Pointer to the HDD container which should use the cache image.
640 * @param pszBackend Name of the cache file backend to use (case insensitive).
641 * @param pszFilename Name of the cache image to open.
642 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
643 * @param pVDIfsCache Pointer to the per-cache VD interface list.
644 */
645VBOXDDU_DECL(int) VDCacheOpen(PVDISK pDisk, const char *pszBackend,
646 const char *pszFilename, unsigned uOpenFlags,
647 PVDINTERFACE pVDIfsCache);
648
649/**
650 * Adds a filter to the disk.
651 *
652 * @returns VBox status code.
653 * @param pDisk Pointer to the HDD container which should use the filter.
654 * @param pszFilter Name of the filter backend to use (case insensitive).
655 * @param fFlags Flags which apply to the filter, combination of VD_FILTER_FLAGS_*
656 * defines.
657 * @param pVDIfsFilter Pointer to the per-filter VD interface list.
658 */
659VBOXDDU_DECL(int) VDFilterAdd(PVDISK pDisk, const char *pszFilter, uint32_t fFlags,
660 PVDINTERFACE pVDIfsFilter);
661
662/**
663 * Creates and opens a new base image file.
664 *
665 * @return VBox status code.
666 * @param pDisk Pointer to HDD container.
667 * @param pszBackend Name of the image file backend to use (case insensitive).
668 * @param pszFilename Name of the image file to create.
669 * @param cbSize Image size in bytes.
670 * @param uImageFlags Flags specifying special image features.
671 * @param pszComment Pointer to image comment. NULL is ok.
672 * @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
673 * @param pLCHSGeometry Pointer to logical disk geometry <= (x,255,63). Not NULL.
674 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
675 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
676 * @param pVDIfsImage Pointer to the per-image VD interface list.
677 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
678 */
679VBOXDDU_DECL(int) VDCreateBase(PVDISK pDisk, const char *pszBackend,
680 const char *pszFilename, uint64_t cbSize,
681 unsigned uImageFlags, const char *pszComment,
682 PCVDGEOMETRY pPCHSGeometry,
683 PCVDGEOMETRY pLCHSGeometry,
684 PCRTUUID pUuid, unsigned uOpenFlags,
685 PVDINTERFACE pVDIfsImage,
686 PVDINTERFACE pVDIfsOperation);
687
688/**
689 * Creates and opens a new differencing image file in HDD container.
690 * See comments for VDOpen function about differencing images.
691 *
692 * @return VBox status code.
693 * @param pDisk Pointer to HDD container.
694 * @param pszBackend Name of the image file backend to use (case insensitive).
695 * @param pszFilename Name of the differencing image file to create.
696 * @param uImageFlags Flags specifying special image features.
697 * @param pszComment Pointer to image comment. NULL is ok.
698 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
699 * @param pParentUuid New parent UUID of the image. If NULL, the UUID is queried automatically.
700 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
701 * @param pVDIfsImage Pointer to the per-image VD interface list.
702 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
703 */
704VBOXDDU_DECL(int) VDCreateDiff(PVDISK pDisk, const char *pszBackend,
705 const char *pszFilename, unsigned uImageFlags,
706 const char *pszComment, PCRTUUID pUuid,
707 PCRTUUID pParentUuid, unsigned uOpenFlags,
708 PVDINTERFACE pVDIfsImage,
709 PVDINTERFACE pVDIfsOperation);
710
711/**
712 * Creates and opens new cache image file in HDD container.
713 *
714 * @return VBox status code.
715 * @param pDisk Name of the cache file backend to use (case insensitive).
716 * @param pszBackend Name of the image file backend to use (case insensitive).
717 * @param pszFilename Name of the differencing cache file to create.
718 * @param cbSize Maximum size of the cache.
719 * @param uImageFlags Flags specifying special cache features.
720 * @param pszComment Pointer to image comment. NULL is ok.
721 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
722 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
723 * @param pVDIfsCache Pointer to the per-cache VD interface list.
724 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
725 */
726VBOXDDU_DECL(int) VDCreateCache(PVDISK pDisk, const char *pszBackend,
727 const char *pszFilename, uint64_t cbSize,
728 unsigned uImageFlags, const char *pszComment,
729 PCRTUUID pUuid, unsigned uOpenFlags,
730 PVDINTERFACE pVDIfsCache, PVDINTERFACE pVDIfsOperation);
731
732/**
733 * Merges two images (not necessarily with direct parent/child relationship).
734 * As a side effect the source image and potentially the other images which
735 * are also merged to the destination are deleted from both the disk and the
736 * images in the HDD container.
737 *
738 * @return VBox status code.
739 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
740 * @param pDisk Pointer to HDD container.
741 * @param nImageFrom Image number to merge from, counts from 0. 0 is always base image of container.
742 * @param nImageTo Image number to merge to, counts from 0. 0 is always base image of container.
743 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
744 */
745VBOXDDU_DECL(int) VDMerge(PVDISK pDisk, unsigned nImageFrom,
746 unsigned nImageTo, PVDINTERFACE pVDIfsOperation);
747
748/**
749 * Copies an image from one HDD container to another - extended version.
750 *
751 * The copy is opened in the target HDD container. It is possible to convert
752 * between different image formats, because the backend for the destination may
753 * be different from the source. If both the source and destination reference
754 * the same HDD container, then the image is moved (by copying/deleting or
755 * renaming) to the new location. The source container is unchanged if the move
756 * operation fails, otherwise the image at the new location is opened in the
757 * same way as the old one was.
758 *
759 * @note The read/write accesses across disks are not synchronized, just the
760 * accesses to each disk. Once there is a use case which requires a defined
761 * read/write behavior in this situation this needs to be extended.
762 *
763 * @return VBox status code.
764 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
765 *
766 * @param pDiskFrom Pointer to source HDD container.
767 * @param nImageFrom Image number to copy from, counts from 0. 0 is always base image of container.
768 * @param pDiskTo Pointer to destination HDD container.
769 * @param nImageTo Image number to copy to, counts from 0. 0 is always base image of container.
770 * @param pszBackend Name of the image file backend to use (may be NULL
771 * to use the same as the source, case insensitive).
772 * @param pszFilename New name of the image (may be NULL to specify that
773 * the copy destination is the destination container,
774 * or if pDiskFrom == pDiskTo, i.e. when moving).
775 * @param fMoveByRename If true, attempt to perform a move by renaming (if
776 * successful the new size is ignored).
777 * @param cbSize New image size (0 means leave unchanged).
778 * @param nImageFromSame The number of the last image in the source chain
779 * having the same content as the image in the
780 * destination chain given by nImageToSame or
781 * VD_IMAGE_CONTENT_UNKNOWN to indicate that the
782 * content of both containers is unknown. See the
783 * notes for further information.
784 * @param nImageToSame The number of the last image in the destination
785 * chain having the same content as the image in the
786 * source chain given by nImageFromSame or
787 * VD_IMAGE_CONTENT_UNKNOWN to indicate that the
788 * content of both containers is unknown. See the notes
789 * for further information.
790 * @param uImageFlags Flags specifying special destination image features.
791 * @param pDstUuid New UUID of the destination image. If NULL, a new
792 * UUID is created. This parameter is used if and only
793 * if a true copy is created. In all rename/move cases
794 * or copy to existing image cases the modification
795 * UUIDs are copied over.
796 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
797 * Only used if the destination image is created.
798 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
799 * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
800 * destination image.
801 * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
802 * for the destination operation.
803 *
804 * @note Using nImageFromSame and nImageToSame can lead to a significant speedup
805 * when copying an image but can also lead to a corrupted copy if used
806 * incorrectly. It is mainly useful when cloning a chain of images and it
807 * is known that the virtual disk content of the two chains is exactly the
808 * same upto a certain image. Example:
809 * Imagine the chain of images which consist of a base and one diff
810 * image. Copying the chain starts with the base image. When copying
811 * the first diff image VDCopy() will read the data from the diff of
812 * the source chain and probably from the base image again in case the
813 * diff doesn't has data for the block. However the block will be
814 * optimized away because VDCopy() reads data from the base image of
815 * the destination chain compares the to and suppresses the write
816 * because the data is unchanged. For a lot of diff images this will be
817 * a huge waste of I/O bandwidth if the diff images contain only few
818 * changes. Because it is known that the base image of the source and
819 * the destination chain have the same content it is enough to check
820 * the diff image for changed data and copy it to the destination diff
821 * image which is achieved with nImageFromSame and nImageToSame.
822 * Setting both to 0 can suppress a lot of I/O.
823 */
824VBOXDDU_DECL(int) VDCopyEx(PVDISK pDiskFrom, unsigned nImageFrom, PVDISK pDiskTo, unsigned nImageTo,
825 const char *pszBackend, const char *pszFilename,
826 bool fMoveByRename, uint64_t cbSize,
827 unsigned nImageFromSame, unsigned nImageToSame,
828 unsigned uImageFlags, PCRTUUID pDstUuid,
829 unsigned uOpenFlags, PVDINTERFACE pVDIfsOperation,
830 PVDINTERFACE pDstVDIfsImage,
831 PVDINTERFACE pDstVDIfsOperation);
832
833/**
834 * Copies an image from one HDD container to another.
835 * The copy is opened in the target HDD container.
836 * It is possible to convert between different image formats, because the
837 * backend for the destination may be different from the source.
838 * If both the source and destination reference the same HDD container,
839 * then the image is moved (by copying/deleting or renaming) to the new location.
840 * The source container is unchanged if the move operation fails, otherwise
841 * the image at the new location is opened in the same way as the old one was.
842 *
843 * @note The read/write accesses across disks are not synchronized, just the
844 * accesses to each disk. Once there is a use case which requires a defined
845 * read/write behavior in this situation this needs to be extended.
846 *
847 * @return VBox status code.
848 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
849 * @param pDiskFrom Pointer to source HDD container.
850 * @param nImage Image number, counts from 0. 0 is always base image of container.
851 * @param pDiskTo Pointer to destination HDD container.
852 * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
853 * @param pszFilename New name of the image (may be NULL to specify that the
854 * copy destination is the destination container, or
855 * if pDiskFrom == pDiskTo, i.e. when moving).
856 * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
857 * @param cbSize New image size (0 means leave unchanged).
858 * @param uImageFlags Flags specifying special destination image features.
859 * @param pDstUuid New UUID of the destination image. If NULL, a new UUID is created.
860 * This parameter is used if and only if a true copy is created.
861 * In all rename/move cases or copy to existing image cases the modification UUIDs are copied over.
862 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
863 * Only used if the destination image is created.
864 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
865 * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
866 * destination image.
867 * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
868 * for the destination operation.
869 */
870VBOXDDU_DECL(int) VDCopy(PVDISK pDiskFrom, unsigned nImage, PVDISK pDiskTo,
871 const char *pszBackend, const char *pszFilename,
872 bool fMoveByRename, uint64_t cbSize,
873 unsigned uImageFlags, PCRTUUID pDstUuid,
874 unsigned uOpenFlags, PVDINTERFACE pVDIfsOperation,
875 PVDINTERFACE pDstVDIfsImage,
876 PVDINTERFACE pDstVDIfsOperation);
877
878/**
879 * Optimizes the storage consumption of an image. Typically the unused blocks
880 * have to be wiped with zeroes to achieve a substantial reduced storage use.
881 * Another optimization done is reordering the image blocks, which can provide
882 * a significant performance boost, as reads and writes tend to use less random
883 * file offsets.
884 *
885 * @note Compaction is treated as a single operation with regard to thread
886 * synchronization, which means that it potentially blocks other activities for
887 * a long time. The complexity of compaction would grow even more if concurrent
888 * accesses have to be handled.
889 *
890 * @return VBox status code.
891 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
892 * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
893 * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but
894 * this isn't supported yet.
895 * @param pDisk Pointer to HDD container.
896 * @param nImage Image number, counts from 0. 0 is always base image of container.
897 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
898 */
899VBOXDDU_DECL(int) VDCompact(PVDISK pDisk, unsigned nImage, PVDINTERFACE pVDIfsOperation);
900
901/**
902 * Resizes the given disk image to the given size. It is OK if there are
903 * multiple images open in the container. In this case the last disk image
904 * will be resized.
905 *
906 * @return VBox status
907 * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
908 * @return VERR_NOT_SUPPORTED if this kind of image can't be compacted.
909 *
910 * @param pDisk Pointer to the HDD container.
911 * @param cbSize New size of the image.
912 * @param pPCHSGeometry Pointer to the new physical disk geometry <= (16383,16,63). Not NULL.
913 * @param pLCHSGeometry Pointer to the new logical disk geometry <= (x,255,63). Not NULL.
914 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
915 */
916VBOXDDU_DECL(int) VDResize(PVDISK pDisk, uint64_t cbSize,
917 PCVDGEOMETRY pPCHSGeometry,
918 PCVDGEOMETRY pLCHSGeometry,
919 PVDINTERFACE pVDIfsOperation);
920
921/**
922 * Prepares the given disk for use by the added filters. This applies to all
923 * opened images in the chain which might be opened read/write temporary.
924 *
925 * @return VBox status code.
926 *
927 * @param pDisk Pointer to the HDD container.
928 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
929 */
930VBOXDDU_DECL(int) VDPrepareWithFilters(PVDISK pDisk, PVDINTERFACE pVDIfsOperation);
931
932/**
933 * Closes the last opened image file in HDD container.
934 * If previous image file was opened in read-only mode (the normal case) and
935 * the last opened image is in read-write mode then the previous image will be
936 * reopened in read/write mode.
937 *
938 * @return VBox status code.
939 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
940 * @param pDisk Pointer to HDD container.
941 * @param fDelete If true, delete the image from the host disk.
942 */
943VBOXDDU_DECL(int) VDClose(PVDISK pDisk, bool fDelete);
944
945/**
946 * Removes the last added filter in the HDD container from the specified chain.
947 *
948 * @return VBox status code.
949 * @retval VERR_VD_NOT_OPENED if no filter is present for the disk.
950 * @param pDisk Pointer to HDD container.
951 * @param fFlags Combination of VD_FILTER_FLAGS_* defines.
952 */
953VBOXDDU_DECL(int) VDFilterRemove(PVDISK pDisk, uint32_t fFlags);
954
955/**
956 * Closes the currently opened cache image file in HDD container.
957 *
958 * @return VBox status code.
959 * @return VERR_VD_NOT_OPENED if no cache is opened in HDD container.
960 * @param pDisk Pointer to HDD container.
961 * @param fDelete If true, delete the image from the host disk.
962 */
963VBOXDDU_DECL(int) VDCacheClose(PVDISK pDisk, bool fDelete);
964
965/**
966 * Closes all opened image files in HDD container.
967 *
968 * @return VBox status code.
969 * @param pDisk Pointer to HDD container.
970 */
971VBOXDDU_DECL(int) VDCloseAll(PVDISK pDisk);
972
973/**
974 * Removes all filters of the given HDD container.
975 *
976 * @return VBox status code.
977 * @param pDisk Pointer to HDD container.
978 */
979VBOXDDU_DECL(int) VDFilterRemoveAll(PVDISK pDisk);
980
981/**
982 * Read data from virtual HDD.
983 *
984 * @return VBox status code.
985 * @retval VERR_VD_NOT_OPENED if no image is opened in HDD container.
986 * @param pDisk Pointer to HDD container.
987 * @param uOffset Offset of first reading byte from start of disk.
988 * Must be aligned to a sector boundary.
989 * @param pvBuf Pointer to buffer for reading data.
990 * @param cbRead Number of bytes to read.
991 * Must be aligned to a sector boundary.
992 */
993VBOXDDU_DECL(int) VDRead(PVDISK pDisk, uint64_t uOffset, void *pvBuf, size_t cbRead);
994
995/**
996 * Write data to virtual HDD.
997 *
998 * @return VBox status code.
999 * @retval VERR_VD_NOT_OPENED if no image is opened in HDD container.
1000 * @param pDisk Pointer to HDD container.
1001 * @param uOffset Offset of first writing byte from start of disk.
1002 * Must be aligned to a sector boundary.
1003 * @param pvBuf Pointer to buffer for writing data.
1004 * @param cbWrite Number of bytes to write.
1005 * Must be aligned to a sector boundary.
1006 */
1007VBOXDDU_DECL(int) VDWrite(PVDISK pDisk, uint64_t uOffset, const void *pvBuf, size_t cbWrite);
1008
1009/**
1010 * Make sure the on disk representation of a virtual HDD is up to date.
1011 *
1012 * @return VBox status code.
1013 * @retval VERR_VD_NOT_OPENED if no image is opened in HDD container.
1014 * @param pDisk Pointer to HDD container.
1015 */
1016VBOXDDU_DECL(int) VDFlush(PVDISK pDisk);
1017
1018/**
1019 * Get number of opened images in HDD container.
1020 *
1021 * @return Number of opened images for HDD container. 0 if no images have been opened.
1022 * @param pDisk Pointer to HDD container.
1023 */
1024VBOXDDU_DECL(unsigned) VDGetCount(PVDISK pDisk);
1025
1026/**
1027 * Get read/write mode of HDD container.
1028 *
1029 * @return Virtual disk ReadOnly status.
1030 * @return true if no image is opened in HDD container.
1031 * @param pDisk Pointer to HDD container.
1032 */
1033VBOXDDU_DECL(bool) VDIsReadOnly(PVDISK pDisk);
1034
1035/**
1036 * Get sector size of an image in HDD container.
1037 *
1038 * @return Virtual disk sector size in bytes.
1039 * @return 0 if image with specified number was not opened.
1040 * @param pDisk Pointer to HDD container.
1041 * @param nImage Image number, counts from 0. 0 is always base image of container.
1042 */
1043VBOXDDU_DECL(uint32_t) VDGetSectorSize(PVDISK pDisk, unsigned nImage);
1044
1045/**
1046 * Get total capacity of an image in HDD container.
1047 *
1048 * @return Virtual disk size in bytes.
1049 * @return 0 if image with specified number was not opened.
1050 * @param pDisk Pointer to HDD container.
1051 * @param nImage Image number, counts from 0. 0 is always base image of container.
1052 */
1053VBOXDDU_DECL(uint64_t) VDGetSize(PVDISK pDisk, unsigned nImage);
1054
1055/**
1056 * Get total file size of an image in HDD container.
1057 *
1058 * @return Virtual disk size in bytes.
1059 * @return 0 if image with specified number was not opened.
1060 * @param pDisk Pointer to HDD container.
1061 * @param nImage Image number, counts from 0. 0 is always base image of container.
1062 */
1063VBOXDDU_DECL(uint64_t) VDGetFileSize(PVDISK pDisk, unsigned nImage);
1064
1065/**
1066 * Get virtual disk PCHS geometry of an image in HDD container.
1067 *
1068 * @return VBox status code.
1069 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1070 * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
1071 * @param pDisk Pointer to HDD container.
1072 * @param nImage Image number, counts from 0. 0 is always base image of container.
1073 * @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
1074 */
1075VBOXDDU_DECL(int) VDGetPCHSGeometry(PVDISK pDisk, unsigned nImage, PVDGEOMETRY pPCHSGeometry);
1076
1077/**
1078 * Store virtual disk PCHS geometry of an image in HDD container.
1079 *
1080 * @return VBox status code.
1081 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1082 * @param pDisk Pointer to HDD container.
1083 * @param nImage Image number, counts from 0. 0 is always base image of container.
1084 * @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
1085 */
1086VBOXDDU_DECL(int) VDSetPCHSGeometry(PVDISK pDisk, unsigned nImage, PCVDGEOMETRY pPCHSGeometry);
1087
1088/**
1089 * Get virtual disk LCHS geometry of an image in HDD container.
1090 *
1091 * @return VBox status code.
1092 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1093 * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
1094 * @param pDisk Pointer to HDD container.
1095 * @param nImage Image number, counts from 0. 0 is always base image of container.
1096 * @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
1097 */
1098VBOXDDU_DECL(int) VDGetLCHSGeometry(PVDISK pDisk, unsigned nImage, PVDGEOMETRY pLCHSGeometry);
1099
1100/**
1101 * Store virtual disk LCHS geometry of an image in HDD container.
1102 *
1103 * @return VBox status code.
1104 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1105 * @param pDisk Pointer to HDD container.
1106 * @param nImage Image number, counts from 0. 0 is always base image of container.
1107 * @param pLCHSGeometry Where to load LCHS geometry from. Not NULL.
1108 */
1109VBOXDDU_DECL(int) VDSetLCHSGeometry(PVDISK pDisk, unsigned nImage, PCVDGEOMETRY pLCHSGeometry);
1110
1111/**
1112 * Queries the available regions of an image in the given VD container.
1113 *
1114 * @return VBox status code.
1115 * @retval VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1116 * @retval VERR_NOT_SUPPORTED if the image backend doesn't support region lists.
1117 * @param pDisk Pointer to HDD container.
1118 * @param nImage Image number, counts from 0. 0 is always base image of container.
1119 * @param fFlags Combination of VD_REGION_LIST_F_* flags.
1120 * @param ppRegionList Where to store the pointer to the region list on success, must be freed
1121 * with VDRegionListFree().
1122 */
1123VBOXDDU_DECL(int) VDQueryRegions(PVDISK pDisk, unsigned nImage, uint32_t fFlags,
1124 PPVDREGIONLIST ppRegionList);
1125
1126/**
1127 * Frees a region list previously queried with VDQueryRegions().
1128 *
1129 * @param pRegionList The region list to free.
1130 */
1131VBOXDDU_DECL(void) VDRegionListFree(PVDREGIONLIST pRegionList);
1132
1133/**
1134 * Get version of image in HDD container.
1135 *
1136 * @return VBox status code.
1137 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1138 * @param pDisk Pointer to HDD container.
1139 * @param nImage Image number, counts from 0. 0 is always base image of container.
1140 * @param puVersion Where to store the image version.
1141 */
1142VBOXDDU_DECL(int) VDGetVersion(PVDISK pDisk, unsigned nImage, unsigned *puVersion);
1143
1144/**
1145 * List the capabilities of image backend in HDD container.
1146 *
1147 * @return VBox status code.
1148 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1149 * @param pDisk Pointer to the HDD container.
1150 * @param nImage Image number, counts from 0. 0 is always base image of container.
1151 * @param pBackendInfo Where to store the backend information.
1152 */
1153VBOXDDU_DECL(int) VDBackendInfoSingle(PVDISK pDisk, unsigned nImage, PVDBACKENDINFO pBackendInfo);
1154
1155/**
1156 * Get flags of image in HDD container.
1157 *
1158 * @return VBox status code.
1159 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1160 * @param pDisk Pointer to HDD container.
1161 * @param nImage Image number, counts from 0. 0 is always base image of container.
1162 * @param puImageFlags Where to store the image flags.
1163 */
1164VBOXDDU_DECL(int) VDGetImageFlags(PVDISK pDisk, unsigned nImage, unsigned *puImageFlags);
1165
1166/**
1167 * Get open flags of image in HDD container.
1168 *
1169 * @return VBox status code.
1170 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1171 * @param pDisk Pointer to HDD container.
1172 * @param nImage Image number, counts from 0. 0 is always base image of container.
1173 * @param puOpenFlags Where to store the image open flags.
1174 */
1175VBOXDDU_DECL(int) VDGetOpenFlags(PVDISK pDisk, unsigned nImage, unsigned *puOpenFlags);
1176
1177/**
1178 * Set open flags of image in HDD container.
1179 * This operation may cause file locking changes and/or files being reopened.
1180 * Note that in case of unrecoverable error all images in HDD container will be closed.
1181 *
1182 * @return VBox status code.
1183 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1184 * @param pDisk Pointer to HDD container.
1185 * @param nImage Image number, counts from 0. 0 is always base image of container.
1186 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1187 */
1188VBOXDDU_DECL(int) VDSetOpenFlags(PVDISK pDisk, unsigned nImage, unsigned uOpenFlags);
1189
1190/**
1191 * Get base filename of image in HDD container. Some image formats use
1192 * other filenames as well, so don't use this for anything but informational
1193 * purposes.
1194 *
1195 * @return VBox status code.
1196 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1197 * @return VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
1198 * @param pDisk Pointer to HDD container.
1199 * @param nImage Image number, counts from 0. 0 is always base image of container.
1200 * @param pszFilename Where to store the image file name.
1201 * @param cbFilename Size of buffer pszFilename points to.
1202 */
1203VBOXDDU_DECL(int) VDGetFilename(PVDISK pDisk, unsigned nImage, char *pszFilename, unsigned cbFilename);
1204
1205/**
1206 * Get the comment line of image in HDD container.
1207 *
1208 * @return VBox status code.
1209 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1210 * @return VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
1211 * @param pDisk Pointer to HDD container.
1212 * @param nImage Image number, counts from 0. 0 is always base image of container.
1213 * @param pszComment Where to store the comment string of image. NULL is ok.
1214 * @param cbComment The size of pszComment buffer. 0 is ok.
1215 */
1216VBOXDDU_DECL(int) VDGetComment(PVDISK pDisk, unsigned nImage, char *pszComment, unsigned cbComment);
1217
1218/**
1219 * Changes the comment line of image in HDD container.
1220 *
1221 * @return VBox status code.
1222 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1223 * @param pDisk Pointer to HDD container.
1224 * @param nImage Image number, counts from 0. 0 is always base image of container.
1225 * @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
1226 */
1227VBOXDDU_DECL(int) VDSetComment(PVDISK pDisk, unsigned nImage, const char *pszComment);
1228
1229/**
1230 * Get UUID of image in HDD container.
1231 *
1232 * @return VBox status code.
1233 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1234 * @param pDisk Pointer to HDD container.
1235 * @param nImage Image number, counts from 0. 0 is always base image of container.
1236 * @param pUuid Where to store the image UUID.
1237 */
1238VBOXDDU_DECL(int) VDGetUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid);
1239
1240/**
1241 * Set the image's UUID. Should not be used by normal applications.
1242 *
1243 * @return VBox status code.
1244 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1245 * @param pDisk Pointer to HDD container.
1246 * @param nImage Image number, counts from 0. 0 is always base image of container.
1247 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
1248 */
1249VBOXDDU_DECL(int) VDSetUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid);
1250
1251/**
1252 * Get last modification UUID of image in HDD container.
1253 *
1254 * @return VBox status code.
1255 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1256 * @param pDisk Pointer to HDD container.
1257 * @param nImage Image number, counts from 0. 0 is always base image of container.
1258 * @param pUuid Where to store the image modification UUID.
1259 */
1260VBOXDDU_DECL(int) VDGetModificationUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid);
1261
1262/**
1263 * Set the image's last modification UUID. Should not be used by normal applications.
1264 *
1265 * @return VBox status code.
1266 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1267 * @param pDisk Pointer to HDD container.
1268 * @param nImage Image number, counts from 0. 0 is always base image of container.
1269 * @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
1270 */
1271VBOXDDU_DECL(int) VDSetModificationUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid);
1272
1273/**
1274 * Get parent UUID of image in HDD container.
1275 *
1276 * @return VBox status code.
1277 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1278 * @param pDisk Pointer to HDD container.
1279 * @param nImage Image number, counts from 0. 0 is always base image of the container.
1280 * @param pUuid Where to store the parent image UUID.
1281 */
1282VBOXDDU_DECL(int) VDGetParentUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid);
1283
1284/**
1285 * Set the image's parent UUID. Should not be used by normal applications.
1286 *
1287 * @return VBox status code.
1288 * @param pDisk Pointer to HDD container.
1289 * @param nImage Image number, counts from 0. 0 is always base image of container.
1290 * @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
1291 */
1292VBOXDDU_DECL(int) VDSetParentUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid);
1293
1294
1295/**
1296 * Debug helper - dumps all opened images in HDD container into the log file.
1297 *
1298 * @param pDisk Pointer to HDD container.
1299 */
1300VBOXDDU_DECL(void) VDDumpImages(PVDISK pDisk);
1301
1302
1303/**
1304 * Discards unused ranges given as a list.
1305 *
1306 * @return VBox status code.
1307 * @param pDisk Pointer to HDD container.
1308 * @param paRanges The array of ranges to discard.
1309 * @param cRanges Number of entries in the array.
1310 *
1311 * @note In contrast to VDCompact() the ranges are always discarded even if they
1312 * appear to contain data. This method is mainly used to implement TRIM support.
1313 */
1314VBOXDDU_DECL(int) VDDiscardRanges(PVDISK pDisk, PCRTRANGE paRanges, unsigned cRanges);
1315
1316
1317/**
1318 * Start an asynchronous read request.
1319 *
1320 * @return VBox status code.
1321 * @param pDisk Pointer to the HDD container.
1322 * @param off The offset of the virtual disk to read from.
1323 * @param cbRead How many bytes to read.
1324 * @param pSgBuf Pointer to the S/G buffer to read into.
1325 * @param pfnComplete Completion callback.
1326 * @param pvUser1 User data which is passed on completion.
1327 * @param pvUser2 User data which is passed on completion.
1328 */
1329VBOXDDU_DECL(int) VDAsyncRead(PVDISK pDisk, uint64_t off, size_t cbRead,
1330 PCRTSGBUF pSgBuf,
1331 PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
1332 void *pvUser1, void *pvUser2);
1333
1334
1335/**
1336 * Start an asynchronous write request.
1337 *
1338 * @return VBox status code.
1339 * @param pDisk Pointer to the HDD container.
1340 * @param off The offset of the virtual disk to write to.
1341 * @param cbWrite How many bytes to write.
1342 * @param pSgBuf Pointer to the S/G buffer to write from.
1343 * @param pfnComplete Completion callback.
1344 * @param pvUser1 User data which is passed on completion.
1345 * @param pvUser2 User data which is passed on completion.
1346 */
1347VBOXDDU_DECL(int) VDAsyncWrite(PVDISK pDisk, uint64_t off, size_t cbWrite,
1348 PCRTSGBUF pSgBuf,
1349 PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
1350 void *pvUser1, void *pvUser2);
1351
1352
1353/**
1354 * Start an asynchronous flush request.
1355 *
1356 * @return VBox status code.
1357 * @param pDisk Pointer to the HDD container.
1358 * @param pfnComplete Completion callback.
1359 * @param pvUser1 User data which is passed on completion.
1360 * @param pvUser2 User data which is passed on completion.
1361 */
1362VBOXDDU_DECL(int) VDAsyncFlush(PVDISK pDisk,
1363 PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
1364 void *pvUser1, void *pvUser2);
1365
1366/**
1367 * Start an asynchronous discard request.
1368 *
1369 * @return VBox status code.
1370 * @param pDisk Pointer to HDD container.
1371 * @param paRanges The array of ranges to discard.
1372 * @param cRanges Number of entries in the array.
1373 * @param pfnComplete Completion callback.
1374 * @param pvUser1 User data which is passed on completion.
1375 * @param pvUser2 User data which is passed on completion.
1376 */
1377VBOXDDU_DECL(int) VDAsyncDiscardRanges(PVDISK pDisk, PCRTRANGE paRanges, unsigned cRanges,
1378 PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
1379 void *pvUser1, void *pvUser2);
1380
1381/**
1382 * Tries to repair a corrupted image.
1383 *
1384 * @return VBox status code.
1385 * @retval VERR_VD_IMAGE_REPAIR_NOT_SUPPORTED if the backend does not support repairing the image.
1386 * @retval VERR_VD_IMAGE_REPAIR_IMPOSSIBLE if the corruption is to severe to repair the image.
1387 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
1388 * @param pVDIfsImage Pointer to the per-image VD interface list.
1389 * @param pszFilename Name of the image file to repair.
1390 * @param pszBackend The backend to use.
1391 * @param fFlags Combination of the VD_REPAIR_* flags.
1392 */
1393VBOXDDU_DECL(int) VDRepair(PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
1394 const char *pszFilename, const char *pszBackend, uint32_t fFlags);
1395
1396/**
1397 * Create a VFS file handle from the given HDD container.
1398 *
1399 * @return VBox status code.
1400 * @param pDisk Pointer to HDD container.
1401 * @param fFlags Combination of the VD_VFSFILE_* flags.
1402 * @param phVfsFile Where to store the handle to the VFS file on
1403 * success.
1404 */
1405VBOXDDU_DECL(int) VDCreateVfsFileFromDisk(PVDISK pDisk, uint32_t fFlags,
1406 PRTVFSFILE phVfsFile);
1407
1408
1409
1410/** @defgroup grp_vd_ifs_def Default implementations for certain VD interfaces.
1411 * @{
1412 */
1413/** Internal per interface instance data. */
1414typedef struct VDIFINSTINT *VDIFINST;
1415/** Pointer to the per instance interface data. */
1416typedef VDIFINST *PVDIFINST;
1417
1418/**
1419 * Creates a new VD TCP/IP interface instance and adds it to the given interface list.
1420 *
1421 * @returns VBox status code.
1422 * @param phTcpNetInst Where to store the TCP/IP interface handle on success.
1423 * @param ppVdIfs Pointer to the VD interface list.
1424 */
1425VBOXDDU_DECL(int) VDIfTcpNetInstDefaultCreate(PVDIFINST phTcpNetInst, PVDINTERFACE *ppVdIfs);
1426
1427/**
1428 * Destroys the given VD TCP/IP interface instance.
1429 *
1430 * @param hTcpNetInst The TCP/IP interface instance handle.
1431 */
1432VBOXDDU_DECL(void) VDIfTcpNetInstDefaultDestroy(VDIFINST hTcpNetInst);
1433/** @} */
1434
1435
1436
1437/** @defgroup grp_vd_ioiter I/O iterator
1438 * @{
1439 */
1440
1441/** Read metadata coming before each main data block addressed in the segment. */
1442#define VD_IOITER_SEG_F_PRE_METADATA RT_BIT_32(0)
1443/** Read the main user data of each addressed block in the segment. */
1444#define VD_IOITER_SEG_F_MAIN_DATA RT_BIT_32(1)
1445/** Read metadata coming after each main data block addressed in the segment. */
1446#define VD_IOITER_SEG_F_POST_METADATA RT_BIT_32(2)
1447/** Read checksum data of each data block addressed in the segment. */
1448#define VD_IOITER_SEG_F_CHKSUM RT_BIT_32(3)
1449/** Read all available data for each addressed block in the segment. */
1450#define VD_IOITER_SEG_F_AVAILABLE RT_BIT_32(4)
1451
1452/** The offset and size members in the segments use byte granularity instead of a
1453 * block address and number of blocks respectively. */
1454#define VDIOITER_F_BYTE_OFFSET_AND_SIZE RT_BIT_32(0)
1455
1456/**
1457 * VD I/O iterator segment.
1458 */
1459typedef struct VDIOITERSEG
1460{
1461 /** Start offset for this segment. */
1462 uint64_t offStartSeg;
1463 /** Size of the segment (bytes or blocks). */
1464 uint64_t cSizeSeg;
1465 /** Flags for this segment, see VD_IOITER_SEG_F_*. */
1466 uint32_t fFlags;
1467} VDIOITERSEG;
1468/** Pointer to a I/O iterator segment. */
1469typedef VDIOITERSEG *PVDIOITERSEG;
1470/** Pointer to a constant I/O iterator segment. */
1471typedef VDIOITERSEG *PCVDIOITERSEG;
1472
1473/** I/O iterator handle. */
1474typedef struct VDIOITERINT *VDIOITER;
1475/** Pointer to a I/O iterator handle. */
1476typedef VDIOITER *PVDIOITER;
1477
1478/**
1479 * Create a new I/O iterator.
1480 *
1481 * @returns VBox status code.
1482 * @param pDisk The disk to create the iterator for.
1483 * @param phVdIoIter Where to store the handle to the I/O iterator on success.
1484 * @param paIoIterSegs The segments for the iterator, can be destroyed after the call.
1485 * @param cIoIterSegs Number of segments.
1486 * @param fFlags Flags for the iterator, see VDIOITER_F_*
1487 */
1488VBOXDDU_DECL(int) VDIoIterCreate(PVDISK pDisk, PVDIOITER phVdIoIter, PCVDIOITERSEG paIoIterSegs,
1489 uint32_t cIoIterSegs, uint32_t fFlags);
1490
1491/**
1492 * Retains the reference count of the given I/O iterator.
1493 *
1494 * @returns New reference count.
1495 * @param hVdIoIter The I/O iterator handle.
1496 */
1497VBOXDDU_DECL(uint32_t) VDIoIterRetain(VDIOITER hVdIoIter);
1498
1499/**
1500 * Releases the reference count of the given I/O iterator.
1501 *
1502 * @returns New reference count, on 0 the iterator is destroyed.
1503 * @param hVdIoIter The I/O iterator handle.
1504 */
1505VBOXDDU_DECL(uint32_t) VDIoIterRelease(VDIOITER hVdIoIter);
1506
1507/**
1508 * Returns the number of segments in the given I/O iterator.
1509 *
1510 * @returns Number of segments.
1511 * @param hVdIoIter The I/O iterator handle.
1512 */
1513VBOXDDU_DECL(uint32_t) VDIoIterGetSegmentCount(VDIOITER hVdIoIter);
1514
1515/**
1516 * Returns the flags of the given I/O iterator.
1517 *
1518 * @returns Flags.
1519 * @param hVdIoIter The I/O iterator handle.
1520 */
1521VBOXDDU_DECL(uint32_t) VDIoIterGetFlags(VDIOITER hVdIoIter);
1522
1523/**
1524 * Queries the properties of the given segment for the given I/O iterator.
1525 *
1526 * @returns VBox status code.
1527 * @param hVdIoIter The I/O iterator handle.
1528 * @param idx The segment index to query.
1529 * @param pSegment Where to store the segment properties on success.
1530 */
1531VBOXDDU_DECL(int) VDIoIterQuerySegment(VDIOITER hVdIoIter, uint32_t idx, PVDIOITERSEG pSegment);
1532
1533/** @} */
1534
1535
1536/** @defgroup grp_vd_io_buf I/O buffer management API.
1537 * @{
1538 */
1539
1540/** VD I/O buffer manager handle. */
1541typedef struct VDIOBUFMGRINT *VDIOBUFMGR;
1542/** Pointer to VD I/O buffer manager handle. */
1543typedef VDIOBUFMGR *PVDIOBUFMGR;
1544
1545/** VD I/O buffer handle. */
1546typedef struct VDIOBUFINT *VDIOBUF;
1547/** Pointer to a VD I/O buffer handle. */
1548typedef VDIOBUF *PVDIOBUF;
1549
1550/** Default I/O buffer manager flags. */
1551#define VD_IOBUFMGR_F_DEFAULT (0)
1552/** I/O buffer memory needs to be non pageable (for example because it contains sensitive data
1553 * which shouldn't end up in swap unencrypted). */
1554#define VD_IOBUFMGR_F_REQUIRE_NOT_PAGABLE RT_BIT(0)
1555
1556/** Pointer to VD I/O buffer callbacks. */
1557typedef struct VDIOBUFCALLBACKS *PVDIOBUFCALLBACKS;
1558/** Pointer to const VD I/O buffer callbacks. */
1559typedef const struct VDIOBUFCALLBACKS *PCVDIOBUFCALLBACKS;
1560
1561/**
1562 * VD I/O buffer callbacks.
1563 */
1564typedef struct VDIOBUFCALLBACKS
1565{
1566 /**
1567 * Copy data from the memory buffer of the caller to the callees memory buffer for the given request.
1568 *
1569 * @returns VBox status code.
1570 * @retval VERR_PDM_MEDIAEX_IOBUF_OVERFLOW if there is not enough room to store the data.
1571 * @param pInterface Pointer to the interface structure containing the called function pointer.
1572 * @param hIoBuf The I/O request handle.
1573 * @param pvIoBufAlloc The allocator specific memory for this request.
1574 * @param offDst The destination offset from the start to write the data to.
1575 * @param pSgBuf The S/G buffer to read the data from.
1576 * @param cbCopy How many bytes to copy.
1577 */
1578 DECLR3CALLBACKMEMBER(int, pfnIoBufCopyFromBuf, (PVDIOBUFCALLBACKS pInterface, VDIOBUF hIoBuf,
1579 void *pvIoBufAlloc, uint32_t offDst, PRTSGBUF pSgBuf,
1580 size_t cbCopy));
1581
1582 /**
1583 * Copy data to the memory buffer of the caller from the callees memory buffer for the given request.
1584 *
1585 * @returns VBox status code.
1586 * @retval VERR_PDM_MEDIAEX_IOBUF_UNDERRUN if there is not enough data to copy from the buffer.
1587 * @param pInterface Pointer to the interface structure containing the called function pointer.
1588 * @param hIoBuf The I/O request handle.
1589 * @param pvIoBufAlloc The allocator specific memory for this request.
1590 * @param offSrc The offset from the start of the buffer to read the data from.
1591 * @param pSgBuf The S/G buffer to write the data to.
1592 * @param cbCopy How many bytes to copy.
1593 */
1594 DECLR3CALLBACKMEMBER(int, pfnIoBufCopyToBuf, (PVDIOBUFCALLBACKS pInterface, VDIOBUF hIoBuf,
1595 void *pvIoBufAlloc, uint32_t offSrc, PRTSGBUF pSgBuf,
1596 size_t cbCopy));
1597
1598 /**
1599 * Queries a pointer to the memory buffer for the request from the drive/device above.
1600 *
1601 * @returns VBox status code.
1602 * @retval VERR_NOT_SUPPORTED if this is not supported for this request.
1603 * @param pInterface Pointer to the interface structure containing the called function pointer.
1604 * @param hIoBuf The I/O request handle.
1605 * @param pvIoBufAlloc The allocator specific memory for this request.
1606 * @param offBuf The offset from the start of the buffer to get the buffer address.
1607 * @param cbBuf The number of bytes requested.
1608 * @param ppvBuf Where to store the pointer to the guest buffer on success.
1609 * @param pcbBuf Where to store the size of the buffer on success.
1610 *
1611 * @note This is an optional feature of the entity implementing this interface to avoid overhead
1612 * by copying the data between buffers. If NULL it is not supported at all and the caller
1613 * has to resort to VDIOBUFCALLBACKS::pfnIoBufCopyToBuf and VDIOBUFCALLBACKS::pfnIoBufCopyFromBuf.
1614 * The same holds when VERR_NOT_SUPPORTED is returned.
1615 *
1616 * On the upside the caller of this interface might not call this method at all and just
1617 * use the before mentioned methods to copy the data between the buffers.
1618 */
1619 DECLR3CALLBACKMEMBER(int, pfnIoBufQueryBuf, (PVDIOBUFCALLBACKS pInterface, VDIOBUF hIoBuf,
1620 void *pvIoBufAlloc, uint32_t offBuf, size_t cbBuf,
1621 void **ppvBuf, size_t *pcbBuf));
1622
1623} VDIOBUFCALLBACKS;
1624
1625/**
1626 * Creates a new I/O buffer manager.
1627 *
1628 * @returns VBox status code.
1629 * @param phIoBufMgr Where to store the handle to the I/O buffer manager on success.
1630 * @param cbMax The maximum amount of I/O memory to allow. Trying to allocate more than
1631 * this will lead to out of memory errors. 0 for "unlimited" size (only restriction
1632 * is the available memory on the host).
1633 * @param fFlags Combination of VD_IOBUFMGR_F_*.
1634 * @param pIoBufClbks Memory copy callbacks between source and target memory regions, optional.
1635 * When NULL all I/O buffers must be allocated with a valid S/G buffer laying out the
1636 * memory.
1637 * @param cbIoBufAlloc How much to allocate extra in the I/O buffer for private use.
1638 */
1639VBOXDDU_DECL(int) VDIoBufMgrCreate(PVDIOBUFMGR phIoBufMgr, size_t cbMax, uint32_t fFlags,
1640 PVDIOBUFCALLBACKS pIoBufClbks, size_t cbIoBufAlloc);
1641
1642/**
1643 * Destroys the given I/O buffer manager.
1644 *
1645 * @returns VBox status code.
1646 * @retval VERR_INVALID_STATE if there are still buffers allocated by the given manager.
1647 * @param hIoBufMgr The I/O buffer manager.
1648 */
1649VBOXDDU_DECL(int) VDIoBufMgrDestroy(VDIOBUFMGR hIoBufMgr);
1650
1651/**
1652 * Allocate a new I/O buffer handle.
1653 *
1654 * @returns VBox status code.
1655 * @param hIoBufMgr The I/O buffer manager to use.
1656 * @param phIoBuf Where to store the I/O buffer handle on success.
1657 * @param ppvIoBufAlloc Where to store the pointe to the private party on success.
1658 * @param pSgBuf The S/G buffer to use, optional. If NULL the I/O buffer callbacks
1659 * supplied when creating the owning manager are used to transfer the
1660 * data.
1661 * @param cbBuf Size of the buffer in bytes.
1662 */
1663VBOXDDU_DECL(int) VDIoBufMgrAllocBuf(VDIOBUFMGR hIoBufMgr, PVDIOBUF phIoBuf, void **ppvIoBufAlloc,
1664 PCRTSGBUF pSgBuf, size_t cbBuf);
1665
1666/**
1667 * Retains the I/O buffer reference count.
1668 *
1669 * @returns New reference count.
1670 * @param hIoBuf The I/O buffer handle.
1671 */
1672VBOXDDU_DECL(uint32_t) VDIoBufRetain(VDIOBUF hIoBuf);
1673
1674/**
1675 * Releases the given I/O buffer reference.
1676 *
1677 * @returns New reference count, on 0 the I/O buffer is destroyed.
1678 * @param hIoBuf The I/O buffer handle.
1679 */
1680VBOXDDU_DECL(uint32_t) VDIoBufRelease(VDIOBUF hIoBuf);
1681
1682/** @} */
1683
1684
1685/** @defgroup grp_vd_ioqueue I/O queues
1686 * @{
1687 */
1688
1689/** VD I/O queue handle. */
1690typedef struct VDIOQUEUEINT *VDIOQUEUE;
1691/** Pointer to an VD I/O queue handle. */
1692typedef VDIOQUEUE *PVDIOQUEUE;
1693
1694/** VD I/O queue request handle. */
1695typedef struct VDIOREQINT *VDIOREQ;
1696/** Pointer to an VD I/O queue request handle. */
1697typedef VDIOREQ *PVDIOREQ;
1698
1699/** A I/O request ID. */
1700typedef uint64_t VDIOREQID;
1701
1702/**
1703 * I/O request type.
1704 */
1705typedef enum VDIOREQTYPE
1706{
1707 /** Invalid request type. */
1708 VDIOREQTYPE_INVALID = 0,
1709 /** Read request. */
1710 VDIOREQTYPE_READ,
1711 /** Write request. */
1712 VDIOREQTYPE_WRITE,
1713 /** Flush request. */
1714 VDIOREQTYPE_FLUSH,
1715 /** Discard request. */
1716 VDIOREQTYPE_DISCARD,
1717 /** 32bit hack. */
1718 VDIOREQTYPE_32BIT_HACK = 0x7fffffff
1719} VDIOREQTYPE;
1720/** Pointer to a request type. */
1721typedef VDIOREQTYPE *PVDIOREQTYPE;
1722
1723/**
1724 * I/O queue request completion callback.
1725 *
1726 * @param hVdIoQueue The VD I/O queue handle.
1727 * @param pDisk The disk the queue is attached to.
1728 * @param hVdIoReq The VD I/O request which completed.
1729 * @param pvVdIoReq Pointer to the allocator specific memory for this request.
1730 * @param rcReq The completion status code.
1731 */
1732typedef DECLCALLBACKTYPE(void, FNVDIOQUEUEREQCOMPLETE,(VDIOQUEUE hVdIoQueue, PVDISK pDisk,
1733 VDIOREQ hVdIoReq, void *pvVdIoReq, int rcReq));
1734/** Pointer to a VD I/O queue request completion callback. */
1735typedef FNVDIOQUEUEREQCOMPLETE *PFNVDIOQUEUEREQCOMPLETE;
1736
1737
1738/**
1739 * Creates a new I/O queue.
1740 *
1741 * @returns VBox status code.
1742 * @param phVdIoQueue Where to store the handle to the I/O queue on success.
1743 * @param pfnIoReqComplete The completion handle to call when a request on the specified queue completes.
1744 * @param cbIoReqAlloc The extra amount of memory to allocate and associate with allocated requests
1745 * for use by the caller.
1746 * @param iPriority The priority of the queue from 0..UINT32_MAX. The lower the number the higher
1747 * the priority of the queue.
1748 */
1749VBOXDDU_DECL(int) VDIoQueueCreate(PVDIOQUEUE phVdIoQueue, PFNVDIOQUEUEREQCOMPLETE pfnIoReqComplete,
1750 size_t cbIoReqAlloc, uint32_t iPriority);
1751
1752/**
1753 * Destroys the given I/O queue.
1754 *
1755 * @returns VBox status code.
1756 * @param hVdIoQueue The I/O queue handle.
1757 */
1758VBOXDDU_DECL(int) VDIoQueueDestroy(VDIOQUEUE hVdIoQueue);
1759
1760/**
1761 * Attaches the given I/O queue to the given virtual disk container.
1762 *
1763 * @returns VBox status code.
1764 * @param pDisk The disk container handle.
1765 * @param hVdIoQueue The I/O queue to attach.
1766 */
1767VBOXDDU_DECL(int) VDIoQueueAttach(PVDISK pDisk, VDIOQUEUE hVdIoQueue);
1768
1769/**
1770 * Detaches the given I/O queue from the currently attached disk container.
1771 *
1772 * @returns VBox status code.
1773 * @param hVdIoQueue The I/O queue.
1774 * @param fPurge Flag whether to cancel all active requests on this queue
1775 * before detaching.
1776 */
1777VBOXDDU_DECL(int) VDIoQueueDetach(VDIOQUEUE hVdIoQueue, bool fPurge);
1778
1779/**
1780 * Purges all requests on the given queue.
1781 *
1782 * @returns VBox status code.
1783 * @param hVdIoQueue The I/O queue.
1784 */
1785VBOXDDU_DECL(int) VDIoQueuePurge(VDIOQUEUE hVdIoQueue);
1786
1787/**
1788 * Allocates a new request from the given queue.
1789 *
1790 * @returns VBox status code.
1791 * @param hVdIoQueue The I/O queue.
1792 * @param phVdIoReq Where to store the handle of the request on success.
1793 * @param ppvVdIoReq Where to store the pointer to the allocator usable memory on success.
1794 * @param uIoReqId The request ID to assign to the request for canceling.
1795 */
1796VBOXDDU_DECL(int) VDIoQueueReqAlloc(VDIOQUEUE hVdIoQueue, PVDIOREQ phVdIoReq,
1797 void **ppvVdIoReq, VDIOREQID uIoReqId);
1798
1799/**
1800 * Frees a given non active request.
1801 *
1802 * @returns VBox status code.
1803 * @param hVdIoReq The I/O request to free.
1804 */
1805VBOXDDU_DECL(int) VDIoQueueReqFree(VDIOREQ hVdIoReq);
1806
1807/**
1808 * Cancels an active request by the given request ID.
1809 *
1810 * @returns VBox status code.
1811 * @param hVdIoQueue The I/O queue to cancel the request on.
1812 * @param uIoReqId The request ID.
1813 */
1814VBOXDDU_DECL(int) VDIoQueueReqCancelById(VDIOQUEUE hVdIoQueue, VDIOREQID uIoReqId);
1815
1816/**
1817 * Cancels an active request by the given handle.
1818 *
1819 * @returns VBox status code.
1820 * @param hVdIoReq The I/O request handle to cancel.
1821 */
1822VBOXDDU_DECL(int) VDIoQueueReqCancelByHandle(VDIOREQ hVdIoReq);
1823
1824/**
1825 * Submit a new request to the queue the request was allocated from.
1826 *
1827 * @returns VBox status code.
1828 * @param hVdIoReq The I/O request handle to submit.
1829 * @param enmType The type of the request.
1830 * @param hVdIoIter The iterator to use, NULL for flush requests.
1831 * @param hVdIoBuf The I/O buffer handle to use, NULL for flush and discard requests.
1832 */
1833VBOXDDU_DECL(int) VDIoQueueReqSubmit(VDIOREQ hVdIoReq, VDIOREQTYPE enmType,
1834 VDIOITER hVdIoIter, VDIOBUF hVdIoBuf);
1835
1836/** @} */
1837
1838
1839RT_C_DECLS_END
1840
1841/** @} */
1842
1843#endif /* !VBOX_INCLUDED_vd_h */
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