From patchwork Thu Sep 13 07:47:02 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 146612 Delivered-To: patch@linaro.org Received: by 2002:a2e:1648:0:0:0:0:0 with SMTP id 8-v6csp294573ljw; Thu, 13 Sep 2018 00:47:12 -0700 (PDT) X-Google-Smtp-Source: ANB0VdZbKsgCPO8f9qDPDmOd1SMbkjUfdpb5HAGiOolVhcj9oQvXA49q8Vt+HTjYSWVPnkgFybiN X-Received: by 2002:a62:1bc2:: with SMTP id b185-v6mr6210086pfb.170.1536824832637; Thu, 13 Sep 2018 00:47:12 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1536824832; cv=none; d=google.com; s=arc-20160816; b=PgA7Nm4c0uIvAJgYJf8lvLD4laydE/3TF5Yi9oAnOGyQPsIIio52TjjcBOVVoyfDVv +1qOTtptK+oel66gkBX3zFVuB0k7TinSWecRrVJ+dPhYfY5v4Rz1lWoNR5cGbEAW29F7 XrYz2Xp8IcPdtymro5v8YmY4jz5PbZJ2rYSeanocAgarib6WKuDC+ShsRtuhrdhGp4RR PoDe6UKctapSifWybhshM9JCTgblhyvuPf/tqwICrVLPuClOO5ENZkk+6YcqtBWXaidm wUHUNKWKGGr9ZbnlxEGn/zvMNUHEUnXj4G+4WCkHWJ5OvXtX2pSxBn4N1wcS4vcGNh2s N92w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:message-id:date:subject:cc:to:from :dkim-signature; bh=NYLovZ4zC4KTlYpYjQGfz3KgPxt2wH3LpV4blT5R4n4=; b=0MkZy6SxKlxE1iXU5KmrCG33qV4vSBXMFximdGpI6LmRXopc4HgScDDGWrEjd/tlP0 7kz30L/HWQioTDnrTRaoI4fKjUnHWdD2yb7EYYxW+botZsWRdE3EKRgvpbNLONSVUvUF zKweST5ZE9dKL5Y6YbDaaVYdWpWDT7dNdukwGWpwPIoYpsu+OxTvGh1V0G9PKA636zBO yaevY0AnmUFiUd8uPgqRIIQkuAuyN2HjryAYGc5vKWWnqNS1w2NrxKpdYN3BzR+Pkyuk JSnyzeO5/Qa39XqVXju148sfzugUHNxbOQ6EzzPyWQGoz1fBgzhlAUukMSECLptP/UvV 7MDw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="BRo/zZUL"; 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=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id a27-v6si3485998pfh.164.2018.09.13.00.47.12; Thu, 13 Sep 2018 00:47:12 -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=pass header.i=@linaro.org header.s=google header.b="BRo/zZUL"; 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=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726697AbeIMMz2 (ORCPT + 5 others); Thu, 13 Sep 2018 08:55:28 -0400 Received: from mail-lf1-f67.google.com ([209.85.167.67]:44771 "EHLO mail-lf1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726733AbeIMMz2 (ORCPT ); Thu, 13 Sep 2018 08:55:28 -0400 Received: by mail-lf1-f67.google.com with SMTP id g6-v6so3934692lfb.11 for ; Thu, 13 Sep 2018 00:47:09 -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=NYLovZ4zC4KTlYpYjQGfz3KgPxt2wH3LpV4blT5R4n4=; b=BRo/zZULLKNDF+lzyibu2liRhQt+vIBHqguzP/HuEYP1fYNyu9dnnsnBhEPr79Hzl4 d4iCrfv/TdYk17hxwVWkOloLe458GOs/ZLDGF8Ry++ckFuMGidfgUe48lDM0ol+rJbGa nd+P303I5uQeMYp9RcHP/7uecNiSEvWctCSJo= 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=NYLovZ4zC4KTlYpYjQGfz3KgPxt2wH3LpV4blT5R4n4=; b=nbAPgDDsJryugnkVP4kdyK0yuMefZM2BvvIuud4zB6fSSZt81558gfm4bw4Rv1fTxD 3dI8sAnsAdcy7GuZT6MOZE8WNAPXvr/r1+XA1V7l6gMlobXMhSraSpHZuk5y1xAWwYN3 cl6EnIw2LqZfkJQTF4BgQCq8OMQ3WwBdnO2BINYv6O43XmZ5yMJs/4Wp66O/mgotRdN0 NBBKWt7muqGmcGPeSTLiY/2nw7vNLPt1gLxF2q5oCHxsl8D9s8ruROeqzKRfHka/pvrs WmKSpZfzPUCNa5e8tmyOQ2GrbsMun9CLG7bcj3y7g+2eByNx9j0KNEw60Jyqn+fUjeRD 6HVg== X-Gm-Message-State: APzg51B94YJSoJ0/9MBz88CofmQanOiUvW5wWPWyPneI1/D9RGbtfQiR v90JftSEy+q3GmMObllFfp77RkzXsDA= X-Received: by 2002:a19:c20f:: with SMTP id l15-v6mr4086129lfc.21.1536824828139; Thu, 13 Sep 2018 00:47:08 -0700 (PDT) Received: from genomnajs.ideon.se ([85.235.10.227]) by smtp.gmail.com with ESMTPSA id m20-v6sm579298lfb.27.2018.09.13.00.47.06 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 13 Sep 2018 00:47:06 -0700 (PDT) From: Linus Walleij To: linux-gpio@vger.kernel.org Cc: Linus Walleij , devicetree@vger.kernel.org, Grant Likely , Rob Herring , Kumar Gala Subject: [PATCH] gpio: OF: Cut painful BNF experiments from bindings Date: Thu, 13 Sep 2018 09:47:02 +0200 Message-Id: <20180913074702.5724-1-linus.walleij@linaro.org> X-Mailer: git-send-email 2.17.1 Sender: linux-gpio-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-gpio@vger.kernel.org In 2011 the commit bf859f84a19f ("gpio/dt: Refine GPIO device tree binding") introduced an experimental BNF notation for defining a regular grammar for the GPIO phandles used by different devices. This was an interesting approach, and shows that we have long nutured the idea to formally verify device tree files using regular grammar. Most if not all other bindings use natural language to define the bindings, and the recent thinking for verifying device tree files is to use JSON schemas in separate definitions. Cut the BNF business and replace it with natural language so that it becomes more human-readable for now. Cc: devicetree@vger.kernel.org Cc: Grant Likely Cc: Rob Herring Cc: Kumar Gala Signed-off-by: Linus Walleij --- .../devicetree/bindings/gpio/gpio.txt | 114 ++++++++++-------- 1 file changed, 64 insertions(+), 50 deletions(-) -- 2.17.1 diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 0451f612ff2b..3afaa396adf7 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -1,18 +1,9 @@ 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 @@ -236,46 +227,40 @@ Example of two SOC GPIO banks defined as gpio-controller nodes: 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. +GPIO and other functions. It is a fairly common practice among silicon +engineers. + +2.2) Ordinary (numerical) GPIO ranges +------------------------------------- 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>' - pinctrl-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. +controllers. The gpio-ranges property described below represents this with +a discrete set of ranges mapping pins from the pin controller local number space +to pins in the GPIO controller local number space. + +The format is: <[pin controller phandle], [GPIO controller offset], + [pin controller offset], [number of pins]>; + +The GPIO controller offset pertains to the GPIO controller node containing the +range definition. + +The pin controller node referenced by the phandle must conform to the bindings +described in pinctrl/pinctrl-bindings.txt. + +Each offset runs from 0 to N. It is perfectly fine to pile any number of +ranges with just one pin-to-GPIO line mapping if the ranges are concocted, but +in practice these ranges are often lumped in discrete sets. + +Example: + + gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>; + +This means: +- pins 20..29 on pin controller "foo" is mapped to GPIO line 0..9 and +- pins 50..69 on pin controller "bar" is mapped to GPIO line 10..29 -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: +Verbose example: qe_pio_e: gpio-controller@1460 { #gpio-cells = <2>; @@ -289,7 +274,28 @@ Here, a single GPIO controller has GPIOs 0..9 routed to pin controller pinctrl1's pins 20..29, and GPIOs 10..29 routed to pin controller pinctrl2's pins 50..69. -Example 2: + +2.3) GPIO ranges from named pin groups +-------------------------------------- + +It is also possible to use pin groups for gpio ranges when pin groups are the +easiest and most convenient mapping. + +Both both and must set to 0 when using named pin groups +names. + +The property gpio-ranges-group-names must contain exactly one string for each +range. + +Elements of gpio-ranges-group-names must contain the name of a pin group +defined in the respective pin controller. The number of pins/GPIO lines in the +range is the number of pins in that pin group. The number of pins of that +group is defined int the implementation and not in the device tree. + +If numerical and named pin groups are mixed, the string corresponding to a +numerical pin range in gpio-ranges-group-names must be empty. + +Example: gpio_pio_i: gpio-controller@14b0 { #gpio-cells = <2>; @@ -306,6 +312,14 @@ Example 2: "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". +Here, three GPIO ranges are defined referring to two pin controllers. + +pinctrl1 GPIO ranges are defined using pin numbers whereas the GPIO ranges +in pinctrl2 are defined using the pin groups named "foo" and "bar". + +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.