[PATCH v1] dt-bindings: dma: st-stm32-dmamux: Add description for dma-cell values

[PATCH v1] dt-bindings: dma: st-stm32-dmamux: Add description for dma-cell values

[Ken Sloat]

The dma-cell values for the stm32-dmamux are used to craft the DMA spec
for the actual controller. These values are currently undocumented
leaving the user to reverse engineer the driver in order to determine
their meaning. Add a basic description, while avoiding duplicating
information by pointing the user to the associated DMA docs that
describe the fields in depth.

Signed-off-by: Ken Sloat <ksloat@cornersoftsolutions.com>
---
.../bindings/dma/stm32/st,stm32-dmamux.yaml | 11 +++++++++++
1 file changed, 11 insertions(+)

diff --git a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
index f26c914a3a9a..aa2e52027ee6 100644
--- a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
+++ b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
@@ -15,6 +15,17 @@ allOf:
properties:
"#dma-cells":
const: 3
+ description: |
+ Should be set to <3> with each cell representing the following:
+ 1. The mux input number/line for the request
+ 2. Bitfield representing DMA channel configuration that is passed
+ to the real DMA controller
+ 3. Bitfield representing device dependent DMA features passed to
+ the real DMA controller
+
+ For bitfield definitions of cells 2 and 3, see the associated
+ bindings doc for the actual DMA controller the mux is connected
+ to.
compatible:
const: st,stm32h7-dmamux
-- 
2.34.1

Re: [PATCH v1] dt-bindings: dma: st-stm32-dmamux: Add description for dma-cell values

[Krzysztof Kozlowski]

On 05/12/2024 16:32, Ken Sloat wrote:
> The dma-cell values for the stm32-dmamux are used to craft the DMA spec
> for the actual controller. These values are currently undocumented
> leaving the user to reverse engineer the driver in order to determine
> their meaning. Add a basic description, while avoiding duplicating
> information by pointing the user to the associated DMA docs that
> describe the fields in depth.
> 
> Signed-off-by: Ken Sloat <ksloat@cornersoftsolutions.com>
> ---
> .../bindings/dma/stm32/st,stm32-dmamux.yaml | 11 +++++++++++
> 1 file changed, 11 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> index f26c914a3a9a..aa2e52027ee6 100644
> --- a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> +++ b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> @@ -15,6 +15,17 @@ allOf:
> properties:
> "#dma-cells":
> const: 3

Your patch is corrupted. Please use git send-email or b4 or b4+relay.

> + description: |
> + Should be set to <3> with each cell representing the following:

Drop this part, const says this.

> + 1. The mux input number/line for the request
> + 2. Bitfield representing DMA channel configuration that is passed
> + to the real DMA controller
> + 3. Bitfield representing device dependent DMA features passed to
> + the real DMA controller
> +
> + For bitfield definitions of cells 2 and 3, see the associated
> + bindings doc for the actual DMA controller the mux is connected

This does not sound right. This is the binding for DMA controller, so
you are saying "please look at itself". I suggest to drop this as well.


Best regards,
Krzysztof

Re: [PATCH v1] dt-bindings: dma: st-stm32-dmamux: Add description for dma-cell values

[Ken Sloat]

Hi Krzysztof,

Thanks for reviewing

On Thu, Dec 5, 2024 at 10:59 AM Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> On 05/12/2024 16:32, Ken Sloat wrote:
> > The dma-cell values for the stm32-dmamux are used to craft the DMA spec
> > for the actual controller. These values are currently undocumented
> > leaving the user to reverse engineer the driver in order to determine
> > their meaning. Add a basic description, while avoiding duplicating
> > information by pointing the user to the associated DMA docs that
> > describe the fields in depth.
> >
> > Signed-off-by: Ken Sloat <ksloat@cornersoftsolutions.com>
> > ---
> > .../bindings/dma/stm32/st,stm32-dmamux.yaml | 11 +++++++++++
> > 1 file changed, 11 insertions(+)
> >
> > diff --git a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> > b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> > index f26c914a3a9a..aa2e52027ee6 100644
> > --- a/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> > +++ b/Documentation/devicetree/bindings/dma/stm32/st,stm32-dmamux.yaml
> > @@ -15,6 +15,17 @@ allOf:
> > properties:
> > "#dma-cells":
> > const: 3
>
> Your patch is corrupted. Please use git send-email or b4 or b4+relay.

Sorry about that, I will do that. I will wait for any additional
comments and then re-submit.

>
> > + description: |
> > + Should be set to <3> with each cell representing the following:
>
> Drop this part, const says this.

Ok

>
> > + 1. The mux input number/line for the request
> > + 2. Bitfield representing DMA channel configuration that is passed
> > + to the real DMA controller
> > + 3. Bitfield representing device dependent DMA features passed to
> > + the real DMA controller
> > +
> > + For bitfield definitions of cells 2 and 3, see the associated
> > + bindings doc for the actual DMA controller the mux is connected
>
> This does not sound right. This is the binding for DMA controller, so
> you are saying "please look at itself". I suggest to drop this as well.
>

While logically it is the DMA controller, this doc is specifically for
the mux - the DMA controller has its own driver and binding docs in
Documentation/devicetree/bindings/dma/stm32/st,stm32-dma.yaml

I can reference st,stm32-dma.yaml directly, but I was unsure if this
mux IP was used with another DMA controller from ST on a different
SoC.

What do you suggest here?

>
> Best regards,
> Krzysztof

-- 
Sincerely,
Ken Sloat

Re: [PATCH v1] dt-bindings: dma: st-stm32-dmamux: Add description for dma-cell values

