Update version for v4.2.0 release
[qemu.git] / 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/module.h"
20 #include "qemu/queue.h"
21
22 typedef struct ReplicationOps ReplicationOps;
23 typedef struct ReplicationState ReplicationState;
24
25 /**
26 * SECTION:replication.h
27 * @title:Base Replication System
28 * @short_description: interfaces for handling replication
29 *
30 * The Replication Model provides a framework for handling Replication
31 *
32 * <example>
33 * <title>How to use replication interfaces</title>
34 * <programlisting>
35 * #include "replication.h"
36 *
37 * typedef struct BDRVReplicationState {
38 * ReplicationState *rs;
39 * } BDRVReplicationState;
40 *
41 * static void replication_start(ReplicationState *rs, ReplicationMode mode,
42 * Error **errp);
43 * static void replication_do_checkpoint(ReplicationState *rs, Error **errp);
44 * static void replication_get_error(ReplicationState *rs, Error **errp);
45 * static void replication_stop(ReplicationState *rs, bool failover,
46 * Error **errp);
47 *
48 * static ReplicationOps replication_ops = {
49 * .start = replication_start,
50 * .checkpoint = replication_do_checkpoint,
51 * .get_error = replication_get_error,
52 * .stop = replication_stop,
53 * }
54 *
55 * static int replication_open(BlockDriverState *bs, QDict *options,
56 * int flags, Error **errp)
57 * {
58 * BDRVReplicationState *s = bs->opaque;
59 * s->rs = replication_new(bs, &replication_ops);
60 * return 0;
61 * }
62 *
63 * static void replication_close(BlockDriverState *bs)
64 * {
65 * BDRVReplicationState *s = bs->opaque;
66 * replication_remove(s->rs);
67 * }
68 *
69 * BlockDriver bdrv_replication = {
70 * .format_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 */