From patchwork Tue Jan 26 10:38:10 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Fam Zheng X-Patchwork-Id: 8120031 Return-Path: X-Original-To: patchwork-qemu-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 3590EBEEE5 for ; Tue, 26 Jan 2016 10:40:37 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 72F73201FA for ; Tue, 26 Jan 2016 10:40:36 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 9203120166 for ; Tue, 26 Jan 2016 10:40:35 +0000 (UTC) Received: from localhost ([::1]:42913 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aO134-0007Ga-S5 for patchwork-qemu-devel@patchwork.kernel.org; Tue, 26 Jan 2016 05:40:34 -0500 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 Received: from mx1.redhat.com ([209.132.183.28]:60238) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aO11J-0007EY-QH; Tue, 26 Jan 2016 05:38:45 -0500 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (Postfix) with ESMTPS id 7035C8EA48; Tue, 26 Jan 2016 10:38:45 +0000 (UTC) Received: from fam-t430.redhat.com (vpn1-5-65.pek2.redhat.com [10.72.5.65]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id u0QAcRTC016464; Tue, 26 Jan 2016 05:38:38 -0500 From: Fam Zheng To: qemu-devel@nongnu.org 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> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.22 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Cc: Kevin Wolf , Fam Zheng , qemu-block@nongnu.org, jsnow@redhat.com, Markus Armbruster , mreitz@redhat.com, vsementsov@parallels.com, Stefan Hajnoczi Subject: [Qemu-devel] [RFC PATCH 01/16] doc: Add QBM format specification X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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", + }, + } + } +} } +