1 /*
2 * Graph lock: rwlock to protect block layer graph manipulations (add/remove
3 * edges and nodes)
4 *
5 * Copyright (c) 2022 Red Hat
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 */
20 #ifndef GRAPH_LOCK_H
21 #define GRAPH_LOCK_H
22
23 #include "qemu/clang-tsa.h"
24
25 /**
26 * Graph Lock API
27 * This API provides a rwlock used to protect block layer
28 * graph modifications like edge (BdrvChild) and node (BlockDriverState)
29 * addition and removal.
30 * Currently we have 1 writer only, the Main loop, and many
31 * readers, mostly coroutines running in other AioContext thus other threads.
32 *
33 * We distinguish between writer (main loop, under BQL) that modifies the
34 * graph, and readers (all other coroutines running in various AioContext),
35 * that go through the graph edges, reading
36 * BlockDriverState ->parents and->children.
37 *
38 * The writer (main loop) has an "exclusive" access, so it first waits for
39 * current read to finish, and then prevents incoming ones from
40 * entering while it has the exclusive access.
41 *
42 * The readers (coroutines in multiple AioContext) are free to
43 * access the graph as long the writer is not modifying the graph.
44 * In case it is, they go in a CoQueue and sleep until the writer
45 * is done.
46 *
47 * If a coroutine changes AioContext, the counter in the original and new
48 * AioContext are left intact, since the writer does not care where is the
49 * reader, but only if there is one.
50 * As a result, some AioContexts might have a negative reader count, to
51 * balance the positive count of the AioContext that took the lock.
52 * This also means that when an AioContext is deleted it may have a nonzero
53 * reader count. In that case we transfer the count to a global shared counter
54 * so that the writer is always aware of all readers.
55 */
56 typedef struct BdrvGraphRWlock BdrvGraphRWlock;
57
58 /* Dummy lock object to use for Thread Safety Analysis (TSA) */
59 typedef struct TSA_CAPABILITY("mutex") BdrvGraphLock {
60 } BdrvGraphLock;
61
62 extern BdrvGraphLock graph_lock;
63
64 /*
65 * clang doesn't check consistency in locking annotations between forward
66 * declarations and the function definition. Having the annotation on the
67 * definition, but not the declaration in a header file, may give the reader
68 * a false sense of security because the condition actually remains unchecked
69 * for callers in other source files.
70 *
71 * Therefore, as a convention, for public functions, GRAPH_RDLOCK and
72 * GRAPH_WRLOCK annotations should be present only in the header file.
73 */
74 #define GRAPH_WRLOCK TSA_REQUIRES(graph_lock)
75 #define GRAPH_RDLOCK TSA_REQUIRES_SHARED(graph_lock)
76 #define GRAPH_UNLOCKED TSA_EXCLUDES(graph_lock)
77
78 /*
79 * TSA annotations are not part of function types, so checks are defeated when
80 * using a function pointer. As a workaround, annotate function pointers with
81 * this macro that will require that the lock is at least taken while reading
82 * the pointer. In most cases this is equivalent to actually protecting the
83 * function call.
84 */
85 #define GRAPH_RDLOCK_PTR TSA_GUARDED_BY(graph_lock)
86 #define GRAPH_WRLOCK_PTR TSA_GUARDED_BY(graph_lock)
87 #define GRAPH_UNLOCKED_PTR
88
89 /*
90 * register_aiocontext:
91 * Add AioContext @ctx to the list of AioContext.
92 * This list is used to obtain the total number of readers
93 * currently running the graph.
94 */
95 void register_aiocontext(AioContext *ctx);
96
97 /*
98 * unregister_aiocontext:
99 * Removes AioContext @ctx to the list of AioContext.
100 */
101 void unregister_aiocontext(AioContext *ctx);
102
103 /*
104 * bdrv_graph_wrlock:
105 * Start an exclusive write operation to modify the graph. This means we are
106 * adding or removing an edge or a node in the block layer graph. Nobody else
107 * is allowed to access the graph.
108 *
109 * Must only be called from outside bdrv_graph_co_rdlock.
110 *
111 * The wrlock can only be taken from the main loop, with BQL held, as only the
112 * main loop is allowed to modify the graph.
113 */
114 void no_coroutine_fn TSA_ACQUIRE(graph_lock) TSA_NO_TSA
115 bdrv_graph_wrlock(void);
116
117 /*
118 * bdrv_graph_wrunlock:
119 * Write finished, reset global has_writer to 0 and restart
120 * all readers that are waiting.
121 */
122 void no_coroutine_fn TSA_RELEASE(graph_lock) TSA_NO_TSA
123 bdrv_graph_wrunlock(void);
124
125 /*
126 * bdrv_graph_co_rdlock:
127 * Read the bs graph. This usually means traversing all nodes in
128 * the graph, therefore it can't happen while another thread is
129 * modifying it.
130 * Increases the reader counter of the current aiocontext,
131 * and if has_writer is set, it means that the writer is modifying
132 * the graph, therefore wait in a coroutine queue.
133 * The writer will then wake this coroutine once it is done.
134 *
135 * This lock should be taken from Iothreads (IO_CODE() class of functions)
136 * because it signals the writer that there are some
137 * readers currently running, or waits until the current
138 * write is finished before continuing.
139 * Calling this function from the Main Loop with BQL held
140 * is not necessary, since the Main Loop itself is the only
141 * writer, thus won't be able to read and write at the same time.
142 * The only exception to that is when we can't take the lock in the
143 * function/coroutine itself, and need to delegate the caller (usually main
144 * loop) to take it and wait that the coroutine ends, so that
145 * we always signal that a reader is running.
146 */
147 void coroutine_fn TSA_ACQUIRE_SHARED(graph_lock) TSA_NO_TSA
148 bdrv_graph_co_rdlock(void);
149
150 /*
151 * bdrv_graph_rdunlock:
152 * Read terminated, decrease the count of readers in the current aiocontext.
153 * If the writer is waiting for reads to finish (has_writer == 1), signal
154 * the writer that we are done via aio_wait_kick() to let it continue.
155 */
156 void coroutine_fn TSA_RELEASE_SHARED(graph_lock) TSA_NO_TSA
157 bdrv_graph_co_rdunlock(void);
158
159 /*
160 * bdrv_graph_rd{un}lock_main_loop:
161 * Just a placeholder to mark where the graph rdlock should be taken
162 * in the main loop. It is just asserting that we are not
163 * in a coroutine and in GLOBAL_STATE_CODE.
164 */
165 void TSA_ACQUIRE_SHARED(graph_lock) TSA_NO_TSA
166 bdrv_graph_rdlock_main_loop(void);
167
168 void TSA_RELEASE_SHARED(graph_lock) TSA_NO_TSA
169 bdrv_graph_rdunlock_main_loop(void);
170
171 /*
172 * assert_bdrv_graph_readable:
173 * Make sure that the reader is either the main loop,
174 * or there is at least a reader helding the rdlock.
175 * In this way an incoming writer is aware of the read and waits.
176 */
177 void GRAPH_RDLOCK assert_bdrv_graph_readable(void);
178
179 /*
180 * assert_bdrv_graph_writable:
181 * Make sure that the writer is the main loop and has set @has_writer,
182 * so that incoming readers will pause.
183 */
184 void GRAPH_WRLOCK assert_bdrv_graph_writable(void);
185
186 /*
187 * Calling this function tells TSA that we know that the lock is effectively
188 * taken even though we cannot prove it (yet) with GRAPH_RDLOCK. This can be
189 * useful in intermediate stages of a conversion to using the GRAPH_RDLOCK
190 * macro.
191 */
TSA_ASSERT_SHARED(graph_lock)192 static inline void TSA_ASSERT_SHARED(graph_lock) TSA_NO_TSA
193 assume_graph_lock(void)
194 {
195 }
196
197 typedef struct GraphLockable { } GraphLockable;
198
199 /*
200 * In C, compound literals have the lifetime of an automatic variable.
201 * In C++ it would be different, but then C++ wouldn't need QemuLockable
202 * either...
203 */
204 #define GML_OBJ_() (&(GraphLockable) { })
205
206 /*
207 * This is not marked as TSA_ACQUIRE_SHARED() because TSA doesn't understand the
208 * cleanup attribute and would therefore complain that the graph is never
209 * unlocked. TSA_ASSERT_SHARED() makes sure that the following calls know that
210 * we hold the lock while unlocking is left unchecked.
211 */
TSA_ACQUIRE_SHARED(graph_lock)212 static inline GraphLockable * TSA_ACQUIRE_SHARED(graph_lock) coroutine_fn
213 graph_lockable_auto_lock(GraphLockable *x)
214 {
215 bdrv_graph_co_rdlock();
216 return x;
217 }
218
TSA_RELEASE_SHARED(graph_lock)219 static inline void TSA_RELEASE_SHARED(graph_lock) coroutine_fn
220 graph_lockable_auto_unlock(GraphLockable **x)
221 {
222 bdrv_graph_co_rdunlock();
223 }
224
225 #define GRAPH_AUTO_UNLOCK __attribute__((cleanup(graph_lockable_auto_unlock)))
226
227 /*
228 * @var is only used to break the loop after the first iteration.
229 * @unlock_var can't be unlocked and then set to NULL because TSA wants the lock
230 * to be held at the start of every iteration of the loop.
231 */
232 #define WITH_GRAPH_RDLOCK_GUARD_(var) \
233 for (GraphLockable *unlock_var GRAPH_AUTO_UNLOCK = \
234 graph_lockable_auto_lock(GML_OBJ_()), \
235 *var = unlock_var; \
236 var; \
237 var = NULL)
238
239 #define WITH_GRAPH_RDLOCK_GUARD() \
240 WITH_GRAPH_RDLOCK_GUARD_(glue(graph_lockable_auto, __COUNTER__))
241
242 #define GRAPH_RDLOCK_GUARD(x) \
243 GraphLockable * GRAPH_AUTO_UNLOCK \
244 glue(graph_lockable_auto, __COUNTER__) G_GNUC_UNUSED = \
245 graph_lockable_auto_lock(GML_OBJ_())
246
247
248 typedef struct GraphLockableMainloop { } GraphLockableMainloop;
249
250 /*
251 * In C, compound literals have the lifetime of an automatic variable.
252 * In C++ it would be different, but then C++ wouldn't need QemuLockable
253 * either...
254 */
255 #define GMLML_OBJ_() (&(GraphLockableMainloop) { })
256
257 /*
258 * This is not marked as TSA_ACQUIRE_SHARED() because TSA doesn't understand the
259 * cleanup attribute and would therefore complain that the graph is never
260 * unlocked. TSA_ASSERT_SHARED() makes sure that the following calls know that
261 * we hold the lock while unlocking is left unchecked.
262 */
TSA_ASSERT_SHARED(graph_lock)263 static inline GraphLockableMainloop * TSA_ASSERT_SHARED(graph_lock) TSA_NO_TSA
264 graph_lockable_auto_lock_mainloop(GraphLockableMainloop *x)
265 {
266 bdrv_graph_rdlock_main_loop();
267 return x;
268 }
269
270 static inline void TSA_NO_TSA
graph_lockable_auto_unlock_mainloop(GraphLockableMainloop * x)271 graph_lockable_auto_unlock_mainloop(GraphLockableMainloop *x)
272 {
273 bdrv_graph_rdunlock_main_loop();
274 }
275
276 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GraphLockableMainloop,
277 graph_lockable_auto_unlock_mainloop)
278
279 #define GRAPH_RDLOCK_GUARD_MAINLOOP(x) \
280 g_autoptr(GraphLockableMainloop) \
281 glue(graph_lockable_auto, __COUNTER__) G_GNUC_UNUSED = \
282 graph_lockable_auto_lock_mainloop(GMLML_OBJ_())
283
284 #endif /* GRAPH_LOCK_H */
285
286