On Wed, Dec 08, 2021 at 06:30:43PM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding@xxxxxxxxxx>
>
> Convert the Tegra186 GPIO controller device tree bindings from free-form
> text format to json-schema.
>
> Signed-off-by: Thierry Reding <treding@xxxxxxxxxx>
> ---
> Changes in v2:
> - replace unevaluatedProperties with additionalProperties
> - drop redundant description of standard properties
> - fix order of entries in the reg property
> - fix examples
>
> .../bindings/gpio/nvidia,tegra186-gpio.txt | 165 --------------
> .../bindings/gpio/nvidia,tegra186-gpio.yaml | 209 ++++++++++++++++++
> 2 files changed, 209 insertions(+), 165 deletions(-)
> delete mode 100644 Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt
> create mode 100644 Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml
>
> diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt
> deleted file mode 100644
> index adff16c71d21..000000000000
> --- a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.txt
> +++ /dev/null
> @@ -1,165 +0,0 @@
> -NVIDIA Tegra186 GPIO controllers
> -
> -Tegra186 contains two GPIO controllers; a main controller and an "AON"
> -controller. This binding document applies to both controllers. The register
> -layouts for the controllers share many similarities, but also some significant
> -differences. Hence, this document describes closely related but different
> -bindings and compatible values.
> -
> -The Tegra186 GPIO controller allows software to set the IO direction of, and
> -read/write the value of, numerous GPIO signals. Routing of GPIO signals to
> -package balls is under the control of a separate pin controller HW block. Two
> -major sets of registers exist:
> -
> -a) Security registers, which allow configuration of allowed access to the GPIO
> -register set. These registers exist in a single contiguous block of physical
> -address space. The size of this block, and the security features available,
> -varies between the different GPIO controllers.
> -
> -Access to this set of registers is not necessary in all circumstances. Code
> -that wishes to configure access to the GPIO registers needs access to these
> -registers to do so. Code which simply wishes to read or write GPIO data does not
> -need access to these registers.
> -
> -b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO
> -controllers, these registers are exposed via multiple "physical aliases" in
> -address space, each of which access the same underlying state. See the hardware
> -documentation for rationale. Any particular GPIO client is expected to access
> -just one of these physical aliases.
> -
> -Tegra HW documentation describes a unified naming convention for all GPIOs
> -implemented by the SoC. Each GPIO is assigned to a port, and a port may control
> -a number of GPIOs. Thus, each GPIO is named according to an alphabetical port
> -name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6,
> -or GPIO_PCC3.
> -
> -The number of ports implemented by each GPIO controller varies. The number of
> -implemented GPIOs within each port varies. GPIO registers within a controller
> -are grouped and laid out according to the port they affect.
> -
> -The mapping from port name to the GPIO controller that implements that port, and
> -the mapping from port name to register offset within a controller, are both
> -extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h>
> -describes the port-level mapping. In that file, the naming convention for ports
> -matches the HW documentation. The values chosen for the names are alphabetically
> -sorted within a particular controller. Drivers need to map between the DT GPIO
> -IDs and HW register offsets using a lookup table.
> -
> -Each GPIO controller can generate a number of interrupt signals. Each signal
> -represents the aggregate status for all GPIOs within a set of ports. Thus, the
> -number of interrupt signals generated by a controller varies as a rough function
> -of the number of ports it implements. Note that the HW documentation refers to
> -both the overall controller HW module and the sets-of-ports as "controllers".
> -
> -Each GPIO controller in fact generates multiple interrupts signals for each set
> -of ports. Each GPIO may be configured to feed into a specific one of the
> -interrupt signals generated by a set-of-ports. The intent is for each generated
> -signal to be routed to a different CPU, thus allowing different CPUs to each
> -handle subsets of the interrupts within a port. The status of each of these
> -per-port-set signals is reported via a separate register. Thus, a driver needs
> -to know which status register to observe. This binding currently defines no
> -configuration mechanism for this. By default, drivers should use register
> -GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
> -define a property to configure this.
> -
> -Required properties:
> -- compatible
> - Array of strings.
> - One of:
> - - "nvidia,tegra186-gpio".
> - - "nvidia,tegra186-gpio-aon".
> - - "nvidia,tegra194-gpio".
> - - "nvidia,tegra194-gpio-aon".
> -- reg-names
> - Array of strings.
> - Contains a list of names for the register spaces described by the reg
> - property. May contain the following entries, in any order:
> - - "gpio": Mandatory. GPIO control registers. This may cover either:
> - a) The single physical alias that this OS should use.
> - b) All physical aliases that exist in the controller. This is
> - appropriate when the OS is responsible for managing assignment of
> - the physical aliases.
> - - "security": Optional. Security configuration registers.
> - Users of this binding MUST look up entries in the reg property by name,
> - using this reg-names property to do so.
> -- reg
> - Array of (physical base address, length) tuples.
> - Must contain one entry per entry in the reg-names property, in a matching
> - order.
> -- interrupts
> - Array of interrupt specifiers.
> - The interrupt outputs from the HW block, one per set of ports, in the
> - order the HW manual describes them. The number of entries required varies
> - depending on compatible value:
> - - "nvidia,tegra186-gpio": 6 entries.
> - - "nvidia,tegra186-gpio-aon": 1 entry.
> - - "nvidia,tegra194-gpio": 6 entries.
> - - "nvidia,tegra194-gpio-aon": 1 entry.
> -- gpio-controller
> - Boolean.
> - Marks the device node as a GPIO controller/provider.
> -- #gpio-cells
> - Single-cell integer.
> - Must be <2>.
> - Indicates how many cells are used in a consumer's GPIO specifier.
> - In the specifier:
> - - The first cell is the pin number.
> - See <dt-bindings/gpio/tegra186-gpio.h>.
> - - The second cell contains flags:
> - - Bit 0 specifies polarity
> - - 0: Active-high (normal).
> - - 1: Active-low (inverted).
> -- interrupt-controller
> - Boolean.
> - Marks the device node as an interrupt controller/provider.
> -- #interrupt-cells
> - Single-cell integer.
> - Must be <2>.
> - Indicates how many cells are used in a consumer's interrupt specifier.
> - In the specifier:
> - - The first cell is the GPIO number.
> - See <dt-bindings/gpio/tegra186-gpio.h>.
> - - The second cell is contains flags:
> - - Bits [3:0] indicate trigger type and level:
> - - 1: Low-to-high edge triggered.
> - - 2: High-to-low edge triggered.
> - - 4: Active high level-sensitive.
> - - 8: Active low level-sensitive.
> - Valid combinations are 1, 2, 3, 4, 8.
> -
> -Example:
> -
> -#include <dt-bindings/interrupt-controller/irq.h>
> -
> -gpio@2200000 {
> - compatible = "nvidia,tegra186-gpio";
> - reg-names = "security", "gpio";
> - reg =
> - <0x0 0x2200000 0x0 0x10000>,
> - <0x0 0x2210000 0x0 0x10000>;
> - interrupts =
> - <0 47 IRQ_TYPE_LEVEL_HIGH>,
> - <0 50 IRQ_TYPE_LEVEL_HIGH>,
> - <0 53 IRQ_TYPE_LEVEL_HIGH>,
> - <0 56 IRQ_TYPE_LEVEL_HIGH>,
> - <0 59 IRQ_TYPE_LEVEL_HIGH>,
> - <0 180 IRQ_TYPE_LEVEL_HIGH>;
> - gpio-controller;
> - #gpio-cells = <2>;
> - interrupt-controller;
> - #interrupt-cells = <2>;
> -};
> -
> -gpio@c2f0000 {
> - compatible = "nvidia,tegra186-gpio-aon";
> - reg-names = "security", "gpio";
> - reg =
> - <0x0 0xc2f0000 0x0 0x1000>,
> - <0x0 0xc2f1000 0x0 0x1000>;
> - interrupts =
> - <0 60 IRQ_TYPE_LEVEL_HIGH>;
> - gpio-controller;
> - #gpio-cells = <2>;
> - interrupt-controller;
> - #interrupt-cells = <2>;
> -};
> diff --git a/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml
> new file mode 100644
> index 000000000000..ad4deb5959fb
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/gpio/nvidia,tegra186-gpio.yaml
> @@ -0,0 +1,209 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/gpio/nvidia,tegra186-gpio.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: NVIDIA Tegra GPIO Controller (Tegra186 and later)
> +
> +maintainers:
> + - Thierry Reding <thierry.reding@xxxxxxxxx>
> + - Jon Hunter <jonathanh@xxxxxxxxxx>
> +
> +description: |
> + Tegra186 contains two GPIO controllers; a main controller and an "AON"
> + controller. This binding document applies to both controllers. The register
> + layouts for the controllers share many similarities, but also some
> + significant differences. Hence, this document describes closely related but
> + different bindings and compatible values.
> +
> + The Tegra186 GPIO controller allows software to set the IO direction of,
> + and read/write the value of, numerous GPIO signals. Routing of GPIO signals
> + to package balls is under the control of a separate pin controller hardware
> + block. Two major sets of registers exist:
> +
> + a) Security registers, which allow configuration of allowed access to the
> + GPIO register set. These registers exist in a single contiguous block
> + of physical address space. The size of this block, and the security
> + features available, varies between the different GPIO controllers.
> +
> + Access to this set of registers is not necessary in all circumstances.
> + Code that wishes to configure access to the GPIO registers needs access
> + to these registers to do so. Code which simply wishes to read or write
> + GPIO data does not need access to these registers.
> +
> + b) GPIO registers, which allow manipulation of the GPIO signals. In some
> + GPIO controllers, these registers are exposed via multiple "physical
> + aliases" in address space, each of which access the same underlying
> + state. See the hardware documentation for rationale. Any particular
> + GPIO client is expected to access just one of these physical aliases.
> +
> + Tegra HW documentation describes a unified naming convention for all GPIOs
> + implemented by the SoC. Each GPIO is assigned to a port, and a port may
> + control a number of GPIOs. Thus, each GPIO is named according to an
> + alphabetical port name and an integer GPIO name within the port. For
> + example, GPIO_PA0, GPIO_PN6, or GPIO_PCC3.
> +
> + The number of ports implemented by each GPIO controller varies. The number
> + of implemented GPIOs within each port varies. GPIO registers within a
> + controller are grouped and laid out according to the port they affect.
> +
> + The mapping from port name to the GPIO controller that implements that
> + port, and the mapping from port name to register offset within a
> + controller, are both extremely non-linear. The header file
> + <dt-bindings/gpio/tegra186-gpio.h> describes the port-level mapping. In
> + that file, the naming convention for ports matches the HW documentation.
> + The values chosen for the names are alphabetically sorted within a
> + particular controller. Drivers need to map between the DT GPIO IDs and HW
> + register offsets using a lookup table.
> +
> + Each GPIO controller can generate a number of interrupt signals. Each
> + signal represents the aggregate status for all GPIOs within a set of
> + ports. Thus, the number of interrupt signals generated by a controller
> + varies as a rough function of the number of ports it implements. Note
> + that the HW documentation refers to both the overall controller HW
> + module and the sets-of-ports as "controllers".
> +
> + Each GPIO controller in fact generates multiple interrupts signals for
> + each set of ports. Each GPIO may be configured to feed into a specific
> + one of the interrupt signals generated by a set-of-ports. The intent is
> + for each generated signal to be routed to a different CPU, thus allowing
> + different CPUs to each handle subsets of the interrupts within a port.
> + The status of each of these per-port-set signals is reported via a
> + separate register. Thus, a driver needs to know which status register to
> + observe. This binding currently defines no configuration mechanism for
> + this. By default, drivers should use register
> + GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could
> + define a property to configure this.
> +
> +properties:
> + compatible:
> + enum:
> + - nvidia,tegra186-gpio
> + - nvidia,tegra186-gpio-aon
> + - nvidia,tegra194-gpio
> + - nvidia,tegra194-gpio-aon
> +
> + reg-names:
> + items:
> + - const: security
> + - const: gpio
> + minItems: 1
> +
> + reg:
> + items:
> + - description: Security configuration registers.
> + - description: |
> + GPIO control registers. This may cover either:
> +
> + a) The single physical alias that this OS should use.
> + b) All physical aliases that exist in the controller. This is
> + appropriate when the OS is responsible for managing assignment
> + of the physical aliases.
> + minItems: 1
> +
> + interrupts:
> + description: The interrupt outputs from the HW block, one per set of
> + ports, in the order the HW manual describes them. The number of entries
> + required varies depending on compatible value.
> +
> + gpio-controller: true
> +
> + "#gpio-cells":
> + description: |
> + Indicates how many cells are used in a consumer's GPIO specifier. In the
> + specifier:
> +
> + - The first cell is the pin number.
> + See <dt-bindings/gpio/tegra186-gpio.h>.
> + - The second cell contains flags:
> + - Bit 0 specifies polarity
> + - 0: Active-high (normal).
> + - 1: Active-low (inverted).
> + const: 2
> +
> + interrupt-controller: true
> +
> + "#interrupt-cells":
> + description: |
> + Indicates how many cells are used in a consumer's interrupt specifier.
> + In the specifier:
> +
> + - The first cell is the GPIO number.
> + See <dt-bindings/gpio/tegra186-gpio.h>.
> + - The second cell is contains flags:
> + - Bits [3:0] indicate trigger type and level:
> + - 1: Low-to-high edge triggered.
> + - 2: High-to-low edge triggered.
> + - 4: Active high level-sensitive.
> + - 8: Active low level-sensitive.
> +
> + Valid combinations are 1, 2, 3, 4, 8.
const: 2
With that,
Reviewed-by: Rob Herring <robh@xxxxxxxxxx>
