Add devicetree binding documentation for MIPS Coherence Manager.

Signed-off-by: Jiaxun Yang <jiaxun.yang@flygoat.com>
---
 .../devicetree/bindings/mips/mips-cm.yaml          | 37 ++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/Documentation/devicetree/bindings/mips/mips-cm.yaml b/Documentation/devicetree/bindings/mips/mips-cm.yaml
new file mode 100644
index 000000000000..b92b008d7758
--- /dev/null
+++ b/Documentation/devicetree/bindings/mips/mips-cm.yaml
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mips/mips-cm.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: MIPS Coherence Manager
+
+description: |
+  Defines a location of the MIPS Coherence Manager registers.
+
+maintainers:
+  - Jiaxun Yang <jiaxun.yang@flygoat.com>
+
+properties:
+  compatible:
+    const: mti,mips-cm
+
+  reg:
+    description: |
+      Base address and size of an unoccupied memory region, which will be
+      used to map the MIPS CM registers block.
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+
+additionalProperties: false
+
+examples:
+  - |
+    cm@1fbf8000 {
+      compatible = "mti,mips-cm";
+      reg = <0x1bde8000 0x8000>;
+    };
+...

-- 
2.34.1

On Tue, May 07, 2024 at 10:01:52AM +0100, Jiaxun Yang wrote:
> Add devicetree binding documentation for MIPS Coherence Manager.
> 
> Signed-off-by: Jiaxun Yang <jiaxun.yang@flygoat.com>
> ---
>  .../devicetree/bindings/mips/mips-cm.yaml          | 37 ++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/mips/mips-cm.yaml b/Documentation/devicetree/bindings/mips/mips-cm.yaml
> new file mode 100644
> index 000000000000..b92b008d7758
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mips/mips-cm.yaml

Filename matching the compatible please.

> @@ -0,0 +1,37 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mips/mips-cm.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: MIPS Coherence Manager
> +
> +description: |
> +  Defines a location of the MIPS Coherence Manager registers.
> +
> +maintainers:
> +  - Jiaxun Yang <jiaxun.yang@flygoat.com>
> +
> +properties:
> +  compatible:
> +    const: mti,mips-cm

Is it actually only available on mips? Google seems to report there
being Coherence Managers on their RISC-V offerings too.

> +  reg:
> +    description: |

The | isn't needed, there's no formatting to preserve.

> +      Base address and size of an unoccupied memory region, which will be
> +      used to map the MIPS CM registers block.

This sounds like it should actually be a memory-region that references
some reserved memory, not a reg, given the description. I think the
commit message here is lacking any information about what the intentions
are for this binding.

> +    maxItems: 1
> +
> +required:
> +  - compatible
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    cm@1fbf8000 {

And a generic node name here please. I actually don't quite know what to
suggest though, but "coherency-manager" would likely be better than
"cm".

Thanks,
Conor.

> +      compatible = "mti,mips-cm";
> +      reg = <0x1bde8000 0x8000>;
> +    };
> +...
> 
> -- 
> 2.34.1
> 

在2024年5月7日五月 下午5:50，Conor Dooley写道：
> On Tue, May 07, 2024 at 10:01:52AM +0100, Jiaxun Yang wrote:
>> Add devicetree binding documentation for MIPS Coherence Manager.
>> 
>> Signed-off-by: Jiaxun Yang <jiaxun.yang@flygoat.com>
>> ---
>>  .../devicetree/bindings/mips/mips-cm.yaml          | 37 ++++++++++++++++++++++
>>  1 file changed, 37 insertions(+)
>> 
>> diff --git a/Documentation/devicetree/bindings/mips/mips-cm.yaml b/Documentation/devicetree/bindings/mips/mips-cm.yaml
>> new file mode 100644
>> index 000000000000..b92b008d7758
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mips/mips-cm.yaml
Hi Cornor,

Thanks for your comments.

>
> Filename matching the compatible please.
Ok.

>
>> @@ -0,0 +1,37 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/mips/mips-cm.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: MIPS Coherence Manager
>> +
>> +description: |
>> +  Defines a location of the MIPS Coherence Manager registers.
>> +
>> +maintainers:
>> +  - Jiaxun Yang <jiaxun.yang@flygoat.com>
>> +
>> +properties:
>> +  compatible:
>> +    const: mti,mips-cm
>
> Is it actually only available on mips? Google seems to report there
> being Coherence Managers on their RISC-V offerings too.

I think for MIPS's RISC-V system, it is only used by SBI and transparent
to kernel, so it won't present in DT. 

Register fields for RISC-V system is totally different with MIPS one, and
there is no driver to be reused. In MIPS system CM code is highly coupled
with arch code, so for RISC-V if we want to expose it to kernel we'll need
a new set of driver and a new binding.

>
>> +  reg:
>> +    description: |
>
> The | isn't needed, there's no formatting to preserve.
Ok.

>
>> +      Base address and size of an unoccupied memory region, which will be
>> +      used to map the MIPS CM registers block.
>
> This sounds like it should actually be a memory-region that references
> some reserved memory, not a reg, given the description. I think the
> commit message here is lacking any information about what the intentions
> are for this binding.
So it's actually a register block that can be remapped to anywhere in
MMIO address space. DeviceTree usually passes firmware's mapping location
to kernel.

There are some other similar bindings like mti,mips-cdmm and mti,mips-cpc,
I just copied phraseology from them, should I try to explain it more here?

