From:   Sander Vanheule <sander@svanheule.net>
To:     Thomas Gleixner <tglx@linutronix.de>,
        Marc Zyngier <maz@kernel.org>,
        Rob Herring <robh+dt@kernel.org>, devicetree@vger.kernel.org
Cc:     Birger Koblitz <mail@birger-koblitz.de>,
        Bert Vermeulen <bert@biot.com>,
        John Crispin <john@phrozen.org>, linux-kernel@vger.kernel.org,
        Sander Vanheule <sander@svanheule.net>
Subject: [RFC PATCH v2 4/5] dt-bindings: interrupt-controller: realtek,rtl-intc: map output lines
Date:   Sun, 26 Dec 2021 20:59:27 +0100
Message-Id: <0a91967d40d486bb8cccd0dcf5a817df11317cf0.1640548009.git.sander@svanheule.net>
In-Reply-To: <cover.1640548009.git.sander@svanheule.net>
References: <cover.1640548009.git.sander@svanheule.net>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Amend the binding to also require a list of parent interrupts, and an
optional mask to specify which parent is mapped to which output.

Without this information, any driver would have to make an assumption on
which parent interrupt is connected to which output.

Additionally, extend (or add) the relevant descriptions to more clearly
describe the inputs and outputs of this router.

Signed-off-by: Sander Vanheule <sander@svanheule.net>
---
Since it does not properly describe the hardware, I would still really
rather get rid of "interrupt-map", even though that would mean breaking
ABI for this binding. As we've argued before [1], that is our prefered
solution, and would enable us to not carry more (hacky) code because of
a mistake with the initial submission.

Vendors don't ship independent DT blobs for devices with this hardware,
so the independent devicetree/kernel upgrades issue is really rather
theoretical here. Realtek isn't driving the development of the bindings
and associated drivers for this platform. They have their SDK and seem
to care very little about proper kernel integration.

Furthermore, there are currently no device descriptions in the kernel
using this binding. There are in OpenWrt, but OpenWrt firmware images
for this platform always contain both the kernel and the appended DTB,
so there's also no breakage to worry about.

[1] https://lore.kernel.org/all/9c169aad-3c7b-2ffb-90a2-1ca791a3f411@phrozen.org/

Differences with v1:
- Don't drop the "interrupt-map" property
- Add the "realtek,output-valid-mask" property
---
 .../realtek,rtl-intc.yaml                     | 38 ++++++++++++++++---
 1 file changed, 33 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml
index 9e76fff20323..29014673c34e 100644
--- a/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml
+++ b/Documentation/devicetree/bindings/interrupt-controller/realtek,rtl-intc.yaml
@@ -6,6 +6,10 @@ $schema: http://devicetree.org/meta-schemas/core.yaml#
 
 title: Realtek RTL SoC interrupt controller devicetree bindings
 
+description:
+  Interrupt router for Realtek MIPS SoCs, allowing up to 32 SoC interrupts to
+  be routed to one of up to 15 parent interrupts, or left disconnected.
+
 maintainers:
   - Birger Koblitz <mail@birger-koblitz.de>
   - Bert Vermeulen <bert@biot.com>
@@ -22,7 +26,11 @@ properties:
     maxItems: 1
 
   interrupts:
-    maxItems: 1
+    minItems: 1
+    maxItems: 15
+    description:
+      List of parent interrupts, in the order that they are connected to this
+      interrupt router's outputs.
 
   interrupt-controller: true
 
@@ -30,7 +38,21 @@ properties:
     const: 0
 
   interrupt-map:
-    description: Describes mapping from SoC interrupts to CPU interrupts
+    description:
+      List of <soc_int parent_phandle parent_args ...> tuples, where "soc_int"
+      is the interrupt input line number as provided by this controller.
+      "parent_phandle" and "parent_args" specify which parent interrupt this
+      line should be routed to. Note that interrupt specifiers should be
+      identical to the parents specified in the "interrupts" property.
+
+  realtek,output-valid-mask:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      Optional bit mask indicating which outputs are connected to the parent
+      interrupts. The lowest set bit indicates which output line the first
+      interrupt from "interrupts" is connected to, the second lowest set bit
+      for the second interrupt, etc. If not provided, parent interrupts will be
+      assigned sequentially to the outputs.
 
 required:
   - compatible
@@ -39,6 +61,7 @@ required:
   - interrupt-controller
   - "#address-cells"
   - interrupt-map
+  - interrupts
 
 additionalProperties: false
 
@@ -49,9 +72,14 @@ examples:
       #interrupt-cells = <1>;
       interrupt-controller;
       reg = <0x3000 0x20>;
+
+      interrupt-parent = <&cpuintc>;
+      interrupts = <1>, <2>, <5>;
+      realtek,output-valid-mask = <0x13>;
+
       #address-cells = <0>;
       interrupt-map =
-              <31 &cpuintc 2>,
-              <30 &cpuintc 1>,
-              <29 &cpuintc 5>;
+              <31 &cpuintc 2>, /* connect to cpuintc 2 via output 1 */
+              <30 &cpuintc 1>, /* connect to cpuintc 1 via output 0 */
+              <29 &cpuintc 5>; /* connect to cpuintc 5 via output 4 */
     };
-- 
2.33.1