diff mbox

[1/2] dt-bindings: Document the STM32 MDMA bindings

Message ID 1489417599-31308-2-git-send-email-cedric.madianga@gmail.com (mailing list archive)
State Changes Requested
Headers show

Commit Message

M'boumba Cedric Madianga March 13, 2017, 3:06 p.m. UTC 
This patch adds documentation of device tree bindings for the STM32 MDMA
controller.

Signed-off-by: M'boumba Cedric Madianga <cedric.madianga@gmail.com>
Reviewed-by: Ludovic BARRE <ludovic.barre@st.com>
---
 .../devicetree/bindings/dma/stm32-mdma.txt         | 94 ++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/dma/stm32-mdma.txt

Comments

Rob Herring (Arm) March 20, 2017, 9:52 p.m. UTC | #1 
On Mon, Mar 13, 2017 at 04:06:38PM +0100, M'boumba Cedric Madianga wrote:
> This patch adds documentation of device tree bindings for the STM32 MDMA
> controller.
> 
> Signed-off-by: M'boumba Cedric Madianga <cedric.madianga@gmail.com>
> Reviewed-by: Ludovic BARRE <ludovic.barre@st.com>
> ---
>  .../devicetree/bindings/dma/stm32-mdma.txt         | 94 ++++++++++++++++++++++
>  1 file changed, 94 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/dma/stm32-mdma.txt
> 
> diff --git a/Documentation/devicetree/bindings/dma/stm32-mdma.txt b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
> new file mode 100644
> index 0000000..26a930c
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
> @@ -0,0 +1,94 @@
> +* STMicroelectronics STM32 MDMA controller
> +
> +The STM32 MDMA is a general-purpose direct memory access controller capable of
> +supporting 64 independent DMA channels with 256 HW requests.
> +
> +Required properties:
> +- compatible: Should be "st,stm32-mdma"

Should be more specific.

> +- reg: Should contain MDMA registers location and length. This should include
> +  all of the per-channel registers.
> +- interrupts: Should contain the MDMA interrupt.
> +- clocks: Should contain the input clock of the DMA instance.
> +- resets: Reference to a reset controller asserting the DMA controller.
> +- #dma-cells : Must be <5>. See DMA client paragraph for more details.
> +
> +Optional properties:
> +- dma-channels: Number of DMA channels supported by the controller.
> +- dma-requests: Number of DMA request signals supported by the controller.
> +- st,ahb-addr-masks: Array of u32 mask to list memory devices addressed via
> +  AHB bus.

I don't understand what this is.

> +
> +Example:

Put the 2 examples together.

