[RFC V6] Libxl Domain Snapshot API Design

[Chunyan Liu <cyliu@suse.com>]

Since Bamvor left SUSE and turns to work on ARM server, I'd like to continue
this work and make progress. Following the discussion about V5, which mainly
focused on the API design, here post the updated API design. Thanks for any
of your further suggestions!

Main changes to V5:
* libxl_disk_snapshot: reuse libxl_device_disk rather than specify path,
    format separately in the structure. Including two libxl_device_disk
    components, one is to indicate the original disk info, one is to
    indicate the external snapshot info if it is 'external snapshot'.
* define common APIs for domain snapshot creating/deleting/reverting,
  rather than a group of functions for disk snapshot operations.
* remove those APIs for loading/storing/deleting snapshot config.

V5 is here:
http://lists.xenproject.org/archives/html/xen-devel/2014-07/msg00893.html
V5 about API Design is here:
http://lists.xenproject.org/archives/html/xen-devel/2014-07/msg00897.html

===========================================================================
Libxl Domain Snapshot API

libxl_domain_snapshot = Struct("domain_snapshot",[
    ("name",          string),              /* snapshot name */
    ("description",   string),              /* snapshot description */
    ("creation_time", uint64),              /* creation time, in seconds */

    /* save memory or not. "false" means disk-only snapshot */
    ("memory",        bool),

    /* memory state file when snapshot is external */
    ("memory_file",   string),

    /* Array to store disk snapshot info. */
    ("disks", Array(libxl_disk_snapshot, "num_disks")),
    ])

libxl_disk_snapshot = Struct("disk_snapshot",[
    ("disk",           libxl_device_disk),      /* orignal disk */
    ("name",           string),                 /* snapshot name */
    ("external",       bool),                   /* external snapshot or not */

    /* external snapshot info, including file path and format, etc.
     * if "external" is false, this will be "NULL".
     */
    ("external_sn",    libxl_device_disk),
    ])

enum libxlDomainSnapshotCreateFlags {
    /* disk snapshot, not system checkpoint */
    LIBXL_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY	=  1,

    /* create the snapshot while the guest is running */
    LIBXL_DOMAIN_SNAPSHOT_CREATE_LIVE	        =  2,
}

enum libxlDomainSnapshotDeleteFlags {
    LIBXL_DOMAIN_SNAPSHOT_DELETE_CHILDREN	=  1, /* delete children too */
}

enum virDomainSnapshotRevertFlags {
    LIBXL_DOMAIN_SNAPSHOT_REVERT_RUNNING        =  1, /* run after revert */
    LIBXL_DOMAIN_SNAPSHOT_REVERT_PAUSED         =  2, /* pause after revert */
    LIBXL_DOMAIN_SNAPSHOT_REVERT_FORCE          =  4, /* force revert */
}

int libxl_domain_snapshot_create(libxl_ctx *ctx, const char *domname,
                                 libxl_domain_snapshot *snapshot,
                                 unsigned int flags);

    Creates a new snapshot of a domain based on the snapshot config contained
    in @snapshot.

    If @flags includes LIBXL_DOMAIN_SNAPSHOT_CREATE_LIVE, then the domain is not
    paused while creating the snapshot, like live migration. This increases size
    of the memory dump file, but reducess downtime of the guest. Only support
    this flag during external checkpoints.

    If @flags includes LIBXL_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY, then the snapshot
    will be limited to the disks described in @snapshot, and no VM state will
    be saved. For an active guest, this is not supported.

    ctx: context
    domname:  domain name
    snapshot: configuration of domain snapshot
    flags: bitwise-OR of libxlDomainSnapshotCreateFlags
    Returns: 0 on success, -1 on failure


int libxl_domain_snapshot_delete(libxl_ctx *ctx, const char *domname,
                                 const char *snapshot_name,
                                 unsigned int flags);

    Delete a snapshot.

    If @flags is 0, then just this snapshot is deleted, and changes from this
    snapshot are automatically merged into children snapshots.

    If @flags includes LIBXL_DOMAIN_SNAPSHOT_DELETE_CHILDREN, then this snapshot
    and any descendant snapshots are deleted.

    ctx: context
    domname: domain name
    snapshot_name: snapshot name
    flags: bitwise-OR of supported libxlDomainSnapshotDeleteFlags
    Returns: 0 on success, -1 on error.

int libxl_disk_snapshot_revert(libxl_ctx *ctx, const char *domname,
                               const char *snapshot_name,
                               unsigned int flags);

    Revert the domain to a given snapshot.

    Normally, the domain will revert to the same state the domain was in while
    the snapshot was taken (whether inactive, running, or paused).

    If @flags includes LIBXL_DOMAIN_SNAPSHOT_REVERT_RUNNING, then overrides the
    snapshot state to guarantee a running domain after the revert.

    If @flags includes LIBXL_DOMAIN_SNAPSHOT_REVERT_PAUSED, then guarantees a
    paused domain after the revert.

    ctx: context
    domname: domain name
    snapshot_name: snapshot name
    flags: bitwise-OR of supported libxlDomainSnapshotRevertFlags
    Returns: 0 on success, -1 on error.