# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/soc/samsung/exynos-usi.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Samsung's Exynos USI (Universal Serial Interface) binding

maintainers:
  - Sam Protsenko <semen.protsenko@linaro.org>
  - Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>

description: |
  USI IP-core provides selectable serial protocol (UART, SPI or High-Speed I2C).
  USI shares almost all internal circuits within each protocol, so only one
  protocol can be chosen at a time. USI is modeled as a node with zero or more
  child nodes, each representing a serial sub-node device. The mode setting
  selects which particular function will be used.

  Refer to next bindings documentation for information on protocol subnodes that
  can exist under USI node:

  [1] Documentation/devicetree/bindings/serial/samsung_uart.yaml
  [2] Documentation/devicetree/bindings/i2c/i2c-exynos5.txt
  [3] Documentation/devicetree/bindings/spi/spi-samsung.txt

properties:
  $nodename:
    pattern: "^usi@[0-9a-f]+$"

  compatible:
    enum:
      - samsung,exynos850-usi   # for USIv2 (Exynos850, ExynosAutoV9)

  reg: true

  clocks: true

  clock-names: true

  ranges: true

  "#address-cells":
    const: 1

  "#size-cells":
    const: 1

  samsung,sysreg:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    description:
      Should be phandle/offset pair. The phandle to System Register syscon node
      (for the same domain where this USI controller resides) and the offset
      of SW_CONF register for this USI controller.

  samsung,mode:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      Selects USI function (which serial protocol to use). Refer to
      <include/dt-bindings/soc/samsung,exynos-usi.h> for valid USI mode values.

  samsung,clkreq-on:
    type: boolean
    description:
      Enable this property if underlying protocol requires the clock to be
      continuously provided without automatic gating. As suggested by SoC
      manual, it should be set in case of SPI/I2C slave, UART Rx and I2C
      multi-master mode. Usually this property is needed if USI mode is set
      to "UART".

      This property is optional.

patternProperties:
  # All other properties should be child nodes
  "^(serial|spi|i2c)@[0-9a-f]+$":
    type: object
    description: Child node describing underlying USI serial protocol

required:
  - compatible
  - ranges
  - "#address-cells"
  - "#size-cells"
  - samsung,sysreg
  - samsung,mode

if:
  properties:
    compatible:
      contains:
        enum:
          - samsung,exynos850-usi

then:
  properties:
    reg:
      maxItems: 1

    clocks:
      items:
        - description: Bus (APB) clock
        - description: Operating clock for UART/SPI/I2C protocol

    clock-names:
      items:
        - const: pclk
        - const: ipclk

  required:
    - reg
    - clocks
    - clock-names

else:
  properties:
    reg: false
    clocks: false
    clock-names: false
    samsung,clkreq-on: false

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/soc/samsung,exynos-usi.h>

    usi0: usi@138200c0 {
        compatible = "samsung,exynos850-usi";
        reg = <0x138200c0 0x20>;
        samsung,sysreg = <&sysreg_peri 0x1010>;
        samsung,mode = <USI_V2_UART>;
        samsung,clkreq-on; /* needed for UART mode */
        #address-cells = <1>;
        #size-cells = <1>;
        ranges;
        clocks = <&cmu_peri 32>, <&cmu_peri 31>;
        clock-names = "pclk", "ipclk";

        serial_0: serial@13820000 {
            compatible = "samsung,exynos850-uart";
            reg = <0x13820000 0xc0>;
            interrupts = <GIC_SPI 227 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&cmu_peri 32>, <&cmu_peri 31>;
            clock-names = "uart", "clk_uart_baud0";
            status = "disabled";
        };

        hsi2c_0: i2c@13820000 {
            compatible = "samsung,exynosautov9-hsi2c";
            reg = <0x13820000 0xc0>;
            interrupts = <GIC_SPI 227 IRQ_TYPE_LEVEL_HIGH>;
            #address-cells = <1>;
            #size-cells = <0>;
            clocks = <&cmu_peri 31>, <&cmu_peri 32>;
            clock-names = "hsi2c", "hsi2c_pclk";
            status = "disabled";
        };
    };