Re: [RFC][PATCH 00/11] Android PM extensions

Arve Hjønnevåg
2009-01-15T04:42:54Z

On Wed, Jan 14, 2009 at 1:01 AM, Nigel Cunningham
<ncunningham@crca.org.au> wrote:
> Would you be able to provide some more documentation?

Would something like this help:
Documentation/power/wakelocks.txt

Wakelocks
=========

A wake_lock prevents the system from entering suspend or other low power
states when active. If the type is set to WAKE_LOCK_SUSPEND, the wake_lock
prevents a full system suspend. If the type is WAKE_LOCK_IDLE, low power
states that cause large interrupt latencies or that disable a set of
interrupts will not entered from idle until the wake_locks are released.

Driver API
==========

A driver can use the wakelock api by adding a wakelock variable to its state
and calling wake_lock_init. For instance:
struct state {
struct wakelock wakelock;
}

init() {
wake_lock_init(&state->wakelock, WAKE_LOCK_SUSPEND, "wakelockname");
}

Before freeing the memory wake_lock_destroy must be called:

uninit() {
wake_lock_destroy(&state->wakelock);
}

When the driver determines that it needs to run (usually in an interrupt
handler) it calls wake_lock:
wake_lock(&state->wakelock);

When it no longer needs to run it calls wake_unlock:
wake_unlock(&state->wakelock);

It can also call wake_lock_timeout to release the wakelock after a delay:
wake_lock_timeout(&state->wakelock, HZ);

This works whether the wake_lock is already held or not. It is useful if the
driver woke up other parts of the system that does not use wakelocks but
still need to run. Avoid this when possible, since it will waste power
if the timeout is long or may fail to finish needed work if the timeout is
short.

User-space API
==============

Write "lockname" or "lockname timeout" to /sys/power/wake_lock lock and if
needed create a wake lock. The timeout here is specified nanoseconds.
Write "lockname" to /sys/power/wake_unlock to unlock a user wake lock.

Do not use randomly generated wakelock names as there is no api to free
a userspace wakelock.

--
Arve Hjønnevåg