From patchwork Tue Jan 31 14:43:50 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 92991 Delivered-To: patch@linaro.org Received: by 10.182.3.34 with SMTP id 2csp1867001obz; Tue, 31 Jan 2017 06:44:06 -0800 (PST) X-Received: by 10.84.209.204 with SMTP id y70mr40342643plh.180.1485873846287; Tue, 31 Jan 2017 06:44:06 -0800 (PST) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id v16si11387178pgo.368.2017.01.31.06.44.06; Tue, 31 Jan 2017 06:44:06 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org; spf=pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-gpio-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1750894AbdAaOoD (ORCPT + 4 others); Tue, 31 Jan 2017 09:44:03 -0500 Received: from mail-lf0-f41.google.com ([209.85.215.41]:34652 "EHLO mail-lf0-f41.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751156AbdAaOn5 (ORCPT ); Tue, 31 Jan 2017 09:43:57 -0500 Received: by mail-lf0-f41.google.com with SMTP id v186so212512506lfa.1 for ; Tue, 31 Jan 2017 06:43:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=lmmInkxHH2mzgXZmsvMTNlB2oPLtSiWDca+/AdkZbiE=; b=PrGdo0y9NYUMKmz64kfYATbSbsQ746pr748WSakq5bfsysLCti7M7FCQlQHXCtMeSI B/i6lUwrrq7BFMHAIzR8P3eSFYNMz4V0l3PbzJOgtC1WuHSebhB2M7MVAZzWwJorqp8o ZdMMtxgrOn6wDJe1Znwz32xKdyVYFI5xbAD4E= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=lmmInkxHH2mzgXZmsvMTNlB2oPLtSiWDca+/AdkZbiE=; b=eW+D4koOhF/bM0Qzhq5wXPwwVFKvbSP7h0ILCzkFfaa7h1L0YQEKulGkXDqPPdqP4/ XLNWnHLcuABIwUgRTP4amMr5Tovbte6Kaxcjk+ywTIoeUzQnsu5/k2RuXSYpAwGKUsEy aCJ6CZwMRlgaQSOfMQU0mVQQJEC3ujVj6U31z9NGPgrVxF2st/n7rrBleyRRfHh4qN33 eTQs/4kSIUCaV7r7/hTQ2JmvvxIHuechz2YsSJMQUKAcktGnLvfHUxoFnNuMjtPsBOpz C0aPxsvO3td9MzGRF5QT07ZdLYZo9WzNfk2bHrFBv78SHy5pAyVU++PDUi6tvD67Ak+r mGVQ== X-Gm-Message-State: AIkVDXK0f755dzoNWzkrae1ak+07432VntsYIjS9d48r0MXHJM9Kp59Ccr3ul8HCPfT0hFJj X-Received: by 10.46.77.9 with SMTP id a9mr10650929ljb.25.1485873834786; Tue, 31 Jan 2017 06:43:54 -0800 (PST) Received: from gnarp.ideon.se ([85.235.10.227]) by smtp.gmail.com with ESMTPSA id t13sm4658940ljd.42.2017.01.31.06.43.53 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 31 Jan 2017 06:43:53 -0800 (PST) From: Linus Walleij To: linux-gpio@vger.kernel.org, Alexandre Courbot Cc: Linus Walleij Subject: [PATCH] gpio: random documentation update Date: Tue, 31 Jan 2017 15:43:50 +0100 Message-Id: <20170131144350.28025-1-linus.walleij@linaro.org> X-Mailer: git-send-email 2.9.3 Sender: linux-gpio-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-gpio@vger.kernel.org Updated and proofread the documentation for GPIO drivers a bit when looking over the changes for generic configuration. Signed-off-by: Linus Walleij --- Documentation/gpio/driver.txt | 55 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 9 deletions(-) -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-gpio" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index ad8f0c0cd13f..fc1d2f83564d 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -41,34 +41,71 @@ In the gpiolib framework each GPIO controller is packaged as a "struct gpio_chip" (see linux/gpio/driver.h for its complete definition) with members common to each controller of that type: - - methods to establish GPIO direction - - methods used to access GPIO values - - method to return the IRQ number associated to a given GPIO + - methods to establish GPIO line direction + - methods used to access GPIO line values + - method to set electrical configuration to a a given GPIO line + - method to return the IRQ number associated to a given GPIO line - flag saying whether calls to its methods may sleep + - optional line names array to identify lines - optional debugfs dump method (showing extra state like pullup config) - optional base number (will be automatically assigned if omitted) - - label for diagnostics and GPIOs mapping using platform data + - optional label for diagnostics and GPIO chip mapping using platform data The code implementing a gpio_chip should support multiple instances of the controller, possibly using the driver model. That code will configure each -gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare; -use gpiochip_remove() when it is unavoidable. +gpio_chip and issue gpiochip_add[_data]() or devm_gpiochip_add_data(). +Removing a GPIO controller should be rare; use [devm_]gpiochip_remove() when +it is unavoidable. -Most often a gpio_chip is part of an instance-specific structure with state not +Often a gpio_chip is part of an instance-specific structure with states not exposed by the GPIO interfaces, such as addressing, power management, and more. -Chips such as codecs will have complex non-GPIO state. +Chips such as audio codecs will have complex non-GPIO states. Any debugfs dump method should normally ignore signals which haven't been requested as GPIOs. They can use gpiochip_is_requested(), which returns either NULL or the label associated with that GPIO when it was requested. -RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs +RT_FULL: the GPIO driver should not use spinlock_t or any sleepable APIs (like PM runtime) in its gpio_chip implementation (.get/.set and direction control callbacks) if it is expected to call GPIO APIs from atomic context on -RT (inside hard IRQ handlers and similar contexts). Normally this should not be required. +GPIO electrical configuration +----------------------------- + +GPIOs can be configured for several electrical modes of operation by using the +.set_config() callback. Currently this API supports setting debouncing and +single-ended modes (open drain/open source). These settings are described +below. + +The .set_config() callback uses the same enumerators and configuration +semantics as the generic pin control drivers. This is not a coincidence: it is +possible to assign the .set_config() to the function gpiochip_generic_config() +which will result in pinctrl_gpio_set_config() being called and eventually +ending up in the pin control back-end "behind" the GPIO controller, usually +closer to the actual pins. This way the pin controller can manage the below +listed GPIO configurations. + + +GPIOs with debounce support +--------------------------- + +Debouncing is a configuration set to a pin indicating that it is connected to +a mechanical switch or button, or similar that may bounce. Bouncing means the +line is pulled high/low quickly at very short intervals for mechanical +reasons. This can result in the value being unstable or irqs fireing repeatedly +unless the line is debounced. + +Debouncing in practice involves setting up a timer when something happens on +the line, wait a little while and then sample the line again, so see if it +still has the same value (low or high). This could also be repeated by a clever +state machine, waiting for a line to become stable. In either case, it sets +a certain number of milliseconds for debouncing, or just "on/off" if that time +is not configurable. + + GPIOs with open drain/source support ------------------------------------