From 7b1c4e22532ded6b20ee41936fa38b5ca1e61ff9 Mon Sep 17 00:00:00 2001
From: Luo Jie <quic_luoj@quicinc.com>
Date: Mon, 29 Jan 2024 17:57:20 +0800
Subject: [PATCH] dt-bindings: net: Document Qualcomm QCA8084 PHY package

QCA8084 is quad PHY chip, which integrates 4 PHYs, 2 PCS
interfaces (PCS0 and PCS1) and clock controller, which can
also be integrated to the switch chip named as QCA8386.

1. MDIO address of 4 PHYs, 2 PCS and 1 XPCS (PCS1 includes
   PCS and XPCS, PCS0 includes PCS) can be configured.
2. The package mode of PHY is optionally configured for the
   interface mode of two PCSes working correctly.
3. The package level clock and reset need to be initialized.
4. The clock and reset per PHY device need to be initialized
   so that the PHY register can be accessed.

Change-Id: Idb2338d2673152cbd3c57e95968faa59e9d4a80f
Signed-off-by: Luo Jie <quic_luoj@quicinc.com>
Alex G: Update to match the patches that will be upstream.
Signed-off-by: Alexandru Gagniuc <mr.nuke.me@gmail.com>
---
 .../devicetree/bindings/net/qcom,qca8084.yaml | 488 ++++++++++++++++++
 include/dt-bindings/net/qcom,qca808x.h        |  14 +
 2 files changed, 502 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/qcom,qca8084.yaml
 create mode 100644 include/dt-bindings/net/qcom,qca808x.h

