dts/bindings/dma/gd,gd32-dma-v1.yaml

# Copyright (c) 2022, TOKITA Hiroshi <tokita.hiroshi@gmail.com>
# SPDX-License-Identifier: Apache-2.0

description: |
  GD32 DMA controller with FIFO

  channel: Select channel for data transmitting

  slot: Select peripheral to connect DMA

  config: A 32bit mask specifying the DMA channel configuration
    - bit 6-7:   Direction  (see dma.h)
                 - 0x0: MEMORY to MEMORY
                 - 0x1: MEMORY to PERIPH
                 - 0x2: PERIPH to MEMORY
                 - 0x3: reserved for PERIPH to PERIPH

    - bit 9:     Peripheral address increase
                 - 0x0: no address increment between transfers
                 - 0x1: increment address between transfers

    - bit 10:    Memory address increase
                 - 0x0: no address increase between transfers
                 - 0x1: increase address between transfers

    - bit 11-12: Peripheral data width
                 - 0x0: 8 bits
                 - 0x1: 16 bits
                 - 0x2: 32 bits
                 - 0x3: reserved

    - bit 13-14: Memory data width
                 - 0x0: 8 bits
                 - 0x1: 16 bits
                 - 0x2: 32 bits
                 - 0x3: reserved

    - bit 15:    Peripheral Increment Offset Size
                 - 0x0: offset size is linked to the peripheral bus width
                 - 0x1: offset size is fixed to 4 (32-bit alignment)

    - bit 16-17: Priority
                 - 0x0: low
                 - 0x1: medium
                 - 0x2: high
                 - 0x3: very high

  fifo-threshold: A 32bit bitfield value specifying FIFO threshold
    - bit 0-1:   Depth of DMA's FIFO used by burst-transfer.
                 - 0x0: 1 word
                 - 0x1: 2 word
                 - 0x2: 3 word
                 - 0x3: 4 word


  Example of devicetree configuration

  &spi0 {
        status = "okay";
        pinctrl-0 = <&spi0_default>;
        pinctrl-names = "default";
        cs-gpios = <&gpioa 4 GPIO_ACTIVE_LOW>;

        dmas = <&dma1 0 3 0 0>, <&dma1 5 3 GD32_DMA_PRIORITY_HIGH 0>
        dma-names = "rx", "tx";
  };

  "spi0" uses dma1 for transmitting and receiving in the example.
  Each is named "rx" and "tx".
  The first cell assigns channel 0 to receive and channel 5 to transmit.
  The second cell is slot. Both channels select 3.
  What the slot number '3' means depends on the DMA controller and channel.
  See the Hardware manual.
  The config that places on the third can take various configs.
  But the setting used depends on each driver implementation.
  Set the priority for the transmitting channel as HIGH, LOW(the default) for receive channel.
  The fifo-threshold cell that places the fourth is configuring FIFO threshold.
  The behavior of burst transfer determines by data-width in the config cell,
  burst-length in the dma_config struct, and fifo-threshold.
  A single burst transfer transfers [(4 * fifo-threshold)] bytes using with DMA's FIFO.
  Where (data-width * burst-length) must be multiple numbers of burst transfer size.
  For example, In the case of data-width is 'byte' and burst-length is 8.
  If the fifo-threshold is a 2-word case, it runs one burst transfer to transfer 8 bytes.
  Or the fifo-threshold is a 4-word case, runs two times burst transfer to transferring 8 bytes each
  time.

compatible: "gd,gd32-dma-v1"

include: ["reset-device.yaml", "gd,gd32-dma-base.yaml"]

properties:
  "#dma-cells":
    const: 4

dma-cells:
  - channel
  - slot
  - config
  - fifo-threshold