From 88e756e05e27ce6e269ff8ad07d5186d76b886d9 Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Tue, 29 Sep 2020 10:43:10 -0500 Subject: [PATCH] kernel: document interrupt behavior of k_cpu_atomic_idle The generic kernel API did not specify the effect of the call on the interrupt lockout state. The implementation forwards to arch_cpu_atomic_idle() which does document that the state is restored to the state specified in the passed key, which makes it have the effect of invoking irq_unlock(key). Signed-off-by: Peter Bigot --- include/kernel.h | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/include/kernel.h b/include/kernel.h index ad281824a05..5c48ff30853 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -5220,8 +5220,14 @@ static inline void k_cpu_idle(void) /** * @brief Make the CPU idle in an atomic fashion. * - * Similar to k_cpu_idle(), but called with interrupts locked if operations - * must be done atomically before making the CPU idle. + * Similar to k_cpu_idle(), but must be called with interrupts locked. + * + * Enabling interrupts and entering a low-power mode will be atomic, + * i.e. there will be no period of time where interrupts are enabled before + * the processor enters a low-power mode. + * + * After waking up from the low-power mode, the interrupt lockout state will + * be restored as if by irq_unlock(key). * * @param key Interrupt locking key obtained from irq_lock(). *