dt-bindings: dma: rework qcom,adm Documentation to yaml schema

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

%YAML 1.2

---

$id: http://devicetree.org/schemas/dma/qcom,adm.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Qualcomm ADM DMA Controller

maintainers:

  - Christian Marangi <ansuelsmth@gmail.com>

  - Bjorn Andersson <bjorn.andersson@linaro.org>

description: |

  QCOM ADM DMA controller provides DMA capabilities for

  peripheral buses such as NAND and SPI.

properties:

  compatible:

    const: qcom,adm

  reg:

    maxItems: 1

  interrupts:

    maxItems: 1

  "#dma-cells":

    const: 1

  clocks:

    items:

      - description: phandle to the core clock

      - description: phandle to the iface clock

  clock-names:

    items:

      - const: core

      - const: iface

  resets:

    items:

      - description: phandle to the clk reset

      - description: phandle to the c0 reset

      - description: phandle to the c1 reset

      - description: phandle to the c2 reset

  reset-names:

    items:

      - const: clk

      - const: c0

      - const: c1

      - const: c2

  qcom,ee:

    $ref: /schemas/types.yaml#/definitions/uint32

    description: indicates the security domain identifier used in the secure world.

    minimum: 0

    maximum: 255

required:

  - compatible

  - reg

  - interrupts

  - "#dma-cells"

  - clocks

  - clock-names

  - resets

  - reset-names

  - qcom,ee

additionalProperties: false

examples:

  - |

    #include <dt-bindings/clock/qcom,gcc-ipq806x.h>

    #include <dt-bindings/reset/qcom,gcc-ipq806x.h>

    adm_dma: dma-controller@18300000 {

        compatible = "qcom,adm";

        reg = <0x18300000 0x100000>;

        interrupts = <0 170 0>;

        #dma-cells = <1>;

        clocks = <&gcc ADM0_CLK>,

                  <&gcc ADM0_PBUS_CLK>;

        clock-names = "core", "iface";

        resets = <&gcc ADM0_RESET>,

                  <&gcc ADM0_C0_RESET>,

                  <&gcc ADM0_C1_RESET>,

                  <&gcc ADM0_C2_RESET>;

        reset-names = "clk", "c0", "c1", "c2";

        qcom,ee = <0>;

    };

...

QCOM ADM DMA Controller

Required properties:

- compatible: must contain "qcom,adm" for IPQ/APQ8064 and MSM8960

- reg: Address range for DMA registers

- interrupts: Should contain one interrupt shared by all channels

- #dma-cells: must be <2>.  First cell denotes the channel number.  Second cell

  denotes CRCI (client rate control interface) flow control assignment.

- clocks: Should contain the core clock and interface clock.

- clock-names: Must contain "core" for the core clock and "iface" for the

  interface clock.

- resets: Must contain an entry for each entry in reset names.

- reset-names: Must include the following entries:

  - clk

  - c0

  - c1

  - c2

- qcom,ee: indicates the security domain identifier used in the secure world.

Example:

		adm_dma: dma@18300000 {

			compatible = "qcom,adm";

			reg = <0x18300000 0x100000>;

			interrupts = <0 170 0>;

			#dma-cells = <2>;

			clocks = <&gcc ADM0_CLK>, <&gcc ADM0_PBUS_CLK>;

			clock-names = "core", "iface";

			resets = <&gcc ADM0_RESET>,

				<&gcc ADM0_C0_RESET>,

				<&gcc ADM0_C1_RESET>,

				<&gcc ADM0_C2_RESET>;

			reset-names = "clk", "c0", "c1", "c2";

			qcom,ee = <0>;

		};

DMA clients must use the format descripted in the dma.txt file, using a three

cell specifier for each channel.

Each dmas request consists of 3 cells:

 1. phandle pointing to the DMA controller

 2. channel number

 3. CRCI assignment, if applicable.  If no CRCI flow control is required, use 0.

    The CRCI is used for flow control.  It identifies the peripheral device that

    is the source/destination for the transferred data.

Example:

	spi4: spi@1a280000 {

		spi-max-frequency = <50000000>;

		pinctrl-0 = <&spi_pins>;

		pinctrl-names = "default";

		cs-gpios = <&qcom_pinmux 20 0>;

		dmas = <&adm_dma 6 9>,

			<&adm_dma 5 10>;

		dma-names = "rx", "tx";

	};