From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47480) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aW0bJ-0008Lg-UK for qemu-devel@nongnu.org; Wed, 17 Feb 2016 06:48:59 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aW0bG-0001UQ-JK for qemu-devel@nongnu.org; Wed, 17 Feb 2016 06:48:57 -0500 Message-ID: <56C45E14.1090406@virtuozzo.com> Date: Wed, 17 Feb 2016 14:48:36 +0300 From: Vladimir Sementsov-Ogievskiy MIME-Version: 1.0 References: <1453804705-7205-1-git-send-email-famz@redhat.com> <1453804705-7205-2-git-send-email-famz@redhat.com> In-Reply-To: <1453804705-7205-2-git-send-email-famz@redhat.com> Content-Type: text/plain; charset="utf-8"; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] [RFC PATCH 01/16] doc: Add QBM format specification List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Fam Zheng , qemu-devel@nongnu.org Cc: Kevin Wolf , qemu-block@nongnu.org, jsnow@redhat.com, Markus Armbruster , mreitz@redhat.com, vsementsov@parallels.com, Stefan Hajnoczi On 26.01.2016 13:38, Fam Zheng wrote: > Signed-off-by: Fam Zheng > --- > docs/specs/qbm.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 118 insertions(+) > create mode 100644 docs/specs/qbm.md > > diff --git a/docs/specs/qbm.md b/docs/specs/qbm.md > new file mode 100644 > index 0000000..b91910b > --- /dev/null > +++ b/docs/specs/qbm.md > @@ -0,0 +1,118 @@ > +QEMU Block Bitmap (QBM) > +======================= > + > +QBM is a multi-file disk format to allow storing persistent block bitmaps along > +with the tracked data image. A QBM image includes one json descriptor file, > +one data image, one or more bitmap files that describe the block dirty status > +of the data image. > + > +The json file describes the structure of the image. The structure of the json > +descriptor file is: > + > + QBM-JSON-FILE := { "QBM": DESC-JSON } > + > + DESC-JSON := { "version": 1, > + "image": IMAGE, > + "BITMAPS": BITMAPS > + } > + > +Fields in the top level json dictionary are: > + > +@version: An integer which must be 1. > +@image: A dictionary in IMAGE schema, as described later. It provides the > + information of the data image where user data is stored. Its format is > + documented in the "IMAGE schema" section. I think, ', as described later' or entire third sentence may be dropped as duplication. > +@bitmaps: A dictionary that describes one ore more bitmap files. The keys into > + the dictionary are the names of bitmap, which must be strings, and > + each value is a dictionary describing the information of the bitmap, > + as documented below in the "BITMAP schema" section. Agree with others, that it should be an array. It seems like it is more common practice. > + > +=== IMAGE schema === > + > +An IMAGE records the information of an image (such as a data image or a backing > +file). It has following fields: > + > +@file: The file name string of the referenced image. If it's a relative path, > + the file should be found relative to the descriptor file's > + location. > +@format: The format string of the file. > + > +=== BITMAP schema === > + > +A BITMAP dictionary records the information of a bitmap (such as a dirty bitmap > +or a block allocation status bitmap). It has following mandatory fields: > + > +@file: The name of the bitmap file. The bitmap file is in little endian, both > + byte-order-wise and bit-order-wise, which means the LSB in the byte 0 > + corresponds to the first sectors. What about reuse my bitmap-table approach (one indexing table, like L1), to save space? Or, add @format field, to allow adding this later as native option, without ext-hard-. > +@granularity-bytes: How many bytes of data does one bit in the bitmap track. > + This value must be a power of 2 and no less than 512. > +@type: The type of the bitmap. Currently only "dirty" and "allocation" are > + supported. > + "dirty" indicates a block dirty bitmap; "allocation" indicates a > + allocation status bitmap. There must be at most one "allocation" bitmap. > + > +If the type of the bitmap is "allocation", an extra field "backing" is also > +accepted: > + > +@backing: a dictionary as specified in the IMAGE schema. It can be used to > + adding a backing file to raw image. > + > + > +=== Extended fields === > + > +Implementations are allowed to extend the format schema by inserting additinoal > +members into above dictionaries, with key names that starts with either > +an "ext-hard-" or an "ext-soft-" prefix. > + > +Extended fields prefixed with "ext-soft-" are optional and can be ignored by > +parsers if they do not support it; fields starting with "ext-hard-" are > +mandatory and cannot be ignored, a parser should not proceed parsing the image > +if it does not support it. > + > +It is strongly recommended that the application names are also included in the > +extention name string, such as "ext-hard-qemu-", if the effect or > +interpretation of the field is local to a specific application. > + > +For example, QEMU can implement a "checksum" feature to make sure no files > +referred to by the json descriptor are modified inconsistently, by adding > +"ext-soft-qemu-checksum" fields in "image" and "bitmaps" descriptions, like in > +the json text found below. > + > +=== QBM descriptor file example === > + > +This is the content of a QBM image's json descriptor file, which contains a > +data image (data.img), and three bitmaps, out of which the "allocation" bitmap > +associates a backing file to this image (base.img). > + > +{ "QBM": { > + "version": 1, > + "image": { > + "file": "data.img", > + "format": "raw" > + "ext-soft-qemu-checksum": "9eff24b72bd693cc8aa3e887141b96f8", > + }, > + "bitmaps": { > + "0": { > + "file": "bitmap0.bin", > + "granularity-bytes": 512, > + "type": "dirty" > + }, > + "1": { > + "file": "bitmap1.bin", > + "granularity-bytes": 4096, > + "type": "dirty" > + }, > + "2": { > + "file": "bitmap3.bin", > + "granularity-bytes": 4096, > + "type": "allocation" > + "backing": { > + "file": "base.img", > + "format": "raw" > + "ext-soft-qemu-checksum": "fcad1f672b2fb19948405e7a1a18c2a7", > + }, > + } > + } > +} } > + -- Best regards, Vladimir