> +
> +	mdma1: dma@52000000 {
> +		compatible = "st,stm32-mdma";
> +		reg = <0x52000000 0x1000>;
> +		interrupts = <122>;
> +		clocks = <&clk_dummy>;
> +		resets = <&rcc 992>;
> +		#dma-cells = <5>;
> +		dma-channels = <16>;
> +		dma-requests = <32>;
> +		st,ahb-addr-masks = <0x20000000>, <0x00000000>;
> +	};
> +
> +* DMA client
> +
> +DMA clients connected to the STM32 MDMA controller must use the format
> +described in the dma.txt file, using a six-cell specifier for each channel:
> +a phandle to the MDMA controller plus the following five integer cells:
> +
> +1. The request line number
> +2. The priority level
> +	0x00: Low
> +	0x01: Medium
> +	0x10: High
> +	0x11: Very high
> +3. A 32bit mask specifying the DMA channel configuration
> + -bit 0-1: Source increment mode
> +	0x00: Source address pointer is fixed
> +	0x10: Source address pointer is incremented after each data transfer
> +	0x11: Source address pointer is decremented after each data transfer
> + -bit 2-3: Destination increment mode
> +	0x00: Destination address pointer is fixed
> +	0x10: Destination address pointer is incremented after each data
> +	transfer
> +	0x11: Destination address pointer is decremented after each data
> +	transfer
> + -bit 8-9: Source increment offset size
> +	0x00: byte (8bit)
> +	0x01: half-word (16bit)
> +	0x10: word (32bit)
> +	0x11: double-word (64bit)
> + -bit 10-11: Destination increment offset size
> +	0x00: byte (8bit)
> +	0x01: half-word (16bit)
> +	0x10: word (32bit)
> +	0x11: double-word (64bit)
> +-bit 25-18: The number of bytes to be transferred in a single transfer
> +	(min = 1 byte, max = 128 bytes)
> +-bit 29:28: Trigger Mode
> +	0x00: Each MDMA request triggers a buffer transfer (max 128 bytes)
> +	0x01: Each MDMA request triggers a block transfer (max 64K bytes)
> +	0x10: Each MDMA request triggers a repeated block transfer
> +	0x11: Each MDMA request triggers a linked list transfer
> +4. A 32bit value specifying the register to be used to acknowledge the request
> +   if no HW ack signal is used by the MDMA client
> +5. A 32bit mask specifying the value to be written to acknowledge the request
> +   if no HW ack signal is used by the MDMA client
> +
> +Example:
> +
> +	i2c4: i2c@5c002000 {
> +		compatible = "st,stm32f7-i2c";
> +		reg = <0x5c002000 0x400>;
> +		interrupts = <GIC_SPI 95 IRQ_TYPE_NONE>,
> +			     <GIC_SPI 96 IRQ_TYPE_NONE>;
> +		clocks = <&clk_hsi>;
> +		#address-cells = <1>;
> +		#size-cells = <0>;
> +		dmas = <&mdma1 36 0x0 0x40008 0x0 0x0>,
> +		       <&mdma1 37 0x0 0x40002 0x0 0x0>;
> +		dma-names = "rx", "tx";
> +		status = "disabled";
> +	};
> -- 
> 1.9.1
> 
--
To unsubscribe from this list: send the line "unsubscribe dmaengine" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
M'boumba Cedric Madianga March 27, 2017, 10:06 a.m. UTC | #2 
Hi Rob,

2017-03-20 22:52 GMT+01:00 Rob Herring <robh@kernel.org>:
> On Mon, Mar 13, 2017 at 04:06:38PM +0100, M'boumba Cedric Madianga wrote:
>> This patch adds documentation of device tree bindings for the STM32 MDMA
>> controller.
>>
>> Signed-off-by: M'boumba Cedric Madianga <cedric.madianga@gmail.com>
>> Reviewed-by: Ludovic BARRE <ludovic.barre@st.com>
>> ---
>>  .../devicetree/bindings/dma/stm32-mdma.txt         | 94 ++++++++++++++++++++++
>>  1 file changed, 94 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/dma/stm32-mdma.txt
>>
>> diff --git a/Documentation/devicetree/bindings/dma/stm32-mdma.txt b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
>> new file mode 100644
>> index 0000000..26a930c
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
>> @@ -0,0 +1,94 @@
>> +* STMicroelectronics STM32 MDMA controller
>> +
>> +The STM32 MDMA is a general-purpose direct memory access controller capable of
>> +supporting 64 independent DMA channels with 256 HW requests.
>> +
>> +Required properties:
>> +- compatible: Should be "st,stm32-mdma"
>
> Should be more specific.

The compatible string is not specific enough ? I don't see how to specific more.

>
>> +- reg: Should contain MDMA registers location and length. This should include
>> +  all of the per-channel registers.
>> +- interrupts: Should contain the MDMA interrupt.
>> +- clocks: Should contain the input clock of the DMA instance.
>> +- resets: Reference to a reset controller asserting the DMA controller.
>> +- #dma-cells : Must be <5>. See DMA client paragraph for more details.
>> +
>> +Optional properties:
>> +- dma-channels: Number of DMA channels supported by the controller.
>> +- dma-requests: Number of DMA request signals supported by the controller.
>> +- st,ahb-addr-masks: Array of u32 mask to list memory devices addressed via
>> +  AHB bus.
>
> I don't understand what this is.

