diff mbox series

[v3,1/2] dt-bindings: usb: dwc3: Clean up hs_phy_irq in bindings

Message ID 20231211121124.4194-2-quic_kriskura@quicinc.com
State Superseded
Headers show
Series [v3,1/2] dt-bindings: usb: dwc3: Clean up hs_phy_irq in bindings | expand

Commit Message

Krishna Kurapati Dec. 11, 2023, 12:11 p.m. UTC
The high speed related interrupts present on QC targets are as follows:

dp/dm irq's
These IRQ's directly reflect changes on the DP/DM pads of the SoC. These
are used as wakeup interrupts only on SoCs with non-QUSB2 targets with
exception of SDM670/SDM845/SM6350.

qusb2_phy irq
SoCs with QUSB2 PHY do not have separate DP/DM IRQs and expose only a
single IRQ whose behavior can be modified by the QUSB2PHY_INTR_CTRL
register. The required DPSE/DMSE configuration is done in
QUSB2PHY_INTR_CTRL register of phy address space.

hs_phy_irq
This is completely different from the above two and is present on all
targets with exception of a few IPQ ones. The interrupt is not enabled by
default and its functionality is mutually exclusive of qusb2_phy on QUSB
targets and DP/DM on femto phy targets.

The DTs of several QUSB2 PHY based SoCs incorrectly define "hs_phy_irq"
when they should have been "qusb2_phy_irq". On Femto phy targets, the
"hs_phy_irq" mentioned is either the actual "hs_phy_irq" or "pwr_event",
neither of which would never be triggered directly are non-functional
currently. The implementation tries to clean up this issue by addressing
the discrepencies involved and fixing the hs_phy_irq's in respective DT's.

Classiffy SoC's into four groups based on whether qusb2_phy interrupt
or {dp/dm}_hs_phy_irq is used for wakeup in high speed and whether the
SoCs have hs_phy_irq present in them or not.

The ss_phy_irq is optional interrupt because there are mutliple SoC's
which either support only High Speed or there are multiple controllers
within same Soc and the secondary controller is High Speed only capable.

This breaks ABI on targets running older kernels, but since the interrupt
definitions are given wrong on many targets and to establish proper rules
for usage of DWC3 interrupts on Qualcomm platforms, DT binding update is
necessary.

Signed-off-by: Krishna Kurapati <quic_kriskura@quicinc.com>
---
 .../devicetree/bindings/usb/qcom,dwc3.yaml    | 138 ++++++++----------
 1 file changed, 59 insertions(+), 79 deletions(-)

Comments

Krzysztof Kozlowski Dec. 13, 2023, 7:15 a.m. UTC | #1
On 11/12/2023 13:11, Krishna Kurapati wrote:
> The high speed related interrupts present on QC targets are as follows:
> 
> dp/dm irq's
> These IRQ's directly reflect changes on the DP/DM pads of the SoC. These
> are used as wakeup interrupts only on SoCs with non-QUSB2 targets with
> exception of SDM670/SDM845/SM6350.
> 
> qusb2_phy irq
> SoCs with QUSB2 PHY do not have separate DP/DM IRQs and expose only a
> single IRQ whose behavior can be modified by the QUSB2PHY_INTR_CTRL
> register. The required DPSE/DMSE configuration is done in
> QUSB2PHY_INTR_CTRL register of phy address space.
> 
> hs_phy_irq
> This is completely different from the above two and is present on all
> targets with exception of a few IPQ ones. The interrupt is not enabled by
> default and its functionality is mutually exclusive of qusb2_phy on QUSB
> targets and DP/DM on femto phy targets.
> 
> The DTs of several QUSB2 PHY based SoCs incorrectly define "hs_phy_irq"
> when they should have been "qusb2_phy_irq". On Femto phy targets, the
> "hs_phy_irq" mentioned is either the actual "hs_phy_irq" or "pwr_event",
> neither of which would never be triggered directly are non-functional
> currently. The implementation tries to clean up this issue by addressing
> the discrepencies involved and fixing the hs_phy_irq's in respective DT's.
> 
> Classiffy SoC's into four groups based on whether qusb2_phy interrupt
> or {dp/dm}_hs_phy_irq is used for wakeup in high speed and whether the
> SoCs have hs_phy_irq present in them or not.
> 
> The ss_phy_irq is optional interrupt because there are mutliple SoC's
> which either support only High Speed or there are multiple controllers
> within same Soc and the secondary controller is High Speed only capable.
> 
> This breaks ABI on targets running older kernels, but since the interrupt
> definitions are given wrong on many targets and to establish proper rules
> for usage of DWC3 interrupts on Qualcomm platforms, DT binding update is
> necessary.

