[RFC V5 2/5] Libxl Domain Snapshot API Design

[Bamvor Jian Zhang <bjzhang@suse.com>]

Libxl Domain Snapshot API Design

1. New Structures

    Domain snapshot introduces two new structures:
    - "libxl_domain_snapshot" store domain snapshot information, it contains
       libxl_disk_snapshot array.
    - "libxl_disk_snapshot" stores disk snapshot related information.

    Both are defined in libxl_types.idl, which will generate the following
    libxl-json helper functions:

    char *libxl_domain_snapshot_to_json(libxl_ctx *ctx,
                                        libxl_domain_snapshot *p);
    int libxl_domain_snapshot_from_json(libxl_ctx *ctx,
                                        libxl_domain_snapshot *p, const char *s);
    char *libxl_disk_snapshot_to_json(libxl_ctx *ctx,
                                      libxl_disk_snapshot *p);
    int libxl_disk_snapshot_from_json(libxl_ctx *ctx,
                                      libxl_disk_snapshot *p, const char *s);

    These functions will be used internally, and are very userful when load/store
    domain snapshot configuration file (libxl-json format).

    Struct Details:

    libxl_disk_snapshot = Struct("disk_snapshot",[
        ("device",        string),              /* The name of disk: hda, hdc */

        ("name",          string),              /* The name of disk snapshot.
                                                 * Usually it is inherited from
                                                 * libxl_domain_snapshot.
                                                 */

        ("file",          string),              /* The new disk file after
                                                 * external snapshot. empty for
                                                 * internal snapshot.
                                                 */

        ("format",        libxl_disk_format),   /* The format of external
                                                 * snapshot file. For the
                                                 * internal snapshot, it's
                                                 * ignored and it should be
                                                 * LIBXL_DISK_FORMAT_UNKNOWN
                                                 */

        ("path",          string),              /* The path of current disk
                                                 * backend. It gets from
                                                 * libxl_device_disk_getinfo.
                                                 * It will be force-empty when
                                                 * store domain snapshot
                                                 * configuration in order to
                                                 * hide this from users.
                                                 */
        ])

    libxl_domain_snapshot = Struct("domain_snapshot",[
        ("name",          string),              /* The name of the domain
                                                 * snapshot. It should not be
                                                 * empty.
                                                 */

        ("description",   string),              /* The description of snapshot.
                                                 * It could be empty.
                                                 */

        ("creation_time", uint64),              /* The creation time of domain
                                                 * snapshot which is the epoch
                                                 * second from 1, Jan 1970.
                                                 */

        ("memory",        string),              /* The path to save domain
                                                 * memory image. 'empty' means
                                                 * it is a disk-only snapshot.
                                                 * note that "yes" or "no" is
                                                 * not allowed, this is different
                                                 * from xl.snapshot.pod.5
                                                 */

        /* Following state represents the domain state in the beginning of snapshot.
         * These state gets from libxl_domain_info.
         */
        ("running",       bool),
        ("blocked",       bool),
        ("paused",        bool),
        ("shutdown",      bool),
        ("dying",         bool),

        /* The array of disk snapshot information belong to this domain snapshot. */
        ("disks", Array(libxl_disk_snapshot, "num_disks")),
        ])


