a1bc260bb5
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: Stephen Warren <swarren@nvidia.com> Acked-by: Mark Rutland <mark.rutland@arm.com> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
120 lines
3.8 KiB
Plaintext
120 lines
3.8 KiB
Plaintext
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 ::= <single-gpio> [gpio-list]
|
|
single-gpio ::= <gpio-phandle> <gpio-specifier>
|
|
gpio-phandle : phandle to gpio controller node
|
|
gpio-specifier : Array of #gpio-cells specifying specific gpio
|
|
(controller specific)
|
|
|
|
GPIO properties should be named "[<name>-]gpios". Exact
|
|
meaning of each gpios property must be documented in the device tree
|
|
binding for each device.
|
|
|
|
For example, the following could be used to describe gpios pins to use
|
|
as chip select lines; with chip selects 0, 1 and 3 populated, and chip
|
|
select 2 left empty:
|
|
|
|
gpio1: gpio1 {
|
|
gpio-controller
|
|
#gpio-cells = <2>;
|
|
};
|
|
gpio2: gpio2 {
|
|
gpio-controller
|
|
#gpio-cells = <1>;
|
|
};
|
|
[...]
|
|
chipsel-gpios = <&gpio1 12 0>,
|
|
<&gpio1 13 0>,
|
|
<0>, /* holes are permitted, means no GPIO 2 */
|
|
<&gpio2 2>;
|
|
|
|
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.
|
|
|
|
Example of the node using GPIOs:
|
|
|
|
node {
|
|
gpios = <&qe_pio_e 18 0>;
|
|
};
|
|
|
|
In this example gpio-specifier is "18 0" and encodes GPIO pin number,
|
|
and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller.
|
|
|
|
2) gpio-controller nodes
|
|
------------------------
|
|
|
|
Every GPIO controller node must both an empty "gpio-controller"
|
|
property, and have #gpio-cells contain the size of the gpio-specifier.
|
|
|
|
Example of two SOC GPIO banks defined as gpio-controller nodes:
|
|
|
|
qe_pio_a: gpio-controller@1400 {
|
|
#gpio-cells = <2>;
|
|
compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
|
|
reg = <0x1400 0x18>;
|
|
gpio-controller;
|
|
};
|
|
|
|
qe_pio_e: gpio-controller@1460 {
|
|
#gpio-cells = <2>;
|
|
compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
|
|
reg = <0x1460 0x18>;
|
|
gpio-controller;
|
|
};
|
|
|
|
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 ::= <single-gpio-range> [gpio-range-list]
|
|
single-gpio-range ::=
|
|
<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
|
|
|
|
The "pin controller node" mentioned above must conform to the bindings
|
|
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 {
|
|
#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.
|