From 258877a9217ca8a9df065914e0a9bbba4e6ea21d Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Tue, 26 Jan 2021 09:55:18 -0600 Subject: [PATCH] irq: document requirement that irq_lock/unlock provides a memory barrier Correct functioning of spinlocks requires that they be memory barriers. With CONFIG_SMP=y this falls out as a consequence of using sequentially consistent atomic operations to ensure all processors are locked out. With CONFIG_SMP=n a spinlock uses arch_irq_lock/unlock(), so the barrier behavior must come from that function. As arch_irq_lock/unlock() delegates to irq_lock/unlock() for documentation, document the barrier requirement there. Signed-off-by: Peter Bigot --- include/irq.h | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/include/irq.h b/include/irq.h index b5616d58529..50088742b43 100644 --- a/include/irq.h +++ b/include/irq.h @@ -187,6 +187,10 @@ irq_connect_dynamic(unsigned int irq, unsigned int priority, * whether interrupts were locked prior to the call. The lock-out key must be * passed to irq_unlock() to re-enable interrupts. * + * @note + * This routine must also serve as a memory barrier to ensure the uniprocessor + * implementation of `k_spinlock_t` is correct. + * * This routine can be called recursively, as long as the caller keeps track * of each lock-out key that is generated. Interrupts are re-enabled by * passing each of the keys to irq_unlock() in the reverse order they were @@ -231,6 +235,10 @@ unsigned int z_smp_global_lock(void); * each time it called irq_lock(), supplying the keys in the reverse order * they were acquired, before interrupts are enabled. * + * @note + * This routine must also serve as a memory barrier to ensure the uniprocessor + * implementation of `k_spinlock_t` is correct. + * * This routine can only be invoked from supervisor mode. Some architectures * (for example, ARM) will fail silently if invoked from user mode instead * of generating an exception.