[mirror_qemu.git] / block / vhdx.h

/*
 * Block driver for Hyper-V VHDX Images
 *
 * Copyright (c) 2013 Red Hat, Inc.,
 *
 * Authors:
 *  Jeff Cody <jcody@redhat.com>
 *
 *  This is based on the "VHDX Format Specification v1.00", published 8/25/2012
 *  by Microsoft:
 *      https://www.microsoft.com/en-us/download/details.aspx?id=34750
 *
 * This work is licensed under the terms of the GNU LGPL, version 2 or later.
 * See the COPYING.LIB file in the top-level directory.
 *
 */

#ifndef BLOCK_VHDX_H
#define BLOCK_VHDX_H
#include "qemu/units.h"

#define DEFAULT_LOG_SIZE 1048576 /* 1MiB */
/* Structures and fields present in the VHDX file */

/* The header section has the following blocks,
 * each block is 64KB:
 *
 * _____________________________________________________________________________
 * | File Id. |   Header 1    | Header 2   | Region Table |  Reserved (768KB)  |
 * |----------|---------------|------------|--------------|--------------------|
 * |          |               |            |              |                    |
 * 0.........64KB...........128KB........192KB..........256KB................1MB
 */

#define VHDX_HEADER_BLOCK_SIZE      (64 * 1024)

#define VHDX_FILE_ID_OFFSET         0
#define VHDX_HEADER1_OFFSET         (VHDX_HEADER_BLOCK_SIZE * 1)
#define VHDX_HEADER2_OFFSET         (VHDX_HEADER_BLOCK_SIZE * 2)
#define VHDX_REGION_TABLE_OFFSET    (VHDX_HEADER_BLOCK_SIZE * 3)
#define VHDX_REGION_TABLE2_OFFSET   (VHDX_HEADER_BLOCK_SIZE * 4)

#define VHDX_HEADER_SECTION_END     (1 * MiB)
/*
 * A note on the use of MS-GUID fields.  For more details on the GUID,
 * please see: https://en.wikipedia.org/wiki/Globally_unique_identifier.
 *
 * The VHDX specification only states that these are MS GUIDs, and which
 * bytes are data1-data4. It makes no mention of what algorithm should be used
 * to generate the GUID, nor what standard.  However, looking at the specified
 * known GUID fields, it appears the GUIDs are:
 *  Standard/DCE GUID type  (noted by 10b in the MSB of byte 0 of .data4)
 *  Random algorithm        (noted by 0x4XXX for .data3)
 */

/* ---- HEADER SECTION STRUCTURES ---- */

/* These structures are ones that are defined in the VHDX specification
 * document */

#define VHDX_FILE_SIGNATURE 0x656C696678646876ULL  /* "vhdxfile" in ASCII */
typedef struct VHDXFileIdentifier {
    uint64_t    signature;              /* "vhdxfile" in ASCII */
    uint16_t    creator[256];           /* optional; utf-16 string to identify
                                           the vhdx file creator.  Diagnostic
                                           only */
} VHDXFileIdentifier;


/* the guid is a 16 byte unique ID - the definition for this used by
 * Microsoft is not just 16 bytes though - it is a structure that is defined,
 * so we need to follow it here so that endianness does not trip us up */

typedef struct QEMU_PACKED MSGUID {
    uint32_t  data1;
    uint16_t  data2;
    uint16_t  data3;
    uint8_t   data4[8];
} MSGUID;

#define guid_eq(a, b) \
    (memcmp(&(a), &(b), sizeof(MSGUID)) == 0)

#define VHDX_HEADER_SIZE (4 * 1024)   /* although the vhdx_header struct in disk
                                         is only 582 bytes, for purposes of crc
                                         the header is the first 4KB of the 64KB
                                         block */

/* The full header is 4KB, although the actual header data is much smaller.
 * But for the checksum calculation, it is over the entire 4KB structure,
 * not just the defined portion of it */
#define VHDX_HEADER_SIGNATURE 0x64616568
typedef struct QEMU_PACKED VHDXHeader {
    uint32_t    signature;              /* "head" in ASCII */
    uint32_t    checksum;               /* CRC-32C hash of the whole header */
    uint64_t    sequence_number;        /* Seq number of this header.  Each
                                           VHDX file has 2 of these headers,
                                           and only the header with the highest
                                           sequence number is valid */
    MSGUID      file_write_guid;        /* 128 bit unique identifier. Must be
                                           updated to new, unique value before
                                           the first modification is made to
                                           file */
    MSGUID      data_write_guid;        /* 128 bit unique identifier. Must be
                                           updated to new, unique value before
                                           the first modification is made to
                                           visible data.   Visbile data is
                                           defined as:
                                                    - system & user metadata
                                                    - raw block data
                                                    - disk size
                                                    - any change that will
                                                      cause the virtual disk
                                                      sector read to differ

                                           This does not need to change if
                                           blocks are re-arranged */
    MSGUID      log_guid;               /* 128 bit unique identifier. If zero,
                                           there is no valid log. If non-zero,
                                           log entries with this guid are
                                           valid. */
    uint16_t    log_version;            /* version of the log format. Must be
                                           set to zero */
    uint16_t    version;                /* version of the vhdx file.  Currently,
                                           only supported version is "1" */
    uint32_t    log_length;             /* length of the log.  Must be multiple
                                           of 1MB */
    uint64_t    log_offset;             /* byte offset in the file of the log.
                                           Must also be a multiple of 1MB */
} VHDXHeader;

