[qemu.git] / block / vhdx.h

/*
 * Block driver for Hyper-V VHDX Images
 *
 * Copyright (c) 2013 Red Hat, Inc.,
 *
 * Authors:
 *  Jeff Cody <[email protected]>
 *
 *  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

#define KiB              (1 * 1024)
#define MiB            (KiB * 1024)
#define GiB            (MiB * 1024)
#define TiB ((uint64_t) GiB * 1024)

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