The MDMA is able to address memories and devices from AHB bus or AXI bus.
The MDMA has a little different way of working to address AHB
device/memory and AXI device/memory.
In STM32H7 platform, almost all devices are addressed by AXI bus.
But we have some memories adress by AHB bus.
So, we add these parameter to be able to handle this.

>
>> +
>> +Example:
>
> Put the 2 examples together.

OK

>
>> +
>> +     mdma1: dma@52000000 {
>> +             compatible = "st,stm32-mdma";
>> +             reg = <0x52000000 0x1000>;
>> +             interrupts = <122>;
>> +             clocks = <&clk_dummy>;
>> +             resets = <&rcc 992>;
>> +             #dma-cells = <5>;
>> +             dma-channels = <16>;
>> +             dma-requests = <32>;
>> +             st,ahb-addr-masks = <0x20000000>, <0x00000000>;
>> +     };
>> +
>> +* DMA client
>> +
>> +DMA clients connected to the STM32 MDMA controller must use the format
>> +described in the dma.txt file, using a six-cell specifier for each channel:
>> +a phandle to the MDMA controller plus the following five integer cells:
>> +
>> +1. The request line number
>> +2. The priority level
>> +     0x00: Low
>> +     0x01: Medium
>> +     0x10: High
>> +     0x11: Very high
>> +3. A 32bit mask specifying the DMA channel configuration
>> + -bit 0-1: Source increment mode
>> +     0x00: Source address pointer is fixed
>> +     0x10: Source address pointer is incremented after each data transfer
>> +     0x11: Source address pointer is decremented after each data transfer
>> + -bit 2-3: Destination increment mode
>> +     0x00: Destination address pointer is fixed
>> +     0x10: Destination address pointer is incremented after each data
>> +     transfer
>> +     0x11: Destination address pointer is decremented after each data
>> +     transfer
>> + -bit 8-9: Source increment offset size
>> +     0x00: byte (8bit)
>> +     0x01: half-word (16bit)
>> +     0x10: word (32bit)
>> +     0x11: double-word (64bit)
>> + -bit 10-11: Destination increment offset size
>> +     0x00: byte (8bit)
>> +     0x01: half-word (16bit)
>> +     0x10: word (32bit)
>> +     0x11: double-word (64bit)
>> +-bit 25-18: The number of bytes to be transferred in a single transfer
>> +     (min = 1 byte, max = 128 bytes)
>> +-bit 29:28: Trigger Mode
>> +     0x00: Each MDMA request triggers a buffer transfer (max 128 bytes)
>> +     0x01: Each MDMA request triggers a block transfer (max 64K bytes)
>> +     0x10: Each MDMA request triggers a repeated block transfer
>> +     0x11: Each MDMA request triggers a linked list transfer
>> +4. A 32bit value specifying the register to be used to acknowledge the request
>> +   if no HW ack signal is used by the MDMA client
>> +5. A 32bit mask specifying the value to be written to acknowledge the request
>> +   if no HW ack signal is used by the MDMA client
>> +
>> +Example:
>> +
>> +     i2c4: i2c@5c002000 {
>> +             compatible = "st,stm32f7-i2c";
>> +             reg = <0x5c002000 0x400>;
>> +             interrupts = <GIC_SPI 95 IRQ_TYPE_NONE>,
>> +                          <GIC_SPI 96 IRQ_TYPE_NONE>;
>> +             clocks = <&clk_hsi>;
>> +             #address-cells = <1>;
>> +             #size-cells = <0>;
>> +             dmas = <&mdma1 36 0x0 0x40008 0x0 0x0>,
>> +                    <&mdma1 37 0x0 0x40002 0x0 0x0>;
>> +             dma-names = "rx", "tx";
>> +             status = "disabled";
>> +     };
>> --
>> 1.9.1
>>
--
To unsubscribe from this list: send the line "unsubscribe dmaengine" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Rob Herring (Arm) March 28, 2017, 4:26 p.m. UTC | #3 
On Mon, Mar 27, 2017 at 5:06 AM, M'boumba Cedric Madianga
<cedric.madianga@gmail.com> wrote:
> Hi Rob,
>
> 2017-03-20 22:52 GMT+01:00 Rob Herring <robh@kernel.org>:
>> On Mon, Mar 13, 2017 at 04:06:38PM +0100, M'boumba Cedric Madianga wrote:
>>> This patch adds documentation of device tree bindings for the STM32 MDMA
>>> controller.
>>>
>>> Signed-off-by: M'boumba Cedric Madianga <cedric.madianga@gmail.com>
>>> Reviewed-by: Ludovic BARRE <ludovic.barre@st.com>
>>> ---
>>>  .../devicetree/bindings/dma/stm32-mdma.txt         | 94 ++++++++++++++++++++++
>>>  1 file changed, 94 insertions(+)
>>>  create mode 100644 Documentation/devicetree/bindings/dma/stm32-mdma.txt
>>>
>>> diff --git a/Documentation/devicetree/bindings/dma/stm32-mdma.txt b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
>>> new file mode 100644
>>> index 0000000..26a930c
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
>>> @@ -0,0 +1,94 @@
>>> +* STMicroelectronics STM32 MDMA controller
>>> +
>>> +The STM32 MDMA is a general-purpose direct memory access controller capable of
>>> +supporting 64 independent DMA channels with 256 HW requests.
>>> +
>>> +Required properties:
>>> +- compatible: Should be "st,stm32-mdma"
>>
>> Should be more specific.
>
> The compatible string is not specific enough ? I don't see how to specific more.

