dt-bindings: soc: samsung: Add Exynos USI bindings

# 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 32>, <&cmu_peri 31>;

            clock-names = "hsi2c_pclk", "hsi2c";

            status = "disabled";

        };

    };

/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */

/*

 * Copyright (c) 2021 Linaro Ltd.

 * Author: Sam Protsenko <semen.protsenko@linaro.org>

 *

 * Device Tree bindings for Samsung Exynos USI (Universal Serial Interface).

 */

#ifndef __DT_BINDINGS_SAMSUNG_EXYNOS_USI_H

#define __DT_BINDINGS_SAMSUNG_EXYNOS_USI_H

#define USI_V2_NONE		0

#define USI_V2_UART		1

#define USI_V2_SPI		2

#define USI_V2_I2C		3

#endif /* __DT_BINDINGS_SAMSUNG_EXYNOS_USI_H */