Struct TranslationTable

pub struct TranslationTable { /* private fields */ }

QCOW uses a 2-level translation table to map guest-clusters to host clusters.

The translation table is a way of mapping a linear disk address to a physical offset in the QCOW file. Not every linear address may be mapped in the QCOW file, in which case reads to those regions would read-as-zero. These mappings are done with ‘cluster’ granularity such that a single, contiguous linear cluster maps to a contiguous region in the host file. The exact size of clusters used is determined by a field in the QCOW header.

Ex: a linear address can be decomposed into 3 parts:

• l1_index - The index into the top-level L1 translation table. The entry in the L1 table can either be a pointer to an L2 translation table, or the entry can indicate that the entire region is un-mapped, regardless of l2_index or cluster_offset.
• l2_index - If the l1_index indicates that there is a valid L2 table for a translation, the l2_index is offset into that L2 table that defines the per-cluster mapping for a translation. This mapping can either indicate there is a physical cluster allocated for a linear cluster or it can indicate that the cluster is unmapped and no translation exists.
• cluster_offset - If there is a valid l1_table entry and a valid l2_table entry for a linear disk address, that means there is physical cluster that has been allocated to the linear cluster. The cluster_offset is then the remaining byte-offset into this cluster.

Implementations

impl TranslationTable

pub fn load(file: &mut File) -> Result<Self, Error>

pub fn linear_size(&self) -> u64

The logical size of the QCOW disk as specified in the header.

pub fn translate<'a>(&'a self, linear_range: Range<u64>) -> Translation<'a>

Looks up translations for a linear disk range.

This takes a linear_range describing a region of the qcow file to read from and returns an iterator over Mappings of that region.

The returned iterator will yield mappings that indicate how the linear rante is represented in the qcow file. This can be a combination of physical cluster mappings and also unmapped regions if the translation table contains no data for the linear range.

If any part of linear_range extends beyond the disk (bounded by linear_size()) then the iterator will not yield any mappings for those regions. In other words, no Mapping is a distinct situation for a Mapping::Unmapped. The former means there is no logical disk backing the range and the latter means that the linear range is valid but no physical disk clusters have been allocated to it.