diff mbox

[v5,3/4] documentation: dts: Add the device tree binding for APM X-Gene v1 PCIe MSI device tree node

Message ID cfdb95a38689836bac693df6edb8c09829ea61cd.1429586144.git.dhdang@apm.com (mailing list archive)
State New, archived
Headers show

Commit Message

Duc Dang April 21, 2015, 4:04 a.m. UTC
The driver for this binding is under 'drivers/pci/host/pci-xgene-msi.c'

Signed-off-by: Duc Dang <dhdang@apm.com>
Signed-off-by: Tanmay Inamdar <tinamdar@apm.com>
---
 .../devicetree/bindings/pci/xgene-pci-msi.txt      | 63 ++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/pci/xgene-pci-msi.txt

Comments

Mark Rutland April 21, 2015, 3:42 p.m. UTC | #1
On Tue, Apr 21, 2015 at 05:04:23AM +0100, Duc Dang wrote:
> The driver for this binding is under 'drivers/pci/host/pci-xgene-msi.c'

Please provide a bit of description of what this device is, and please
place the binding patch _before_ the driver and DTS patches.

> Signed-off-by: Duc Dang <dhdang@apm.com>
> Signed-off-by: Tanmay Inamdar <tinamdar@apm.com>
> ---
>  .../devicetree/bindings/pci/xgene-pci-msi.txt      | 63 ++++++++++++++++++++++
>  1 file changed, 63 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
> 
> diff --git a/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt b/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
> new file mode 100644
> index 0000000..0ffdcb3
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
> @@ -0,0 +1,63 @@
> +* AppliedMicro X-Gene PCIe MSI interface
> +
> +Required properties:
> +
> +- compatible: should contain "apm,xgene1-msi" to identify the core.

What does the core have to do with the MSI controller?

> +- msi-controller: indicates that this is X-Gene1 PCIe MSI controller node
> +- reg: A list of physical base address and length for each set of controller
> +       registers.

How many? Which ones? In which order? Do you need reg-names?

> +- interrupts: A list of interrupt outputs of the controller.

How many? Which ones? In which order? Do you need interrupt-names?

You need to define these for *this particular binding*, in order for
them to actually define the contract. An abstract definition is
completely useless for writing or parsing a DT, and as such this
document is just noise.

Please think about the purpose of this document, and write something
appropriate.

[...]

> +		interrupts = <  0x0 0x10 0x4
> +				0x0 0x11 0x4
> +				0x0 0x12 0x4
> +				0x0 0x13 0x4
> +				0x0 0x14 0x4
> +				0x0 0x15 0x4
> +				0x0 0x16 0x4
> +				0x0 0x17 0x4
> +				0x0 0x18 0x4
> +				0x0 0x19 0x4
> +				0x0 0x1a 0x4
> +				0x0 0x1b 0x4
> +				0x0 0x1c 0x4
> +				0x0 0x1d 0x4
> +				0x0 0x1e 0x4
> +				0x0 0x1f 0x4>;

Nit: please bracket list entries individually.

Mark.
Duc Dang April 21, 2015, 5:37 p.m. UTC | #2
On Tue, Apr 21, 2015 at 8:42 AM, Mark Rutland <mark.rutland@arm.com> wrote:
>
> On Tue, Apr 21, 2015 at 05:04:23AM +0100, Duc Dang wrote:
> > The driver for this binding is under 'drivers/pci/host/pci-xgene-msi.c'
>
> Please provide a bit of description of what this device is, and please
> place the binding patch _before_ the driver and DTS patches.

I will add in next version of the patch.
>
>
> > Signed-off-by: Duc Dang <dhdang@apm.com>
> > Signed-off-by: Tanmay Inamdar <tinamdar@apm.com>
> > ---
> >  .../devicetree/bindings/pci/xgene-pci-msi.txt      | 63 ++++++++++++++++++++++
> >  1 file changed, 63 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
> >
> > diff --git a/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt b/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
> > new file mode 100644
> > index 0000000..0ffdcb3
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
> > @@ -0,0 +1,63 @@
> > +* AppliedMicro X-Gene PCIe MSI interface
> > +
> > +Required properties:
> > +
> > +- compatible: should contain "apm,xgene1-msi" to identify the core.
>
> What does the core have to do with the MSI controller?

'core' here is the MSI controller block. I will use different word to
avoid confusion with CPU core.
>
> > +- msi-controller: indicates that this is X-Gene1 PCIe MSI controller node
> > +- reg: A list of physical base address and length for each set of controller
> > +       registers.
>
> How many? Which ones? In which order? Do you need reg-names?

