11:56 a.m.
Here is version 4 of the BlockStream API (now called BlockPull). Hopefully this
version addresses all remaining concerns and I can begin to work on the code.
Does everyone approve of the new name 'virDomainBlockPull'?
Changes since V3:
- Renamed the API to 'Block Pull' to emphasize the effect of the API over its
method of operation.
- Changed virDomainGetBlockPullInfo() to accept a path argument and to return
information about that path alone.
- Added a new virDomainEvent to report final status when using CONTINUOUS mode.
/*
* Block Pull API
*/
typedef enum {
/*
* If set, virDomainBlockPull() will operate on the entire device in the
* background. The status can be checked and the operation aborted by
* using the functions virDomainBlockPullInfo() and
* virDomainBlockPullAbort().
*/
VIR_DOMAIN_BLOCK_PULL_CONTINUOUS = 1,
} virDomainBlockPullFlags;
/* An iterator for initiating and monitoring block pull operations */
typedef unsigned long long virDomainBlockPullCursor;
typedef struct _virDomainBlockPullInfo virDomainBlockPullInfo;
struct _virDomainBlockPullInfo {
/*
* The following fields provide an indication of block pull progress. @cur
* indicates the current position and will be between 0 and @end. @end is
* the final cursor position for this operation and represents completion.
* To approximate progress, divide @cur by @end.
*/
virDomainBlockPullCursor cur;
virDomainBlockPullCursor end;
};
typedef virDomainBlockPullInfo *virDomainBlockPullInfoPtr;
/**
* virDomainBlockPull:
* @dom: pointer to domain object
* @path: Fully-qualified filename of disk
* @cursor: pointer to a virDomainBlockPullCursor, or NULL
* @flags: One of virDomainBlockPullFlags, or zero
*
* Populate a disk image with data from its backing image. Once all data from
* its backing image has been pulled, the disk no longer depends on a backing
* image.
*
* If VIR_DOMAIN_BLOCK_PULL_CONTINUOUS is specified, the entire device will be
* streamed in the background. Otherwise, the value stored in @cursor will be
* used to stream an increment.
*
* Returns -1 in case of failure, 0 when successful. On success and when @flags
* does not contain VIR_DOMAIN_BLOCK_PULL_CONTINUOUS, the iterator @cursor will
* be updated to the proper value for use in a subsequent call.
*/
int virDomainBlockPull(virDomainPtr dom,
const char *path,
virDomainBlockPullCursor *cursor,
unsigned int flags);
/**
* virDomainBlockPullAbort:
* @dom: pointer to domain object
* @path: fully-qualified filename of disk
* @flags: currently unused, for future extension
*
* Cancel a pull operation that has been previously started by a call to
* virDomainBlockPull() with the VIR_DOMAIN_BLOCK_PULL_CONTINUOUS flag.
*
* Returns -1 in case of failure, 0 when successful.
*/
int virDomainBlockPullAbort(virDomainPtr dom,
const char *path,
unsigned int flags);
/**
* virDomainGetBlockPullInfo:
* @dom: pointer to domain object
* @path: fully-qualified filename of disk
* @info: pointer to a virDomainBlockPullInfo structure
* @flags: currently unused, for future extension
*
* Request progress information on a block pull operation that has been started
* with the VIR_DOMAIN_BLOCK_PULL_CONTINUOUS flag set. If an operation is
* active for the given parameters, @info will be updated with the current
* progress.
*
* Returns -1 in case of failure, 0 when successful.
*/
int virDomainGetBlockPullInfo(virDomainPtr dom,
const char *path,
virDomainBlockStreamInfoPtr info,
unsigned int flags);
The following new asynchronous event will be made available for subscription:
VIR_DOMAIN_EVENT_ID_BLOCK_PULL = 7,
typedef enum {
VIR_DOMAIN_BLOCK_PULL_COMPLETED,
VIR_DOMAIN_BLOCK_PULL_FAILED,
} virConnectDomainEventBlockPullStatus;
typedef void (*virConnectDomainEventBlockPullCallback(virConnectPtr conn,
virDomainPtr dom,
const char *path,
int status);
Upon receipt of this event and when the status field indicates success, libvirt
will revoke access to the backing file which is no longer needed by the domain.
NOTE: Qemu will emit an asynchronous event (VIR_DOMAIN_BLOCK_PULL_COMPLETED)
after any operation that eliminates the dependency on the backing file. This
could be a virDomainBlockPull() without VIR_DOMAIN_BLOCK_PULL_CONTINUOUS and
will allow libvirt to manage backing file security regardless of the pull mode
used.
--
Adam Litke
IBM Linux Technology Center