/* Header for the region table block */
#define VHDX_REGION_SIGNATURE  0x69676572  /* "regi" in ASCII */
typedef struct QEMU_PACKED VHDXRegionTableHeader {
    uint32_t    signature;              /* "regi" in ASCII */
    uint32_t    checksum;               /* CRC-32C hash of the 64KB table */
    uint32_t    entry_count;            /* number of valid entries */
    uint32_t    reserved;
} VHDXRegionTableHeader;

/* Individual region table entry.  There may be a maximum of 2047 of these
 *
 *  There are two known region table properties.  Both are required.
 *  BAT (block allocation table):  2DC27766F62342009D64115E9BFD4A08
 *  Metadata:                      8B7CA20647904B9AB8FE575F050F886E
 */
#define VHDX_REGION_ENTRY_REQUIRED  0x01    /* if set, parser must understand
                                               this entry in order to open
                                               file */
typedef struct QEMU_PACKED VHDXRegionTableEntry {
    MSGUID      guid;                   /* 128-bit unique identifier */
    uint64_t    file_offset;            /* offset of the object in the file.
                                           Must be multiple of 1MB */
    uint32_t    length;                 /* length, in bytes, of the object */
    uint32_t    data_bits;
} VHDXRegionTableEntry;


/* ---- LOG ENTRY STRUCTURES ---- */
#define VHDX_LOG_MIN_SIZE (1024 * 1024)
#define VHDX_LOG_SECTOR_SIZE 4096
#define VHDX_LOG_HDR_SIZE 64
#define VHDX_LOG_SIGNATURE 0x65676f6c
typedef struct QEMU_PACKED VHDXLogEntryHeader {
    uint32_t    signature;              /* "loge" in ASCII */
    uint32_t    checksum;               /* CRC-32C hash of the 64KB table */
    uint32_t    entry_length;           /* length in bytes, multiple of 1MB */
    uint32_t    tail;                   /* byte offset of first log entry of a
                                           seq, where this entry is the last
                                           entry */
    uint64_t    sequence_number;        /* incremented with each log entry.
                                           May not be zero. */
    uint32_t    descriptor_count;       /* number of descriptors in this log
                                           entry, must be >= 0 */
    uint32_t    reserved;
    MSGUID      log_guid;               /* value of the log_guid from
                                           vhdx_header.  If not found in
                                           vhdx_header, it is invalid */
    uint64_t    flushed_file_offset;    /* see spec for full details - this
                                           should be vhdx file size in bytes */
    uint64_t    last_file_offset;       /* size in bytes that all allocated
                                           file structures fit into */
} VHDXLogEntryHeader;

#define VHDX_LOG_DESC_SIZE 32
#define VHDX_LOG_DESC_SIGNATURE 0x63736564
#define VHDX_LOG_ZERO_SIGNATURE 0x6f72657a
typedef struct QEMU_PACKED VHDXLogDescriptor {
    uint32_t    signature;              /* "zero" or "desc" in ASCII */
    union  {
        uint32_t    reserved;           /* zero desc */
        uint32_t    trailing_bytes;     /* data desc: bytes 4092-4096 of the
                                           data sector */
    };
    union {
        uint64_t    zero_length;        /* zero desc: length of the section to
                                           zero */
        uint64_t    leading_bytes;      /* data desc: bytes 0-7 of the data
                                           sector */
    };
    uint64_t    file_offset;            /* file offset to write zeros - multiple
                                           of 4kB */
    uint64_t    sequence_number;        /* must match same field in
                                           vhdx_log_entry_header */
} VHDXLogDescriptor;

#define VHDX_LOG_DATA_SIGNATURE 0x61746164
typedef struct QEMU_PACKED VHDXLogDataSector {
    uint32_t    data_signature;         /* "data" in ASCII */
    uint32_t    sequence_high;          /* 4 MSB of 8 byte sequence_number */
    uint8_t     data[4084];             /* raw data, bytes 8-4091 (inclusive).
                                           see the data descriptor field for the
                                           other mising bytes */
    uint32_t    sequence_low;           /* 4 LSB of 8 byte sequence_number */
} VHDXLogDataSector;


/* block states - different state values depending on whether it is a
 * payload block, or a sector block. */

#define PAYLOAD_BLOCK_NOT_PRESENT       0
#define PAYLOAD_BLOCK_UNDEFINED         1
#define PAYLOAD_BLOCK_ZERO              2
#define PAYLOAD_BLOCK_UNMAPPED          3
#define PAYLOAD_BLOCK_UNMAPPED_v095     5
#define PAYLOAD_BLOCK_FULLY_PRESENT     6
#define PAYLOAD_BLOCK_PARTIALLY_PRESENT 7

#define SB_BLOCK_NOT_PRESENT    0
#define SB_BLOCK_PRESENT        6

/* per the spec */
#define VHDX_MAX_SECTORS_PER_BLOCK  (1 << 23)

/* upper 44 bits are the file offset in 1MB units lower 3 bits are the state
   other bits are reserved */
#define VHDX_BAT_STATE_BIT_MASK 0x07
#define VHDX_BAT_FILE_OFF_MASK  0xFFFFFFFFFFF00000ULL /* upper 44 bits */
typedef uint64_t VHDXBatEntry;

/* ---- METADATA REGION STRUCTURES ---- */

#define VHDX_METADATA_ENTRY_SIZE 32
#define VHDX_METADATA_MAX_ENTRIES 2047  /* not including the header */
#define VHDX_METADATA_TABLE_MAX_SIZE \
    (VHDX_METADATA_ENTRY_SIZE * (VHDX_METADATA_MAX_ENTRIES+1))
