1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/gpio/nvidia,tegra186-gpio.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: NVIDIA Tegra GPIO Controller (Tegra186 and later)
8
9maintainers:
10  - Thierry Reding <thierry.reding@gmail.com>
11  - Jon Hunter <jonathanh@nvidia.com>
12
13description: |
14  Tegra186 contains two GPIO controllers; a main controller and an "AON"
15  controller. This binding document applies to both controllers. The register
16  layouts for the controllers share many similarities, but also some
17  significant differences. Hence, this document describes closely related but
18  different bindings and compatible values.
19
20  The Tegra186 GPIO controller allows software to set the IO direction of,
21  and read/write the value of, numerous GPIO signals. Routing of GPIO signals
22  to package balls is under the control of a separate pin controller hardware
23  block. Two major sets of registers exist:
24
25    a) Security registers, which allow configuration of allowed access to the
26       GPIO register set. These registers exist in a single contiguous block
27       of physical address space. The size of this block, and the security
28       features available, varies between the different GPIO controllers.
29
30       Access to this set of registers is not necessary in all circumstances.
31       Code that wishes to configure access to the GPIO registers needs access
32       to these registers to do so. Code which simply wishes to read or write
33       GPIO data does not need access to these registers.
34
35    b) GPIO registers, which allow manipulation of the GPIO signals. In some
36       GPIO controllers, these registers are exposed via multiple "physical
37       aliases" in address space, each of which access the same underlying
38       state. See the hardware documentation for rationale. Any particular
39       GPIO client is expected to access just one of these physical aliases.
40
41    Tegra HW documentation describes a unified naming convention for all GPIOs
42    implemented by the SoC. Each GPIO is assigned to a port, and a port may
43    control a number of GPIOs. Thus, each GPIO is named according to an
44    alphabetical port name and an integer GPIO name within the port. For
45    example, GPIO_PA0, GPIO_PN6, or GPIO_PCC3.
46
47    The number of ports implemented by each GPIO controller varies. The number
48    of implemented GPIOs within each port varies. GPIO registers within a
49    controller are grouped and laid out according to the port they affect.
50
51    The mapping from port name to the GPIO controller that implements that
52    port, and the mapping from port name to register offset within a
53    controller, are both extremely non-linear. The header file
54    <dt-bindings/gpio/tegra186-gpio.h> describes the port-level mapping. In
55    that file, the naming convention for ports matches the HW documentation.
56    The values chosen for the names are alphabetically sorted within a
57    particular controller. Drivers need to map between the DT GPIO IDs and HW
58    register offsets using a lookup table.
59
60    Each GPIO controller can generate a number of interrupt signals. Each
61    signal represents the aggregate status for all GPIOs within a set of
62    ports. Thus, the number of interrupt signals generated by a controller
63    varies as a rough function of the number of ports it implements. Note
64    that the HW documentation refers to both the overall controller HW
65    module and the sets-of-ports as "controllers".
66
67    Each GPIO controller in fact generates multiple interrupts signals for
68    each set of ports. Each GPIO may be configured to feed into a specific
69    one of the interrupt signals generated by a set-of-ports. The intent is
70    for each generated signal to be routed to a different CPU, thus allowing
71    different CPUs to each handle subsets of the interrupts within a port.
72    The status of each of these per-port-set signals is reported via a
73    separate register. Thus, a driver needs to know which status register to
74    observe. This binding currently defines no configuration mechanism for
75    this. By default, drivers should use register
76    GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
77    define a property to configure this.
78
79properties:
80  compatible:
81    enum:
82      - nvidia,tegra186-gpio
83      - nvidia,tegra186-gpio-aon
84      - nvidia,tegra194-gpio
85      - nvidia,tegra194-gpio-aon
86      - nvidia,tegra234-gpio
87      - nvidia,tegra234-gpio-aon
88
89  reg-names:
90    items:
91      - const: security
92      - const: gpio
93    minItems: 1
94
95  reg:
96    items:
97      - description: Security configuration registers.
98      - description: |
99          GPIO control registers. This may cover either:
100
101            a) The single physical alias that this OS should use.
102            b) All physical aliases that exist in the controller. This is
103               appropriate when the OS is responsible for managing assignment
104               of the physical aliases.
105    minItems: 1
106
107  interrupts:
108    description: The interrupt outputs from the HW block, one per set of
109      ports, in the order the HW manual describes them. The number of entries
110      required varies depending on compatible value.
111
112  gpio-controller: true
113
114  "#gpio-cells":
115    description: |
116      Indicates how many cells are used in a consumer's GPIO specifier. In the
117      specifier:
118
119        - The first cell is the pin number.
120          See <dt-bindings/gpio/tegra186-gpio.h>.
121        - The second cell contains flags:
122          - Bit 0 specifies polarity
123            - 0: Active-high (normal).
124            - 1: Active-low (inverted).
125    const: 2
126
127  interrupt-controller: true
128
129  "#interrupt-cells":
130    description: |
131      Indicates how many cells are used in a consumer's interrupt specifier.
132      In the specifier:
133
134        - The first cell is the GPIO number.
135          See <dt-bindings/gpio/tegra186-gpio.h>.
136        - The second cell is contains flags:
137          - Bits [3:0] indicate trigger type and level:
138            - 1: Low-to-high edge triggered.
139            - 2: High-to-low edge triggered.
140            - 4: Active high level-sensitive.
141            - 8: Active low level-sensitive.
142
143            Valid combinations are 1, 2, 3, 4, 8.
144    const: 2
145
146allOf:
147  - if:
148      properties:
149        compatible:
150          contains:
151            enum:
152              - nvidia,tegra186-gpio
153              - nvidia,tegra194-gpio
154              - nvidia,tegra234-gpio
155    then:
156      properties:
157        interrupts:
158          minItems: 6
159          maxItems: 48
160
161  - if:
162      properties:
163        compatible:
164          contains:
165            enum:
166              - nvidia,tegra186-gpio-aon
167              - nvidia,tegra194-gpio-aon
168              - nvidia,tegra234-gpio-aon
169    then:
170      properties:
171        interrupts:
172          minItems: 1
173          maxItems: 4
174
175required:
176  - compatible
177  - reg
178  - reg-names
179  - interrupts
180
181additionalProperties: false
182
183examples:
184  - |
185    #include <dt-bindings/interrupt-controller/irq.h>
186
187    gpio@2200000 {
188        compatible = "nvidia,tegra186-gpio";
189        reg-names = "security", "gpio";
190        reg = <0x2200000 0x10000>,
191              <0x2210000 0x10000>;
192        interrupts = <0  47 IRQ_TYPE_LEVEL_HIGH>,
193                     <0  50 IRQ_TYPE_LEVEL_HIGH>,
194                     <0  53 IRQ_TYPE_LEVEL_HIGH>,
195                     <0  56 IRQ_TYPE_LEVEL_HIGH>,
196                     <0  59 IRQ_TYPE_LEVEL_HIGH>,
197                     <0 180 IRQ_TYPE_LEVEL_HIGH>;
198        gpio-controller;
199        #gpio-cells = <2>;
200        interrupt-controller;
201        #interrupt-cells = <2>;
202    };
203
204    gpio@c2f0000 {
205        compatible = "nvidia,tegra186-gpio-aon";
206        reg-names = "security", "gpio";
207        reg = <0xc2f0000 0x1000>,
208              <0xc2f1000 0x1000>;
209        interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>;
210        gpio-controller;
211        #gpio-cells = <2>;
212        interrupt-controller;
213        #interrupt-cells = <2>;
214    };
215