VirtualBox

source: vbox/trunk/src/VBox/Devices/Storage/VDICore.h@ 7152

Last change on this file since 7152 was 7152, checked in by vboxsync, 17 years ago

Preparations for implementing a VBoxHDD-new based VDI backend. Clean up the existing stuff to not pollute the namespace.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 19.0 KB
Line 
1/** $Id: VDICore.h 7152 2008-02-26 17:17:10Z vboxsync $ */
2/** @file
3 * Virtual Disk Image (VDI), Core Code Header (internal).
4 */
5
6/*
7 * Copyright (C) 2006-2007 innotek GmbH
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18#ifndef __VDICore_h__
19
20
21/*******************************************************************************
22* Header Files *
23*******************************************************************************/
24#ifndef VBOX_VDICORE_VD
25#include <VBox/VBoxHDD.h>
26#else /* VBOX_VDICORE_VD */
27#include <VBox/VBoxHDD-new.h>
28#endif /* VBOX_VDICORE_VD */
29#include <VBox/pdm.h>
30#include <VBox/mm.h>
31#include <VBox/err.h>
32
33#include <VBox/log.h>
34#include <iprt/alloc.h>
35#include <iprt/assert.h>
36#include <iprt/uuid.h>
37#include <iprt/file.h>
38#include <iprt/string.h>
39#include <iprt/asm.h>
40
41
42/*******************************************************************************
43* Constants And Macros, Structures and Typedefs *
44*******************************************************************************/
45
46/** Image info, not handled anyhow.
47 * Must be less than 64 bytes in length, including the trailing 0.
48 */
49#define VDI_IMAGE_FILE_INFO "<<< innotek VirtualBox Disk Image >>>\n"
50
51/** The Sector size.
52 * Currently we support only 512 bytes sectors.
53 */
54#define VDI_GEOMETRY_SECTOR_SIZE (512)
55/** 512 = 2^^9 */
56#define VDI_GEOMETRY_SECTOR_SHIFT (9)
57
58/**
59 * Harddisk geometry.
60 */
61#pragma pack(1)
62typedef struct VDIDISKGEOMETRY
63{
64 /** Cylinders. */
65 uint32_t cCylinders;
66 /** Heads. */
67 uint32_t cHeads;
68 /** Sectors per track. */
69 uint32_t cSectors;
70 /** Sector size. (bytes per sector) */
71 uint32_t cbSector;
72} VDIDISKGEOMETRY, *PVDIDISKGEOMETRY;
73#pragma pack()
74
75/** Image signature. */
76#define VDI_IMAGE_SIGNATURE (0xbeda107f)
77
78/**
79 * Pre-Header to be stored in image file - used for version control.
80 */
81#pragma pack(1)
82typedef struct VDIPREHEADER
83{
84 /** Just text info about image type, for eyes only. */
85 char szFileInfo[64];
86 /** The image signature (VDI_IMAGE_SIGNATURE). */
87 uint32_t u32Signature;
88 /** The image version (VDI_IMAGE_VERSION). */
89 uint32_t u32Version;
90} VDIPREHEADER, *PVDIPREHEADER;
91#pragma pack()
92
93/**
94 * Size of szComment field of HDD image header.
95 */
96#define VDI_IMAGE_COMMENT_SIZE 256
97
98/**
99 * Header to be stored in image file, VDI_IMAGE_VERSION_MAJOR = 0.
100 * Prepended by VDIPREHEADER.
101 */
102#pragma pack(1)
103typedef struct VDIHEADER0
104{
105 /** The image type (VDI_IMAGE_TYPE_*). */
106 uint32_t u32Type;
107 /** Image flags (VDI_IMAGE_FLAGS_*). */
108 uint32_t fFlags;
109 /** Image comment. (UTF-8) */
110 char szComment[VDI_IMAGE_COMMENT_SIZE];
111 /** Legacy image geometry (previous code stored PCHS there). */
112 VDIDISKGEOMETRY LegacyGeometry;
113 /** Size of disk (in bytes). */
114 uint64_t cbDisk;
115 /** Block size. (For instance VDI_IMAGE_BLOCK_SIZE.) */
116 uint32_t cbBlock;
117 /** Number of blocks. */
118 uint32_t cBlocks;
119 /** Number of allocated blocks. */
120 uint32_t cBlocksAllocated;
121 /** UUID of image. */
122 RTUUID uuidCreate;
123 /** UUID of image's last modification. */
124 RTUUID uuidModify;
125 /** Only for secondary images - UUID of primary image. */
126 RTUUID uuidLinkage;
127} VDIHEADER0, *PVDIHEADER0;
128#pragma pack()
129
130/**
131 * Header to be stored in image file, VDI_IMAGE_VERSION_MAJOR = 1,
132 * VDI_IMAGE_VERSION_MINOR = 1. Prepended by VDIPREHEADER.
133 */
134#pragma pack(1)
135typedef struct VDIHEADER1
136{
137 /** Size of this structure in bytes. */
138 uint32_t cbHeader;
139 /** The image type (VDI_IMAGE_TYPE_*). */
140 uint32_t u32Type;
141 /** Image flags (VDI_IMAGE_FLAGS_*). */
142 uint32_t fFlags;
143 /** Image comment. (UTF-8) */
144 char szComment[VDI_IMAGE_COMMENT_SIZE];
145 /** Offset of Blocks array from the begining of image file.
146 * Should be sector-aligned for HDD access optimization. */
147 uint32_t offBlocks;
148 /** Offset of image data from the begining of image file.
149 * Should be sector-aligned for HDD access optimization. */
150 uint32_t offData;
151 /** Legacy image geometry (previous code stored PCHS there). */
152 VDIDISKGEOMETRY LegacyGeometry;
153 /** Was BIOS HDD translation mode, now unused. */
154 uint32_t u32Dummy;
155 /** Size of disk (in bytes). */
156 uint64_t cbDisk;
157 /** Block size. (For instance VDI_IMAGE_BLOCK_SIZE.) Should be a power of 2! */
158 uint32_t cbBlock;
159 /** Size of additional service information of every data block.
160 * Prepended before block data. May be 0.
161 * Should be a power of 2 and sector-aligned for optimization reasons. */
162 uint32_t cbBlockExtra;
163 /** Number of blocks. */
164 uint32_t cBlocks;
165 /** Number of allocated blocks. */
166 uint32_t cBlocksAllocated;
167 /** UUID of image. */
168 RTUUID uuidCreate;
169 /** UUID of image's last modification. */
170 RTUUID uuidModify;
171 /** Only for secondary images - UUID of previous image. */
172 RTUUID uuidLinkage;
173 /** Only for secondary images - UUID of previous image's last modification. */
174 RTUUID uuidParentModify;
175} VDIHEADER1, *PVDIHEADER1;
176#pragma pack()
177
178/**
179 * Header to be stored in image file, VDI_IMAGE_VERSION_MAJOR = 1,
180 * VDI_IMAGE_VERSION_MINOR = 1, the slightly changed variant necessary as the
181 * old released code doesn't support changing the minor version at all.
182 */
183#pragma pack(1)
184typedef struct VDIHEADER1PLUS
185{
186 /** Size of this structure in bytes. */
187 uint32_t cbHeader;
188 /** The image type (VDI_IMAGE_TYPE_*). */
189 uint32_t u32Type;
190 /** Image flags (VDI_IMAGE_FLAGS_*). */
191 uint32_t fFlags;
192 /** Image comment. (UTF-8) */
193 char szComment[VDI_IMAGE_COMMENT_SIZE];
194 /** Offset of Blocks array from the begining of image file.
195 * Should be sector-aligned for HDD access optimization. */
196 uint32_t offBlocks;
197 /** Offset of image data from the begining of image file.
198 * Should be sector-aligned for HDD access optimization. */
199 uint32_t offData;
200 /** Legacy image geometry (previous code stored PCHS there). */
201 VDIDISKGEOMETRY LegacyGeometry;
202 /** Was BIOS HDD translation mode, now unused. */
203 uint32_t u32Dummy;
204 /** Size of disk (in bytes). */
205 uint64_t cbDisk;
206 /** Block size. (For instance VDI_IMAGE_BLOCK_SIZE.) Should be a power of 2! */
207 uint32_t cbBlock;
208 /** Size of additional service information of every data block.
209 * Prepended before block data. May be 0.
210 * Should be a power of 2 and sector-aligned for optimization reasons. */
211 uint32_t cbBlockExtra;
212 /** Number of blocks. */
213 uint32_t cBlocks;
214 /** Number of allocated blocks. */
215 uint32_t cBlocksAllocated;
216 /** UUID of image. */
217 RTUUID uuidCreate;
218 /** UUID of image's last modification. */
219 RTUUID uuidModify;
220 /** Only for secondary images - UUID of previous image. */
221 RTUUID uuidLinkage;
222 /** Only for secondary images - UUID of previous image's last modification. */
223 RTUUID uuidParentModify;
224 /** LCHS image geometry (new field in VDI1.2 version. */
225 VDIDISKGEOMETRY LCHSGeometry;
226} VDIHEADER1PLUS, *PVDIHEADER1PLUS;
227#pragma pack()
228
229/**
230 * Header structure for all versions.
231 */
232typedef struct VDIHEADER
233{
234 unsigned uVersion;
235 union
236 {
237 VDIHEADER0 v0;
238 VDIHEADER1 v1;
239 VDIHEADER1PLUS v1plus;
240 } u;
241} VDIHEADER, *PVDIHEADER;
242
243/** Block 'pointer'. */
244typedef uint32_t VDIIMAGEBLOCKPOINTER;
245/** Pointer to a block 'pointer'. */
246typedef VDIIMAGEBLOCKPOINTER *PVDIIMAGEBLOCKPOINTER;
247
248/**
249 * Block marked as free is not allocated in image file, read from this
250 * block may returns any random data.
251 */
252#define VDI_IMAGE_BLOCK_FREE ((VDIIMAGEBLOCKPOINTER)~0)
253
254/**
255 * Block marked as zero is not allocated in image file, read from this
256 * block returns zeroes.
257 */
258#define VDI_IMAGE_BLOCK_ZERO ((VDIIMAGEBLOCKPOINTER)~1)
259
260/**
261 * Block 'pointer' >= VDI_IMAGE_BLOCK_UNALLOCATED indicates block is not
262 * allocated in image file.
263 */
264#define VDI_IMAGE_BLOCK_UNALLOCATED (VDI_IMAGE_BLOCK_ZERO)
265#define IS_VDI_IMAGE_BLOCK_ALLOCATED(bp) (bp < VDI_IMAGE_BLOCK_UNALLOCATED)
266
267#define GET_MAJOR_HEADER_VERSION(ph) (VDI_GET_VERSION_MAJOR((ph)->uVersion))
268#define GET_MINOR_HEADER_VERSION(ph) (VDI_GET_VERSION_MINOR((ph)->uVersion))
269
270#ifdef VBOX_VDICORE_VD
271/** @name VDI image types
272 * @{ */
273typedef enum VDIIMAGETYPE
274{
275 /** Normal dynamically growing base image file. */
276 VDI_IMAGE_TYPE_NORMAL = 1,
277 /** Preallocated base image file of a fixed size. */
278 VDI_IMAGE_TYPE_FIXED,
279 /** Dynamically growing image file for undo/commit changes support. */
280 VDI_IMAGE_TYPE_UNDO,
281 /** Dynamically growing image file for differencing support. */
282 VDI_IMAGE_TYPE_DIFF,
283
284 /** First valid image type value. */
285 VDI_IMAGE_TYPE_FIRST = VDI_IMAGE_TYPE_NORMAL,
286 /** Last valid image type value. */
287 VDI_IMAGE_TYPE_LAST = VDI_IMAGE_TYPE_DIFF
288} VDIIMAGETYPE;
289/** Pointer to VDI image type. */
290typedef VDIIMAGETYPE *PVDIIMAGETYPE;
291/** @} */
292#endif /* VBOX_VDICORE_VD */
293
294/*******************************************************************************
295* Internal Functions for header access *
296*******************************************************************************/
297DECLINLINE(VDIIMAGETYPE) getImageType(PVDIHEADER ph)
298{
299 switch (GET_MAJOR_HEADER_VERSION(ph))
300 {
301 case 0: return (VDIIMAGETYPE)ph->u.v0.u32Type;
302 case 1: return (VDIIMAGETYPE)ph->u.v1.u32Type;
303 }
304 AssertFailed();
305 return (VDIIMAGETYPE)0;
306}
307
308DECLINLINE(unsigned) getImageFlags(PVDIHEADER ph)
309{
310 switch (GET_MAJOR_HEADER_VERSION(ph))
311 {
312 case 0: return ph->u.v0.fFlags;
313 case 1: return ph->u.v1.fFlags;
314 }
315 AssertFailed();
316 return 0;
317}
318
319DECLINLINE(char *) getImageComment(PVDIHEADER ph)
320{
321 switch (GET_MAJOR_HEADER_VERSION(ph))
322 {
323 case 0: return &ph->u.v0.szComment[0];
324 case 1: return &ph->u.v1.szComment[0];
325 }
326 AssertFailed();
327 return NULL;
328}
329
330DECLINLINE(unsigned) getImageBlocksOffset(PVDIHEADER ph)
331{
332 switch (GET_MAJOR_HEADER_VERSION(ph))
333 {
334 case 0: return (sizeof(VDIPREHEADER) + sizeof(VDIHEADER0));
335 case 1: return ph->u.v1.offBlocks;
336 }
337 AssertFailed();
338 return 0;
339}
340
341DECLINLINE(unsigned) getImageDataOffset(PVDIHEADER ph)
342{
343 switch (GET_MAJOR_HEADER_VERSION(ph))
344 {
345 case 0: return sizeof(VDIPREHEADER) + sizeof(VDIHEADER0) + \
346 (ph->u.v0.cBlocks * sizeof(VDIIMAGEBLOCKPOINTER));
347 case 1: return ph->u.v1.offData;
348 }
349 AssertFailed();
350 return 0;
351}
352
353DECLINLINE(PVDIDISKGEOMETRY) getImageLCHSGeometry(PVDIHEADER ph)
354{
355 switch (GET_MAJOR_HEADER_VERSION(ph))
356 {
357 case 0: return NULL;
358 case 1:
359 switch (GET_MINOR_HEADER_VERSION(ph))
360 {
361 case 1:
362 if (ph->u.v1.cbHeader < sizeof(ph->u.v1plus))
363 return NULL;
364 else
365 return &ph->u.v1plus.LCHSGeometry;
366 }
367 }
368 AssertFailed();
369 return NULL;
370}
371
372DECLINLINE(uint64_t) getImageDiskSize(PVDIHEADER ph)
373{
374 switch (GET_MAJOR_HEADER_VERSION(ph))
375 {
376 case 0: return ph->u.v0.cbDisk;
377 case 1: return ph->u.v1.cbDisk;
378 }
379 AssertFailed();
380 return 0;
381}
382
383DECLINLINE(unsigned) getImageBlockSize(PVDIHEADER ph)
384{
385 switch (GET_MAJOR_HEADER_VERSION(ph))
386 {
387 case 0: return ph->u.v0.cbBlock;
388 case 1: return ph->u.v1.cbBlock;
389 }
390 AssertFailed();
391 return 0;
392}
393
394DECLINLINE(unsigned) getImageExtraBlockSize(PVDIHEADER ph)
395{
396 switch (GET_MAJOR_HEADER_VERSION(ph))
397 {
398 case 0: return 0;
399 case 1: return ph->u.v1.cbBlockExtra;
400 }
401 AssertFailed();
402 return 0;
403}
404
405DECLINLINE(unsigned) getImageBlocks(PVDIHEADER ph)
406{
407 switch (GET_MAJOR_HEADER_VERSION(ph))
408 {
409 case 0: return ph->u.v0.cBlocks;
410 case 1: return ph->u.v1.cBlocks;
411 }
412 AssertFailed();
413 return 0;
414}
415
416DECLINLINE(unsigned) getImageBlocksAllocated(PVDIHEADER ph)
417{
418 switch (GET_MAJOR_HEADER_VERSION(ph))
419 {
420 case 0: return ph->u.v0.cBlocksAllocated;
421 case 1: return ph->u.v1.cBlocksAllocated;
422 }
423 AssertFailed();
424 return 0;
425}
426
427DECLINLINE(void) setImageBlocksAllocated(PVDIHEADER ph, unsigned cBlocks)
428{
429 switch (GET_MAJOR_HEADER_VERSION(ph))
430 {
431 case 0: ph->u.v0.cBlocksAllocated = cBlocks; return;
432 case 1: ph->u.v1.cBlocksAllocated = cBlocks; return;
433 }
434 AssertFailed();
435}
436
437DECLINLINE(PRTUUID) getImageCreationUUID(PVDIHEADER ph)
438{
439 switch (GET_MAJOR_HEADER_VERSION(ph))
440 {
441 case 0: return &ph->u.v0.uuidCreate;
442 case 1: return &ph->u.v1.uuidCreate;
443 }
444 AssertFailed();
445 return NULL;
446}
447
448DECLINLINE(PRTUUID) getImageModificationUUID(PVDIHEADER ph)
449{
450 switch (GET_MAJOR_HEADER_VERSION(ph))
451 {
452 case 0: return &ph->u.v0.uuidModify;
453 case 1: return &ph->u.v1.uuidModify;
454 }
455 AssertFailed();
456 return NULL;
457}
458
459DECLINLINE(PRTUUID) getImageParentUUID(PVDIHEADER ph)
460{
461 switch (GET_MAJOR_HEADER_VERSION(ph))
462 {
463 case 0: return &ph->u.v0.uuidLinkage;
464 case 1: return &ph->u.v1.uuidLinkage;
465 }
466 AssertFailed();
467 return NULL;
468}
469
470DECLINLINE(PRTUUID) getImageParentModificationUUID(PVDIHEADER ph)
471{
472 switch (GET_MAJOR_HEADER_VERSION(ph))
473 {
474 case 1: return &ph->u.v1.uuidParentModify;
475 }
476 AssertFailed();
477 return NULL;
478}
479
480#ifndef VBOX_VDICORE_VD
481/**
482 * Default image block size, may be changed by setBlockSize/getBlockSize.
483 *
484 * Note: for speed reasons block size should be a power of 2 !
485 */
486#define VDI_IMAGE_DEFAULT_BLOCK_SIZE _1M
487#endif /* !VBOX_VDICORE_VD */
488
489#ifndef VBOX_VDICORE_VD
490/**
491 * fModified bit flags.
492 */
493#define VDI_IMAGE_MODIFIED_FLAG RT_BIT(0)
494#define VDI_IMAGE_MODIFIED_FIRST RT_BIT(1)
495#define VDI_IMAGE_MODIFIED_DISABLE_UUID_UPDATE RT_BIT(2)
496#endif /* !VBOX_VDICORE_VD */
497
498/**
499 * Image structure
500 */
501typedef struct VDIIMAGEDESC
502{
503#ifndef VBOX_VDICORE_VD
504 /** Link to parent image descriptor, if any. */
505 struct VDIIMAGEDESC *pPrev;
506 /** Link to child image descriptor, if any. */
507 struct VDIIMAGEDESC *pNext;
508#endif /* !VBOX_VDICORE_VD */
509 /** File handle. */
510 RTFILE File;
511#ifndef VBOX_VDICORE_VD
512 /** True if the image is operating in readonly mode. */
513 bool fReadOnly;
514 /** Image open flags, VDI_OPEN_FLAGS_*. */
515 unsigned fOpen;
516#else /* VBOX_VDICORE_VD */
517 /** Image open flags, VD__OPEN_FLAGS_*. */
518 unsigned uOpenFlags;
519#endif /* VBOX_VDICORE_VD */
520 /** Image pre-header. */
521 VDIPREHEADER PreHeader;
522 /** Image header. */
523 VDIHEADER Header;
524 /** Pointer to a block array. */
525 PVDIIMAGEBLOCKPOINTER paBlocks;
526#ifndef VBOX_VDICORE_VD
527 /** fFlags copy from image header, for speed optimization. */
528 unsigned fFlags;
529#else /* VBOX_VDICORE_VD */
530 /** fFlags copy from image header, for speed optimization. */
531 unsigned uImageFlags;
532#endif /* VBOX_VDICORE_VD */
533 /** Start offset of block array in image file, here for speed optimization. */
534 unsigned offStartBlocks;
535 /** Start offset of data in image file, here for speed optimization. */
536 unsigned offStartData;
537 /** Block mask for getting the offset into a block from a byte hdd offset. */
538 unsigned uBlockMask;
539 /** Block shift value for converting byte hdd offset into paBlock index. */
540 unsigned uShiftOffset2Index;
541 /** Block shift value for converting block index into offset in image. */
542 unsigned uShiftIndex2Offset;
543 /** Offset of data from the beginning of block. */
544 unsigned offStartBlockData;
545 /** Image is modified flags (VDI_IMAGE_MODIFIED*). */
546 unsigned fModified;
547#ifndef VBOX_VDICORE_VD
548 /** Container filename. (UTF-8)
549 * @todo Make this variable length to save a bunch of bytes. (low prio) */
550 char szFilename[RTPATH_MAX];
551#else /* !VBOX_VDICORE_VD */
552 /** Container filename. (UTF-8) */
553 const char *pszFilename;
554 /** Physical geometry of this image (never actually stored). */
555 PDMMEDIAGEOMETRY PCHSGeometry;
556 /** Error callback. */
557 PFNVDERROR pfnError;
558 /** Opaque data for error callback. */
559 void *pvErrorUser;
560#endif /* !VBOX_VDICORE_VD */
561} VDIIMAGEDESC, *PVDIIMAGEDESC;
562
563#ifndef VBOX_VDICORE_VD
564/**
565 * Default work buffer size, may be changed by setBufferSize() method.
566 *
567 * For best speed performance it must be equal to image block size.
568 */
569#define VDIDISK_DEFAULT_BUFFER_SIZE (VDI_IMAGE_DEFAULT_BLOCK_SIZE)
570#endif /* !VBOX_VDICORE_VD */
571
572/** VDIDISK Signature. */
573#define VDIDISK_SIGNATURE (0xbedafeda)
574
575/**
576 * VBox HDD Container main structure, private part.
577 */
578struct VDIDISK
579{
580 /** Structure signature (VDIDISK_SIGNATURE). */
581 uint32_t u32Signature;
582
583 /** Number of opened images. */
584 unsigned cImages;
585
586 /** Base image. */
587 PVDIIMAGEDESC pBase;
588
589 /** Last opened image in the chain.
590 * The same as pBase if only one image is used or the last opened diff image. */
591 PVDIIMAGEDESC pLast;
592
593 /** Default block size for newly created images. */
594 unsigned cbBlock;
595
596 /** Working buffer size, allocated only while committing data,
597 * copying block from primary image to secondary and saving previously
598 * zero block. Buffer deallocated after operation complete.
599 * @remark For best performance buffer size must be equal to image's
600 * block size, however it may be decreased for memory saving.
601 */
602 unsigned cbBuf;
603
604 /** Flag whether zero writes should be handled normally or optimized
605 * away if possible. */
606 bool fHonorZeroWrites;
607
608 /** The media interface. */
609 PDMIMEDIA IMedia;
610 /** Pointer to the driver instance. */
611 PPDMDRVINS pDrvIns;
612};
613
614
615/*******************************************************************************
616* Internal Functions *
617*******************************************************************************/
618__BEGIN_DECLS
619
620#ifndef VBOX_VDICORE_VD
621VBOXDDU_DECL(void) vdiInitVDIDisk(PVDIDISK pDisk);
622VBOXDDU_DECL(void) VDIFlushImage(PVDIIMAGEDESC pImage);
623VBOXDDU_DECL(int) vdiChangeImageMode(PVDIIMAGEDESC pImage, bool fReadOnly);
624#endif /* !VBOX_VDICORE_VD */
625
626__END_DECLS
627
628#endif
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