| 1 | //===- ThreadSafety.h -------------------------------------------*- C++ -*-===// |
|---|---|
| 2 | // |
| 3 | // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
| 4 | // See https://llvm.org/LICENSE.txt for license information. |
| 5 | // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
| 6 | // |
| 7 | //===----------------------------------------------------------------------===// |
| 8 | // |
| 9 | // |
| 10 | // A intra-procedural analysis for thread safety (e.g. deadlocks and race |
| 11 | // conditions), based off of an annotation system. |
| 12 | // |
| 13 | // See http://clang.llvm.org/docs/LanguageExtensions.html#thread-safety-annotation-checking |
| 14 | // for more information. |
| 15 | // |
| 16 | //===----------------------------------------------------------------------===// |
| 17 | |
| 18 | #ifndef LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H |
| 19 | #define LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H |
| 20 | |
| 21 | #include "clang/Basic/SourceLocation.h" |
| 22 | #include "llvm/ADT/StringRef.h" |
| 23 | |
| 24 | namespace clang { |
| 25 | |
| 26 | class AnalysisDeclContext; |
| 27 | class FunctionDecl; |
| 28 | class NamedDecl; |
| 29 | |
| 30 | namespace threadSafety { |
| 31 | |
| 32 | class BeforeSet; |
| 33 | |
| 34 | /// This enum distinguishes between different kinds of operations that may |
| 35 | /// need to be protected by locks. We use this enum in error handling. |
| 36 | enum ProtectedOperationKind { |
| 37 | /// Dereferencing a variable (e.g. p in *p = 5;) |
| 38 | POK_VarDereference, |
| 39 | |
| 40 | /// Reading or writing a variable (e.g. x in x = 5;) |
| 41 | POK_VarAccess, |
| 42 | |
| 43 | /// Making a function call (e.g. fool()) |
| 44 | POK_FunctionCall, |
| 45 | |
| 46 | /// Passing a guarded variable by reference. |
| 47 | POK_PassByRef, |
| 48 | |
| 49 | /// Passing a pt-guarded variable by reference. |
| 50 | POK_PtPassByRef |
| 51 | }; |
| 52 | |
| 53 | /// This enum distinguishes between different kinds of lock actions. For |
| 54 | /// example, it is an error to write a variable protected by shared version of a |
| 55 | /// mutex. |
| 56 | enum LockKind { |
| 57 | /// Shared/reader lock of a mutex. |
| 58 | , |
| 59 | |
| 60 | /// Exclusive/writer lock of a mutex. |
| 61 | LK_Exclusive, |
| 62 | |
| 63 | /// Can be either Shared or Exclusive. |
| 64 | LK_Generic |
| 65 | }; |
| 66 | |
| 67 | /// This enum distinguishes between different ways to access (read or write) a |
| 68 | /// variable. |
| 69 | enum AccessKind { |
| 70 | /// Reading a variable. |
| 71 | AK_Read, |
| 72 | |
| 73 | /// Writing a variable. |
| 74 | AK_Written |
| 75 | }; |
| 76 | |
| 77 | /// This enum distinguishes between different situations where we warn due to |
| 78 | /// inconsistent locking. |
| 79 | /// \enum SK_LockedSomeLoopIterations -- a mutex is locked for some but not all |
| 80 | /// loop iterations. |
| 81 | /// \enum SK_LockedSomePredecessors -- a mutex is locked in some but not all |
| 82 | /// predecessors of a CFGBlock. |
| 83 | /// \enum SK_LockedAtEndOfFunction -- a mutex is still locked at the end of a |
| 84 | /// function. |
| 85 | enum LockErrorKind { |
| 86 | LEK_LockedSomeLoopIterations, |
| 87 | LEK_LockedSomePredecessors, |
| 88 | LEK_LockedAtEndOfFunction, |
| 89 | LEK_NotLockedAtEndOfFunction |
| 90 | }; |
| 91 | |
| 92 | /// Handler class for thread safety warnings. |
| 93 | class ThreadSafetyHandler { |
| 94 | public: |
| 95 | using Name = StringRef; |
| 96 | |
| 97 | ThreadSafetyHandler() = default; |
| 98 | virtual ~ThreadSafetyHandler(); |
| 99 | |
| 100 | /// Warn about lock expressions which fail to resolve to lockable objects. |
| 101 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 102 | /// \param Loc -- the SourceLocation of the unresolved expression. |
| 103 | virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc) {} |
| 104 | |
| 105 | /// Warn about unlock function calls that do not have a prior matching lock |
| 106 | /// expression. |
| 107 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 108 | /// \param LockName -- A StringRef name for the lock expression, to be printed |
| 109 | /// in the error message. |
| 110 | /// \param Loc -- The SourceLocation of the Unlock |
| 111 | virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName, |
| 112 | SourceLocation Loc) {} |
| 113 | |
| 114 | /// Warn about an unlock function call that attempts to unlock a lock with |
| 115 | /// the incorrect lock kind. For instance, a shared lock being unlocked |
| 116 | /// exclusively, or vice versa. |
| 117 | /// \param LockName -- A StringRef name for the lock expression, to be printed |
| 118 | /// in the error message. |
| 119 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 120 | /// \param Expected -- the kind of lock expected. |
| 121 | /// \param Received -- the kind of lock received. |
| 122 | /// \param LocLocked -- The SourceLocation of the Lock. |
| 123 | /// \param LocUnlock -- The SourceLocation of the Unlock. |
| 124 | virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName, |
| 125 | LockKind Expected, LockKind Received, |
| 126 | SourceLocation LocLocked, |
| 127 | SourceLocation LocUnlock) {} |
| 128 | |
| 129 | /// Warn about lock function calls for locks which are already held. |
| 130 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 131 | /// \param LockName -- A StringRef name for the lock expression, to be printed |
| 132 | /// in the error message. |
| 133 | /// \param LocLocked -- The location of the first lock expression. |
| 134 | /// \param LocDoubleLock -- The location of the second lock expression. |
| 135 | virtual void handleDoubleLock(StringRef Kind, Name LockName, |
| 136 | SourceLocation LocLocked, |
| 137 | SourceLocation LocDoubleLock) {} |
| 138 | |
| 139 | /// Warn about situations where a mutex is sometimes held and sometimes not. |
| 140 | /// The three situations are: |
| 141 | /// 1. a mutex is locked on an "if" branch but not the "else" branch, |
| 142 | /// 2, or a mutex is only held at the start of some loop iterations, |
| 143 | /// 3. or when a mutex is locked but not unlocked inside a function. |
| 144 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 145 | /// \param LockName -- A StringRef name for the lock expression, to be printed |
| 146 | /// in the error message. |
| 147 | /// \param LocLocked -- The location of the lock expression where the mutex is |
| 148 | /// locked |
| 149 | /// \param LocEndOfScope -- The location of the end of the scope where the |
| 150 | /// mutex is no longer held |
| 151 | /// \param LEK -- which of the three above cases we should warn for |
| 152 | virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName, |
| 153 | SourceLocation LocLocked, |
| 154 | SourceLocation LocEndOfScope, |
| 155 | LockErrorKind LEK) {} |
| 156 | |
| 157 | /// Warn when a mutex is held exclusively and shared at the same point. For |
| 158 | /// example, if a mutex is locked exclusively during an if branch and shared |
| 159 | /// during the else branch. |
| 160 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 161 | /// \param LockName -- A StringRef name for the lock expression, to be printed |
| 162 | /// in the error message. |
| 163 | /// \param Loc1 -- The location of the first lock expression. |
| 164 | /// \param Loc2 -- The location of the second lock expression. |
| 165 | virtual void (StringRef Kind, Name LockName, |
| 166 | SourceLocation Loc1, |
| 167 | SourceLocation Loc2) {} |
| 168 | |
| 169 | /// Warn when a protected operation occurs while no locks are held. |
| 170 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 171 | /// \param D -- The decl for the protected variable or function |
| 172 | /// \param POK -- The kind of protected operation (e.g. variable access) |
| 173 | /// \param AK -- The kind of access (i.e. read or write) that occurred |
| 174 | /// \param Loc -- The location of the protected operation. |
| 175 | virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D, |
| 176 | ProtectedOperationKind POK, AccessKind AK, |
| 177 | SourceLocation Loc) {} |
| 178 | |
| 179 | /// Warn when a protected operation occurs while the specific mutex protecting |
| 180 | /// the operation is not locked. |
| 181 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 182 | /// \param D -- The decl for the protected variable or function |
| 183 | /// \param POK -- The kind of protected operation (e.g. variable access) |
| 184 | /// \param LockName -- A StringRef name for the lock expression, to be printed |
| 185 | /// in the error message. |
| 186 | /// \param LK -- The kind of access (i.e. read or write) that occurred |
| 187 | /// \param Loc -- The location of the protected operation. |
| 188 | virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D, |
| 189 | ProtectedOperationKind POK, Name LockName, |
| 190 | LockKind LK, SourceLocation Loc, |
| 191 | Name *PossibleMatch = nullptr) {} |
| 192 | |
| 193 | /// Warn when acquiring a lock that the negative capability is not held. |
| 194 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 195 | /// \param LockName -- The name for the lock expression, to be printed in the |
| 196 | /// diagnostic. |
| 197 | /// \param Neg -- The name of the negative capability to be printed in the |
| 198 | /// diagnostic. |
| 199 | /// \param Loc -- The location of the protected operation. |
| 200 | virtual void handleNegativeNotHeld(StringRef Kind, Name LockName, Name Neg, |
| 201 | SourceLocation Loc) {} |
| 202 | |
| 203 | /// Warn when a function is called while an excluded mutex is locked. For |
| 204 | /// example, the mutex may be locked inside the function. |
| 205 | /// \param Kind -- the capability's name parameter (role, mutex, etc). |
| 206 | /// \param FunName -- The name of the function |
| 207 | /// \param LockName -- A StringRef name for the lock expression, to be printed |
| 208 | /// in the error message. |
| 209 | /// \param Loc -- The location of the function call. |
| 210 | virtual void handleFunExcludesLock(StringRef Kind, Name FunName, |
| 211 | Name LockName, SourceLocation Loc) {} |
| 212 | |
| 213 | /// Warn that L1 cannot be acquired before L2. |
| 214 | virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name, |
| 215 | Name L2Name, SourceLocation Loc) {} |
| 216 | |
| 217 | /// Warn that there is a cycle in acquired_before/after dependencies. |
| 218 | virtual void handleBeforeAfterCycle(Name L1Name, SourceLocation Loc) {} |
| 219 | |
| 220 | /// Called by the analysis when starting analysis of a function. |
| 221 | /// Used to issue suggestions for changes to annotations. |
| 222 | virtual void enterFunction(const FunctionDecl *FD) {} |
| 223 | |
| 224 | /// Called by the analysis when finishing analysis of a function. |
| 225 | virtual void leaveFunction(const FunctionDecl *FD) {} |
| 226 | |
| 227 | bool issueBetaWarnings() { return IssueBetaWarnings; } |
| 228 | void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; } |
| 229 | |
| 230 | private: |
| 231 | bool IssueBetaWarnings = false; |
| 232 | }; |
| 233 | |
| 234 | /// Check a function's CFG for thread-safety violations. |
| 235 | /// |
| 236 | /// We traverse the blocks in the CFG, compute the set of mutexes that are held |
| 237 | /// at the end of each block, and issue warnings for thread safety violations. |
| 238 | /// Each block in the CFG is traversed exactly once. |
| 239 | void runThreadSafetyAnalysis(AnalysisDeclContext &AC, |
| 240 | ThreadSafetyHandler &Handler, |
| 241 | BeforeSet **Bset); |
| 242 | |
| 243 | void threadSafetyCleanup(BeforeSet *Cache); |
| 244 | |
| 245 | /// Helper function that returns a LockKind required for the given level |
| 246 | /// of access. |
| 247 | LockKind getLockKindFromAccessKind(AccessKind AK); |
| 248 | |
| 249 | } // namespace threadSafety |
| 250 | } // namespace clang |
| 251 | |
| 252 | #endif // LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H |
| 253 |