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=-8.0 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_1 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 2EA37C433E1 for ; Wed, 17 Jun 2020 16:53:08 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 0104221527 for ; Wed, 17 Jun 2020 16:53:08 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="EjXQIdOb" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727007AbgFQQxH (ORCPT ); Wed, 17 Jun 2020 12:53:07 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53444 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726329AbgFQQxF (ORCPT ); Wed, 17 Jun 2020 12:53:05 -0400 Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D49DDC06174E; Wed, 17 Jun 2020 09:53:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Content-Transfer-Encoding: Content-Type:In-Reply-To:MIME-Version:Date:Message-ID:From:References:Cc:To: Subject:Sender:Reply-To:Content-ID:Content-Description; bh=3aHDULVOAZalwQVfI9n5bUMyn1CLTGa3J/NFAT87OxI=; b=EjXQIdObgegi5j91EFEDjl6J4B 4PFr18Fmi9N2VNb1fcBGNkiLBXvVZ1htcGrseMu9kTS9bo9T44MNOJqZ007Xrbp4NGvwIhogVMROC 4xtL4tRjznzBTriAV5EjM3uTlwrvgQlihLewoVQE8JFYD41d85i4wnyyAiSwg0Ckhm1pLMAj99YQD QdSXFKeUT+35nzi0FYZdeC1mkdJzl2xxgC10iJIbNe3MwEtwTXMWmltCGmq0CuBk8ERWPzwHQblLB iJ6ysmGyfsUwrKbj3L5z7An9AM1KW4q34m1/jm2fcnd3SznIGzuPTxs7Gb+F0uIni5G6Tk/eu9I/E MpsG7yaQ==; Received: from [2601:1c0:6280:3f0::19c2] by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1jlbIe-0002Zw-LA; Wed, 17 Jun 2020 16:52:32 +0000 Subject: Re: [PATCH v2] Input: document inhibiting To: Andrzej Pietrasiewicz , 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 , =?UTF-8?B?TWljaGHFgiBNaXJvc8WCYXc=?= , kernel@collabora.com References: <20200617101822.8558-1-andrzej.p@collabora.com> From: Randy Dunlap Message-ID: <8ebf502e-855d-6a6b-9c7b-d96d5e519d82@infradead.org> Date: Wed, 17 Jun 2020 09:52:30 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.9.0 MIME-Version: 1.0 In-Reply-To: <20200617101822.8558-1-andrzej.p@collabora.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 6/17/20 3:18 AM, Andrzej Pietrasiewicz wrote: > 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 > ~~~~~~~~~~~~~~~~~ > > Reviewed-by: Randy Dunlap Thanks. -- ~Randy