new file mode 100644
@@ -0,0 +1,128 @@
+== General ==
+Raw file format does not support backing file and 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.
+While using add-cow, procedures may like this:
+(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 by the size of ubuntu.img, test.raw will be used from the
+1st byte, the rest part can be used for other purpose.
+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_pages_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 null 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 - 35: features
+ Currently only 3 feature bit is used:
+ Feature bits:
+ The image uses a backing file:
+ * ADD_COW_F_BACKING_FILE = 0x01.
+ The image uses a image file:
+ * ADD_COW_F_IMAGE_FILE = 0x02.
+ All bits in bitmap have been set to 1, add-cow wrapper
+ can be discarded.
+ * ADD_COW_F_All_ALLOCATED = 0x04.
+ 36 - 43: optional features
+ Not used now. Researved for future use.
+ 44 - 47: header pages size
+ The header field is variable-sized. This field indicates
+ how many pages(4k) will be used to store add-cow header.
+ In add-cow v1, it is fixed to 1, so the header size will
+ be 4k * 1 = 4096 bytes.
+Image file name and backing file name must NOT be the same, we prevent this
+while creating add-cow files.
+Image file and backing file are interpreted relative to the qcow2 file, not
+to the current working directory of the process that opened the qcow2 file.
+== Reserved ==
+ Byte 48 - 63: 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 none-zero, it must be non-zero.
+ 64 - 79: image file format
+ format of image file. It must be non-zero.
+ 80 - [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.
+== COW bitmap ==
+The "COW bitmap" field starts at the 4096th byte, 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 indicates one cluster's status. One cluster includes 128
+sectors, then each bit indicates 512 * 128 = 64k bytes. the size of bitmap is
+calculated according to virtual size of backing file. In each byte, bit 0 to 7
+will track the 1st to 7th cluster in sequence, 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 will be 0.