#define VHDX_METADATA_SIGNATURE 0x617461646174656DULL  /* "metadata" in ASCII */
typedef struct QEMU_PACKED VHDXMetadataTableHeader {
    uint64_t    signature;              /* "metadata" in ASCII */
    uint16_t    reserved;
    uint16_t    entry_count;            /* number table entries. <= 2047 */
    uint32_t    reserved2[5];
} VHDXMetadataTableHeader;

#define VHDX_META_FLAGS_IS_USER         0x01    /* max 1024 entries */
#define VHDX_META_FLAGS_IS_VIRTUAL_DISK 0x02    /* virtual disk metadata if set,
                                                   otherwise file metdata */
#define VHDX_META_FLAGS_IS_REQUIRED     0x04    /* parse must understand this
                                                   entry to open the file */
typedef struct QEMU_PACKED VHDXMetadataTableEntry {
    MSGUID      item_id;                /* 128-bit identifier for metadata */
    uint32_t    offset;                 /* byte offset of the metadata.  At
                                           least 64kB.  Relative to start of
                                           metadata region */
                                        /* note: if length = 0, so is offset */
    uint32_t    length;                 /* length of metadata. <= 1MB. */
    uint32_t    data_bits;              /* least-significant 3 bits are flags,
                                           the rest are reserved (see above) */
    uint32_t    reserved2;
} VHDXMetadataTableEntry;

#define VHDX_PARAMS_LEAVE_BLOCKS_ALLOCED 0x01   /* Do not change any blocks to
                                                   be BLOCK_NOT_PRESENT.
                                                   If set indicates a fixed
                                                   size VHDX file */
#define VHDX_PARAMS_HAS_PARENT           0x02    /* has parent / backing file */
#define VHDX_BLOCK_SIZE_MIN             (1   * MiB)
#define VHDX_BLOCK_SIZE_MAX             (256 * MiB)
typedef struct QEMU_PACKED VHDXFileParameters {
    uint32_t    block_size;             /* size of each payload block, always
                                           power of 2, <= 256MB and >= 1MB. */
    uint32_t data_bits;                 /* least-significant 2 bits are flags,
                                           the rest are reserved (see above) */
} VHDXFileParameters;

#define VHDX_MAX_IMAGE_SIZE  ((uint64_t) 64 * TiB)
typedef struct QEMU_PACKED VHDXVirtualDiskSize {
    uint64_t    virtual_disk_size;      /* Size of the virtual disk, in bytes.
                                           Must be multiple of the sector size,
                                           max of 64TB */
} VHDXVirtualDiskSize;

typedef struct QEMU_PACKED VHDXPage83Data {
    MSGUID      page_83_data;           /* unique id for scsi devices that
                                           support page 0x83 */
} VHDXPage83Data;

typedef struct QEMU_PACKED VHDXVirtualDiskLogicalSectorSize {
    uint32_t    logical_sector_size;    /* virtual disk sector size (in bytes).
                                           Can only be 512 or 4096 bytes */
} VHDXVirtualDiskLogicalSectorSize;

typedef struct QEMU_PACKED VHDXVirtualDiskPhysicalSectorSize {
    uint32_t    physical_sector_size;   /* physical sector size (in bytes).
                                           Can only be 512 or 4096 bytes */
} VHDXVirtualDiskPhysicalSectorSize;

typedef struct QEMU_PACKED VHDXParentLocatorHeader {
    MSGUID      locator_type;           /* type of the parent virtual disk. */
    uint16_t    reserved;
    uint16_t    key_value_count;        /* number of key/value pairs for this
                                           locator */
} VHDXParentLocatorHeader;

/* key and value strings are UNICODE strings, UTF-16 LE encoding, no NULs */
typedef struct QEMU_PACKED VHDXParentLocatorEntry {
    uint32_t    key_offset;             /* offset in metadata for key, > 0 */
    uint32_t    value_offset;           /* offset in metadata for value, >0 */
    uint16_t    key_length;             /* length of entry key, > 0 */
    uint16_t    value_length;           /* length of entry value, > 0 */
} VHDXParentLocatorEntry;


/* ----- END VHDX SPECIFICATION STRUCTURES ---- */

typedef struct VHDXMetadataEntries {
    VHDXMetadataTableEntry file_parameters_entry;
    VHDXMetadataTableEntry virtual_disk_size_entry;
    VHDXMetadataTableEntry page83_data_entry;
    VHDXMetadataTableEntry logical_sector_size_entry;
    VHDXMetadataTableEntry phys_sector_size_entry;
    VHDXMetadataTableEntry parent_locator_entry;
    uint16_t present;
} VHDXMetadataEntries;

typedef struct VHDXLogEntries {
    uint64_t offset;
    uint64_t length;
    uint32_t write;
    uint32_t read;
    VHDXLogEntryHeader *hdr;
    void *desc_buffer;
    uint64_t sequence;
    uint32_t tail;
} VHDXLogEntries;

typedef struct VHDXRegionEntry {
    uint64_t start;
    uint64_t end;
    QLIST_ENTRY(VHDXRegionEntry) entries;
} VHDXRegionEntry;

