qapi: add missing colon-ending for section name
[qemu/armbru.git] / replication.h
blobece6ca6133e0613c495f70a15878782a15b93401
1 /*
2 * Replication filter
4 * Copyright (c) 2016 HUAWEI TECHNOLOGIES CO., LTD.
5 * Copyright (c) 2016 Intel Corporation
6 * Copyright (c) 2016 FUJITSU LIMITED
8 * Author:
9 * Changlong Xie <xiecl.fnst@cn.fujitsu.com>
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.
15 #ifndef REPLICATION_H
16 #define REPLICATION_H
18 #include "qemu/queue.h"
20 typedef struct ReplicationOps ReplicationOps;
21 typedef struct ReplicationState ReplicationState;
23 /**
24 * SECTION:replication.h
25 * @title:Base Replication System
26 * @short_description: interfaces for handling replication
28 * The Replication Model provides a framework for handling Replication
30 * <example>
31 * <title>How to use replication interfaces</title>
32 * <programlisting>
33 * #include "replication.h"
35 * typedef struct BDRVReplicationState {
36 * ReplicationState *rs;
37 * } BDRVReplicationState;
39 * static void replication_start(ReplicationState *rs, ReplicationMode mode,
40 * Error **errp);
41 * static void replication_do_checkpoint(ReplicationState *rs, Error **errp);
42 * static void replication_get_error(ReplicationState *rs, Error **errp);
43 * static void replication_stop(ReplicationState *rs, bool failover,
44 * Error **errp);
46 * static ReplicationOps replication_ops = {
47 * .start = replication_start,
48 * .checkpoint = replication_do_checkpoint,
49 * .get_error = replication_get_error,
50 * .stop = replication_stop,
51 * }
53 * static int replication_open(BlockDriverState *bs, QDict *options,
54 * int flags, Error **errp)
55 * {
56 * BDRVReplicationState *s = bs->opaque;
57 * s->rs = replication_new(bs, &replication_ops);
58 * return 0;
59 * }
61 * static void replication_close(BlockDriverState *bs)
62 * {
63 * BDRVReplicationState *s = bs->opaque;
64 * replication_remove(s->rs);
65 * }
67 * BlockDriver bdrv_replication = {
68 * .format_name = "replication",
69 * .protocol_name = "replication",
70 * .instance_size = sizeof(BDRVReplicationState),
72 * .bdrv_open = replication_open,
73 * .bdrv_close = replication_close,
74 * };
76 * static void bdrv_replication_init(void)
77 * {
78 * bdrv_register(&bdrv_replication);
79 * }
81 * block_init(bdrv_replication_init);
82 * </programlisting>
83 * </example>
85 * We create an example about how to use replication interfaces in above.
86 * Then in migration, we can use replication_(start/stop/do_checkpoint/
87 * get_error)_all to handle all replication operations.
90 /**
91 * ReplicationState:
92 * @opaque: opaque pointer value passed to this ReplicationState
93 * @ops: replication operation of this ReplicationState
94 * @node: node that we will insert into @replication_states QLIST
96 struct ReplicationState {
97 void *opaque;
98 ReplicationOps *ops;
99 QLIST_ENTRY(ReplicationState) node;
103 * ReplicationOps:
104 * @start: callback to start replication
105 * @stop: callback to stop replication
106 * @checkpoint: callback to do checkpoint
107 * @get_error: callback to check if error occurred during replication
109 struct ReplicationOps {
110 void (*start)(ReplicationState *rs, ReplicationMode mode, Error **errp);
111 void (*stop)(ReplicationState *rs, bool failover, Error **errp);
112 void (*checkpoint)(ReplicationState *rs, Error **errp);
113 void (*get_error)(ReplicationState *rs, Error **errp);
117 * replication_new:
118 * @opaque: opaque pointer value passed to ReplicationState
119 * @ops: replication operation of the new relevant ReplicationState
121 * Called to create a new ReplicationState instance, and then insert it
122 * into @replication_states QLIST
124 * Returns: the new ReplicationState instance
126 ReplicationState *replication_new(void *opaque, ReplicationOps *ops);
129 * replication_remove:
130 * @rs: the ReplicationState instance to remove
132 * Called to remove a ReplicationState instance, and then delete it from
133 * @replication_states QLIST
135 void replication_remove(ReplicationState *rs);
138 * replication_start_all:
139 * @mode: replication mode that could be "primary" or "secondary"
140 * @errp: returns an error if this function fails
142 * Start replication, called in migration/checkpoint thread
144 * Note: the caller of the function MUST make sure vm stopped
146 void replication_start_all(ReplicationMode mode, Error **errp);
149 * replication_do_checkpoint_all:
150 * @errp: returns an error if this function fails
152 * This interface is called after all VM state is transferred to Secondary QEMU
154 void replication_do_checkpoint_all(Error **errp);
157 * replication_get_error_all:
158 * @errp: returns an error if this function fails
160 * This interface is called to check if error occurred during replication
162 void replication_get_error_all(Error **errp);
165 * replication_stop_all:
166 * @failover: boolean value that indicates if we need do failover or not
167 * @errp: returns an error if this function fails
169 * It is called on failover. The vm should be stopped before calling it, if you
170 * use this API to shutdown the guest, or other things except failover
172 void replication_stop_all(bool failover, Error **errp);
174 #endif /* REPLICATION_H */