--- /dev/null
+++ b/Documentation/devicetree/bindings/net/qcom,qca8084.yaml
@@ -0,0 +1,488 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/qcom,qca8084.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm QCA8084 Ethernet Quad PHY
+
+maintainers:
+  - Luo Jie <quic_luoj@quicinc.com>
+
+description:
+  Qualcomm QCA8084 is PHY package of four-port Ethernet transceiver,
+  the Ethernet port supports link speed 10/100/1000/2500 Mbps.
+  There are two PCSes (PCS0 and PCS1) integrated in the PHY
+  package, PCS1 includes XPCS and PCS to support the interface
+  mode 10G-QXGMII and SGMII, PCS0 includes a PCS to support the
+  interface mode SGMII only. There is also a clock controller
+  integrated in the PHY package. This four-port Ethernet
+  transceiver can also be integrated to the switch chip named
+  as QCA8386. The PHY package mode needs to be configured as the
+  correct value to apply the interface mode of two PCSes as
+  mentioned below.
+
+  QCA8084 expects an input reference clock 50 MHZ as the clock
+  source of the integrated clock controller, the integrated
+  clock controller supplies the clocks and resets to the
+  integrated PHY, PCS and PHY package.
+
+  - |
+                 +--| |--+-------------------+--| |--+
+                 | PCS1  |<------------+---->| PCS0  |
+                 +-------+             |     +-------+
+                 |                     |             |
+    Ref 50M clk  +--------+            |             |
+    ------------>|        | clk & rst  |             |
+    GPIO Reset   |QCA8K-CC+------------+             |
+    ------------>|        |            |             |
+                 +--------+            |             |
+                 |                     V             |
+                 +--------+--------+--------+--------+
+                 |  PHY0  |  PHY1  |  PHY2  |  PHY3  |
+                 +--------+--------+--------+--------+
+
+properties:
+  compatible:
+    const: qcom,qca8084-package
+
+  clocks:
+    description:
+      PHY package level initial common clocks, which are needed to
+      be enabled after GPIO reset on the PHY package, these clocks
+      are supplied from the PHY integrated clock controller (QCA8K-CC).
+    items:
+      - description: APB bridge clock
+      - description: AHB clock
+      - description: Security control clock
+      - description: TLMM clock
+      - description: TLMM AHB clock
+      - description: CNOC AHB clock
+      - description: MDIO AHB clock
+
+  clock-names:
+    items:
+      - const: apb_bridge
+      - const: ahb
+      - const: sec_ctrl_ahb
+      - const: tlmm
+      - const: tlmm_ahb
+      - const: cnoc_ahb
+      - const: mdio_ahb
+
+  resets:
+    description:
+      PHY package level initial common reset, which are needed to
+      be deasserted after GPIO reset on the PHY package, this reset
+      is provided by the PHY integrated clock controller to do PHY
+      DSP reset.
+    maxItems: 1
+
+  qcom,package-mode:
+    description: |
+      The package mode of PHY supports to be configured as 3 modes
+      to apply the combinations of interface mode of two PCSes
+      correctly. This value should use one of the values defined in
+      dt-bindings/net/qcom,qca808x.h. The package mode 10G-QXGMII of
+      Quad PHY is used by default.
+
+      package mode             PCS1             PCS0
+      phy mode (0)             10G-QXGMII for   not used
+                               PHY0-PHY3
+
+      switch mode (1)          SGMII for        SGMII for
+                               switch MAC0      switch MAC5 (optional)
+
+      switch bypass MAC5 (2)   SGMII for        SGMII for
+                               switch MAC0      PHY3
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0, 1, 2]
+    default: 0
+
+  qcom,phy-addr-fixup:
+    description:
+      MDIO address for PHY0-PHY3, PCS0 and PCS1 including PCS and XPCS,
+      which can be optionally customized by programming the security
+      control register of PHY package. The hardware default MDIO address
+      of PHY0-PHY3, PCS0 and PCS1 including PCS and XPCS is 0-6.
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 7
+    maxItems: 7
+
+patternProperties:
+  ^ethernet-phy@[a-f0-9]+$:
+    unevaluatedProperties: false
+    $ref: ethernet-phy.yaml#
+
+    properties:
+      compatible:
+        const: ethernet-phy-id004d.d180
+
+      qcom,xpcs-channel:
+        description:
+          When PCS1 works on the interface mode 10G-QXGMII, the integrated
+          XPCS including 4 channels is used to connected with the Quad PHYs,
+          each PHY needs to be specified the XPCS channel ID to deliver the
+          PHY link status to the XPCS.
+        $ref: /schemas/types.yaml#/definitions/uint32
+        enum: [0, 1, 2, 3]
+
+    required:
+      - compatible
+      - reg
+      - clocks
+      - resets
+
+  ^pcs-phy@[a-f0-9]+$:
+    type: object
+    additionalProperties: false
+    description:
+      PCS device has the independent MDIO address, which controls
+      the interface mode used and provides the clocks such as
+      312.5 MHZ as RX and TX root clocks to the integrated clock
+      controller.
+    properties:
+      compatible:
+        const: qcom,qca8k-pcs-phy
+
+      reg:
+        items:
+          - description: PCS MDIO address.
+
+      clocks:
+        items:
+          - description: PCS clock.
+          - description: PCS RX root clock.
+          - description: PCS TX root clock.
+
+      clock-names:
+        items:
+          - const: pcs
+          - const: pcs_rx_root
+          - const: pcs_tx_root
+
+      resets:
+        items:
+          - description: PCS reset.
+
+    required:
+      - compatible
+      - reg
+      - clocks
+      - resets
+
+  ^xpcs-phy@[a-f0-9]+$:
+    type: object
+    additionalProperties: false
+    description:
+      XPCS device has the independent MDIO address, which includes 4
+      channels to connect with Quad PHYs.
+    properties:
+      compatible:
+        const: qcom,qca8k-xpcs-phy
+
+      reg:
+        items:
+          - description: XPCS MDIO address.
+
+      resets:
+        items:
+          - description: XPCS reset.
+
+      '#address-cells':
+        const: 1
+
+      '#size-cells':
+        const: 0
+
+    required:
+      - compatible
+      - reg
+      - resets
+      - '#address-cells'
+      - '#size-cells'
+
+    patternProperties:
+      "^channel@[0-3]+$":
+        type: object
+        additionalProperties: false
+        description:
+          XPCS is used to support 10G-QXGMII mode, which inlcudes 4 channels
+          to be connected with Quad PHYs, each channels has the dedicated
+          clocks and resets from the integrated clock controller of QCA8084.
+
+        properties:
+          reg:
+            items:
+              - description: XPCS channel ID
+
+          clocks:
+            items:
+              - description: XPCS XGMII RX clock
+              - description: XPCS XGMII TX clock
+              - description: XPCS RX clock
+              - description: XPCS TX clock
+              - description: Port RX clock
+              - description: Port TX clock
+              - description: RX source clock
+              - description: TX source clock
+
+          clock-names:
+            items:
+              - const: xgmii_rx
+              - const: xgmii_tx
+              - const: xpcs_rx
+              - const: xpcs_tx
+              - const: port_rx
+              - const: port_tx
+              - const: rx_src
+              - const: tx_src
+
+          resets:
+            items:
+              - description: XPCS XGMII RX reset
+              - description: XPCS XGMII TX reset
+              - description: XPCS RX reset
+              - description: XPCS TX reset
+              - description: Port RX reset
+              - description: Port TX reset
+
+          reset-names:
+            items:
+              - const: xgmii_rx
+              - const: xgmii_tx
+              - const: xpcs_rx
+              - const: xpcs_tx
+              - const: port_rx
+              - const: port_tx
+
+        required:
+          - reg
+          - clocks
+          - clock-names
+          - resets
+          - reset-names
+
+required:
+  - compatible
+  - clocks
+  - clock-names
+  - resets
+
+allOf:
+  - $ref: ethernet-phy-package.yaml#
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/qcom,qca8k-nsscc.h>
+    #include <dt-bindings/net/qcom,qca808x.h>
+    #include <dt-bindings/reset/qcom,qca8k-nsscc.h>
+
+    mdio {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ethernet-phy-package@1 {
+            #address-cells = <1>;
+            #size-cells = <0>;
+            compatible = "qcom,qca8084-package";
+            reg = <1>;
+            clocks = <&qca8k_nsscc NSS_CC_APB_BRIDGE_CLK>,
+                     <&qca8k_nsscc NSS_CC_AHB_CLK>,
+                     <&qca8k_nsscc NSS_CC_SEC_CTRL_AHB_CLK>,
+                     <&qca8k_nsscc NSS_CC_TLMM_CLK>,
+                     <&qca8k_nsscc NSS_CC_TLMM_AHB_CLK>,
+                     <&qca8k_nsscc NSS_CC_CNOC_AHB_CLK>,
+                     <&qca8k_nsscc NSS_CC_MDIO_AHB_CLK>;
+            clock-names = "apb_bridge",
+                          "ahb",
+                          "sec_ctrl_ahb",
+                          "tlmm",
+                          "tlmm_ahb",
+                          "cnoc_ahb",
+                          "mdio_ahb";
+            resets = <&qca8k_nsscc NSS_CC_GEPHY_FULL_ARES>;
+            qcom,package-mode = <QCA808X_PCS1_10G_QXGMII_PCS0_UNUNSED>;
+            qcom,phy-addr-fixup = <1 2 3 4 5 6 7>;
+
+            ethernet-phy@1 {
+                compatible = "ethernet-phy-id004d.d180";
+                reg = <1>;
+                clocks = <&qca8k_nsscc NSS_CC_GEPHY0_SYS_CLK>;
+                resets = <&qca8k_nsscc NSS_CC_GEPHY0_SYS_ARES>;
+                qcom,xpcs-channel = <0>;
+            };
+
+            ethernet-phy@2 {
+                compatible = "ethernet-phy-id004d.d180";
+                reg = <2>;
+                clocks = <&qca8k_nsscc NSS_CC_GEPHY1_SYS_CLK>;
+                resets = <&qca8k_nsscc NSS_CC_GEPHY1_SYS_ARES>;
+                qcom,xpcs-channel = <1>;
+            };
+
+            ethernet-phy@3 {
+                compatible = "ethernet-phy-id004d.d180";
+                reg = <3>;
+                clocks = <&qca8k_nsscc NSS_CC_GEPHY2_SYS_CLK>;
+                resets = <&qca8k_nsscc NSS_CC_GEPHY2_SYS_ARES>;
+                qcom,xpcs-channel = <2>;
+            };
+
+            ethernet-phy@4 {
+                compatible = "ethernet-phy-id004d.d180";
+                reg = <4>;
+                clocks = <&qca8k_nsscc NSS_CC_GEPHY3_SYS_CLK>;
+                resets = <&qca8k_nsscc NSS_CC_GEPHY3_SYS_ARES>;
+                qcom,xpcs-channel = <3>;
+            };
+
+            pcs-phy@6 {
+                compatible = "qcom,qca8k-pcs-phy";
+                reg = <6>;
+                clocks = <&qca8k_nsscc NSS_CC_SRDS1_SYS_CLK>,
+                         <&qca8k_uniphy1_tx312p5m>,
+                         <&qca8k_uniphy1_rx312p5m>;
+                clock-names = "pcs", "pcs_rx_root", "pcs_tx_root";
+                resets = <&qca8k_nsscc NSS_CC_SRDS1_SYS_ARES>;
+            };
+
+            xpcs-phy@7 {
+                compatible = "qcom,qca8k-xpcs-phy";
+                reg = <7>;
+                #address-cells = <1>;
+                #size-cells = <0>;
+                resets = <&qca8k_nsscc NSS_CC_XPCS_ARES>;
+
+                channel@0 {
+                    reg = <0>;
+                    clocks = <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_XGMII_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_XGMII_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC1_GEPHY0_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC1_GEPHY0_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC1_RX_CLK_SRC>,
+                             <&qca8k_nsscc NSS_CC_MAC1_TX_CLK_SRC>;
+                    clock-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx",
+                                  "rx_src",
+                                  "tx_src";
+                    resets = <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_XGMII_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_XGMII_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC1_SRDS1_CH0_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC1_GEPHY0_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC1_GEPHY0_TX_ARES>;
+                    reset-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx";
+                };
+
+                channel@1 {
+                    reg = <1>;
+                    clocks = <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_XGMII_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_XGMII_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC2_GEPHY1_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC2_GEPHY1_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC2_RX_CLK_SRC>,
+                             <&qca8k_nsscc NSS_CC_MAC2_TX_CLK_SRC>;
+                    clock-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx",
+                                  "rx_src",
+                                  "tx_src";
+                    resets = <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_XGMII_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_XGMII_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC2_SRDS1_CH1_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC2_GEPHY1_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC2_GEPHY1_TX_ARES>;
+                    reset-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx";
+                };
+
+                channel@2 {
+                    reg = <2>;
+                    clocks = <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_XGMII_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_XGMII_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC3_GEPHY2_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC3_GEPHY2_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC3_RX_CLK_SRC>,
+                             <&qca8k_nsscc NSS_CC_MAC3_TX_CLK_SRC>;
+                    clock-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx",
+                                  "rx_src",
+                                  "tx_src";
+                    resets = <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_XGMII_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_XGMII_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC3_SRDS1_CH2_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC3_GEPHY2_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC3_GEPHY2_TX_ARES>;
+                    reset-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx";
+                };
+
+                channel@3 {
+                    reg = <3>;
+                    clocks = <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_XGMII_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_XGMII_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC4_GEPHY3_RX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC4_GEPHY3_TX_CLK>,
+                             <&qca8k_nsscc NSS_CC_MAC4_RX_CLK_SRC>,
+                             <&qca8k_nsscc NSS_CC_MAC4_TX_CLK_SRC>;
+                    clock-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx",
+                                  "rx_src",
+                                  "tx_src";
+                    resets = <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_XGMII_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_XGMII_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_TX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC4_SRDS1_CH3_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC4_GEPHY3_RX_ARES>,
+                             <&qca8k_nsscc NSS_CC_MAC4_GEPHY3_TX_ARES>;
+                    reset-names = "xgmii_rx",
+                                  "xgmii_tx",
+                                  "xpcs_rx",
+                                  "xpcs_tx",
+                                  "port_rx",
+                                  "port_tx";
+                };
+            };
+        };
+    };
--- /dev/null
+++ b/include/dt-bindings/net/qcom,qca808x.h
@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */
+/*
+ * Device Tree constants for the Qualcomm QCA808X PHYs
+ */
+
+#ifndef _DT_BINDINGS_QCOM_QCA808X_H
+#define _DT_BINDINGS_QCOM_QCA808X_H
+
+/* PHY package modes of QCA8084 to apply the interface modes of two PCSes. */
+#define QCA808X_PCS1_10G_QXGMII_PCS0_UNUNSED		0
+#define QCA808X_PCS1_SGMII_MAC_PCS0_SGMII_MAC		1
+#define QCA808X_PCS1_SGMII_MAC_PCS0_SGMII_PHY		2
+
+#endif
