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

[Chunyan Liu <cyliu@xxxxxxxx>]

changes to V6:
  * redefine libxl and xl work separately
  * modified according to Ian's sugguestion

===========================================================================
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",[
    # save memory or not. "false" means disk-only snapshot
    ("memory",        bool),

    # memory state path when snapshot is external
    ("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:
       If domain is active, this is the domid of the domain.
       If domain is inactive, set domid=-1. Only disk-only snapshot can be
       done. libxl_domain_snapshot_args:memory should be 'false'.

    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. Only support this flag during external
       checkpoints.

    snapshot:
       memory:
           true or false.
           'false' means disk-only, won't save memory state.
           'true' means saving memory state. Memory would be saved in
           'memory_path'.
       memory_path:
           path to save memory file. NULL when 'memory' is false.
       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 'qcow2'.
              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 domain and related 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.

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

    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).

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

    About each input, explanation is the same as libxl_domain_snapshot_create.

3. Function Implementation

   libxl_domain_snapshot_create:
       1). check args validation
       2). if it is not disk-only, 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 if it's not disk-only.
       3). delete disk snapshot. (for internal disk snapshot, through qmp
           command or qemu-img command)

   libxl_domain_snapshot_revert:
       This may need to hack current libxl code. Could be (?):
       1). pause domain
       2). reload memory
       3). apply disk snapshot.
       4). restore domain config file
       5). resume.

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