1# Copyright (c) 2022, TOKITA Hiroshi <tokita.hiroshi@gmail.com>
2# SPDX-License-Identifier: Apache-2.0
3
4description: |
5  GD32 DMA controller with FIFO
6
7  channel: Select channel for data transmitting
8
9  slot: Select peripheral to connect DMA
10
11  config: A 32bit mask specifying the DMA channel configuration
12    - bit 6-7:   Direction  (see dma.h)
13                 - 0x0: MEMORY to MEMORY
14                 - 0x1: MEMORY to PERIPH
15                 - 0x2: PERIPH to MEMORY
16                 - 0x3: reserved for PERIPH to PERIPH
17
18    - bit 9:     Peripheral address increase
19                 - 0x0: no address increment between transfers
20                 - 0x1: increment address between transfers
21
22    - bit 10:    Memory address increase
23                 - 0x0: no address increase between transfers
24                 - 0x1: increase address between transfers
25
26    - bit 11-12: Peripheral data width
27                 - 0x0: 8 bits
28                 - 0x1: 16 bits
29                 - 0x2: 32 bits
30                 - 0x3: reserved
31
32    - bit 13-14: Memory data width
33                 - 0x0: 8 bits
34                 - 0x1: 16 bits
35                 - 0x2: 32 bits
36                 - 0x3: reserved
37
38    - bit 15:    Peripheral Increment Offset Size
39                 - 0x0: offset size is linked to the peripheral bus width
40                 - 0x1: offset size is fixed to 4 (32-bit alignment)
41
42    - bit 16-17: Priority
43                 - 0x0: low
44                 - 0x1: medium
45                 - 0x2: high
46                 - 0x3: very high
47
48  fifo-threshold: A 32bit bitfield value specifying FIFO threshold
49    - bit 0-1:   Depth of DMA's FIFO used by burst-transfer.
50                 - 0x0: 1 word
51                 - 0x1: 2 word
52                 - 0x2: 3 word
53                 - 0x3: 4 word
54
55
56  Example of devicetree configuration
57
58  &spi0 {
59        status = "okay";
60        pinctrl-0 = <&spi0_default>;
61        pinctrl-names = "default";
62        cs-gpios = <&gpioa 4 GPIO_ACTIVE_LOW>;
63
64        dmas = <&dma1 0 3 0 0>, <&dma1 5 3 GD32_DMA_PRIORITY_HIGH 0>
65        dma-names = "rx", "tx";
66  };
67
68  "spi0" uses dma1 for transmitting and receiving in the example.
69  Each is named "rx" and "tx".
70  The first cell assigns channel 0 to receive and channel 5 to transmit.
71  The second cell is slot. Both channels select 3.
72  What the slot number '3' means depends on the DMA controller and channel.
73  See the Hardware manual.
74  The config that places on the third can take various configs.
75  But the setting used depends on each driver implementation.
76  Set the priority for the transmitting channel as HIGH, LOW(the default) for receive channel.
77  The fifo-threshold cell that places the fourth is configuring FIFO threshold.
78  The behavior of burst transfer determines by data-width in the config cell,
79  burst-length in the dma_config struct, and fifo-threshold.
80  A single burst transfer transfers [(4 * fifo-threshold)] bytes using with DMA's FIFO.
81  Where (data-width * burst-length) must be multiple numbers of burst transfer size.
82  For example, In the case of data-width is 'byte' and burst-length is 8.
83  If the fifo-threshold is a 2-word case, it runs one burst transfer to transfer 8 bytes.
84  Or the fifo-threshold is a 4-word case, runs two times burst transfer to transferring 8 bytes each
85  time.
86
87compatible: "gd,gd32-dma-v1"
88
89include: ["reset-device.yaml", "gd,gd32-dma-base.yaml"]
90
91properties:
92  "#dma-cells":
93    const: 4
94
95dma-cells:
96  - channel
97  - slot
98  - config
99  - fifo-threshold
100