typedef struct BDRVVHDXState {
    CoMutex lock;

    int curr_header;
    VHDXHeader *headers[2];

    VHDXRegionTableHeader rt;
    VHDXRegionTableEntry bat_rt;         /* region table for the BAT */
    VHDXRegionTableEntry metadata_rt;    /* region table for the metadata */

    VHDXMetadataTableHeader metadata_hdr;
    VHDXMetadataEntries metadata_entries;

    VHDXFileParameters params;
    uint32_t block_size;
    uint32_t block_size_bits;
    uint32_t sectors_per_block;
    uint32_t sectors_per_block_bits;

    uint64_t virtual_disk_size;
    uint32_t logical_sector_size;
    uint32_t physical_sector_size;

    uint64_t chunk_ratio;
    uint32_t chunk_ratio_bits;
    uint32_t logical_sector_size_bits;

    uint32_t bat_entries;
    VHDXBatEntry *bat;
    uint64_t bat_offset;

    bool first_visible_write;
    MSGUID session_guid;

    VHDXLogEntries log;

    VHDXParentLocatorHeader parent_header;
    VHDXParentLocatorEntry *parent_entries;

    Error *migration_blocker;

    bool log_replayed_on_open;

    QLIST_HEAD(, VHDXRegionEntry) regions;
} BDRVVHDXState;

void vhdx_guid_generate(MSGUID *guid);

int vhdx_update_headers(BlockDriverState *bs, BDRVVHDXState *s, bool rw,
                        MSGUID *log_guid);

uint32_t vhdx_update_checksum(uint8_t *buf, size_t size, int crc_offset);
uint32_t vhdx_checksum_calc(uint32_t crc, uint8_t *buf, size_t size,
                            int crc_offset);

bool vhdx_checksum_is_valid(uint8_t *buf, size_t size, int crc_offset);

int vhdx_parse_log(BlockDriverState *bs, BDRVVHDXState *s, bool *flushed,
                   Error **errp);

int vhdx_log_write_and_flush(BlockDriverState *bs, BDRVVHDXState *s,
                             void *data, uint32_t length, uint64_t offset);

static inline void leguid_to_cpus(MSGUID *guid)
{
    guid->data1 = le32_to_cpu(guid->data1);
    guid->data2 = le16_to_cpu(guid->data2);
    guid->data3 = le16_to_cpu(guid->data3);
}

static inline void cpu_to_leguids(MSGUID *guid)
{
    guid->data1 = cpu_to_le32(guid->data1);
    guid->data2 = cpu_to_le16(guid->data2);
    guid->data3 = cpu_to_le16(guid->data3);
}

void vhdx_header_le_import(VHDXHeader *h);
void vhdx_header_le_export(VHDXHeader *orig_h, VHDXHeader *new_h);
void vhdx_log_desc_le_import(VHDXLogDescriptor *d);
void vhdx_log_desc_le_export(VHDXLogDescriptor *d);
void vhdx_log_data_le_import(VHDXLogDataSector *d);
void vhdx_log_data_le_export(VHDXLogDataSector *d);
void vhdx_log_entry_hdr_le_import(VHDXLogEntryHeader *hdr);
void vhdx_log_entry_hdr_le_export(VHDXLogEntryHeader *hdr);
void vhdx_region_header_le_import(VHDXRegionTableHeader *hdr);
void vhdx_region_header_le_export(VHDXRegionTableHeader *hdr);
void vhdx_region_entry_le_import(VHDXRegionTableEntry *e);
void vhdx_region_entry_le_export(VHDXRegionTableEntry *e);
void vhdx_metadata_header_le_import(VHDXMetadataTableHeader *hdr);
void vhdx_metadata_header_le_export(VHDXMetadataTableHeader *hdr);
void vhdx_metadata_entry_le_import(VHDXMetadataTableEntry *e);
void vhdx_metadata_entry_le_export(VHDXMetadataTableEntry *e);
int vhdx_user_visible_write(BlockDriverState *bs, BDRVVHDXState *s);

#endif
Commit	Line	Data
203cdba3 JC	1	/*
	2	* Block driver for Hyper-V VHDX Images
	3	*
	4	* Copyright (c) 2013 Red Hat, Inc.,
	5	*
	6	* Authors:
	7	* Jeff Cody <jcody@redhat.com>
	8	*
6e9d290b	9	* This is based on the "VHDX Format Specification v1.00", published 8/25/2012
203cdba3	10	* by Microsoft:
6e9d290b	11	* https://www.microsoft.com/en-us/download/details.aspx?id=34750
203cdba3 JC	12	*
	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.
	15	*
	16	*/
	17
	18	#ifndef BLOCK_VHDX_H
	19	#define BLOCK_VHDX_H
e9991e29	20	#include "qemu/units.h"
3412f7b1	21
5366092c	22	#define DEFAULT_LOG_SIZE 1048576 /* 1MiB */
203cdba3 JC	23	/* Structures and fields present in the VHDX file */
	24
	25	/* The header section has the following blocks,
	26	* each block is 64KB:
	27	*
	28	* _____________________________________________________________________________
	29	* \| File Id. \| Header 1 \| Header 2 \| Region Table \| Reserved (768KB) \|
	30	* \|----------\|---------------\|------------\|--------------\|--------------------\|
	31	* \| \| \| \| \| \|
	32	* 0.........64KB...........128KB........192KB..........256KB................1MB
	33	*/
	34
625565d2	35	#define VHDX_HEADER_BLOCK_SIZE (64 * 1024)
203cdba3 JC	36
203cdba3 JC	37	#define VHDX_FILE_ID_OFFSET 0
625565d2 JC	38	#define VHDX_HEADER1_OFFSET (VHDX_HEADER_BLOCK_SIZE * 1)
	39	#define VHDX_HEADER2_OFFSET (VHDX_HEADER_BLOCK_SIZE * 2)
	40	#define VHDX_REGION_TABLE_OFFSET (VHDX_HEADER_BLOCK_SIZE * 3)
