svn commit: r270941 - head/sys/sys

[Ed Schouten]

Author: ed
Date: Mon Sep  1 18:27:04 2014
New Revision: 270941
URL: http://svnweb.freebsd.org/changeset/base/270941

Log:
  Add lock annotations to <sys/cdefs.h>.
  
  Clang has support for annotating mutexes and code that uses mutexes to
  validate certain aspects of thread safety:
  
  - Whether acquiring/releasing locks is done properly (e.g., whether you
    unlock a mutex before leaving a function).
  - Whether a lock is held while reading/writing data from/to memory.
  
  Analysis is performed at the function level. Functions can be annotated
  to indicate they:
  
  - (try to) pick up a lock,
  - release a lock,
  - can only be called when (not) holding a lock,
  - assert that a lock is held.
  
  Variables and structure members can be annotated to indicate that they
  are guarded by a certain lock. In C++, these annotations can refer
  to both global variables, but also other class/structure members. In C,
  it is only possible to refer to global variables.
  
  This change adds wrappers for the annotations used by Clang to
  <sys/cdefs.h>. They currently have no effect, but this is on purpose.
  This change will be merged back to FreeBSD 9 and 10, which means we can
  safely experiment with these annotations on HEAD without making it
  harder to port changes back.
  
  Reviewed by:	announced on arch@ and toolchain@
  MFC after:	3 weeks

Modified:
  head/sys/sys/cdefs.h

Modified: head/sys/sys/cdefs.h
==============================================================================
--- head/sys/sys/cdefs.h	Mon Sep  1 18:25:49 2014	(r270940)
+++ head/sys/sys/cdefs.h	Mon Sep  1 18:27:04 2014	(r270941)
@@ -739,4 +739,60 @@
 #define __NO_TLS 1
 #endif
 
+/*
+ * Lock annotations.
+ *
+ * Clang provides support for doing basic thread-safety tests at
+ * compile-time, by marking which locks will/should be held when
+ * entering/leaving a functions.
+ *
+ * Furthermore, it is also possible to annotate variables and structure
+ * members to enforce that they are only accessed when certain locks are
+ * held.
+ *
+ * Note: These annotations have no effect on this version of FreeBSD.
+ * They are merely provided for forward compatibilty.
+ */
+
+#define	__lock_annotate(x)
+
+/* Structure implements a lock. */
+#define	__lockable		__lock_annotate(lockable)
+
+/* Function acquires an exclusive or shared lock. */
+#define	__locks_exclusive(...) \
+	__lock_annotate(exclusive_lock_function(__VA_ARGS__))
+#define	__locks_shared(...) \
+	__lock_annotate(shared_lock_function(__VA_ARGS__))
+
+/* Function attempts to acquire an exclusive or shared lock. */
+#define	__trylocks_exclusive(...) \
+	__lock_annotate(exclusive_trylock_function(__VA_ARGS__))
+#define	__trylocks_shared(...) \
+	__lock_annotate(shared_trylock_function(__VA_ARGS__))
+
+/* Function releases a lock. */
+#define	__unlocks(...)		__lock_annotate(unlock_function(__VA_ARGS__))
+
+/* Function asserts that an exclusive or shared lock is held. */
+#define	__asserts_exclusive(...) \
+	__lock_annotate(assert_exclusive_lock(__VA_ARGS__))
+#define	__asserts_shared(...) \
+	__lock_annotate(assert_shared_lock(__VA_ARGS__))
+
+/* Function requires that an exclusive or shared lock is or is not held. */
+#define	__requires_exclusive(...) \
+	__lock_annotate(exclusive_locks_required(__VA_ARGS__))
+#define	__requires_shared(...) \
+	__lock_annotate(shared_locks_required(__VA_ARGS__))
+#define	__requires_unlocked(...) \
+	__lock_annotate(locks_excluded(__VA_ARGS__))
+
+/* Function should not be analyzed. */
+#define	__no_lock_analysis	__lock_annotate(no_thread_safety_analysis)
+
+/* Guard variables and structure members by lock. */
+#define	__guarded_by(x)		__lock_annotate(guarded_by(x))
+#define	__pt_guarded_by(x)	__lock_annotate(pt_guarded_by(x))
+
 #endif /* !_SYS_CDEFS_H_ */