Document inhibiting input devices and its relation to being a wakeup source. Signed-off-by: Andrzej Pietrasiewicz <andrzej.p@xxxxxxxxxxxxx> --- @Hans, @Dmitry, My fist attempt at documenting inhibiting. Kindly look at it to see if I haven't got anything wrong. Andrzej Documentation/input/input-programming.rst | 36 +++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst index 45a4c6e05e39..0cd1ad4504fb 100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@ -164,6 +164,42 @@ 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 an 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. + +Inhibiting and uninhibiting is 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 is 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 to 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 ~~~~~~~~~~~~~~~~~ -- 2.17.1
