From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=52296 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PGuFP-0006fG-7v for qemu-devel@nongnu.org; Fri, 12 Nov 2010 09:05:00 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PGuFN-0005Go-Mw for qemu-devel@nongnu.org; Fri, 12 Nov 2010 09:04:59 -0500 Received: from mail-ey0-f173.google.com ([209.85.215.173]:43675) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PGuFN-0005Gf-9h for qemu-devel@nongnu.org; Fri, 12 Nov 2010 09:04:57 -0500 Received: by eya25 with SMTP id 25so1941142eya.4 for ; Fri, 12 Nov 2010 06:04:56 -0800 (PST) MIME-Version: 1.0 In-Reply-To: <4CDD47F4.6000000@redhat.com> References: <1288263684-18892-1-git-send-email-stefanha@linux.vnet.ibm.com> <1288263684-18892-2-git-send-email-stefanha@linux.vnet.ibm.com> <4CDD47F4.6000000@redhat.com> Date: Fri, 12 Nov 2010 14:04:54 +0000 Message-ID: Subject: Re: [Qemu-devel] Re: [PATCH v4 1/5] docs: Add QED image format specification From: Stefan Hajnoczi Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Kevin Wolf Cc: qemu-devel@nongnu.org, Anthony Liguori , Avi Kivity , Stefan Hajnoczi , Christoph Hellwig On Fri, Nov 12, 2010 at 1:58 PM, Kevin Wolf wrote: > Am 28.10.2010 13:01, schrieb Stefan Hajnoczi: >> Signed-off-by: Stefan Hajnoczi >> --- >> =A0docs/specs/qed_spec.txt | =A0128 ++++++++++++++++++++++++++++++++++++= +++++++++++ >> =A01 files changed, 128 insertions(+), 0 deletions(-) >> =A0create mode 100644 docs/specs/qed_spec.txt >> >> diff --git a/docs/specs/qed_spec.txt b/docs/specs/qed_spec.txt >> new file mode 100644 >> index 0000000..e4425c8 >> --- /dev/null >> +++ b/docs/specs/qed_spec.txt >> @@ -0,0 +1,128 @@ >> +=3DSpecification=3D >> + >> +The file format looks like this: >> + >> + +----------+----------+----------+-----+ >> + | cluster0 | cluster1 | cluster2 | ... | >> + +----------+----------+----------+-----+ >> + >> +The first cluster begins with the '''header'''. =A0The header contains = information about where regular clusters start; this allows the header to b= e extensible and store extra information about the image file. =A0A regular= cluster may be a '''data cluster''', an '''L2''', or an '''L1 table'''. = =A0L1 and L2 tables are composed of one or more contiguous clusters. >> + >> +Normally the file size will be a multiple of the cluster size. =A0If th= e file size is not a multiple, extra information after the last cluster may= not be preserved if data is written. =A0Legitimate extra information shoul= d use space between the header and the first regular cluster. >> + >> +All fields are little-endian. >> + >> +=3D=3DHeader=3D=3D >> + Header { >> + =A0 =A0 uint32_t magic; =A0 =A0 =A0 =A0 =A0 =A0 =A0 /* QED\0 */ >> + >> + =A0 =A0 uint32_t cluster_size; =A0 =A0 =A0 =A0/* in bytes */ >> + =A0 =A0 uint32_t table_size; =A0 =A0 =A0 =A0 =A0/* for L1 and L2 table= s, in clusters */ >> + =A0 =A0 uint32_t header_size; =A0 =A0 =A0 =A0 /* in clusters */ >> + >> + =A0 =A0 uint64_t features; =A0 =A0 =A0 =A0 =A0 =A0/* format feature bi= ts */ >> + =A0 =A0 uint64_t compat_features; =A0 =A0 /* compat feature bits */ >> + =A0 =A0 uint64_t l1_table_offset; =A0 =A0 /* in bytes */ >> + =A0 =A0 uint64_t image_size; =A0 =A0 =A0 =A0 =A0/* total logical image= size, in bytes */ >> + >> + =A0 =A0 /* if (features & QED_F_BACKING_FILE) */ >> + =A0 =A0 uint32_t backing_filename_offset; /* in bytes from start of he= ader */ >> + =A0 =A0 uint32_t backing_filename_size; =A0 /* in bytes */ >> + } >> + >> +Field descriptions: >> +* ''cluster_size'' must be a power of 2 in range [2^12, 2^26]. >> +* ''table_size'' must be a power of 2 in range [1, 16]. >> +* ''header_size'' is the number of clusters used by the header and any = additional information stored before regular clusters. >> +* ''features'', ''compat_features'', and ''autoclear_features'' are fil= e format extension bitmaps. =A0They work as follows: >> +** An image with unknown ''features'' bits enabled must not be opened. = =A0File format changes that are not backwards-compatible must use ''feature= s'' bits. >> +** An image with unknown ''compat_features'' bits enabled can be opened= safely. =A0The unknown features are simply ignored and represent backwards= -compatible changes to the file format. >> +** An image with unknown ''autoclear_features'' bits enable can be open= ed safely after clearing the unknown bits. =A0This allows for backwards-com= patible changes to the file format which degrade gracefully and can be re-e= nabled again by a new program later. > > autoclear features aren't even part of the header in the spec. Thanks for spotting this, I forgot to sync the header with the code. >> +* ''l1_table_offset'' is the offset of the first byte of the L1 table i= n the image file and must be a multiple of ''cluster_size''. >> +* ''image_size'' is the block device size seen by the guest and must be= a multiple of 512 bytes. >> +* ''backing_filename'' is a string in (byte offset, byte size) form. = =A0It is not NUL-terminated and has no alignment constraints. >> + >> +Feature bits: >> +* QED_F_BACKING_FILE =3D 0x01. =A0The image uses a backing file. =A0The= backing filename string is given in the ''backing_filename_{offset,size}''= fields and may be an absolute path or relative to the image file. >> +* QED_F_NEED_CHECK =3D 0x02. =A0The image needs a consistency check bef= ore use. >> +* QED_F_BACKING_FORMAT_NO_PROBE =3D 0x04. =A0The backing file is a raw = disk image and no file format autodetection should be attempted. =A0This sh= ould be used to ensure that raw backing images are never detected as an ima= ge format if they happen to contain magic constants. >> + >> +There are currently no defined ''compat_features'' or ''autoclear_featu= res'' bits. >> + >> +Fields predicated on a feature bit are only used when that feature is s= et. =A0The fields always take up header space, regardless of whether or not= the feature bit is set. >> + >> +=3D=3DTables=3D=3D >> + >> +Tables provide the translation from logical offsets in the block device= to cluster offsets in the file. >> + >> + #define TABLE_NOFFSETS (table_size * cluster_size / sizeof(uint64_t)) >> + >> + Table { >> + =A0 =A0 uint64_t offsets[TABLE_NOFFSETS]; >> + } >> + >> +The tables are organized as follows: >> + >> + =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0+----------+ >> + =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0| L1 table | >> + =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0+----------+ >> + =A0 =A0 =A0 =A0 =A0 =A0 =A0 ,------' =A0| =A0'------. >> + =A0 =A0 =A0 =A0 =A0+----------+ =A0 | =A0 =A0+----------+ >> + =A0 =A0 =A0 =A0 =A0| L2 table | =A0... =A0 | L2 table | >> + =A0 =A0 =A0 =A0 =A0+----------+ =A0 =A0 =A0 =A0+----------+ >> + =A0 =A0 =A0,------' =A0| =A0'------. >> + +----------+ =A0 | =A0 =A0+----------+ >> + | =A0 Data =A0 | =A0... =A0 | =A0 Data =A0 | >> + +----------+ =A0 =A0 =A0 =A0+----------+ >> + >> +A table is made up of one or more contiguous clusters. =A0The table_siz= e header field determines table size for an image file. =A0For example, clu= ster_size=3D64 KB and table_size=3D4 results in 256 KB tables. >> + >> +The logical image size must be less than or equal to the maximum possib= le size of clusters rooted by the L1 table: >> + header.image_size <=3D TABLE_NOFFSETS * TABLE_NOFFSETS * header.cluste= r_size >> + >> +All offsets in L1 and L2 tables are cluster-aligned. =A0The least signi= ficant bits up to ''cluster_size'' are reserved and must be zero. > > I know what you mean here, but the text leaves things a bit unclear. > First I would expect a bit number instead of a byte offset for "bits up > to x". Second, cluster_size is the first bit not reserved, whereas your > description sounds to me as if it included cluster_size. Will fix. Stefan