From: Dong Xu Wang
Document for add-cow format, the usage and spec of add-cow are
introduced.
v18-v19:
1) backing_fmt and image_fmt NUL-terminated.
2) other fix.
V17->V18:
1) remove version field.
2) header size is maximum value and cluster size value.
3) fix type.
Signed-off-by: Dong Xu Wang
Signed-off-by: Dongxu Wang
---
docs/specs/add-cow.txt | 172 +
1 file changed, 172 insertions(+)
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 000..fba74dd
--- /dev/null
+++ b/docs/specs/add-cow.txt
@@ -0,0 +1,172 @@
+== 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 an image by keeping a separate .add-cow metadata file.
+Once all clusters have been written into the image it is safe to
+discard the .add-cow and backing files, then we can use the image
+directly.
+
+An example usage of add-cow would look like:
+(ubuntu.img is a disk image which has an installed OS.)
+1) Create an image, such as raw format, 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.
+
+image_fmt can be omitted, in that case image_fmt is assumed to be
+"raw". backing_fmt can also be omitted, add-cow should do a probe
+operation and determine what the backing file's format is. It is
+recommended to always specify the format for any raw file, because
+probing a raw file is a security hole.
+
+=Specification=
+
+The file format looks like this:
+
+ +---+---+
+ | Header| COW bitmap |
+ +---+---+
+
+All numbers in add-cow are stored in Little Endian byte order.
+
+== Header ==
+
+The Header is included in the first bytes:
+(HEADER_SIZE is defined in 40-43 bytes.)
+Byte0 - 3:magic
+add-cow magic string ("ACOW"). It is coded in
+free-form ASCII.
+
+4 - 7: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 76 and [HEADER_SIZE
+- 2](a file name must be at least 1 byte).
+
+8 - 11: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 - 76] to fit in the reserved
+part of the header. Backing file name offset
++ size must be no more than HEADER_SIZE.
+
+12 - 15:image file name offset
+Offset in the add-cow file at which the image
+file name is stored (NB: The string is NOT
+NUL-terminated). It must be between 76 and
+[HEADER_SIZE - 2]. Image file name size + offset
+must be no more than HEADER_SIZE.
+
+16 - 19:image file name size
+Length of the image file name in bytes.
+Must be less than [HEADER_SIZE - 76] to fit in
+the reserved part of the header.
+
+20 - 23: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 12
+(i.e. 4096 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.
+
+24 - 31:features
+Bitmask of features. If a feature bit is set
+but not recognized, the opening add-cow file must
+fail. No features bits are currently defined.
+
+Bits 0-63: Reserved (set to 0)
+
+32 - 3