This still does not explain why missing property has to be added as
first one, causing huge reordering of everything here and in DTS.

If pwr_event is required and we already break the ABI, reduce the impact
of the change by putting it after all required interrupts. Otherwise
please explain here and in commit msg why different approach is taken.

Best regards,
Krzysztof
Krishna Kurapati Dec. 13, 2023, 4:18 p.m. UTC | #2
On 12/13/2023 12:45 PM, Krzysztof Kozlowski wrote:
> On 11/12/2023 13:11, Krishna Kurapati wrote:
>> The high speed related interrupts present on QC targets are as follows:
>>
>> dp/dm irq's
>> These IRQ's directly reflect changes on the DP/DM pads of the SoC. These
>> are used as wakeup interrupts only on SoCs with non-QUSB2 targets with
>> exception of SDM670/SDM845/SM6350.
>>
>> qusb2_phy irq
>> SoCs with QUSB2 PHY do not have separate DP/DM IRQs and expose only a
>> single IRQ whose behavior can be modified by the QUSB2PHY_INTR_CTRL
>> register. The required DPSE/DMSE configuration is done in
>> QUSB2PHY_INTR_CTRL register of phy address space.
>>
>> hs_phy_irq
>> This is completely different from the above two and is present on all
>> targets with exception of a few IPQ ones. The interrupt is not enabled by
>> default and its functionality is mutually exclusive of qusb2_phy on QUSB
>> targets and DP/DM on femto phy targets.
>>
>> The DTs of several QUSB2 PHY based SoCs incorrectly define "hs_phy_irq"
>> when they should have been "qusb2_phy_irq". On Femto phy targets, the
>> "hs_phy_irq" mentioned is either the actual "hs_phy_irq" or "pwr_event",
>> neither of which would never be triggered directly are non-functional
>> currently. The implementation tries to clean up this issue by addressing
>> the discrepencies involved and fixing the hs_phy_irq's in respective DT's.
>>
>> Classiffy SoC's into four groups based on whether qusb2_phy interrupt
>> or {dp/dm}_hs_phy_irq is used for wakeup in high speed and whether the
>> SoCs have hs_phy_irq present in them or not.
>>
>> The ss_phy_irq is optional interrupt because there are mutliple SoC's
>> which either support only High Speed or there are multiple controllers
>> within same Soc and the secondary controller is High Speed only capable.
>>
>> This breaks ABI on targets running older kernels, but since the interrupt
>> definitions are given wrong on many targets and to establish proper rules
>> for usage of DWC3 interrupts on Qualcomm platforms, DT binding update is
>> necessary.
> 
> This still does not explain why missing property has to be added as
> first one, causing huge reordering of everything here and in DTS.
> 
> If pwr_event is required and we already break the ABI, reduce the impact
> of the change by putting it after all required interrupts. Otherwise
> please explain here and in commit msg why different approach is taken.
> 

Hi Krzysztof. I don't know much about the effect of the ordering on ABI. 
I will try to learn up on it. Would the series be good if we just move 
the pwr_event to the end and keep everything in v3 as it is, and push v4 
for now ?

Regards,
Krishna,
Johan Hovold Dec. 14, 2023, 9:56 a.m. UTC | #3
On Wed, Dec 13, 2023 at 09:48:57PM +0530, Krishna Kurapati PSSNV wrote:
> On 12/13/2023 12:45 PM, Krzysztof Kozlowski wrote:
> > On 11/12/2023 13:11, Krishna Kurapati wrote:
> >> The high speed related interrupts present on QC targets are as follows:

> >> Classiffy SoC's into four groups based on whether qusb2_phy interrupt

typo: Classify

