From: Peter Maydell Date: Fri, 9 Aug 2024 16:37:55 +0000 (+0100) Subject: docs/interop/parallels.txt: Convert to rST X-Git-Tag: qemu-xen-4.20.0~23^2~5 X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=1bc0fc0a0b2a25b10008b0dc870ca87e2a090006;p=qemu-xen.git docs/interop/parallels.txt: Convert to rST Convert parallels.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson Reviewed-by: Eric Blake Message-id: 20240801170131.3977807-4-peter.maydell@linaro.org --- diff --git a/MAINTAINERS b/MAINTAINERS index 04a1fd0850..ae8bed8c75 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3964,7 +3964,7 @@ L: qemu-block@nongnu.org S: Supported F: block/parallels.c F: block/parallels-ext.c -F: docs/interop/parallels.txt +F: docs/interop/parallels.rst T: git https://src.openvz.org/scm/~den/qemu.git parallels qed diff --git a/docs/interop/index.rst b/docs/interop/index.rst index b9ceaabc64..70bba62d90 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -15,6 +15,7 @@ are useful for making QEMU interoperate with other software. dbus-display live-block-operations nbd + parallels pr-helper qmp-spec qemu-ga diff --git a/docs/interop/parallels.rst b/docs/interop/parallels.rst new file mode 100644 index 0000000000..7b328a40c8 --- /dev/null +++ b/docs/interop/parallels.rst @@ -0,0 +1,240 @@ +Parallels Expandable Image File Format +====================================== + +.. + Copyright (c) 2015 Denis Lunev + Copyright (c) 2015 Vladimir Sementsov-Ogievskiy + + This work is licensed under the terms of the GNU GPL, version 2 or later. + See the COPYING file in the top-level directory. + + +A Parallels expandable image file consists of three consecutive parts: + +* header +* BAT +* data area + +All numbers in a Parallels expandable image are stored in little-endian byte +order. + + +Definitions +----------- + +Sector + A 512-byte data chunk. + +Cluster + A data chunk of the size specified in the image header. + Currently, the default size is 1MiB (2048 sectors). In previous + versions, cluster sizes of 63 sectors, 256 and 252 kilobytes were used. + +BAT + Block Allocation Table, an entity that contains information for + guest-to-host I/O data address translation. + +Header +------ + +The header is placed at the start of an image and contains the following +fields:: + + Bytes: + 0 - 15: magic + Must contain "WithoutFreeSpace" or "WithouFreSpacExt". + + 16 - 19: version + Must be 2. + + 20 - 23: heads + Disk geometry parameter for guest. + + 24 - 27: cylinders + Disk geometry parameter for guest. + + 28 - 31: tracks + Cluster size, in sectors. + + 32 - 35: nb_bat_entries + Disk size, in clusters (BAT size). + + 36 - 43: nb_sectors + Disk size, in sectors. + + For "WithoutFreeSpace" images: + Only the lowest 4 bytes are used. The highest 4 bytes must be + cleared in this case. + + For "WithouFreSpacExt" images, there are no such + restrictions. + + 44 - 47: in_use + Set to 0x746F6E59 when the image is opened by software in R/W + mode; set to 0x312e3276 when the image is closed. + + A zero in this field means that the image was opened by an old + version of the software that doesn't support Format Extension + (see below). + + Other values are not allowed. + + 48 - 51: data_off + An offset, in sectors, from the start of the file to the start of + the data area. + + For "WithoutFreeSpace" images: + - If data_off is zero, the offset is calculated as the end of BAT + table plus some padding to ensure sector size alignment. + - If data_off is non-zero, the offset should be aligned to sector + size. However it is recommended to align it to cluster size for + newly created images. + + For "WithouFreSpacExt" images: + data_off must be non-zero and aligned to cluster size. + + 52 - 55: flags + Miscellaneous flags. + + Bit 0: Empty Image bit. If set, the image should be + considered clear. + + Bits 1-31: Unused. + + 56 - 63: ext_off + Format Extension offset, an offset, in sectors, from the start of + the file to the start of the Format Extension Cluster. + + ext_off must meet the same requirements as cluster offsets + defined by BAT entries (see below). + +BAT +--- + +BAT is placed immediately after the image header. In the file, BAT is a +contiguous array of 32-bit unsigned little-endian integers with +``(bat_entries * 4)`` bytes size. + +Each BAT entry contains an offset from the start of the file to the +corresponding cluster. The offset set in clusters for ``WithouFreSpacExt`` +images and in sectors for ``WithoutFreeSpace`` images. + +If a BAT entry is zero, the corresponding cluster is not allocated and should +be considered as filled with zeroes. + +Cluster offsets specified by BAT entries must meet the following requirements: + +- the value must not be lower than data offset (provided by ``header.data_off`` + or calculated as specified above) +- the value must be lower than the desired file size +- the value must be unique among all BAT entries +- the result of ``(cluster offset - data offset)`` must be aligned to + cluster size + +Data Area +--------- + +The data area is an area from the data offset (provided by ``header.data_off`` +or calculated as specified above) to the end of the file. It represents a +contiguous array of clusters. Most of them are allocated by the BAT, some may +be allocated by the ``ext_off`` field in the header while other may be +allocated by extensions. All clusters allocated by ``ext_off`` and extensions +should meet the same requirements as clusters specified by BAT entries. + + +Format Extension +---------------- + +The Format Extension is an area 1 cluster in size that provides additional +format features. This cluster is addressed by the ext_off field in the header. +The format of the Format Extension area is the following:: + + 0 - 7: magic + Must be 0xAB234CEF23DCEA87 + + 8 - 23: m_CheckSum + The MD5 checksum of the entire Header Extension cluster except + the first 24 bytes. + +The above are followed by feature sections or "extensions". The last +extension must be "End of features" (see below). + +Each feature section has the following format:: + + 0 - 7: magic + The identifier of the feature: + 0x0000000000000000 - End of features + 0x20385FAE252CB34A - Dirty bitmap + + 8 - 15: flags + External flags for extension: + + Bit 0: NECESSARY + If the software cannot load the extension (due to an + unknown magic number or error), the file should not be + changed. If this flag is unset and there is an error on + loading the extension, said extension should be dropped. + + Bit 1: TRANSIT + If there is an unknown extension with this flag set, + said extension should be left as is. + + If neither NECESSARY nor TRANSIT are set, the extension should be + dropped. + + 16 - 19: data_size + The size of the following feature data, in bytes. + + 20 - 23: unused32 + Align header to 8 bytes boundary. + + variable: data (data_size bytes) + +The above is followed by padding to the next 8 bytes boundary, then the +next extension starts. + +The last extension must be "End of features" with all the fields set to 0. + + +Dirty bitmaps feature +--------------------- + +This feature provides a way of storing dirty bitmaps in the image. The fields +of its data area are:: + + 0 - 7: size + The bitmap size, should be equal to disk size in sectors. + + 8 - 23: id + An identifier for backup consistency checking. + + 24 - 27: granularity + Bitmap granularity, in sectors. I.e., the number of sectors + corresponding to one bit of the bitmap. Granularity must be + a power of 2. + + 28 - 31: l1_size + The number of entries in the L1 table of the bitmap. + + variable: L1 offset table (l1_table), size: 8 * l1_size bytes + +The dirty bitmap described by this feature extension is stored in a set of +clusters inside the Parallels image file. The offsets of these clusters are +saved in the L1 offset table specified by the feature extension. Each L1 table +entry is a 64 bit integer as described below: + +Given an offset in bytes into the bitmap data, corresponding L1 entry is:: + + l1_table[offset / cluster_size] + +If an L1 table entry is 0, all bits in the corresponding cluster of the bitmap +are assumed to be 0. + +If an L1 table entry is 1, all bits in the corresponding cluster of the bitmap +are assumed to be 1. + +If an L1 table entry is not 0 or 1, it contains the corresponding cluster +offset (in 512b sectors). Given an offset in bytes into the bitmap data the +offset in bytes into the image file can be obtained as follows:: + + offset = l1_table[offset / cluster_size] * 512 + (offset % cluster_size) diff --git a/docs/interop/parallels.txt b/docs/interop/parallels.txt deleted file mode 100644 index bb3fadf369..0000000000 --- a/docs/interop/parallels.txt +++ /dev/null @@ -1,232 +0,0 @@ -= License = - -Copyright (c) 2015 Denis Lunev -Copyright (c) 2015 Vladimir Sementsov-Ogievskiy - -This work is licensed under the terms of the GNU GPL, version 2 or later. -See the COPYING file in the top-level directory. - -= Parallels Expandable Image File Format = - -A Parallels expandable image file consists of three consecutive parts: - * header - * BAT - * data area - -All numbers in a Parallels expandable image are stored in little-endian byte -order. - - -== Definitions == - - Sector A 512-byte data chunk. - - Cluster A data chunk of the size specified in the image header. - Currently, the default size is 1MiB (2048 sectors). In previous - versions, cluster sizes of 63 sectors, 256 and 252 kilobytes were - used. - - BAT Block Allocation Table, an entity that contains information for - guest-to-host I/O data address translation. - - -== Header == - -The header is placed at the start of an image and contains the following -fields: - -Bytes: - 0 - 15: magic - Must contain "WithoutFreeSpace" or "WithouFreSpacExt". - - 16 - 19: version - Must be 2. - - 20 - 23: heads - Disk geometry parameter for guest. - - 24 - 27: cylinders - Disk geometry parameter for guest. - - 28 - 31: tracks - Cluster size, in sectors. - - 32 - 35: nb_bat_entries - Disk size, in clusters (BAT size). - - 36 - 43: nb_sectors - Disk size, in sectors. - - For "WithoutFreeSpace" images: - Only the lowest 4 bytes are used. The highest 4 bytes must be - cleared in this case. - - For "WithouFreSpacExt" images, there are no such - restrictions. - - 44 - 47: in_use - Set to 0x746F6E59 when the image is opened by software in R/W - mode; set to 0x312e3276 when the image is closed. - - A zero in this field means that the image was opened by an old - version of the software that doesn't support Format Extension - (see below). - - Other values are not allowed. - - 48 - 51: data_off - An offset, in sectors, from the start of the file to the start of - the data area. - - For "WithoutFreeSpace" images: - - If data_off is zero, the offset is calculated as the end of BAT - table plus some padding to ensure sector size alignment. - - If data_off is non-zero, the offset should be aligned to sector - size. However it is recommended to align it to cluster size for - newly created images. - - For "WithouFreSpacExt" images: - data_off must be non-zero and aligned to cluster size. - - 52 - 55: flags - Miscellaneous flags. - - Bit 0: Empty Image bit. If set, the image should be - considered clear. - - Bits 1-31: Unused. - - 56 - 63: ext_off - Format Extension offset, an offset, in sectors, from the start of - the file to the start of the Format Extension Cluster. - - ext_off must meet the same requirements as cluster offsets - defined by BAT entries (see below). - - -== BAT == - -BAT is placed immediately after the image header. In the file, BAT is a -contiguous array of 32-bit unsigned little-endian integers with -(bat_entries * 4) bytes size. - -Each BAT entry contains an offset from the start of the file to the -corresponding cluster. The offset set in clusters for "WithouFreSpacExt" images -and in sectors for "WithoutFreeSpace" images. - -If a BAT entry is zero, the corresponding cluster is not allocated and should -be considered as filled with zeroes. - -Cluster offsets specified by BAT entries must meet the following requirements: - - the value must not be lower than data offset (provided by header.data_off - or calculated as specified above), - - the value must be lower than the desired file size, - - the value must be unique among all BAT entries, - - the result of (cluster offset - data offset) must be aligned to cluster - size. - - -== Data Area == - -The data area is an area from the data offset (provided by header.data_off or -calculated as specified above) to the end of the file. It represents a -contiguous array of clusters. Most of them are allocated by the BAT, some may -be allocated by the ext_off field in the header while other may be allocated by -extensions. All clusters allocated by ext_off and extensions should meet the -same requirements as clusters specified by BAT entries. - - -== Format Extension == - -The Format Extension is an area 1 cluster in size that provides additional -format features. This cluster is addressed by the ext_off field in the header. -The format of the Format Extension area is the following: - - 0 - 7: magic - Must be 0xAB234CEF23DCEA87 - - 8 - 23: m_CheckSum - The MD5 checksum of the entire Header Extension cluster except - the first 24 bytes. - - The above are followed by feature sections or "extensions". The last - extension must be "End of features" (see below). - -Each feature section has the following format: - - 0 - 7: magic - The identifier of the feature: - 0x0000000000000000 - End of features - 0x20385FAE252CB34A - Dirty bitmap - - 8 - 15: flags - External flags for extension: - - Bit 0: NECESSARY - If the software cannot load the extension (due to an - unknown magic number or error), the file should not be - changed. If this flag is unset and there is an error on - loading the extension, said extension should be dropped. - - Bit 1: TRANSIT - If there is an unknown extension with this flag set, - said extension should be left as is. - - If neither NECESSARY nor TRANSIT are set, the extension should be - dropped. - - 16 - 19: data_size - The size of the following feature data, in bytes. - - 20 - 23: unused32 - Align header to 8 bytes boundary. - - variable: data (data_size bytes) - - The above is followed by padding to the next 8 bytes boundary, then the - next extension starts. - - The last extension must be "End of features" with all the fields set to 0. - - -=== Dirty bitmaps feature === - -This feature provides a way of storing dirty bitmaps in the image. The fields -of its data area are: - - 0 - 7: size - The bitmap size, should be equal to disk size in sectors. - - 8 - 23: id - An identifier for backup consistency checking. - - 24 - 27: granularity - Bitmap granularity, in sectors. I.e., the number of sectors - corresponding to one bit of the bitmap. Granularity must be - a power of 2. - - 28 - 31: l1_size - The number of entries in the L1 table of the bitmap. - - variable: L1 offset table (l1_table), size: 8 * l1_size bytes - -The dirty bitmap described by this feature extension is stored in a set of -clusters inside the Parallels image file. The offsets of these clusters are -saved in the L1 offset table specified by the feature extension. Each L1 table -entry is a 64 bit integer as described below: - -Given an offset in bytes into the bitmap data, corresponding L1 entry is - - l1_table[offset / cluster_size] - -If an L1 table entry is 0, all bits in the corresponding cluster of the bitmap -are assumed to be 0. - -If an L1 table entry is 1, all bits in the corresponding cluster of the bitmap -are assumed to be 1. - -If an L1 table entry is not 0 or 1, it contains the corresponding cluster -offset (in 512b sectors). Given an offset in bytes into the bitmap data the -offset in bytes into the image file can be obtained as follows: - - offset = l1_table[offset / cluster_size] * 512 + (offset % cluster_size)