nvidia,tegra186-gpio.yaml

  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      - nvidia,tegra256-gpio
 89
 90  reg-names:
 91    items:
 92      - const: security
 93      - const: gpio
 94    minItems: 1
 95
 96  reg:
 97    items:
 98      - description: Security configuration registers.
 99      - description: |
100          GPIO control registers. This may cover either:
101
102            a) The single physical alias that this OS should use.
103            b) All physical aliases that exist in the controller. This is
104               appropriate when the OS is responsible for managing assignment
105               of the physical aliases.
106    minItems: 1
107
108  interrupts:
109    description: The interrupt outputs from the HW block, one per set of
110      ports, in the order the HW manual describes them. The number of entries
111      required varies depending on compatible value.
112
113  gpio-controller: true
114
115  gpio-ranges:
116    maxItems: 1
117
118  "#gpio-cells":
119    description: |
120      Indicates how many cells are used in a consumer's GPIO specifier. In the
121      specifier:
122
123        - The first cell is the pin number.
124          See <dt-bindings/gpio/tegra186-gpio.h>.
125        - The second cell contains flags:
126          - Bit 0 specifies polarity
127            - 0: Active-high (normal).
128            - 1: Active-low (inverted).
129    const: 2
130
131  interrupt-controller: true
132
133  "#interrupt-cells":
134    description: |
135      Indicates how many cells are used in a consumer's interrupt specifier.
136      In the specifier:
137
138        - The first cell is the GPIO number.
139          See <dt-bindings/gpio/tegra186-gpio.h>.
140        - The second cell is contains flags:
141          - Bits [3:0] indicate trigger type and level:
142            - 1: Low-to-high edge triggered.
143            - 2: High-to-low edge triggered.
144            - 4: Active high level-sensitive.
145            - 8: Active low level-sensitive.
146
147            Valid combinations are 1, 2, 3, 4, 8.
148    const: 2
149
150allOf:
151  - if:
152      properties:
153        compatible:
154          contains:
155            enum:
156              - nvidia,tegra186-gpio
157              - nvidia,tegra194-gpio
158              - nvidia,tegra234-gpio
159              - nvidia,tegra256-gpio
160    then:
161      properties:
162        interrupts:
163          minItems: 6
164          maxItems: 48
165
166  - if:
167      properties:
168        compatible:
169          contains:
170            enum:
171              - nvidia,tegra186-gpio-aon
172              - nvidia,tegra194-gpio-aon
173              - nvidia,tegra234-gpio-aon
174    then:
175      properties:
176        interrupts:
177          minItems: 1
178          maxItems: 4
179
180required:
181  - compatible
182  - reg
183  - reg-names
184  - interrupts
185
186additionalProperties: false
187
188examples:
189  - |
190    #include <dt-bindings/interrupt-controller/irq.h>
191
192    gpio@2200000 {
193        compatible = "nvidia,tegra186-gpio";
194        reg-names = "security", "gpio";
195        reg = <0x2200000 0x10000>,
196              <0x2210000 0x10000>;
197        interrupts = <0  47 IRQ_TYPE_LEVEL_HIGH>,
198                     <0  50 IRQ_TYPE_LEVEL_HIGH>,
199                     <0  53 IRQ_TYPE_LEVEL_HIGH>,
200                     <0  56 IRQ_TYPE_LEVEL_HIGH>,
201                     <0  59 IRQ_TYPE_LEVEL_HIGH>,
202                     <0 180 IRQ_TYPE_LEVEL_HIGH>;
203        gpio-controller;
204        #gpio-cells = <2>;
205        interrupt-controller;
206        #interrupt-cells = <2>;
207    };
208
209    gpio@c2f0000 {
210        compatible = "nvidia,tegra186-gpio-aon";
211        reg-names = "security", "gpio";
212        reg = <0xc2f0000 0x1000>,
213              <0xc2f1000 0x1000>;
214        interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>;
215        gpio-controller;
216        #gpio-cells = <2>;
217        interrupt-controller;
218        #interrupt-cells = <2>;
219    };