From patchwork Mon Jul 15 18:40:25 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Warren X-Patchwork-Id: 2827708 Return-Path: X-Original-To: patchwork-linux-arm@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 759CD9F7D6 for ; Mon, 15 Jul 2013 18:41:56 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 539EE2026C for ; Mon, 15 Jul 2013 18:41:55 +0000 (UTC) Received: from casper.infradead.org (casper.infradead.org [85.118.1.10]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 376B92026A for ; Mon, 15 Jul 2013 18:41:54 +0000 (UTC) Received: from merlin.infradead.org ([2001:4978:20e::2]) by casper.infradead.org with esmtps (Exim 4.80.1 #2 (Red Hat Linux)) id 1Uyni1-0002Oh-Bh; Mon, 15 Jul 2013 18:41:18 +0000 Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.80.1 #2 (Red Hat Linux)) id 1Uynhv-0005DR-C1; Mon, 15 Jul 2013 18:41:11 +0000 Received: from avon.wwwdotorg.org ([2001:470:1f0f:bd7::2]) by merlin.infradead.org with esmtps (Exim 4.80.1 #2 (Red Hat Linux)) id 1Uynhi-0005B3-7k for linux-arm-kernel@lists.infradead.org; Mon, 15 Jul 2013 18:40:59 +0000 Received: from severn.wwwdotorg.org (unknown [192.168.65.5]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by avon.wwwdotorg.org (Postfix) with ESMTPS id 3D83762E3; Mon, 15 Jul 2013 12:52:48 -0600 (MDT) Received: from swarren-lx1.nvidia.com (localhost [127.0.0.1]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by severn.wwwdotorg.org (Postfix) with ESMTPSA id 40130E40EB; Mon, 15 Jul 2013 12:40:35 -0600 (MDT) From: Stephen Warren To: Linus Walleij , Rob Herring Subject: [PATCH V2 1/5] gpio: clean up gpio-ranges documentation Date: Mon, 15 Jul 2013 12:40:25 -0600 Message-Id: <1373913629-32179-1-git-send-email-swarren@wwwdotorg.org> X-Mailer: git-send-email 1.8.1.5 X-NVConfidentiality: public X-Virus-Scanned: clamav-milter 0.97.7 at avon.wwwdotorg.org X-Virus-Status: Clean X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20130715_144058_479140_46AA9734 X-CRM114-Status: GOOD ( 10.53 ) X-Spam-Score: -2.3 (--) Cc: Stephen Warren , linux-gpio@vger.kernel.org, devicetree-discuss@lists.ozlabs.org, Shiraz Hashim , Haojian Zhuang , Jingchang Lu , Shawn Guo , linux-arm-kernel@lists.infradead.org X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org X-Spam-Status: No, score=-4.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Stephen Warren This change makes documentation of the the gpio-ranges property shorter and more succinct, more consistent with the style of the rest of the document, and not mention Linux-specifics such as the API pinctrl_request_gpio(); DT binding documents should be OS independant where at all possible. This change also removes any mention of the #gpio-range-cells property. Such properties are useful when one node references a second node, and that second node dictates the format of the reference. However, that is not the case here; the definition of gpio-ranges itself always dictates its format entirely, and hence the value #gpio-range-cells must always be 3, and hence there is no point requiring any referenced node to include this property. Signed-off-by: Stephen Warren --- Patches 2-6 need to be applied in the same branch, since they all build upon each-other. --- Documentation/devicetree/bindings/gpio/gpio.txt | 48 ++++++++++++------------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index d933af3..b262378 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -75,23 +75,29 @@ Example of two SOC GPIO banks defined as gpio-controller nodes: gpio-controller; }; -2.1) gpio-controller and pinctrl subsystem ------------------------------------------- +2.1) gpio- and pin-controller interaction +----------------------------------------- -gpio-controller on a SOC might be tightly coupled with the pinctrl -subsystem, in the sense that the pins can be used by other functions -together with optional gpio feature. +Some or all of the GPIOs provided by a GPIO controller may be routed to pins +on the package via a pin controller. This allows muxing those pins between +GPIO and other functions. -While the pin allocation is totally managed by the pin ctrl subsystem, -gpio (under gpiolib) is still maintained by gpio drivers. It may happen -that different pin ranges in a SoC is managed by different gpio drivers. +It is useful to represent which GPIOs correspond to which pins on which pin +controllers. The gpio-ranges property described below represents this, and +contains information strucutres as follows: -This makes it logical to let gpio drivers announce their pin ranges to -the pin ctrl subsystem and call 'pinctrl_request_gpio' in order to -request the corresponding pin before any gpio usage. + gpio-range-list ::= [gpio-range-list] + single-gpio-range ::= + + gpio-phandle : phandle to pin controller node. + gpio-base : Base GPIO ID in the GPIO controller + pinctrl-base : Base pinctrl pin ID in the pin controller + count : The number of GPIOs/pins in this range -For this, the gpio controller can use a pinctrl phandle and pins to -announce the pinrange to the pin ctrl subsystem. For example, +The "pin controller node" mentioned above must conform to the bindings +described in ../pinctrl/pinctrl-bindings.txt. + +Example: qe_pio_e: gpio-controller@1460 { #gpio-cells = <2>; @@ -99,16 +105,8 @@ announce the pinrange to the pin ctrl subsystem. For example, reg = <0x1460 0x18>; gpio-controller; gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; + }; - } - -where, - &pinctrl1 and &pinctrl2 is the phandle to the pinctrl DT node. - - Next values specify the base pin and number of pins for the range - handled by 'qe_pio_e' gpio. In the given example from base pin 20 to - pin 29 under pinctrl1 with gpio offset 0 and pin 50 to pin 69 under - pinctrl2 with gpio offset 10 is handled by this gpio controller. - -The pinctrl node must have "#gpio-range-cells" property to show number of -arguments to pass with phandle from gpio controllers node. +Here, a single GPIO controller has GPIOs 0..9 routed to pin controller +pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's +pins 50..59.