[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 */
/* Note: can't use 1 * MiB, because it's passed to stringify() */

/* 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 * KiB)

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