stm32 is not a specific SoC. Compatible strings should be specific to
an SoC (with fallback strings to whatever they are compatible with) so
you can handle SoC specific differences or errata.

>>> +- reg: Should contain MDMA registers location and length. This should include
>>> +  all of the per-channel registers.
>>> +- interrupts: Should contain the MDMA interrupt.
>>> +- clocks: Should contain the input clock of the DMA instance.
>>> +- resets: Reference to a reset controller asserting the DMA controller.
>>> +- #dma-cells : Must be <5>. See DMA client paragraph for more details.
>>> +
>>> +Optional properties:
>>> +- dma-channels: Number of DMA channels supported by the controller.
>>> +- dma-requests: Number of DMA request signals supported by the controller.
>>> +- st,ahb-addr-masks: Array of u32 mask to list memory devices addressed via
>>> +  AHB bus.
>>
>> I don't understand what this is.
>
> The MDMA is able to address memories and devices from AHB bus or AXI bus.
> The MDMA has a little different way of working to address AHB
> device/memory and AXI device/memory.
> In STM32H7 platform, almost all devices are addressed by AXI bus.
> But we have some memories adress by AHB bus.
> So, we add these parameter to be able to handle this.

I still don't understand. Is the difference in DMA addresses vs. CPU
addresses? If so, you should dma-ranges to translate these.

Rob
--
To unsubscribe from this list: send the line "unsubscribe dmaengine" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
M'boumba Cedric Madianga March 29, 2017, 8:07 a.m. UTC | #4 
Hi Rob,

> stm32 is not a specific SoC. Compatible strings should be specific to
> an SoC (with fallback strings to whatever they are compatible with) so
> you can handle SoC specific differences or errata.

Ok I see. I will add a more specific SoC description in my compatible.
Thanks.


> I still don't understand. Is the difference in DMA addresses vs. CPU
> addresses? If so, you should dma-ranges to translate these.

Not really.
In fact, the MDMA controller provides a master AXI interface for
memories like DDR/SRAM and peripheral registers access (system access
port).
It also provides a master AHB interface only for Cortex-M7 TCM memory
access (TCM access port).
So the goal of this st,ahb-addr-masks property is to list all TCM
addresses avalaible in the SoC, in order to correctly configure the
MDMA as an AHB master in that particular case.
For all other cases (other memories or peripheral registers access),
the MDMA will act as AXI master.

Hope it helps to understand.

BR,
Cedric
--
To unsubscribe from this list: send the line "unsubscribe dmaengine" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
diff mbox

Patch

