Enum Mapping

#[non_exhaustive]
pub enum Mapping<'a, S: Storage + 'static> {
    Raw {
        storage: &'a S,
        offset: u64,
        writable: bool,
    },
    Zero {
        explicit: bool,
    },
    Eof {},
    Special {
        layer: &'a FormatAccess<S>,
        offset: u64,
    },
}

Fully recursive mapping information.

Mapping information that resolves down to the storage object layer (except for special data).

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Raw

Raw data.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

storage: &'a S

Storage object where this data is stored.

offset: u64

Offset in storage where this data is stored.

writable: bool

Whether this mapping may be written to.

If true, you can directly write to offset on storage to change the disk image’s data accordingly.

If false, the disk image format does not allow writing to offset on storage; a new mapping must be allocated first.

Zero

Range is to be read as zeroes.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

explicit: bool

Whether these zeroes are explicit on this image (the top layer).

Differential image formats (like qcow2) track information about the status for all blocks in the image (called clusters in case of qcow2). Perhaps most importantly, they track whether a block is allocated or not:

• Allocated blocks have their data in the image.
• Unallocated blocks do not have their data in this image, but have to be read from a backing image (which results in ShallowMapping::Indirect mappings).

Thus, such images represent the difference from their backing image (hence “differential”).

Without a backing image, this feature can be used for sparse allocation: Unallocated blocks are simply interpreted to be zero. These ranges will be noted as Mapping::Zero with explicit set to false.

Formats like qcow2 can track more information beyond just the allocation status, though, for example, whether a block should read as zero. Such blocks similarly do not need to have their data stored in the image file, but are still not treated as unallocated, so will never be read from a backing image, regardless of whether one exists or not.

These ranges are noted as Mapping::Zero with explicit set to true.

Eof

End of file reached.

The accompanying length is always 0.

Special

Data is encoded in some manner, e.g. compressed or encrypted.

Such data cannot be accessed directly, but must be interpreted by the image format driver.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

layer: &'a FormatAccess<S>

Format layer where this special data was encountered.

offset: u64

Original (“guest”) offset on layer to pass to readv_special().

Implementations

impl<S: Storage> Mapping<'_, S>

pub fn is_eof(&self) -> bool

Return true if and only if this mapping signifies the end of file.

Trait Implementations

impl<'a, S: Debug + Storage + 'static> Debug for Mapping<'a, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: Storage> Display for Mapping<'_, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.