[PATCH] dt-bindings: interrupt-controller: Convert fsl,mpic-msi to YAML

[PATCH] dt-bindings: interrupt-controller: Convert fsl,mpic-msi to YAML

[J. Neuschäfer via B4 Relay]

From: "J. Neuschäfer" <j.ne@posteo.net>

As part of a larger effort to bring various PowerPC-related bindings
into the YAML world, this patch converts msi-pic.txt to YAML and moves
it into the bindings/interrupt-controller/ directory. The conversion may
necessarily be a bit hard to read because the binding is quite verbose.

Signed-off-by: J. Neuschäfer <j.ne@posteo.net>
---
 .../interrupt-controller/fsl,mpic-msi.yaml         | 141 +++++++++++++++++++++
 .../devicetree/bindings/powerpc/fsl/msi-pic.txt    | 111 ----------------
 2 files changed, 141 insertions(+), 111 deletions(-)

diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..99a98864bd10c5e5b67112c0149fe123b51ca26f
--- /dev/null
+++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/interrupt-controller/fsl,mpic-msi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Freescale MSI interrupt controller
+
+description:
+  The Freescale hypervisor and msi-address-64
+  -------------------------------------------
+
+  Normally, PCI devices have access to all of CCSR via an ATMU mapping.  The
+  Freescale MSI driver calculates the address of MSIIR (in the MSI register
+  block) and sets that address as the MSI message address.
+
+  In a virtualized environment, the hypervisor may need to create an IOMMU
+  mapping for MSIIR.  The Freescale ePAPR hypervisor has this requirement
+  because of hardware limitations of the Peripheral Access Management Unit
+  (PAMU), which is currently the only IOMMU that the hypervisor supports.
+  The ATMU is programmed with the guest physical address, and the PAMU
+  intercepts transactions and reroutes them to the true physical address.
+
+  In the PAMU, each PCI controller is given only one primary window.  The
+  PAMU restricts DMA operations so that they can only occur within a window.
+  Because PCI devices must be able to DMA to memory, the primary window must
+  be used to cover all of the guest's memory space.
+
+  PAMU primary windows can be divided into 256 subwindows, and each
+  subwindow can have its own address mapping ("guest physical" to "true
+  physical").  However, each subwindow has to have the same alignment, which
+  means they cannot be located at just any address.  Because of these
+  restrictions, it is usually impossible to create a 4KB subwindow that
+  covers MSIIR where it's normally located.
+
+  Therefore, the hypervisor has to create a subwindow inside the same
+  primary window used for memory, but mapped to the MSIR block (where MSIIR
+  lives).  The first subwindow after the end of guest memory is used for
+  this.  The address specified in the msi-address-64 property is the PCI
+  address of MSIIR.  The hypervisor configures the PAMU to map that address to
+  the true physical address of MSIIR.
+
+maintainers:
+  - J. Neuschäfer <j.ne@posteo.net>
+
+properties:
+  compatible:
+    oneOf:
+      - enum:
+          - fsl,mpic-msi
+          - fsl,mpic-msi-v4.3
+          - fsl,ipic-msi
+          - fsl,vmpic-msi
+          - fsl,vmpic-msi-v4.3
+      - items:
+          - enum:
+              - fsl,mpc8572-msi
+              - fsl,mpc8610-msi
+              - fsl,mpc8641-msi
+          - const: fsl,mpic-msi
+    description:
+      compatible list, may contain one or two entries The first is
+      "fsl,CHIP-msi", where CHIP is the processor(mpc8610, mpc8572, etc.) and
+      the second is "fsl,mpic-msi" or "fsl,ipic-msi" or "fsl,mpic-msi-v4.3"
+      depending on the parent type and version. If mpic version is 4.3, the
+      number of MSI registers is increased to 16, MSIIR1 is provided to access
+      these 16 registers, and compatible "fsl,mpic-msi-v4.3" should be used.
+      The first entry is optional; the second entry is required.
+
+  reg:
+    minItems: 1
+    items:
+      - description: Address and length of the shared message interrupt
+          register set
+      - description: Address of aliased MSIIR or MSIIR1 register for platforms
+          that have such an alias. If using MSIIR1, the second region must be
+          added because different MSI group has different MSIIR1 offset.
+
+  interrupts:
+    minItems: 1
+    maxItems: 16
+    description:
+      Each one of the interrupts here is one entry per 32 MSIs, and routed to
+      the host interrupt controller. The interrupts should be set as edge
+      sensitive. If msi-available-ranges is present, only the interrupts that
+      correspond to available ranges shall be present.
+
+  msi-available-ranges:
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    items:
+      items:
+        - description: First MSI interrupt in this range
+        - description: Number of MSI interrupts in this range
+    description:
+      Use <start count> style section to define which MSI interrupt can be used
+      in the 256 msi interrupts. This property is optional, without this, all
+      the MSI interrupts can be used.  Each available range must begin and end
+      on a multiple of 32 (i.e.  no splitting an individual MSI register or the
+      associated PIC interrupt).  MPIC v4.3 does not support this property
+      because the 32 interrupts of an individual register are not continuous
+      when using MSIIR1.
+
+  msi-address-64:
+    $ref: /schemas/types.yaml#/definitions/uint64
+    description:
+      64-bit PCI address of the MSIIR register. The MSIIR register is used for
+      MSI messaging.  The address of MSIIR in PCI address space is the MSI
+      message address.
+
+      This property may be used in virtualized environments where the hypervisor
+      has created an alternate mapping for the MSIR block.  See the top-level
+      description for an explanation.
+
+required:
+  - compatible
+  - reg
+  - interrupts
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    msi@41600 {
+            compatible = "fsl,mpc8610-msi", "fsl,mpic-msi";
+            reg = <0x41600 0x80>;
+            msi-available-ranges = <0 0x100>;
+            interrupts = <0xe0 0>, <0xe1 0>, <0xe2 0>, <0xe3 0>,
+                         <0xe4 0>, <0xe5 0>, <0xe6 0>, <0xe7 0>;
+    };
+
+  - |
+    msi@41600 {
+            compatible = "fsl,mpic-msi-v4.3";
+            reg = <0x41600 0x200 0x44148 4>;
+            interrupts = <0xe0 0 0 0>, <0xe1 0 0 0>, <0xe2 0 0 0>, <0xe3 0 0 0>,
+                         <0xe4 0 0 0>, <0xe5 0 0 0>, <0xe6 0 0 0>, <0xe7 0 0 0>,
+                         <0x100 0 0 0>, <0x101 0 0 0>, <0x102 0 0 0>, <0x103 0 0 0>,
+                         <0x104 0 0 0>, <0x105 0 0 0>, <0x106 0 0 0>, <0x107 0 0 0>;
+    };
+
+...
diff --git a/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt b/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt
deleted file mode 100644
index f8d2b7fe06d695971d48ba21ab67e5b72a212fe9..0000000000000000000000000000000000000000
--- a/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt
+++ /dev/null
@@ -1,111 +0,0 @@
-* Freescale MSI interrupt controller
-
-Required properties:
-- compatible : compatible list, may contain one or two entries
-  The first is "fsl,CHIP-msi", where CHIP is the processor(mpc8610, mpc8572,
-  etc.) and the second is "fsl,mpic-msi" or "fsl,ipic-msi" or
-  "fsl,mpic-msi-v4.3" depending on the parent type and version. If mpic
-  version is 4.3, the number of MSI registers is increased to 16, MSIIR1 is
-  provided to access these 16 registers, and compatible "fsl,mpic-msi-v4.3"
-  should be used. The first entry is optional; the second entry is
-  required.
-
-- reg : It may contain one or two regions. The first region should contain
-  the address and the length of the shared message interrupt register set.
-  The second region should contain the address of aliased MSIIR or MSIIR1
-  register for platforms that have such an alias, if using MSIIR1, the second
-  region must be added because different MSI group has different MSIIR1 offset.
-
-- interrupts : each one of the interrupts here is one entry per 32 MSIs,
-  and routed to the host interrupt controller. the interrupts should
-  be set as edge sensitive.  If msi-available-ranges is present, only
-  the interrupts that correspond to available ranges shall be present.
-
-Optional properties:
-- msi-available-ranges: use <start count> style section to define which
-  msi interrupt can be used in the 256 msi interrupts. This property is
-  optional, without this, all the MSI interrupts can be used.
-  Each available range must begin and end on a multiple of 32 (i.e.
-  no splitting an individual MSI register or the associated PIC interrupt).
-  MPIC v4.3 does not support this property because the 32 interrupts of an
-  individual register are not continuous when using MSIIR1.
-
-- msi-address-64: 64-bit PCI address of the MSIIR register. The MSIIR register
-  is used for MSI messaging.  The address of MSIIR in PCI address space is
-  the MSI message address.
-
-  This property may be used in virtualized environments where the hypervisor
-  has created an alternate mapping for the MSIR block.  See below for an
-  explanation.
-
-
-Example:
-	msi@41600 {
-		compatible = "fsl,mpc8610-msi", "fsl,mpic-msi";
-		reg = <0x41600 0x80>;
-		msi-available-ranges = <0 0x100>;
-		interrupts = <
-			0xe0 0
-			0xe1 0
-			0xe2 0
-			0xe3 0
-			0xe4 0
-			0xe5 0
-			0xe6 0
-			0xe7 0>;
-		interrupt-parent = <&mpic>;
-	};
-
-	msi@41600 {
-		compatible = "fsl,mpic-msi-v4.3";
-		reg = <0x41600 0x200 0x44148 4>;
-		interrupts = <
-			0xe0 0 0 0
-			0xe1 0 0 0
-			0xe2 0 0 0
-			0xe3 0 0 0
-			0xe4 0 0 0
-			0xe5 0 0 0
-			0xe6 0 0 0
-			0xe7 0 0 0
-			0x100 0 0 0
-			0x101 0 0 0
-			0x102 0 0 0
-			0x103 0 0 0
-			0x104 0 0 0
-			0x105 0 0 0
-			0x106 0 0 0
-			0x107 0 0 0>;
-	};
-
-The Freescale hypervisor and msi-address-64
--------------------------------------------
-Normally, PCI devices have access to all of CCSR via an ATMU mapping.  The
-Freescale MSI driver calculates the address of MSIIR (in the MSI register
-block) and sets that address as the MSI message address.
-
-In a virtualized environment, the hypervisor may need to create an IOMMU
-mapping for MSIIR.  The Freescale ePAPR hypervisor has this requirement
-because of hardware limitations of the Peripheral Access Management Unit
-(PAMU), which is currently the only IOMMU that the hypervisor supports.
-The ATMU is programmed with the guest physical address, and the PAMU
-intercepts transactions and reroutes them to the true physical address.
-
-In the PAMU, each PCI controller is given only one primary window.  The
-PAMU restricts DMA operations so that they can only occur within a window.
-Because PCI devices must be able to DMA to memory, the primary window must
-be used to cover all of the guest's memory space.
-
-PAMU primary windows can be divided into 256 subwindows, and each
-subwindow can have its own address mapping ("guest physical" to "true
-physical").  However, each subwindow has to have the same alignment, which
-means they cannot be located at just any address.  Because of these
-restrictions, it is usually impossible to create a 4KB subwindow that
-covers MSIIR where it's normally located.
-
-Therefore, the hypervisor has to create a subwindow inside the same
-primary window used for memory, but mapped to the MSIR block (where MSIIR
-lives).  The first subwindow after the end of guest memory is used for
-this.  The address specified in the msi-address-64 property is the PCI
-address of MSIIR.  The hypervisor configures the PAMU to map that address to
-the true physical address of MSIIR.

---
base-commit: 2014c95afecee3e76ca4a56956a936e23283f05b
change-id: 20250226-msipic-yaml-76e3f00bf5ee

Best regards,
-- 
J. Neuschäfer <j.ne@posteo.net>

Re: [PATCH] dt-bindings: interrupt-controller: Convert fsl,mpic-msi to YAML

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 13563 bytes --]

On Thu, Apr 03, 2025 at 07:38:00PM +0200, J. Neuschäfer via B4 Relay wrote:
> From: "J. Neuschäfer" <j.ne@posteo.net>
> 
> As part of a larger effort to bring various PowerPC-related bindings
> into the YAML world, this patch converts msi-pic.txt to YAML and moves
> it into the bindings/interrupt-controller/ directory. The conversion may
> necessarily be a bit hard to read because the binding is quite verbose.
> 
> Signed-off-by: J. Neuschäfer <j.ne@posteo.net>
> ---
>  .../interrupt-controller/fsl,mpic-msi.yaml         | 141 +++++++++++++++++++++
>  .../devicetree/bindings/powerpc/fsl/msi-pic.txt    | 111 ----------------
>  2 files changed, 141 insertions(+), 111 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
> new file mode 100644
> index 0000000000000000000000000000000000000000..99a98864bd10c5e5b67112c0149fe123b51ca26f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
> @@ -0,0 +1,141 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/interrupt-controller/fsl,mpic-msi.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Freescale MSI interrupt controller
> +
> +description:

I think you want some sort of chomping operator here to preserve
formatting.

> +  The Freescale hypervisor and msi-address-64
> +  -------------------------------------------
> +
> +  Normally, PCI devices have access to all of CCSR via an ATMU mapping.  The
> +  Freescale MSI driver calculates the address of MSIIR (in the MSI register
> +  block) and sets that address as the MSI message address.
> +
> +  In a virtualized environment, the hypervisor may need to create an IOMMU
> +  mapping for MSIIR.  The Freescale ePAPR hypervisor has this requirement
> +  because of hardware limitations of the Peripheral Access Management Unit
> +  (PAMU), which is currently the only IOMMU that the hypervisor supports.
> +  The ATMU is programmed with the guest physical address, and the PAMU
> +  intercepts transactions and reroutes them to the true physical address.
> +
> +  In the PAMU, each PCI controller is given only one primary window.  The
> +  PAMU restricts DMA operations so that they can only occur within a window.
> +  Because PCI devices must be able to DMA to memory, the primary window must
> +  be used to cover all of the guest's memory space.
> +
> +  PAMU primary windows can be divided into 256 subwindows, and each
> +  subwindow can have its own address mapping ("guest physical" to "true
> +  physical").  However, each subwindow has to have the same alignment, which
> +  means they cannot be located at just any address.  Because of these
> +  restrictions, it is usually impossible to create a 4KB subwindow that
> +  covers MSIIR where it's normally located.
> +
> +  Therefore, the hypervisor has to create a subwindow inside the same
> +  primary window used for memory, but mapped to the MSIR block (where MSIIR
> +  lives).  The first subwindow after the end of guest memory is used for
> +  this.  The address specified in the msi-address-64 property is the PCI
> +  address of MSIIR.  The hypervisor configures the PAMU to map that address to
> +  the true physical address of MSIIR.
> +
> +maintainers:
> +  - J. Neuschäfer <j.ne@posteo.net>
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - enum:
> +          - fsl,mpic-msi
> +          - fsl,mpic-msi-v4.3
> +          - fsl,ipic-msi
> +          - fsl,vmpic-msi
> +          - fsl,vmpic-msi-v4.3
> +      - items:
> +          - enum:
> +              - fsl,mpc8572-msi
> +              - fsl,mpc8610-msi
> +              - fsl,mpc8641-msi
> +          - const: fsl,mpic-msi
> +    description:

> +      compatible list, may contain one or two entries The first is
> +      "fsl,CHIP-msi", where CHIP is the processor(mpc8610, mpc8572, etc.) and
> +      the second is "fsl,mpic-msi" or "fsl,ipic-msi" or "fsl,mpic-msi-v4.3"
> +      depending on the parent type and version. 

I think this just dupes the compatible list and should be dropped.


> If mpic version is 4.3, the
> +      number of MSI registers is increased to 16, MSIIR1 is provided to access
> +      these 16 registers, and compatible "fsl,mpic-msi-v4.3" should be used.

This part is kinda stating the obvious I /think/ but might not be for
odd reason?

> +      The first entry is optional; the second entry is required.

I think this part is confusing and should be dropped.

> +
> +  reg:
> +    minItems: 1
> +    items:
> +      - description: Address and length of the shared message interrupt
> +          register set

> +      - description: Address of aliased MSIIR or MSIIR1 register for platforms
> +          that have such an alias. If using MSIIR1, the second region must be
> +          added because different MSI group has different MSIIR1 offset.

This part is based on platform, so should it not have an if/then/else
below restricting it to the correct platforms?

> +
> +  interrupts:
> +    minItems: 1
> +    maxItems: 16
> +    description:
> +      Each one of the interrupts here is one entry per 32 MSIs, and routed to
> +      the host interrupt controller. The interrupts should be set as edge
> +      sensitive. If msi-available-ranges is present, only the interrupts that
> +      correspond to available ranges shall be present.
> +
> +  msi-available-ranges:
> +    $ref: /schemas/types.yaml#/definitions/uint32-matrix
> +    items:
> +      items:
> +        - description: First MSI interrupt in this range
> +        - description: Number of MSI interrupts in this range
> +    description:

> +      Use <start count> style section to define which MSI interrupt can be used
> +      in the 256 msi interrupts.

I think this dupes information in the items list in a more confusing
manner.

> This property is optional, without this, all
> +      the MSI interrupts can be used.  Each available range must begin and end
> +      on a multiple of 32 (i.e.  no splitting an individual MSI register or the
> +      associated PIC interrupt).

> MPIC v4.3 does not support this property
> +      because the 32 interrupts of an individual register are not continuous
> +      when using MSIIR1.

Sounds like another if/then/else should restrict this too.
Rest seems fine :)

Cheers,
Conor.

> +
> +  msi-address-64:
> +    $ref: /schemas/types.yaml#/definitions/uint64
> +    description:
> +      64-bit PCI address of the MSIIR register. The MSIIR register is used for
> +      MSI messaging.  The address of MSIIR in PCI address space is the MSI
> +      message address.
> +
> +      This property may be used in virtualized environments where the hypervisor
> +      has created an alternate mapping for the MSIR block.  See the top-level
> +      description for an explanation.
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    msi@41600 {
> +            compatible = "fsl,mpc8610-msi", "fsl,mpic-msi";
> +            reg = <0x41600 0x80>;
> +            msi-available-ranges = <0 0x100>;
> +            interrupts = <0xe0 0>, <0xe1 0>, <0xe2 0>, <0xe3 0>,
> +                         <0xe4 0>, <0xe5 0>, <0xe6 0>, <0xe7 0>;
> +    };
> +
> +  - |
> +    msi@41600 {
> +            compatible = "fsl,mpic-msi-v4.3";
> +            reg = <0x41600 0x200 0x44148 4>;
> +            interrupts = <0xe0 0 0 0>, <0xe1 0 0 0>, <0xe2 0 0 0>, <0xe3 0 0 0>,
> +                         <0xe4 0 0 0>, <0xe5 0 0 0>, <0xe6 0 0 0>, <0xe7 0 0 0>,
> +                         <0x100 0 0 0>, <0x101 0 0 0>, <0x102 0 0 0>, <0x103 0 0 0>,
> +                         <0x104 0 0 0>, <0x105 0 0 0>, <0x106 0 0 0>, <0x107 0 0 0>;
> +    };
> +
> +...
> diff --git a/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt b/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt
> deleted file mode 100644
> index f8d2b7fe06d695971d48ba21ab67e5b72a212fe9..0000000000000000000000000000000000000000
> --- a/Documentation/devicetree/bindings/powerpc/fsl/msi-pic.txt
> +++ /dev/null
> @@ -1,111 +0,0 @@
> -* Freescale MSI interrupt controller
> -
> -Required properties:
> -- compatible : compatible list, may contain one or two entries
> -  The first is "fsl,CHIP-msi", where CHIP is the processor(mpc8610, mpc8572,
> -  etc.) and the second is "fsl,mpic-msi" or "fsl,ipic-msi" or
> -  "fsl,mpic-msi-v4.3" depending on the parent type and version. If mpic
> -  version is 4.3, the number of MSI registers is increased to 16, MSIIR1 is
> -  provided to access these 16 registers, and compatible "fsl,mpic-msi-v4.3"
> -  should be used. The first entry is optional; the second entry is
> -  required.
> -
> -- reg : It may contain one or two regions. The first region should contain
> -  the address and the length of the shared message interrupt register set.
> -  The second region should contain the address of aliased MSIIR or MSIIR1
> -  register for platforms that have such an alias, if using MSIIR1, the second
> -  region must be added because different MSI group has different MSIIR1 offset.
> -
> -- interrupts : each one of the interrupts here is one entry per 32 MSIs,
> -  and routed to the host interrupt controller. the interrupts should
> -  be set as edge sensitive.  If msi-available-ranges is present, only
> -  the interrupts that correspond to available ranges shall be present.
> -
> -Optional properties:
> -- msi-available-ranges: use <start count> style section to define which
> -  msi interrupt can be used in the 256 msi interrupts. This property is
> -  optional, without this, all the MSI interrupts can be used.
> -  Each available range must begin and end on a multiple of 32 (i.e.
> -  no splitting an individual MSI register or the associated PIC interrupt).
> -  MPIC v4.3 does not support this property because the 32 interrupts of an
> -  individual register are not continuous when using MSIIR1.
> -
> -- msi-address-64: 64-bit PCI address of the MSIIR register. The MSIIR register
> -  is used for MSI messaging.  The address of MSIIR in PCI address space is
> -  the MSI message address.
> -
> -  This property may be used in virtualized environments where the hypervisor
> -  has created an alternate mapping for the MSIR block.  See below for an
> -  explanation.
> -
> -
> -Example:
> -	msi@41600 {
> -		compatible = "fsl,mpc8610-msi", "fsl,mpic-msi";
> -		reg = <0x41600 0x80>;
> -		msi-available-ranges = <0 0x100>;
> -		interrupts = <
> -			0xe0 0
> -			0xe1 0
> -			0xe2 0
> -			0xe3 0
> -			0xe4 0
> -			0xe5 0
> -			0xe6 0
> -			0xe7 0>;
> -		interrupt-parent = <&mpic>;
> -	};
> -
> -	msi@41600 {
> -		compatible = "fsl,mpic-msi-v4.3";
> -		reg = <0x41600 0x200 0x44148 4>;
> -		interrupts = <
> -			0xe0 0 0 0
> -			0xe1 0 0 0
> -			0xe2 0 0 0
> -			0xe3 0 0 0
> -			0xe4 0 0 0
> -			0xe5 0 0 0
> -			0xe6 0 0 0
> -			0xe7 0 0 0
> -			0x100 0 0 0
> -			0x101 0 0 0
> -			0x102 0 0 0
> -			0x103 0 0 0
> -			0x104 0 0 0
> -			0x105 0 0 0
> -			0x106 0 0 0
> -			0x107 0 0 0>;
> -	};
> -
> -The Freescale hypervisor and msi-address-64
> --------------------------------------------
> -Normally, PCI devices have access to all of CCSR via an ATMU mapping.  The
> -Freescale MSI driver calculates the address of MSIIR (in the MSI register
> -block) and sets that address as the MSI message address.
> -
> -In a virtualized environment, the hypervisor may need to create an IOMMU
> -mapping for MSIIR.  The Freescale ePAPR hypervisor has this requirement
> -because of hardware limitations of the Peripheral Access Management Unit
> -(PAMU), which is currently the only IOMMU that the hypervisor supports.
> -The ATMU is programmed with the guest physical address, and the PAMU
> -intercepts transactions and reroutes them to the true physical address.
> -
> -In the PAMU, each PCI controller is given only one primary window.  The
> -PAMU restricts DMA operations so that they can only occur within a window.
> -Because PCI devices must be able to DMA to memory, the primary window must
> -be used to cover all of the guest's memory space.
> -
> -PAMU primary windows can be divided into 256 subwindows, and each
> -subwindow can have its own address mapping ("guest physical" to "true
> -physical").  However, each subwindow has to have the same alignment, which
> -means they cannot be located at just any address.  Because of these
> -restrictions, it is usually impossible to create a 4KB subwindow that
> -covers MSIIR where it's normally located.
> -
> -Therefore, the hypervisor has to create a subwindow inside the same
> -primary window used for memory, but mapped to the MSIR block (where MSIIR
> -lives).  The first subwindow after the end of guest memory is used for
> -this.  The address specified in the msi-address-64 property is the PCI
> -address of MSIIR.  The hypervisor configures the PAMU to map that address to
> -the true physical address of MSIIR.
> 
> ---
> base-commit: 2014c95afecee3e76ca4a56956a936e23283f05b
> change-id: 20250226-msipic-yaml-76e3f00bf5ee
> 
> Best regards,
> -- 
> J. Neuschäfer <j.ne@posteo.net>
> 
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] dt-bindings: interrupt-controller: Convert fsl,mpic-msi to YAML

[J. Neuschäfer]

On Fri, Apr 04, 2025 at 06:06:39PM +0100, Conor Dooley wrote:
> On Thu, Apr 03, 2025 at 07:38:00PM +0200, J. Neuschäfer via B4 Relay wrote:
> > From: "J. Neuschäfer" <j.ne@posteo.net>
> > 
> > As part of a larger effort to bring various PowerPC-related bindings
> > into the YAML world, this patch converts msi-pic.txt to YAML and moves
> > it into the bindings/interrupt-controller/ directory. The conversion may
> > necessarily be a bit hard to read because the binding is quite verbose.
> > 
> > Signed-off-by: J. Neuschäfer <j.ne@posteo.net>
> > ---
> >  .../interrupt-controller/fsl,mpic-msi.yaml         | 141 +++++++++++++++++++++
> >  .../devicetree/bindings/powerpc/fsl/msi-pic.txt    | 111 ----------------
> >  2 files changed, 141 insertions(+), 111 deletions(-)
> > 
> > diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
> > new file mode 100644
> > index 0000000000000000000000000000000000000000..99a98864bd10c5e5b67112c0149fe123b51ca26f
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,mpic-msi.yaml
> > @@ -0,0 +1,141 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/interrupt-controller/fsl,mpic-msi.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Freescale MSI interrupt controller
> > +
> > +description:
> 
> I think you want some sort of chomping operator here to preserve
> formatting.

Sounds good, will do.

> 
> > +  The Freescale hypervisor and msi-address-64
> > +  -------------------------------------------
> > +
> > +  Normally, PCI devices have access to all of CCSR via an ATMU mapping.  The
> > +  Freescale MSI driver calculates the address of MSIIR (in the MSI register
> > +  block) and sets that address as the MSI message address.
[...]
> > +properties:
> > +  compatible:
> > +    oneOf:
> > +      - enum:
> > +          - fsl,mpic-msi
> > +          - fsl,mpic-msi-v4.3
> > +          - fsl,ipic-msi
> > +          - fsl,vmpic-msi
> > +          - fsl,vmpic-msi-v4.3
> > +      - items:
> > +          - enum:
> > +              - fsl,mpc8572-msi
> > +              - fsl,mpc8610-msi
> > +              - fsl,mpc8641-msi
> > +          - const: fsl,mpic-msi
> > +    description:
> 
> > +      compatible list, may contain one or two entries The first is
> > +      "fsl,CHIP-msi", where CHIP is the processor(mpc8610, mpc8572, etc.) and
> > +      the second is "fsl,mpic-msi" or "fsl,ipic-msi" or "fsl,mpic-msi-v4.3"
> > +      depending on the parent type and version. 
> 
> I think this just dupes the compatible list and should be dropped.

Sounds good.

> 
> > If mpic version is 4.3, the
> > +      number of MSI registers is increased to 16, MSIIR1 is provided to access
> > +      these 16 registers, and compatible "fsl,mpic-msi-v4.3" should be used.
> 
> This part is kinda stating the obvious I /think/ but might not be for
> odd reason?

For part of it (using fsl,mpic-msi-v4.3 for version 4.3) yes, but the
other part, the relation between the version and the register (MSIIR vs.
MSIIR1) and number of shared interrupts (8 vs. 16) is only obvious for
readers that have read the hardware reference manuals in detail.

Since it's a difference that essentially depends on the value of
"compatible", I'll rewrite it as an "if/then/else" block in the schema.

> 
> > +      The first entry is optional; the second entry is required.
> 
> I think this part is confusing and should be dropped.

I'll drop it, since it's also redundant with the "oneOf: ..." list for
the compatible property.

> 
> > +
> > +  reg:
> > +    minItems: 1
> > +    items:
> > +      - description: Address and length of the shared message interrupt
> > +          register set
> 
> > +      - description: Address of aliased MSIIR or MSIIR1 register for platforms
> > +          that have such an alias. If using MSIIR1, the second region must be
> > +          added because different MSI group has different MSIIR1 offset.
> 
> This part is based on platform, so should it not have an if/then/else
> below restricting it to the correct platforms?

Good point, I'll do that.

> 
> > +
> > +  interrupts:
> > +    minItems: 1
> > +    maxItems: 16
> > +    description:
> > +      Each one of the interrupts here is one entry per 32 MSIs, and routed to
> > +      the host interrupt controller. The interrupts should be set as edge
> > +      sensitive. If msi-available-ranges is present, only the interrupts that
> > +      correspond to available ranges shall be present.
> > +
> > +  msi-available-ranges:
> > +    $ref: /schemas/types.yaml#/definitions/uint32-matrix
> > +    items:
> > +      items:
> > +        - description: First MSI interrupt in this range
> > +        - description: Number of MSI interrupts in this range
> > +    description:
> 
> > +      Use <start count> style section to define which MSI interrupt can be used
> > +      in the 256 msi interrupts.
> 
> I think this dupes information in the items list in a more confusing
> manner.

I'll trim it down.

> 
> > This property is optional, without this, all
> > +      the MSI interrupts can be used.  Each available range must begin and end
> > +      on a multiple of 32 (i.e.  no splitting an individual MSI register or the
> > +      associated PIC interrupt).
> 
> > MPIC v4.3 does not support this property
> > +      because the 32 interrupts of an individual register are not continuous
> > +      when using MSIIR1.
> 
> Sounds like another if/then/else should restrict this too.

I'll move it under if/else.


> Rest seems fine :)
> 
> Cheers,
> Conor.


Thank you for your review!

J. Neuschäfer