From patchwork Fri Oct 8 15:48:30 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Hajnoczi X-Patchwork-Id: 67235 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by ozlabs.org (Postfix) with ESMTP id CC78CB70A3 for ; Sat, 9 Oct 2010 02:57:11 +1100 (EST) Received: from localhost ([127.0.0.1]:46849 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1P4FDk-0006Ms-Ps for incoming@patchwork.ozlabs.org; Fri, 08 Oct 2010 11:50:56 -0400 Received: from [140.186.70.92] (port=51722 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1P4FC5-0005M2-2d for qemu-devel@nongnu.org; Fri, 08 Oct 2010 11:49:37 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1P4FBh-0007ut-Tb for qemu-devel@nongnu.org; Fri, 08 Oct 2010 11:48:52 -0400 Received: from mtagate7.de.ibm.com ([195.212.17.167]:60998) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1P4FBh-0007u8-Lv for qemu-devel@nongnu.org; Fri, 08 Oct 2010 11:48:49 -0400 Received: from d12nrmr1607.megacenter.de.ibm.com (d12nrmr1607.megacenter.de.ibm.com [9.149.167.49]) by mtagate7.de.ibm.com (8.13.1/8.13.1) with ESMTP id o98Fmj7H024065 for ; Fri, 8 Oct 2010 15:48:45 GMT Received: from d12av02.megacenter.de.ibm.com (d12av02.megacenter.de.ibm.com [9.149.165.228]) by d12nrmr1607.megacenter.de.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id o98FmiiQ4001992 for ; Fri, 8 Oct 2010 17:48:45 +0200 Received: from d12av02.megacenter.de.ibm.com (loopback [127.0.0.1]) by d12av02.megacenter.de.ibm.com (8.12.11.20060308/8.13.3) with ESMTP id o98Fmi7g019675 for ; Fri, 8 Oct 2010 17:48:44 +0200 Received: from stefan-thinkpad.manchester-maybrook.uk.ibm.com (dyn-9-174-218-53.manchester-maybrook.uk.ibm.com [9.174.218.53]) by d12av02.megacenter.de.ibm.com (8.12.11.20060308/8.12.11) with ESMTP id o98Fmgem019417; Fri, 8 Oct 2010 17:48:44 +0200 From: Stefan Hajnoczi To: Date: Fri, 8 Oct 2010 16:48:30 +0100 Message-Id: <1286552914-27014-4-git-send-email-stefanha@linux.vnet.ibm.com> X-Mailer: git-send-email 1.7.1 In-Reply-To: <1286552914-27014-1-git-send-email-stefanha@linux.vnet.ibm.com> References: <1286552914-27014-1-git-send-email-stefanha@linux.vnet.ibm.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) Cc: Kevin Wolf , Anthony Liguori , Christoph Hellwig , Stefan Hajnoczi , Avi Kivity Subject: [Qemu-devel] [PATCH v2 3/7] docs: Add QED image format specification X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Signed-off-by: Stefan Hajnoczi --- docs/specs/qed_spec.txt | 94 +++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 94 insertions(+), 0 deletions(-) create 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..c942b8e --- /dev/null +++ b/docs/specs/qed_spec.txt @@ -0,0 +1,94 @@ +=Specification= + +The file format looks like this: + + +----------+----------+----------+-----+ + | cluster0 | cluster1 | cluster2 | ... | + +----------+----------+----------+-----+ + +The first cluster begins with the '''header'''. The header contains information about where regular clusters start; this allows the header to be extensible and store extra information about the image file. A regular cluster may be a '''data cluster''', an '''L2''', or an '''L1 table'''. L1 and L2 tables are composed of one or more contiguous clusters. + +Normally the file size will be a multiple of the cluster size. If the file size is not a multiple, extra information after the last cluster may not be preserved if data is written. Legitimate extra information should use space between the header and the first regular cluster. + +All fields are little-endian. + +==Header== + Header { + uint32_t magic; /* QED\0 */ + + uint32_t cluster_size; /* in bytes */ + uint32_t table_size; /* for L1 and L2 tables, in clusters */ + uint32_t header_size; /* in clusters */ + + uint64_t features; /* format feature bits */ + uint64_t compat_features; /* compat feature bits */ + uint64_t l1_table_offset; /* in bytes */ + uint64_t image_size; /* total logical image size, in bytes */ + + /* if (features & QED_F_BACKING_FILE) */ + uint32_t backing_filename_offset; /* in bytes from start of header */ + uint32_t backing_filename_size; /* in bytes */ + + /* if (compat_features & QED_CF_BACKING_FORMAT) */ + uint32_t backing_fmt_offset; /* in bytes from start of header */ + uint32_t backing_fmt_size; /* 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 and compat_features are bitmaps where active file format features can be selectively enabled. The difference between the two is that an image file that uses unknown compat_features bits can be safely opened without knowing how to interpret those bits. If an image file has an unsupported features bit set then it is not possible to open that image (the image is not backwards-compatible). +* l1_table_offset must be a multiple of cluster_size. +* image_size is the block device size seen by the guest and must be a multiple of cluster_size. +* backing_filename and backing_fmt are both strings in (byte offset, byte size) form. They are not NUL-terminated and do not have alignment constraints. + +Feature bits: +* QED_F_BACKING_FILE = 0x01. The image uses a backing file. +* QED_F_NEED_CHECK = 0x02. The image needs a consistency check before use. +* QED_CF_BACKING_FORMAT = 0x01. The image has a specific backing file format stored. + +==Tables== + +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 { + uint64_t offsets[TABLE_NOFFSETS]; + } + +The tables are organized as follows: + + +----------+ + | L1 table | + +----------+ + ,------' | '------. + +----------+ | +----------+ + | L2 table | ... | L2 table | + +----------+ +----------+ + ,------' | '------. + +----------+ | +----------+ + | Data | ... | Data | + +----------+ +----------+ + +A table is made up of one or more contiguous clusters. The table_size header field determines table size for an image file. For example, cluster_size=64 KB and table_size=4 results in 256 KB tables. + +The logical image size must be less than or equal to the maximum possible size of clusters rooted by the L1 table: + header.image_size <= TABLE_NOFFSETS * TABLE_NOFFSETS * header.cluster_size + +Logical offsets are translated into cluster offsets as follows: + + table_bits table_bits cluster_bits + <--------> <--------> <---------------> + +----------+----------+-----------------+ + | L1 index | L2 index | byte offset | + +----------+----------+-----------------+ + + Structure of a logical offset + + def logical_to_cluster_offset(l1_index, l2_index, byte_offset): + l2_offset = l1_table[l1_index] + l2_table = load_table(l2_offset) + cluster_offset = l2_table[l2_index] + return cluster_offset + byte_offset