[Qemu-devel] [PATCH 1/6 v10] docs: spec for add-cow file format

[Dong Xu Wang <wdongxu@linux.vnet.ibm.com>]

Introduce a new file format:add-cow. The usage can be found at this patch.

Signed-off-by: Dong Xu Wang <wdongxu@linux.vnet.ibm.com>
---
 docs/specs/add-cow.txt |   87 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 87 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..e077fc2
--- /dev/null
+++ b/docs/specs/add-cow.txt
@@ -0,0 +1,87 @@
+== 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
+
+=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:
+
+    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_filename_offset
+                        Offset in the add-cow file at which the backing file name
+                        is stored (NB: The string is not null terminated). 0 if the
+                        image doesn't have a backing file.
+
+            16 - 19:    backing_filename_size
+                        Length of the backing file name in bytes. Undefined if the
+                        image doesn't have a backing file.
+
+            20 - 23:    image_filename_offset
+                        Offset in the add-cow file at which the image_file name
+                        is stored (NB: The string is not null terminated).
+
+            24 - 27:    image_filename_size
+                        Length of the image_file name in bytes.
+
+            28 - 35:    features
+                        Currently only 2 feature bits are used:
+                        Feature bits:
+                            The image uses a backing file:
+                            * ADD_COW_F_BACKING_FILE = 0x01.
+                            The backing file's format is raw:
+                            * ADD_COW_F_BACKING_FORMAT_NO_PROBE = 0x02.
+
+== Reserved ==
+
+    Byte    36 - 4095:  Reserved field:
+                        It is used to make sure COW bitmap field starts at the
+                        4096th 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, So the size of bitmap is
+calculated according to virtual size of image_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.
-- 
1.7.1