3412f7b1	41	#define VHDX_REGION_TABLE2_OFFSET (VHDX_HEADER_BLOCK_SIZE * 4)
203cdba3	42
3412f7b1	43	#define VHDX_HEADER_SECTION_END (1 * MiB)
203cdba3 JC	44	/*
	45	* A note on the use of MS-GUID fields. For more details on the GUID,
	46	* please see: https://en.wikipedia.org/wiki/Globally_unique_identifier.
	47	*
	48	* The VHDX specification only states that these are MS GUIDs, and which
	49	* bytes are data1-data4. It makes no mention of what algorithm should be used
	50	* to generate the GUID, nor what standard. However, looking at the specified
	51	* known GUID fields, it appears the GUIDs are:
	52	* Standard/DCE GUID type (noted by 10b in the MSB of byte 0 of .data4)
	53	* Random algorithm (noted by 0x4XXX for .data3)
	54	*/
	55
	56	/* ---- HEADER SECTION STRUCTURES ---- */
	57
	58	/* These structures are ones that are defined in the VHDX specification
	59	* document */
	60
62e466e8	61	#define VHDX_FILE_SIGNATURE 0x656C696678646876ULL /* "vhdxfile" in ASCII */
203cdba3 JC	62	typedef struct VHDXFileIdentifier {
	63	uint64_t signature; /* "vhdxfile" in ASCII */
	64	uint16_t creator[256]; /* optional; utf-16 string to identify
61c02e56	65	the vhdx file creator. Diagnostic
203cdba3 JC	66	only */
	67	} VHDXFileIdentifier;
	68
	69
	70	/* the guid is a 16 byte unique ID - the definition for this used by
	71	* Microsoft is not just 16 bytes though - it is a structure that is defined,
	72	* so we need to follow it here so that endianness does not trip us up */
	73
4f18b782	74	typedef struct QEMU_PACKED MSGUID {
203cdba3 JC	75	uint32_t data1;
	76	uint16_t data2;
	77	uint16_t data3;
	78	uint8_t data4[8];
	79	} MSGUID;
	80
	81	#define guid_eq(a, b) \
	82	(memcmp(&(a), &(b), sizeof(MSGUID)) == 0)
	83
625565d2 JC	84	#define VHDX_HEADER_SIZE (4 * 1024) /* although the vhdx_header struct in disk
	85	is only 582 bytes, for purposes of crc
	86	the header is the first 4KB of the 64KB
	87	block */
203cdba3 JC	88
	89	/* The full header is 4KB, although the actual header data is much smaller.
	90	* But for the checksum calculation, it is over the entire 4KB structure,
	91	* not just the defined portion of it */
3412f7b1	92	#define VHDX_HEADER_SIGNATURE 0x64616568
203cdba3 JC	93	typedef struct QEMU_PACKED VHDXHeader {
	94	uint32_t signature; /* "head" in ASCII */
	95	uint32_t checksum; /* CRC-32C hash of the whole header */
	96	uint64_t sequence_number; /* Seq number of this header. Each
	97	VHDX file has 2 of these headers,
	98	and only the header with the highest
	99	sequence number is valid */
625565d2	100	MSGUID file_write_guid; /* 128 bit unique identifier. Must be
203cdba3 JC	101	updated to new, unique value before
	102	the first modification is made to
	103	file */
	104	MSGUID data_write_guid; /* 128 bit unique identifier. Must be
	105	updated to new, unique value before
	106	the first modification is made to
	107	visible data. Visbile data is
	108	defined as:
	109	- system & user metadata
	110	- raw block data
	111	- disk size
	112	- any change that will
	113	cause the virtual disk
	114	sector read to differ
	115
	116	This does not need to change if
	117	blocks are re-arranged */
	118	MSGUID log_guid; /* 128 bit unique identifier. If zero,
	119	there is no valid log. If non-zero,
	120	log entries with this guid are
	121	valid. */
61c02e56 JC	122	uint16_t log_version; /* version of the log format. Must be
61c02e56 JC	123	set to zero */
6e9d290b	124	uint16_t version; /* version of the vhdx file. Currently,
203cdba3 JC	125	only supported version is "1" */
	126	uint32_t log_length; /* length of the log. Must be multiple
	127	of 1MB */
	128	uint64_t log_offset; /* byte offset in the file of the log.
	129	Must also be a multiple of 1MB */
	130	} VHDXHeader;
	131
	132	/* Header for the region table block */
3412f7b1	133	#define VHDX_REGION_SIGNATURE 0x69676572 /* "regi" in ASCII */
203cdba3 JC	134	typedef struct QEMU_PACKED VHDXRegionTableHeader {
	135	uint32_t signature; /* "regi" in ASCII */
	136	uint32_t checksum; /* CRC-32C hash of the 64KB table */
	137	uint32_t entry_count; /* number of valid entries */
	138	uint32_t reserved;
	139	} VHDXRegionTableHeader;
	140
	141	/* Individual region table entry. There may be a maximum of 2047 of these
	142	*
	143	* There are two known region table properties. Both are required.
	144	* BAT (block allocation table): 2DC27766F62342009D64115E9BFD4A08
	145	* Metadata: 8B7CA20647904B9AB8FE575F050F886E
	146	*/
	147	#define VHDX_REGION_ENTRY_REQUIRED 0x01 /* if set, parser must understand
	148	this entry in order to open
	149	file */
	150	typedef struct QEMU_PACKED VHDXRegionTableEntry {
	151	MSGUID guid; /* 128-bit unique identifier */
	152	uint64_t file_offset; /* offset of the object in the file.
	153	Must be multiple of 1MB */
	154	uint32_t length; /* length, in bytes, of the object */
	155	uint32_t data_bits;
	156	} VHDXRegionTableEntry;
	157
	158
	159	/* ---- LOG ENTRY STRUCTURES ---- */