>
>> +    maxItems: 1
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    cm@1fbf8000 {
>
> And a generic node name here please. I actually don't quite know what to
> suggest though, but "coherency-manager" would likely be better than
> "cm".
Ok

Thanks!
- Jiaxun
>
> Thanks,
> Conor.
>
>> +      compatible = "mti,mips-cm";
>> +      reg = <0x1bde8000 0x8000>;
>> +    };
>> +...
>> 
>> -- 
>> 2.34.1
>> 
>
> 附件:
> * signature.asc

-- 
- Jiaxun

On Tue, May 07, 2024 at 07:16:25PM +0100, Jiaxun Yang wrote:
> 
> 
> 在2024年5月7日五月 下午5:50，Conor Dooley写道：
> > On Tue, May 07, 2024 at 10:01:52AM +0100, Jiaxun Yang wrote:
> >> Add devicetree binding documentation for MIPS Coherence Manager.
> >> 
> >> Signed-off-by: Jiaxun Yang <jiaxun.yang@flygoat.com>
> >> ---
> >>  .../devicetree/bindings/mips/mips-cm.yaml          | 37 ++++++++++++++++++++++
> >>  1 file changed, 37 insertions(+)
> >> 
> >> diff --git a/Documentation/devicetree/bindings/mips/mips-cm.yaml b/Documentation/devicetree/bindings/mips/mips-cm.yaml
> >> new file mode 100644
> >> index 000000000000..b92b008d7758
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/mips/mips-cm.yaml
> Hi Cornor,
> 
> Thanks for your comments.
> 
> >
> > Filename matching the compatible please.
> Ok.
> 
> >
> >> @@ -0,0 +1,37 @@
> >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> +%YAML 1.2
> >> +---
> >> +$id: http://devicetree.org/schemas/mips/mips-cm.yaml#
> >> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> +
> >> +title: MIPS Coherence Manager
> >> +
> >> +description: |
> >> +  Defines a location of the MIPS Coherence Manager registers.
> >> +
> >> +maintainers:
> >> +  - Jiaxun Yang <jiaxun.yang@flygoat.com>
> >> +
> >> +properties:
> >> +  compatible:
> >> +    const: mti,mips-cm
> >
> > Is it actually only available on mips? Google seems to report there
> > being Coherence Managers on their RISC-V offerings too.
> 
> I think for MIPS's RISC-V system, it is only used by SBI and transparent
> to kernel, so it won't present in DT. 

Devicetree isn't just for Linux, things that only the SBI implementation
cares about should also be documented in bindings - or at least I try to
get them to be, where I have enough sway to have it happen..

> Register fields for RISC-V system is totally different with MIPS one, and
> there is no driver to be reused. In MIPS system CM code is highly coupled
> with arch code, so for RISC-V if we want to expose it to kernel we'll need
> a new set of driver and a new binding.

Right, that's a reasonable reason (lol) for having it be declared as
mips-specific.

> >> +  reg:
> >> +    description: |
> >
> > The | isn't needed, there's no formatting to preserve.
> Ok.
> 
> >
> >> +      Base address and size of an unoccupied memory region, which will be
> >> +      used to map the MIPS CM registers block.
> >
> > This sounds like it should actually be a memory-region that references
> > some reserved memory, not a reg, given the description. I think the
> > commit message here is lacking any information about what the intentions
> > are for this binding.
> So it's actually a register block that can be remapped to anywhere in
> MMIO address space. DeviceTree usually passes firmware's mapping location
> to kernel.
> 
> There are some other similar bindings like mti,mips-cdmm and mti,mips-cpc,
> I just copied phraseology from them, should I try to explain it more here?

The description that you've given here is of something that sounded
awfully like mapping into a location in DDR etc, is it actually being
mapped into a non-memory address?

Thanks,
Conor.

在 2024/5/8 18:01, Conor Dooley 写道:
[...]
>> So it's actually a register block that can be remapped to anywhere in
>> MMIO address space. DeviceTree usually passes firmware's mapping location
>> to kernel.
>>
>> There are some other similar bindings like mti,mips-cdmm and mti,mips-cpc,
>> I just copied phraseology from them, should I try to explain it more here?
> The description that you've given here is of something that sounded
> awfully like mapping into a location in DDR etc, is it actually being
> mapped into a non-memory address?
It is an overlay being realized at CPU core level so it can be mapped at any
where, but the firmware convention is to map it to a "non-memory address".

Thanks
- Jiaxun
>
> Thanks,
> Conor.

On Wed, May 08, 2024 at 09:28:27PM +0100, Jiaxun Yang wrote:
> 
> 
> 在 2024/5/8 18:01, Conor Dooley 写道:
> [...]
> > > So it's actually a register block that can be remapped to anywhere in
> > > MMIO address space. DeviceTree usually passes firmware's mapping location
> > > to kernel.
> > > 
> > > There are some other similar bindings like mti,mips-cdmm and mti,mips-cpc,
> > > I just copied phraseology from them, should I try to explain it more here?
> > The description that you've given here is of something that sounded
> > awfully like mapping into a location in DDR etc, is it actually being
> > mapped into a non-memory address?
> It is an overlay being realized at CPU core level so it can be mapped at any
> where, but the firmware convention is to map it to a "non-memory address".

In that case, a description that even eejits like my can understand
sounds like all you need to understand :)

Thanks,
Conor.