OpenE2K
/
linux
6
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

gpio: document polarity flag best practices 

Document what we (Laurent and I, following a mailing list dicussion)
believe are best practices for the polarity flag in a GPIO specifier.

While touching the doc, I made a few minor editing changes to other
areas.

Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Stephen Warren <swarren@nvidia.com>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
This commit is contained in:
Stephen Warren 2014-02-19 11:43:26 -07:00 committed by Linus Walleij
parent 3bde4d26f9
commit 51e8afc1c4
1 changed files with 52 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
Documentation/devicetree/bindings/gpio/gpio.txt
View File

@ -13,11 +13,11 @@ properties, each containing a 'gpio-list':
gpio-specifier : Array of #gpio-cells specifying specific gpio
(controller specific)
GPIO properties should be named "[<name>-]gpios". Exact
GPIO properties should be named "[<name>-]gpios". The 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
For example, the following could be used to describe GPIO pins used
as chip select lines; with chip selects 0, 1 and 3 populated, and chip
select 2 left empty:
@ -44,35 +44,79 @@ 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:
Example of a 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.
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 both an empty "gpio-controller"
property, and have #gpio-cells contain the size of the gpio-specifier.
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 {
#gpio-cells = <2>;
compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
reg = <0x1400 0x18>;
gpio-controller;
#gpio-cells = <2>;
};
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-cells = <2>;
};
2.1) gpio- and pin-controller interaction