1NVIDIA Tegra186 GPIO controllers
2
3Tegra186 contains two GPIO controllers; a main controller and an "AON"
4controller. This binding document applies to both controllers. The register
5layouts for the controllers share many similarities, but also some significant
6differences. Hence, this document describes closely related but different
7bindings and compatible values.
8
9The Tegra186 GPIO controller allows software to set the IO direction of, and
10read/write the value of, numerous GPIO signals. Routing of GPIO signals to
11package balls is under the control of a separate pin controller HW block. Two
12major sets of registers exist:
13
14a) Security registers, which allow configuration of allowed access to the GPIO
15register set. These registers exist in a single contiguous block of physical
16address space. The size of this block, and the security features available,
17varies between the different GPIO controllers.
18
19Access to this set of registers is not necessary in all circumstances. Code
20that wishes to configure access to the GPIO registers needs access to these
21registers to do so. Code which simply wishes to read or write GPIO data does not
22need access to these registers.
23
24b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO
25controllers, these registers are exposed via multiple "physical aliases" in
26address space, each of which access the same underlying state. See the hardware
27documentation for rationale. Any particular GPIO client is expected to access
28just one of these physical aliases.
29
30Tegra HW documentation describes a unified naming convention for all GPIOs
31implemented by the SoC. Each GPIO is assigned to a port, and a port may control
32a number of GPIOs. Thus, each GPIO is named according to an alphabetical port
33name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6,
34or GPIO_PCC3.
35
36The number of ports implemented by each GPIO controller varies. The number of
37implemented GPIOs within each port varies. GPIO registers within a controller
38are grouped and laid out according to the port they affect.
39
40The mapping from port name to the GPIO controller that implements that port, and
41the mapping from port name to register offset within a controller, are both
42extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h>
43describes the port-level mapping. In that file, the naming convention for ports
44matches the HW documentation. The values chosen for the names are alphabetically
45sorted within a particular controller. Drivers need to map between the DT GPIO
46IDs and HW register offsets using a lookup table.
47
48Each GPIO controller can generate a number of interrupt signals. Each signal
49represents the aggregate status for all GPIOs within a set of ports. Thus, the
50number of interrupt signals generated by a controller varies as a rough function
51of the number of ports it implements. Note that the HW documentation refers to
52both the overall controller HW module and the sets-of-ports as "controllers".
53
54Each GPIO controller in fact generates multiple interrupts signals for each set
55of ports. Each GPIO may be configured to feed into a specific one of the
56interrupt signals generated by a set-of-ports. The intent is for each generated
57signal to be routed to a different CPU, thus allowing different CPUs to each
58handle subsets of the interrupts within a port. The status of each of these
59per-port-set signals is reported via a separate register. Thus, a driver needs
60to know which status register to observe. This binding currently defines no
61configuration mechanism for this. By default, drivers should use register
62GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
63define a property to configure this.
64
65Required properties:
66- compatible
67    Array of strings.
68    One of:
69    - "nvidia,tegra186-gpio".
70    - "nvidia,tegra186-gpio-aon".
71- reg-names
72    Array of strings.
73    Contains a list of names for the register spaces described by the reg
74    property. May contain the following entries, in any order:
75    - "gpio": Mandatory. GPIO control registers. This may cover either:
76        a) The single physical alias that this OS should use.
77        b) All physical aliases that exist in the controller. This is
78           appropriate when the OS is responsible for managing assignment of
79           the physical aliases.
80    - "security": Optional. Security configuration registers.
81    Users of this binding MUST look up entries in the reg property by name,
82    using this reg-names property to do so.
83- reg
84    Array of (physical base address, length) tuples.
85    Must contain one entry per entry in the reg-names property, in a matching
86    order.
87- interrupts
88    Array of interrupt specifiers.
89    The interrupt outputs from the HW block, one per set of ports, in the
90    order the HW manual describes them. The number of entries required varies
91    depending on compatible value:
92    - "nvidia,tegra186-gpio": 6 entries.
93    - "nvidia,tegra186-gpio-aon": 1 entry.
94- gpio-controller
95    Boolean.
96    Marks the device node as a GPIO controller/provider.
97- #gpio-cells
98    Single-cell integer.
99    Must be <2>.
100    Indicates how many cells are used in a consumer's GPIO specifier.
101    In the specifier:
102    - The first cell is the pin number.
103        See <dt-bindings/gpio/tegra186-gpio.h>.
104    - The second cell contains flags:
105        - Bit 0 specifies polarity
106            - 0: Active-high (normal).
107            - 1: Active-low (inverted).
108- interrupt-controller
109    Boolean.
110    Marks the device node as an interrupt controller/provider.
111- #interrupt-cells
112    Single-cell integer.
113    Must be <2>.
114    Indicates how many cells are used in a consumer's interrupt specifier.
115    In the specifier:
116    - The first cell is the GPIO number.
117        See <dt-bindings/gpio/tegra186-gpio.h>.
118    - The second cell is contains flags:
119        - Bits [3:0] indicate trigger type and level:
120            - 1: Low-to-high edge triggered.
121            - 2: High-to-low edge triggered.
122            - 4: Active high level-sensitive.
123            - 8: Active low level-sensitive.
124            Valid combinations are 1, 2, 3, 4, 8.
125
126Example:
127
128#include <dt-bindings/interrupt-controller/irq.h>
129
130gpio@2200000 {
131	compatible = "nvidia,tegra186-gpio";
132	reg-names = "security", "gpio";
133	reg =
134		<0x0 0x2200000 0x0 0x10000>,
135		<0x0 0x2210000 0x0 0x10000>;
136	interrupts =
137		<0 47 IRQ_TYPE_LEVEL_HIGH>,
138		<0 50 IRQ_TYPE_LEVEL_HIGH>,
139		<0 53 IRQ_TYPE_LEVEL_HIGH>,
140		<0 56 IRQ_TYPE_LEVEL_HIGH>,
141		<0 59 IRQ_TYPE_LEVEL_HIGH>,
142		<0 180 IRQ_TYPE_LEVEL_HIGH>;
143	gpio-controller;
144	#gpio-cells = <2>;
145	interrupt-controller;
146	#interrupt-cells = <2>;
147};
148
149gpio@c2f0000 {
150	compatible = "nvidia,tegra186-gpio-aon";
151	reg-names = "security", "gpio";
152	reg =
153		<0x0 0xc2f0000 0x0 0x1000>,
154		<0x0 0xc2f1000 0x0 0x1000>;
155	interrupts =
156		<0 60 IRQ_TYPE_LEVEL_HIGH>;
157	gpio-controller;
158	#gpio-cells = <2>;
159	interrupt-controller;
160	#interrupt-cells = <2>;
161};
162