Commit a1bc260b authored by Stephen Warren's avatar Stephen Warren Committed by Linus Walleij

gpio: clean up gpio-ranges documentation

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. As part of this, the gpio-ranges property's format
is described in BNF form, in order to match the rest of the document.

This change also deprecates 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. The only remaining need for this property is to ensure
compatibility of DTs with older SW that was written to support the
previous version of the binding.

v4:
* Mention #gpio-range-cells as being deprecated, rather than removing all
  documentation of that property. This allows DTs to be written in a
  backwards-compatible way if desired, and also allows older DTs to be
  interpreted fully using the latest documentation.
v3:
* Mention BNF in commit description.
* Fixed typo.
* Dropped patch that removed the deprecated property from *.dts, since
  it's required to boot older kernels.
Signed-off-by: default avatarStephen Warren <swarren@nvidia.com>
Acked-by: default avatarMark Rutland <mark.rutland@arm.com>
Signed-off-by: default avatarLinus Walleij <linus.walleij@linaro.org>
parent 0fabc835
...@@ -75,23 +75,36 @@ Example of two SOC GPIO banks defined as gpio-controller nodes: ...@@ -75,23 +75,36 @@ Example of two SOC GPIO banks defined as gpio-controller nodes:
gpio-controller; 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 Some or all of the GPIOs provided by a GPIO controller may be routed to pins
subsystem, in the sense that the pins can be used by other functions on the package via a pin controller. This allows muxing those pins between
together with optional gpio feature. GPIO and other functions.
While the pin allocation is totally managed by the pin ctrl subsystem, It is useful to represent which GPIOs correspond to which pins on which pin
gpio (under gpiolib) is still maintained by gpio drivers. It may happen controllers. The gpio-ranges property described below represents this, and
that different pin ranges in a SoC is managed by different gpio drivers. contains information structures as follows:
This makes it logical to let gpio drivers announce their pin ranges to gpio-range-list ::= <single-gpio-range> [gpio-range-list]
the pin ctrl subsystem and call 'pinctrl_request_gpio' in order to single-gpio-range ::=
request the corresponding pin before any gpio usage. <pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
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 The "pin controller node" mentioned above must conform to the bindings
announce the pinrange to the pin ctrl subsystem. For example, described in ../pinctrl/pinctrl-bindings.txt.
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:
qe_pio_e: gpio-controller@1460 { qe_pio_e: gpio-controller@1460 {
#gpio-cells = <2>; #gpio-cells = <2>;
...@@ -99,16 +112,8 @@ announce the pinrange to the pin ctrl subsystem. For example, ...@@ -99,16 +112,8 @@ announce the pinrange to the pin ctrl subsystem. For example,
reg = <0x1460 0x18>; reg = <0x1460 0x18>;
gpio-controller; gpio-controller;
gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; 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
where, pins 50..59.
&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.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment