From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:35378) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Seogy-0004fx-SQ for qemu-devel@nongnu.org; Wed, 13 Jun 2012 10:37:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Seogw-0001rs-TU for qemu-devel@nongnu.org; Wed, 13 Jun 2012 10:37:04 -0400 Received: from mail-pz0-f45.google.com ([209.85.210.45]:50041) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Seogw-0001rj-Ht for qemu-devel@nongnu.org; Wed, 13 Jun 2012 10:37:02 -0400 Received: by dadn2 with SMTP id n2so62418dad.4 for ; Wed, 13 Jun 2012 07:36:59 -0700 (PDT) Sender: Dong Xu Wang From: Dong Xu Wang Date: Wed, 13 Jun 2012 22:36:24 +0800 Message-Id: <1339598189-17933-1-git-send-email-wdongxu@linux.vnet.ibm.com> Subject: [Qemu-devel] [PATCH 1/6 v10] docs: spec for add-cow file format List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: kwolf@redhat.com, Dong Xu Wang Introduce a new file format:add-cow. The usage can be found at this patch. Signed-off-by: Dong Xu Wang --- 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