Architecture-specific power management APIs

Functions
FUNC_NORETURN void	arch_system_halt (unsigned int reason)
	Halt the system, optionally propagating a reason code.
void	arch_cpu_idle (void)
	Power save idle routine.
void	arch_cpu_atomic_idle (unsigned int key)
	Atomically re-enable interrupts and enter low power mode.
unsigned int	arch_pm_state_set_prepare (void)
	Prepare interrupt state before entering a system PM state.
void	arch_pm_state_set_finish (unsigned int key)
	Restore interrupt state after leaving a system PM state.

Detailed Description

Function Documentation

arch_cpu_atomic_idle()

void arch_cpu_atomic_idle

(

unsigned int

key

)

#include <zephyr/arch/arch_interface.h>

Atomically re-enable interrupts and enter low power mode.

The requirements for arch_cpu_atomic_idle() are as follows:

1. Enabling interrupts and entering a low-power mode needs to be atomic, i.e. there should be no period of time where interrupts are enabled before the processor enters a low-power mode. See the comments in k_lifo_get(), for example, of the race condition that occurs if this requirement is not met.
2. After waking up from the low-power mode, the interrupt lockout state must be restored as indicated in the 'key' input parameter.

See also

k_cpu_atomic_idle()

Parameters

key	Lockout key returned by previous invocation of arch_irq_lock()

arch_cpu_idle()

void arch_cpu_idle

(

void

)

#include <zephyr/arch/arch_interface.h>

Power save idle routine.

This function will be called by the kernel idle loop or possibly within an implementation of z_pm_save_idle in the kernel when the '_pm_save_flag' variable is non-zero.

Architectures that do not implement power management instructions may 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 also

k_cpu_idle()

arch_pm_state_set_finish()

void arch_pm_state_set_finish

(

unsigned int

key

)

#include <zephyr/arch/arch_interface.h>

Restore interrupt state after leaving a system PM state.

This hook restores the interrupt state prepared by arch_pm_state_set_prepare() back to the locked state expected by the PM core. The original idle-thread interrupt key is still owned by the idle path and restored after PM resume bookkeeping is complete.

Parameters

key	Architecture-specific key returned by arch_pm_state_set_prepare().

arch_pm_state_set_prepare()

unsigned int arch_pm_state_set_prepare

(

void

)

#include <zephyr/arch/arch_interface.h>

Prepare interrupt state before entering a system PM state.

This hook is called with interrupts locked by SoC PM implementations that keep IRQ dispatch blocked across system PM resume. It should be called immediately before the low-power instruction. Architectures may use it to allow a pending wake event to bring the CPU out of the low-power instruction without allowing regular interrupt handlers to run before PM resume bookkeeping.

Despite the name, this is not a pm_state_set() boundary hook. SoC code should call it immediately around the low-power instruction, typically WFI, to minimize the window of restrictive interrupt masking.

Returns

Architecture-specific key to pass to arch_pm_state_set_finish().

arch_system_halt()

FUNC_NORETURN void arch_system_halt

(

unsigned int

reason

)

#include <kernel_arch_interface.h>

Halt the system, optionally propagating a reason code.