Enable thread safety analysis for system mutex (#23678)

* Enable thread safety analysis for system mutex

Thread Safety Analysis [1] is a clang extension tool which adds static
analysis for potential race conditions.

This commit adds support for such thread safety analysis to Matter
system mutex class.

Simple usage:

  int state CHIP_GUARDED_BY(stateMtx);
  chip::System::Mutex stateMtx;

	void setState(int value) {
		chip::System::MutexUniqueLock lock(stateMtx);
		state = value;
	}

[1] https://clang.llvm.org/docs/ThreadSafetyAnalysis.html

* Reuse thread safety config from pigweed

* No need to wrap std::lock_guard since clang c++ std library provides
such functionality out of the box. The only requirements is that the
_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS=1 is defined.

* Use thread safety with ConnectivityManagerImpl to prove that it works

build/config/compiler/BUILD.gn

@@ -259,6 +259,7 @@ config("strict_warnings") {
 
  cflags_cc = [ "-Wnon-virtual-dtor" ]
 
+ configs = []
  ldflags = []
 
  if (is_clang) {
@@ -269,6 +270,8 @@ config("strict_warnings") {
  "-Wformat-type-confusion",
  ]
 
+ configs += [ "$dir_pw_build:clang_thread_safety_warnings" ]
+
  # TODO: can make this back fatal in once pigweed updates can be taken again.
  # See https://github.com/project-chip/connectedhomeip/pull/22079
  #

src/platform/Linux/ConnectivityManagerImpl.h

@@ -45,6 +45,7 @@
 #include <platform/Linux/dbus/wpa/DBusWpaBss.h>
 #include <platform/Linux/dbus/wpa/DBusWpaInterface.h>
 #include <platform/Linux/dbus/wpa/DBusWpaNetwork.h>
+#include <system/SystemMutex.h>
 
 #include <mutex>
 #endif
@@ -207,7 +208,7 @@ class ConnectivityManagerImpl final : public ConnectivityManager,
 
  static bool mAssociationStarted;
  static BitFlags<ConnectivityFlags> mConnectivityFlag;
- static GDBusWpaSupplicant mWpaSupplicant;
+ static GDBusWpaSupplicant mWpaSupplicant CHIP_GUARDED_BY(mWpaSupplicantMutex);
  // Access to mWpaSupplicant has to be protected by a mutex because it is accessed from
  // the CHIP event loop thread and dedicated D-Bus thread started by platform manager.
  static std::mutex mWpaSupplicantMutex;

src/system/SystemMutex.h

@@ -63,6 +63,34 @@
 namespace chip {
 namespace System {
 
+// Enable thread safety attributes only with clang.
+#if defined(__clang__) && (!defined(SWIG))
+#define CHIP_TSA_ATTRIBUTE__(x) __attribute__((x))
+#else
+#define CHIP_TSA_ATTRIBUTE__(x)
+#endif
+
+#define CHIP_CAPABILITY(x) CHIP_TSA_ATTRIBUTE__(capability(x))
+#define CHIP_SCOPED_CAPABILITY CHIP_TSA_ATTRIBUTE__(scoped_lockable)
+#define CHIP_GUARDED_BY(x) CHIP_TSA_ATTRIBUTE__(guarded_by(x))
+#define CHIP_PT_GUARDED_BY(x) CHIP_TSA_ATTRIBUTE__(pt_guarded_by(x))
+#define CHIP_ACQUIRED_BEFORE(...) CHIP_TSA_ATTRIBUTE__(acquired_before(__VA_ARGS__))
+#define CHIP_ACQUIRED_AFTER(...) CHIP_TSA_ATTRIBUTE__(acquired_after(__VA_ARGS__))
+#define CHIP_REQUIRES(...) CHIP_TSA_ATTRIBUTE__(requires_capability(__VA_ARGS__))
+#define CHIP_REQUIRES_SHARED(...) CHIP_TSA_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))
+#define CHIP_ACQUIRE(...) CHIP_TSA_ATTRIBUTE__(acquire_capability(__VA_ARGS__))
+#define CHIP_ACQUIRE_SHARED(...) CHIP_TSA_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))
+#define CHIP_RELEASE(...) CHIP_TSA_ATTRIBUTE__(release_capability(__VA_ARGS__))
+#define CHIP_RELEASE_SHARED(...) CHIP_TSA_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
+#define CHIP_RELEASE_GENERIC(...) CHIP_TSA_ATTRIBUTE__(release_generic_capability(__VA_ARGS__))
+#define CHIP_TRY_ACQUIRE(...) CHIP_TSA_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))
+#define CHIP_TRY_ACQUIRE_SHARED(...) CHIP_TSA_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))
+#define CHIP_EXCLUDES(...) CHIP_TSA_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
+#define CHIP_ASSERT_CAPABILITY(x) CHIP_TSA_ATTRIBUTE__(assert_capability(x))
+#define CHIP_ASSERT_SHARED_CAPABILITY(x) CHIP_TSA_ATTRIBUTE__(assert_shared_capability(x))
+#define CHIP_RETURN_CAPABILITY(x) CHIP_TSA_ATTRIBUTE__(lock_returned(x))
+#define CHIP_NO_THREAD_SAFETY_ANALYSIS CHIP_TSA_ATTRIBUTE__(no_thread_safety_analysis)
+
 /**
  * @class Mutex
  *
@@ -73,8 +101,12 @@ namespace System {
  * objects with \c static storage duration and uninitialized memory. Use \c Init method to initialize. The copy/move
  * operators are not provided.
  *
+ * @note
+ * This class is compatible with \c std::lock_guard and provides
+ * annotations for thread safety analysis.
+ *
  */
-class DLL_EXPORT Mutex
+class DLL_EXPORT CHIP_CAPABILITY("mutex") Mutex
 {
 public:
  Mutex() = default;
@@ -84,12 +116,12 @@ class DLL_EXPORT Mutex
  inline bool isInitialized() { return mInitialized; }
 #endif // CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING
 
- void Lock(); /**< Acquire the mutual exclusion lock, blocking the current thread indefinitely if necessary. */
- void Unlock(); /**< Release the mutual exclusion lock (can block on some systems until scheduler completes). */
+ void Lock() CHIP_ACQUIRE(); /**< Acquire the mutual exclusion lock, blocking the current thread indefinitely if necessary. */
+ void Unlock() CHIP_RELEASE(); /**< Release the mutual exclusion lock (can block on some systems until scheduler completes). */
 
  // Synonyms for compatibility with std::lock_guard.
- void lock() { Lock(); }
- void unlock() { Unlock(); }
+ void lock() CHIP_ACQUIRE() { Lock(); }
+ void unlock() CHIP_RELEASE() { Unlock(); }
 
 private:
 #if CHIP_SYSTEM_CONFIG_POSIX_LOCKING