docs/interop/qed_spec.rst

7  +----------+----------+----------+-----+
9  +----------+----------+----------+-----+
14 a ``data cluster``, an ``L2``, or an ``L1 table``. L1 and L2 tables are composed
19 if data is written. Legitimate extra information should use space between the header
22 All fields are little-endian.
25 ------
36      uint64_t features;            /* format feature bits */
37      uint64_t compat_features;     /* compat feature bits */
38      uint64_t autoclear_features;  /* self-resetting feature bits */
51 - ``cluster_size`` must be a power of 2 in range [2^12, 2^26].
52 - ``table_size`` must be a power of 2 in range [1, 16].
53 - ``header_size`` is the number of clusters used by the header and any additional
55 - ``features``, ``compat_features``, and ``autoclear_features`` are file format
58   - An image with unknown ``features`` bits enabled must not be opened. File format
59     changes that are not backwards-compatible must use ``features`` bits.
60   - An image with unknown ``compat_features`` bits enabled can be opened safely.
61     The unknown features are simply ignored and represent backwards-compatible
63   - An image with unknown ``autoclear_features`` bits enable can be opened safely
64     after clearing the unknown bits. This allows for backwards-compatible changes
65     to the file format which degrade gracefully and can be re-enabled again by a
67 - ``l1_table_offset`` is the offset of the first byte of the L1 table in the image
69 - ``image_size`` is the block device size seen by the guest and must be a multiple
71 - ``backing_filename_offset`` and ``backing_filename_size`` describe a string in
72   (byte offset, byte size) form. It is not NUL-terminated and has no alignment constraints.
76 Feature bits:
79 - ``QED_F_BACKING_FILE = 0x01``. The image uses a backing file.
80 - ``QED_F_NEED_CHECK = 0x02``. The image needs a consistency check before use.
81 - ``QED_F_BACKING_FORMAT_NO_PROBE = 0x04``. The backing file is a raw disk image
86 There are currently no defined ``compat_features`` or ``autoclear_features`` bits.
93 ------
108                     +----------+
110                     +----------+
111                ,------'  |  '------.
112           +----------+   |    +----------+
114           +----------+        +----------+
115       ,------'  |  '------.
116  +----------+   |    +----------+
117  |   Data   |  ...   |   Data   |
118  +----------+        +----------+
131 L1, L2, and data cluster offsets must be aligned to ``header.cluster_size``.
137 - 0 - unallocated. The L2 table is not yet allocated.
139 Data cluster offsets
142 - 0 - unallocated.  The data cluster is not yet allocated.
143 - 1 - zero. The data cluster contents are all zeroes and no cluster is allocated.
145 Future format extensions may wish to store per-offset information. The least
146 significant 12 bits of an offset are reserved for this purpose and must be set
147 to zero. Image files with ``cluster_size`` > 2^12 will have more unused bits
150 Unallocated L2 tables and data clusters
158 Writes to an unallocated area cause a new data clusters to be allocated, and a new
159 L2 table if that is also unallocated. The new data cluster is populated with data
160 from the backing file (or zeroes if no backing file) and the data being written.
162 Zero data clusters
165 Zero data clusters are a space-efficient way of storing zeroed regions of the image.
167 Reads to a zero data cluster produce zeroes.
170     The difference between an unallocated and a zero data cluster is that zero data
173 Writes to a zero data cluster cause a new data cluster to be allocated.  The new
174 data cluster is populated with zeroes and the data being written.
182   <--------> <--------> <--------------->
183  +----------+----------+-----------------+
185  +----------+----------+-----------------+
189  offset_mask = ~(cluster_size - 1) # mask for the image file byte offset
198 --------------------
210 - Each cluster is referenced once and only once. It is an inconsistency to have
213 - Offsets must be within the image file size and must be ``cluster_size`` aligned.
214 - Table offsets must at least ``table_size`` * ``cluster_size`` bytes from the end