625565d2 JC	160	#define VHDX_LOG_MIN_SIZE (1024 * 1024)
625565d2 JC	161	#define VHDX_LOG_SECTOR_SIZE 4096
203cdba3	162	#define VHDX_LOG_HDR_SIZE 64
625565d2	163	#define VHDX_LOG_SIGNATURE 0x65676f6c
203cdba3 JC	164	typedef struct QEMU_PACKED VHDXLogEntryHeader {
	165	uint32_t signature; /* "loge" in ASCII */
	166	uint32_t checksum; /* CRC-32C hash of the 64KB table */
	167	uint32_t entry_length; /* length in bytes, multiple of 1MB */
	168	uint32_t tail; /* byte offset of first log entry of a
	169	seq, where this entry is the last
	170	entry */
	171	uint64_t sequence_number; /* incremented with each log entry.
	172	May not be zero. */
	173	uint32_t descriptor_count; /* number of descriptors in this log
	174	entry, must be >= 0 */
	175	uint32_t reserved;
	176	MSGUID log_guid; /* value of the log_guid from
	177	vhdx_header. If not found in
	178	vhdx_header, it is invalid */
	179	uint64_t flushed_file_offset; /* see spec for full details - this
52f35022	180	should be vhdx file size in bytes */
203cdba3 JC	181	uint64_t last_file_offset; /* size in bytes that all allocated
	182	file structures fit into */
	183	} VHDXLogEntryHeader;
	184
	185	#define VHDX_LOG_DESC_SIZE 32
625565d2 JC	186	#define VHDX_LOG_DESC_SIGNATURE 0x63736564
625565d2 JC	187	#define VHDX_LOG_ZERO_SIGNATURE 0x6f72657a
203cdba3 JC	188	typedef struct QEMU_PACKED VHDXLogDescriptor {
	189	uint32_t signature; /* "zero" or "desc" in ASCII */
	190	union {
	191	uint32_t reserved; /* zero desc */
	192	uint32_t trailing_bytes; /* data desc: bytes 4092-4096 of the
	193	data sector */
	194	};
	195	union {
	196	uint64_t zero_length; /* zero desc: length of the section to
	197	zero */
	198	uint64_t leading_bytes; /* data desc: bytes 0-7 of the data
	199	sector */
	200	};
	201	uint64_t file_offset; /* file offset to write zeros - multiple
	202	of 4kB */
	203	uint64_t sequence_number; /* must match same field in
	204	vhdx_log_entry_header */
	205	} VHDXLogDescriptor;
	206
625565d2	207	#define VHDX_LOG_DATA_SIGNATURE 0x61746164
203cdba3 JC	208	typedef struct QEMU_PACKED VHDXLogDataSector {
	209	uint32_t data_signature; /* "data" in ASCII */
	210	uint32_t sequence_high; /* 4 MSB of 8 byte sequence_number */
	211	uint8_t data[4084]; /* raw data, bytes 8-4091 (inclusive).
	212	see the data descriptor field for the
	213	other mising bytes */
	214	uint32_t sequence_low; /* 4 LSB of 8 byte sequence_number */
	215	} VHDXLogDataSector;
	216
	217
	218
	219	/* block states - different state values depending on whether it is a
	220	* payload block, or a sector block. */
	221
	222	#define PAYLOAD_BLOCK_NOT_PRESENT 0
	223	#define PAYLOAD_BLOCK_UNDEFINED 1
	224	#define PAYLOAD_BLOCK_ZERO 2
a9d1e9da JC	225	#define PAYLOAD_BLOCK_UNMAPPED 3
a9d1e9da JC	226	#define PAYLOAD_BLOCK_UNMAPPED_v095 5
d92aa883	227	#define PAYLOAD_BLOCK_FULLY_PRESENT 6
203cdba3 JC	228	#define PAYLOAD_BLOCK_PARTIALLY_PRESENT 7
	229
	230	#define SB_BLOCK_NOT_PRESENT 0
	231	#define SB_BLOCK_PRESENT 6
	232
	233	/* per the spec */
625565d2	234	#define VHDX_MAX_SECTORS_PER_BLOCK (1 << 23)
203cdba3 JC	235
	236	/* upper 44 bits are the file offset in 1MB units lower 3 bits are the state
	237	other bits are reserved */
	238	#define VHDX_BAT_STATE_BIT_MASK 0x07
62e466e8	239	#define VHDX_BAT_FILE_OFF_MASK 0xFFFFFFFFFFF00000ULL /* upper 44 bits */
203cdba3 JC	240	typedef uint64_t VHDXBatEntry;
	241
	242	/* ---- METADATA REGION STRUCTURES ---- */
	243
	244	#define VHDX_METADATA_ENTRY_SIZE 32
	245	#define VHDX_METADATA_MAX_ENTRIES 2047 /* not including the header */
	246	#define VHDX_METADATA_TABLE_MAX_SIZE \
	247	(VHDX_METADATA_ENTRY_SIZE * (VHDX_METADATA_MAX_ENTRIES+1))
