2 * Block driver for Hyper-V VHDX Images
4 * Copyright (c) 2013 Red Hat, Inc.,
7 * Jeff Cody <jcody@redhat.com>
9 * This is based on the "VHDX Format Specification v1.00", published 8/25/2012
11 * https://www.microsoft.com/en-us/download/details.aspx?id=34750
13 * This work is licensed under the terms of the GNU LGPL, version 2 or later.
14 * See the COPYING.LIB file in the top-level directory.
22 #define KiB (1 * 1024)
25 #define MiB (KiB * 1024)
27 #define GiB (MiB * 1024)
28 #define TiB ((uint64_t) GiB * 1024)
30 /* Structures and fields present in the VHDX file */
32 /* The header section has the following blocks,
35 * _____________________________________________________________________________
36 * | File Id. | Header 1 | Header 2 | Region Table | Reserved (768KB) |
37 * |----------|---------------|------------|--------------|--------------------|
39 * 0.........64KB...........128KB........192KB..........256KB................1MB
42 #define VHDX_HEADER_BLOCK_SIZE (64 * 1024)
44 #define VHDX_FILE_ID_OFFSET 0
45 #define VHDX_HEADER1_OFFSET (VHDX_HEADER_BLOCK_SIZE * 1)
46 #define VHDX_HEADER2_OFFSET (VHDX_HEADER_BLOCK_SIZE * 2)
47 #define VHDX_REGION_TABLE_OFFSET (VHDX_HEADER_BLOCK_SIZE * 3)
48 #define VHDX_REGION_TABLE2_OFFSET (VHDX_HEADER_BLOCK_SIZE * 4)
50 #define VHDX_HEADER_SECTION_END (1 * MiB)
52 * A note on the use of MS-GUID fields. For more details on the GUID,
53 * please see: https://en.wikipedia.org/wiki/Globally_unique_identifier.
55 * The VHDX specification only states that these are MS GUIDs, and which
56 * bytes are data1-data4. It makes no mention of what algorithm should be used
57 * to generate the GUID, nor what standard. However, looking at the specified
58 * known GUID fields, it appears the GUIDs are:
59 * Standard/DCE GUID type (noted by 10b in the MSB of byte 0 of .data4)
60 * Random algorithm (noted by 0x4XXX for .data3)
63 /* ---- HEADER SECTION STRUCTURES ---- */
65 /* These structures are ones that are defined in the VHDX specification
68 #define VHDX_FILE_SIGNATURE 0x656C696678646876 /* "vhdxfile" in ASCII */
69 typedef struct VHDXFileIdentifier
{
70 uint64_t signature
; /* "vhdxfile" in ASCII */
71 uint16_t creator
[256]; /* optional; utf-16 string to identify
72 the vhdx file creator. Diagnostic
77 /* the guid is a 16 byte unique ID - the definition for this used by
78 * Microsoft is not just 16 bytes though - it is a structure that is defined,
79 * so we need to follow it here so that endianness does not trip us up */
81 typedef struct QEMU_PACKED MSGUID
{
88 #define guid_eq(a, b) \
89 (memcmp(&(a), &(b), sizeof(MSGUID)) == 0)
91 #define VHDX_HEADER_SIZE (4 * 1024) /* although the vhdx_header struct in disk
92 is only 582 bytes, for purposes of crc
93 the header is the first 4KB of the 64KB
96 /* The full header is 4KB, although the actual header data is much smaller.
97 * But for the checksum calculation, it is over the entire 4KB structure,
98 * not just the defined portion of it */
99 #define VHDX_HEADER_SIGNATURE 0x64616568
100 typedef struct QEMU_PACKED VHDXHeader
{
101 uint32_t signature
; /* "head" in ASCII */
102 uint32_t checksum
; /* CRC-32C hash of the whole header */
103 uint64_t sequence_number
; /* Seq number of this header. Each
104 VHDX file has 2 of these headers,
105 and only the header with the highest
106 sequence number is valid */
107 MSGUID file_write_guid
; /* 128 bit unique identifier. Must be
108 updated to new, unique value before
109 the first modification is made to
111 MSGUID data_write_guid
; /* 128 bit unique identifier. Must be
112 updated to new, unique value before
113 the first modification is made to
114 visible data. Visbile data is
116 - system & user metadata
119 - any change that will
120 cause the virtual disk
121 sector read to differ
123 This does not need to change if
124 blocks are re-arranged */
125 MSGUID log_guid
; /* 128 bit unique identifier. If zero,
126 there is no valid log. If non-zero,
127 log entries with this guid are
129 uint16_t log_version
; /* version of the log format. Must be
131 uint16_t version
; /* version of the vhdx file. Currently,
132 only supported version is "1" */
133 uint32_t log_length
; /* length of the log. Must be multiple
135 uint64_t log_offset
; /* byte offset in the file of the log.
136 Must also be a multiple of 1MB */
139 /* Header for the region table block */
140 #define VHDX_REGION_SIGNATURE 0x69676572 /* "regi" in ASCII */
141 typedef struct QEMU_PACKED VHDXRegionTableHeader
{
142 uint32_t signature
; /* "regi" in ASCII */
143 uint32_t checksum
; /* CRC-32C hash of the 64KB table */
144 uint32_t entry_count
; /* number of valid entries */
146 } VHDXRegionTableHeader
;
148 /* Individual region table entry. There may be a maximum of 2047 of these
150 * There are two known region table properties. Both are required.
151 * BAT (block allocation table): 2DC27766F62342009D64115E9BFD4A08
152 * Metadata: 8B7CA20647904B9AB8FE575F050F886E
154 #define VHDX_REGION_ENTRY_REQUIRED 0x01 /* if set, parser must understand
155 this entry in order to open
157 typedef struct QEMU_PACKED VHDXRegionTableEntry
{
158 MSGUID guid
; /* 128-bit unique identifier */
159 uint64_t file_offset
; /* offset of the object in the file.
160 Must be multiple of 1MB */
161 uint32_t length
; /* length, in bytes, of the object */
163 } VHDXRegionTableEntry
;
166 /* ---- LOG ENTRY STRUCTURES ---- */
167 #define VHDX_LOG_MIN_SIZE (1024 * 1024)
168 #define VHDX_LOG_SECTOR_SIZE 4096
169 #define VHDX_LOG_HDR_SIZE 64
170 #define VHDX_LOG_SIGNATURE 0x65676f6c
171 typedef struct QEMU_PACKED VHDXLogEntryHeader
{
172 uint32_t signature
; /* "loge" in ASCII */
173 uint32_t checksum
; /* CRC-32C hash of the 64KB table */
174 uint32_t entry_length
; /* length in bytes, multiple of 1MB */
175 uint32_t tail
; /* byte offset of first log entry of a
176 seq, where this entry is the last
178 uint64_t sequence_number
; /* incremented with each log entry.
180 uint32_t descriptor_count
; /* number of descriptors in this log
181 entry, must be >= 0 */
183 MSGUID log_guid
; /* value of the log_guid from
184 vhdx_header. If not found in
185 vhdx_header, it is invalid */
186 uint64_t flushed_file_offset
; /* see spec for full details - this
187 should be vhdx file size in bytes */
188 uint64_t last_file_offset
; /* size in bytes that all allocated
189 file structures fit into */
190 } VHDXLogEntryHeader
;
192 #define VHDX_LOG_DESC_SIZE 32
193 #define VHDX_LOG_DESC_SIGNATURE 0x63736564
194 #define VHDX_LOG_ZERO_SIGNATURE 0x6f72657a
195 typedef struct QEMU_PACKED VHDXLogDescriptor
{
196 uint32_t signature
; /* "zero" or "desc" in ASCII */
198 uint32_t reserved
; /* zero desc */
199 uint32_t trailing_bytes
; /* data desc: bytes 4092-4096 of the
203 uint64_t zero_length
; /* zero desc: length of the section to
205 uint64_t leading_bytes
; /* data desc: bytes 0-7 of the data
208 uint64_t file_offset
; /* file offset to write zeros - multiple
210 uint64_t sequence_number
; /* must match same field in
211 vhdx_log_entry_header */
214 #define VHDX_LOG_DATA_SIGNATURE 0x61746164
215 typedef struct QEMU_PACKED VHDXLogDataSector
{
216 uint32_t data_signature
; /* "data" in ASCII */
217 uint32_t sequence_high
; /* 4 MSB of 8 byte sequence_number */
218 uint8_t data
[4084]; /* raw data, bytes 8-4091 (inclusive).
219 see the data descriptor field for the
220 other mising bytes */
221 uint32_t sequence_low
; /* 4 LSB of 8 byte sequence_number */
226 /* block states - different state values depending on whether it is a
227 * payload block, or a sector block. */
229 #define PAYLOAD_BLOCK_NOT_PRESENT 0
230 #define PAYLOAD_BLOCK_UNDEFINED 1
231 #define PAYLOAD_BLOCK_ZERO 2
232 #define PAYLOAD_BLOCK_UNMAPPED 5
233 #define PAYLOAD_BLOCK_FULLY_PRESENT 6
234 #define PAYLOAD_BLOCK_PARTIALLY_PRESENT 7
236 #define SB_BLOCK_NOT_PRESENT 0
237 #define SB_BLOCK_PRESENT 6
240 #define VHDX_MAX_SECTORS_PER_BLOCK (1 << 23)
242 /* upper 44 bits are the file offset in 1MB units lower 3 bits are the state
243 other bits are reserved */
244 #define VHDX_BAT_STATE_BIT_MASK 0x07
245 #define VHDX_BAT_FILE_OFF_MASK 0xFFFFFFFFFFF00000 /* upper 44 bits */
246 typedef uint64_t VHDXBatEntry
;
248 /* ---- METADATA REGION STRUCTURES ---- */
250 #define VHDX_METADATA_ENTRY_SIZE 32
251 #define VHDX_METADATA_MAX_ENTRIES 2047 /* not including the header */
252 #define VHDX_METADATA_TABLE_MAX_SIZE \
253 (VHDX_METADATA_ENTRY_SIZE * (VHDX_METADATA_MAX_ENTRIES+1))
254 #define VHDX_METADATA_SIGNATURE 0x617461646174656D /* "metadata" in ASCII */
255 typedef struct QEMU_PACKED VHDXMetadataTableHeader
{
256 uint64_t signature
; /* "metadata" in ASCII */
258 uint16_t entry_count
; /* number table entries. <= 2047 */
259 uint32_t reserved2
[5];
260 } VHDXMetadataTableHeader
;
262 #define VHDX_META_FLAGS_IS_USER 0x01 /* max 1024 entries */
263 #define VHDX_META_FLAGS_IS_VIRTUAL_DISK 0x02 /* virtual disk metadata if set,
264 otherwise file metdata */
265 #define VHDX_META_FLAGS_IS_REQUIRED 0x04 /* parse must understand this
266 entry to open the file */
267 typedef struct QEMU_PACKED VHDXMetadataTableEntry
{
268 MSGUID item_id
; /* 128-bit identifier for metadata */
269 uint32_t offset
; /* byte offset of the metadata. At
270 least 64kB. Relative to start of
272 /* note: if length = 0, so is offset */
273 uint32_t length
; /* length of metadata. <= 1MB. */
274 uint32_t data_bits
; /* least-significant 3 bits are flags,
275 the rest are reserved (see above) */
277 } VHDXMetadataTableEntry
;
279 #define VHDX_PARAMS_LEAVE_BLOCKS_ALLOCED 0x01 /* Do not change any blocks to
280 be BLOCK_NOT_PRESENT.
281 If set indicates a fixed
283 #define VHDX_PARAMS_HAS_PARENT 0x02 /* has parent / backing file */
284 #define VHDX_BLOCK_SIZE_MIN (1 * MiB)
285 #define VHDX_BLOCK_SIZE_MAX (256 * MiB)
286 typedef struct QEMU_PACKED VHDXFileParameters
{
287 uint32_t block_size
; /* size of each payload block, always
288 power of 2, <= 256MB and >= 1MB. */
289 uint32_t data_bits
; /* least-significant 2 bits are flags,
290 the rest are reserved (see above) */
291 } VHDXFileParameters
;
293 #define VHDX_MAX_IMAGE_SIZE ((uint64_t) 64 * TiB)
294 typedef struct QEMU_PACKED VHDXVirtualDiskSize
{
295 uint64_t virtual_disk_size
; /* Size of the virtual disk, in bytes.
296 Must be multiple of the sector size,
298 } VHDXVirtualDiskSize
;
300 typedef struct QEMU_PACKED VHDXPage83Data
{
301 MSGUID page_83_data
; /* unique id for scsi devices that
305 typedef struct QEMU_PACKED VHDXVirtualDiskLogicalSectorSize
{
306 uint32_t logical_sector_size
; /* virtual disk sector size (in bytes).
307 Can only be 512 or 4096 bytes */
308 } VHDXVirtualDiskLogicalSectorSize
;
310 typedef struct QEMU_PACKED VHDXVirtualDiskPhysicalSectorSize
{
311 uint32_t physical_sector_size
; /* physical sector size (in bytes).
312 Can only be 512 or 4096 bytes */
313 } VHDXVirtualDiskPhysicalSectorSize
;
315 typedef struct QEMU_PACKED VHDXParentLocatorHeader
{
316 MSGUID locator_type
; /* type of the parent virtual disk. */
318 uint16_t key_value_count
; /* number of key/value pairs for this
320 } VHDXParentLocatorHeader
;
322 /* key and value strings are UNICODE strings, UTF-16 LE encoding, no NULs */
323 typedef struct QEMU_PACKED VHDXParentLocatorEntry
{
324 uint32_t key_offset
; /* offset in metadata for key, > 0 */
325 uint32_t value_offset
; /* offset in metadata for value, >0 */
326 uint16_t key_length
; /* length of entry key, > 0 */
327 uint16_t value_length
; /* length of entry value, > 0 */
328 } VHDXParentLocatorEntry
;
331 /* ----- END VHDX SPECIFICATION STRUCTURES ---- */
333 typedef struct VHDXMetadataEntries
{
334 VHDXMetadataTableEntry file_parameters_entry
;
335 VHDXMetadataTableEntry virtual_disk_size_entry
;
336 VHDXMetadataTableEntry page83_data_entry
;
337 VHDXMetadataTableEntry logical_sector_size_entry
;
338 VHDXMetadataTableEntry phys_sector_size_entry
;
339 VHDXMetadataTableEntry parent_locator_entry
;
341 } VHDXMetadataEntries
;
343 typedef struct VHDXLogEntries
{
348 VHDXLogEntryHeader
*hdr
;
354 typedef struct VHDXRegionEntry
{
357 QLIST_ENTRY(VHDXRegionEntry
) entries
;
360 typedef struct BDRVVHDXState
{
364 VHDXHeader
*headers
[2];
366 VHDXRegionTableHeader rt
;
367 VHDXRegionTableEntry bat_rt
; /* region table for the BAT */
368 VHDXRegionTableEntry metadata_rt
; /* region table for the metadata */
370 VHDXMetadataTableHeader metadata_hdr
;
371 VHDXMetadataEntries metadata_entries
;
373 VHDXFileParameters params
;
375 uint32_t block_size_bits
;
376 uint32_t sectors_per_block
;
377 uint32_t sectors_per_block_bits
;
379 uint64_t virtual_disk_size
;
380 uint32_t logical_sector_size
;
381 uint32_t physical_sector_size
;
383 uint64_t chunk_ratio
;
384 uint32_t chunk_ratio_bits
;
385 uint32_t logical_sector_size_bits
;
387 uint32_t bat_entries
;
391 bool first_visible_write
;
396 VHDXParentLocatorHeader parent_header
;
397 VHDXParentLocatorEntry
*parent_entries
;
399 Error
*migration_blocker
;
401 QLIST_HEAD(VHDXRegionHead
, VHDXRegionEntry
) regions
;
404 void vhdx_guid_generate(MSGUID
*guid
);
406 int vhdx_update_headers(BlockDriverState
*bs
, BDRVVHDXState
*s
, bool rw
,
409 uint32_t vhdx_update_checksum(uint8_t *buf
, size_t size
, int crc_offset
);
410 uint32_t vhdx_checksum_calc(uint32_t crc
, uint8_t *buf
, size_t size
,
413 bool vhdx_checksum_is_valid(uint8_t *buf
, size_t size
, int crc_offset
);
415 int vhdx_parse_log(BlockDriverState
*bs
, BDRVVHDXState
*s
, bool *flushed
);
417 int vhdx_log_write_and_flush(BlockDriverState
*bs
, BDRVVHDXState
*s
,
418 void *data
, uint32_t length
, uint64_t offset
);
420 static inline void leguid_to_cpus(MSGUID
*guid
)
422 le32_to_cpus(&guid
->data1
);
423 le16_to_cpus(&guid
->data2
);
424 le16_to_cpus(&guid
->data3
);
427 static inline void cpu_to_leguids(MSGUID
*guid
)
429 cpu_to_le32s(&guid
->data1
);
430 cpu_to_le16s(&guid
->data2
);
431 cpu_to_le16s(&guid
->data3
);
434 void vhdx_header_le_import(VHDXHeader
*h
);
435 void vhdx_header_le_export(VHDXHeader
*orig_h
, VHDXHeader
*new_h
);
436 void vhdx_log_desc_le_import(VHDXLogDescriptor
*d
);
437 void vhdx_log_desc_le_export(VHDXLogDescriptor
*d
);
438 void vhdx_log_data_le_export(VHDXLogDataSector
*d
);
439 void vhdx_log_entry_hdr_le_import(VHDXLogEntryHeader
*hdr
);
440 void vhdx_log_entry_hdr_le_export(VHDXLogEntryHeader
*hdr
);
441 void vhdx_region_header_le_import(VHDXRegionTableHeader
*hdr
);
442 void vhdx_region_header_le_export(VHDXRegionTableHeader
*hdr
);
443 void vhdx_region_entry_le_import(VHDXRegionTableEntry
*e
);
444 void vhdx_region_entry_le_export(VHDXRegionTableEntry
*e
);
445 void vhdx_metadata_header_le_import(VHDXMetadataTableHeader
*hdr
);
446 void vhdx_metadata_header_le_export(VHDXMetadataTableHeader
*hdr
);
447 void vhdx_metadata_entry_le_import(VHDXMetadataTableEntry
*e
);
448 void vhdx_metadata_entry_le_export(VHDXMetadataTableEntry
*e
);
449 int vhdx_user_visible_write(BlockDriverState
*bs
, BDRVVHDXState
*s
);