VDICore.h revision 5c1a0e405ed53adff36d4fb4e6185d43311cc74e
/* $Id$ */
/** @file
* Virtual Disk Image (VDI), Core Code Header (internal).
*/
/*
* Copyright (C) 2006-2011 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*/
#ifndef ___VDICore_h___
/*******************************************************************************
* Header Files *
*******************************************************************************/
/*******************************************************************************
* Constants And Macros, Structures and Typedefs *
*******************************************************************************/
/** Image info, not handled anyhow.
* Must be less than 64 bytes in length, including the trailing 0.
*/
#define VDI_IMAGE_FILE_INFO "<<< Oracle VM VirtualBox Disk Image >>>\n"
/** The Sector size.
* Currently we support only 512 bytes sectors.
*/
#define VDI_GEOMETRY_SECTOR_SIZE (512)
/** 512 = 2^^9 */
#define VDI_GEOMETRY_SECTOR_SHIFT (9)
/**
* Harddisk geometry.
*/
#pragma pack(1)
typedef struct VDIDISKGEOMETRY
{
/** Cylinders. */
/** Heads. */
/** Sectors per track. */
/** Sector size. (bytes per sector) */
#pragma pack()
/** Image signature. */
#define VDI_IMAGE_SIGNATURE (0xbeda107f)
/**
* Pre-Header to be stored in image file - used for version control.
*/
#pragma pack(1)
typedef struct VDIPREHEADER
{
/** Just text info about image type, for eyes only. */
char szFileInfo[64];
/** The image signature (VDI_IMAGE_SIGNATURE). */
/** The image version (VDI_IMAGE_VERSION). */
#pragma pack()
/**
* Size of szComment field of HDD image header.
*/
#define VDI_IMAGE_COMMENT_SIZE 256
/**
* Header to be stored in image file, VDI_IMAGE_VERSION_MAJOR = 0.
* Prepended by VDIPREHEADER.
*/
#pragma pack(1)
typedef struct VDIHEADER0
{
/** The image type (VDI_IMAGE_TYPE_*). */
/** Image flags (VDI_IMAGE_FLAGS_*). */
/** Image comment. (UTF-8) */
char szComment[VDI_IMAGE_COMMENT_SIZE];
/** Legacy image geometry (previous code stored PCHS there). */
/** Size of disk (in bytes). */
/** Block size. (For instance VDI_IMAGE_BLOCK_SIZE.) */
/** Number of blocks. */
/** Number of allocated blocks. */
/** UUID of image. */
/** UUID of image's last modification. */
/** Only for secondary images - UUID of primary image. */
} VDIHEADER0, *PVDIHEADER0;
#pragma pack()
/**
* Header to be stored in image file, VDI_IMAGE_VERSION_MAJOR = 1,
* VDI_IMAGE_VERSION_MINOR = 1. Prepended by VDIPREHEADER.
*/
#pragma pack(1)
typedef struct VDIHEADER1
{
/** Size of this structure in bytes. */
/** The image type (VDI_IMAGE_TYPE_*). */
/** Image flags (VDI_IMAGE_FLAGS_*). */
/** Image comment. (UTF-8) */
char szComment[VDI_IMAGE_COMMENT_SIZE];
/** Offset of Blocks array from the beginning of image file.
* Should be sector-aligned for HDD access optimization. */
/** Offset of image data from the beginning of image file.
* Should be sector-aligned for HDD access optimization. */
/** Legacy image geometry (previous code stored PCHS there). */
/** Was BIOS HDD translation mode, now unused. */
/** Size of disk (in bytes). */
/** Block size. (For instance VDI_IMAGE_BLOCK_SIZE.) Should be a power of 2! */
/** Size of additional service information of every data block.
* Prepended before block data. May be 0.
* Should be a power of 2 and sector-aligned for optimization reasons. */
/** Number of blocks. */
/** Number of allocated blocks. */
/** UUID of image. */
/** UUID of image's last modification. */
/** Only for secondary images - UUID of previous image. */
/** Only for secondary images - UUID of previous image's last modification. */
} VDIHEADER1, *PVDIHEADER1;
#pragma pack()
/**
* Header to be stored in image file, VDI_IMAGE_VERSION_MAJOR = 1,
* VDI_IMAGE_VERSION_MINOR = 1, the slightly changed variant necessary as the
* old released code doesn't support changing the minor version at all.
*/
#pragma pack(1)
typedef struct VDIHEADER1PLUS
{
/** Size of this structure in bytes. */
/** The image type (VDI_IMAGE_TYPE_*). */
/** Image flags (VDI_IMAGE_FLAGS_*). */
/** Image comment. (UTF-8) */
char szComment[VDI_IMAGE_COMMENT_SIZE];
/** Offset of blocks array from the beginning of image file.
* Should be sector-aligned for HDD access optimization. */
/** Offset of image data from the beginning of image file.
* Should be sector-aligned for HDD access optimization. */
/** Legacy image geometry (previous code stored PCHS there). */
/** Was BIOS HDD translation mode, now unused. */
/** Size of disk (in bytes). */
/** Block size. (For instance VDI_IMAGE_BLOCK_SIZE.) Should be a power of 2! */
/** Size of additional service information of every data block.
* Prepended before block data. May be 0.
* Should be a power of 2 and sector-aligned for optimization reasons. */
/** Number of blocks. */
/** Number of allocated blocks. */
/** UUID of image. */
/** UUID of image's last modification. */
/** Only for secondary images - UUID of previous image. */
/** Only for secondary images - UUID of previous image's last modification. */
/** LCHS image geometry (new field in VDI1.2 version. */
#pragma pack()
/**
* Header structure for all versions.
*/
typedef struct VDIHEADER
{
unsigned uVersion;
union
{
} u;
} VDIHEADER, *PVDIHEADER;
/**
* File alignment boundary for both the block array and data area. Should be
* at least the size of a physical sector on disk for performance reasons.
* With the growing market share of disks with 4K sectors this needs to be
* bumped, and maybe again later. */
#define VDI_DATA_ALIGN _4K
/** Block 'pointer'. */
typedef uint32_t VDIIMAGEBLOCKPOINTER;
/** Pointer to a block 'pointer'. */
typedef VDIIMAGEBLOCKPOINTER *PVDIIMAGEBLOCKPOINTER;
/**
* Block marked as free is not allocated in image file, read from this
* block may returns any random data.
*/
#define VDI_IMAGE_BLOCK_FREE ((VDIIMAGEBLOCKPOINTER)~0)
/**
* Block marked as zero is not allocated in image file, read from this
* block returns zeroes.
*/
/**
* Block 'pointer' >= VDI_IMAGE_BLOCK_UNALLOCATED indicates block is not
* allocated in image file.
*/
/** @name VDI image types
* @{ */
typedef enum VDIIMAGETYPE
{
/** Normal dynamically growing base image file. */
/** Preallocated base image file of a fixed size. */
/** Dynamically growing image file for differencing support. */
/** First valid image type value. */
/** Last valid image type value. */
} VDIIMAGETYPE;
/** Pointer to VDI image type. */
typedef VDIIMAGETYPE *PVDIIMAGETYPE;
/** @} */
/*******************************************************************************
* Internal Functions for header access *
*******************************************************************************/
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return (VDIIMAGETYPE)0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
case 0:
/* VDI image flag conversion to VD image flags. */
case 1:
/* VDI image flag conversion to VD image flags. */
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return NULL;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
case 0: return (sizeof(VDIPREHEADER) + sizeof(VDIHEADER0));
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
case 0: return sizeof(VDIPREHEADER) + sizeof(VDIHEADER0) + \
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
case 0: return;
}
AssertFailed();
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
case 0: return NULL;
case 1:
switch (GET_MINOR_HEADER_VERSION(ph))
{
case 1:
return NULL;
else
}
}
AssertFailed();
return NULL;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
case 0: return 0;
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return 0;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return NULL;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return NULL;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return NULL;
}
{
switch (GET_MAJOR_HEADER_VERSION(ph))
{
}
AssertFailed();
return NULL;
}
/**
* Image structure
*/
typedef struct VDIIMAGEDESC
{
/** Opaque storage handle. */
/** Image open flags, VD_OPEN_FLAGS_*. */
unsigned uOpenFlags;
/** Image pre-header. */
/** Image header. */
/** Pointer to a block array. */
/** Pointer to the block array for back resolving (used if discarding is enabled). */
unsigned *paBlocksRev;
/** fFlags copy from image header, for speed optimization. */
unsigned uImageFlags;
/** Start offset of block array in image file, here for speed optimization. */
unsigned offStartBlocks;
/** Start offset of data in image file, here for speed optimization. */
unsigned offStartData;
/** Block mask for getting the offset into a block from a byte hdd offset. */
unsigned uBlockMask;
/** Block shift value for converting byte hdd offset into paBlock index. */
unsigned uShiftOffset2Index;
/** Offset of data from the beginning of block. */
unsigned offStartBlockData;
/** Total size of image block (including the extra data). */
unsigned cbTotalBlockData;
/** Container filename. (UTF-8) */
const char *pszFilename;
/** Physical geometry of this image (never actually stored). */
/** Pointer to the per-disk VD interface list. */
/** Pointer to the per-image VD interface list. */
/** Error interface. */
/** I/O interface. */
/** Current size of the image (used for range validation when reading). */
/**
* Async block discard states.
*/
typedef enum VDIBLOCKDISCARDSTATE
{
/** Invalid. */
/** Read the last block. */
/** Write block into the hole. */
/** Update metadata. */
/** 32bit hack. */
VDIBLOCKDISCARDSTATE_32BIT_HACK = 0x7fffffff
/**
* Async block discard structure.
*/
typedef struct VDIBLOCKDISCARDASYNC
{
/** State of the block discard. */
/** Pointer to the block data. */
void *pvBlock;
/** Block index in the block table. */
unsigned uBlock;
/** Block pointer to the block to discard. */
/** Index of the last block in the reverse block table. */
unsigned idxLastBlock;
/** Index of the last block in the block table (gathered from the reverse block table). */
unsigned uBlockLast;
/**
* Async image expansion state.
*/
typedef struct VDIASYNCBLOCKALLOC
{
/** Number of blocks allocated. */
unsigned cBlocksAllocated;
/** Block index to allocate. */
unsigned uBlock;
#endif