From f3e7d10d076bf53516fcb9a2aa11b00a01ed3bb6 Mon Sep 17 00:00:00 2001
From: Martin Ling <martin-git@earth.li>
Date: Mon, 16 Dec 2024 21:19:12 +0000
Subject: [PATCH] Add comment about constraints on locking primitives.

---
 firmware/common/locking.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/firmware/common/locking.h b/firmware/common/locking.h
index 80fbf12f..392b689d 100644
--- a/firmware/common/locking.h
+++ b/firmware/common/locking.h
@@ -26,6 +26,12 @@
 
 #include <libopencm3/cm3/sync.h>
 
+/* Primitives for implementing locking.
+ *
+ * Must always be used in a pair, with a call to load_exclusive being
+ * followed immediately or near-immediately by a call to store_exclusive().
+ * Failure to observe this rule may lead to undefined results. */
+
 // Use ldrex and strex directly if available.
 // Otherwise, disable interrupts to ensure exclusivity.
 #if defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7EM__)