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_ACQUIRE_SHARED(graph_lock) 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_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 */ 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 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