From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:40387) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aO11Q-0004Fb-HO for qemu-devel@nongnu.org; Tue, 26 Jan 2016 05:38:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aO11O-0007G3-KK for qemu-devel@nongnu.org; Tue, 26 Jan 2016 05:38:52 -0500 From: Fam Zheng Date: Tue, 26 Jan 2016 18:38:10 +0800 Message-Id: <1453804705-7205-2-git-send-email-famz@redhat.com> In-Reply-To: <1453804705-7205-1-git-send-email-famz@redhat.com> References: <1453804705-7205-1-git-send-email-famz@redhat.com> Subject: [Qemu-devel] [RFC PATCH 01/16] doc: Add QBM format specification List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: Kevin Wolf , Fam Zheng , qemu-block@nongnu.org, jsnow@redhat.com, Markus Armbruster , mreitz@redhat.com, vsementsov@parallels.com, Stefan Hajnoczi 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. +@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. + +=== 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. +@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", + }, + } + } +} } + -- 2.4.3