From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:58170) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UVrOW-0007mi-Ts for qemu-devel@nongnu.org; Fri, 26 Apr 2013 18:45:35 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UVrOV-0004N8-LU for qemu-devel@nongnu.org; Fri, 26 Apr 2013 18:45:32 -0400 Received: from mx1.redhat.com ([209.132.183.28]:30247) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UVrOV-0004Mw-DH for qemu-devel@nongnu.org; Fri, 26 Apr 2013 18:45:31 -0400 Message-ID: <517B0382.3080104@redhat.com> Date: Fri, 26 Apr 2013 16:45:22 -0600 From: Eric Blake MIME-Version: 1.0 References: <1365581513-3475-1-git-send-email-wdongxu@linux.vnet.ibm.com> <1365581513-3475-2-git-send-email-wdongxu@linux.vnet.ibm.com> In-Reply-To: <1365581513-3475-2-git-send-email-wdongxu@linux.vnet.ibm.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="----enig2DFWCGMBVPOCISLSONKTH" Subject: Re: [Qemu-devel] [PATCH V18 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: wdongxu@cn.ibm.com, qemu-devel@nongnu.org, stefanha@redhat.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) ------enig2DFWCGMBVPOCISLSONKTH Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On 04/10/2013 02:11 AM, Dong Xu Wang wrote: > Document for add-cow format, the usage and spec of add-cow are > introduced. >=20 > Signed-off-by: Dong Xu Wang > --- > V17->V18: > 1) remove version field. > 2) header size is maximum value and cluster size value. > 3) fix type. > docs/specs/add-cow.txt | 165 +++++++++++++++++++++++++++++++++++++++++= ++++++++ > 1 file changed, 165 insertions(+) > create mode 100644 docs/specs/add-cow.txt >=20 > diff --git a/docs/specs/add-cow.txt b/docs/specs/add-cow.txt > new file mode 100644 > index 0000000..151028b > --- /dev/null > +++ b/docs/specs/add-cow.txt > @@ -0,0 +1,165 @@ > +=3D=3D General =3D=3D No copyright notice? Not necessarily your fault, since many other files in this directory suffer from the same problem. > + > +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 a 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 a 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=3Dubuntu.img,image_file=3Dtest.raw > + 3) Run qemu with add-cow image > + qemu -drive if=3Dvirtio,file=3Dtest.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. In general, probing a raw file is a security hole (we just plugged a CVE with NBD probing); you probably ought to mention that it is recommended to always specify the format for any raw file, so that probing doesn't misinterpret the contents of the file as some other format. > + > +=3DSpecification=3D > + > +The file format looks like this: > + > + +---------------+-------------------------------+ > + | Header | COW bitmap | > + +---------------+-------------------------------+ > + > +All numbers in add-cow are stored in Little Endian byte order. > + > +=3D=3D Header =3D=3D > + > +The Header is included in the first bytes: > +(HEADER_SIZE is defined in 40-43 bytes.) > + Byte 0 - 3: magic > + add-cow magic string ("ACOW"). Probably ought to mention that this magic string is in the ASCII encoding (those characters map to different bytes on EBCDIC, although I doubt qemu will ever really been ported to EBCDIC) > + > + 4 - 7: backing file name offset > + Offset in the add-cow file at which the backin= g > + file name is stored (NB: The string is not > + lNUL-terminated). s/lNUL/NUL/ > + If backing file name does NOT exist, this fiel= d > + will be 0. Must be between 76 and [HEADER_SIZE= > + - 2](a file name must be at least 1 byte). > + > + > + 40 - 43: HEADER_SIZE > + The header field is variable-sized. This field= > + indicates how many bytes will be used to store= > + add-cow header. By default, it is maximum valu= e > + of 4096 and cluster size value. Should it be required to be a multiple of 4096, for efficient alignment of clusters? > + > + 44 - 59: 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 righ= t. Requiring this to be non-empty if a backing file is named contradicts your earlier statement that backing format is probed (I actually like mandating the backing format, though). > + > + 60 - 75: 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. Again, requiring a format contradicts the earlier statement about format probing. How does this compare with Paolo's efforts to design a persistent bitmap for drive-mirror/block-backup use? --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org ------enig2DFWCGMBVPOCISLSONKTH 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.13 (GNU/Linux) Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJRewOCAAoJEKeha0olJ0Nqf2kH/RST0+6+92T2I3SmthJi95pr 3m5RHDk6y6GryNxglV0gUkg6cTdW/V8y+6G0m3ZElzA+izIYHktew82iLs42ejsi s/W3Yu7dXZyfTg8kLrkjRUaCZNhSbnj3hRlu07Svk4NMaqZ9p0FkiUoVYyolr6ou OVMvUHFb+3tITrAKrI8YpcDmBzsDKWlySBGlfBCGBq/S8IIGy86Vk5ypQyLzF9kD zt9NJCWJ4Lt4dsUdpXOOEr7QJg9myJuFzYAdphHf48frjBuW1Kgt+7kt5lATsy9f YKMYhVKSVYoVxji+8PN4vSOavVcNDnFrRLpkJLTnlaW6CUaNUldf4E+nQXJpYUs= =HIEN -----END PGP SIGNATURE----- ------enig2DFWCGMBVPOCISLSONKTH--