← Back to branch summary

~jderose/ubuntu/raring/qemu/vde-again

« back to all changes in this revision

Viewing changes to docs/specs/qed_spec.txt

  • Committer: Package Import Robot
  • Author(s): Serge Hallyn, Serge Hallyn, Adam Conrad
  • Date: 2013-01-04 08:50:24 UTC
  • mfrom: (1.6.6) (10.1.29 sid)
  • Revision ID: package-import@ubuntu.com-20130104085024-k4mr3z3zzjxemww2
Tags: 1.2.0.dfsg-1~exp1-0ubuntu1
https://launchpad.net/bugs/1077838
[ Serge Hallyn ]
* debian/control:
  - update maintainer
  - remove vde2 recommends
  - build-deps: remove libusbredir, libvdeplug2-dev,
    libspice-server-dev, libspice-protocol-dev, libiscsi-dev,
    and libxen-dev.
  - qemu-keymaps: break/replace qemu-common
  - qemu-system:
    - break/replace qemu-common
    - depend on udev
    - remove openbios-ppc, openbios-sparc, and openhackware from
      Depends.  (Intend to add them back once we can build them.)
    - provides: qemu-kvm
  - qemu-utils: break/replace qemu-kvm
  - set up transitional packages for qemu-kvm, qemu-common, and kvm.
* debian/rules:
  - install kvm-ifup and kvm-ifdown
  - dh_installinit the qemu-kvm upstart job
* install a 30-qemu-kvm.conf into /etc/sysctl.c for nr_hugepages.
* qemu-kvm.upstart:
  - add qemu-system.qemu-kvm.upstart
  - add mv_confile to qemu-system.preinst, postinst, and .postrm to rename
    /etc/init/qemu-kvm.conf to qemu-system.conf
  - debian/rules: add dh_installinit to get qemu-system.upstart installed.
  - take the defaults from the old qemu-kvm.defaults, and move them into
    the upstart job