62e466e8	248	#define VHDX_METADATA_SIGNATURE 0x617461646174656DULL /* "metadata" in ASCII */
203cdba3 JC	249	typedef struct QEMU_PACKED VHDXMetadataTableHeader {
	250	uint64_t signature; /* "metadata" in ASCII */
	251	uint16_t reserved;
	252	uint16_t entry_count; /* number table entries. <= 2047 */
	253	uint32_t reserved2[5];
	254	} VHDXMetadataTableHeader;
	255
	256	#define VHDX_META_FLAGS_IS_USER 0x01 /* max 1024 entries */
	257	#define VHDX_META_FLAGS_IS_VIRTUAL_DISK 0x02 /* virtual disk metadata if set,
	258	otherwise file metdata */
	259	#define VHDX_META_FLAGS_IS_REQUIRED 0x04 /* parse must understand this
	260	entry to open the file */
	261	typedef struct QEMU_PACKED VHDXMetadataTableEntry {
	262	MSGUID item_id; /* 128-bit identifier for metadata */
	263	uint32_t offset; /* byte offset of the metadata. At
	264	least 64kB. Relative to start of
	265	metadata region */
	266	/* note: if length = 0, so is offset */
	267	uint32_t length; /* length of metadata. <= 1MB. */
625565d2 JC	268	uint32_t data_bits; /* least-significant 3 bits are flags,
625565d2 JC	269	the rest are reserved (see above) */
203cdba3 JC	270	uint32_t reserved2;
	271	} VHDXMetadataTableEntry;
	272
	273	#define VHDX_PARAMS_LEAVE_BLOCKS_ALLOCED 0x01 /* Do not change any blocks to
	274	be BLOCK_NOT_PRESENT.
	275	If set indicates a fixed
	276	size VHDX file */
	277	#define VHDX_PARAMS_HAS_PARENT 0x02 /* has parent / backing file */
3412f7b1 JC	278	#define VHDX_BLOCK_SIZE_MIN (1 * MiB)
3412f7b1 JC	279	#define VHDX_BLOCK_SIZE_MAX (256 * MiB)
203cdba3 JC	280	typedef struct QEMU_PACKED VHDXFileParameters {
	281	uint32_t block_size; /* size of each payload block, always
	282	power of 2, <= 256MB and >= 1MB. */
625565d2 JC	283	uint32_t data_bits; /* least-significant 2 bits are flags,
625565d2 JC	284	the rest are reserved (see above) */
203cdba3 JC	285	} VHDXFileParameters;
203cdba3 JC	286
3412f7b1	287	#define VHDX_MAX_IMAGE_SIZE ((uint64_t) 64 * TiB)
203cdba3 JC	288	typedef struct QEMU_PACKED VHDXVirtualDiskSize {
	289	uint64_t virtual_disk_size; /* Size of the virtual disk, in bytes.
	290	Must be multiple of the sector size,
	291	max of 64TB */
	292	} VHDXVirtualDiskSize;
	293
	294	typedef struct QEMU_PACKED VHDXPage83Data {
61c02e56	295	MSGUID page_83_data; /* unique id for scsi devices that
203cdba3 JC	296	support page 0x83 */
	297	} VHDXPage83Data;
	298
	299	typedef struct QEMU_PACKED VHDXVirtualDiskLogicalSectorSize {
	300	uint32_t logical_sector_size; /* virtual disk sector size (in bytes).
	301	Can only be 512 or 4096 bytes */
	302	} VHDXVirtualDiskLogicalSectorSize;
	303
	304	typedef struct QEMU_PACKED VHDXVirtualDiskPhysicalSectorSize {
	305	uint32_t physical_sector_size; /* physical sector size (in bytes).
	306	Can only be 512 or 4096 bytes */
	307	} VHDXVirtualDiskPhysicalSectorSize;
	308
	309	typedef struct QEMU_PACKED VHDXParentLocatorHeader {
61c02e56	310	MSGUID locator_type; /* type of the parent virtual disk. */
203cdba3 JC	311	uint16_t reserved;
	312	uint16_t key_value_count; /* number of key/value pairs for this
	313	locator */
	314	} VHDXParentLocatorHeader;
	315
	316	/* key and value strings are UNICODE strings, UTF-16 LE encoding, no NULs */
	317	typedef struct QEMU_PACKED VHDXParentLocatorEntry {
	318	uint32_t key_offset; /* offset in metadata for key, > 0 */
	319	uint32_t value_offset; /* offset in metadata for value, >0 */
	320	uint16_t key_length; /* length of entry key, > 0 */
	321	uint16_t value_length; /* length of entry value, > 0 */
	322	} VHDXParentLocatorEntry;
	323
	324
	325	/* ----- END VHDX SPECIFICATION STRUCTURES ---- */
	326
28541d46 JC	327	typedef struct VHDXMetadataEntries {
	328	VHDXMetadataTableEntry file_parameters_entry;
	329	VHDXMetadataTableEntry virtual_disk_size_entry;
	330	VHDXMetadataTableEntry page83_data_entry;
	331	VHDXMetadataTableEntry logical_sector_size_entry;
	332	VHDXMetadataTableEntry phys_sector_size_entry;
	333	VHDXMetadataTableEntry parent_locator_entry;
	334	uint16_t present;
	335	} VHDXMetadataEntries;
	336
625565d2 JC	337	typedef struct VHDXLogEntries {
	338	uint64_t offset;
	339	uint64_t length;
0a43a1b5 JC	340	uint32_t write;
	341	uint32_t read;
	342	VHDXLogEntryHeader *hdr;
	343	void *desc_buffer;
	344	uint64_t sequence;
625565d2 JC	345	uint32_t tail;
	346	} VHDXLogEntries;
	347
