On 4/30/21 9:45 AM, Max Reitz wrote: >> + ``data_file_raw`` >> + If this option is set to ``on``, QEMU will always keep the external >> + data file consistent as a standalone read-only raw image. It does >> + this by forwarding updates through to the raw image in addition to >> + updating the image metadata. If set to ``off``, QEMU will only >> + update the image metadata without forwarding the changes through >> + to the raw image. The default value is ``off``. > > Hm, what updates and what changes? I mean, the first part makes sense (the > “It does this by...”), but the second part doesn’t. qemu will still forward > most writes to the data file. (Not all, but most.) > > (Also, nit pick: With data_file_raw=off, the data file is not a raw image. > (You still call it that in the penultimate sentence.)) > When you write data to a qcow2 file with data_file, the data also goes to the > data_file, most of the time. The exception is when it can be handled with a > metadata update, i.e. when it's a zero write or discard. > > In addition, such updates (i.e. zero writes, I presume) not happening to the > data file are usually a minor problem. The real problem is that without > data_file_raw, data clusters can be allocated anywhere in the data file, > whereas with data_file_raw, they are allocated at their respective guest > offset (i.e. the host offset always equals the guest offset). > > I personally would have been fine with the first sentence, but if we want > more of an explanation... Perhaps: > > <<EOF > > If this option is set to ``on``, QEMU will always keep the external data file > consistent as a standalone read-only raw image. > > It does this by effectively forwarding all write accesses that happen to the > qcow2 file to the raw data file, including their offsets. Therefore, data > that is visible on the qcow2 node (i.e., to the guest) at some offset is > visible at the same offset in the raw data file. > > If this option is ``off``, QEMU will use the data file just to store data in > an effectively arbitrary manner. The file’s content will not make sense > without the accompanying qcow2 metadata. Where data is written will have no > relation to its offset as seen by the guest, and some writes (specifically > zero writes) may not be forwarded to the data file at all, but will only be > handled by modifying qcow2 metadata. > > In short: With data_file_raw, the data file reads as a valid raw VM image > file. Without it, its content can only be interpreted by reading the > accompanying qcow2 metadata. > > Note that this option only makes the data file valid as a read-only raw > image. You should not write to it, as this may effectively corrupt the qcow2 > metadata (for example, dirty bitmaps may become out of sync). > > EOF > > This got longer than I wanted it to be. Hm. Anyway, what do you think?
I found it very helpful. I'll incorporate your explanation into the next revision. I'm wondering what the most appropriate trailer would be for the next revision? Suggested-by: Max [..] Co-developed-by: Max [..] Let me know if you have a strong preference, otherwise I'll go with Suggested-by: Thank you, Connor