From patchwork Tue Apr 5 14:56:02 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 65099 Delivered-To: patch@linaro.org Received: by 10.112.199.169 with SMTP id jl9csp513555lbc; Tue, 5 Apr 2016 07:56:14 -0700 (PDT) X-Received: by 10.66.66.234 with SMTP id i10mr63744159pat.114.1459868174233; Tue, 05 Apr 2016 07:56:14 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id ze7si8272548pac.34.2016.04.05.07.56.14; Tue, 05 Apr 2016 07:56:14 -0700 (PDT) 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 dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758661AbcDEO4L (ORCPT + 4 others); Tue, 5 Apr 2016 10:56:11 -0400 Received: from mail-lb0-f170.google.com ([209.85.217.170]:36049 "EHLO mail-lb0-f170.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751899AbcDEO4I (ORCPT ); Tue, 5 Apr 2016 10:56:08 -0400 Received: by mail-lb0-f170.google.com with SMTP id qe11so11032514lbc.3 for ; Tue, 05 Apr 2016 07:56:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=y6i/RgejfWuxjNT8IcCN/+5YOOavLOFywmAmLKwlSlU=; b=X664bX1EDbfD04eW1AxHLswld7bxwqdmXktOYCHAokk7/8hjg+DdOxsdkN65v9xfOO m3/zuZNPjfS4pC6KfyD5/igBbDOq8QslKFyLjt3Dful/ykS7AQK5f881ONySUwuMnRTo 2XII8r72kjYBYHZxaUNPXXkecpOWeeadh7ni0= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=y6i/RgejfWuxjNT8IcCN/+5YOOavLOFywmAmLKwlSlU=; b=gQn1SxUFvPvjy8fSjbRfM1+xa4f730iJVWIfztkv3kq0lha0r/nMeN2fHgZ9wMbIr1 7FeIuW093bX9F+K5QiccZ6WwDbZPqO+PB4axLkhwpQWlE+VVQ1LUaAq1UzKVMVa09W8c efJIEekOyoQZCQ1eaIy6bVqLhm4+RKCv6+03Eh9aErBkwO1NQQzpI/WwXRywU8KPHNiF 4ib9vTTO/M6NtDAKolKu25oi0MwqDtRWTyotIytYuDG3EM7rsCJhZ7Rxs3L9ZQKMlLvX pnC75FO5m6zhaPxZIpQ7xvw2Zi+sik/KGol4GaoAUUqIJgOs5JVkkZ6STRwjekktzp3R T4mg== X-Gm-Message-State: AD7BkJI4RiNXNupx4g9SWLdzrCb9Il9buof79xWmFqUnZIMYsLeg7v8RvJuNAIajAf+IMf79 X-Received: by 10.113.4.4 with SMTP id ca4mr7799258lbd.6.1459868166597; Tue, 05 Apr 2016 07:56:06 -0700 (PDT) Received: from localhost.localdomain ([85.235.10.227]) by smtp.gmail.com with ESMTPSA id i9sm5587362lfe.31.2016.04.05.07.56.05 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 05 Apr 2016 07:56:05 -0700 (PDT) From: Linus Walleij To: linux-gpio@vger.kernel.org, Alexandre Courbot Cc: Linus Walleij , Michael Hennerich , Nicolas Saenz Julienne , "H. Nikolaus Schaller" Subject: [PATCH] gpio: document open drain/source behaviour Date: Tue, 5 Apr 2016 16:56:02 +0200 Message-Id: <1459868162-9736-1-git-send-email-linus.walleij@linaro.org> X-Mailer: git-send-email 2.4.3 Sender: linux-gpio-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-gpio@vger.kernel.org This has been a totally undocumented feature for years so add some generic concepts and documentation about open drain/source, include some facts on how we now support for hardware. Cc: Michael Hennerich Cc: Nicolas Saenz Julienne Cc: H. Nikolaus Schaller Signed-off-by: Linus Walleij --- Documentation/gpio/driver.txt | 68 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) -- 2.4.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 bbeec415f406..4cfcf889efcb 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -68,6 +68,74 @@ 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. + +GPIOs with open drain/source support +------------------------------------ + +Open drain (CMOS) or open collector (TTL) is traditionally a way to achieve +wire-OR on an I/O line, for example a GPIO line, using a single transistor. +This means the line is not actively driven high, instead you provide the +drain/collector as output, so when the transistor is not open, it will present +a high-impedance (tristate) to the external rail. This means it will not +conflict with other similarly wired I/O lines on the rail, and when accompanied +with a pull-up resistor, this will tend to high level unless one of the +transistors on the rail actively pull it down. + +Modern electronics very seldom has this kind of single-transistor output +stage. Instead they usually have a CMOS "totempole" with one N-MOS and one +P-MOS transistor where one of them drive the line high and one of them drive +the line low. This is called a push-pull-output. The "totempole" looks like so, +and shold be familiar to anyone working with electronics: + + VDD + | + ||--+ + +--/ ---o|| P-MOS-FET + | ||--+ +in --+ +----- out + | ||--+ + +--/ ----|| N-MOS-FET + ||--+ + | + GND + +You see the little "switches" that enable/disable the P-MOS or N-MOS transistor +right after the split of the input. As you can see, either transistor will go +totally numb if this switch is open. That is usually how software-controlled +open drain/source works. + +Some GPIO hardware support open drain / open source configuration. What this +means in practice is usually that the driver has a push-pull output driver +stage with one N-MOS and one P-MOS transistor like above, and using software, +one of the transistors can be disabled, yielding an open drain or open source +output. + +By disabling the P-MOS transistor, the output can be driven between GND and +high impedance (open drain), and by disabling the N-MOS transistor, the output +can be driven between VDD and high impedance (open source). In the first case, +a pull-up resistor is needed on the outgoing rail to complete the circuit, and +in the second case, a pull-down resistor is needed on the rail. + +Hardware that supports open drain or open source or both, can implement a +special callback in the gpio_chip: .set_single_ended() that takes an enum flag +telling whether to configure the line as open drain, open source or push-pull. +This will happen i response to the GPIO_OPEN_DRAIN or GPIO_OPEN_SOURCE flag +set in the machine file, or coming from other hardware descriptions. + +If this state can not be configured in hardware, i.e. if the GPIO hardware does +not support open drain/open source in hardware, the GPIO library will instead +use a trick: when a line is set as output, if the line is flagged as open +drain, and the output value is negative, it will be driven low as usual. But +if the output value is set to positive, it will instead *NOT* be driven high, +instead it will be switched to input, as input mode is high impedance, thus +achieveing a "open drain emulation" of sorts: electrically the behaviour will +be identical, with the exception of possible hardware glitches when switching +the mode of the line. + +For open source configuration the same principle is used, just that instead +of actively driving the line low, it is set to input. + + GPIO drivers providing IRQs --------------------------- It is custom that GPIO drivers (GPIO chips) are also providing interrupts,