xref: /openbmc/qemu/include/block/graph-lock.h (revision 243975c0)
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  * If @bs is non-NULL, its AioContext is temporarily released.
115  *
116  * This function polls. Callers must not hold the lock of any AioContext other
117  * than the current one and the one of @bs.
118  */
119 void bdrv_graph_wrlock(BlockDriverState *bs) TSA_ACQUIRE(graph_lock) TSA_NO_TSA;
120 
121 /*
122  * bdrv_graph_wrunlock:
123  * Write finished, reset global has_writer to 0 and restart
124  * all readers that are waiting.
125  */
126 void bdrv_graph_wrunlock(void) TSA_RELEASE(graph_lock) TSA_NO_TSA;
127 
128 /*
129  * bdrv_graph_co_rdlock:
130  * Read the bs graph. This usually means traversing all nodes in
131  * the graph, therefore it can't happen while another thread is
132  * modifying it.
133  * Increases the reader counter of the current aiocontext,
134  * and if has_writer is set, it means that the writer is modifying
135  * the graph, therefore wait in a coroutine queue.
136  * The writer will then wake this coroutine once it is done.
137  *
138  * This lock should be taken from Iothreads (IO_CODE() class of functions)
139  * because it signals the writer that there are some
140  * readers currently running, or waits until the current
141  * write is finished before continuing.
142  * Calling this function from the Main Loop with BQL held
143  * is not necessary, since the Main Loop itself is the only
144  * writer, thus won't be able to read and write at the same time.
145  * The only exception to that is when we can't take the lock in the
146  * function/coroutine itself, and need to delegate the caller (usually main
147  * loop) to take it and wait that the coroutine ends, so that
148  * we always signal that a reader is running.
149  */
150 void coroutine_fn TSA_ACQUIRE_SHARED(graph_lock) TSA_NO_TSA
151 bdrv_graph_co_rdlock(void);
152 
153 /*
154  * bdrv_graph_rdunlock:
155  * Read terminated, decrease the count of readers in the current aiocontext.
156  * If the writer is waiting for reads to finish (has_writer == 1), signal
157  * the writer that we are done via aio_wait_kick() to let it continue.
158  */
159 void coroutine_fn TSA_RELEASE_SHARED(graph_lock) TSA_NO_TSA
160 bdrv_graph_co_rdunlock(void);
161 
162 /*
163  * bdrv_graph_rd{un}lock_main_loop:
164  * Just a placeholder to mark where the graph rdlock should be taken
165  * in the main loop. It is just asserting that we are not
166  * in a coroutine and in GLOBAL_STATE_CODE.
167  */
168 void TSA_ACQUIRE_SHARED(graph_lock) TSA_NO_TSA
169 bdrv_graph_rdlock_main_loop(void);
170 
171 void TSA_RELEASE_SHARED(graph_lock) TSA_NO_TSA
172 bdrv_graph_rdunlock_main_loop(void);
173 
174 /*
175  * assert_bdrv_graph_readable:
176  * Make sure that the reader is either the main loop,
177  * or there is at least a reader helding the rdlock.
178  * In this way an incoming writer is aware of the read and waits.
179  */
180 void GRAPH_RDLOCK assert_bdrv_graph_readable(void);
181 
182 /*
183  * assert_bdrv_graph_writable:
184  * Make sure that the writer is the main loop and has set @has_writer,
185  * so that incoming readers will pause.
186  */
187 void GRAPH_WRLOCK assert_bdrv_graph_writable(void);
188 
189 /*
190  * Calling this function tells TSA that we know that the lock is effectively
191  * taken even though we cannot prove it (yet) with GRAPH_RDLOCK. This can be
192  * useful in intermediate stages of a conversion to using the GRAPH_RDLOCK
193  * macro.
194  */
195 static inline void TSA_ASSERT_SHARED(graph_lock) TSA_NO_TSA
196 assume_graph_lock(void)
197 {
198 }
199 
200 typedef struct GraphLockable { } GraphLockable;
201 
202 /*
203  * In C, compound literals have the lifetime of an automatic variable.
204  * In C++ it would be different, but then C++ wouldn't need QemuLockable
205  * either...
206  */
207 #define GML_OBJ_() (&(GraphLockable) { })
208 
209 /*
210  * This is not marked as TSA_ACQUIRE_SHARED() because TSA doesn't understand the
211  * cleanup attribute and would therefore complain that the graph is never
212  * unlocked. TSA_ASSERT_SHARED() makes sure that the following calls know that
213  * we hold the lock while unlocking is left unchecked.
214  */
215 static inline GraphLockable * TSA_ASSERT_SHARED(graph_lock) TSA_NO_TSA coroutine_fn
216 graph_lockable_auto_lock(GraphLockable *x)
217 {
218     bdrv_graph_co_rdlock();
219     return x;
220 }
221 
222 static inline void TSA_NO_TSA coroutine_fn
223 graph_lockable_auto_unlock(GraphLockable *x)
224 {
225     bdrv_graph_co_rdunlock();
226 }
227 
228 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GraphLockable, graph_lockable_auto_unlock)
229 
230 #define WITH_GRAPH_RDLOCK_GUARD_(var)                                         \
231     for (g_autoptr(GraphLockable) var = graph_lockable_auto_lock(GML_OBJ_()); \
232          var;                                                                 \
233          graph_lockable_auto_unlock(var), var = NULL)
234 
235 #define WITH_GRAPH_RDLOCK_GUARD() \
236     WITH_GRAPH_RDLOCK_GUARD_(glue(graph_lockable_auto, __COUNTER__))
237 
238 #define GRAPH_RDLOCK_GUARD(x)                                       \
239     g_autoptr(GraphLockable)                                        \
240     glue(graph_lockable_auto, __COUNTER__) G_GNUC_UNUSED =          \
241             graph_lockable_auto_lock(GML_OBJ_())
242 
243 
244 typedef struct GraphLockableMainloop { } GraphLockableMainloop;
245 
246 /*
247  * In C, compound literals have the lifetime of an automatic variable.
248  * In C++ it would be different, but then C++ wouldn't need QemuLockable
249  * either...
250  */
251 #define GMLML_OBJ_() (&(GraphLockableMainloop) { })
252 
253 /*
254  * This is not marked as TSA_ACQUIRE_SHARED() because TSA doesn't understand the
255  * cleanup attribute and would therefore complain that the graph is never
256  * unlocked. TSA_ASSERT_SHARED() makes sure that the following calls know that
257  * we hold the lock while unlocking is left unchecked.
258  */
259 static inline GraphLockableMainloop * TSA_ASSERT_SHARED(graph_lock) TSA_NO_TSA
260 graph_lockable_auto_lock_mainloop(GraphLockableMainloop *x)
261 {
262     bdrv_graph_rdlock_main_loop();
263     return x;
264 }
265 
266 static inline void TSA_NO_TSA
267 graph_lockable_auto_unlock_mainloop(GraphLockableMainloop *x)
268 {
269     bdrv_graph_rdunlock_main_loop();
270 }
271 
272 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GraphLockableMainloop,
273                               graph_lockable_auto_unlock_mainloop)
274 
275 #define GRAPH_RDLOCK_GUARD_MAINLOOP(x)                              \
276     g_autoptr(GraphLockableMainloop)                                \
277     glue(graph_lockable_auto, __COUNTER__) G_GNUC_UNUSED =          \
278             graph_lockable_auto_lock_mainloop(GMLML_OBJ_())
279 
280 #endif /* GRAPH_LOCK_H */
281 
282