dt-bindings: mips: Convert plain text file to ReST

[PATCH] dt-bindings: mips: Convert plain text file to ReST

Posted by Soumya Negi 3 years, 11 months ago

Converts .txt documentation file to ReST format(.rst).

Signed-off-by: Soumya Negi <soumya.negi97@gmail.com>
---
 .../devicetree/bindings/mips/cpu_irq.rst      | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mips/cpu_irq.rst

diff --git a/Documentation/devicetree/bindings/mips/cpu_irq.rst b/Documentation/devicetree/bindings/mips/cpu_irq.rst
new file mode 100644
index 000000000000..601cc12caa2a
--- /dev/null
+++ b/Documentation/devicetree/bindings/mips/cpu_irq.rst
@@ -0,0 +1,56 @@
+=============================
+MIPS CPU interrupt controller
+=============================
+
+On MIPS the ``mips_cpu_irq_of_init()`` helper can be used to initialize the 8 CPU
+IRQs from a devicetree file and create a ``irq_domain`` for IRQ controller.
+
+With the ``irq_domain`` in place we can describe how the 8 IRQs are wired to the
+platforms internal interrupt controller cascade.
+
+Below is an example of a platform describing the cascade inside the devicetree
+and the code used to load it inside ``arch_init_irq()``.
+
+Required properties
+-------------------
+* compatible: Should be **"mti,cpu-interrupt-controller"**
+
+Example devicetree
+------------------
+::
+
+	cpu-irq: cpu-irq {
+		#address-cells = <0>;
+
+		interrupt-controller;
+		#interrupt-cells = <1>;
+
+		compatible = "mti,cpu-interrupt-controller";
+	};
+
+	intc: intc@200 {
+		compatible = "ralink,rt2880-intc";
+		reg = <0x200 0x100>;
+
+		interrupt-controller;
+		#interrupt-cells = <1>;
+
+		interrupt-parent = <&cpu-irq>;
+		interrupts = <2>;
+	};
+
+
+Example platform ``irq.c``
+--------------------------
+::
+
+	static struct of_device_id __initdata of_irq_ids[] = {
+		{ .compatible = "mti,cpu-interrupt-controller", .data = mips_cpu_irq_of_init },
+		{ .compatible = "ralink,rt2880-intc", .data = intc_of_init },
+		{},
+	};
+
+	void __init arch_init_irq(void)
+	{
+		of_irq_init(of_irq_ids);
+	}
-- 
2.17.1

Re: [PATCH] dt-bindings: mips: Convert plain text file to ReST

Posted by Krzysztof Kozlowski 3 years, 11 months ago

On 21/05/2022 03:56, Soumya Negi wrote:
> Converts .txt documentation file to ReST format(.rst).
> 
> Signed-off-by: Soumya Negi <soumya.negi97@gmail.com>
> ---
>  .../devicetree/bindings/mips/cpu_irq.rst      | 56 +++++++++++++++++++
>  1 file changed, 56 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mips/cpu_irq.rst
> 
> diff --git a/Documentation/devicetree/bindings/mips/cpu_irq.rst b/Documentation/devicetree/bindings/mips/cpu_irq.rst
> new file mode 100644
> index 000000000000..601cc12caa2a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mips/cpu_irq.rst
> @@ -0,0 +1,56 @@
> +=============================
> +MIPS CPU interrupt controller
> +=============================
> +
> +On MIPS the ``mips_cpu_irq_of_init()`` helper can be used to initialize the 8 CPU
> +IRQs from a devicetree file and create a ``irq_domain`` for IRQ controller.

Bindings is not a place for code. No.

> +
> +With the ``irq_domain`` in place we can describe how the 8 IRQs are wired to the
> +platforms internal interrupt controller cascade.
> +
> +Below is an example of a platform describing the cascade inside the devicetree
> +and the code used to load it inside ``arch_init_irq()``.
> +
> +Required properties
> +-------------------
> +* compatible: Should be **"mti,cpu-interrupt-controller"**

If you wanted to add bindings, please use DT schema format (see
writing-schema, writing-bindings and example-schema files).


Best regards,
Krzysztof

Re: [PATCH] dt-bindings: mips: Convert plain text file to ReST

Posted by Soumya Negi 3 years, 11 months ago

On Sat, May 21, 2022 at 04:25:07PM +0200, Krzysztof Kozlowski wrote:
> On 21/05/2022 03:56, Soumya Negi wrote:
> > Converts .txt documentation file to ReST format(.rst).
> > 
> > Signed-off-by: Soumya Negi <soumya.negi97@gmail.com>
> > ---
> >  .../devicetree/bindings/mips/cpu_irq.rst      | 56 +++++++++++++++++++
> >  1 file changed, 56 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/mips/cpu_irq.rst
> > 
> > diff --git a/Documentation/devicetree/bindings/mips/cpu_irq.rst b/Documentation/devicetree/bindings/mips/cpu_irq.rst
> > new file mode 100644
> > index 000000000000..601cc12caa2a
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/mips/cpu_irq.rst
> > @@ -0,0 +1,56 @@
> > +=============================
> > +MIPS CPU interrupt controller
> > +=============================
> > +
> > +On MIPS the ``mips_cpu_irq_of_init()`` helper can be used to initialize the 8 CPU
> > +IRQs from a devicetree file and create a ``irq_domain`` for IRQ controller.
> 
> Bindings is not a place for code. No.
> 
> > +
> > +With the ``irq_domain`` in place we can describe how the 8 IRQs are wired to the
> > +platforms internal interrupt controller cascade.
> > +
> > +Below is an example of a platform describing the cascade inside the devicetree
> > +and the code used to load it inside ``arch_init_irq()``.
> > +
> > +Required properties
> > +-------------------
> > +* compatible: Should be **"mti,cpu-interrupt-controller"**
> 
> If you wanted to add bindings, please use DT schema format (see
> writing-schema, writing-bindings and example-schema files).

