From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:58876) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TROrw-0007la-W1 for qemu-devel@nongnu.org; Thu, 25 Oct 2012 10:57:22 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TROrm-0006JU-Dr for qemu-devel@nongnu.org; Thu, 25 Oct 2012 10:57:12 -0400 Received: from mx1.redhat.com ([209.132.183.28]:6840) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TROrm-0006JK-5U for qemu-devel@nongnu.org; Thu, 25 Oct 2012 10:57:02 -0400 Message-ID: <50895338.80900@redhat.com> Date: Thu, 25 Oct 2012 08:56:56 -0600 From: Eric Blake MIME-Version: 1.0 References: <1351172204-29233-1-git-send-email-wdongxu@linux.vnet.ibm.com> <1351172204-29233-2-git-send-email-wdongxu@linux.vnet.ibm.com> In-Reply-To: <1351172204-29233-2-git-send-email-wdongxu@linux.vnet.ibm.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="------------enigC95AFE6968E5754530C3FABD" Subject: Re: [Qemu-devel] [PATCH V14 1/6] docs: document for add-cow file format List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Dong Xu Wang Cc: kwolf@redhat.com, qemu-devel@nongnu.org This is an OpenPGP/MIME signed message (RFC 2440 and 3156) --------------enigC95AFE6968E5754530C3FABD Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On 10/25/2012 07:36 AM, Dong Xu Wang wrote: > Document for add-cow format, the usage and spec of add-cow are introduc= ed. >=20 > Signed-off-by: Dong Xu Wang > --- > +An example usage of add-cow would look like:: > +(ubuntu.img is a disk image which has an 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=3Dubuntu.img,image_file=3Dtest.raw This example does not specify the file format of either the backing_file or the image_file, yet[1]... >=20 > + 8 - 11: backing file name offset > + Offset in the add-cow file at which the backin= g file > + name is stored (NB: The string is not nul-term= inated). Correct spelling of nul-terminated, but...[2] >=20 > + 16 - 19: image file name offset > + Offset in the add-cow file at which the image = file name > + is stored (NB: The string is not null terminat= ed). It [2]...here, you used the wrong spelling... > + 28 - 35: features > + Bitmask of features. If a feature bit set that= can not > + be recognized, the add-cow file should be drop= ed. They are not > + used in v1. If a feature bit is set but not recognized, the add-cow file should be dropped. > + > + 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 non-empty, it must be non-empty. It = is coded > + in free-form ASCII, and is not NUL-terminated.= Zero > + padded on the right. [2]...and here, you used different capitalization. I think I prefer NUL-terminated in all cases. > + > + 64 - 79: image file format > + Format of image file. It must be non-empty. It= is coded > + in free-form ASCII, and is not NUL-terminated.= Zero > + padded on the right. [1]...here you claim that backing and image file format are mandatory (must not be empty). Shouldn't you allow the file format to be empty, in which case qemu will probe? And why do you even need image file format - isn't the whole point of add-cow to wrap a raw image file, or are you planning on also being able to wrap non-raw files? Are there other non-raw file formats that lack backing file support, where add-cow can be used to give it a backing file? > + > + 80 - [HEADER_SIZE - 1]: > + It is used to make sure COW bitmap field start= s at the > + HEADER_SIZE byte, backing file name and image = file name > + will be stored here. The bytes that is not poi= nting to s/is/are/ > + backing file and image file names must be set = to 0. > + > +=3D=3D COW bitmap =3D=3D > + > +The "COW bitmap" field starts at offset HEADER_SIZE, stores a bitmap r= elated to > +backing file and image file. The bitmap will track whether the sector = in > +backing file is dirty or not. Rather, it is tracking whether the sector in image file is allocated or n= ot. > + > +Each bit in the bitmap tracks one cluster's status. For example, if cl= uster > +bit is 16, then each bit tracks one cluster, (1 << 16) =3D 65536 bytes= =2E The > +image file size is rounded up to cluster size (where any bytes in the > +last cluster that do not fit in the image are ignored), then if the > +number of clusters is not a multiple of 8, then remaining bits in the > +bitmap will be set to 0. > + > +The size of bitmap is calculated according to virtual size of image fi= le,and s/file,and/file, and/ > +the size of bitmap should be multiple of add-cow file's cluster size, = the bits > +not used will be set to 0. Within each byte, the least significant bit= covers > +the first cluster. Bit orders in one byte look like: > + +----+----+----+----+----+----+----+----+ > + | b7 | b6 | b5 | b4 | b3 | b2 | b1 | b0 | > + +----+----+----+----+----+----+----+----+ > + > +If the bit is 0, it indicates the sector has not been allocated in ima= ge file, > +data should be loaded from backing file while reading; if the bit is 1= , it > +indicates the related sector has been dirty, should be loaded from ima= ge file > +while reading. Writing to a sector causes the corresponding bit to be = set to 1. > +If there is no backing file, or if the image file is larger than the b= acking > +file and the offset is beyond the end of the backing file, then the da= ta should > +be read as all zero bytes instead. > + > +If raw image is not an even multiple of cluster bytes, bits that corre= spond to > +bytes beyond the raw file size in add-cow must be written as 0 and mus= t be > +ignored when reading. > + > +Image file name and backing file name must NOT be the same, we prevent= this > +while creating add-cow files via qemu-img. If image file name and back= ing file > +name are the same, the add-cow image must be treated as invalid. >=20 --=20 Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --------------enigC95AFE6968E5754530C3FABD Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.12 (GNU/Linux) Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Mozilla - http://www.enigmail.net/ iQEcBAEBCAAGBQJQiVM4AAoJEKeha0olJ0NqriwH/R1CtqaSDER9pMvdOauVdqDK Wkz0MzrYMCCG/eDYWLEM63LGP7shE6Gn2tsIVM18cT6BRSPwXPsCy1DY5NuOwogs kA6+MzOC9xWmTJYV0TjypxmYn0njjz9R8lGsbxguHKOokdqSB9T0fx5a/rfUzJgR pJpwg0SjNglhpMwZluBk2JhPa0D3kX8seDsZ19LrqPXPhTrxGe7hGlB4C/SFtUIg J14b8DpN40LA52DNVqSlWG1/hZwqaii3SeSMdq1IIKHztMJuIEFmJbe+f//qviGm E+K0TqwIwJIFlQqry0CzlyZmYOawMRCGgD5rzVhpdmmp9/A76KZ9pd1QghJBZD4= =mh4T -----END PGP SIGNATURE----- --------------enigC95AFE6968E5754530C3FABD--