2. New Functions

  2.1 Management functions for domain snapshot config file (libxl-json format).

    /* There are two type of config file relative to domain snapshot: user
     * config file and internal domain snapshot configuration file(libxl-json
     * format). The relation of the two config files are like xl.cfg and
     * libxl-json for domain configuration.
     * The user visiable config file (KEY=VALUE format) is only used for
     * creation. The internal domain snapshot config file is located at
     * "/var/lib/xen/snapshots/<domain_uuid>"\
     * snapshotdata-<snapshot_name>.libxl-json". This file is only for internal
     * usage, not for users. user should not modify the libxl-json format file.
     *
     * Currently, libvirt use XML format snapshot configuration file for user
     * both input(snapshot create) and output(snapshot-dumpxml). And libvirt
     * qemu driver store with xml format as internal usage as well.
     * For libxl, if libxl hope it is easy to migrate domain between different
     * toolstack, then all the toolstack should use the same internal config
     * file: libxl-json format. it will not affect the user experience. e.g. xl
     * will use the KEY=VALUE format while libvirt will use the xml format.
     */
    /*
     * function:  To retrieve domain snapshot configuration file contents from
     *            "/var/lib/xen/snapshots/<domain_uuid>/"snapshotdata-\
     *            <snapshot->name>.libxl-json", and store the information
     *            to @snapshot.
     * @domid:    The domain id. It is used to get the uuid of domain.
     * @snapshot: The caller should provide valid @snapshot->name. On return,
     *            @snapshot will hold the domain snapshot information retrieved
     *            from the file.
     * return value:
     *            0:  success
     *            <0: fail. Config file doesn't exist or the file format is wrong.
     */

    int libxl_load_dom_snapshot_conf(libxl_ctx *ctx, uint32_t domid,
                                     libxl_domain_snapshot *snapshot);


    /*
     * function:  To convert @snapshot to libxl-json format, and save at
     *            /var/lib/xen/snapshots/<domain_uuid>/"snapshotdata-\
     *            <snapshot->name>.libxl-json"
     * @domid:    The domain id. It is used to get the uuid of domain.
     * @snapshot: @snapshot->name should be valid name in the caller's file
     *            system. Other strings in this strcut should not be NULL. For
     *            the empty item the caller should set as "".
     * return value:
     *            0:  successful
     *            ERROR_INVAL:  snapshot name is empty
     *            <0: fail. snapshot information invalid or write file fail.
     */

    int libxl_store_dom_snapshot_conf(libxl_ctx *ctx, uint32_t domid,
                                      libxl_domain_snapshot *snapshot);


    /*
     * function:  To delete configuration file of indicated domain snapshot:
     *            /var/lib/xen/snapshots/<domain_uuid>/"snapshotdata-\
     *            <snapshot->name>.libxl-json"
     * @domid:    The domain id. It is used to get the uuid of domain.
     * @snapshot: The caller should provide valid @snapshot->name. other value
     *            of this struct is ignored in this function.
     * return value:
     *            0:  successful
     *            <0: fail. file delete fail.
     */

    int libxl_delete_dom_snapshot_conf(libxl_ctx *ctx, uint32_t domid,
                                       libxl_domain_snapshot *snapshot);


    /*
     * function: To retrieve all snapshot info of the speicfic domain from
     *           /var/lib/xen/snapshots/<domain_uuid>", and return the
     *           result to @libxl_domain_snapshot array. Put number of
     *           snapshot(s) to @num. The caller is responsible for free
     *           the libxl_domain_snapshot array.
     *           This is useful when toolstack want to get all the snapshot
     *           information relative to the specific domain. e.g. xl
     *           snapshot-list or libvirt libxl driver load/reload.
     * @domid:   domain id. will get domain_uuid from domid.
     * @num:     hold the number of snapshot(s) as part of the return result.
     * return value:
     *           NULL:     no valid snapshot configuration for such domain.
     *           non-NULL: successful
     */

    libxl_domain_snapshot *
    libxl_list_dom_snapshot(libxl_ctx *ctx, uint32_t domid, int *num);


  2.2 functions for disk snapshot operations

    /*
     * function:  To create disk(s) snapshot according to config in @snapshot
     *            array. Disk (one or more) snapshot in this operation is
     *            handled by qmp transaction. The transaction operation ensures
     *            that all disks are consistent. This function is used in
     *            'domain snapshot create'.
     * @domid:    domain id
     * @snapshot: array of disk snapshot
     * @num:      number of disk snapshot struct in above array
     * return value:
     *            0:   successful
     *            <0:  fail
     */

    int libxl_disk_snapshot_create(libxl_ctx *ctx, int domid,
                                   libxl_disk_snapshot *snapshot, int num);


    /*
     * function:  To delete disk snapshot according to the config in @snapshot
     *            array. Only the internal snapshot is supported currently. It
     *            will call blockdev-snapshot-delete-internal-sync qmp
     *            command for each disk snapshot delete operation.
     * @domid:    domain id
     * @snapshot: array of disk snapshot
     * @num:      number of disk snapshot struct in above array
     * return value:
     *            0:   successful
     *            <0:  fail.
     */

    int libxl_disk_snapshot_delete(libxl_ctx *ctx, int domid,
                                   libxl_disk_snapshot *snapshot, int num);

    /*
     * function:  To revert the disk snapshot state according to @snapshot
     *            array. Since there is no qmp command to use and we cannot
     *            re-send paramters to inform it about the snapshot
     *            info when qemu running, so we will call "qemu-img snapshot\
     *            -a snapshot_name" to do revert operation. (better ideas??)
     * @domid:    domain id
     * @snapshot: array of disk snapshot
     * @num:      number of disk snapshot struct in above array
     * return value:
     *            0:   successful
     *            <0:  fail
     */
    int libxl_disk_snapshot_revert(libxl_ctx *ctx, int domid,
                                   libxl_disk_snapshot *snapshot, int num);