1a848fd4 JC	348	typedef struct VHDXRegionEntry {
	349	uint64_t start;
	350	uint64_t end;
	351	QLIST_ENTRY(VHDXRegionEntry) entries;
	352	} VHDXRegionEntry;
	353
28541d46 JC	354	typedef struct BDRVVHDXState {
	355	CoMutex lock;
	356
	357	int curr_header;
	358	VHDXHeader *headers[2];
	359
	360	VHDXRegionTableHeader rt;
	361	VHDXRegionTableEntry bat_rt; /* region table for the BAT */
	362	VHDXRegionTableEntry metadata_rt; /* region table for the metadata */
	363
	364	VHDXMetadataTableHeader metadata_hdr;
	365	VHDXMetadataEntries metadata_entries;
	366
	367	VHDXFileParameters params;
	368	uint32_t block_size;
	369	uint32_t block_size_bits;
	370	uint32_t sectors_per_block;
	371	uint32_t sectors_per_block_bits;
	372
	373	uint64_t virtual_disk_size;
	374	uint32_t logical_sector_size;
	375	uint32_t physical_sector_size;
	376
	377	uint64_t chunk_ratio;
	378	uint32_t chunk_ratio_bits;
	379	uint32_t logical_sector_size_bits;
	380
	381	uint32_t bat_entries;
	382	VHDXBatEntry *bat;
	383	uint64_t bat_offset;
	384
c3906c5e	385	bool first_visible_write;
28541d46 JC	386	MSGUID session_guid;
28541d46 JC	387
625565d2 JC	388	VHDXLogEntries log;
625565d2 JC	389
28541d46 JC	390	VHDXParentLocatorHeader parent_header;
	391	VHDXParentLocatorEntry *parent_entries;
	392
	393	Error *migration_blocker;
1a848fd4	394
7e30e6a6 JC	395	bool log_replayed_on_open;
7e30e6a6 JC	396
b58deb34	397	QLIST_HEAD(, VHDXRegionEntry) regions;
28541d46	398	} BDRVVHDXState;
e8d4e5ff	399
4f18b782 JC	400	void vhdx_guid_generate(MSGUID *guid);
4f18b782 JC	401
c3906c5e JC	402	int vhdx_update_headers(BlockDriverState bs, BDRVVHDXState s, bool rw,
	403	MSGUID *log_guid);
	404
4f18b782	405	uint32_t vhdx_update_checksum(uint8_t *buf, size_t size, int crc_offset);
e8d4e5ff JC	406	uint32_t vhdx_checksum_calc(uint32_t crc, uint8_t *buf, size_t size,
	407	int crc_offset);
	408
	409	bool vhdx_checksum_is_valid(uint8_t *buf, size_t size, int crc_offset);
	410
7e30e6a6 JC	411	int vhdx_parse_log(BlockDriverState bs, BDRVVHDXState s, bool *flushed,
7e30e6a6 JC	412	Error **errp);
e8d4e5ff	413
8adc5233 JC	414	int vhdx_log_write_and_flush(BlockDriverState bs, BDRVVHDXState s,
	415	void *data, uint32_t length, uint64_t offset);
	416
4f18b782	417	static inline void leguid_to_cpus(MSGUID *guid)
e8d4e5ff	418	{
1229e46d PM	419	guid->data1 = le32_to_cpu(guid->data1);
	420	guid->data2 = le16_to_cpu(guid->data2);
	421	guid->data3 = le16_to_cpu(guid->data3);
e8d4e5ff JC	422	}
e8d4e5ff JC	423
4f18b782 JC	424	static inline void cpu_to_leguids(MSGUID *guid)
4f18b782 JC	425	{
1229e46d PM	426	guid->data1 = cpu_to_le32(guid->data1);
	427	guid->data2 = cpu_to_le16(guid->data2);
	428	guid->data3 = cpu_to_le16(guid->data3);
4f18b782 JC	429	}
4f18b782 JC	430
0f48e8f0 JC	431	void vhdx_header_le_import(VHDXHeader *h);
	432	void vhdx_header_le_export(VHDXHeader orig_h, VHDXHeader new_h);
	433	void vhdx_log_desc_le_import(VHDXLogDescriptor *d);
	434	void vhdx_log_desc_le_export(VHDXLogDescriptor *d);
4f75b52a	435	void vhdx_log_data_le_import(VHDXLogDataSector *d);
0f48e8f0 JC	436	void vhdx_log_data_le_export(VHDXLogDataSector *d);
	437	void vhdx_log_entry_hdr_le_import(VHDXLogEntryHeader *hdr);
	438	void vhdx_log_entry_hdr_le_export(VHDXLogEntryHeader *hdr);
c325ee1d JC	439	void vhdx_region_header_le_import(VHDXRegionTableHeader *hdr);
	440	void vhdx_region_header_le_export(VHDXRegionTableHeader *hdr);
	441	void vhdx_region_entry_le_import(VHDXRegionTableEntry *e);
	442	void vhdx_region_entry_le_export(VHDXRegionTableEntry *e);
	443	void vhdx_metadata_header_le_import(VHDXMetadataTableHeader *hdr);
	444	void vhdx_metadata_header_le_export(VHDXMetadataTableHeader *hdr);
	445	void vhdx_metadata_entry_le_import(VHDXMetadataTableEntry *e);
	446	void vhdx_metadata_entry_le_export(VHDXMetadataTableEntry *e);
c3906c5e JC	447	int vhdx_user_visible_write(BlockDriverState bs, BDRVVHDXState s);
c3906c5e JC	448
203cdba3	449	#endif