Hi, 
I don't want to add bindings. I want to the convert the doc file
Documentation/devicetree/bindings/mips/cpu_irq.txt to ReST file format.

I referred to this page(https://wiki.linuxfoundation.org/lkmp/lkmp_task_list) while
creating the patch. It also mentions exceptions that should be kept as plain text 
files. Does this file count as an exception?

Thanks
Soumya

Re: [PATCH] dt-bindings: mips: Convert plain text file to ReST

Posted by Krzysztof Kozlowski 3 years, 11 months ago

On 21/05/2022 22:24, Soumya Negi wrote:
> On Sat, May 21, 2022 at 04:25:07PM +0200, Krzysztof Kozlowski wrote:
>> On 21/05/2022 03:56, Soumya Negi wrote:
>>> Converts .txt documentation file to ReST format(.rst).
>>>
>>> Signed-off-by: Soumya Negi <soumya.negi97@gmail.com>
>>> ---
>>>  .../devicetree/bindings/mips/cpu_irq.rst      | 56 +++++++++++++++++++
>>>  1 file changed, 56 insertions(+)
>>>  create mode 100644 Documentation/devicetree/bindings/mips/cpu_irq.rst
>>>
>>> diff --git a/Documentation/devicetree/bindings/mips/cpu_irq.rst b/Documentation/devicetree/bindings/mips/cpu_irq.rst
>>> new file mode 100644
>>> index 000000000000..601cc12caa2a
>>> --- /dev/null
>>> +++ b/Documentation/devicetree/bindings/mips/cpu_irq.rst
>>> @@ -0,0 +1,56 @@
>>> +=============================
>>> +MIPS CPU interrupt controller
>>> +=============================
>>> +
>>> +On MIPS the ``mips_cpu_irq_of_init()`` helper can be used to initialize the 8 CPU
>>> +IRQs from a devicetree file and create a ``irq_domain`` for IRQ controller.
>>
>> Bindings is not a place for code. No.
>>
>>> +
>>> +With the ``irq_domain`` in place we can describe how the 8 IRQs are wired to the
>>> +platforms internal interrupt controller cascade.
>>> +
>>> +Below is an example of a platform describing the cascade inside the devicetree
>>> +and the code used to load it inside ``arch_init_irq()``.
>>> +
>>> +Required properties
>>> +-------------------
>>> +* compatible: Should be **"mti,cpu-interrupt-controller"**
>>
>> If you wanted to add bindings, please use DT schema format (see
>> writing-schema, writing-bindings and example-schema files).
> 
> Hi, 
> I don't want to add bindings. I want to the convert the doc file
> Documentation/devicetree/bindings/mips/cpu_irq.txt to ReST file format.
> 
> I referred to this page(https://wiki.linuxfoundation.org/lkmp/lkmp_task_list) while
> creating the patch. It also mentions exceptions that should be kept as plain text 
> files. Does this file count as an exception?


The original file you mention is a dt-bindings file, not a doc file. As
you see it is in the bindings subdirectory. All (or almost all) files in
Documentation/devicetree/bindings are bindings.

It should be stripped out of C code and converted to DT schema (and
moved to interrupt-controllers), not to ReST.

Best regards,
Krzysztof

Re: [PATCH] dt-bindings: mips: Convert plain text file to ReST

Posted by Greg KH 3 years, 11 months ago

On Fri, May 20, 2022 at 06:56:13PM -0700, Soumya Negi wrote:
> Converts .txt documentation file to ReST format(.rst).
> 
> Signed-off-by: Soumya Negi <soumya.negi97@gmail.com>
> ---
>  .../devicetree/bindings/mips/cpu_irq.rst      | 56 +++++++++++++++++++
>  1 file changed, 56 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mips/cpu_irq.rst

That did not "convert" it merely added the new file.  Where was the old
file?

And does this get added to the build somehow?

thanks,

greg k-h

Re: [PATCH] dt-bindings: mips: Convert plain text file to ReST

Posted by Soumya Negi 3 years, 11 months ago

On Sat, May 21, 2022 at 03:25:07PM +0200, Greg KH wrote:
> On Fri, May 20, 2022 at 06:56:13PM -0700, Soumya Negi wrote:
> > Converts .txt documentation file to ReST format(.rst).
> > 
> > Signed-off-by: Soumya Negi <soumya.negi97@gmail.com>
> > ---
> >  .../devicetree/bindings/mips/cpu_irq.rst      | 56 +++++++++++++++++++
> >  1 file changed, 56 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/mips/cpu_irq.rst
> 
> That did not "convert" it merely added the new file.  Where was the old
> file?

I will correct the patch. The old file is Documentation/devicetree/bindings/mips/cpu_irq.txt 

> And does this get added to the build somehow?

No, I don't think so. When building documentation using make htmldocs, the file
does not show up in the Documentation/output directory. 


Regards
Soumya