Module Qcow.MakeSource

Parameters

Signature

include Mirage_block.S
Sourcetype nonrec error = private [>
  1. | Mirage_block.error
]

The type for block errors.

Sourceval pp_error : error Fmt.t

pp_error is the pretty-printer for errors.

Sourcetype nonrec write_error = private [>
  1. | Mirage_block.write_error
]

The type for write errors.

Sourceval pp_write_error : write_error Fmt.t

pp_write_error is the pretty-printer for write errors.

Sourcetype t

The type representing the internal state of the block device

Sourceval disconnect : t -> unit Lwt.t

Disconnect from the device. While this might take some time to complete, it can never result in an error.

Sourceval get_info : t -> Mirage_block.info Lwt.t

Query the characteristics of a specific block device

Sourceval read : t -> int64 -> Cstruct.t list -> (unit, error) result Lwt.t

read device sector_start buffers reads data starting at sector_start from the block device into buffers. Ok () means the buffers have been filled. Error _ indicates an I/O error has happened and some of the buffers may not be filled. Each of elements in the list buffers must be a whole number of sectors in length. The list of buffers can be of any length. Some implementations may further require that each element in buffers is exactly sector_size long.

Sourceval write : t -> int64 -> Cstruct.t list -> (unit, write_error) result Lwt.t

write device sector_start buffers writes data from buffers onto the block device starting at sector_start. Ok () means the contents of the buffers have been written. Error _ indicates a partial failure in which some of the writes may not have happened.

Once submitted, it is not possible to cancel a request and there is no timeout.

The operation may fail with: `Is_read_only: the device is read-only, no data has been written.

Each of buffers must be a whole number of sectors in length. The list of buffers can be of any length. Some implementations may further require that each element in buffers is exactly sector_size long.

The data will not be copied, so the supplied buffers must not be re-used until the IO operation completes.

Sourcemodule Config : sig ... end
Sourcemodule Stats : sig ... end
Sourceval create : B.t -> size:int64 -> ?lazy_refcounts:bool -> ?cluster_bits:int -> ?config:Config.t -> unit -> (t, write_error) result Lwt.t

create block ~size ?lazy_refcounts ?cluster_bits ?config () initialises a qcow-formatted image on block with virtual size size in bytes.

By default the file will use lazy refcounts, but this can be overriden by supplying ~lazy_refcounts:false. By default the file will use 64KiB clusters (= 16 bits) but this can be overridden by supplying ?cluster_bits. Note the cluster size must be greater than the sector size on the underlying block device.

The ?config argument does not affect the on-disk format but rather the behaviour as seen from this client.

Sourceval connect : ?config:Config.t -> B.t -> t Lwt.t

connect ?config block connects to an existing qcow-formatted image on block.

Sourceval resize : t -> new_size:int64 -> ?ignore_data_loss:bool -> unit -> (unit, write_error) result Lwt.t

resize block new_size_bytes ?ignore_data_loss changes the size of the qcow-formatted image to new_size_bytes, rounded up to the next allocation unit. This function will fail with an error if the new size would be smaller than the old size as this would cause data loss, unless the argument ?ignore_data_loss is set to true.

Sourcetype compact_result = {
  1. copied : int64;
    (*

    number of sectors copied

    *)
  2. refs_updated : int64;
    (*

    number of cluster references updated

    *)
  3. old_size : int64;
    (*

    previous size in sectors

    *)
  4. new_size : int64;
    (*

    new size in sectors

    *)
}

Summary of the compaction run

Sourceval compact : t -> ?progress_cb:(percent:int -> unit) -> unit -> (compact_result, write_error) result Lwt.t

compact t () scans the disk for unused space and attempts to fill it and shrink the file. This is useful if the underlying block device doesn't support discard and we must emulate it.

Sourceval discard : t -> sector:int64 -> n:int64 -> unit -> (unit, write_error) result Lwt.t

discard sector n signals that the n sectors starting at sector are no longer needed and the contents may be discarded. Note the contents may not actually be deleted: this is not a "secure erase".

Sourceval seek_unmapped : t -> int64 -> (int64, error) result Lwt.t

seek_unmapped t start returns the offset of the next "hole": a region of the device which is guaranteed to be full of zeroes (typically guaranteed because it is unmapped)

Sourceval seek_mapped : t -> int64 -> (int64, error) result Lwt.t

seek_mapped t start returns the offset of the next region of the device which may have data in it (typically this is the next mapped region)

Sourceval rebuild_refcount_table : t -> (unit, write_error) result Lwt.t

rebuild_refcount_table t rebuilds the refcount table from scratch. Normally we won't update the refcount table live, for performance.

Sourcetype check_result = {
  1. free : int64;
    (*

    unused sectors

    *)
  2. used : int64;
    (*

    used sectors

    *)
}
Sourceval check : B.t -> (check_result, [ Mirage_block.error | `Reference_outside_file of int64 * int64 | `Duplicate_reference of (int64 * int) * (int64 * int) * int64 | `Msg of string ]) result Lwt.t

check t performs sanity checks of the file, looking for errors. The error `Reference_outside_file (src, dst) means that at offset src there is a reference to offset dst which is outside the file. The error `Duplicate_reference (ref1, ref2, target) means that references at both [ref1] and [ref2] both point to the same [target] offset.

Sourceval flush : t -> (unit, write_error) result Lwt.t

flush t flushes any outstanding buffered writes

Sourceval header : t -> Header.t

Return a snapshot of the current header

Sourceval to_config : t -> Config.t

to_config t returns the configuration of a device

Sourceval get_stats : t -> Stats.t

get_stats t returns the runtime statistics of a device

Sourcemodule Debug : sig ... end