[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH V13 1/6] docs: document for add-cow file format
From: |
Dong Xu Wang |
Subject: |
[Qemu-devel] [PATCH V13 1/6] docs: document for add-cow file format |
Date: |
Thu, 18 Oct 2012 17:51:30 +0800 |
Document for add-cow format, the usage and spec of add-cow are introduced.
Signed-off-by: Dong Xu Wang <address@hidden>
---
docs/specs/add-cow.txt | 139 ++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 139 insertions(+), 0 deletions(-)
create mode 100644 docs/specs/add-cow.txt
diff --git a/docs/specs/add-cow.txt b/docs/specs/add-cow.txt
new file mode 100644
index 0000000..dc1e107
--- /dev/null
+++ b/docs/specs/add-cow.txt
@@ -0,0 +1,139 @@
+== General ==
+
+The raw file format does not support backing files or copy on write feature.
+The add-cow image format makes it possible to use backing files with raw
+image by keeping a separate .add-cow metadata file. Once all sectors
+have been written into the raw image it is safe to discard the .add-cow
+and backing files, then we can use the raw image directly.
+
+An example usage of add-cow would look like::
+(ubuntu.img is a disk image which has been installed OS.)
+ 1) Create a raw image with the same size of ubuntu.img
+ qemu-img create -f raw test.raw 8G
+ 2) Create an add-cow image which will store dirty bitmap
+ qemu-img create -f add-cow test.add-cow \
+ -o backing_file=ubuntu.img,image_file=test.raw
+ 3) Run qemu with add-cow image
+ qemu -drive if=virtio,file=test.add-cow
+
+test.raw may be larger than ubuntu.img, in that case, the size of test.add-cow
+will be calculated from the size of test.raw.
+
+=Specification=
+
+The file format looks like this:
+
+ +---------------+-------------+-----------------+
+ | Header | Reserved | COW bitmap |
+ +---------------+-------------+-----------------+
+
+All numbers in add-cow are stored in Little Endian byte order.
+
+== Header ==
+
+The Header is included in the first bytes:
+(#define HEADER_SIZE (4096 * header_size))
+ Byte 0 - 7: magic
+ add-cow magic string ("ADD_COW\xff").
+
+ 8 - 11: version
+ Version number (only valid value is 1 now).
+
+ 12 - 15: backing file name offset
+ Offset in the add-cow file at which the backing file
+ name is stored (NB: The string is not nul-terminated).
+ If backing file name does NOT exist, this field will be
+ 0. Must be between 80 and [HEADER_SIZE - 2](a file name
+ must be at least 1 byte).
+
+ 16 - 19: backing file name size
+ Length of the backing file name in bytes. It will be 0
+ if the backing file name offset is 0. If backing file
+ name offset is non-zero, then it must be non-zero. Must
+ be less than [HEADER_SIZE - 80] to fit in the reserved
+ part of the header.
+
+ 20 - 23: image file name offset
+ Offset in the add-cow file at which the image file name
+ is stored (NB: The string is not null terminated). It
+ must be between 80 and [HEADER_SIZE - 2].
+
+ 24 - 27: image file name size
+ Length of the image file name in bytes.
+ Must be less than [HEADER_SIZE - 80] to fit in the
reserved
+ part of the header.
+
+ 28 - 31: cluster bits
+ Number of bits that are used for addressing an offset
+ within a cluster (1 << cluster_bits is the cluster
size).
+ Must not be less than 9 (i.e. 512 byte clusters).
+
+ Note: qemu as of today has an implementation limit of
2 MB
+ as the maximum cluster size and won't be able to open
images
+ with larger cluster sizes.
+
+ 32 - 39: features
+ Bitmask of features. An implementation can safely
ignore
+ any unknown bits that are set.
+
+ Bit 0: All allocated bit. If this bit is set then
+ backing file and COW bitmap will not be
used,
+ and can read from or write to image file
directly.
+
+ Bits 1-63: Reserved (set to 0)
+
+ 40 - 47: optional features
+ Not used now. Reserved for future use. It must be set
to 0.
+ And must be ignored while reading.
+
+ 48 - 51: header size
+ The header field is variable-sized. This field
indicates
+ how many 4096 bytes will be used to store add-cow
header.
+ In add-cow v1, it is fixed to 1, so the header size
will
+ be 4096 * 1 = 4096 bytes.
+
+ 52 - 67: backing file format
+ Format of backing file. It will be filled with 0 if
+ backing file name offset is 0. If backing file name
+ offset is non-empty, it must be non-empty. It is coded
+ in free-form ASCII, and is not NUL-terminated. Zero
+ padded on the right.
+
+ 68 - 83: image file format
+ Format of image file. It must be non-empty. It is coded
+ in free-form ASCII, and is not NUL-terminated. Zero
+ padded on the right.
+
+ 84 - [HEADER_SIZE - 1]:
+ It is used to make sure COW bitmap field starts at the
+ HEADER_SIZE byte, backing file name and image file name
+ will be stored here. The bytes that is not pointing to
+ backing file and image file names must be set to 0.
+
+== COW bitmap ==
+
+The "COW bitmap" field starts at offset HEADER_SIZE, stores a bitmap related to
+backing file and image file. The bitmap will track whether the sector in
+backing file is dirty or not.
+
+Each bit in the bitmap tracks one cluster's status. For example, if cluster
+bit is 16, then each bit tracks one cluster, (1 >> 16) = 65536 bytes. The size
+of bitmap is calculated according to virtual size of image file, and it must
+be multiple of 65536, the bits not used will be set to 0. Within each byte,
+the least significant bit covers the first cluster. Bit orders in one
+byte look like:
+ +----+----+----+----+----+----+----+----+
+ | b7 | b6 | b5 | b4 | b3 | b2 | b1 | b0 |
+ +----+----+----+----+----+----+----+----+
+
+If the bit is 0, indicates the sector has not been allocated in image file,
data
+should be loaded from backing file while reading; if the bit is 1, indicates
the
+related sector has been dirty, should be loaded from image file while reading.
+Writing to a sector causes the corresponding bit to be set to 1.
+
+If raw image is not an even multiple of cluster bytes, bits that correspond to
+bytes beyond the raw file size in add-cow must be written as 0 and must be
+ignored when reading.
+
+Image file name and backing file name must NOT be the same, we prevent this
+while creating add-cow files.
--
1.7.1
- [Qemu-devel] [PATCH V13 0/6] add-cow file format, Dong Xu Wang, 2012/10/18
- [Qemu-devel] [PATCH V13 2/6] make path_has_protocol non static, Dong Xu Wang, 2012/10/18
- [Qemu-devel] [PATCH V13 1/6] docs: document for add-cow file format,
Dong Xu Wang <=
- [Qemu-devel] [PATCH V13 3/6] qed_read_string to bdrv_read_string, Dong Xu Wang, 2012/10/18
- [Qemu-devel] [PATCH V13 6/6] qemu-iotests: add add-cow iotests support., Dong Xu Wang, 2012/10/18
- [Qemu-devel] [PATCH V13 4/6] rename qcow2-cache.c to block-cache.c, Dong Xu Wang, 2012/10/18
- [Qemu-devel] [PATCH V13 5/6] add-cow file format core code., Dong Xu Wang, 2012/10/18