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 <peter.bigot@nordicsemi.no>

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.