From patchwork Tue Jan 6 03:05:23 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 425494 X-Patchwork-Delegate: sjg@chromium.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from theia.denx.de (theia.denx.de [85.214.87.163]) by ozlabs.org (Postfix) with ESMTP id 784A6140077 for ; Tue, 6 Jan 2015 14:06:40 +1100 (AEDT) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id 53B6B4B67B; Tue, 6 Jan 2015 04:06:33 +0100 (CET) Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 6XMZ7pMEKg30; Tue, 6 Jan 2015 04:06:33 +0100 (CET) Received: from theia.denx.de (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id B42864B67C; Tue, 6 Jan 2015 04:06:19 +0100 (CET) Received: from localhost (localhost [127.0.0.1]) by theia.denx.de (Postfix) with ESMTP id EA7C44B61D for ; Tue, 6 Jan 2015 04:06:08 +0100 (CET) Received: from theia.denx.de ([127.0.0.1]) by localhost (theia.denx.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 7o0KPvevVZv1 for ; Tue, 6 Jan 2015 04:06:08 +0100 (CET) X-policyd-weight: NOT_IN_SBL_XBL_SPAMHAUS=-1.5 NOT_IN_SPAMCOP=-1.5 NOT_IN_BL_NJABL=-1.5 (only DNSBL check requested) Received: from mail-ob0-f201.google.com (mail-ob0-f201.google.com [209.85.214.201]) by theia.denx.de (Postfix) with ESMTPS id 7BFB84B61A for ; Tue, 6 Jan 2015 04:06:04 +0100 (CET) Received: by mail-ob0-f201.google.com with SMTP id vb8so218250obc.0 for ; Mon, 05 Jan 2015 19:06:03 -0800 (PST) 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:in-reply-to :references; bh=2kkwfk5L/IfD/J+4khm+aCbJvGlZ+VPx9gM1TF9abMg=; b=JADo3COXYpVpIse56ds0IRc1jk0bfxsH8Q3Jyl2XlPz4fCg69LIpzIQItQ4cxdoiUx q6B6XvhpwgW6xUe47eIc/HISsOv/EYJWCbG2qdT6F7IJ4aDl9OiDxPpL5SEvWFmV0teF 3SnIbxSdcOVU0o8GYSTmrO4jFQxFohPwBdQbevUEYPyGAiAPZ0OQ58fQ0jYPOGfGfYqY JyStJ7xvhPdMne3n07h0O32CLdVvbqFAFyBSBS5Chh9az/ZrCzZudsK4yFdjAUElQLvY m/q2BH0FOROY+pEAfJotpKMhVDVIL6xyWmQVWvDG94Xnr0Hp/gYJC7l/5h2ImzZQDHUR OaSg== X-Gm-Message-State: ALoCoQnUSgS2h1Bqj1WyuxleZ/MKqio7whEcVutQvf6JkwhxlCMxeW9ornZHjQ+nOMo2BZbu/L1I X-Received: by 10.42.89.211 with SMTP id h19mr6540931icm.32.1420513563309; Mon, 05 Jan 2015 19:06:03 -0800 (PST) Received: from corpmail-nozzle1-2.hot.corp.google.com ([100.108.1.103]) by gmr-mx.google.com with ESMTPS id t7si1126860yho.3.2015.01.05.19.06.02 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 05 Jan 2015 19:06:03 -0800 (PST) Received: from kaki.bld.corp.google.com ([172.29.216.32]) by corpmail-nozzle1-2.hot.corp.google.com with ESMTP id 6zPDKavg.1; Mon, 05 Jan 2015 19:06:03 -0800 Received: by kaki.bld.corp.google.com (Postfix, from userid 121222) id 8C1112203F6; Mon, 5 Jan 2015 20:06:02 -0700 (MST) From: Simon Glass To: U-Boot Mailing List Date: Mon, 5 Jan 2015 20:05:23 -0700 Message-Id: <1420513543-4453-2-git-send-email-sjg@chromium.org> X-Mailer: git-send-email 2.2.0.rc0.207.ga3a616c In-Reply-To: <1420513543-4453-1-git-send-email-sjg@chromium.org> References: <1420513543-4453-1-git-send-email-sjg@chromium.org> Subject: [U-Boot] [PATCH 01/21] dm: gpio: Bring in GPIO device tree binding X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.13 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: u-boot-bounces@lists.denx.de Errors-To: u-boot-bounces@lists.denx.de Add the binding file that we are about to support. Signed-off-by: Simon Glass --- doc/device-tree-bindings/gpio/gpio.txt | 211 +++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 doc/device-tree-bindings/gpio/gpio.txt diff --git a/doc/device-tree-bindings/gpio/gpio.txt b/doc/device-tree-bindings/gpio/gpio.txt new file mode 100644 index 0000000..b9bd1d6 --- /dev/null +++ b/doc/device-tree-bindings/gpio/gpio.txt @@ -0,0 +1,211 @@ +Specifying GPIO information for devices +============================================ + +1) gpios property +----------------- + +Nodes that makes use of GPIOs should specify them using one or more +properties, each containing a 'gpio-list': + + gpio-list ::= [gpio-list] + single-gpio ::= + gpio-phandle : phandle to gpio controller node + gpio-specifier : Array of #gpio-cells specifying specific gpio + (controller specific) + +GPIO properties should be named "[-]gpios", with being the purpose +of this GPIO for the device. While a non-existent is considered valid +for compatibility reasons (resolving to the "gpios" property), it is not allowed +for new bindings. + +GPIO properties can contain one or more GPIO phandles, but only in exceptional +cases should they contain more than one. If your device uses several GPIOs with +distinct functions, reference each of them under its own property, giving it a +meaningful name. The only case where an array of GPIOs is accepted is when +several GPIOs serve the same function (e.g. a parallel data line). + +The exact purpose of each gpios property must be documented in the device tree +binding of the device. + +The following example could be used to describe GPIO pins used as device enable +and bit-banged data signals: + + gpio1: gpio1 { + gpio-controller + #gpio-cells = <2>; + }; + gpio2: gpio2 { + gpio-controller + #gpio-cells = <1>; + }; + [...] + + enable-gpios = <&gpio2 2>; + data-gpios = <&gpio1 12 0>, + <&gpio1 13 0>, + <&gpio1 14 0>, + <&gpio1 15 0>; + +Note that gpio-specifier length is controller dependent. In the +above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 +only uses one. + +gpio-specifier may encode: bank, pin position inside the bank, +whether pin is open-drain and whether pin is logically inverted. +Exact meaning of each specifier cell is controller specific, and must +be documented in the device tree binding for the device. Use the macros +defined in include/dt-bindings/gpio/gpio.h whenever possible: + +Example of a node using GPIOs: + + node { + enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>; + }; + +GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes +GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. + +1.1) GPIO specifier best practices +---------------------------------- + +A gpio-specifier should contain a flag indicating the GPIO polarity; active- +high or active-low. If it does, the follow best practices should be followed: + +The gpio-specifier's polarity flag should represent the physical level at the +GPIO controller that achieves (or represents, for inputs) a logically asserted +value at the device. The exact definition of logically asserted should be +defined by the binding for the device. If the board inverts the signal between +the GPIO controller and the device, then the gpio-specifier will represent the +opposite physical level than the signal at the device's pin. + +When the device's signal polarity is configurable, the binding for the +device must either: + +a) Define a single static polarity for the signal, with the expectation that +any software using that binding would statically program the device to use +that signal polarity. + +The static choice of polarity may be either: + +a1) (Preferred) Dictated by a binding-specific DT property. + +or: + +a2) Defined statically by the DT binding itself. + +In particular, the polarity cannot be derived from the gpio-specifier, since +that would prevent the DT from separately representing the two orthogonal +concepts of configurable signal polarity in the device, and possible board- +level signal inversion. + +or: + +b) Pick a single option for device signal polarity, and document this choice +in the binding. The gpio-specifier should represent the polarity of the signal +(at the GPIO controller) assuming that the device is configured for this +particular signal polarity choice. If software chooses to program the device +to generate or receive a signal of the opposite polarity, software will be +responsible for correctly interpreting (inverting) the GPIO signal at the GPIO +controller. + +2) gpio-controller nodes +------------------------ + +Every GPIO controller node must contain both an empty "gpio-controller" +property, and a #gpio-cells integer property, which indicates the number of +cells in a gpio-specifier. + +Example of two SOC GPIO banks defined as gpio-controller nodes: + + qe_pio_a: gpio-controller@1400 { + compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; + reg = <0x1400 0x18>; + gpio-controller; + #gpio-cells = <2>; + }; + + qe_pio_e: gpio-controller@1460 { + compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; + reg = <0x1460 0x18>; + gpio-controller; + #gpio-cells = <2>; + }; + +2.1) gpio- and pin-controller interaction +----------------------------------------- + +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. + +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 structures as follows: + + gpio-range-list ::= [gpio-range-list] + single-gpio-range ::= | + numeric-gpio-range ::= + + named-gpio-range ::= '<0 0>' + 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 + +The "pin controller node" mentioned above must conform to the bindings +described in ../pinctrl/pinctrl-bindings.txt. + +In case named gpio ranges are used (ranges with both and + set to 0), the property gpio-ranges-group-names contains one string +for every single-gpio-range in gpio-ranges: + gpiorange-names-list ::= [gpiorange-names-list] + gpiorange-name : Name of the pingroup associated to the GPIO range in + the respective pin controller. + +Elements of gpiorange-names-list corresponding to numeric ranges contain +the empty string. Elements of gpiorange-names-list corresponding to named +ranges contain the name of a pin group defined in the respective pin +controller. The number of pins/GPIOs in the range is the number of pins in +that pin group. + +Previous versions of this binding required all pin controller nodes that +were referenced by any gpio-ranges property to contain a property named +#gpio-range-cells with value <3>. This requirement is now deprecated. +However, that property may still exist in older device trees for +compatibility reasons, and would still be required even in new device +trees that need to be compatible with older software. + +Example 1: + + qe_pio_e: gpio-controller@1460 { + #gpio-cells = <2>; + compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; + reg = <0x1460 0x18>; + gpio-controller; + gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; + }; + +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. + +Example 2: + + gpio_pio_i: gpio-controller@14B0 { + #gpio-cells = <2>; + compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; + reg = <0x1480 0x18>; + gpio-controller; + gpio-ranges = <&pinctrl1 0 20 10>, + <&pinctrl2 10 0 0>, + <&pinctrl1 15 0 10>, + <&pinctrl2 25 0 0>; + gpio-ranges-group-names = "", + "foo", + "", + "bar"; + }; + +Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO +ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2 +are named "foo" and "bar".