kernel: cpu idle: add info about IRQ unlocking in k_cpu_idle

We add a note in k_cpu_idle() documentation, stressing that for
certain architectures. the function unmasks interrupts
unconditionally before returning. In the
documentation of the architecture-specific API (arch_cpu_idle)
we describe the expected behavior with regards to the wake-up
event.

Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>

include/kernel.h

@@ -4999,6 +4999,9 @@ extern void z_handle_obj_poll_events(sys_dlist_t *events, u32_t state);
  * However, in some more constrained systems, such as a single-threaded system,
  * the only thread would be responsible for this if needed.
  *
+ * @note In some architectures, before returning, the function unmasks interrupts
+ * unconditionally.
+ *
  * @return N/A
  * @req K-CPU-IDLE-001
  */

include/sys/arch_interface.h

@@ -127,6 +127,10 @@ static inline u32_t arch_k_cycle_get_32(void);
  * immediately return, otherwise a power-saving instruction should be
  * issued to wait for an interrupt.
  *
+ * @note The function is expected to return after the interrupt that has
+ * caused the CPU to exit power-saving mode has been serviced, although
+ * this is not a firm requirement.
+ *
  * @see k_cpu_idle()
  */
 void arch_cpu_idle(void);