[Xen-devel] [RFC V8 2/3] libxl domain snapshot API design

[Chunyan Liu <cyliu@xxxxxxxx>]

changes to V7:
  * remove libxl_domain_snapshot_revert API
  * about libxl_domain_snapshot_delete, disk snapshot part
    could be extracted to libxlu if we would support many kinds of
    disk backendtypes in future. Add words to the docs, but not
    extended. Basic goal will support only raw and qcow2.
  * remove all disk-only descriptions. Won't support disk-only
    snapshot in xl and libxl.

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

1. New Structures

libxl_disk_snapshot = Struct("disk_snapshot",[
    # target disk
    ("disk",            libxl_device_disk),

    # disk snapshot name
    ("name",            string),

    # internal/external disk snapshot?
    ("external",        bool),

    # for external disk snapshot, specify following two field
    ("external_format", string),
    ("external_path",   string),
    ])

libxl_domain_snapshot_args = Struct("domain_snapshot_args",[
    # memory state path
    ("memory_path",   string),

    # array to store disk snapshot info
    ("disks",         Array(libxl_disk_snapshot, "num_disks")),
    ]

2. New Functions

int libxl_domain_snapshot_create(libxl_ctx *ctx, int domid,
                                 libxl_domain_snapshot_args *snapshot,
                                 bool live)

    Creates a new snapshot of a domain based on the snapshot config contained
    in @snapshot. Save domain and do disk snapshot.

    ctx (INPUT): context
    domid (INPUT):  domain id
    snapshot (INPUT): configuration of domain snapshot
    live (INPUT):   live snapshot or not
    Returns: 0 on success, -1 on failure

    ctx:
       context.

    domid:
       domid of the domain.

    live:
       true or false.
       when live is 'true', 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.

    snapshot:
       memory_path:
           path to save memory state.
       num_disks:
           number of disks that need to take disk snapshot.
       disks:
           array of disk snapshot configuration. Has num_disks members.
           libxl_device_disk:
               structure to represent which disk.
           name:
               snapshot name.
           external:
               true or flase.
               'false' means internal disk snapshot. external_format and
               external_path will be ignored.
               'true' means external disk snapshot, then external_format and
               external_path should be provided.
          external_format:
              Should be provided when 'external' is true. If not provided, will
              use default format proper to the backend file.
              Ignored when 'external' is false.
          external_path:
              Must be provided when 'external' is true.
              Ignored when 'external' is false.


int libxl_domain_snapshot_delete(libxl_ctx *ctx, int domid,
                                 libxl_domain_snapshot_args *snapshot);

    Delete a snapshot.
    This will delete the related memory state file and disk snapshots.

    ctx (INPUT): context
    domid (INPUT): domain id
    snapshot (INPUT): domain snapshot related info
    Returns: 0 on success, -1 on error.

    About each input, explanation is the same as libxl_domain_snapshot_create.


libxl_domain_snapshot_revert API will not be provided. Considering that:
    domain snapshot revert work could be done by destroying the domain
    and then restore a new domain from the snapshot. Application could
    do that by themselves. If wrapped as an libxl API, the new domain
    will not be awared by libvirt, causing problems in libvirt, worse
    than better.

3. Function Implementation

   libxl_domain_snapshot_create:
       1). check args validation
       2). save domain memory through save-domain
       3). take disk snapshot by qmp command (if domian is active) or qemu-img
           command (if domain is inactive).

   libxl_domain_snapshot_delete:
       1). check args validation
       2). remove memory state file.
       3). delete disk snapshot. (for internal disk snapshot, through qmp
           command or qemu-img command)

   To handle disk snapshot (disk snapshot create or delete) of different
   disk backend types, this work could be extracted to libxlu in future.
   (Base goal would support raw and qcow2 types only, as currently kvm does).

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel