diff options
author | Andrzej Pietrasiewicz <andrzej.p@collabora.com> | 2020-12-02 14:44:26 -0800 |
---|---|---|
committer | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2020-12-02 22:10:37 -0800 |
commit | 6d59224fdcc532dd7292e3657d796b3728ec1e8e (patch) | |
tree | ddd7db6ae5743b9cce1ffc42bf82377faf18b1a0 | |
parent | a181616487dbdbc953e476d1da15365f887859ed (diff) | |
download | linux-6d59224fdcc532dd7292e3657d796b3728ec1e8e.tar.bz2 |
Input: document inhibiting
Document inhibiting input devices and its relation to being
a wakeup source.
Signed-off-by: Andrzej Pietrasiewicz <andrzej.p@collabora.com>
Reviewed-by: Hans de Goede <hdegoede@redhat.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20200617101822.8558-1-andrzej.p@collabora.com
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
-rw-r--r-- | Documentation/input/input-programming.rst | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst index 45a4c6e05e39..5938145b0e35 100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@ -164,6 +164,52 @@ disconnects. Calls to both callbacks are serialized. The open() callback should return a 0 in case of success or any nonzero value in case of failure. The close() callback (which is void) must always succeed. +Inhibiting input devices +~~~~~~~~~~~~~~~~~~~~~~~~ + +Inhibiting a device means ignoring input events from it. As such it is about +maintaining relationships with input handlers - either already existing +relationships, or relationships to be established while the device is in +inhibited state. + +If a device is inhibited, no input handler will receive events from it. + +The fact that nobody wants events from the device is exploited further, by +calling device's close() (if there are users) and open() (if there are users) on +inhibit and uninhibit operations, respectively. Indeed, the meaning of close() +is to stop providing events to the input core and that of open() is to start +providing events to the input core. + +Calling the device's close() method on inhibit (if there are users) allows the +driver to save power. Either by directly powering down the device or by +releasing the runtime-pm reference it got in open() when the driver is using +runtime-pm. + +Inhibiting and uninhibiting are orthogonal to opening and closing the device by +input handlers. Userspace might want to inhibit a device in anticipation before +any handler is positively matched against it. + +Inhibiting and uninhibiting are orthogonal to device's being a wakeup source, +too. Being a wakeup source plays a role when the system is sleeping, not when +the system is operating. How drivers should program their interaction between +inhibiting, sleeping and being a wakeup source is driver-specific. + +Taking the analogy with the network devices - bringing a network interface down +doesn't mean that it should be impossible be wake the system up on LAN through +this interface. So, there may be input drivers which should be considered wakeup +sources even when inhibited. Actually, in many I2C input devices their interrupt +is declared a wakeup interrupt and its handling happens in driver's core, which +is not aware of input-specific inhibit (nor should it be). Composite devices +containing several interfaces can be inhibited on a per-interface basis and e.g. +inhibiting one interface shouldn't affect the device's capability of being a +wakeup source. + +If a device is to be considered a wakeup source while inhibited, special care +must be taken when programming its suspend(), as it might need to call device's +open(). Depending on what close() means for the device in question, not +opening() it before going to sleep might make it impossible to provide any +wakeup events. The device is going to sleep anyway. + Basic event types ~~~~~~~~~~~~~~~~~ |