dt-bindings: dma: Convert jz4740-dma doc to YAML

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

%YAML 1.2

---

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

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

title: Ingenic SoCs DMA Controller DT bindings

maintainers:

  - Paul Cercueil <paul@crapouillou.net>

allOf:

  - $ref: "dma-controller.yaml#"

properties:

  compatible:

    enum:

      - ingenic,jz4740-dma

      - ingenic,jz4725b-dma

      - ingenic,jz4770-dma

      - ingenic,jz4780-dma

      - ingenic,x1000-dma

      - ingenic,x1830-dma

  reg:

    items:

      - description: Channel-specific registers

      - description: System control registers

  interrupts:

    maxItems: 1

  clocks:

    maxItems: 1

  "#dma-cells":

    const: 2

    description: >

      DMA clients must use the format described in dma.txt, giving a phandle

      to the DMA controller plus the following 2 integer cells:

      - Request type: The DMA request type for transfers to/from the

        device on the allocated channel, as defined in the SoC documentation.

      - Channel: If set to 0xffffffff, any available channel will be allocated

        for the client. Otherwise, the exact channel specified will be used.

        The channel should be reserved on the DMA controller using the

        ingenic,reserved-channels property.

  ingenic,reserved-channels:

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

    description: >

      Bitmask of channels to reserve for devices that need a specific

      channel. These channels will only be assigned when explicitely

      requested by a client. The primary use for this is channels 0 and

      1, which can be configured to have special behaviour for NAND/BCH

      when using programmable firmware.

required:

  - compatible

  - reg

  - interrupts

  - clocks

examples:

  - |

    #include <dt-bindings/clock/jz4780-cgu.h>

    dma: dma-controller@13420000 {

      compatible = "ingenic,jz4780-dma";

      reg = <0x13420000 0x400>, <0x13421000 0x40>;

      interrupt-parent = <&intc>;

      interrupts = <10>;

      clocks = <&cgu JZ4780_CLK_PDMA>;

      #dma-cells = <2>;

      ingenic,reserved-channels = <0x3>;

    };

* Ingenic XBurst DMA Controller

Required properties:

- compatible: Should be one of:

  * ingenic,jz4740-dma

  * ingenic,jz4725b-dma

  * ingenic,jz4770-dma

  * ingenic,jz4780-dma

  * ingenic,x1000-dma

  * ingenic,x1830-dma

- reg: Should contain the DMA channel registers location and length, followed

  by the DMA controller registers location and length.

- interrupts: Should contain the interrupt specifier of the DMA controller.

- clocks: Should contain a clock specifier for the JZ4780/X1000/X1830 PDMA

  clock.

- #dma-cells: Must be <2>. Number of integer cells in the dmas property of

  DMA clients (see below).

Optional properties:

- ingenic,reserved-channels: Bitmask of channels to reserve for devices that

  need a specific channel. These channels will only be assigned when explicitly

  requested by a client. The primary use for this is channels 0 and 1, which

  can be configured to have special behaviour for NAND/BCH when using

  programmable firmware.

Example:

dma: dma-controller@13420000 {

	compatible = "ingenic,jz4780-dma";

	reg = <0x13420000 0x400

	       0x13421000 0x40>;

	interrupt-parent = <&intc>;

	interrupts = <10>;

	clocks = <&cgu JZ4780_CLK_PDMA>;

	#dma-cells = <2>;

	ingenic,reserved-channels = <0x3>;

};

DMA clients must use the format described in dma.txt, giving a phandle to the

DMA controller plus the following 2 integer cells:

1. Request type: The DMA request type for transfers to/from the device on

   the allocated channel, as defined in the SoC documentation.

2. Channel: If set to 0xffffffff, any available channel will be allocated for

   the client. Otherwise, the exact channel specified will be used. The channel

   should be reserved on the DMA controller using the ingenic,reserved-channels

   property.

Example:

uart0: serial@10030000 {

	...

	dmas = <&dma 0x14 0xffffffff

		&dma 0x15 0xffffffff>;

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

	...

};