replication.h

   1 /*
   2  * Replication filter
   3  *
   4  * Copyright (c) 2016 HUAWEI TECHNOLOGIES CO., LTD.
   5  * Copyright (c) 2016 Intel Corporation
   6  * Copyright (c) 2016 FUJITSU LIMITED
   7  *
   8  * Author:
   9  *   Changlong Xie <xiecl.fnst@cn.fujitsu.com>
  10  *
  11  * This work is licensed under the terms of the GNU GPL, version 2 or later.
  12  * See the COPYING file in the top-level directory.
  13  */
  14
  15 #ifndef REPLICATION_H
  16 #define REPLICATION_H
  17
  18 #include "qapi/qapi-types-block-core.h"
  19 #include "qemu/queue.h"
  20
  21 typedef struct ReplicationOps ReplicationOps;
  22 typedef struct ReplicationState ReplicationState;
  23
  24 /**
  25  * SECTION:replication.h
  26  * @title:Base Replication System
  27  * @short_description: interfaces for handling replication
  28  *
  29  * The Replication Model provides a framework for handling Replication
  30  *
  31  * <example>
  32  *   <title>How to use replication interfaces</title>
  33  *   <programlisting>
  34  * #include "replication.h"
  35  *
  36  * typedef struct BDRVReplicationState {
  37  *     ReplicationState *rs;
  38  * } BDRVReplicationState;
  39  *
  40  * static void replication_start(ReplicationState *rs, ReplicationMode mode,
  41  *                               Error **errp);
  42  * static void replication_do_checkpoint(ReplicationState *rs, Error **errp);
  43  * static void replication_get_error(ReplicationState *rs, Error **errp);
  44  * static void replication_stop(ReplicationState *rs, bool failover,
  45  *                              Error **errp);
  46  *
  47  * static ReplicationOps replication_ops = {
  48  *     .start = replication_start,
  49  *     .checkpoint = replication_do_checkpoint,
  50  *     .get_error = replication_get_error,
  51  *     .stop = replication_stop,
  52  * }
  53  *
  54  * static int replication_open(BlockDriverState *bs, QDict *options,
  55  *                             int flags, Error **errp)
  56  * {
  57  *     BDRVReplicationState *s = bs->opaque;
  58  *     s->rs = replication_new(bs, &replication_ops);
  59  *     return 0;
  60  * }
  61  *
  62  * static void replication_close(BlockDriverState *bs)
  63  * {
  64  *     BDRVReplicationState *s = bs->opaque;
  65  *     replication_remove(s->rs);
  66  * }
  67  *
  68  * BlockDriver bdrv_replication = {
  69  *     .format_name                = "replication",
  70  *     .protocol_name              = "replication",
  71  *     .instance_size              = sizeof(BDRVReplicationState),
  72  *
  73  *     .bdrv_open                  = replication_open,
  74  *     .bdrv_close                 = replication_close,
  75  * };
  76  *
  77  * static void bdrv_replication_init(void)
  78  * {
  79  *     bdrv_register(&bdrv_replication);
  80  * }
  81  *
  82  * block_init(bdrv_replication_init);
  83  *   </programlisting>
  84  * </example>
  85  *
  86  * We create an example about how to use replication interfaces in above.
  87  * Then in migration, we can use replication_(start/stop/do_checkpoint/
  88  * get_error)_all to handle all replication operations.
  89  */
  90
  91 /**
  92  * ReplicationState:
  93  * @opaque: opaque pointer value passed to this ReplicationState
  94  * @ops: replication operation of this ReplicationState
  95  * @node: node that we will insert into @replication_states QLIST
  96  */
  97 struct ReplicationState {
  98     void *opaque;
  99     ReplicationOps *ops;
 100     QLIST_ENTRY(ReplicationState) node;
 101 };
 102
 103 /**
 104  * ReplicationOps:
 105  * @start: callback to start replication
 106  * @stop: callback to stop replication
 107  * @checkpoint: callback to do checkpoint
 108  * @get_error: callback to check if error occurred during replication
 109  */
 110 struct ReplicationOps {
 111     void (*start)(ReplicationState *rs, ReplicationMode mode, Error **errp);
 112     void (*stop)(ReplicationState *rs, bool failover, Error **errp);
 113     void (*checkpoint)(ReplicationState *rs, Error **errp);
 114     void (*get_error)(ReplicationState *rs, Error **errp);
 115 };
 116
 117 /**
 118  * replication_new:
 119  * @opaque: opaque pointer value passed to ReplicationState
 120  * @ops: replication operation of the new relevant ReplicationState
 121  *
 122  * Called to create a new ReplicationState instance, and then insert it
 123  * into @replication_states QLIST
 124  *
 125  * Returns: the new ReplicationState instance
 126  */
 127 ReplicationState *replication_new(void *opaque, ReplicationOps *ops);
 128
 129 /**
 130  * replication_remove:
 131  * @rs: the ReplicationState instance to remove
 132  *
 133  * Called to remove a ReplicationState instance, and then delete it from
 134  * @replication_states QLIST
 135  */
 136 void replication_remove(ReplicationState *rs);
 137
 138 /**
 139  * replication_start_all:
 140  * @mode: replication mode that could be "primary" or "secondary"
 141  * @errp: returns an error if this function fails
 142  *
 143  * Start replication, called in migration/checkpoint thread
 144  *
 145  * Note: the caller of the function MUST make sure vm stopped
 146  */
 147 void replication_start_all(ReplicationMode mode, Error **errp);
 148
 149 /**
 150  * replication_do_checkpoint_all:
 151  * @errp: returns an error if this function fails
 152  *
 153  * This interface is called after all VM state is transferred to Secondary QEMU
 154  */
 155 void replication_do_checkpoint_all(Error **errp);
 156
 157 /**
 158  * replication_get_error_all:
 159  * @errp: returns an error if this function fails
 160  *
 161  * This interface is called to check if error occurred during replication
 162  */
 163 void replication_get_error_all(Error **errp);
 164
 165 /**
 166  * replication_stop_all:
 167  * @failover: boolean value that indicates if we need do failover or not
 168  * @errp: returns an error if this function fails
 169  *
 170  * It is called on failover. The vm should be stopped before calling it, if you
 171  * use this API to shutdown the guest, or other things except failover
 172  */
 173 void replication_stop_all(bool failover, Error **errp);
 174
 175 #endif /* REPLICATION_H */