VirtualBox

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

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

Rebranding: replacing more innotek strings.

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