Commit 2071d096 authored by Alexandre Courbot's avatar Alexandre Courbot Committed by Linus Walleij

Documentation: gpio: guidelines for bindings

Now that ACPI supports named GPIO properties, either through ACPI 5.1 or
the per-driver ACPI GPIO mappings, we can be more narrow about the way
GPIOs should be specified in Device Tree bindings.

This patch updates the GPIO DT bindings documentation to highlight the
following rules for new GPIO bindings:

- All new bindings must have a meaningful name (e.g. the "gpios"
  property must not be used)
- The only suffix allowed is "-gpios", no matter the number of
  descriptors in the property
- GPIOs can only be grouped under the same property when they serve the
  same purpose, a case that should remain exceptional (e.g. bit-banged
  data lines).
Signed-off-by: default avatarAlexandre Courbot <acourbot@nvidia.com>
Cc: Rafael J. Wysocki <rjw@rjwysocki.net>
Acked-by: default avatarArnd Bergmann <arnd@arndb.de>
Reviewed-by: default avatarMika Westerberg <mika.westerberg@linux.intel.com>
Signed-off-by: default avatarLinus Walleij <linus.walleij@linaro.org>
parent bd1dbc3b
...@@ -13,13 +13,22 @@ properties, each containing a 'gpio-list': ...@@ -13,13 +13,22 @@ properties, each containing a 'gpio-list':
gpio-specifier : Array of #gpio-cells specifying specific gpio gpio-specifier : Array of #gpio-cells specifying specific gpio
(controller specific) (controller specific)
GPIO properties should be named "[<name>-]gpios". The exact GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
meaning of each gpios property must be documented in the device tree of this GPIO for the device. While a non-existent <name> is considered valid
binding for each device. for compatibility reasons (resolving to the "gpios" property), it is not allowed
for new bindings.
For example, the following could be used to describe GPIO pins used GPIO properties can contain one or more GPIO phandles, but only in exceptional
as chip select lines; with chip selects 0, 1 and 3 populated, and chip cases should they contain more than one. If your device uses several GPIOs with
select 2 left empty: 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 { gpio1: gpio1 {
gpio-controller gpio-controller
...@@ -30,10 +39,12 @@ select 2 left empty: ...@@ -30,10 +39,12 @@ select 2 left empty:
#gpio-cells = <1>; #gpio-cells = <1>;
}; };
[...] [...]
chipsel-gpios = <&gpio1 12 0>,
<&gpio1 13 0>, enable-gpios = <&gpio2 2>;
<0>, /* holes are permitted, means no GPIO 2 */ data-gpios = <&gpio1 12 0>,
<&gpio2 2>; <&gpio1 13 0>,
<&gpio1 14 0>,
<&gpio1 15 0>;
Note that gpio-specifier length is controller dependent. In the Note that gpio-specifier length is controller dependent. In the
above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2
...@@ -42,16 +53,17 @@ only uses one. ...@@ -42,16 +53,17 @@ only uses one.
gpio-specifier may encode: bank, pin position inside the bank, gpio-specifier may encode: bank, pin position inside the bank,
whether pin is open-drain and whether pin is logically inverted. whether pin is open-drain and whether pin is logically inverted.
Exact meaning of each specifier cell is controller specific, and must Exact meaning of each specifier cell is controller specific, and must
be documented in the device tree binding for the device. 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: Example of a node using GPIOs:
node { node {
gpios = <&qe_pio_e 18 0>; enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
}; };
In this example gpio-specifier is "18 0" and encodes GPIO pin number, GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
and GPIO flags as accepted by the "qe_pio_e" gpio-controller. GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
1.1) GPIO specifier best practices 1.1) GPIO specifier best practices
---------------------------------- ----------------------------------
......
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