From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:43858) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S5xPf-0006kN-24 for qemu-devel@nongnu.org; Fri, 09 Mar 2012 05:51:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1S5xPW-0002jf-GV for qemu-devel@nongnu.org; Fri, 09 Mar 2012 05:51:06 -0500 Received: from mail-lpp01m010-f45.google.com ([209.85.215.45]:56349) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S5xPV-0002jG-W6 for qemu-devel@nongnu.org; Fri, 09 Mar 2012 05:50:58 -0500 Received: by lahe6 with SMTP id e6so1613377lah.4 for ; Fri, 09 Mar 2012 02:50:55 -0800 (PST) MIME-Version: 1.0 In-Reply-To: References: Date: Fri, 9 Mar 2012 10:50:55 +0000 Message-ID: From: Stefan Hajnoczi Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH 1/5] block: Virtual Bridges VERDE GOW disk image format documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: "Leonardo E. Reiter" Cc: QEMU Developers Mailing List On Thu, Mar 8, 2012 at 10:13 PM, Leonardo E. Reiter wrote: > commit 4b7b36f3776247c92615073b6fa0880d0a1ea1fb > Author: Leonardo E. Reiter > Date: =A0 Thu Mar 8 15:50:55 2012 -0600 > > =A0 =A0 Documentation for Virtual Bridges GOW version 1, 2, and 3 disk im= age > formats. =A0Includes products consuming these disk image formats, basic > overview of how they work, and example use case for remote disk image > synchronization. > > =A0 =A0 Signed-off-by: Leonardo E. Reiter > > diff --git a/docs/vb-gow.txt b/docs/vb-gow.txt > new file mode 100644 > index 0000000..e2ba64b > --- /dev/null > +++ b/docs/vb-gow.txt > @@ -0,0 +1,71 @@ > +Virtual Bridges GOW Disk Image formats > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > +GOW has 3 versions that covers the following products: > + v1: (circa 2006) Win4Lin Pro, Win4BSD, Win4Solaris > + v2: (circa 2008) Virtual Bridges VERDE, > + IBM Virtual Desktop for Smart Business > + v3: (circa 2009) Virtual Bridges VERDE, > + IBM Virtual Desktop for Smart Business > + > +Current versions of VERDE and IBM Virtual Desktop for Smart Business use > both > +versions 2 and 3 in virtual machines to store user images and gold image= s, > +respectively. =A0Older versions of VERDE (prior to 2009) used only versi= on 2. > + > +What is GOW? > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > +GOW stands for "Grow on Write", which is a very simple disk image format > that > +grows by 64KB blocks when data is added to disk images. =A0Data added to > existing > +allocated areas do not result in growth of course. =A0There is no compre= ssion > +other than that explicitly available by not having to allocate unused > blocks > +in order to handle data beyond them. =A0A simple header at the beginning= of > the > +image file maps logical blocks (from the guest's perspective) to file > offsets > +(from the host's perspective). > +This image format is optimized for product virtual desktop use cases onl= y, > and > +has been in mainstream use since 2006. =A0Both Virtual Bridges and IBM s= ell > +new versions of this technology worldwide at the time of this writing. > +GOW implementation memory maps the allocation map in order to reduce > additional > +file-level system calls during normal operation. =A0It supports both > read-only > +and read-write images. The mmap(2) approach doesn't support QEMU's "protocol" concept where an image format block driver is independent of the underlying storage (host file system, NBD, HTTP, etc). In QEMU block layer terminology NBD, HTTP, and the host file system block drivers are "protocols" in that they give access to data. It's not possible to mmap(2) over NBD or HTTP. (I'm doing a linear code review, so perhaps your later patches avoid using mmap. But at this point I wanted to comment on this.) > + > +Differences Between Versions > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D > +Version 1 supports disk images of up to 64GB logical size, with an > approximate > +4MB header overhead. > +Version 2 supports disk images of up to 256GB logical size, with an > approximate > +16MB header overhead. =A0It also aligned file offsets of logical sectors= to > 512- > +byte boundaries (starting at the first such boundary following the heade= r). > +Version 3 supports disk images of up to 256GB logical size, with an > approximate > +32MB header overhead. =A0It is identical to GOW2 except that it also tra= cks > +block-level version numbers, incrementing (once-per-session) them on > changes > +or new allocation. =A0This allows for very easy delta size calculations = when > +synchronizing images with external tools (see below). > +File offsets in headers are expressed in 64KB blocks. =A0Block 0 starts > +immediately after the header for each version. =A0In GOW2 and GOW3, bloc= k 0 > +is actually aligned to a 512 byte boundary beyond the header. =A0Using 6= 4KB > +blocks allows the use of 32-bit unsigned integers in the header itself, > rather > +than 64-bit integers, to store offsets even for large files. =A0This cut= s the > +header size requirement in half while adding only a minimal shift overhe= ad > to > +offset calculations. This is a good overview. It would be nice to see a structure-level specification of the file format on disk, but given this explanation it doesn't seem critical unless you wish to do that. > +Advanced Use Case: Synchronizing Remote Images from Master > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D > +One of the technologies VERDE provides is "decentralized" virtual deskto= ps. > +This means a gold master image living in the data center can be cached o= n > +either local desktop(s) or local server(s) to use offline or in a > decentralized > +way. =A0This assumes that the consumer is using the virtual desktop imag= e in > COW > +mode, with no changes to the image file committed back to it. > +In this scenario, it is easy to do block-level delta downloads from the > master > +image that can even be interrupted and resumed from partial downloads. > +The consumer need only to copy blocks from the master image file that ha= ve > +a newer version number in the image's header than the local block. This sounds cool and reminds me of the image streaming code that was added upstream recently although GOW takes a different approach using block version numbers instead of purely relying on allocating information. > +License > +=3D=3D=3D=3D=3D=3D=3D > +Virtual Bridges GOW functionality is licensed under BSD-style terms that > +are identical to how most QEMU source files are licensed, including vl.c= . > +Please check the respective source files for the comment header with thi= s > +license stated explicitly. > + > +Copyright (C) 1984-2012 Virtual Bridges, Inc. =A0All Rights Reserved. This has been raised in similar situations in the past: you have BSD licensed this but then say "All Rights Reserved". What does that mean? You have just given rights to distribute, modify, etc through the BSD license so I'm not sure it makes sense to reserve all rights. Your copyright is fine but you cannot restrict rights, that would conflict with QEMU's license (which overall is GPL). Stefan