From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.7 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS, UNPARSEABLE_RELAY,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6BB2AC433E2 for ; Wed, 17 Jun 2020 10:18:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 55432214DB for ; Wed, 17 Jun 2020 10:18:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726434AbgFQKSf (ORCPT ); Wed, 17 Jun 2020 06:18:35 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48368 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725554AbgFQKSf (ORCPT ); Wed, 17 Jun 2020 06:18:35 -0400 Received: from bhuna.collabora.co.uk (bhuna.collabora.co.uk [IPv6:2a00:1098:0:82:1000:25:2eeb:e3e3]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C874FC061573; Wed, 17 Jun 2020 03:18:34 -0700 (PDT) Received: from [127.0.0.1] (localhost [127.0.0.1]) (Authenticated sender: andrzej.p) with ESMTPSA id 95B322A395D From: Andrzej Pietrasiewicz To: linux-pm@vger.kernel.org, linux-acpi@vger.kernel.org, linux-kernel@vger.kernel.org, linux-iio@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-samsung-soc@vger.kernel.org, linux-input@vger.kernel.org, linux-tegra@vger.kernel.org, patches@opensource.cirrus.com, ibm-acpi-devel@lists.sourceforge.net, platform-driver-x86@vger.kernel.org Cc: "Rafael J . Wysocki" , Len Brown , Jonathan Cameron , Hartmut Knaack , Lars-Peter Clausen , Peter Meerwald-Stadler , Kukjin Kim , Krzysztof Kozlowski , Dmitry Torokhov , Shawn Guo , Sascha Hauer , Pengutronix Kernel Team , Fabio Estevam , NXP Linux Team , Vladimir Zapolskiy , Sylvain Lemieux , Laxman Dewangan , Thierry Reding , Jonathan Hunter , Barry Song , Michael Hennerich , Nick Dyer , Hans de Goede , Sangwon Jee , Peter Hutterer , Henrique de Moraes Holschuh , Andrzej Pietrasiewicz , =?UTF-8?q?Micha=C5=82=20Miros=C5=82aw?= , kernel@collabora.com Subject: [PATCH v2] Input: document inhibiting Date: Wed, 17 Jun 2020 12:18:22 +0200 Message-Id: <20200617101822.8558-1-andrzej.p@collabora.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: References: Sender: linux-input-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org Document inhibiting input devices and its relation to being a wakeup source. Signed-off-by: Andrzej Pietrasiewicz --- v1..v2: - Addressed editorial comments from Randy - Added a paragraph by Hans Documentation/input/input-programming.rst | 40 +++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst index 45a4c6e05e39..7432315cc829 100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@ -164,6 +164,46 @@ 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 ~~~~~~~~~~~~~~~~~ -- 2.17.1