I will add these details in next version of the patch.
>
> > +- interrupts: A list of interrupt outputs of the controller.

I will add these details in next version of the patch.
>
> How many? Which ones? In which order? Do you need interrupt-names?

I will add these details in next version of the patch.
>
> You need to define these for *this particular binding*, in order for
> them to actually define the contract. An abstract definition is
> completely useless for writing or parsing a DT, and as such this
> document is just noise.
>
> Please think about the purpose of this document, and write something
> appropriate.
>
> [...]
>
> > +             interrupts = <  0x0 0x10 0x4
> > +                             0x0 0x11 0x4
> > +                             0x0 0x12 0x4
> > +                             0x0 0x13 0x4
> > +                             0x0 0x14 0x4
> > +                             0x0 0x15 0x4
> > +                             0x0 0x16 0x4
> > +                             0x0 0x17 0x4
> > +                             0x0 0x18 0x4
> > +                             0x0 0x19 0x4
> > +                             0x0 0x1a 0x4
> > +                             0x0 0x1b 0x4
> > +                             0x0 0x1c 0x4
> > +                             0x0 0x1d 0x4
> > +                             0x0 0x1e 0x4
> > +                             0x0 0x1f 0x4>;
>
> Nit: please bracket list entries individually.

Thanks for your comment, I will address them on next version of the patch.

>
> Mark.

Regards,
Duc Dang.
diff mbox

Patch

diff --git a/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt b/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
new file mode 100644
index 0000000..0ffdcb3
--- /dev/null
+++ b/Documentation/devicetree/bindings/pci/xgene-pci-msi.txt
@@ -0,0 +1,63 @@ 
+* AppliedMicro X-Gene PCIe MSI interface
+
+Required properties:
+
+- compatible: should contain "apm,xgene1-msi" to identify the core.
+- msi-controller: indicates that this is X-Gene1 PCIe MSI controller node
+- reg: A list of physical base address and length for each set of controller
+       registers.
+- interrupts: A list of interrupt outputs of the controller.
+
+Each PCIe node needs to have property msi-parent that points to msi controller node
+
+Examples:
+
+SoC DTSI:
+
+	+ MSI node:
+	msi@79000000 {
+		compatible = "apm,xgene1-msi";
+		msi-controller;
+		reg = <0x00 0x79000000 0x0 0x900000>;
+		interrupts = <  0x0 0x10 0x4
+				0x0 0x11 0x4
+				0x0 0x12 0x4
+				0x0 0x13 0x4
+				0x0 0x14 0x4
+				0x0 0x15 0x4
+				0x0 0x16 0x4
+				0x0 0x17 0x4
+				0x0 0x18 0x4
+				0x0 0x19 0x4
+				0x0 0x1a 0x4
+				0x0 0x1b 0x4
+				0x0 0x1c 0x4
+				0x0 0x1d 0x4
+				0x0 0x1e 0x4
+				0x0 0x1f 0x4>;
+	};
+
+	+ PCIe controller node with msi-parent property pointing to MSI node:
+	pcie0: pcie@1f2b0000 {
+		status = "disabled";
+		device_type = "pci";
+		compatible = "apm,xgene-storm-pcie", "apm,xgene-pcie";
+		#interrupt-cells = <1>;
+		#size-cells = <2>;
+		#address-cells = <3>;
+		reg = < 0x00 0x1f2b0000 0x0 0x00010000   /* Controller registers */
+			0xe0 0xd0000000 0x0 0x00040000>; /* PCI config space */
+		reg-names = "csr", "cfg";
+		ranges = <0x01000000 0x00 0x00000000 0xe0 0x10000000 0x00 0x00010000   /* io */
+			  0x02000000 0x00 0x80000000 0xe1 0x80000000 0x00 0x80000000>; /* mem */
+		dma-ranges = <0x42000000 0x80 0x00000000 0x80 0x00000000 0x00 0x80000000
+			      0x42000000 0x00 0x00000000 0x00 0x00000000 0x80 0x00000000>;
+		interrupt-map-mask = <0x0 0x0 0x0 0x7>;
+		interrupt-map = <0x0 0x0 0x0 0x1 &gic 0x0 0xc2 0x1
+				 0x0 0x0 0x0 0x2 &gic 0x0 0xc3 0x1
+				 0x0 0x0 0x0 0x3 &gic 0x0 0xc4 0x1
+				 0x0 0x0 0x0 0x4 &gic 0x0 0xc5 0x1>;
+		dma-coherent;
+		clocks = <&pcie0clk 0>;
+		msi-parent= <&msi>;
+	};