Documentation/devicetree/bindings/gpio/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
   7 title: NVIDIA Tegra GPIO Controller (Tegra186 and later)
   8
   9 maintainers:
  10   - Thierry Reding <thierry.reding@gmail.com>
  11   - Jon Hunter <jonathanh@nvidia.com>
  12
  13 description: |
  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
  79 properties:
  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
 146 allOf:
 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
 175 required:
 176   - compatible
 177   - reg
 178   - reg-names
 179   - interrupts
 180
 181 additionalProperties: false
 182
 183 examples:
 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     };