list: introduce LIST_HEAD_GUARDED

Introduce LIST_HEAD_GUARDED(name, lock) to define a struct list_head
annotated with __guarded_by(lock). This provides a convenient shorthand
for defining lock-protected list heads and allows compiler context
analysis to validate accesses to the list against the associated lock.

The new helper also reduces boilerplate and improves consistency across
callers that annotate struct list_head objects with __guarded_by().

This is a preparatory change for subsequent patches that annotate
LIST_HEAD() instances with their protecting lock.

Suggested-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Nilay Shroff <nilay@linux.ibm.com>
Signed-off-by: Keith Busch <kbusch@kernel.org>

1 files changed, 8 insertions, 0 deletions

diff --git a/include/linux/list.h b/include/linux/list.h
index 09d979976b3b..f6f22c8b06f7 100644
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -34,6 +34,14 @@
 	struct list_head name = LIST_HEAD_INIT(name)
 
 /**
+ * LIST_HEAD_GUARDED - define a &struct list_head annotated with __guarded_by()
+ * @name: name of the list_head
+ * @lock: lock protecting the list
+ */
+#define LIST_HEAD_GUARDED(name, lock) \
+	__guarded_by(&(lock)) LIST_HEAD(name)
+
+/**
  * INIT_LIST_HEAD - Initialize a list_head structure
  * @list: list_head structure to be initialized.
  *