* debian/patches:
  - apply gridcentric patches from lp:~amscanne/+junk/gridcentric-qemu-patches
  - apply arm patches from git://git.linaro.org/qemu/qemu-linaro.git
  - apply nbd-fixes-to-read-only-handling.patch from upstream to
    make read-write mount after read-only mount work.  (LP: #1077838)
* ifup/down:
  - copy Ubuntu qemu-kvm's kvm-ifup/down into debian/
  - fix dh_install for kvm-ifup/down in debian/rules
  - add links for qemu-ifup/down in qemu-system.links
  - remove (debian's original) qemu-ifup from qemu-system.install
* debian/qemu-system.postinst
  - udevadm trigger to fix up /dev/kvm perms
  - make the 'qemu' symlink point to qemu-system-x86_64, not -i386.
* debian/qemu-system.links:
  - point 'kvm' to qemu-system-x86_64
  - remove pxe-virtio, pxe-e1000 and pxe-rtl8139 links (which conflict
    with ones from kvm-ipxe).  We may want to move the links from kvm-ipxe
    back to qemu-system at some point.
  - add qemu-ifdown and qemu-ifup links
* debian/qemu-system.install:
  - remove /etc/qemu-ifup link
  - add /etc/sysctl.d/30-qemu-kvm.conf

[ Adam Conrad ]
* Appease apt-get's dist-upgrade resolver by creating a qemu-common
  transitional package to upgrade more gracefully to qemu-keymaps.
* Move all the empty transitional packages to the oldlibs section. 
* Restore the versioned dep from qemu-kvm (and kvm) to qemu-system.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/specs/qed_spec.txt
 
1
=Specification=
 
2
 
 
3
The file format looks like this:
 
4
 
 
5
 +----------+----------+----------+-----+
 
6
 | cluster0 | cluster1 | cluster2 | ... |
 
7
 +----------+----------+----------+-----+
 
8
 
 
9
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.
 
10
 
 
11
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.
 
12
 
 
13
All fields are little-endian.
 
14
 
 
15
==Header==
 
16
 Header {
 
17
     uint32_t magic;               /* QED\0 */
 
18
 
 
19
     uint32_t cluster_size;        /* in bytes */
 
20
     uint32_t table_size;          /* for L1 and L2 tables, in clusters */
 
21
     uint32_t header_size;         /* in clusters */
 
22
 
 
23
     uint64_t features;            /* format feature bits */
 
24
     uint64_t compat_features;     /* compat feature bits */
 
25
     uint64_t autoclear_features;  /* self-resetting feature bits */
 
26
 
 
27
     uint64_t l1_table_offset;     /* in bytes */
 
28
     uint64_t image_size;          /* total logical image size, in bytes */
 
29
 
 
30
     /* if (features & QED_F_BACKING_FILE) */
 
31
     uint32_t backing_filename_offset; /* in bytes from start of header */
 
32
     uint32_t backing_filename_size;   /* in bytes */
 
33
 }
 
34
 
 
35
Field descriptions:
 
36
* ''cluster_size'' must be a power of 2 in range [2^12, 2^26].
 
37
* ''table_size'' must be a power of 2 in range [1, 16].
 
38
* ''header_size'' is the number of clusters used by the header and any additional information stored before regular clusters.
 
39
* ''features'', ''compat_features'', and ''autoclear_features'' are file format extension bitmaps.  They work as follows:
 
40
** An image with unknown ''features'' bits enabled must not be opened.  File format changes that are not backwards-compatible must use ''features'' bits.
 
41
** An image with unknown ''compat_features'' bits enabled can be opened safely.  The unknown features are simply ignored and represent backwards-compatible changes to the file format.
 
42
** An image with unknown ''autoclear_features'' bits enable can be opened safely after clearing the unknown bits.  This allows for backwards-compatible changes to the file format which degrade gracefully and can be re-enabled again by a new program later.
 
43
* ''l1_table_offset'' is the offset of the first byte of the L1 table in the image file and must be a multiple of ''cluster_size''.
 
44
* ''image_size'' is the block device size seen by the guest and must be a multiple of 512 bytes.
 
45
* ''backing_filename_offset'' and ''backing_filename_size'' describe a string in (byte offset, byte size) form.  It is not NUL-terminated and has no alignment constraints.  The string must be stored within the first ''header_size'' clusters.  The backing filename may be an absolute path or relative to the image file.
 
46
 
 
47
Feature bits:
 
48
* QED_F_BACKING_FILE = 0x01.  The image uses a backing file.
 
49
* QED_F_NEED_CHECK = 0x02.  The image needs a consistency check before use.
 
50
* QED_F_BACKING_FORMAT_NO_PROBE = 0x04.  The backing file is a raw disk image and no file format autodetection should be attempted.  This should be used to ensure that raw backing files are never detected as an image format if they happen to contain magic constants.
 
51
 
 
52
There are currently no defined ''compat_features'' or ''autoclear_features'' bits.
 
53
 
 
54
Fields predicated on a feature bit are only used when that feature is set.  The fields always take up header space, regardless of whether or not the feature bit is set.
 
55
 
 
56
==Tables==
 
57
 
 
58
Tables provide the translation from logical offsets in the block device to cluster offsets in the file.
 
59
 
 
60
 #define TABLE_NOFFSETS (table_size * cluster_size / sizeof(uint64_t))
 
61
  
 
62
 Table {
 
63
     uint64_t offsets[TABLE_NOFFSETS];
 
64
 }
 
65
 
 
66
The tables are organized as follows:
 
67
 
 
68
                    +----------+
 
69
                    | L1 table |
 
70
                    +----------+
 
71
               ,------'  |  '------.
 
72
          +----------+   |    +----------+
 
73
          | L2 table |  ...   | L2 table |
 
74
          +----------+        +----------+
 
75
      ,------'  |  '------.
 
76
 +----------+   |    +----------+
 
77
 |   Data   |  ...   |   Data   |
 
78
 +----------+        +----------+
 
79
 
 
80
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.
 
81
 
 
82
The logical image size must be less than or equal to the maximum possible size of clusters rooted by the L1 table:
 
83
 header.image_size <= TABLE_NOFFSETS * TABLE_NOFFSETS * header.cluster_size
 
84
 
 
85
L1, L2, and data cluster offsets must be aligned to header.cluster_size.  The following offsets have special meanings:
 
86
 
 
87
===L2 table offsets===
 
88
* 0 - unallocated.  The L2 table is not yet allocated.
 
89
 
 
90
===Data cluster offsets===
 
91
* 0 - unallocated.  The data cluster is not yet allocated.
 
92
* 1 - zero.  The data cluster contents are all zeroes and no cluster is allocated.
 
93
 
 
94
Future format extensions may wish to store per-offset information.  The least significant 12 bits of an offset are reserved for this purpose and must be set to zero.  Image files with cluster_size > 2^12 will have more unused bits which should also be zeroed.
 
95
 
 
96
===Unallocated L2 tables and data clusters===
 
97
Reads to an unallocated area of the image file access the backing file.  If there is no backing file, then zeroes are produced.  The backing file may be smaller than the image file and reads of unallocated areas beyond the end of the backing file produce zeroes.
 
98
 
 
99
Writes to an unallocated area cause a new data clusters to be allocated, and a new L2 table if that is also unallocated.  The new data cluster is populated with data from the backing file (or zeroes if no backing file) and the data being written.
 
100
 
 
101
===Zero data clusters===
 
102
Zero data clusters are a space-efficient way of storing zeroed regions of the image.
 
103
 
 
104
Reads to a zero data cluster produce zeroes.  Note that the difference between an unallocated and a zero data cluster is that zero data clusters stop the reading of contents from the backing file.
 
105
 
 
106
Writes to a zero data cluster cause a new data cluster to be allocated.  The new data cluster is populated with zeroes and the data being written.
 
107
 
 
108
===Logical offset translation===
 
109
Logical offsets are translated into cluster offsets as follows:
 
110
 
 
111
  table_bits table_bits    cluster_bits
 
112
  <--------> <--------> <--------------->
 
113
 +----------+----------+-----------------+
 
114
 | L1 index | L2 index |     byte offset |
 
115
 +----------+----------+-----------------+
 
116
 
 
117
       Structure of a logical offset
 
118
 
 
119
 offset_mask = ~(cluster_size - 1) # mask for the image file byte offset
 
120
 
 
121
 def logical_to_cluster_offset(l1_index, l2_index, byte_offset):
 
122
   l2_offset = l1_table[l1_index]
 
123
   l2_table = load_table(l2_offset)
 
124
   cluster_offset = l2_table[l2_index] & offset_mask
 
125
   return cluster_offset + byte_offset
 
126
 
 
127
==Consistency checking==
 
128
 
 
129
This section is informational and included to provide background on the use of the QED_F_NEED_CHECK ''features'' bit.
 
130
 
 
131
The QED_F_NEED_CHECK bit is used to mark an image as dirty before starting an operation that could leave the image in an inconsistent state if interrupted by a crash or power failure.  A dirty image must be checked on open because its metadata may not be consistent.
 
132
 
 
133
Consistency check includes the following invariants:
 
134
# Each cluster is referenced once and only once.  It is an inconsistency to have a cluster referenced more than once by L1 or L2 tables.  A cluster has been leaked if it has no references.
 
135
# Offsets must be within the image file size and must be ''cluster_size'' aligned.
 
136
# Table offsets must at least ''table_size'' * ''cluster_size'' bytes from the end of the image file so that there is space for the entire table.
 
137
 
 
138
The consistency check process starts by from ''l1_table_offset'' and scans all L2 tables.  After the check completes with no other errors besides leaks, the QED_F_NEED_CHECK bit can be cleared and the image can be accessed.