From patchwork Wed Jun 13 14:36:24 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Robert Wang X-Patchwork-Id: 164698 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 97B1BB7046 for ; Thu, 14 Jun 2012 00:37:17 +1000 (EST) Received: from localhost ([::1]:37711 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Seoh9-0004gK-Rr for incoming@patchwork.ozlabs.org; Wed, 13 Jun 2012 10:37:15 -0400 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) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:date:message-id:x-mailer; bh=KR2DQxiKn16vVZuU6jJCDGlUyI5HfA3RynrCuM/WieY=; b=pdrwVXtqSSWIrOoIqRJc8vP7bcUFmNsr5UtEvbW6IVoAcUjmsqi71vHjPou04n2mGC ObAmo6wMMKp3Q6iZytrw4A2WGLtCvEzxbvzgWWtgdeiO27+AS5GAnv0q2NUcGznMNxXy zl+zKM+vhGfleNQzWMu7JogW1v/EG/nGK7npqU+UkcAifEVnbhxjP61lyOaNn9GLA8gY j7eWYYh1gx2AsaelsNpgOXORuFn6UwJx3kped9e/t7mmMAs94GJjrTpoP7vX+aDlIHC2 W+gpwbK8vBSdUwgiMaJahyUVncEC6ybSNZlJ6CRc93f6tOxCIPa9NO5t5KsEVe9tfB3v eG5A== Received: by 10.68.129.167 with SMTP id nx7mr22657947pbb.80.1339598219540; Wed, 13 Jun 2012 07:36:59 -0700 (PDT) Received: from localhost.localdomain ([202.108.130.138]) by mx.google.com with ESMTPS id tj4sm5945250pbc.33.2012.06.13.07.36.56 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 13 Jun 2012 07:36:58 -0700 (PDT) From: Dong Xu Wang To: qemu-devel@nongnu.org Date: Wed, 13 Jun 2012 22:36:24 +0800 Message-Id: <1339598189-17933-1-git-send-email-wdongxu@linux.vnet.ibm.com> X-Mailer: git-send-email 1.7.1 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 209.85.210.45 Cc: kwolf@redhat.com, Dong Xu Wang Subject: [Qemu-devel] [PATCH 1/6 v10] docs: spec for add-cow file format X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org 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.