> >> or {dp/dm}_hs_phy_irq is used for wakeup in high speed and whether the
> >> SoCs have hs_phy_irq present in them or not.
> >>
> >> The ss_phy_irq is optional interrupt because there are mutliple SoC's
> >> which either support only High Speed or there are multiple controllers
> >> within same Soc and the secondary controller is High Speed only capable.
> >>
> >> This breaks ABI on targets running older kernels, but since the interrupt
> >> definitions are given wrong on many targets and to establish proper rules
> >> for usage of DWC3 interrupts on Qualcomm platforms, DT binding update is
> >> necessary.
> > 
> > This still does not explain why missing property has to be added as
> > first one, causing huge reordering of everything here and in DTS.
> > 
> > If pwr_event is required and we already break the ABI, reduce the impact
> > of the change by putting it after all required interrupts. Otherwise
> > please explain here and in commit msg why different approach is taken.
> > 
> 
> Hi Krzysztof. I don't know much about the effect of the ordering on ABI. 
> I will try to learn up on it. Would the series be good if we just move 
> the pwr_event to the end and keep everything in v3 as it is, and push v4 
> for now ?

Since all SoCs have the pwr_event (HS) interrupt, but not all
controllers have the SS PHY interrupt, this would prevent expressing
that the SS PHY is optional by keeping it last in the binding schema and
making sure that minItem = maxItems - 1.

And as we discussed, the aim here is to group the three classes of SoCs
(qusb2, qusb2+, femto) and fix the order of these interrupts once and
for all so that random reorderings, renames and omissions do not make it
into the bindings next time someone grabs a downstream DT and sends it
upstream.

Johan
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml
index 3ec62027f663..602949d64586 100644
--- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml
+++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml
@@ -98,12 +98,29 @@  properties:
       - const: apps-usb
 
   interrupts:
-    minItems: 1
-    maxItems: 4
+    description: |
+      Different types of interrupts are used based on HS PHY used on target:
+        - pwr_event: Used for wakeup based on other power events.
+        - hs_phY_irq: Apart from DP/DM/QUSB2 PHY interrupts, there is
+                       hs_phy_irq which is not triggered by default and its
+                       functionality is mutually exclusive to that of
+                       {dp/dm}_hs_phy_irq and qusb2_phy_irq.
+        - qusb2_phy: SoCs with QUSB2 PHY do not have separate DP/DM IRQs and
+                      expose only a single IRQ whose behavior can be modified
+                      by the QUSB2PHY_INTR_CTRL register. The required DPSE/
+                      DMSE configuration is done in QUSB2PHY_INTR_CTRL register
+                      of PHY address space.
+        - {dp/dm}_hs_phy_irq: These IRQ's directly reflect changes on the DP/
+                               DM pads of the SoC. These are used for wakeup
+                               only on SoCs with non-QUSB2 targets with
+                               exception of SDM670/SDM845/SM6350.
+        - ss_phy_irq: Used for remote wakeup in Super Speed mode of operation.
+    minItems: 2
+    maxItems: 5
 
   interrupt-names:
-    minItems: 1
-    maxItems: 4
+    minItems: 2
+    maxItems: 5
 
   qcom,select-utmi-as-pipe-clk:
     description:
@@ -359,60 +376,21 @@  allOf:
         compatible:
           contains:
             enum:
-              - qcom,ipq4019-dwc3
+              - qcom,ipq5018-dwc3
               - qcom,ipq6018-dwc3
-              - qcom,ipq8064-dwc3
               - qcom,ipq8074-dwc3
-              - qcom,msm8994-dwc3
-              - qcom,qcs404-dwc3
-              - qcom,sc7180-dwc3
-              - qcom,sdm670-dwc3
-              - qcom,sdm845-dwc3
-              - qcom,sdx55-dwc3
-              - qcom,sdx65-dwc3
-              - qcom,sdx75-dwc3
-              - qcom,sm4250-dwc3
-              - qcom,sm6350-dwc3
-              - qcom,sm8150-dwc3
-              - qcom,sm8250-dwc3
-              - qcom,sm8350-dwc3
-              - qcom,sm8450-dwc3
-              - qcom,sm8550-dwc3
-              - qcom,sm8650-dwc3
-    then:
-      properties:
-        interrupts:
-          items:
-            - description: The interrupt that is asserted
-                when a wakeup event is received on USB2 bus.
-            - description: The interrupt that is asserted
-                when a wakeup event is received on USB3 bus.
-            - description: Wakeup event on DM line.
-            - description: Wakeup event on DP line.
-        interrupt-names:
-          items:
-            - const: hs_phy_irq
-            - const: ss_phy_irq
-            - const: dm_hs_phy_irq
-            - const: dp_hs_phy_irq
-
-  - if:
-      properties:
-        compatible:
-          contains:
-            enum:
               - qcom,msm8953-dwc3
