xref: /qemu/include/block/graph-lock.h (revision 4bda8224)
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  */
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  */
212 static inline GraphLockable * TSA_ASSERT_SHARED(graph_lock) TSA_NO_TSA coroutine_fn
213 graph_lockable_auto_lock(GraphLockable *x)
214 {
215     bdrv_graph_co_rdlock();
216     return x;
217 }
218 
219 static inline void TSA_NO_TSA coroutine_fn
220 graph_lockable_auto_unlock(GraphLockable *x)
221 {
222     bdrv_graph_co_rdunlock();
223 }
224 
225 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GraphLockable, graph_lockable_auto_unlock)
226 
227 #define WITH_GRAPH_RDLOCK_GUARD_(var)                                         \
228     for (g_autoptr(GraphLockable) var = graph_lockable_auto_lock(GML_OBJ_()); \
229          var;                                                                 \
230          graph_lockable_auto_unlock(var), var = NULL)
231 
232 #define WITH_GRAPH_RDLOCK_GUARD() \
233     WITH_GRAPH_RDLOCK_GUARD_(glue(graph_lockable_auto, __COUNTER__))
234 
235 #define GRAPH_RDLOCK_GUARD(x)                                       \
236     g_autoptr(GraphLockable)                                        \
237     glue(graph_lockable_auto, __COUNTER__) G_GNUC_UNUSED =          \
238             graph_lockable_auto_lock(GML_OBJ_())
239 
240 
241 typedef struct GraphLockableMainloop { } GraphLockableMainloop;
242 
243 /*
244  * In C, compound literals have the lifetime of an automatic variable.
245  * In C++ it would be different, but then C++ wouldn't need QemuLockable
246  * either...
247  */
248 #define GMLML_OBJ_() (&(GraphLockableMainloop) { })
249 
250 /*
251  * This is not marked as TSA_ACQUIRE_SHARED() because TSA doesn't understand the
252  * cleanup attribute and would therefore complain that the graph is never
253  * unlocked. TSA_ASSERT_SHARED() makes sure that the following calls know that
254  * we hold the lock while unlocking is left unchecked.
255  */
256 static inline GraphLockableMainloop * TSA_ASSERT_SHARED(graph_lock) TSA_NO_TSA
257 graph_lockable_auto_lock_mainloop(GraphLockableMainloop *x)
258 {
259     bdrv_graph_rdlock_main_loop();
260     return x;
261 }
262 
263 static inline void TSA_NO_TSA
264 graph_lockable_auto_unlock_mainloop(GraphLockableMainloop *x)
265 {
266     bdrv_graph_rdunlock_main_loop();
267 }
268 
269 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GraphLockableMainloop,
270                               graph_lockable_auto_unlock_mainloop)
271 
272 #define GRAPH_RDLOCK_GUARD_MAINLOOP(x)                              \
273     g_autoptr(GraphLockableMainloop)                                \
274     glue(graph_lockable_auto, __COUNTER__) G_GNUC_UNUSED =          \
275             graph_lockable_auto_lock_mainloop(GMLML_OBJ_())
276 
277 #endif /* GRAPH_LOCK_H */
278 
279