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 09F68C433E0 for ; Tue, 16 Jun 2020 17:39:06 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id DFDA7214DB for ; Tue, 16 Jun 2020 17:39:05 +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="B3neG+m2" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730040AbgFPRjF (ORCPT ); Tue, 16 Jun 2020 13:39:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:35646 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727819AbgFPRjF (ORCPT ); Tue, 16 Jun 2020 13:39:05 -0400 Received: from bombadil.infradead.org (bombadil.infradead.org [IPv6:2607:7c80:54:e::133]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 21D3CC061573; Tue, 16 Jun 2020 10:39:05 -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=qjEmQC/q9jkbq0weF5raFJ+MekaRoErGgDZ2oBWSGlY=; b=B3neG+m2+S68Ce+3qE1cme/bDP 96XS9wANDMwKFaCFn39PMlkwWkaqsdYBucnzcMe/DgbmvgnLdNkjScpTdwHpQ2VQ9UEpyN1jBaig/ EcLqohthiqiT3/GEWW8VzXYijJTnimRSTWIOpimZowKjLG+HEaUGambpFxV0tKpGtTtc9QHjViyO/ tsMR7U10PzFUZVYgdD13m+8kDuuWQUvXlaXGfmMclzFuH2Lu9pOpOZP0go4opO2Wunly4vABMuTv5 BlR8w8Oot6blQQ/+HuMuLCC5yXOqbQegpqB0/kzIinBkn+zFrfaU762b8k+7pmJ5FHsE7asUCq31S 8nSvtAVw==; Received: from [2601:1c0:6280:3f0::19c2] by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1jlFXX-0005Ij-SD; Tue, 16 Jun 2020 17:38:27 +0000 Subject: Re: [PATCH] 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: <40988408-8f36-3a52-6439-34084de6b129@redhat.com> <20200616172909.21625-1-andrzej.p@collabora.com> From: Randy Dunlap Message-ID: Date: Tue, 16 Jun 2020 10:38:25 -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: <20200616172909.21625-1-andrzej.p@collabora.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Sender: linux-acpi-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-acpi@vger.kernel.org On 6/16/20 10:29 AM, Andrzej Pietrasiewicz wrote: > Document inhibiting input devices and its relation to being > a wakeup source. > > Signed-off-by: Andrzej Pietrasiewicz > --- Hi, I have some editorial comments. Please see below. > @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 are > +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 are > +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 I2C > +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 in question, not > +to provide any wakeup events. The device is going to sleep anyway. > + > Basic event types > ~~~~~~~~~~~~~~~~~ > > thanks for documentation. -- ~Randy