-              - qcom,msm8996-dwc3
               - qcom,msm8998-dwc3
-              - qcom,sm6115-dwc3
-              - qcom,sm6125-dwc3
+              - qcom,qcm2290-dwc3
     then:
       properties:
         interrupts:
-          maxItems: 2
+          minItems: 2
+          maxItems: 3
         interrupt-names:
           items:
-            - const: hs_phy_irq
+            - const: pwr_event
+            - const: qusb2_phy
             - const: ss_phy_irq
 
   - if:
@@ -420,37 +398,21 @@  allOf:
         compatible:
           contains:
             enum:
-              - qcom,ipq5018-dwc3
-              - qcom,ipq5332-dwc3
+              - qcom,msm8996-dwc3
+              - qcom,qcs404-dwc3
               - qcom,sdm660-dwc3
-    then:
-      properties:
-        interrupts:
-          minItems: 1
-          maxItems: 2
-        interrupt-names:
-          minItems: 1
-          items:
-            - const: hs_phy_irq
-            - const: ss_phy_irq
-
-  - if:
-      properties:
-        compatible:
-          contains:
-            enum:
-              - qcom,sc7280-dwc3
+              - qcom,sm6115-dwc3
+              - qcom,sm6125-dwc3
     then:
       properties:
         interrupts:
           minItems: 3
           maxItems: 4
         interrupt-names:
-          minItems: 3
           items:
+            - const: pwr_event
             - const: hs_phy_irq
-            - const: dp_hs_phy_irq
-            - const: dm_hs_phy_irq
+            - const: qusb2_phy
             - const: ss_phy_irq
 
   - if:
@@ -458,10 +420,12 @@  allOf:
         compatible:
           contains:
             enum:
+              - qcom,ipq5332-dwc3
               - qcom,sc8280xp-dwc3
     then:
       properties:
         interrupts:
+          minItems: 3
           maxItems: 4
         interrupt-names:
           items:
@@ -476,15 +440,30 @@  allOf:
           contains:
             enum:
               - qcom,sa8775p-dwc3
+              - qcom,sc7180-dwc3
+              - qcom,sc7280-dwc3
+              - qcom,sdm670-dwc3
+              - qcom,sdm845-dwc3
+              - qcom,sdx55-dwc3
+              - qcom,sdx65-dwc3
+              - qcom,sdx75-dwc3
+              - qcom,sm6350-dwc3
+              - qcom,sm6375-dwc3
+              - qcom,sm8150-dwc3
+              - qcom,sm8250-dwc3
+              - qcom,sm8350-dwc3
+              - qcom,sm8450-dwc3
+              - qcom,sm8550-dwc3
+              - qcom,sm8650-dwc3
     then:
       properties:
         interrupts:
-          minItems: 3
-          maxItems: 4
+          minItems: 4
+          maxItems: 5
         interrupt-names:
-          minItems: 3
           items:
             - const: pwr_event
+            - const: hs_phy_irq
             - const: dp_hs_phy_irq
             - const: dm_hs_phy_irq
             - const: ss_phy_irq
@@ -522,12 +501,13 @@  examples:
                           <&gcc GCC_USB30_PRIM_MASTER_CLK>;
             assigned-clock-rates = <19200000>, <150000000>;
 
-            interrupts = <GIC_SPI 131 IRQ_TYPE_LEVEL_HIGH>,
-                         <GIC_SPI 486 IRQ_TYPE_LEVEL_HIGH>,
+            interrupts = <GIC_SPI 130 IRQ_TYPE_LEVEL_HIGH>,
+                         <GIC_SPI 131 IRQ_TYPE_LEVEL_HIGH>,
+                         <GIC_SPI 489 IRQ_TYPE_EDGE_BOTH>,
                          <GIC_SPI 488 IRQ_TYPE_EDGE_BOTH>,
-                         <GIC_SPI 489 IRQ_TYPE_EDGE_BOTH>;
-            interrupt-names = "hs_phy_irq", "ss_phy_irq",
-                          "dm_hs_phy_irq", "dp_hs_phy_irq";
+                         <GIC_SPI 486 IRQ_TYPE_LEVEL_HIGH>;
+            interrupt-names = "pwr_event", "hs_phy_irq",
+                          "dp_hs_phy_irq", "dm_hs_phy_irq", "ss_phy_irq";
 
             power-domains = <&gcc USB30_PRIM_GDSC>;