[Krzysztof Kozlowski]

On 05/12/2024 17:07, Ken Sloat wrote:
>>> + 1. The mux input number/line for the request
>>> + 2. Bitfield representing DMA channel configuration that is passed
>>> + to the real DMA controller
>>> + 3. Bitfield representing device dependent DMA features passed to
>>> + the real DMA controller
>>> +
>>> + For bitfield definitions of cells 2 and 3, see the associated
>>> + bindings doc for the actual DMA controller the mux is connected
>>
>> This does not sound right. This is the binding for DMA controller, so
>> you are saying "please look at itself". I suggest to drop this as well.
>>
> 
> While logically it is the DMA controller, this doc is specifically for
> the mux - the DMA controller has its own driver and binding docs in
> Documentation/devicetree/bindings/dma/stm32/st,stm32-dma.yaml
> 
> I can reference st,stm32-dma.yaml directly, but I was unsure if this
> mux IP was used with another DMA controller from ST on a different
> SoC.
> 
> What do you suggest here?

Thanks for explanation, I think it is fine.

Best regards,
Krzysztof

Re: [PATCH v1] dt-bindings: dma: st-stm32-dmamux: Add description for dma-cell values

[Amelie Delaunay]

On 12/5/24 17:09, Krzysztof Kozlowski wrote:
> On 05/12/2024 17:07, Ken Sloat wrote:
>>>> + 1. The mux input number/line for the request
>>>> + 2. Bitfield representing DMA channel configuration that is passed
>>>> + to the real DMA controller
>>>> + 3. Bitfield representing device dependent DMA features passed to
>>>> + the real DMA controller
>>>> +
>>>> + For bitfield definitions of cells 2 and 3, see the associated
>>>> + bindings doc for the actual DMA controller the mux is connected
>>>
>>> This does not sound right. This is the binding for DMA controller, so
>>> you are saying "please look at itself". I suggest to drop this as well.
>>>
>>
>> While logically it is the DMA controller, this doc is specifically for
>> the mux - the DMA controller has its own driver and binding docs in
>> Documentation/devicetree/bindings/dma/stm32/st,stm32-dma.yaml
>>
>> I can reference st,stm32-dma.yaml directly, but I was unsure if this
>> mux IP was used with another DMA controller from ST on a different
>> SoC.
>>
>> What do you suggest here?
> 
> Thanks for explanation, I think it is fine.
> 
> Best regards,
> Krzysztof

This description was lost when STM32 DMAMUX binding txt file was 
converted to yaml:
0b7c446fa9f7 ("dt-bindings: dma: Convert stm32 DMAMUX bindings to 
json-schema")

-- #dma-cells:	Should be set to <3>.
-		First parameter is request line number.
-		Second is DMA channel configuration
-		Third is Fifo threshold
-		For more details about the three cells, please see
-		stm32-dma.txt documentation binding file


stm32-dmamux exclusively muxes stm32-dma channels. It is not used with 
other ST DMA controllers (STM32 MDMA, STM32 DMA3).

So it is fine to refer to st,stm32-dma.yaml.

Regards,
Amelie

Re: [PATCH v1] dt-bindings: dma: st-stm32-dmamux: Add description for dma-cell values

[Ken Sloat]

Hi Amelie,

Thanks for reviewing

On Thu, Dec 5, 2024 at 1:06 PM Amelie Delaunay
<amelie.delaunay@foss.st.com> wrote:
>
>
> On 12/5/24 17:09, Krzysztof Kozlowski wrote:
> > On 05/12/2024 17:07, Ken Sloat wrote:
> >>>> + 1. The mux input number/line for the request
> >>>> + 2. Bitfield representing DMA channel configuration that is passed
> >>>> + to the real DMA controller
> >>>> + 3. Bitfield representing device dependent DMA features passed to
> >>>> + the real DMA controller
> >>>> +
> >>>> + For bitfield definitions of cells 2 and 3, see the associated
> >>>> + bindings doc for the actual DMA controller the mux is connected
> >>>
> >>> This does not sound right. This is the binding for DMA controller, so
> >>> you are saying "please look at itself". I suggest to drop this as well.
> >>>
> >>
> >> While logically it is the DMA controller, this doc is specifically for
> >> the mux - the DMA controller has its own driver and binding docs in
> >> Documentation/devicetree/bindings/dma/stm32/st,stm32-dma.yaml
> >>
> >> I can reference st,stm32-dma.yaml directly, but I was unsure if this
> >> mux IP was used with another DMA controller from ST on a different
> >> SoC.
> >>
> >> What do you suggest here?
> >
> > Thanks for explanation, I think it is fine.
> >
> > Best regards,
> > Krzysztof
>
> This description was lost when STM32 DMAMUX binding txt file was
> converted to yaml:
> 0b7c446fa9f7 ("dt-bindings: dma: Convert stm32 DMAMUX bindings to
> json-schema")
>
> -- #dma-cells:  Should be set to <3>.
> -               First parameter is request line number.
> -               Second is DMA channel configuration
> -               Third is Fifo threshold

Thanks for the info, this aligns with what I have

> -               For more details about the three cells, please see
> -               stm32-dma.txt documentation binding file
>
>
> stm32-dmamux exclusively muxes stm32-dma channels. It is not used with
> other ST DMA controllers (STM32 MDMA, STM32 DMA3).
>
> So it is fine to refer to st,stm32-dma.yaml.

Ok, I can add that on v2

>
> Regards,
> Amelie

-- 
Sincerely,
Ken Sloat