vd.h revision 8eeee8a3c0abf2bacba420fdf542963f8f0ba2e8
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * VBox HDD Container API.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Copyright (C) 2006-2013 Oracle Corporation
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * available from http://www.virtualbox.org. This file is free software;
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * you can redistribute it and/or modify it under the terms of the GNU
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * General Public License (GPL) as published by the Free Software
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * The contents of this file may alternatively be used under the terms
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * of the Common Development and Distribution License Version 1.0
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * VirtualBox OSE distribution, in which case the provisions of the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * CDDL are applicable instead of those of the GPL.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * You may elect to license modified versions of this file under the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * terms and conditions of either the GPL or the CDDL or both.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync# error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** @defgroup grp_vd VBox HDD Container
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Current VMDK image version. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Current VDI image major version. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Current VDI image minor version. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Current VDI image version. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) | VDI_IMAGE_VERSION_MINOR)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Get VDI major version from combined version. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Get VDI minor version from combined version. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Placeholder for specifying the last opened image. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Placeholder for VDCopyEx to indicate that the image content is unknown. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** @name VBox HDD container image flags
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** No flags. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Fixed image. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Diff image. Mutually exclusive with fixed image. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** VMDK: Split image into 2GB extents. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** VMDK: Raw disk image (giving access to a number of host partitions). */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** VMDK: stream optimized image, read only. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED (0x0004)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** VMDK: ESX variant, use in addition to other flags. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** VDI: Fill new blocks with zeroes while expanding image file. Only valid
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * for newly created images, never set for opened existing images. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Mask of valid image flags for VMDK. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VD_VMDK_IMAGE_FLAGS_MASK ( VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE \
3bad884471a4755d52abffc98cc326f153750ca1vboxsync | VD_VMDK_IMAGE_FLAGS_SPLIT_2G | VD_VMDK_IMAGE_FLAGS_RAWDISK \
3bad884471a4755d52abffc98cc326f153750ca1vboxsync | VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED | VD_VMDK_IMAGE_FLAGS_ESX)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Mask of valid image flags for VDI. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE | VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Mask of all valid image flags for all formats. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK | VD_VDI_IMAGE_FLAGS_MASK)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Default image flags. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** @name VD image repair flags
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Don't repair the image but check what needs to be done. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Mask of all valid repair flags. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** @name VD image VFS file flags
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Destroy the VD disk container when the VFS file is released. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Mask of all valid repair flags. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync#define VD_VFSFILE_FLAGS_MASK (VD_VFSFILE_DESTROY_ON_RELEASE)
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Auxiliary type for describing partitions on raw disks. The entries must be
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * in ascending order (as far as uStart is concerned), and must not overlap.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Note that this does not correspond 1:1 to partitions, it is describing the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * general meaning of contiguous areas on the disk.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Device to use for this partition/data area. Can be the disk device if
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * the offset field is set appropriately. If this is NULL, then this
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * partition will not be accessible to the guest. The size of the data area
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * must still be set correctly. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Pointer to the partitioning info. NULL means this is a regular data
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * area on disk, non-NULL denotes data which should be copied to the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * partition data overlay. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Offset where the data starts in this device. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Offset where the data starts in the disk. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Size of the data area. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Auxiliary data structure for difference between GPT and MBR
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Auxiliary data structure for creating raw disks.
3bad884471a4755d52abffc98cc326f153750ca1vboxsynctypedef struct VBOXHDDRAW
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Signature for structure. Must be 'R', 'A', 'W', '\\0'. Actually a trick
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * to make logging of the comment string produce sensible results. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Flag whether access to full disk should be given (ignoring the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * partition information below). */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Filename for the raw disk. Ignored for partitioned raw disks.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * For Linux e.g. /dev/sda, and for Windows e.g. \\\\.\\PhysicalDisk0. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Number of entries in the partition descriptor array. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Pointer to the partition descriptor array. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Partitioning type of the disk */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** @name VBox HDD container image open mode flags
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Open image in read-only mode with sharing access with others. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Honor zero block writes instead of ignoring them whenever possible.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * This is not supported by all formats. It is silently ignored in this case. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Honor writes of the same data instead of ignoring whenever possible.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * This is handled generically, and is only meaningful for differential image
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * formats. It is silently ignored otherwise. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Do not perform the base/diff image check on open. This does NOT imply
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * opening the image as readonly (would break e.g. adding UUIDs to VMDK files
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * created by other products). Images opened with this flag should only be
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * used for querying information, and nothing else. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Open image for asynchronous access. Only available if VD_CAP_ASYNC_IO is
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * set. VDOpen fails with VERR_NOT_SUPPORTED if this operation is not supported for
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * this kind of image. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Allow sharing of the image for writable images. May be ignored if the
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * format backend doesn't support this type of concurrent access. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Ask the backend to switch to sequential accesses if possible. Opening
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * will not fail if it cannot do this, the flag will be simply ignored. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Allow the discard operation if supported. Only available if VD_CAP_DISCARD
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * is set. VDOpen fails with VERR_VD_DISCARD_NOT_SUPPORTED if discarding is not
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * supported. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Ignore all flush requests to workaround certain filesystems which are slow
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * when writing a lot of cached data to the medium.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * Use with extreme care as a host crash can result in completely corrupted and
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * unusable images.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * Return VINF_VD_NEW_ZEROED_BLOCK for reads from unallocated blocks.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * The caller who uses the flag has to make sure that the read doesn't cross
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * a block boundary. Because the block size can differ between images reading one
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * sector at a time is the safest solution.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync#define VD_OPEN_FLAGS_INFORM_ABOUT_ZERO_BLOCKS RT_BIT(9)
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * Don't do unnecessary consistency checks when opening the image.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * Only valid when the image is opened in readonly because inconsistencies
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * can lead to corrupted images in read-write mode.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync#define VD_OPEN_FLAGS_SKIP_CONSISTENCY_CHECKS RT_BIT(10)
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Mask of valid flags. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync#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)
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * Helper functions to handle open flags.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * Translate VD_OPEN_FLAGS_* to RTFile open flags.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * @return RTFile open flags.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * @param uOpenFlags VD_OPEN_FLAGS_* open flags.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * @param fCreate Flag that the file should be created.
3bad884471a4755d52abffc98cc326f153750ca1vboxsyncDECLINLINE(uint32_t) VDOpenFlagsToFileOpenFlags(unsigned uOpenFlags, bool fCreate)
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync AssertMsg(!((uOpenFlags & VD_OPEN_FLAGS_READONLY) && fCreate), ("Image can't be opened readonly while being created\n"));
3bad884471a4755d52abffc98cc326f153750ca1vboxsync if (RT_UNLIKELY(uOpenFlags & VD_OPEN_FLAGS_READONLY))
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync if (RT_UNLIKELY(uOpenFlags & VD_OPEN_FLAGS_SHAREABLE))
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync fOpen |= RTFILE_O_CREATE | RTFILE_O_NOT_CONTENT_INDEXED;
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** @name VBox HDD container backend capability flags
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Supports UUIDs as expected by VirtualBox code. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Supports creating fixed size images, allocating all space instantly. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Supports creating dynamically growing images, allocating space on demand. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Supports creating images split in chunks of a bit less than 2GBytes. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Supports being used as differencing image format backend. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** Supports asynchronous I/O operations for at least some configurations. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** The backend operates on files. The caller needs to know to handle the
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * location appropriately. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** The backend uses the config interface. The caller needs to know how to
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * provide the mandatory configuration parts this way. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** The backend uses the network stack interface. The caller has to provide
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * the appropriate interface. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** The backend supports VFS (virtual filesystem) functionality since it uses
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync * VDINTERFACEIO exclusively for all file operations. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** The backend supports the discard operation. */
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync/** @name VBox HDD container type.
5eb8c49f193655f19bb89b653df8643091fa987bvboxsync /** Invalid. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** HardDisk */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Floppy. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** @name Configuration interface key handling flags.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Mandatory config key. Not providing a value for this key will cause
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * the backend to fail. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Expert config key. Not showing it by default in the GUI is is probably
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * a good idea, as the average user won't understand it easily. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Configuration value type for configuration information interface.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Integer value. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** String value. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Bytestring value. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Structure describing configuration keys required/supported by a backend
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * through the config interface.
3bad884471a4755d52abffc98cc326f153750ca1vboxsynctypedef struct VDCONFIGINFO
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Key name of the configuration. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync const char *pszKey;
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Pointer to default value (descriptor). NULL if no useful default value
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * can be specified. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Value type for this key. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Key handling flags (a combination of VD_CFGKEY_* flags). */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Pointer to structure describing configuration keys. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Pointer to const structure describing configuration keys. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync * Structure describing a file extension.
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** Pointer to the NULL-terminated string containing the extension. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync /** The device type the extension supports. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Pointer to a structure describing a file extension. */
3bad884471a4755d52abffc98cc326f153750ca1vboxsync/** Pointer to a const structure describing a file extension. */
typedef struct VDBACKENDINFO
const char *pszBackend;
typedef struct VDGEOMETRY
} VDGEOMETRY;
struct VBOXHDD;
unsigned *pcEntriesUsed);
* @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
* @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
* @param nImageSameFrom The number of the last image in the source chain having the same content as the
* @param nImageSameTo The number of the last image in the destination chain having the same content as the
* @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
* @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
unsigned *puVersion);
unsigned *puOpenFlags);
unsigned uOpenFlags);
const char *pszComment);