Components need access to the Power Manager to control the system's wake-up state. Operations that need fast response times (e.g., maintaining call state or playing/recording a media stream) result in high interrupt rates; keeping the system awake results in better performance and power efficiency.

Power Manager uses kernel wakeup sources to keep the system awake when at least one of the registered components requests a wakeup source to be held. When all wakeup sources are released, the system may enter a suspend state depending on the status of other (unrelated) wakeup sources.

IPC interfaces binding

All the functions of this API are provided by the powerMgr service.

Here's a code sample binding to Power Manager services:

bindings:
{
   clientExe.clientComponent.le_pm -> powerMgr.le_pm
}

Requesting and releasing a wakeup source

The Power Manager service provides basic API for requesting and releasing a wakeup source. Power Manager's clients call le_pm_NewWakeupSource() to create a wakeup source. This function returns a le_pm_WakeupSourceRef_t type that can later be used to acquire and release a wakeup source through le_pm_StayAwake() and le_pm_Relax(), respectively. Wakeup sources are not reference-counted, which means multiple calls to le_pm_StayAwake() can be canceled by a single call to le_pm_Relax().

To have a reference-counted wakeup-source, set the LE_PM_REF_COUNT bit in the opts argument. When this bit is set, each le_pm_StayAwake() increments a counter, and multiple calls to le_pm_Relax() is necessary to release the wakeup source.

Power Manager service will automatically release and delete all wakeup sources held on behalf of an exiting or disconnecting client.

The service le_pm_ForceRelaxAndDestroyAllWakeupSource() will return LE_NOT_PERMITTED until a call to le_pm_StayAwake() fails with LE_NO_MEMORY. This should be considered as an ultime defense if no more wakeup sources may be acquired or relased. This service will kill all clients and release and destroy all wakeup source currently managed.

At startup, the Power Manager will release all wakeup sources matching the pattern for Legato apps and will keep the others untouched.

For deterministic behaviour, clients requesting services of Power Manager should have CAP_EPOLLWAKEUP (or CAP_BLOCK_SUSPEND) capability assigned.

The maximum number of wakeup sources managed at same time is fixed by the kernel configuration option CONFIG_PM_WAKELOCKS_LIMIT.