A locked wakelock, depending on its type, prevents the system from entering suspend or other low-power states. This document describes how to employ wakelocks.
There are two settings for a wakelock:
WAKE_LOCK_SUSPEND: prevents a full system suspend. WAKE_LOCK_IDLE: low-power states, which often cause large interrupt latencies or that disable a set of interrupts, will not be entered from idle until the wakelocks are released. Unless the type is specified, this document refers to wakelocks of type WAKE_LOCK_SUSPEND.
If the suspend operation has already started when locking a wakelock, the system will abort the suspend operation as long it has not already reached the suspend_late stage. This means that locking a wakelock from an interrupt handler or a freezeable thread always works, but if you lock a wakelock from a suspend_late handler, you must also return an error from that handler to abort suspend. You can use wakelocks to allow the user-space to decide which keys should wake the full system and turn on the screen. Use set_irq_wake or a platform-specific API to ensure that the keypad interrupt wakes up the CPU. Once the keypad driver has resumed, the sequence of events can look like this:
The simple sequence diagram below illustrates these steps:
Key pressed Key released
| |
keypad-scan ++++++++++++++++++++++
input-event-queue +++ +++
process-input-events +++ +++
A driver can use the wakelock API by adding a wakelock variable to its state and calling wake_lock_init, as illustrated in the snippet below:
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 or not the wakelock is already held. It is useful if the driver woke up other parts of the system that do 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.
Write lockname or lockname timeout to /sys/power/wake_lock lock and, if needed, create a wakelock. The timeout here is specified in nanoseconds. Write lockname to /sys/power/wake_unlock to unlock a user wakelock.
Do not use randomly generated wakelock names as there is no API to free a user-space wakelock.