diff --git a/Documentation/devicetree/bindings/dma/stm32-mdma.txt b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
new file mode 100644
index 0000000..26a930c
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/stm32-mdma.txt
@@ -0,0 +1,94 @@ 
+* STMicroelectronics STM32 MDMA controller
+
+The STM32 MDMA is a general-purpose direct memory access controller capable of
+supporting 64 independent DMA channels with 256 HW requests.
+
+Required properties:
+- compatible: Should be "st,stm32-mdma"
+- reg: Should contain MDMA registers location and length. This should include
+  all of the per-channel registers.
+- interrupts: Should contain the MDMA interrupt.
+- clocks: Should contain the input clock of the DMA instance.
+- resets: Reference to a reset controller asserting the DMA controller.
+- #dma-cells : Must be <5>. See DMA client paragraph for more details.
+
+Optional properties:
+- dma-channels: Number of DMA channels supported by the controller.
+- dma-requests: Number of DMA request signals supported by the controller.
+- st,ahb-addr-masks: Array of u32 mask to list memory devices addressed via
+  AHB bus.
+
+Example:
+
+	mdma1: dma@52000000 {
+		compatible = "st,stm32-mdma";
+		reg = <0x52000000 0x1000>;
+		interrupts = <122>;
+		clocks = <&clk_dummy>;
+		resets = <&rcc 992>;
+		#dma-cells = <5>;
+		dma-channels = <16>;
+		dma-requests = <32>;
+		st,ahb-addr-masks = <0x20000000>, <0x00000000>;
+	};
+
+* DMA client
+
+DMA clients connected to the STM32 MDMA controller must use the format
+described in the dma.txt file, using a six-cell specifier for each channel:
+a phandle to the MDMA controller plus the following five integer cells:
+
+1. The request line number
+2. The priority level
+	0x00: Low
+	0x01: Medium
+	0x10: High
+	0x11: Very high
+3. A 32bit mask specifying the DMA channel configuration
+ -bit 0-1: Source increment mode
+	0x00: Source address pointer is fixed
+	0x10: Source address pointer is incremented after each data transfer
+	0x11: Source address pointer is decremented after each data transfer
+ -bit 2-3: Destination increment mode
+	0x00: Destination address pointer is fixed
+	0x10: Destination address pointer is incremented after each data
+	transfer
+	0x11: Destination address pointer is decremented after each data
+	transfer
+ -bit 8-9: Source increment offset size
+	0x00: byte (8bit)
+	0x01: half-word (16bit)
+	0x10: word (32bit)
+	0x11: double-word (64bit)
+ -bit 10-11: Destination increment offset size
+	0x00: byte (8bit)
+	0x01: half-word (16bit)
+	0x10: word (32bit)
+	0x11: double-word (64bit)
+-bit 25-18: The number of bytes to be transferred in a single transfer
+	(min = 1 byte, max = 128 bytes)
+-bit 29:28: Trigger Mode
+	0x00: Each MDMA request triggers a buffer transfer (max 128 bytes)
+	0x01: Each MDMA request triggers a block transfer (max 64K bytes)
+	0x10: Each MDMA request triggers a repeated block transfer
+	0x11: Each MDMA request triggers a linked list transfer
+4. A 32bit value specifying the register to be used to acknowledge the request
+   if no HW ack signal is used by the MDMA client
+5. A 32bit mask specifying the value to be written to acknowledge the request
+   if no HW ack signal is used by the MDMA client
+
+Example:
+
+	i2c4: i2c@5c002000 {
+		compatible = "st,stm32f7-i2c";
+		reg = <0x5c002000 0x400>;
+		interrupts = <GIC_SPI 95 IRQ_TYPE_NONE>,
+			     <GIC_SPI 96 IRQ_TYPE_NONE>;
+		clocks = <&clk_hsi>;
+		#address-cells = <1>;
+		#size-cells = <0>;
+		dmas = <&mdma1 36 0x0 0x40008 0x0 0x0>,
+		       <&mdma1 37 0x0 0x40002 0x0 0x0>;
+		dma-names = "rx", "tx";
+		status = "disabled";
+	};