[libvirt] RFC (V2) New virDomainBlockPull API family to libvirt

Adam Litke agl at us.ibm.com
Thu Jul 21 18:55:04 UTC 2011

Here are the patches to implement the BlockPull/BlockJob API as discussed and
agreed to.  I am testing with a python script (included for completeness as the
final patch).  The qemu monitor interface is not expected to change in the
future.  Stefan is planning to submit placeholder commands for upstream qemu
until the generic streaming support is implemented.

Changes since V1:
 - Make virDomainBlockPullAbort() and virDomainGetBlockPullInfo() into a
   generic BlockJob interface.
 - Added virDomainBlockJobSetSpeed()
 - Rename VIR_DOMAIN_EVENT_ID_BLOCK_PULL event to fit into block job API
 - Add bandwidth argument to virDomainBlockPull()

Summary of changes since first generation patch series:
 - Qemu dropped incremental streaming so remove libvirt incremental
   BlockPull() API
 - Rename virDomainBlockPullAll() to virDomainBlockPull()
 - Changes required to qemu monitor handlers for changed command names


To help speed the provisioning process for large domains, new QED disks are
created with backing to a template image.  These disks are configured with 
copy on read such that blocks that are read from the backing file are copied
to the new disk.  This reduces I/O over a potentially costly path to the
backing image.

In such a configuration, there is a desire to remove the dependency on the
backing image as the domain runs.  To accomplish this, qemu will provide an
interface to perform sequential copy on read operations during normal VM
operation.  Once all data has been copied, the disk image's link to the 
backing file is removed.

The virDomainBlockPull API family brings this functionality to libvirt.

virDomainBlockPull() instructs the hypervisor to stream the entire device in
the background.  Progress of this operation can be checked with the function
virDomainBlockJobInfo().  An ongoing stream can be cancelled with
virDomainBlockJobAbort().  virDomainBlockJobSetSpeed() allows you to limit the
bandwidth that the operation may consume. 

An event (VIR_DOMAIN_EVENT_ID_BLOCK_JOB) will be emitted when a disk has been
fully populated or if a BlockPull() operation was terminated due to an error.
This event is useful to avoid polling on virDomainBlockJobInfo() for
completion and could also be used by the security driver to revoke access to
the backing file when it is no longer needed.

make check:                  PASS
make syntax-check:           PASS
make -C tests valgrind:      PASS

[PATCH 1/8] Add new API virDomainBlockPull* to headers
[PATCH 2/8] virDomainBlockPull: Implement the main entry points
[PATCH 3/8] Add virDomainBlockPull support to the remote driver
[PATCH 4/8] Implement virDomainBlockPull for the qemu driver
[PATCH 5/8] Enable the virDomainBlockPull API in virsh
[PATCH 6/8] Enable virDomainBlockPull in the python API.
[PATCH 7/8] Asynchronous event for BlockJob completion
[PATCH 8/8] Test the blockJob/BlockPull API

More information about the libvir-list mailing list